内容

快速链接: 安装 · 命令 · 快捷键 · MCP · 故障排除

• 入门

  • 快速入门
  • 初始设置

• 配置与环境

  • 环境变量
  • 配置文件

• 命令与使用

  • 斜杠命令参考
  • CLI 快速参考

• 界面与输入

  • 键盘快捷键
  • Vim 模式

• 高级功能

  • 思考模式
  • 计划模式
  • 快速模式
  • 后台任务
  • Chrome 中的 Claude
  • 沙盒模式
  • LSP 工具
  • 远程会话
  • 子代理
  • 代理团队
  • 技能
  • 插件系统
  • 工作树隔离
  • MCP 集成
  • 钩子系统
  • 原生安装程序
  • 认证 CLI
  • 代理管理 CLI
  • 远程控制
  • 托管设置
  • 模型更新
  • 洞察

• 安全与权限

  • 危险模式
  • 安全最佳实践

• 自动化与集成

  • 自动化与脚本
  • 自动 PR 审核
  • 问题分类

• 帮助与故障排除

  • 安装问题
  • MCP 问题
  • 最佳实践

• 第三方集成

  • DeepSeek 集成

开始使用

启用 Claude 完成任务时的声音提醒：

claude config set --global preferredNotifChannel terminal_bell

快速入门

[!TIP] 在终端中输入 claude 或 npx claude 即可启动界面

前往 帮助与故障排除 解决问题...

# 原生安装程序（推荐 — 无需 Node.js）⭐️
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Windows
/* 通过 CMD（原生）      */ curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
/* 通过 Powershell        */ irm https://claude.ai/install.ps1 | iex
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# macOS / Linux / WSL
/* 通过终端          */ curl -fsSL https://claude.ai/install.sh | bash
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Arch
/* 通过终端          */ yay -S claude-code*/
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

# 替代方案（npm）— 已被原生安装程序取代
# 需要 Node.js 18+
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Windows
/* 通过 CMD（npm）         */ npm install -g @anthropic-ai/claude-code
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# macOS
/* 通过终端          */ brew install node && npm install -g @anthropic-ai/claude-code
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Linux
/* 通过终端          */ sudo apt update && sudo apt install -y nodejs npm
/* 通过终端          */ npm install -g @anthropic-ai/claude-code
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

# WSL/GIT
/* 通过终端          */ npm install -g @anthropic-ai/claude-code
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# Docker
/* Windows (CMD)         */ docker run -it --rm -v "%cd%:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc "npm i -g @anthropic-ai/claude-code && cd /workspace && claude"
/* macOS/Linux (bash/zsh)*/ docker run -it --rm -v "$PWD:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc 'npm i -g @anthropic-ai/claude-code && cd /workspace && claude'
/* 无 bash 备用      */ docker run -it --rm -v "$PWD:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim sh -lc 'npm i -g @anthropic-ai/claude-code && cd /workspace && claude'
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# 检查 claude 是否安装正确
/* Linux                 */ which claude
/* Windows               */ where claude
/* 通用                  */ claude --version
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
# 常见管理
/*claude config          */ 配置设置
/*claude mcp list        */ 设置 MCP 服务器，你也可以将 "list" 替换为 add/remove
/*claude /agents         */ 为不同任务配置/设置子代理
/*claude update          */ 更新到最新版本

[!Tip] 通过终端打开项目到 VS Code / Cursor

$ - cd /path/to/project

$ - code .

请确保在你的 VS Code / Cursor 中已安装 (Claude Code 扩展)

系统要求

• 操作系统：macOS 10.15+、Ubuntu 20.04+/Debian 10+，或 Windows 10/11 或 WSL

• 硬件：最低 4GB 内存，建议 8GB+

• 软件：Node.js 18+ 或 git 2.23+（可选）以及 GitHub 或 GitLab CLI 用于 PR 流程（可选）
• Node.js 仅在使用 npm 安装时需要。原生安装程序自带运行时环境。

• 网络：用于 API 调用的连接

• Node.js 18+ (仅在使用 npm 安装时需要；原生安装程序自带运行时环境)

初始设置

[!Tip] 从 Anthropic 控制台 获取 API 密钥

切勿提交真实密钥，请使用 git 忽略文件、操作系统密钥存储或秘密管理工具

