第一章：产品概述与环境要求

什么是 Claude Code？

Claude Code 是 Anthropic 官方推出的 智能编程命令行工具。 它不是普通的代码补全工具，而是一个能在终端中理解你的整个代码库、 自主执行编码任务的 AI 代理。你可以用自然语言描述需求，Claude Code 会：

• 读取、搜索、编辑你的代码文件
• 执行 shell 命令（运行测试、构建项目、安装依赖）
• 管理 Git 工作流（提交、分支、创建 PR）
• 搜索互联网获取最新信息
• 通过 MCP 协议连接外部工具和服务

系统要求

项目	最低要求	推荐
操作系统	macOS 12+、Ubuntu 20.04+、Windows 10+（WSL 或原生）	macOS 14+、Ubuntu 22.04+
Node.js	18+	22+（源码要求 24.0.0+）
内存	4 GB	8 GB+
磁盘空间	1 GB	2 GB+
网络	需要访问 Anthropic API 或兼容 API	稳定低延迟连接

版本信息

本手册基于泄露源码 999.0.0-restored 版本逆向分析， 结合官方 anthropics/claude-code GitHub 仓库交叉验证。 截至 2026 年 5 月，Claude Code 已发展为一个功能极其丰富的平台。

第二章：安装与升级

2.1 推荐安装方式

macOS / Linux

复制# 方式一：官方安装脚本（推荐）
curl -fsSL https://claude.ai/install.sh | bash

# 方式二：Homebrew
brew install --cask claude-code

Windows

复制# 方式一：PowerShell 安装脚本（推荐）
irm https://claude.ai/install.ps1 | iex

# 方式二：WinGet
winget install Anthropic.ClaudeCode

npm（兼容但已废弃）

复制npm install -g @anthropic-ai/claude-code

2.2 首次启动

2.3 常用启动参数

参数	说明	示例
--version	显示版本号	claude --version
--print / -p	非交互模式，适合管道和脚本	claude -p "解释这个函数"
--output-format	输出格式：text / json / stream-json	claude -p "..." --output-format json
--model	指定模型	claude --model sonnet
--allowedTools	限制可用工具	claude --allowedTools "Read,Write,Bash"
--max-turns	限制最大对话轮次	claude --max-turns 10
--resume	恢复上次会话	claude --resume
--continue	继续最近的对话	claude --continue
--dangerously-skip-permissions	跳过所有权限确认（危险）	CI/CD 场景
--verbose	详细输出模式	claude --verbose
--bare	纯 API Key 模式，跳过 OAuth	仅 API Key 认证

2.4 升级

复制# curl 安装的用户，重新运行安装脚本即可升级
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew
brew upgrade claude-code

# WinGet
winget upgrade Anthropic.ClaudeCode

第三章：认证体系详解

Claude Code 支持四种认证方式。源码中认证优先级定义在 src/utils/auth.ts，采用瀑布式降级策略。

3.1 认证方式总览

方式	优先级	适用场景	配置位置
OAuth	默认	个人开发者，Anthropic 账号登录	claude auth login
API Key	高	企业用户，CI/CD，中转 API	ANTHROPIC_API_KEY 环境变量
apiKeyHelper	高	动态获取密钥，企业密钥管理	~/.claude/settings.json
第三方平台	专有	AWS Bedrock / Google Vertex / Foundry	专用环境变量

3.2 OAuth 登录（推荐）

复制# 交互式登录（浏览器跳转）
claude auth login

# 查看当前认证状态
claude auth status

# 登出
claude auth logout

OAuth 登录会打开浏览器跳转到 Anthropic 账号页面。 登录成功后 Token 存储在：

• macOS：Keychain（系统安全存储）
• Linux：~/.claude/credentials.json
• Windows：Credential Manager 或文件存储

3.3 API Key 认证

方式一：环境变量（最常用）

复制# 临时设置（当前终端会话）
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxx"

# 永久设置（添加到 ~/.bashrc / ~/.zshrc）
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

方式二：settings.json 中的环境变量

复制// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-xxxxxxxxxxxx"
  }
}

方式三：apiKeyHelper（高级）

