---
title: "Claude Code 入门"
wiki: cli
category: "终端 Agent 工具"
slug: claude-code-overview
url: https://learnagent.wiki/cli/cards/claude-code-overview
tags: ["Claude Code", "Anthropic", "终端 Agent", "CLI", "入门"]
last_updated: 2026-04-22
reading_time: 17
---

> **Claude Code 是 Anthropic 官方出品的 agentic 编码工具，常驻在你的终端里，直接读你的代码、改你的文件、跑你的命令、和你的开发工具链协同**。它不是一个聊天机器人，也不是一个传统的命令行工具，而是一个会自己「拿主意」的 Agent——你给它一个目标，它会自己决定要看哪些文件、跑哪些命令、改哪些代码，遇到错误自己调整方向，直到任务做完。

# Claude Code 入门

## 基础概念

**Claude Code 是 Anthropic 官方出品的 agentic 编码工具，常驻在你的终端里，直接读你的代码、改你的文件、跑你的命令、和你的开发工具链协同**。它不是一个聊天机器人，也不是一个传统的命令行工具，而是一个会自己「拿主意」的 Agent——你给它一个目标，它会自己决定要看哪些文件、跑哪些命令、改哪些代码，遇到错误自己调整方向，直到任务做完。

要理解 Claude Code 跟 Claude Desktop、Claude API 的差别，先看清楚它的定位：

- **Claude Desktop / claude.ai**：是「聊天界面」，给 Claude 一个友好的窗口让你和它对话。它看不到你电脑上的文件，也不能直接帮你改代码。
- **Claude API / Anthropic SDK**：是「模型接口」，给开发者写代码用，原生只暴露大模型的 chat completion 能力，工具调用、上下文管理、安全控制都得你自己写。
- **Claude Code**：是 **agentic harness（Agent 外壳）**，把 Claude 模型 + 一整套工具 + 上下文管理 + 权限沙箱 + 会话持久化打包成「可以在你电脑上自主工作的 Agent」。它是一个完整的可执行程序（`claude` 命令），开箱即用。

官方对自己的描述是「**an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools**」。它的核心循环非常清楚：拿到任务 → 收集上下文 → 执行动作 → 验证结果 → 不行就再循环，直到任务完成。

> 命名澄清：本卡涉及的官方名称统一是 **Claude Code**（不是 "Claude CLI"、"claude-code-cli"、"Anthropic CLI"，这些都是社区里的口语叫法）。它的可执行命令是 `claude`，配置目录是 `~/.claude/`。

### 核心能力一览

| 能力 | 说明 |
|------|------|
| **Agentic 循环** | 自主在「收集上下文 → 行动 → 验证」三阶段间循环，每一步根据上一步结果自己决定下一步 |
| **内置工具** | 文件读写、代码搜索、Bash 执行、Web 抓取、子任务派发等，覆盖日常开发 90% 场景 |
| **MCP 接入** | 原生支持 [Model Context Protocol](/mcp/cards/what-is-mcp)，可以挂任意 MCP server 扩展能力 |
| **Skills** | 可复用的工作流脚本（如 `/review-pr`、`/deploy-staging`），按需加载、不占用基础上下文 |
| **Hooks** | 在 Agent 生命周期事件上挂 shell 命令（PreToolUse、PostToolUse、Stop、PreCompact 等） |
| **会话持久化** | 每次会话本地存为 JSONL，可 `--resume` 续接、`--fork-session` 分叉、`Esc` 双击回滚 |
| **权限沙箱** | 工具白/黑名单、文件读写边界、网络域名限制，支持 `Plan` / `Auto-accept` / `Auto` 多种模式 |

### Agentic 循环示意

下面这张图说明了 Claude Code 拿到一个任务之后内部到底在做什么——**循环不是一根直线，而是反复调工具、反复验证的闭环**：

```mermaid
sequenceDiagram
    participant U as 你（用户）
    participant CC as Claude Code 进程
    participant M as Claude 模型
    participant T as 内置工具
    U->>CC: 输入任务（"修一下登录 bug"）
    CC->>M: 把任务 + 项目上下文 + CLAUDE.md 一起送过去
    loop agentic loop（直到任务完成或被中断）
        M-->>CC: 决定下一步（读哪个文件 / 跑什么命令 / 改哪段代码）
        CC->>T: 执行工具调用（Read / Bash / Edit / Grep ...）
        T-->>CC: 返回结果（文件内容 / stdout / 报错）
        CC->>M: 把结果回传给模型
    end
    CC-->>U: 给出最终回答 + 修改 diff（每次写文件前自动快照，按 Esc Esc 可回滚）
```