# 通用
/* 开始登录流程                    */ claude /login
/* 设置长期有效认证令牌  */ claude setup-token
/* 通过 Anthropic 账户认证     */ claude auth login
----------------------------------------------------------------------------------------------------------------------------------
# Windows
/* 设置 API 密钥        */ set ANTHROPIC_API_KEY=sk-your-key-here-here
/* CMD 掩码检查   */ echo OK: %ANTHROPIC_API_KEY:~0,8%***
/* 设置持久密钥 */ setx ANTHROPIC_API_KEY "sk-your-key-here-here"
/* CMD 取消设置密钥      */ set ANTHROPIC_API_KEY=
----------------------------------------------------------------------------------------------------------------------------------
# Linux
/* 设置 API 密钥        */ export ANTHROPIC_API_KEY="sk-your-key-here-here"
/* 掩码检查       */ echo "OK: ${ANTHROPIC_API_KEY:0:8}***"
/* 移除会话     */ unset ANTHROPIC_API_KEY
----------------------------------------------------------------------------------------------------------------------------------
# Powershell
/* PS 会话         */ $env:ANTHROPIC_API_KEY = "sk-your-key-here-here"
/* PS 掩码检查    */ "OK: $($env:ANTHROPIC_API_KEY.Substring(0,8))***"
/* PS 持久化         */ [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY","sk-your-key-here-here","User")
/* PS 更换密钥      */ $env:ANTHROPIC_API_KEY = "sk-new-key"
/* PS 删除密钥      */ Remove-Item Env:\ANTHROPIC_API_KEY
----------------------------------------------------------------------------------------------------------------------------------
# 其他...
# persist-bash/*      */ echo 'export ANTHROPIC_API_KEY="sk-your-key-here-here"' >> ~/.bashrc && source ~/.bashrc
# persist-zsh /*      */ echo 'export ANTHROPIC_API_KEY="sk-your-key-here-here"' >> ~/.zshrc  && source ~/.zshrc
# persist-fish/*      */ fish -lc 'set -Ux ANTHROPIC_API_KEY sk-your-key-here-here'
----------------------------------------------------------------------------------------------------------------------------------

配置与环境

环境变量

你也可以在 settings.json 的 "env" 键下设置这些变量，以实现自动应用。

[!重要] Windows 用户请将 export 替换为 set 或 setx 以实现永久设置

# 环境变量开关（放入 ~/.bashrc 或 ~/.zshrc）
export ANTHROPIC_API_KEY="sk-your-key-here-here"      # 作为 X-Api-Key 头发送的 API 密钥（交互式使用：/login）
export ANTHROPIC_AUTH_TOKEN="my-auth-token"           # 自定义 Authorization 头；Claude 会自动添加 "Bearer " 前缀
export ANTHROPIC_CUSTOM_HEADERS="X-Trace-Id: 12345"   # 额外的请求头（格式：名称: 值）

export ANTHROPIC_MODEL="claude-sonnet-4-6-20260217"                # 自定义要使用的模型名称
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6-20260217" # 默认 Sonnet 模型别名
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6-20260130"   # 默认 Opus 模型别名（Opus 4.6 现已可用）
export ANTHROPIC_SMALL_FAST_MODEL="haiku-model"                  # 用于后台任务的 Haiku 级模型（占位符）
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION="REGION"            # 覆盖 Bedrock 上小型快速模型的 AWS 区域（占位符）

export AWS_BEARER_TOKEN_BEDROCK="bedrock_..."         # 用于身份验证的 Amazon Bedrock API 密钥/令牌

export BASH_DEFAULT_TIMEOUT_MS=60000                  # 长时间运行 Bash 命令的默认超时时间（毫秒）
export BASH_MAX_TIMEOUT_MS=300000                     # 允许的长时间运行 Bash 命令的最大超时时间（毫秒）
export BASH_MAX_OUTPUT_LENGTH=20000                   # 在中间截断之前，Bash 输出的最大字符数

export CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # （0 或 1）每次执行完 Bash 命令后返回原始项目目录
export CLAUDE_BASH_NO_LOGIN=1                         # 设置为 1 时，BashTool 不使用登录 Shell。默认行为已在 v2.1.51 中更改（仅在回退时使用登录 Shell）。
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=600000       # 使用 apiKeyHelper 时刷新凭据的时间间隔（毫秒）
export CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1            # （0 或 1）跳过 IDE 扩展的自动安装
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096             # 大多数请求的最大输出标记数

export CLAUDE_CODE_USE_BEDROCK=1                      # （0 或 1）使用 Amazon Bedrock
export CLAUDE_CODE_USE_VERTEX=0                       # （0 或 1）使用 Google Vertex AI
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=0                # （0 或 1）跳过 Bedrock 的 AWS 身份验证（例如通过 LLM 网关）
export CLAUDE_CODE_SKIP_VERTEX_AUTH=0                 # （0 或 1）跳过 Vertex 的 Google 身份验证（例如通过 LLM 网关）

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=0     # （0 或 1）禁用非必要流量（等同于下方的 DISABLE_*）
export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=0           # （0 或 1）禁用终端标题的自动更新

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1         # （0 或 1）启用代理团队研究预览
export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 # （0 或 1）从 --add-dir 路径加载 CLAUDE.md
export CLAUDE_CODE_ENABLE_TASKS=false                 # 设置为“false”以禁用新的任务系统

export DISABLE_AUTOUPDATER=0                          # （0 或 1）禁用自动更新（覆盖 autoUpdates 设置）
export DISABLE_BUG_COMMAND=0                          # （0 或 1）禁用 /bug 命令
export DISABLE_COST_WARNINGS=0                        # （0 或 1）禁用成本警告消息
export DISABLE_ERROR_REPORTING=0                      # （0 或 1）退出 Sentry 错误报告
export DISABLE_NON_ESSENTIAL_MODEL_CALLS=0            # （0 或 1）禁用非关键路径的模型调用
export DISABLE_TELEMETRY=0                            # （0 或 1）退出 Statsig 遥测

export HTTP_PROXY="http://proxy:8080"                 # HTTP 代理服务器 URL
export HTTPS_PROXY="https://proxy:8443"               # HTTPS 代理服务器 URL

export MAX_THINKING_TOKENS=0                          # （0 或 1，用于关闭或开启）强制为模型设置思考预算
export MCP_TIMEOUT=120000                             # MCP 服务器启动超时时间（毫秒）
export MCP_TOOL_TIMEOUT=60000                         # MCP 工具执行超时时间（毫秒）
export MAX_MCP_OUTPUT_TOKENS=25000                    # MCP 工具响应中允许的最大标记数（默认 25000）

export USE_BUILTIN_RIPGREP=0                          # （0 或 1）设置为 0 以使用系统安装的 rg，而非捆绑版本

export VERTEX_REGION_CLAUDE_3_5_HAIKU="REGION"        # Vertex AI 上 Claude 3.5 Haiku 的区域覆盖（旧版模型家族名称）
export VERTEX_REGION_CLAUDE_3_5_SONNET="REGION"       # Vertex AI 上 Claude 3.5 Sonnet 的区域覆盖（旧版模型家族名称）
export VERTEX_REGION_CLAUDE_3_7_SONNET="REGION"       # Vertex AI 上 Claude 3.7 Sonnet 的区域覆盖（旧版模型家族名称）
# 注意：CLAUDE_3_5_* 和 CLAUDE_3_7_* 使用旧版模型家族名称，未来版本可能会更新。
export VERTEX_REGION_CLAUDE_4_0_OPUS="REGION"         # Vertex AI 上 Claude 4.0 Opus 的区域覆盖
export VERTEX_REGION_CLAUDE_4_0_SONNET="REGION"       # Vertex AI 上 Claude 4.0 Sonnet 的区域覆盖
export VERTEX_REGION_CLAUDE_4_1_OPUS="REGION"         # Vertex AI 上 Claude 4.1 Opus 的区域覆盖
export VERTEX_REGION_CLAUDE_4_6_OPUS="REGION"         # Vertex AI 上 Claude 4.6 Opus 的区域覆盖
export VERTEX_REGION_CLAUDE_4_6_SONNET="REGION"       # Vertex AI 上 Claude 4.6 Sonnet 的区域覆盖

# ── v2.1.32–2.1.63 版本新增功能 ──────────────────────────────────────────────────────
export CLAUDE_CODE_SIMPLE=1                            # 极简模式：禁用 MCP 工具、附件、钩子、CLAUDE.md 和技能
export CLAUDE_CODE_DISABLE_1M_CONTEXT=1                # 禁用 100 万 token 上下文窗口（使用默认较短上下文）
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # 完全禁用后台任务
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1        # 退出实验性测试功能
export CLAUDE_CODE_AUTO_CONNECT_IDE=false              # 禁用启动时自动连接 IDE
export CLAUDE_CODE_TMPDIR="/custom/tmp"                # 覆盖 Claude Code 使用的临时目录
export CLAUDE_CODE_SHELL="/bin/zsh"                    # 覆盖 shell 检测（强制指定特定 shell）
export CLAUDE_CODE_SHELL_PREFIX="command-wrapper"      # 为 Claude 运行的每个 shell 命令添加前缀/包装
export CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=50000   # 覆盖 Read 工具的最大输出 token 数
export CLAUDE_CODE_PROXY_RESOLVES_HOSTS=true           # 让 HTTP/HTTPS 代理处理 DNS 解析
export CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=30000         # 在空闲 N 毫秒后自动退出 SDK 模式
export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=30000         # 插件 git 操作的超时时间（毫秒）
export CLAUDE_CODE_ACCOUNT_UUID="uuid"                 # 覆盖账户 UUID（SDK / 自动化流程）
export CLAUDE_CODE_USER_EMAIL="user@example.com"       # 覆盖用户邮箱（SDK / 自动化流程）
export CLAUDE_CODE_ORGANIZATION_UUID="uuid"            # 覆盖组织 UUID（SDK / 自动化流程）
export ENABLE_CLAUDEAI_MCP_SERVERS=false               # 退出 claude.ai 同步的 MCP 服务器
export FORCE_AUTOUPDATE_PLUGINS=1                      # 允许插件自动更新，即使主更新程序已禁用
export IS_DEMO=1                                       # 演示模式 — 隐藏 UI 中的邮箱/组织信息
export NO_PROXY="localhost,127.0.0.1"                  # 对指定主机绕过代理（逗号分隔）

全局配置选项

claude config set -g theme dark                               # 主题：dark | light | light-daltonized | dark-daltonized
claude config set -g preferredNotifChannel iterm2_with_bell   # 通知通道：iterm2 | iterm2_with_bell | terminal_bell | notifications_disabled
claude config set -g autoUpdates true                         # 自动下载并安装更新（重启后生效）
claude config set -g verbose true                             # 显示完整的 bash/命令输出

claude config set -g attribution false                        # 在 git 提交/PR 中省略“co-authored-by Claude”
claude config set -g forceLoginMethod claudeai                 # 限制登录方式：claudeai | console
claude config set -g model "claude-sonnet-4-6-20260217"       # 默认模型覆盖
claude config set -g statusLine '{"type":"command","command":"~/.claude/statusline.sh"}'  # 自定义状态栏

claude config set -g enableAllProjectMcpServers true              # 自动批准 .mcp.json 中的所有 MCP 服务器
claude config set -g enabledMcpjsonServers '["memory","github"]'  # 批准特定的 MCP 服务器
claude config set -g disabledMcpjsonServers '["filesystem"]'      # 拒绝特定的 MCP 服务器

配置文件

（内存类型）Claude Code 提供四种按层级结构排列的内存位置，每种都有不同的用途：

所有内存文件在 Claude Code 启动时会自动加载到上下文中。层级较高的文件优先加载，作为更具体记忆的基础。

.claude/rules/ 目录（v2.0.64+）

.claude/rules/ 目录允许您将项目说明拆分为多个独立的 Markdown 文件，而不是使用一个大型的 CLAUDE.md 文件。该目录下的每个 *.md 文件都会自动与 CLAUDE.md 一同加载到上下文中。这非常有用：

• 模块化组织：分离不同关注点（例如 api-conventions.md、testing-rules.md）
• 按目录覆盖：嵌套的 rules/ 目录可以应用作用域限定的规则
• 团队协作：不同团队成员可以通过 PR 审查分别负责不同的规则文件

自动内存（v2.1.32+）

Claude 现在会在您的会话过程中自动将有用上下文保存到记忆中。这些管理的记忆包括项目规范、工具偏好以及 Claude 在与您协作时观察到的架构决策等。您可以使用 /memory 命令来查看和管理自动保存的记忆。

命令与用法

斜杠命令参考

命令行标志

--output-format json 标志对于脚本编写和自动化特别有用，允许你以编程方式解析 Claude 的响应。

CLI 快速参考与配置示例

## Claude 备忘录

# 基础 / 交互式

claude # 启动交互式 REPL
claude "解释这个项目" # 启动带有提示的 REPL
claude -p "总结 README.md" # 非交互式打印模式（基于 SDK）
cat logs.txt | claude -p "解释" # 将输入通过管道传递给 Claude 并退出
claude -c # 继续最近的对话（--continue 的别名）
claude -r "<session-id>" "完成这个" # 通过 ID 恢复特定会话（--resume 的别名）
claude --model claude-sonnet-4-6-20260217 # 为本次运行选择模型
claude --max-turns 3 -p "检查代码" # 在打印模式下限制代理式轮次
claude --replay-user-messages # 将用户消息回放至标准输出，用于调试或 SDK 工作流

# 更新与安装

claude update # 手动更新 Claude Code
claude doctor # 诊断安装/版本及设置
claude install # 启动原生二进制安装程序（测试版）
claude migrate-installer # 从全局 npm 安装迁移到本地安装程序

# 身份验证（v2.1.41+）

claude auth login # 登录你的 Anthropic 账户
claude auth status # 检查身份验证状态
claude auth logout # 注销

# 代理管理（v2.1.50+）

claude agents # 列出所有已配置的代理（项目、用户、插件）
claude remote-control # 启动远程控制模式，用于外部工具

# 配置：交互式向导 + 直接操作

claude config # 交互式配置向导
claude config get <key> # 获取值（例如，claude config get theme）
claude config set <key> <val> # 设置值（例如，claude config set theme dark）
claude config add <key> <vals…> # 向数组类型键追加值（例如，claude config add env DEV=1）
claude config remove <key> <vals…> # 从列表类型键中移除条目
claude config list # 显示当前项目的全部设置（默认为项目范围）

# 示例项目范围设置

claude config set model "claude-sonnet-4-6-20260217" # 覆盖该项目的默认模型
claude config set attribution false # 禁用 git/PR 中的“由 Claude 共同创作”署名
claude config set forceLoginMethod claudeai # 限制登录流程：claudeai | console
claude config set enableAllProjectMcpServers true # 自动批准 .mcp.json 中的所有 MCP 服务器
claude config set defaultMode "acceptEdits" # 设置默认权限模式
claude config set disableBypassPermissionsMode disable # 阻止绕过权限模式（示例键）

# 管理列表设置（项目范围）

claude config add enabledMcpjsonServers github # 批准 .mcp.json 中的特定 MCP 服务器
claude config add enabledMcpjsonServers memory # 再添加一个
claude config remove enabledMcpjsonServers memory # 移除一条记录
claude config add disabledMcpjsonServers filesystem # 明确拒绝特定 MCP 服务器

# 全局范围（使用 -g 或 --global）

claude config set -g autoUpdates false # 关闭全局自动更新
claude config set --global preferredNotifChannel iterm2_with_bell
claude config set -g theme dark # 主题：dark | light | light-daltonized | dark-daltonized
claude config set -g verbose true # 在所有地方显示完整的 bash/命令输出
claude config get -g theme # 确认全局值

# MCP（模型上下文协议）管理

claude mcp # 启动 MCP 向导 / 配置 MCP 服务器
claude mcp list # 列出已配置的 MCP 服务器
claude mcp get <name> # 显示某服务器的详细信息
claude mcp remove <name> # 移除服务器
claude mcp add <name> <command> [args...] # 添加本地 stdio 服务器
claude mcp add --transport sse <name> <url> # 添加远程 SSE 服务器
claude mcp add --transport http <name> <url> # 添加远程 HTTP 服务器
claude mcp add <name> --env KEY=VALUE -- <cmd> [args...] # 将环境变量传递给服务器命令
claude mcp add --transport sse private-api https://api.example/mcp \
 --header "Authorization: Bearer TOKEN" # 添加带认证头的服务器
claude mcp add-json <name> '<json>' # 通过 JSON 数据块添加服务器
claude mcp add-from-claude-desktop # 从 Claude Desktop 导入服务器
claude mcp reset-project-choices # 重置对项目 .mcp.json 服务器的批准
claude mcp serve # 运行 Claude Code 本身作为 MCP stdio 服务器

# 其他实用标志（打印 / SDK 模式）

claude --add-dir ../apps ../lib # 添加额外的工作目录
claude --allowedTools "Bash(git log:\*)" "Read" # 允许列出的工具无需权限提示
claude --disallowedTools "Edit" # 禁止列出的工具无需权限提示
claude --append-system-prompt "自定义指令" # 向系统提示追加内容（仅限 -p 使用）
claude -p "查询" --output-format json --input-format stream-json # 控制脚本编写的 IO 格式
claude --verbose # 详细日志记录（逐步）
claude --dangerously-skip-permissions # 跳过权限提示（谨慎使用）
claude --permission-mode plan # 以计划模式启动（只读分析）
claude --max-turns 3 -p "查询" # 限制代理式轮次（仅限打印模式）
claude --max-budget-usd 5.00 -p "查询" # 限制每次会话的支出（仅限打印模式）
claude --json-schema '{"type":"object"}' -p "查询" # 获取经过验证的 JSON 输出
claude --chrome # 启用 Chrome 浏览器集成
claude --remote "修复这个 bug" # 在 claude.ai 上创建网络会话
claude --teleport # 在本地恢复网络会话
claude --agents '{"name":{...}}' # 通过 JSON 定义子代理

# 会话管理

claude -c # 继续最近的对话
claude -r "会话名称" # 按名称或 ID 恢复
claude --fork-session -r abc123 # 分叉而非重复使用原始会话
claude -w "实现功能" # 在隔离的 git 工作树中开始
/rename auth-refactor # 为当前会话命名
/resume # 打开会话选择器
/export output.md # 将对话导出到文件
/fork # 分叉当前对话

# 快速验证 / 注意事项

# - 默认情况下，'claude config' 的作用范围是项目；使用 -g/--global 可影响所有项目。

# - 设置优先级：企业 > CLI 参数 > 本地项目 > 共享项目 > 用户 (~/.claude)。

# - 仅在列表类型键上使用 'add' / 'remove'（例如，enabledMcpjsonServers）。

# - CLI 参考和发布说明是关于标志及最新功能的权威来源。

界面与输入

键盘快捷键

文本编辑

多行输入

快速命令

[!Tip] PDF 页面范围： 使用 Read 工具时，可以通过 pages 参数指定 PDF 的页面范围（例如，pages: "1-5"）。超过 10 页的大 PDF 在被 @ 提及时不会内联显示，而是返回一个轻量级引用。

Vim 模式

[!Note] 可以通过 /vim 命令启用 Vim 风格的编辑，或者通过 /config 永久配置。

Vim 模式切换

Vim 导航

Vim 编辑

[!Tip] 在终端设置中配置你喜欢的换行行为。运行 /terminal-setup 可以为 iTerm2、VS Code、Kitty、Alacritty、Zed、Warp 和 WezTerm 安装 Shift+Enter 绑定。

命令历史

Claude Code 会为当前会话保存命令历史：

* 历史按工作目录存储
* 可通过 `/clear` 命令清空
* 使用上/下箭头导航（参见上述键盘快捷键）
* **Ctrl+R**：反向搜索历史（如果终端支持）
* **注意**：默认情况下，历史展开功能（`!`）已被禁用

高级功能

思考关键词

[!Note] 通过在提示中加入以下关键词之一，可为 Claude 提供额外的预答准备时间。 按消耗令牌数量由低到高排序

think -------------> 最低 think hard think harder ultrathink --------> 最高

这会让 Claude 花更多时间：

1. 规划解决方案

2. 分解步骤

3. 权衡替代方案/取舍

4. 检查约束条件与边界情况

   更高的级别通常会增加延迟和令牌使用量，请选择能工作的最小级别。

示例

# 小幅提升

claude -p "思考。概述一个重构认证模块的计划。"

# 中度提升

claude -p "更深入地思考。起草一个从 REST 迁移到 gRPC 的迁移计划。"

# 最大提升

claude -p "超深度思考。提出一个逐步解决支付测试不稳定问题并添加防护机制的策略。"

快速模式

[!注意] 快速模式为 Opus 4.6 提供加速响应时间，专为快速迭代和简单任务优化。

如何启用快速模式：

# 在 REPL 中启用快速模式（需先启用额外使用权限）
/extra-usage
/fast

# 或在对话过程中切换
# 状态栏会显示快速模式是否已激活

主要特性：

• 更快的响应 - 缩短简单任务的延迟
• 适用于 Opus 4.6 - 新增于版本 2.1.36
• 需要额外使用权限 - 必须先启用 /extra-usage

何时使用快速模式：

• 快速代码审查和编辑
• 快速原型开发
• 简单的问题和命令
• 迭代式调试

快速模式以牺牲部分深度为代价换取速度。对于复杂分析和规划任务，请使用正常模式。

计划模式

[!注意] 计划模式指示 Claude 以只读方式分析代码库，非常适合探索代码库、规划复杂变更或安全地审查代码。

何时使用计划模式：

• 多步骤实现：当您的功能需要修改多个文件时
• 代码探索：当您希望在进行任何更改之前彻底研究代码库时
• 交互式开发：当您希望与 Claude 一起迭代开发方向时

如何启用计划模式：

# 以计划模式开始新会话
claude --permission-mode plan

# 或在会话中通过 Shift+Tab 切换
# （循环顺序：正常 → 自动接受 → 计划模式）

# 从提示符进入计划模式
/plan

# 在计划模式下运行无头查询
claude --permission-mode plan -p "分析认证系统并提出改进建议"

将计划模式设置为默认：

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

后台任务

[!注意] Claude Code 支持在后台运行 bash 命令，让您可以在长时间运行的进程执行时继续工作。

如何使用后台任务：

主要特性：

• 输出会被缓冲，Claude 可以使用 TaskOutput 工具检索输出
• 后台任务具有唯一 ID，便于跟踪和获取输出
• 当 Claude Code 退出时，后台任务会自动清理
• 使用 /tasks 可以列出和管理后台任务

常见的后台命令：

• 构建工具（webpack、vite、make）
• 包管理器（npm、yarn、pnpm）
• 测试运行器（jest、pytest）
• 开发服务器
• 长时间运行的进程（docker、terraform）

带有 ! 前缀的 Bash 模式：

# 直接运行 bash 命令，无需 Claude 解释
! npm test
! git status
! ls -la

禁用后台任务：

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

远程会话

[!注意] 订阅用户可使用 --remote 在 claude.ai 上启动任务，并使用 --teleport 在本地恢复这些任务。

启动远程会话：

# 在 claude.ai 上创建包含任务描述的新 Web 会话
claude --remote "修复登录错误"

恢复远程会话：

# 在本地终端恢复 Web 会话
claude --teleport

# 或者使用斜杠命令
/teleport

Claude 在 Chrome 中

Claude Code 可以控制 Google Chrome 浏览器，用于执行基于浏览器的任务，例如测试、网页抓取和 UI 验证。

设置：

claude --chrome                    # 启动时集成 Chrome

功能：

• 导航到 URL、点击页面元素、填写表单
• 截取屏幕截图并分析页面内容
• 在浏览器上下文中执行 JavaScript
• 与 Web 应用程序交互以进行测试

[!注意] 需要安装 Google Chrome。Claude 使用 Chrome DevTools 协议来控制浏览器。

沙盒模式

沙盒模式会将 BashTool 限制在一个隔离的环境中运行命令，从而防止对您实际文件系统的任何修改。

/sandbox              # 切换沙盒模式的开启或关闭

在沙盒模式下：

• 文件系统写操作被限制在沙盒内
• 网络访问可能会受到限制
• 适合安全地测试破坏性命令

该功能适用于 Linux 和 macOS。您可以使用 claude --sandbox 来以沙盒模式启动。

LSP 工具（语言服务器协议）

Claude Code 集成了语言服务器，提供 IDE 级别的代码智能：

• 转到定义 — 跳转到符号的定义处
• 查找引用 — 查找整个代码库中某个符号的所有用法
• 悬停信息 — 获取类型信息和文档

当当前项目有兼容的语言服务器可用时，LSP 工具会自动激活。这使得 Claude 能够比仅通过文本搜索更精确地导航代码库。

当工具结果超过 50,000 字符时，会自动持久化到磁盘，以便高效管理上下文。

子代理

子代理是专门构建的帮助程序，它们拥有各自的提示词、工具和独立的上下文窗口。您可以将其视为一种“专家混合体”，根据每个仓库的需求进行组合。

内置子代理

Claude Code 包含一些内置子代理，Claude 会在适当的时候自动使用它们：

当 Claude 需要搜索或理解代码库而无需进行更改时，它会委托给 Explore 子代理，这样探索的结果就不会进入您的主要对话上下文中。

何时使用子代理：

• 您需要高信号响应（计划、评审、差异），而不需要额外的支线任务。
• 您希望提示词和工具策略能够与代码库一起版本化。
• 您在以 PR 为主导的团队中工作，并希望按角色进行范围限定的编辑。
• 任务会产生大量输出，而这些输出并不需要保留在您的主要上下文中。

每个子代理都有自己的上下文

为您的代理阵容设计规则

• 为每个代理定义一个明确的责任。
• 保留该角色所需的最少工具集。
• 对于分析/评审任务，优先选择只读代理。
• 尽可能减少具有编辑权限的代理数量。

图注：终端中的代理选择界面。

配置代理

将代理保存在项目中，这样它们就能随仓库一起版本化，并通过 PR 不断演进。

快速入门

更新 CLI 并打开代理面板

claude update
/agents

子代理的作用范围

通过 CLI 定义代理

# 通过 JSON 动态定义自定义子代理
claude --agents '{
  "code-reviewer": {
    "description": "专业代码评审员。在代码变更后主动使用。",
    "prompt": "你是一位资深代码评审员。专注于代码质量、安全性及最佳实践。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "专门处理错误和测试失败的调试专家。",
    "prompt": "你是一位经验丰富的调试专家。分析错误、找出根本原因并提供修复方案。"
  },
  "background-impl": {
    "description": "在后台的隔离工作树中实现功能。",
    "prompt": "实现请求的功能。完成后提交更改。",
    "isolation": "worktree",
    "background": true
  }
}'