apiKeyHelper 允许通过外部命令动态获取 API Key， 支持企业密钥轮换、临时凭证等场景。源码中缓存 TTL 为 5 分钟。

复制// ~/.claude/settings.json
{
  "apiKeyHelper": "cat /path/to/api_key.txt"
}

更高级的例子 — 从密钥管理服务获取：

复制{
  "apiKeyHelper": "aws secretsmanager get-secret-value --secret-id claude-api-key --query SecretString --output text"
}

3.4 AWS Bedrock 集成

使用 AWS Bedrock 运行 Claude 模型，无需 Anthropic API Key。

复制# 启用 Bedrock 模式
export CLAUDE_CODE_USE_BEDROCK=1

# 配置 AWS 凭证（任选一种）
# 方式一：AWS CLI 配置
aws configure

# 方式二：环境变量
export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
export AWS_REGION="us-east-1"

# 可选：指定模型
export CLAUDE_CODE_BEDROCK_MODEL="us.anthropic.claude-sonnet-4-20250514"

3.5 Google Vertex AI 集成

复制# 启用 Vertex 模式
export CLAUDE_CODE_USE_VERTEX=1

# 配置 Google Cloud 认证
export CLOUD_ML_REGION="us-east5"
export ANTHROPIC_VERTEX_PROJECT_ID="your-gcp-project-id"

# Google Cloud 认证（任选一种）
gcloud auth application-default login
# 或
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

3.6 Foundry（本地/私有部署）集成

复制# 启用 Foundry 模式
export CLAUDE_CODE_USE_FOUNDRY=1

# 指定 Foundry 端点
export ANTHROPIC_BASE_URL="https://your-foundry-endpoint/v1"

3.7 认证优先级（源码解析）

基于 src/utils/auth.ts 和 src/cli/handlers/auth.ts 逆向：

第四章：代理与网络配置

4.1 为什么需要代理？

Anthropic API 端点 api.anthropic.com 在中国大陆无法直接访问。 国内用户必须通过以下方式之一解决网络问题。

4.2 方案一：ANTHROPIC_BASE_URL（中转 API）

这是最推荐的方案。设置 ANTHROPIC_BASE_URL 指向一个兼容 Anthropic API 的中转服务。 源码中所有 API 请求都通过这个基础 URL 构建。

复制# 设置中转 API 地址
export ANTHROPIC_BASE_URL="https://your-proxy.example.com"

# 配合 API Key 使用
export ANTHROPIC_API_KEY="sk-ant-xxxxx"  # 或中转服务提供的 Key

# 或在 settings.json 中配置
# ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-proxy.example.com",
    "ANTHROPIC_API_KEY": "your-api-key"
  }
}

4.3 方案二：HTTP/SOCKS 代理

复制# HTTP 代理
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

# SOCKS5 代理
export HTTP_PROXY="socks5://127.0.0.1:1080"
export HTTPS_PROXY="socks5://127.0.0.1:1080"

# 需要 Node.js 支持的代理方式
# 全局代理（推荐）
export ALL_PROXY="http://127.0.0.1:7890"

注意：Claude Code 底层使用 undici HTTP 客户端（源码依赖），部分代理需要额外配置。

4.4 方案三：系统级代理 / TUN 模式

如果使用 Clash、V2Ray 等工具的 TUN/系统代理模式， Claude Code 的所有流量会自动经过代理，无需额外配置。 这是最简单的方案，但可能影响其他应用。

4.5 网络相关环境变量完整参考

变量	说明	示例
ANTHROPIC_BASE_URL	API 基础 URL，覆盖默认端点	https://api.example.com
HTTP_PROXY	HTTP 代理地址	http://127.0.0.1:7890
HTTPS_PROXY	HTTPS 代理地址	http://127.0.0.1:7890
ALL_PROXY	全局代理	socks5://127.0.0.1:1080
NO_PROXY	不经过代理的域名	localhost,127.0.0.1
ANTHROPIC_UNIX_SOCKET	Unix 域套接字（SSH 隧道场景）	/tmp/claude-proxy.sock

4.6 macOS Keychain 代理场景