### 同源不同形：CLI / IDE / Desktop / SDK 的关系

下面这张图说明了为什么本卡反复强调「Claude Code 是 harness、不是模型」——Anthropic 的所有 Claude 形态其实是同一个内核的不同外壳：

```mermaid
graph TB
    subgraph Core["共享内核"]
        M[Claude 模型族<br/>Sonnet / Opus / Haiku]
        H[Agent Harness<br/>工具集 / 上下文管理 / 权限模型 / 子 Agent]
    end
    subgraph Surfaces["对外形态"]
        CLI[Claude Code CLI<br/>终端 Agent]
        IDE[VS Code / JetBrains 插件<br/>IDE 内 Agent]
        Desk[Desktop App<br/>桌面 Agent]
        Web[claude.ai/code<br/>云端 Agent]
        SDK[Claude Agent SDK<br/>给开发者的编程接口]
    end
    API[Claude API<br/>纯模型 endpoint]
    Chat[Claude Desktop / claude.ai<br/>聊天 GUI]

    M --> H
    H --> CLI
    H --> IDE
    H --> Desk
    H --> Web
    H --> SDK
    M -.直接调用.-> API
    M -.聊天封装.-> Chat
```

注意右下两个虚线：**Claude API 和 Claude Desktop（聊天版）是直接套在模型上的，不经过 harness**——这就是为什么它们没有文件读写、没有 Bash 执行、没有 agentic 循环。Claude Code、IDE 插件、Desktop App、Web、Agent SDK 都共享同一套 harness，所以你的 CLAUDE.md、settings、MCP server、Skills 在它们之间无缝复用。

### 它和"传统 CLI 工具"差在哪

绝大多数命令行工具（`grep`、`make`、`docker` 等）都是**确定性程序**——你输入什么参数，它就执行什么动作。Claude Code 不是这样：**你给它一个自然语言目标，它自己决定调用哪些工具、调用顺序、什么时候停下来**。这是它被叫做 "Agent" 的本质区别。它更像是一个会用 shell 的实习生，而不是一个 shell 命令。

### 它和"IDE 插件版"差在哪

Anthropic 同时还出了 VS Code、JetBrains、Desktop App 几个版本的 Claude Code。**底层 agent 引擎是同一个**——共享 CLAUDE.md、settings、MCP server 配置——只是 UI 外壳不同：

- **CLI**：纯终端，适合 SSH 远程开发、写 shell 脚本管道、跑在 CI 里
- **IDE 插件**：可视化 diff 审查、行内 @-mention、对话历史侧栏
- **Desktop App**：跨会话并行、视觉 diff 审查、定时任务调度

CLI 是最原始、最灵活的形态。本 wiki 的所有卡片默认讨论的是 CLI 形态。

## 基础用法

### 安装

**官方推荐使用 native installer**（2026 年起 npm 版已被标记为 deprecated，但仍可用）：

```bash
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# macOS 用 Homebrew 也可以
brew install --cask claude-code        # 稳定通道
brew install --cask claude-code@latest # 最新通道
```

native installer 装好之后会**自动后台更新**，省去手动升级的烦恼。Homebrew、WinGet 安装的不会自动更新，需要定期 `brew upgrade claude-code` 或 `winget upgrade Anthropic.ClaudeCode`。

> 历史 npm 安装方式 `npm install -g @anthropic-ai/claude-code` 仍然可用，但官方文档已经不再推荐，主要保留给企业内 npm 镜像场景。

### 登录

第一次跑 `claude` 时会要求登录。账号体系有三种：

1. **Claude Pro / Max / Team / Enterprise 订阅账号**（推荐，最简单）
2. **Anthropic Console 账号 + 预付费 credits**（按 token 计费）
3. **Amazon Bedrock / Google Vertex AI / Microsoft Foundry**（企业云接入）

```bash
claude          # 第一次启动会自动弹出登录流程
/login          # 已登录后想切账号用这个 slash 命令
```

凭证会缓存在系统 keychain 里，下次不用再登。

### 第一次会话

走一个最小可运行示例：进项目目录、起会话、让它写一个文件并验证。

```bash
cd ~/playground/my-app
claude
```

进入交互界面之后，直接用自然语言下指令：

```text
你：在项目根目录创建一个 hello.py，里面定义一个函数 say_hi()，
    打印 "Hello from Claude Code"，然后跑一下确认能输出。

Claude：[调用 Write 工具：写入 hello.py]
Claude：[调用 Bash 工具：python hello.py]
Claude：已经创建 hello.py 并验证输出：
        Hello from Claude Code
        需要我帮你加测试或者写 README 吗？
```