创建您的核心代理

• planner（只读）：将功能/问题分解为可测试的小任务；输出任务列表或 plan.md。
• codegen（可编辑）：负责实现任务；仅限于 src/ 和 tests/。
• tester（只读或仅限补丁）：编写一条失败的测试用例或最小的复现代码。
• reviewer（只读）：留下结构化的评审意见；从不编辑。
• docs（可编辑）：仅更新 README.md 或 docs/。

*政策 提示：对于可编辑的代理，最好采用补丁输出的方式，这样更改可以通过您正常的 Git 工作流程落地。*

图注：仅为代理分配其真正需要的工具（例如，咨询权限 vs 编辑权限）。

示例提示词

提示词应简短、可测试且针对特定仓库。请将其提交到 agents/ 目录中：

图注：一个用于“测试覆盖率分析”代理的示例提示词。

tester.prompt.md（样本）

角色：为我描述的具体场景编写一条专注的失败测试用例。
范围：仅在 tests/ 目录下创建或修改测试文件，不得更改 src/。
输出：简短的理由说明 + 统一的差异或补丁。
如果场景不明确，请提出一个明确的问题。

预期输出

您的测试代理应生成一个小的差异或补丁，以及一段简短的理由说明：

图注：来自“测试覆盖率分析”代理的示例回复。

子代理 Frontmatter 字段

子代理文件使用 YAML frontmatter 进行配置：

---
name: code-reviewer
description: 审查代码的质量和最佳实践
tools: Read, Glob, Grep
disallowedTools: Write, Edit
model: sonnet
permissionMode: default
skills:
  - api-conventions
---

你是一名代码审查员。请分析代码并提供反馈。

为什么这一转变很重要

运营优势

• 减少上下文切换： 你只需保持一种思维模式；其余工作由代理完成。
• 更干净的 PR： 精准的提示 + 有限的工具 → 更小、更易审查的差异。
• 更少的回归问题： 测试员/审查员代理会在合并前发现漏洞。
• 可重复性： 提示和策略存储在仓库中，并随分支一起传播。

安全与治理

• 限制按路径的写入权限（例如，src/、tests/、docs/）。
• 对高风险区域优先采用只读分析。
• 将助手输出记录为补丁并提交，以提高可审计性。

思维方式的转变

应该做

• 将代理视为具有明确职责的团队成员。
• 先从只读开始；最后再授予写入权限。
• 将提示保存在版本控制系统中，并通过 PR 不断迭代。

不要做

• 不要要求一个代理在一轮中同时完成计划、编码和测试。
• 不要给予全面的写入权限。
• 如果你只要求一个测试，就不要接受包含多份文件的差异。

代理团队（研究预览）

[!注意] 代理团队是一项实验性功能，允许多个 Claude 实例在共享代码库上自主并行工作。

启用代理团队：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

关键概念：

• 多个 Claude 实例在同一代码库上并行运行
• 每个代理可以专注于不同的任务（调试、文档编写、测试等）
• 代理之间通过基于 Git 的同步机制进行沟通
• 支持自主、长期的开发工作流