源码中 src/utils/authPortable.ts 使用 macOS Keychain 安全存储 API Key。 如果你在 macOS 上遇到 Keychain 弹窗，这是正常的 — Claude Code 在读取已保存的凭证。

第五章：国内大模型与中转 API 集成

5.1 国内使用场景总览

国内开发者使用 Claude Code 主要有以下路径：

5.2 中转 API 详细配置

通用中转服务配置

复制# 1. 获取中转服务的 API Key 和 Base URL
# 2. 配置环境变量

export ANTHROPIC_BASE_URL="https://api.your-proxy.com"
export ANTHROPIC_API_KEY="sk-your-proxy-key"

# 3. 启动 Claude Code
claude

OpenRouter 配置示例

复制export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxx"

5.3 国内模型间接使用

Claude Code 的 API 客户端期望 Anthropic Messages API 格式。 如果国内模型提供商实现了兼容接口（如 DeepSeek 的 OpenAI 兼容模式）， 理论上可以通过 ANTHROPIC_BASE_URL 指向适配层。

5.4 自建中转服务

如果你有 Anthropic API 访问能力，可以自建中转：

复制// 最简单的 Node.js 中转示例
import express from 'express'
import fetch from 'node-fetch'

const app = express()
app.use(express.json())

app.all('/v1/*', async (req, res) => {
  const upstream = await fetch(`https://api.anthropic.com${req.path}`, {
    method: req.method,
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.REAL_API_KEY,
      'anthropic-version': req.headers['anthropic-version'] || '2023-06-01',
    },
    body: JSON.stringify(req.body),
  })
  res.status(upstream.status)
  upstream.body.pipe(res)
})

app.listen(3000)

第六章：Settings 配置体系深度解析

6.1 配置文件层级

Claude Code 的配置系统采用多层覆盖架构（优先级从高到低）：

6.2 settings.json 完整字段参考

复制// ~/.claude/settings.json — 完整配置示例
{
  // ===== 认证 =====
  "apiKeyHelper": "cat ~/.anthropic-key",   // 动态获取 API Key 的命令

  // ===== 环境变量 =====
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
    "ANTHROPIC_BASE_URL": "https://your-proxy.com",
    "MY_CUSTOM_VAR": "some-value"
  },

  // ===== 权限控制 =====
  "permissions": {
    "allow": [
      "Read",                    // 允许读取任意文件
      "Write",                   // 允许写入任意文件
      "Bash(git log*)",         // 允许特定命令模式
      "Bash(npm test*)",
      "WebFetch",               // 允许网页抓取
      "mcp__my_server__*"       // 允许特定 MCP 服务器的所有工具
    ],
    "deny": [
      "Bash(rm -rf*)",          // 禁止危险命令
      "Write(.env*)",           // 禁止写入环境变量文件
      "Read(*secret*)"          // 禁止读取敏感文件
    ]
  },

  // ===== MCP 服务器 =====
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./mcp-server.js"],
      "env": { "API_KEY": "xxx" }
    }
  },

  // ===== 模型配置 =====
  "model": "claude-sonnet-4-20250514",
  "smallModel": "claude-haiku-4-5-20251001",

  // ===== 其他 =====
  "theme": "dark",
  "verbose": true
}

6.3 权限规则语法

permissions.allow 和 permissions.deny 使用 glob 模式匹配：