注意几个细节：

- 写文件前 Claude 会**先弹出 diff 让你确认**（除非你切到 `Auto-accept edits` 模式）
- 跑 Bash 前会先问你是否允许（除非你预先在 `settings.json` 里 allow 过这条）
- **每次文件修改都会自动快照**，按 `Esc` 双击就能回滚到上一个状态——这是 git 之外的另一道安全网

### 常用命令速查

| 命令 | 干什么 |
|------|--------|
| `claude` | 进入交互式会话 |
| `claude "task"` | 一次性任务，跑完进入交互模式 |
| `claude -p "query"` | 一次性查询，跑完直接退出（适合 shell 管道） |
| `claude -c` | 续接当前目录最近一次会话 |
| `claude -r` | 在历史会话列表里挑一个续接 |
| `claude --fork-session` | 从当前会话分叉一个新会话（不影响原会话） |
| `/help` | 查看所有 slash 命令 |
| `/init` | 帮你生成项目级 CLAUDE.md |
| `/status` | 查看当前生效的所有配置（包含来源） |
| `/context` | 查看上下文窗口被谁占用了多少 |
| `Esc Esc` | 回滚到上一次文件修改前的状态 |
| `Shift+Tab` | 在权限模式之间切换（Default / Auto-accept / Plan / Auto） |

### 配置一个最小的 settings.json

settings 分四层（**Managed → 命令行 → Local → Project → User**，前者覆盖后者）。最常用的是 user 级（`~/.claude/settings.json`）和 project 级（`.claude/settings.json`，可以提交到 git）。

```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read(./src/**)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(curl *)"
    ]
  },
  "hooks": {
    "on-session-start": { "command": "~/.claude/hooks/welcome.sh" }
  }
}
```

这段配置做了三件事：固定模型、给常用命令开绿灯（避免每次问你）、阻断对 `.env` 的读取以防泄密、会话开始时跑一个钩子脚本（典型场景：拉一下当天的 PR 列表打印到终端）。

## 同类工具对比

「同类」这里指的是 **Anthropic 自家的几种使用 Claude 的方式**——它们后端用的可能是同一批模型，但形态完全不同，选哪个取决于你的使用场景。

| 维度 | Claude Code | Claude Desktop / claude.ai | Claude API（Anthropic SDK） | Claude Agent SDK |
|------|-------------|---------------------------|----------------------------|------------------|
| 形态 | 终端 CLI 程序 | 桌面/网页 GUI | HTTP API + 多语言 SDK | 编程框架（Python / TS） |
| 文件系统访问 | ✅ 原生，整个项目 | ❌ 需手动拖文件进对话 | ❌ 需自己实现 | ✅ 通过 SDK 调用同样的工具 |
| Shell 执行 | ✅ 内置 Bash 工具 | ❌ | ❌ | ✅ |
| Agentic 循环 | ✅ 内置 harness 自动循环 | 半 agentic（仅工具调用） | ❌ 需自己写循环 | ✅ |
| MCP 支持 | ✅ 原生 | ✅ | 需自己集成 | ✅ |
| Skills / Hooks | ✅ 完整支持 | ⚠️ 部分支持 | ❌ | ✅（来自 Claude Code 同源） |
| 模型选择 | Anthropic / Bedrock / Vertex / Foundry | Anthropic | Anthropic / Bedrock / Vertex | 同 Claude Code |
| 适合谁 | 工程师日常写代码 | 普通用户聊天/简单生产力 | 想把 Claude 嵌进自己产品的开发者 | 想造自己的 Agent 产品的开发者 |
| 计费模式 | 订阅或按 token | 订阅 | 按 token | 按 token |

### 核心区别一句话

- **Claude Code = 给你一个开箱即用的 Agent，跑在你电脑的终端里**
- **Claude Desktop = 给你一个聊天界面，对话场景为主**
- **Claude API = 给你模型接口，工具/循环/安全你自己造**
- **Claude Agent SDK = 给你 Claude Code 同款引擎的编程接口，让你把 Agent 嵌进自己的程序里**

很多人会把 Claude Code 和 Claude Agent SDK 搞混。**它们其实是同一套底座的两副面孔**：Claude Code 是直接交付给最终用户用的 CLI，Claude Agent SDK 是把同一套 agentic harness（工具集、上下文管理、权限模型、子 Agent 调度）暴露成 API 让开发者重新组合。如果你只是想用，装 Claude Code；如果你想造一个属于自己的 Agent 产品，用 [Claude Agent SDK](/agent/cards/claude-agent-sdk)。