案例研究：由代理团队构建的 C 编译器

Anthropic 的研究团队通过指派 16 个并行的 Claude 实例从零开始构建 C 编译器，展示了代理团队的能力。主要成果如下：

关于代理团队的经验教训：

1. 编写高质量的测试 - 任务验证者必须几乎完美
2. 面向并行性设计 - 代理应能独立工作，互不阻塞
3. 专业化分工 - 将代理分配到特定角色（代码质量、文档编写、性能优化等）
4. 维护上下文文件 - 及时更新 README 和进度文件，以便代理快速定位

阅读完整案例：用并行 Claude 构建 C 编译器

技能（自定义斜杠命令）

[!注意] 技能扩展了 Claude 的功能。创建一个包含说明的 SKILL.md 文件，Claude 会将其加入自己的工具箱。Claude 会在适当的时候使用这些技能，或者你可以直接通过 /技能名 调用它们。

技能的位置

项目级别的技能会覆盖同名的个人技能。位于 .claude/commands/ 的文件仍然有效，并支持相同的 frontmatter。

创建技能

# 创建技能目录
mkdir -p ~/.claude/skills/explain-code

创建 ~/.claude/skills/explain-code/SKILL.md：

---
name: explain-code
description: 用可视化图表和类比解释代码。用于解释代码的工作原理。
---

解释代码时，务必包括以下内容：

1. **从类比入手**：将代码与日常生活中的事物进行对比
2. **绘制图表**：使用 ASCII 艺术展示流程、结构或关系
3. **逐行解释代码**：一步一步说明代码的执行过程
4. **指出常见陷阱**：有哪些常见的错误或误解？

使用该技能：

# 让 Claude 自动调用
这段代码是如何工作的？

# 或直接调用
/explain-code src/auth/login.ts

技能 Frontmatter 字段

向技能传递参数

使用 $ARGUMENTS 占位符接收参数：

---
name: fix-issue
description: 修复 GitHub 问题
disable-model-invocation: true
---

按照我们的编码规范修复 GitHub 问题 $ARGUMENTS。

1. 阅读问题描述
2. 实现修复
3. 编写测试
4. 创建提交

使用方法： /fix-issue 123

注入动态上下文

使用 !`command` 语法在技能内容发送给 Claude 之前运行 Shell 命令：

---
name: pr-summary
description: 总结拉取请求中的更改
context: fork
agent: Explore
---

## 拉取请求上下文

- PR 差异：!`gh pr diff`
- PR 评论：!`gh pr view --comments`
- 更改文件：!`gh pr diff --name-only`

## 你的任务

总结这个拉取请求...

在子代理中运行技能

添加 context: fork 可使技能在隔离环境中运行：

---
name: deep-research
description: 深入研究某个主题
context: fork
agent: Explore
---

深入研究 $ARGUMENTS：

1. 使用 Glob 和 Grep 查找相关文件
2. 阅读并分析代码
3. 总结发现，并附上具体的文件引用

agent 字段可以是 Explore、Plan、general-purpose，或来自 .claude/agents/ 的任何自定义子代理。

插件系统

[!Note] 插件通过自定义命令、技能、代理、钩子以及 MCP 服务器扩展 Claude Code。插件可以从本地目录、Git 仓库或 npm 注册表加载。

关键命令：

# 从 Git 仓库安装插件
/plugins install https://github.com/org/claude-plugin-example

# 从 npm 注册表安装
/plugins install @org/claude-code-plugin

# 列出已安装的插件
/plugins list

# 启用或禁用插件
/plugins enable <plugin-name>
/plugins disable <plugin-name>

# 验证插件结构
/plugins validate ./my-plugin

# 浏览插件市场（社区插件）
/plugins marketplace

插件结构：

my-plugin/
├── plugin.json          # 插件清单（名称、版本、描述）
├── agents/              # 自定义代理 (*.md frontmatter 文件)
├── skills/              # 自定义技能 (SKILL.md 文件)
├── hooks/               # 钩子脚本
├── commands/            # 自定义斜杠命令
└── mcp-servers/         # MCP 服务器配置

插件作用域：

插件清单 (plugin.json)：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "一个 Claude Code 插件",
  "agents": ["agents/"],
  "skills": ["skills/"],
  "hooks": "hooks/hooks.json",
  "mcpServers": "mcp-servers/servers.json"
}

插件默认自动更新。设置 FORCE_AUTOUPDATE_PLUGINS=1 可强制更新，即使主更新程序被禁用；也可通过 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 覆盖慢速仓库的更新。

工作树隔离（v2.1.49+）

[!Note] --worktree (-w) 标志可在隔离的 Git 工作树中启动 Claude，使其能够在独立分支中进行更改，而不会影响您的工作目录。

使用方法：

# 在隔离的工作树中启动 Claude
claude -w "implement the new feature"

# Claude 将执行以下操作：
# 1. 从您当前分支创建一个临时 Git 工作树
# 2. 在该隔离的工作树中运行
# 3. 提交更改，并可选择创建拉取请求
# 4. 完成后清理工作树

代理级别的工作树隔离：

---
name: background-coder
description: 在隔离环境中实现功能
isolation: worktree
background: true
---

在此隔离的工作树中实现请求的功能。

工作树隔离与 background: true 结合使用时尤为强大，可支持多代理同时在不同功能上并行开发的工作流。

原生安装程序（v2.1.15+）

[!Note] Claude Code 现提供原生二进制安装程序，作为 npm 全局安装的替代方案。原生安装程序启动更快、可自动更新，且无需在 PATH 中配置 Node.js。

# 启动原生安装程序（交互式）
claude install

# 从 npm 全局安装迁移到原生安装程序
claude migrate-installer

# 自 v2.1.41 起，Windows ARM64 已获得原生支持

npm 安装方式（npm install -g @anthropic-ai/claude-code）仍然有效。虽然自 v2.1.15 起已开始逐步淘汰基于 npm 的安装方式，但两种方法目前仍可并存。

认证 CLI（v2.1.41+）

[!Note] 无需进入 REPL，即可直接通过 CLI 管理认证。

# 登录 Anthropic 账户
claude auth login

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

# 注销
claude auth logout

代理管理 CLI（v2.1.50+）

[!Note] 可通过命令行列出并检查所有已配置的代理。

# 列出所有代理
claude agents list

# 查看特定代理的详细信息
claude agent inspect <agent-name>

此外，还可以通过 CLI 启动、停止或重启代理，从而实现更高效的管理流程。

列出所有代理（项目、用户、插件、CLI 定义）

claude agents

---

<h2 id="remote-control">远程控制（v2.1.51+）</h2>

> [!注意]
> **`claude remote-control` 子命令允许外部工具和构建系统以编程方式驱动 Claude Code。**