模式	含义	示例
ToolName	允许/禁止某个工具	Read、Write、Bash
Bash(command*)	允许/禁止匹配前缀的命令	Bash(git *)
mcp__server__tool	控制特定 MCP 工具	mcp__github__create_issue
mcp__server__*	控制 MCP 服务器的所有工具	mcp__mydb__*
Read(pattern)	允许读取匹配的文件路径	Read(src/**)
Write(pattern)	允许写入匹配的文件路径	Write(*.ts)

6.4 企业托管配置详解

企业管理员可以通过 Managed Settings 强制推配置，用户无法覆盖。 典型配置文件路径：

复制// /etc/claude-code/managed-settings.json（macOS/Linux）
{
  "permissions": {
    "deny": [
      "Bash(curl*)",
      "Bash(wget*)",
      "Bash(*|*)",           // 禁止管道
      "Bash(*>*)",           // 禁止重定向
      "Write(/etc/*)",
      "Read(/etc/shadow*)"
    ]
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://internal-api.company.com"
  },
  "allowedMcpServers": ["internal-tools"],
  "disableUpdateCheck": true
}

第七章：CLAUDE.md 记忆系统

7.1 什么是 CLAUDE.md？

CLAUDE.md 是 Claude Code 的项目记忆文件， 在每次对话开始时自动加载到系统提示中。 它让你能为 Claude 设定项目上下文、编码规范、架构决策等。

7.2 三级 CLAUDE.md 体系

层级	路径	作用域	Git
用户级	~/.claude/CLAUDE.md	所有项目共享	不提交
项目级	项目根/CLAUDE.md	当前项目	提交到 Git
目录级	子目录/CLAUDE.md	子目录上下文	提交到 Git

7.3 CLAUDE.md 最佳实践

复制# 项目根/CLAUDE.md 示例

## 项目概述
这是一个 Next.js 14 + TypeScript 的电商平台项目。

## 技术栈
- 框架：Next.js 14 (App Router)
- 语言：TypeScript 严格模式
- 样式：Tailwind CSS
- 数据库：PostgreSQL + Prisma
- 测试：Vitest + Playwright

## 编码规范
- 使用函数式组件和 hooks，不用 class 组件
- 文件命名：kebab-case
- 组件命名：PascalCase
- 常量全大写：UPPER_SNAKE_CASE
- 优先使用 `import type` 导入类型
- 所有 async 函数必须有错误处理

## 项目结构
- `src/app/` — 页面路由
- `src/components/` — 共享组件
- `src/lib/` — 工具函数和配置
- `src/server/` — 服务端逻辑

## 测试要求
- 新增功能必须包含单元测试
- 测试文件放在 `__tests__/` 目录
- 运行测试：`npm run test`
- 运行 lint：`npm run lint`

## 注意事项
- 不要修改 `prisma/schema.prisma` 除非明确要求
- 环境变量在 `.env.local` 中，不要提交到 Git
- API 路由统一在 `src/app/api/` 下

7.4 CLAUDE.md 中的指令

你可以在 CLAUDE.md 中写入指令来控制 Claude 的行为：

• 编码规范：告诉 Claude 项目的代码风格
• 禁止操作：例如"不要删除测试文件"
• 架构约束：例如"数据库操作只在 server 目录中"
• 命令提示：告诉 Claude 如何运行构建和测试
• Git 规范：commit message 格式、分支命名等

第八章：模型选择与参数调优

8.1 可用模型

模型别名	完整模型 ID	特点	适用场景
opus	claude-opus-4-20250515	最强推理能力，速度较慢	复杂架构设计、难题攻坚
sonnet	claude-sonnet-4-20250514	能力与速度的平衡	日常编码（默认推荐）
haiku	claude-haiku-4-5-20251001	最快速度，成本最低	快速问答、简单任务

8.2 模型选择方式

复制# 命令行参数
claude --model opus

# 在对话中切换（斜杠命令）
/model opus

# settings.json 全局默认
{
  "model": "claude-sonnet-4-20250514"
}

# 环境变量
export CLAUDE_CODE_MODEL="opus"

8.3 模型别名系统（源码解析）

源码 src/utils/model/model.ts 中定义了模型别名映射：

别名	映射到
opus	claude-opus-4 最新版本
sonnet	claude-sonnet-4 最新版本
haiku	claude-haiku-4-5 最新版本
opusplan	opus（仅 plan 模式使用）

8.4 Thinking 模式（深度思考）

Claude Code 默认启用 extended thinking（扩展思考），让模型在回答前进行更深入的推理。 这对于复杂代码任务非常重要。

复制# 控制思考预算（token 数）
# 在 settings.json 或环境变量中设置
{
  "thinkingBudgetTokens": 10000   // 增加思考深度
}

8.5 Extended Context（扩展上下文）

默认上下文窗口为 200K tokens。通过扩展上下文可以达到 1M tokens， 适合超大型代码库。

复制# 启用扩展上下文（1M tokens）
# 在对话中使用斜杠命令
/extended-context

8.6 Prompt Caching（提示缓存）

源码中 Claude Code 默认启用 Anthropic 的 prompt caching 功能， 通过缓存不变的系统提示和工具定义来降低成本。 源码中设置了 anthropic-beta: prompt-caching-2024-07-31 头。

8.7 小模型配置

Claude Code 在某些轻量任务（如文件搜索、简单分类）中使用小模型以节省成本。 可通过 smallModel 配置：

复制// settings.json
{
  "smallModel": "claude-haiku-4-5-20251001"
}

第九章：权限模式与安全配置

9.1 权限模式概览

模式	行为	启动方式	适用场景
Default	每个敏感操作都需要用户确认	claude	日常开发（最安全）
Auto-accept edits	自动接受文件编辑，其他操作仍需确认	在对话中选择	信任 Claude 的编辑能力
Plan	先规划再执行，需批准计划后才动手	claude --plan	复杂任务，需要先理解再动手
Bypass	跳过所有权限检查	--dangerously-skip-permissions	CI/CD、自动化脚本（危险）

9.2 权限确认机制

在默认模式下，Claude Code 的以下操作需要用户确认：

• Write：写入或修改文件
• Bash：执行 shell 命令
• WebFetch：抓取外部网页
• MCP 工具：调用外部工具

Read（读取文件）和 Grep/Glob（搜索）不需要确认。

9.3 自定义权限白名单

复制// ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(git *)",           // 允许所有 git 命令
      "Bash(npm run *)",       // 允许 npm 脚本
      "Bash(npx vitest *)",    // 允许测试
      "Read",                  // 允许读取（默认就是允许的）
      "Write(src/**)",         // 允许写入 src 目录
      "mcp__github__*"         // 允许 GitHub MCP 所有操作
    ],
    "deny": [
      "Bash(rm -rf /)",        // 禁止危险删除
      "Bash(sudo *)",          // 禁止 sudo
      "Write(.env*)",          // 禁止修改环境变量文件
      "Write(**/secret*)",     // 禁止写入敏感文件
      "Read(**/.ssh/**)"       // 禁止读取 SSH 密钥
    ]
  }
}