## 常见误区

| 误区 | 准确理解 |
|------|----------|
| 以为 Claude Code 就是 Claude Desktop 的命令行版 | 完全不同。Desktop 是聊天 GUI，看不到你的文件；Claude Code 是带工具集和 agentic 循环的完整 Agent，**默认就能改你的代码、跑你的命令** |
| 以为它只能调 Anthropic 自己的模型 | Claude Code 后端默认走 Anthropic API，但**开箱支持 Amazon Bedrock、Google Vertex AI、Microsoft Foundry**，企业可以走自己的云供应商鉴权 |
| 以为 Claude Code 不能用 MCP | 恰恰相反，**Claude Code 是 MCP 的一等公民**——`.mcp.json` 项目级配置、`~/.claude.json` 用户级配置、managed-settings 企业级配置三套机制齐备，甚至有 `/mcp` 命令实时管理 |
| 以为它会自动把你电脑上的所有东西都发给 Anthropic | Claude 只在**你授权的目录**里读文件，敏感文件可以在 settings 里 deny，凭证存在系统 keychain 里。每次 Bash / 写文件都默认要你确认（除非你显式 allow） |
| 以为 Skills 等于 Hooks | 不一样。**Skills 是「可复用的工作流」**——一段 markdown + 可选脚本，按需被 Claude 主动加载；**Hooks 是「生命周期事件回调」**——PreToolUse、Stop 这些点会被 harness 主动触发执行 shell 命令。一个是 Claude 主动用，一个是 harness 主动调 |
| 以为它装完就要付费 | 安装是免费的，**用 Claude Pro/Max/Team 订阅账号登录就能直接用**（额度共享）；按 API 计费只是另一种付费模式，不是必须 |
| 以为关掉终端就丢了对话 | 每次会话本地都存为 JSONL（在 `~/.claude/projects/` 下），可以 `claude -c` 续接、`claude -r` 在历史里挑、`--fork-session` 分叉。会话历史是持久的，**只是上下文窗口本身每次新会话是从空开始的**（这就是为什么需要 CLAUDE.md 和 auto memory） |

## 优劣势分析

| 优势 | 劣势 |
|------|------|
| **开箱即用的 agentic 循环**：不用自己写 ReAct 框架、不用自己拼工具调用，装完就能跑 | **需要订阅或 API key**：不像 OSS 项目能完全本地化（虽然底层 harness 部分代码已经开源在 github.com/anthropics/claude-code） |
| **工具集深度耦合 Claude 模型**：Read/Edit/Bash/Grep 这些工具的描述和参数是和 Claude 的 prompt 联调过的，不是简单套壳 | **强绑定 Anthropic 模型族**：虽然支持 Bedrock/Vertex/Foundry，但本质上跑的还是 Claude 系列模型，不能换成 GPT/Gemini |
| **生态最完整**：MCP / Skills / Hooks / Subagents / Plugins 五种扩展机制都齐了，2026 年市面上 CLI Agent 里覆盖面最广 | **迭代非常快**：几乎每周都有 release，部分配置字段会改名、行为会调整，老教程容易过时 |
| **企业级权限模型**：Managed settings 可以让 IT 集中下发策略、限制工具白名单、限制能挂的 MCP server | **上下文管理仍然是个工程问题**：长会话会自动 compact，但有时关键指令会被压掉，需要靠 CLAUDE.md 显式持久化 |
| **跨形态共享配置**：CLAUDE.md / settings / MCP / Skills 在 CLI、IDE 插件、Desktop、Web 之间无缝复用 | **学习曲线分两段**：上手很快（5 分钟能跑），但要把 hooks / skills / 子 agent / sandbox 全用透，需要持续投入 |
| **会话与回滚机制完善**：JSONL 持久化、`Esc Esc` 文件级回滚、`--fork-session` 分叉，调试体验远超手撸 SDK | **autonomy 越高风险越大**：`Auto-accept` 和 `--dangerously-skip-permissions` 在没沙箱的环境里跑，可能误删文件、污染数据库，必须配合 git worktree / 容器隔离 |

## 思考题

<details>
<summary>初级：为什么 Anthropic 要在已经有 Claude API 的情况下，再单独发一个 Claude Code？</summary>

**参考答案：**

因为 API 给的是「模型能力」，不等于「能干活的 Agent」。要把 Claude API 变成一个能在你电脑上自主写代码的 Agent，至少还要做这些事：