```bash
# 以远程控制模式启动 Claude
claude remote-control

这对于希望通过其 SDK 接口与 Claude Code 交互的 IDE 扩展、CI/CD 流水线或自定义编排工具非常有用。

托管设置（v2.1.51+）

[!注意] 企业管理员可以通过 macOS 的 plist 或 Windows 的注册表推送托管设置，从而实现组织范围内的配置控制。

macOS（plist）：

可通过 MDM 配置文件将设置部署到 /Library/Managed Preferences/com.anthropic.claude-code.plist。

Windows（注册表）：

可通过组策略将设置部署到 HKLM\SOFTWARE\Policies\Anthropic\ClaudeCode。

托管设置优先于用户/项目设置，且不能被单个用户覆盖。

模型更新

Claude Sonnet 4.6（2026年2月17日）

[!注意] Claude Sonnet 4.6 在 Sonnet 定价下实现了前沿级别的性能（每百万 tokens 3美元/15美元），并拥有 100 万 tokens 的上下文窗口。

主要亮点：

• 在编码、推理和智能体规划任务上接近 Opus 级别性能
• 100 万 tokens 上下文窗口（此前仅在 Max 计划的 Sonnet 4.5 中可用）
• 改进的编码基准测试：在 SWE-bench、智能体式编码和多文件重构方面有显著提升
• 更好的长上下文推理能力：在“大海捞针”和长文档任务中的准确性有所提高
• 增强的计算机使用能力：更可靠的浏览器自动化和 GUI 交互
• 与 Sonnet 4.5 相同的价格：每百万 tokens 输入 3 美元 / 输出 15 美元

在 Claude Code 中的使用方法：

# 设置为默认模型
claude --model sonnet

# 或者固定使用特定版本
claude --model claude-sonnet-4-6-20260217

# 在设置中配置
claude config set model "claude-sonnet-4-6-20260217"

具有 1M 上下文的 Sonnet 4.5 已从 Max 计划中移除，取而代之的是 Sonnet 4.6。Claude Opus 4.6（在 v2.1.32 中发布）仍然适用于最苛刻的任务。

Claude Code Insights

[!注意] /insights 命令会生成一份交互式 HTML 报告，分析您过去 30 天的编码习惯。

运行 Insights：

# 在 Claude Code 终端中
/insights

# 打开生成的报告
start ~/.claude/usage-data/report.html     # Windows
open ~/.claude/usage-data/report.html      # Mac
xdg-open ~/.claude/usage-data/report.html  # Linux

工作原理：

1. 会话收集 - 从 ~/.claude/projects/ 中提取会话日志，过滤掉智能体子会话和短会话
2. 元数据提取 - 提取持续时间、token 使用量、使用的工具、检测到的语言以及 Git 活动
3. 特征提取 - 使用 Haiku 模型分析对话记录，识别目标、满意度信号和摩擦点
4. 报告生成 - 创建包含个性化建议的交互式 HTML 报告

报告各部分：

所有处理都在本地使用 Anthropic API 进行。会话数据始终保存在您的设备上。

MCP 集成

理解 MCP（模型上下文协议）

什么是 MCP？

MCP 通过连接外部服务、数据库、API 和工具（文件系统、Puppeteer、GitHub、Context7 等）来扩展 Claude 的功能。

MCP 架构：

Claude Code ←→ MCP 协议 ←→ MCP 服务器 ←→ 外部服务

claude.ai 的 MCP 连接器

Claude Code 可以使用您 claude.ai 账户中配置的 MCP 服务器，从而将云端托管的工具引入您的 CLI 工作流。

# 默认启用 — 如需禁用：
export ENABLE_CLAUDEAI_MCP_SERVERS=false

这使您能够直接从命令行访问 claude.ai 中提供的相同 MCP 工具集成，而无需进行本地 MCP 服务器配置。

MCP 设置与配置

基本 MCP 命令

claude mcp                   # 交互式 MCP 配置
claude mcp list              # 列出已配置的服务器
claude mcp add <name> <cmd>  # 添加新服务器
claude mcp remove <name>     # 移除服务器

MCP 配置文件位置

~/.claude.json      # 全局文件
`.mcp.json`         # 项目范围内的服务器存储在项目根目录下的文件中

快速入门

如果您赶时间，这是最快的方法：

# 添加文件系统访问权限（最常用）
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Desktop

# 验证是否成功
claude mcp list

如果一切正常，您将看到如下响应：

其他方法：

# 基本语法
claude mcp add <名称> <命令> [参数...]

# 实际示例：添加本地文件系统访问权限
claude mcp add my-filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# 使用环境变量的示例
claude mcp add api-server -e API_KEY=your-key-here -- /path/to/server

# 添加带有预配置 OAuth 凭证的 MCP 服务器
claude mcp add <名称> --client-id <id> --client-secret <secret> -- <命令>

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents"
      ],
      "env": {}
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

# 添加项目级 MCP 服务器
claude mcp add shared-tools -s project -- npx -y @your-team/mcp-tools

{
  "mcpServers": {
    "shared-tools": {
      "command": "npx",
      "args": ["-y", "@your-team/mcp-tools"],
      "env": {}
    }
  }
}

MCP 服务器作用域详解

理解作用域对于避免“未找到服务器”错误至关重要：

1. 本地作用域（默认）

• 仅在当前目录中可用
• 配置存储在 ~/.claude.json 的 projects 部分
• 适用场景：个人项目专用工具

2. 用户作用域（全局）

• 在所有项目中均可使用
• 使用 -s user 标志添加
• 适用场景：文件系统、数据库客户端等常用工具

3. 项目作用域（团队共享）

• 通过 .mcp.json 文件共享
• 使用 -s project 标志添加
• 适用场景：团队共享的项目专用工具

实用 MCP 服务器推荐

以下是值得安装的最有价值的 MCP 服务器列表：

1. 文件系统访问

claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects ~/Desktop

用途：让 Claude 直接读写文件、修改代码。

2. GitHub 集成

claude mcp add github -s user -e GITHUB_TOKEN=your-token -- npx -y @modelcontextprotocol/server-github

用途：管理问题、PR 和代码评审。

3. 网页浏览器控制

claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteer

用途：自动化网页操作、爬取和测试。

4. 数据库连接（PostgreSQL）

claude mcp add postgres -s user -e DATABASE_URL=your-db-url -- npx -y @modelcontextprotocol/server-postgres

用途：直接查询和操作数据库。

5. Fetch 工具（API 调用）

claude mcp add fetch -s user -- npx -y @kazuph/mcp-fetch

用途：调用各种 REST API。

6. 搜索引擎

claude mcp add search -s user -e BRAVE_API_KEY=your-key -- npx -y @modelcontextprotocol/server-brave-search

用途：搜索最新信息。

7. Slack 集成

claude mcp add slack -s user -e SLACK_TOKEN=your-token -- npx -y @modelcontextprotocol/server-slack

用途：发送消息、管理频道。

8. 时间管理

claude mcp add time -s user -- npx -y @modelcontextprotocol/server-time

用途：时区转换、日期计算。

9. 内存存储

claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory

用途：跨对话保存信息。

10. 顺序思维（思维链）

claude mcp add thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking

用途：针对复杂问题进行逐步思考。

常见错误及解决方案

错误 1：工具名称验证失败

API Error 400: "tools.11.custom.name: 字符串应匹配模式 '^[a-zA-Z0-9_-]{1,64}$'"

解决方案：

• 确保服务器名称仅包含字母、数字、下划线和短横线。
• 名称长度不得超过 64 个字符。
• 不要使用特殊字符或空格。

错误 2：未找到 MCP 服务器

MCP 服务器 'my-server' 未找到

解决方案：

1. 检查作用域设置是否正确。
2. 运行 claude mcp list 确认服务器已添加。
3. 确保您位于正确的目录中（对于本地作用域）。
4. 重启 Claude Code。

错误 3：协议版本错误

"protocolVersion": "必需"

解决方案：这是 Claude Code 中的一个已知 bug，临时解决方法如下：

1. 使用包装脚本。
2. 确保 MCP 服务器返回正确的协议版本。
3. 更新到最新版本的 Claude Code。

错误 4：Windows 路径问题

错误：无法找到模块 'C:UsersusernameDocuments'

解决方案：Windows 路径需要使用正斜杠或双反斜杠：

# 错误
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Documents

# 正确
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/username/Documents
# 或
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\\Users\\username\\Documents

错误 5：权限问题

权限被拒绝

解决方案：

1. macOS/Linux：使用 sudo（不推荐）或修改文件权限。
2. Windows：以管理员身份运行。
3. 最佳方法：将 MCP 服务器安装在用户目录中。

调试技巧

遇到问题时，以下调试方法可以帮助您快速定位问题：

1. 启用调试模式

claude --debug

2. 查看 MCP 状态

在 Claude Code 中输入：

/mcp

3. 查看日志文件

macOS/Linux：

tail -f ~/Library/Logs/Claude/mcp*.log

Windows：

type "%APPDATA%\Claude\logs\mcp*.log"

4. 手动测试服务器

# 直接运行服务器命令，查看是否有输出
npx -y @modelcontextprotocol/server-filesystem ~/Documents

国际用户特别提示

1. 非英文路径问题

避免在路径中使用非英文字符：

# 避免
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/文档

# 推荐
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

2. 代理配置

如果您正在使用代理：

# 设置 npm 代理
npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port

# 然后添加 MCP 服务器
claude mcp add ...

3. 镜像源

使用镜像源加速下载：

# 临时使用
claude mcp add fs -- npx -y --registry=https://registry.npmjs.org @modelcontextprotocol/server-filesystem ~/Documents

# 或永久设置
npm config set registry https://registry.npmjs.org

最佳实践建议

1. 按需添加：不要一次性添加过多的 MCP 服务器，这会影响性能。
2. 定期清理：使用 claude mcp remove <name> 删除未使用的服务器。
3. 安全第一：仅添加受信任的 MCP 服务器，尤其是需要网络访问权限的服务器。
4. 备份配置：定期备份 ~/.claude.json 文件。
5. 团队协作：使用项目范围共享常用配置。

高级技巧

1. 创建自定义 MCP 服务器

如果现有的 MCP 服务器无法满足您的需求，您可以创建自己的：

// my-mcp-server.js
import { Server } from "@modelcontextprotocol/sdk";

const server = new Server({
  name: "my-custom-server",
  version: "1.0.0",
});

server.setRequestHandler("tools/list", async () => {
  return {
    tools: [
      {
        name: "my_custom_tool",
        description: "自定义工具",
        inputSchema: {
          type: "object",
          properties: {
            input: { type: "string" },
          },
        },
      },
    ],
  };
});

server.start();

2. 批量配置脚本

创建一个脚本来一次性配置所有常用的 MCP 服务器：

#!/bin/bash
# setup-mcp.sh

echo "配置常用 MCP 服务器..."

# 文件系统
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects

# GitHub
read -p "请输入 GitHub Token: " github_token
claude mcp add github -s user -e GITHUB_TOKEN=$github_token -- npx -y @modelcontextprotocol/server-github

# 其他服务器...

echo "MCP 服务器配置成功！"

流行的 MCP 服务器

开发工具

# npm install -g git-mcp-server

# claude mcp add git "git-mcp-server"
# claude mcp add github "github-mcp-server --token $GITHUB_TOKEN"

数据库集成

npm install -g postgres-mcp-server
npm install -g mysql-mcp-server
npm install -g sqlite-mcp-server

# 设置示例可能如下：
# export POSTGRES_URL="postgresql://user:password@localhost:5432/mydb"
# claude mcp add postgres "postgres-mcp-server --url $POSTGRES_URL"

MCP 工具权限

# 允许特定的 MCP 工具
claude --allowedTools "mcp__git__commit,mcp__git__push"

# 允许来自特定服务器的所有工具
claude --allowedTools "mcp__postgres__*"

# 结合内置工具
claude --allowedTools "Edit,View,mcp__git__*"

钩子系统

本页面提供在 Claude Code 中实现钩子的参考文档。

[!TIP] 如需包含示例的快速入门指南，请参阅开始使用 Claude Code 钩子。

配置

Claude Code 的钩子在您的设置文件中进行配置：

• ~/.claude/settings.json - 用户设置
• .claude/settings.json - 项目设置
• .claude/settings.local.json - 本地项目设置（不提交）
• 企业托管策略设置

结构

钩子按匹配器组织，每个匹配器可以有多个钩子：

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

HTTP 钩子（v2.1.63+）

除了 shell 命令之外，钩子还可以将 JSON 发送到 URL 并接收 JSON 响应：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.example.com/validate",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

HTTP 钩子会将与 command 钩子通过 stdin 接收的相同 JSON 负载作为 POST 请求体发送。响应 JSON 遵循相同的输出模式。这对于集中式策略执行或无需本地脚本的远程钩子执行非常有用。

• matcher：用于匹配工具名称的模式，区分大小写（仅适用于 PreToolUse 和 PostToolUse）。
  • 简单字符串精确匹配：Write 只匹配 Write 工具。
  • 支持正则表达式：Edit|Write 或 Notebook.*。
  • 使用 * 匹配所有工具。您也可以使用空字符串 ("") 或留空 matcher。
• hooks：当模式匹配时要执行的命令数组。
  • type："command"（shell 命令）或 "http"（POST JSON 到 URL，v2.1.63+）。
  • command：要执行的 bash 命令（可使用 $CLAUDE_PROJECT_DIR 环境变量）。
  • timeout：（可选）命令运行的时间限制，以秒为单位，超过该时间将取消该命令。

对于像 UserPromptSubmit、Notification、Stop 和 SubagentStop 这样的事件，它们不使用匹配器，因此可以省略 matcher 字段：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/prompt-validator.py"
          }
        ]
      }
    ]
  }
}

项目特定的钩子脚本

您可以使用环境变量 CLAUDE_PROJECT_DIR（仅在 Claude Code 启动钩子命令时可用）来引用存储在项目中的脚本，从而确保无论 Claude 当前位于哪个目录，这些脚本都能正常工作：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

钩子事件

PreToolUse

在 Claude 创建工具参数之后、处理工具调用之前运行。

常见匹配器：

• Task - 子代理任务（参见子代理文档）
• Bash - Shell 命令
• Glob - 文件模式匹配
• Grep - 内容搜索
• Read - 文件读取
• Edit、MultiEdit - 文件编辑
• Write - 文件写入
• WebFetch、WebSearch - 网络操作

PostToolUse

在工具成功完成之后立即运行。

识别与 PreToolUse 相同的匹配器值。

Notification

在 Claude Code 发送通知时运行。通知会在以下情况下发送：

1. Claude 需要您的许可才能使用某个工具。例如：“Claude 需要您的许可才能使用 Bash”。
2. 提示输入已空闲至少 60 秒。“Claude 正在等待您的输入”。

UserPromptSubmit

在用户提交提示之前运行，即在 Claude 处理提示之前。这使您可以根据提示/对话添加额外的上下文、验证提示或阻止某些类型的提示。

Stop

在主 Claude Code 代理完成响应后运行。如果停止是由用户中断引起的，则不会运行。

SubagentStop

在 Claude Code 子代理（Task 工具调用）完成响应后运行。

TeammateIdle

当代理队友进入空闲状态时触发（多代理工作流）。

TaskCompleted

在后台任务完成时触发（多智能体工作流）。

ConfigChange

当 Claude Code 配置文件发生变化时触发（例如设置、CLAUDE.md、.mcp.json）。可用于重新加载外部状态或在配置更改时触发副作用。

WorktreeCreate

当 Claude 创建一个新的 Git 工作树时触发（通过 --worktree / -w 标志或代理定义中的 isolation: worktree）。可用于设置工作树特定的资源。

WorktreeRemove

当 Git 工作树在使用后被清理时触发。可用于销毁工作树特定的资源。

Setup

通过 --init、--init-only 或 --maintenance CLI 标志触发。可用于一次性项目设置任务、插件安装或维护脚本。

PermissionRequest

当 Claude 向用户显示权限提示时触发。可用于记录日志或自动化权限决策。

PreCompact

在 Claude Code 即将执行压缩操作之前运行。

匹配器：

• manual - 从 /compact 调用
• auto - 从自动压缩调用（由于上下文窗口已满）

SessionStart

当 Claude Code 开始新会话或恢复现有会话时运行（目前在后台会启动一个新会话）。可用于加载开发上下文，如现有问题或代码库的近期更改。

匹配器：

• startup - 从启动时调用
• resume - 从 --resume、--continue 或 /resume 调用
• clear - 从 /clear 调用

钩子输入

钩子通过标准输入接收包含会话信息和事件特定数据的 JSON 数据：

{
  // 公共字段
  session_id: string
  transcript_path: string  // 对话 JSON 的路径
  cwd: string              // 钩子调用时的当前工作目录

  // 事件特定字段
  hook_event_name: string
  ...
}

PreToolUse 输入

tool_input 的确切模式取决于工具。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

PostToolUse 输入

tool_input 和 tool_response 的确切模式取决于工具。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

Notification 输入

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "任务成功完成"
}

UserPromptSubmit 输入

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "编写一个计算阶乘的函数"
}

Stop 和 SubagentStop 输入

stop_hook_active 在 Claude Code 已经因停止钩子而继续运行时为真。请检查此值或处理对话记录，以防止 Claude Code 无限运行。

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "我已经完成了所有请求的更改。"
}

last_assistant_message 字段（v2.1.47+）包含 Claude 在停止前生成的最终文本。可用于验证完整性或记录结果。

PreCompact 输入

对于 manual，custom_instructions 来自用户传递给 /compact 的内容。对于 auto，custom_instructions 为空。

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

SessionStart 输入

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

钩子输出

钩子有两种方式可以将输出返回给 Claude Code。输出用于传达是否阻止以及应向 Claude 和用户显示的任何反馈。

简单：退出码

钩子通过退出码、stdout 和 stderr 传达状态：

• 退出码 0：成功。stdout 会在转录模式下显示给用户（CTRL-R），但 UserPromptSubmit 和 SessionStart 除外，在这些情况下 stdout 会被添加到上下文中。
• 退出码 2：阻止性错误。stderr 会反馈给 Claude 自动处理。请参阅下方的每个钩子事件的行为。
• 其他退出码：非阻止性错误。stderr 会显示给用户，执行将继续。

[!WARNING] 提醒：如果退出码为 0，Claude Code 不会看到 stdout，除了 UserPromptSubmit 钩子，该钩子的 stdout 会被注入为上下文。

退出码 2 行为

高级：JSON 输出

钩子可以在 stdout 中返回结构化 JSON，以实现更复杂的控制：

常见 JSON 字段

所有类型的钩子都可以包含以下可选字段：

{
  "continue": true, // Claude 是否应在钩子执行后继续（默认：是）
  "stopReason": "string" // 当 continue 为 false 时显示的消息
  "suppressOutput": true, // 隐藏转录模式下的 stdout（默认：否）
}

如果 continue 为 false，Claude 将在钩子运行后停止处理。

• 对于 PreToolUse，这与 "permissionDecision": "deny" 不同，后者仅阻止特定的工具调用，并向 Claude 提供自动反馈。
• 对于 PostToolUse，这与 "decision": "block" 不同，后者会向 Claude 提供自动化反馈。
• 对于 UserPromptSubmit，这会阻止提示被处理。
• 对于 Stop 和 SubagentStop，这将优先于任何 "decision": "block" 的输出。
• 在所有情况下，"continue" = false 都会优先于任何 "decision": "block" 的输出。

stopReason 会伴随 continue 一起提供一个向用户展示、但不向 Claude 展示的原因。

PreToolUse 决策控制

PreToolUse 钩子可以控制工具调用是否继续。

• "allow" 会绕过权限系统。permissionDecisionReason 会展示给用户，但不会展示给 Claude。（已弃用的 "approve" 值 + reason 具有相同的行为。）
• "deny" 会阻止工具调用执行。permissionDecisionReason 会展示给 Claude。（"block" 值 + reason 具有相同的行为。）
• "ask" 会在 UI 中请求用户确认工具调用。permissionDecisionReason 会展示给用户，但不会展示给 Claude。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow" | "deny" | "ask",
    "permissionDecisionReason": "我的理由在这里（展示给用户）"
  },
  "decision": "approve" | "block" | undefined, // 已弃用，但仍支持
  "reason": "决策解释" // 已弃用，但仍支持
}

PostToolUse 决策控制

PostToolUse 钩子可以控制工具调用是否继续。

• "block" 会自动向 Claude 发送 reason。
• undefined 则不做任何操作。reason 会被忽略。

{
  "decision": "block" | undefined,
  "reason": "决策解释"
}

UserPromptSubmit 决策控制

UserPromptSubmit 钩子可以控制用户提示是否被处理。

• "block" 会阻止提示被处理。提交的提示将从上下文中清除。reason 会展示给用户，但不会添加到上下文中。
• undefined 则允许提示正常进行。reason 会被忽略。
• "hookSpecificOutput.additionalContext" 如果未被阻止，则会将字符串添加到上下文中。

{
  "decision": "block" | undefined,
  "reason": "决策解释",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "我的附加上下文在这里"
  }
}

Stop/SubagentStop 决策控制

Stop 和 SubagentStop 钩子可以控制 Claude 是否必须继续。

• "block" 会阻止 Claude 停止。您必须填写 reason，以便 Claude 知道如何继续。
• undefined 则允许 Claude 停止。reason 会被忽略。

{
  "decision": "block" | undefined,
  "reason": "当 Claude 被阻止停止时，必须提供此原因"
}

SessionStart 决策控制

SessionStart 钩子允许您在会话开始时加载上下文。

• "hookSpecificOutput.additionalContext" 会将字符串添加到上下文中。

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "我的附加上下文在这里"
  }
}

退出码示例：Bash 命令验证

#!/usr/bin/env python3
import json
import re
import sys



# 定义验证规则为 (正则表达式模式, 消息) 元组列表
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "请使用 'rg'（ripgrep）代替 'grep'，以获得更好的性能和功能",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "请使用 'rg --files | rg pattern' 或 'rg --files -g pattern' 代替 'find -name'，以获得更好的性能",
    ),
]


def validate_command(command: str) -> list[str]:
    issues = []
    for pattern, message in VALIDATION_RULES:
        if re.search(pattern, command):
            issues.append(message)
    return issues


try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"错误：无效的 JSON 输入：{e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")

if tool_name != "Bash" 或者命令为空：
    sys.exit(1)

# 验证命令
issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # 退出码 2 会阻止工具调用，并将 stderr 显示给 Claude
    sys.exit(2)

JSON 输出示例：UserPromptSubmit 添加上下文和验证

[!注意] 对于 UserPromptSubmit 钩子，您可以使用以下两种方法注入上下文：

• 退出码 0 并通过 stdout：Claude 可以看到上下文（UserPromptSubmit 的特殊情况）
• JSON 输出：提供更多对行为的控制

#!/usr/bin/env python3
import json
import sys
import re
import datetime

# 从 stdin 加载输入
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"错误：无效的 JSON 输入：{e}", file=sys.stderr)
    sys.exit(1)

prompt = input_data.get("prompt", "")

# 检查敏感模式
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "提示包含潜在的机密信息"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # 使用 JSON 输出以特定理由阻止
        output = {
            "decision": "block",
            "reason": f"违反安全策略：{message}。请重新表述您的请求，避免包含敏感信息。"
        }
        print(json.dumps(output))
        sys.exit(0)

# 将当前时间添加到上下文中
context = f"当前时间：{datetime.datetime.now()}"
print(context)

"""
以下内容也是等价的：
print(json.dumps({
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": context,
  },
}))
"""

# 允许提示在附加上下文的情况下继续
sys.exit(0)

JSON 输出示例：PreToolUse 自动批准

#!/usr/bin/env python3
import json
import sys

# 从 stdin 加载输入
try：
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e：
    print(f"错误：无效的 JSON 输入：{e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# 示例：自动批准文档文件的读取操作
if tool_name == "Read"：
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json"))：
        # 使用 JSON 输出自动批准工具调用
        output = {
            "decision": "approve",
            "reason": "文档文件已自动批准",
            "suppressOutput": True  # 不在转录模式中显示
        }
        print(json.dumps(output))
        sys.exit(0)

# 对于其他情况，让正常的权限流程继续
sys.exit(0)

使用 MCP 工具

Claude Code 钩子可以与 模型上下文协议 (MCP) 工具 无缝协作。当 MCP 服务器提供工具时，这些工具会以一种特殊的命名模式出现，您可以在自己的钩子中匹配这种模式。

MCP 工具命名

MCP 工具遵循 mcp__<server>__<tool> 的命名模式，例如：

• mcp__memory__create_entities - 内存服务器的创建实体工具
• mcp__filesystem__read_file - 文件系统服务器的读取文件工具
• mcp__github__search_repositories - GitHub 服务器的搜索工具

为 MCP 工具配置钩子

您可以针对特定的 MCP 工具或整个 MCP 服务器进行配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

示例

[!TIP] 有关代码格式化、通知和文件保护等实用示例，请参阅入门指南中的“更多示例”(/en/docs/claude-code/hooks-guide#more-examples)。

安全注意事项

免责声明

自担风险使用：Claude Code 钩子会在您的系统上自动执行任意的 shell 命令。通过使用钩子，您确认：

• 您对所配置的命令负全部责任
• 钩子可以修改、删除或访问您用户账户可访问的任何文件
• 恶意或编写不当的钩子可能导致数据丢失或系统损坏
• Anthropic 不对因使用钩子而导致的任何损害提供任何保证或承担任何责任
• 在生产环境中使用之前，您应在安全的环境中彻底测试钩子

在将任何钩子命令添加到您的配置之前，请务必仔细审查并理解这些命令。

钩子安全注意事项

以下是一些编写更安全钩子的关键实践：

1. 验证并清理输入 - 切勿盲目信任输入数据
2. 始终引用 shell 变量 - 使用 "$VAR" 而不是 $VAR
3. 阻止路径遍历 - 检查文件路径中是否存在 ..
4. 使用绝对路径 - 为脚本指定完整路径（使用 $CLAUDE_PROJECT_DIR 表示项目路径）
5. 跳过敏感文件 - 避免 .env、.git/、密钥等文件

配置安全性

直接在设置文件中编辑钩子并不会立即生效。Claude Code：

1. 在启动时捕获钩子的快照
2. 在整个会话中使用该快照
3. 如果钩子被外部修改，会发出警告
4. 必须在 /hooks 菜单中审核后才能应用更改

这可以防止恶意钩子修改影响您当前的会话。

钩子执行细节

• 超时：默认执行限制为 60 秒，每个命令均可配置。
  • 单个命令的超时不会影响其他命令。
• 并行化：所有匹配的钩子会并行运行
• 环境：在当前目录下运行，使用 Claude Code 的环境
  • 环境变量 CLAUDE_PROJECT_DIR 可用，包含项目根目录的绝对路径
• 输入：通过 stdin 传递 JSON
• 输出：
  • PreToolUse/PostToolUse/Stop：进度显示在对话记录中（Ctrl-R）
  • 通知：仅记录到调试日志中（--debug）

调试

基本故障排除

如果您的钩子无法正常工作：

1. 检查配置 - 运行 /hooks 查看您的钩子是否已注册
2. 验证语法 - 确保您的 JSON 设置有效
3. 测试命令 - 先手动运行钩子命令
4. 检查权限 - 确保脚本具有可执行权限
5. 查看日志 - 使用 claude --debug 查看钩子执行详情

常见问题：

• 引号未转义 - 在 JSON 字符串中使用 \"
• 匹配器错误 - 检查工具名称是否完全匹配（区分大小写）
• 命令未找到 - 为脚本使用完整路径

高级调试

对于复杂的钩子问题：

1. 检查钩子执行 - 使用 claude --debug 查看详细的钩子执行过程
2. 验证 JSON 模式 - 使用外部工具测试钩子的输入和输出
3. 检查环境变量 - 验证 Claude Code 的环境是否正确
4. 测试边界条件 - 尝试使用不寻常的文件路径或输入运行钩子
5. 监控系统资源 - 检查钩子执行过程中是否有资源耗尽的情况
6. 使用结构化日志记录 - 在您的钩子脚本中实现日志记录

调试输出示例

使用 claude --debug 查看钩子执行详情：

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

进度消息会显示在对话记录模式（Ctrl-R）中，显示：

• 正在运行哪个钩子
• 正在执行的命令
• 成功或失败状态
• 输出或错误信息

安全与权限

工具权限模式

# 允许特定工具（读取/编辑文件）
claude --allowedTools "Edit,Read"

# 允许工具类别，包括 Bash（但仍有限制范围）
claude --allowedTools "Edit,Read,Bash"

# 限定权限范围（所有 git 命令）
claude --allowedTools "Bash(git:*)"

# 多重限定范围（git + npm）
claude --allowedTools "Bash(git:*),Bash(npm:*)"

危险模式

[!Warning] 切勿在生产系统、共享机器或包含重要数据的系统中使用 仅在隔离环境（如 Docker 容器）中使用此模式，否则可能导致数据丢失并危及您的系统！

claude --dangerously-skip-permissions

自动化与集成

使用 Claude Code 进行自动化和脚本编写

GitHub Actions，您可以直接复制粘贴 :p

1. 在您的组织/仓库中安装 Claude GitHub 应用程序（这是 Actions 能够对 PR 或问题发表评论的必要条件）。
2. 在您的仓库中，添加一个名为 ANTHROPIC_API_KEY 的秘密设置 → 秘密和变量 → Actions → 新建仓库秘密
3. 将下面的工作流复制到 .github/workflows/ 目录中。
4. 打开一个 测试 PR（或新建一个问题），看看它们是否能正常运行。

[!TIP] 当您长期采用这些工作流时，请将其固定到某个发布标签上（例如 @v1）。下面的代码片段为了便于阅读，使用了分支标签。

自动 PR 审核（内联评论）

在 PR 打开或更新时，立即创建带有内联评论的结构化评审。

文件： .github/workflows/claude-pr-auto-review.yml

name: 自动评审 PR
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: write

jobs:
  auto-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Claude PR 审核
        uses: anthropics/claude-code-action@main
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # Claude 将获取差异并留下内联评论
          direct_prompt: |
            审查此拉取请求的差异，检查其正确性、可读性、测试覆盖、性能和开发体验。
            优先提供具体且可操作的建议。在适当的地方使用内联评论。
          # 运行期间允许使用的 GitHub 工具：
          allowed_tools: >-
            mcp__github__get_pull_request_diff,
            mcp__github__create_pending_pull_request_review,
            mcp__github__add_comment_to_pending_review,
            mcp__github__submit_pending_pull_request_review

每个 PR 的安全审核

运行专注的安全扫描，并将发现直接评论到 PR 上。

文件： .github/workflows/claude-security-review.yml

name: 安全审核
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          fetch-depth: 2

      - name: Claude 代码安全审核
        uses: anthropics/claude-code-security-review@main
        with:
          claude-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          comment-pr: true
          # 可选：
          # exclude-directories: "docs,examples"
          # claudecode-timeout: "20"
          # claude-model: "claude-sonnet-4-6-20260217"

问题分类（建议标签与严重性）

当新问题打开时，Claude 会提出标签/严重性建议，并发布整洁的分类评论。您可以通过切换一个标志来启用“自动应用标签”功能。

文件： .github/workflows/claude-issue-triage.yml

name: Claude 问题分类
on:
  issues:
    types: [opened, edited, reopened]

permissions:
  contents: read
  issues: write

jobs:
  triage:
    runs-on: ubuntu-latest
    env:
      CLAUDE_MODEL: claude-sonnet-4-6-20260217
    steps:
      - name: 收集上下文及相似问题
        id: gather
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          TITLE="${{ github.event.issue.title }}"
          BODY="${{ github.event.issue.body }}"
          # 基于标题关键词的简单相似搜索
          Q=$(echo "$TITLE" | tr -dc '[:alnum:] ' | awk '{print $1" "$2" "$3" "$4}')
          gh api -X GET search/issues -f q="repo:${{ github.repository }} is:issue $Q" -f per_page=5 > similars.json
          echo "$TITLE" > title.txt
          echo "$BODY" > body.txt

      - name: 向 Claude 请求分类 JSON
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          cat > payload.json << 'JSON'
          {
            "model": "${{ env.CLAUDE_MODEL }}",
            "max_tokens": 1500,
            "system": "你是一位务实的分类工程师。请务必具体，同时注意避免重复问题。",
            "messages": [{
              "role": "user",
              "content": [{
                "type":"text",
                "text":"根据该问题及其相似候选，生成严格的 JSON 格式，包含以下键：labels（字符串数组）、severity（低、中、高、critical 中的一个）、duplicate_url（字符串或空）、comment_markdown（简短文本）。请勿包含任何额外的键。"
              },
              {"type":"text","text":"问题标题：\n"},
              {"type":"text","text": (从文件中引入) },
              {"type":"text","text":"\n\n问题描述：\n"},
              {"type":"text","text": (从文件中引入) },
              {"type":"text","text":"\n\n相似问题（JSON）：\n"},
              {"type":"text","text": (从文件中引入) }]
            }]
          }
          JSON
          # 安全注入文件内容
          jq --arg title "$(cat title.txt)" '.messages[0].content[2].text = $title' payload.json \
          | jq --arg body "$(cat body.txt)" '.messages[0].content[4].text = $body' \
          | jq --arg sims "$(cat similars.json)" '.messages[0].content[6].text = $sims' > payload.final.json

          curl -s https://api.anthropic.com/v1/messages \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "content-type: application/json" \
            -d @payload.final.json > out.json
          jq -r '.content[0].text' out.json > triage.json || echo '{}' > triage.json
          # 验证 JSON 以避免发布无效数据
          jq -e . triage.json >/dev/null 2>&1 || echo '{"labels":[],"severity":"low","duplicate_url":"","comment_markdown":"(分类解析失败)"}' > triage.json

      - name: 应用标签（可选）
        if: ${{ false }} # 切换为 `true` 即可自动应用标签
        uses: actions/github-script@v7
        with:
          script: |
            const triage = JSON.parse(require('fs').readFileSync('triage.json','utf8'))
            if (triage.labels?.length) {
              await github.rest.issues.addLabels({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                labels: triage.labels
              })
            }

      - name: 发布分类评论
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs')
            const triage = JSON.parse(fs.readFileSync('triage.json','utf8'))
            const md = `### 🤖 分类
            - **建议标签：** ${triage.labels?.join(', ') || '—'}
            - **严重性：** ${triage.severity || '—'}
            ${triage.duplicate_url ? `- **可能重复：** ${triage.duplicate_url}\n` : ''}
            ---
            ${triage.comment_markdown || ''}`
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: md
            })

[!NOTE] 分类工作流默认会发布一条建议评论。如果希望自动应用标签，请将Apply labels步骤切换为true。

配置与自定义

• 模型选择：按照所示设置CLAUDE_MODEL（例如，claude-sonnet-4-6-20260217）。
• 密钥：需要ANTHROPIC_API_KEY。内置的GITHUB_TOKEN足以用于发布评论和应用标签。
• 权限：每个工作流都会声明其所需的最低权限（pull-requests: write和/或issues: write）。仅当您的组织要求更严格的策略时才进行调整。
• 范围：在触发器上使用paths:过滤器来限制工作流运行的时间（例如，仅针对/src目录，或排除/docs目录）。

故障排除

首先检查操作日志——大多数问题都是由于缺少密钥或权限，或者YAML块缩进错误导致的。

• PR上没有出现评论：请确认Claude GitHub应用已安装，并且工作流具有pull-requests: write权限。
• 应用标签时出现403错误：确保作业或步骤具有issues: write权限。默认的GITHUB_TOKEN必须有权访问该仓库。
• Anthropic API错误：请确认ANTHROPIC_API_KEY已在仓库（或组织）级别设置，并且未过期。
• “YAML格式不正确”：请检查缩进——每级缩进两个空格，不要使用制表符。

帮助与故障排除

[!TIP] 问：找不到claude命令，但npx claude可以运行？

答：您的PATH环境变量中缺少npm全局bin目录。请参阅关于PATH问题的部分，适用于Windows或Linux。

问：我需要哪个版本的Node.js？

答：Node.js 18及以上版本（理想情况下是20及以上版本）。您可以通过运行node --version来检查。

问：我在哪里可以看到日志？

答：运行claude doctor和claude --verbose，诊断窗口会显示日志文件的位置。

问：修改PATH后需要重启吗？

答：不需要重启，但您必须打开一个新的终端窗口。

C:\Users\<you>\AppData\Roaming\npm
C:\Program Files\nodejs</kbd>

C:\Users\<you>\.claude\local\bin
C:\Users\<you>\.local\bin

where claude
claude doctor

node --version

npm uninstall -g @anthropic-ai/claude-code

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

echo $env:ANTHROPIC_API_KEY
claude -p "test" --verbose

echo $ANTHROPIC_API_KEY
claude -p "test" --verbose

claude config get allowedTools

claude config set allowedTools "[]"

claude config set allowedTools '["Edit","View"]'

claude --debug

claude mcp list
claude mcp remove <server-name>

npm uninstall -g @anthropic-ai/claude-code

Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\claude*" -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code" -Recurse -Force -ErrorAction SilentlyContinue

Remove-Item -LiteralPath "$env:USERPROFILE\.claude\downloads\*" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath "$env:USERPROFILE\.claude\local\bin\claude.exe" -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath "$env:USERPROFILE\.claude\local" -Recurse -Force -ErrorAction SilentlyContinue

Remove-Item -LiteralPath "$env:USERPROFILE\.claude.json" -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath "$env:USERPROFILE\.claude" -Recurse -Force -ErrorAction SilentlyContinue

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

Write-Host "`n=== Node.js 和 npm ==="; node --version; npm --version
Write-Host "`n=== Claude 在哪里？==="; where claude
Write-Host "`n=== 尝试运行 doctor ==="; try { claude doctor } catch { Write-Host "Claude 没有在 PATH 中" }
Write-Host "`n=== API 密钥已设置吗？==="; if ($env:ANTHROPIC_API_KEY) { "是" } else { "否" }