9.4 CI/CD 场景配置

复制# GitHub Actions 示例
- name: Run Claude Code
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude -p "Run the test suite and fix any failing tests" \
      --dangerously-skip-permissions \
      --max-turns 20 \
      --output-format json

第十章：MCP 服务器集成

10.1 什么是 MCP？

MCP（Model Context Protocol） 是 Anthropic 推出的开放协议， 允许 Claude Code 通过标准化接口连接外部工具和服务。 Claude Code 既是 MCP 客户端（调用外部工具），也支持作为 MCP 服务器（被其他工具调用）。

10.2 配置 MCP 服务器

复制// ~/.claude/settings.json 或 .claude/settings.json
{
  "mcpServers": {
    // 本地命令启动的 MCP 服务器
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-filesystem", "/path/to/dir"]
    },

    // 带环境变量的 MCP 服务器
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxx"
      }
    },

    // SSE 连接的远程 MCP 服务器
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

10.3 常用 MCP 服务器

服务器	功能	安装命令
Filesystem	安全文件系统访问	npx @anthropic-ai/mcp-server-filesystem
GitHub	GitHub API 操作	npx @anthropic-ai/mcp-server-github
PostgreSQL	数据库查询	npx @anthropic-ai/mcp-server-postgres
Puppeteer	浏览器自动化	npx @anthropic-ai/mcp-server-puppeteer
Memory	持久化知识图谱	npx @anthropic-ai/mcp-server-memory
Sentry	错误追踪	npx @anthropic-ai/mcp-server-sentry

10.4 在对话中使用 MCP 工具

MCP 服务器启动后，其提供的工具会出现在 Claude Code 的工具列表中。 工具名称格式为 mcp__服务器名__工具名。

复制# 示例：配置了 GitHub MCP 后，可以直接说：
"创建一个 issue，标题是 'Fix login bug'"
"查看最近的 PR 列表"
"搜索 closed 状态的 issue"