1. **工具集**：实现 Read / Write / Edit / Bash / Grep / WebFetch 等十几种工具，并把它们的描述写得让 Claude 能正确选用
2. **agentic 循环**：把模型输出的 tool_use 实际执行掉、把结果回灌、判断什么时候停
3. **上下文管理**：会话历史要持久化、上下文窗口要自动 compact、CLAUDE.md / 自动记忆要按规则注入
4. **权限模型**：哪些命令可以直接跑、哪些要问、哪些拒绝、能不能进沙箱
5. **会话状态**：怎么续接、怎么分叉、怎么回滚
6. **生态接入**：MCP / Skills / Hooks / Subagents 怎么挂

这些「Agent harness」的工作如果让每个用户自己写一遍，门槛太高、重复太多。Anthropic 把官方 best practice 打包成 Claude Code 直接交付，**让 95% 的开发者拿到一个调好的 Agent，剩下 5% 想造自己产品的人通过 Claude Agent SDK 复用同一套 harness**。这两个产品其实是同一颗内核的两层封装。

类比一下：API 之于 Claude Code，就像 V8 引擎之于 Chrome——内核是必须的，但大多数人要的是浏览器，不是引擎。

</details>

<details>
<summary>中级：在生产环境里，你打算让 Claude Code 自动跑测试 + 修 bug + 提 PR，整条流水线无人值守。请列出至少 3 个安全风险，并给出对应的缓解策略。</summary>

**参考答案：**

**风险 1：误执行破坏性命令（rm -rf、drop database、git push --force 等）**

- 缓解：在 settings.json 的 `permissions.deny` 里把高危命令拉黑（`Bash(rm -rf *)`、`Bash(git push --force*)`、`Bash(curl *)` 等）
- 缓解：开 sandbox 模式，限制可写目录到 build artifact 和 `/tmp`，禁止写 `~/.aws/`、`/etc/` 等敏感路径
- 缓解：流水线整个跑在容器里（Docker / GitHub Actions runner），即使越权也无法影响宿主机

**风险 2：泄露 secrets（.env、API key、SSH key 被读进上下文然后送到模型）**

- 缓解：`permissions.deny` 里加 `Read(./.env)`、`Read(./.env.*)`、`Read(./secrets/**)`、`Read(~/.ssh/**)`
- 缓解：用 PreToolUse hook 在调用 Read 工具前扫一下路径，发现敏感文件直接 block
- 缓解：仓库本身别把 secrets 提交到 git，用 secret manager 注入到环境变量，且配合 sandbox 的环境变量白名单

**风险 3：上下文/工具被外部内容劫持（prompt injection）**

- 缓解：限制 WebFetch 的域名白名单，不让 Agent 抓任意 URL
- 缓解：MCP server 来源严格白名单（`allowedMcpServers`），不要随便挂社区 server
- 缓解：关键操作（git push、部署、调外部 API）在 hook 里加二次确认或限速，不让模型一句话就触发

**风险 4：循环卡死 / 烧钱**

- 缓解：用 `--max-turns` 之类的硬限制（具体参数见 CLI reference）
- 缓解：在 PostToolUse hook 里统计 token 用量，超过预算就发警报或直接 stop

**通用兜底**：所有自动化都跑在独立 git worktree / 独立分支上，**永远不直接动 main**；最终产物是 PR 而不是直接 merge，留人审查这一步。

实际部署的时候，三道防线缺一不可：**权限白名单（settings）+ 运行沙箱（容器/sandbox 配置）+ 人审兜底（PR review）**。

</details>

## 参考资料

1. Claude Code 官方主页与 Overview：<https://code.claude.com/docs/en/overview>（查询日期 2026-04-22）
2. Claude Code Quickstart：<https://code.claude.com/docs/en/quickstart>（查询日期 2026-04-22）
3. How Claude Code Works（agentic 循环、内置工具分类）：<https://code.claude.com/docs/en/how-claude-code-works>（查询日期 2026-04-22）
4. Settings 配置参考（含 permissions / hooks / mcp）：<https://code.claude.com/docs/en/settings>（查询日期 2026-04-22）
5. Claude Code GitHub 仓库（issue / release / 117k+ star）：<https://github.com/anthropics/claude-code>（查询日期 2026-04-22）
6. Claude Code Changelog（官方）：<https://code.claude.com/docs/en/changelog>（查询日期 2026-04-22）
7. Claude Agent SDK Overview（与 Claude Code 同根的编程接口）：<https://code.claude.com/docs/en/agent-sdk/overview>（查询日期 2026-04-22）
8. Model Context Protocol 官方站（与 Claude Code 互链）：<https://modelcontextprotocol.io/>（查询日期 2026-04-22）

---
*Source: https://learnagent.wiki/cli/cards/claude-code-overview*
*Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*