echo "=== Node.js 和 npm ==="; node --version; npm --version
echo "=== Claude 在哪里？==="; which claude || echo "Claude 没有在 PATH 中"
echo "=== 尝试运行 doctor ==="; claude doctor || true
echo "=== API 密钥已设置吗？==="; [ -n "$ANTHROPIC_API_KEY" ] && echo 是 || echo 否

最佳实践

精选指南，帮助您安全、快速且正确地使用 Claude Code CLI 和交互式 REPL。此处的所有命令和标志均与截至 2026年2月28日 的 Anthropic 官方文档一致。

有效提示技巧

# 好的例子：具体且详细
claude "审查 UserAuth.js 中的安全漏洞，重点关注 JWT 处理"

# 不好的例子：含糊不清
claude "检查我的代码"

提示：claude "query" 会启动预加载了您的提示的交互式 REPL；claude -p "query" 则以 打印模式（非交互式）运行并退出。

安全最佳实践

1. 从最小权限开始

   • 优先使用显式的允许和拒绝规则，无论是在 CLI 中还是在配置文件中。

   # 只允许本次运行所需的权限
   claude --allowedTools "Read" "Grep" "LS" "Bash(npm run test:*)"
   

   或者将项目策略写入 .claude/settings.json：

   {
     "permissions": {
       "allow": ["Read", "Grep", "LS", "Bash(npm run test:*)"],
       "deny": [
         "WebFetch",
         "Bash(curl:*)",
         "Read(./.env)",
         "Read(./secrets/**)"
       ]
     }
   }
   