# Claude 会自动调用 mcp__github__create_issue、
# mcp__github__list_pull_requests 等工具

10.5 MCP 工具权限控制

复制// settings.json
{
  "permissions": {
    "allow": [
      "mcp__github__list_*",          // 允许所有 GitHub 列表查询
      "mcp__github__create_issue",    // 允许创建 issue
      "mcp__postgres__query"          // 允许数据库查询
    ],
    "deny": [
      "mcp__github__delete_*",        // 禁止删除操作
      "mcp__postgres__execute"        // 禁止数据库写入
    ]
  }
}

第十一章：自定义 Agent / Skills / Hooks

11.1 自定义 Agent（子代理）

你可以在 .claude/agents/ 目录下创建自定义 Agent 定义文件， 它们会出现在 Claude Code 的 /agent 斜杠命令中。

复制# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: 专门做代码审查的 Agent
tools:
  - Read
  - Grep
  - Glob
---

你是一个专业的代码审查专家。请审查给定的代码变更，关注：
1. 代码正确性和潜在 Bug
2. 安全漏洞（SQL注入、XSS、命令注入）
3. 性能问题
4. 代码可维护性
5. 命名规范

输出格式：
- 每个问题一行，包含文件名和行号
- 按严重程度排序（Critical > Warning > Info）

11.2 Skills（技能）

Skills 是可复用的任务模板，通过斜杠命令调用。 Claude Code 内置了大量 Skills，你也可以创建自定义 Skills。

复制# 使用内置 Skill
/bug          # 报告 Bug
/init         # 初始化项目配置
/pr           # 创建 Pull Request

# Skill 文件结构
.claude/skills/
  my-skill.md      # Skill 定义文件

11.3 Hooks（钩子）

Hooks 允许你在特定事件发生时执行自定义命令。 配置在 settings.json 的 hooks 字段中。

复制// settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "command": "echo 'File being modified: $TOOL_INPUT' >> /tmp/audit.log"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "command": "notify-send 'Claude Code' 'Command completed'"
      }
    ],
    "Stop": [
      {
        "command": "say 'Task completed'"
      }
    ]
  }
}

可用 Hook 事件

事件	触发时机	可用变量
PreToolUse	工具调用前	TOOL_NAME、TOOL_INPUT
PostToolUse	工具调用后	TOOL_NAME、TOOL_OUTPUT
Notification	收到通知时	NOTIFICATION_MESSAGE
Stop	对话结束时	—
SubagentStop	子代理完成时	—

第十二章：多智能体协作与 Agent Teams

12.1 多智能体架构

Claude Code 支持多智能体协作，源码中称为 Coordinator 模式。 一个主 Agent（协调者）可以分派任务给多个子 Agent（执行者）并行或串行执行。

12.2 Agent Teams

通过 TeamCreate 创建团队，使用 Agent 工具分派成员。 团队共享一个任务列表（TaskList），成员之间通过 SendMessage 通信。

复制# 在对话中创建团队（示例）
"创建一个团队来重构认证模块"

# Claude 会：
# 1. 用 TeamCreate 创建团队和任务列表
# 2. 用 TaskCreate 创建任务
# 3. 用 Agent 分派成员
# 4. 成员通过 TaskUpdate 更新进度
# 5. 完成后用 SendMessage 关闭成员

12.3 Worktree 隔离

并行任务使用 Git Worktree 隔离工作空间，避免文件冲突。 源码中 src/utils/swarm/ 目录实现了完整的分布式执行架构。

复制# Worktree 工作流
.claude/worktrees/
  task-1/     # 任务1的工作树（独立分支）
  task-2/     # 任务2的工作树（独立分支）

# 完成后 squash 合并回主分支

12.4 Coordinator 模式（源码解析）

源码 src/coordinator/coordinatorMode.ts 中的 Coordinator 模式：

• 通过 CLAUDE_CODE_COORDINATOR_MODE=1 环境变量激活
• 主 Agent 充当协调者，不直接执行任务
• 子 Agent 使用精简工具集（CLAUDE_CODE_SIMPLE=1）
• 支持 tmux 窗格并行显示多个 Agent 状态
• 完成后通过 SendMessage 汇报结果

第十三章：Plan 模式与 Worktree 工作流

13.1 Plan 模式

Plan 模式让 Claude 在动手前先制定详细计划，用户审批后才执行。 适合复杂任务，防止 Claude 偏离方向。

复制# 启动 Plan 模式
claude --plan

# 在对话中切换
/plan

Plan 模式的工作流：

13.2 自动 Plan（Opus Plan）

源码中有 opusplan 模型别名，专门用于 Plan 模式。 系统会在 Plan 阶段自动使用 Opus 模型（最强推理能力）， 执行阶段切换回 Sonnet（更快速度），实现成本与质量的最优平衡。

13.3 Worktree 工作流

Git Worktree 允许在同一仓库中同时检出多个分支到不同目录。 Claude Code 利用 Worktree 实现任务隔离：

复制# Claude Code 自动管理的 Worktree 结构
.claude/worktrees/
  feature-auth/      # 在独立分支上工作
  feature-api/       # 另一个独立分支

# Worktree 操作
git worktree list                    # 查看所有 worktree
git worktree add .claude/worktrees/task-1 -b task-1  # 创建
git worktree remove .claude/worktrees/task-1          # 清理

第十四章：IDE 集成

14.1 VS Code 集成

Claude Code 提供官方 VS Code 扩展，可以在编辑器中直接使用。

VS Code 集成额外功能：

• 选中代码后右键发送给 Claude 分析
• 直接在编辑器中查看和接受代码修改
• Terminal 集成（在 VS Code 终端中直接运行 claude）
• 文件上下文自动感知

14.2 JetBrains 集成

Claude Code 也支持 JetBrains IDE（IntelliJ、PyCharm、WebStorm 等）， 通过终端工具窗口使用。

14.3 源码中的 IDE 检测

源码中通过环境变量检测运行环境：

变量	含义
TERM_PROGRAM	终端类型（vscode = VS Code 集成终端）
JETBRAINS_IDE	JetBrains IDE 标识
CLAUDE_CODE_ENTRYPOINT	入口类型（claude-desktop = 桌面应用）

第十五章：高级场景与故障排除

15.1 常用斜杠命令速查

命令	功能
/help	显示帮助信息
/init	初始化项目 CLAUDE.md
/bug	报告 Bug
/clear	清除对话历史
/compact	压缩对话上下文（节省 tokens）
/model	切换模型
/cost	查看当前会话成本
/permissions	查看/修改权限设置
/review	代码审查
/pr	创建 Pull Request
/memory	编辑 CLAUDE.md 记忆文件
/plan	进入 Plan 模式
/terminal-setup	配置终端集成
/mcp	管理 MCP 服务器
/doctor	诊断常见问题
/status	查看系统状态

15.2 重要环境变量完整参考

变量	说明
ANTHROPIC_API_KEY	Anthropic API 密钥
ANTHROPIC_BASE_URL	API 基础 URL（覆盖默认端点）
ANTHROPIC_AUTH_TOKEN	认证令牌（Bearer Token）
CLAUDE_CODE_USE_BEDROCK	启用 AWS Bedrock 模式
CLAUDE_CODE_USE_VERTEX	启用 Google Vertex 模式
CLAUDE_CODE_USE_FOUNDRY	启用 Foundry 模式
CLAUDE_CODE_MODEL	默认模型
CLAUDE_CODE_COORDINATOR_MODE	Coordinator 多智能体模式
CLAUDE_CODE_REMOTE	远程模式（CCR/Bridge）
CLAUDE_CODE_OAUTH_TOKEN	OAuth 令牌（程序化使用）
CLAUDE_CODE_OAUTH_REFRESH_TOKEN	OAuth 刷新令牌
CLAUDE_CODE_OAUTH_SCOPES	OAuth 权限范围
CLAUDE_CODE_SIMPLE	精简模式（子代理使用）
CLAUDE_CODE_PROACTIVE	启用主动模式（KAIROS 功能）
CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR	从文件描述符读取 API Key
CLAUDE_CODE_DISABLE_CLAUDE_MDS	禁用 Claude 模型发现服务
CLAUDE_CODE_SKIP_PROMPT_HISTORY	跳过提示历史加载
AWS_ACCESS_KEY_ID	AWS 访问密钥（Bedrock）
AWS_SECRET_ACCESS_KEY	AWS 秘密密钥（Bedrock）
AWS_REGION	AWS 区域（Bedrock）
CLOUD_ML_REGION	Google Cloud 区域（Vertex）
ANTHROPIC_VERTEX_PROJECT_ID	GCP 项目 ID（Vertex）
GOOGLE_APPLICATION_CREDENTIALS	GCP 服务账号 JSON（Vertex）
HTTP_PROXY / HTTPS_PROXY	HTTP(S) 代理
ANTHROPIC_UNIX_SOCKET	Unix 域套接字（SSH 隧道）