2. 正确处理敏感信息

   • 对于 SDK 或自动化流程，使用环境变量：

   export ANTHROPIC_API_KEY="your_key"   # 用于 SDK 或打印模式
   

   • 在交互式 REPL 中，建议使用 /login 命令登录，而不是硬编码令牌。
   • 在配置文件中禁止访问敏感文件（取代旧的 ignorePatterns）：

   {
     "permissions": {
       "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
     }
   }
   

3. 定期审计权限

   # 项目级设置
   claude config list
   claude config get permissions.allow
   claude config get permissions.deny
   
   # 全局级设置
   claude config list -g
   

4. 避免在生产环境中使用绕过模式

   • 不要在隔离或开发沙盒之外使用 --dangerously-skip-permissions。
   • 对于无人值守的任务，应结合狭窄的 --allowedTools 和 --disallowedTools 选项，以及项目级别的配置文件。

性能优化建议

1. 在自动化任务中使用机器可读的输出

   claude -p "总结此错误日志" --output-format json
   # 支持的格式：text | json | stream-json
   

2. 限制非交互式任务的执行范围

   claude -p "运行类型检查并总结失败情况" --max-turns 3
   # 也可以限制思考时间：
   export MAX_THINKING_TOKENS=20000
   

3. 保持会话整洁

   # 默认保留最近 30 天的会话，可以调整为 20 天
   claude config set -g cleanupPeriodDays 20
   

4. 限制上下文范围

   # 只授予对相关路径的访问权限，以减少扫描和噪音
   claude --add-dir ./services/api ./packages/ui
   

5. 选择合适的模型

   • CLI 别名：--model sonnet 或 --model opus（该系列最新版本）。
   • 截至 2026 年 2 月，Sonnet 4.6 是默认的 Sonnet 模型——以 Sonnet 的价格提供前沿性能，并拥有 100 万标记的上下文窗口。
   • 为了确保可重复性，在配置中固定完整的模型 ID（例如 "claude-sonnet-4-6-20260217"）。

监控与告警

1) 健康检查 使用内置的 doctor 命令来验证安装和环境是否正常。

# 每 15 分钟运行一次
*/15 * * * * /usr/local/bin/claude doctor >/dev/null 2>&1 || \
mail -s "Claude Code doctor 失败" admin@company.com </dev/null

2) 日志分析批处理作业

# 每天以非交互式 JSON 格式进行分析
0 6 * * * tail -1000 /var/log/app.log | \
claude -p "分析错误、回归问题及可疑模式；输出 JSON 格式。" \
--output-format json > /tmp/daily-analysis.json

3) 遥测（可选） Claude Code 会发出 OpenTelemetry 指标和事件。您可以在配置或环境变量中设置导出器（例如 OTLP），并将数据发送到您的可观ability 平台（如 Datadog、Honeycomb、Prometheus/Grafana 等）。

协作最佳实践

团队工作流程

1) 共享版本化的配置文件

// .claude/settings.json（提交到代码库）
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "LS",
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
    ],
    "deny": [
      "WebFetch",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
    ],
  },
  // 如果需要可重复性，可以在这里固定完整的模型 ID：
  "model": "claude-sonnet-4-6-20260217",
}

2) 文档自动化

# 使用明确的任务更新文档
claude "更新 README.md，反映最新的 API 端点和示例。"
claude "根据 schema.prisma 生成 TypeScript 类型定义，并写入 /types 目录。"

3) 代码审查标准

claude "审查代码中的潜在逻辑错误，并提出改进建议。"
claude "检查代码是否符合项目的编码规范，并给出反馈。"
claude "评估代码的可维护性和扩展性，并提出优化建议。"

更多资源

• 官方文档: https://docs.anthropic.com/
• 社区论坛: https://community.anthropic.com/
• GitHub 仓库: https://github.com/anthropic-ai/claude-code
• API 参考: https://api.anthropic.com/

结论

Claude Code CLI 和交互式 REPL 为开发者提供了强大的工具，能够显著提升开发效率和代码质量。通过遵循上述最佳实践，您可以更安全、高效地利用这些工具，同时确保代码的安全性和可维护性。无论是个人开发还是团队协作，合理配置和使用 Claude Code 都能为您带来显著的价值。

使用受限工具审查本地差异

git fetch origin main git diff origin/main...HEAD > /tmp/diff.patch claude --allowedTools "Read" "Grep" "Bash(git:*)"
"使用团队标准审查 /tmp/diff.patch：

• 安全最佳实践
• 性能考量
• 代码风格合规性
• 测试覆盖率是否充分"

<h3 id="knowledge-sharing">知识共享</h3>

**1) 项目运行手册**

```bash
claude "为这个应用创建部署运行手册：步骤、检查项、回滚流程。"
claude "记录新开发人员的入职指南：环境搭建、常用命令、编码规范。"

2) 架构文档

claude "更新架构文档以反映新的微服务架构。"
claude "为认证流程创建序列图。"

小贴士：将持久化的上下文保存在项目根目录下的 CLAUDE.md 文件中。在 REPL 中，可以使用 /memory 来管理上下文，并用 @path 将文件内容导入到提示中。

需要避免的常见陷阱

安全方面

❌ 不要

• 在生产系统上使用 --dangerously-skip-permissions
• 将密钥硬编码在命令或配置中
• 授予过于宽泛的权限（例如 Bash(*)）
• 无必要地以高权限运行

✅ 要做

• 将密钥存储在环境变量和凭据管理工具中
• 从最小的 permissions.allow 开始，逐步扩大权限范围
• 使用 claude config list 和 claude config get 进行审计
• 将高风险操作隔离在容器或虚拟机中

性能方面

❌ 不要

• 当只需要一个包时却加载整个 monorepo
• 对简单任务也用尽思考或回合预算
• 忽视会话清理

✅ 要做

• 使用 --add-dir 提供聚焦的上下文
• 根据需求调整 --max-turns 和 MAX_THINKING_TOKENS
• 设置 cleanupPeriodDays 定期清理旧会话

工作流方面

❌ 不要

• 跳过项目上下文（CLAUDE.md）
• 使用模糊不清的提示
• 忽视错误和日志
• 在未测试的情况下就进行自动化

✅ 要做

• 维护并及时更新 CLAUDE.md
• 在提示中保持具体性和目标导向
• 根据需要通过日志或 OTel 监控
• 先在安全环境中测试自动化流程

第三方集成

DeepSeek 集成

1. 确保已安装 claude Code

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

2. 配置环境变量

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=${YOUR_API_KEY}
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat

3. 现在只需启动 claude 即可

更多信息请参阅 DeepSeek 官方文档

Claude Code 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下最低要求：

• 操作系统:
  • macOS 10.15+
  • Linux (Ubuntu 20.04+ / Debian 10+)
  • Windows 10/11 或 WSL
• 硬件配置: 最低 4GB RAM，推荐 8GB 及以上。
• 网络环境: 需要稳定的互联网连接以调用 Anthropic API。
• 依赖软件:
  • 方案 A (推荐): 无需安装 Node.js，原生安装程序自带运行时。
  • 方案 B (npm): 如需通过 npm 安装，需预先安装 Node.js 18+。
  • 可选: Git 2.23+ 及 GitHub/GitLab CLI（用于 PR 工作流）。

注意: 请提前在 Anthropic Console 获取您的 API Key (sk-...)。切勿将真实密钥提交到代码仓库，建议使用环境变量或密钥管理工具存储。

安装步骤

推荐使用原生安装程序（无需配置 Node.js 环境），以下是各平台的具体命令：

1. 原生安装 (推荐 ⭐️)

macOS / Linux / WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows (CMD)

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows (PowerShell)

irm https://claude.ai/install.ps1 | iex

Arch Linux

yay -S claude-code

2. 备选安装 (基于 npm)

仅当您已安装 Node.js 18+ 时使用

全局安装

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

Docker 快速体验

# macOS/Linux
docker run -it --rm -v "$PWD:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc 'npm i -g @anthropic-ai/claude-code && cd /workspace && claude'

# Windows (CMD)
docker run -it --rm -v "%cd%:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc "npm i -g @anthropic-ai/claude-code && cd /workspace && claude"

3. 验证安装

安装完成后，运行以下命令检查版本：

claude --version

或者检查安装路径：

• Linux/macOS: which claude
• Windows: where claude

基本使用

1. 配置 API Key

在使用前，您需要设置 ANTHROPIC_API_KEY 环境变量。

临时设置 (当前终端会话有效)

• Linux / macOS (Bash/Zsh)

  export ANTHROPIC_API_KEY="sk-your-key-here"
  

• Windows (CMD)

  set ANTHROPIC_API_KEY=sk-your-key-here
  

• Windows (PowerShell)

  $env:ANTHROPIC_API_KEY = "sk-your-key-here"
  

永久设置

• Linux: 将 export ANTHROPIC_API_KEY="sk-your-key-here" 添加到 ~/.bashrc 或 ~/.zshrc。
• Windows: 使用 setx ANTHROPIC_API_KEY "sk-your-key-here" (CMD) 或通过系统属性图形界面设置。

或者使用内置登录命令

claude /login
# 或
claude auth login

2. 启动与交互

进入您的项目目录，直接运行 claude 即可启动交互式界面：

cd /path/to/your/project
claude

提示: 您也可以直接使用 npx claude 启动（如果未全局安装）。

简单示例: 启动后，您可以直接输入自然语言指令，例如：

• "解释一下这个项目的结构"
• "帮我修复 src/main.py 中的 bug"
• "为当前的 API 端点编写单元测试"

3. 集成 VS Code / Cursor

若要在编辑器中获得最佳体验：

1. 确保在 VS Code 或 Cursor 中安装了 Claude Code extension。
2. 在终端中进入项目目录并打开编辑器：

   cd /path/to/project
   code .
   

3. 在编辑器内调用 Claude Code 插件即可。

4. 常用管理命令

• 配置设置: claude config
• 管理 MCP 服务器: claude mcp list (支持 add/remove)
• 配置子代理: claude /agents
• 更新版本: claude update
• 开启完成任务提示音:

  claude config set --global preferredNotifChannel terminal_bell