15.3 常见问题排查

问题 1：连接超时 / 无法连接到 API

复制# 检查网络连通性
curl -I https://api.anthropic.com

# 如果超时，需要配置代理或中转
export ANTHROPIC_BASE_URL="https://your-proxy.com"
export ANTHROPIC_API_KEY="your-key"

# 验证中转可用
curl -H "x-api-key: $ANTHROPIC_API_KEY" \
     -H "anthropic-version: 2023-06-01" \
     -H "content-type: application/json" \
     -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}' \
     $ANTHROPIC_BASE_URL/v1/messages

问题 2：认证失败 / Token 过期

复制# 重新登录
claude auth logout
claude auth login

# 或使用 API Key 模式
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 查看当前认证状态
claude auth status

问题 3：权限被拒绝

复制# 检查当前权限配置
claude /permissions

# 临时允许特定操作（在对话中输入）
# 在权限提示时选择 "Allow" 或 "Allow always"

# 永久允许（settings.json）
{
  "permissions": {
    "allow": ["Bash(npm *)", "Write(src/**)"]
  }
}

问题 4：上下文过长 / 成本过高

复制# 压缩上下文
/compact

# 限制对话轮次
claude --max-turns 10

# 使用更便宜的模型
claude --model haiku

# 清除对话重新开始
/clear

问题 5：MCP 服务器启动失败

复制# 查看 MCP 状态
/mcp

# 检查 MCP 服务器配置
cat ~/.claude/settings.json | grep -A 10 mcpServers

# 常见原因：
# 1. command 路径不正确（使用绝对路径）
# 2. Node.js 版本不兼容
# 3. 缺少环境变量（检查 env 字段）
# 4. 端口冲突（SSE 模式）

15.4 性能优化建议

15.5 非交互式使用（自动化场景）

复制# 单次执行并输出
claude -p "列出项目中所有 TODO 注释" --output-format text

# JSON 输出（适合程序处理）
claude -p "分析这个函数的复杂度" --output-format json

# 流式 JSON（适合实时显示）
claude -p "重构这个模块" --output-format stream-json

# 管道输入
cat error.log | claude -p "分析这个错误日志并给出修复建议"

# CI/CD 集成
claude -p "运行测试并修复失败用例" \
  --dangerously-skip-permissions \
  --max-turns 30 \
  --output-format json \
  --model sonnet

15.6 数据隐私与安全

15.7 隐藏功能一览（社区发现）

通过源码逆向分析发现的部分隐藏/实验性功能，部分需要特定条件激活：

功能	激活方式	说明
BUDDY 宠物系统	feature('BUDDY')	18种虚拟宠物，5个稀有度等级，基于用户 ID 确定性生成
KAIROS 持久助手	feature('KAIROS') + settings	关闭终端后仍运行，自动写日志、整理记忆、做梦
Coordinator 模式	CLAUDE_CODE_COORDINATOR_MODE=1	多智能体协调，自动分派任务给子 Agent
Bridge 远程控制	CLAUDE_CODE_REMOTE	允许远程控制 Claude Code 会话
Voice 语音模式	feature('VOICE')	语音输入输出交互
Proactive 主动模式	CLAUDE_CODE_PROACTIVE=1	没人说话时 Claude 自己找活干