Claude Code 概述

安装 NodeJS 18+，然后运行：

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

Claude Code 是一个智能编程工具，它存在于您的终端中，理解您的代码库，并通过自然语言命令帮助您更快地编码。通过直接集成到您的开发环境中，Claude Code 简化了您的工作流程，无需额外的服务器或复杂的设置。

Claude Code 的主要功能包括：

• 编辑文件并修复代码库中的错误
• 回答关于代码架构和逻辑的问题
• 执行和修复测试、代码检查和其他命令
• 搜索 git 历史记录，解决合并冲突，创建提交和 PR

​

开始之前

​

检查系统要求

• 操作系统：macOS 10.15+、Ubuntu 20.04+/Debian 10+ 或通过 WSL 使用的 Windows
• 硬件：最低 4GB RAM
• 软件：
  • Node.js 18+
  • git 2.23+（可选）
  • GitHub 或 GitLab CLI 用于 PR 工作流（可选）
  • ripgrep（rg）用于增强文件搜索（可选）
• 网络：需要互联网连接进行身份验证和 AI 处理
• 地区：仅在支持的国家可用

​

安装和认证

​

核心功能和工作流程

Claude Code 直接在您的终端中运行，理解您的项目上下文并采取实际行动。无需手动将文件添加到上下文中 - Claude 会根据需要探索您的代码库。

​

安全和隐私设计

您代码的安全至关重要。Claude Code 的架构确保：

• 直接 API 连接：您的查询直接发送到 Anthropic 的 API，无需中间服务器
• 在您工作的地方工作：直接在您的终端中运行
• 理解上下文：保持对整个项目结构的感知
• 采取行动：执行实际操作，如编辑文件和创建提交

​

从问题到解决方案，只需几秒钟

# 询问关于您代码库的问题
claude
> 我们的身份验证系统是如何工作的？

# 用一个命令创建提交
claude commit

# 修复多个文件中的问题
claude "修复身份验证模块中的类型错误"

​

初始化您的项目

对于首次使用的用户，我们建议：

1. 使用 claude 启动 Claude Code
2. 尝试一个简单的命令，如 summarize this project
3. 使用 /init 生成 CLAUDE.md 项目指南
4. 要求 Claude 将生成的 CLAUDE.md 文件提交到您的仓库

​

使用 Claude Code 完成常见任务

Claude Code 直接在您的终端中运行，理解您的项目上下文并采取实际行动。无需手动将文件添加到上下文中 - Claude 会根据需要探索您的代码库。

​

理解陌生代码

> 支付处理系统做什么？
> 查找检查用户权限的位置
> 解释缓存层是如何工作的

​

自动化 Git 操作

> 提交我的更改
> 创建一个 pr
> 哪个提交在去年 12 月添加了 markdown 测试？
> 在 main 分支上变基并解决任何合并冲突

​

智能编辑代码

> 为注册表单添加输入验证
> 重构日志记录器以使用新的 API
> 修复工作队列中的竞态条件

​

测试和调试您的代码

> 运行身份验证模块的测试并修复失败
> 查找并修复安全漏洞
> 解释为什么这个测试失败了

​

鼓励更深入的思考

对于复杂问题，明确要求 Claude 更深入地思考：

> 思考我们应该如何构建新的支付服务
> 深入思考我们身份验证流程中的边缘情况

Claude Code 会显示 Claude 何时使用扩展思考（在 Claude Sonnet 3.7、Claude Opus 4 上可用）。您可以主动提示 Claude “思考”或”深入思考”以处理更需要规划的任务。我们建议您首先告诉 Claude 您的任务，让它从您的项目中收集上下文。然后，要求它”思考”以创建计划。

​

自动化 CI 和基础设施工作流程

Claude Code 提供了非交互模式，用于无头执行。这在非交互上下文（如脚本、管道和 Github Actions）中运行 Claude Code 时特别有用。

使用 --print (-p) 在非交互模式下运行 Claude。在此模式下，您可以设置 ANTHROPIC_API_KEY 环境变量来提供自定义 API 密钥。

当您预先配置 Claude 允许使用的命令集时，非交互模式特别有用：

export ANTHROPIC_API_KEY=sk_...
claude -p "使用最新更改更新 README" --allowedTools "Bash(git diff:*)" "Bash(git log:*)" Write --disallowedTools ...

​

使用命令控制 Claude Code

​

CLI 命令

CLI 标志：

• --print (-p)：在非交互模式下打印响应
• --json：在 --print 模式下返回 JSON 输出，对脚本编写和自动化有用
• --verbose：启用详细日志记录，显示完整的逐轮输出（在打印和交互模式下对调试有帮助）
• --dangerously-skip-permissions：跳过权限提示

​

斜杠命令

在会话中控制 Claude 的行为：

​

管理 Claude 的记忆

Claude Code 可以在会话之间记住您的偏好，如样式指南和工作流程中的常用命令。

​

确定记忆类型

Claude Code 提供三个记忆位置，每个位置服务于不同的目的：

所有记忆文件在启动时都会自动加载到 Claude Code 的上下文中。

​

Claude 如何查找记忆

Claude Code 递归读取记忆：从当前工作目录开始，Claude Code 递归向上到 / 并读取它找到的任何 CLAUDE.md 或 CLAUDE.local.md 文件。这在处理大型仓库时特别方便，当您在 foo/bar/ 中运行 Claude Code，并且在 foo/CLAUDE.md 和 foo/bar/CLAUDE.md 中都有记忆时。

​

使用 # 快捷方式快速添加记忆

添加记忆的最快方法是以 # 字符开始您的输入：

# 始终使用描述性变量名

系统将提示您选择要将此记忆存储在哪个记忆文件中。

​

使用 /memory 直接编辑记忆

在会话期间使用 /memory 斜杠命令打开系统编辑器中的任何记忆文件，以进行更广泛的添加或组织。

​

记忆最佳实践

• 具体明确：“使用 2 空格缩进”比”正确格式化代码”更好。
• 使用结构组织：将每个单独的记忆格式化为项目符号，并在描述性的 markdown 标题下对相关记忆进行分组。
• 定期审查：随着项目的发展更新记忆，确保 Claude 始终使用最新的信息和上下文。

​

管理权限和安全

Claude Code 使用分层权限系统来平衡功能和安全性：

​

Claude 可用的工具

Claude Code 可以访问一组强大的工具，帮助它理解和修改您的代码库：

权限规则可以使用 /allowed-tools 或在权限设置中配置。

​

防止提示注入

提示注入是攻击者试图通过插入恶意文本来覆盖或操纵 AI 助手指令的技术。Claude Code 包含几项防范这些攻击的保障措施：

• 权限系统：敏感操作需要明确批准
• 上下文感知分析：通过分析完整请求检测潜在有害指令
• 输入净化：通过处理用户输入防止命令注入
• 命令黑名单：阻止从网络获取任意内容的风险命令，如 curl 和 wget

处理不受信任内容的最佳实践：

1. 在批准前审查建议的命令
2. 避免将不受信任的内容直接通过管道传送给 Claude
3. 验证对关键文件的建议更改
4. 使用 /bug 报告可疑行为

​

配置网络访问

Claude Code 需要访问：

• api.anthropic.com
• statsig.anthropic.com
• sentry.io

在容器化环境中使用 Claude Code 时，请将这些 URL 列入白名单。

​

环境变量

Claude Code 支持以下环境变量来控制其行为：

​

配置 Claude Code

通过在终端中运行 claude config 或在交互式 REPL 中使用 /config 命令来配置 Claude Code。

​

配置选项

Claude Code 支持全局和项目级配置。

要管理您的配置，请使用以下命令：

• 列出设置：claude config list
• 查看设置：claude config get <key>
• 更改设置：claude config set <key> <value>
• 向设置添加（对于列表）：claude config add <key> <value>
• 从设置中移除（对于列表）：claude config remove <key> <value>

默认情况下，config 更改您的项目配置。要管理全局配置，请使用 --global（或 -g）标志。

​

全局配置

要设置全局配置，请使用 claude config set -g <key> <value>：

​

自动更新程序权限选项

当 Claude Code 检测到它没有足够的权限写入全局 npm 前缀目录（自动更新所需）时，您会看到一个警告，指向本文档页面。有关自动更新程序问题的详细解决方案，请参阅故障排除指南。

​

推荐：创建新的用户可写 npm 前缀

# 首先，保存现有全局包列表以便稍后迁移
npm list -g --depth=0 > ~/npm-global-packages.txt

# 为全局包创建目录
mkdir -p ~/.npm-global

# 配置 npm 使用新的目录路径
npm config set prefix ~/.npm-global

# 注意：根据您的 shell 将 ~/.bashrc 替换为 ~/.zshrc、~/.profile 或其他适当的文件
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# 应用新的 PATH 设置
source ~/.bashrc

# 现在在新位置重新安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 可选：在新位置重新安装之前的全局包
# 查看 ~/npm-global-packages.txt 并安装您想保留的包
# npm install -g package1 package2 package3...

为什么我们推荐这个选项：

• 避免修改系统目录权限
• 为全局 npm 包创建一个干净、专用的位置
• 遵循安全最佳实践

由于 Claude Code 正在积极开发中，我们建议使用上述推荐选项设置自动更新。

​

禁用自动更新程序

如果您更喜欢禁用自动更新程序而不是修复权限，可以使用：

claude config set -g autoUpdaterStatus disabled

​

项目配置

使用 claude config set <key> <value>（不带 -g 标志）管理项目配置：

例如：

# 让 npm test 无需批准即可运行
claude config add allowedTools "Bash(npm test)"

# 让 npm test 及其任何子命令无需批准即可运行
claude config add allowedTools "Bash(npm test:*)"

# 指示 Claude 忽略 node_modules
claude config add ignorePatterns node_modules
claude config add ignorePatterns "node_modules/**"

有关 allowedTools 规则格式，请参阅权限。

​

优化您的终端设置

当您的终端正确配置时，Claude Code 效果最佳。请遵循以下指南优化您的体验。

支持的 shell：

• Bash
• Zsh
• Fish

​

主题和外观

Claude 无法控制您终端的主题。这由您的终端应用程序处理。您可以在入门过程中或随时通过 /config 命令将 Claude Code 的主题与您的终端匹配

​

换行符

您有几种选项可以在 Claude Code 中输入换行符：

• 快速转义：输入 \ 后跟 Enter 创建换行
• 键盘快捷键：在正确配置的情况下按 Option+Enter（Meta+Enter）

要在终端中设置 Option+Enter：

对于 Mac Terminal.app：

1. 打开设置 → 配置文件 → 键盘
2. 勾选”将 Option 键用作 Meta 键”

对于 iTerm2 和 VSCode 终端：

1. 打开设置 → 配置文件 → 按键
2. 在常规下，将左/右 Option 键设置为”Esc+”

iTerm2 和 VSCode 用户提示：在 Claude Code 中运行 /terminal-setup 自动配置 Shift+Enter 作为更直观的替代方案。

​

通知设置

通过正确的通知配置，永远不会错过 Claude 完成任务的时刻：

终端铃声通知

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

claude config set --global preferredNotifChannel terminal_bell

对于 macOS 用户：不要忘记在系统设置 → 通知 → [您的终端应用程序] 中启用通知权限。

iTerm 2 系统通知

对于 iTerm 2 任务完成提醒：

1. 打开 iTerm 2 首选项
2. 导航到配置文件 → 终端
3. 启用”静音铃声”和”空闲时发送通知”
4. 设置您首选的通知延迟

请注意，这些通知特定于 iTerm 2，在默认的 macOS 终端中不可用。

​

处理大量输入

处理大量代码或长指令时：

• 避免直接粘贴：Claude Code 可能难以处理非常长的粘贴内容
• 使用基于文件的工作流程：将内容写入文件并要求 Claude 读取
• 注意 VS Code 限制：VS Code 终端特别容易截断长粘贴

​

Vim 模式

Claude Code 支持 Vim 键绑定的子集，可以通过 /vim 启用或通过 /config 配置。

支持的子集包括：

• 模式切换：Esc（到 NORMAL），i/I，a/A，o/O（到 INSERT）
• 导航：h/j/k/l，w/e/b，0/$/^，gg/G
• 编辑：x，dw/de/db/dd/D，cw/ce/cb/cc/C，.（重复）

​

有效管理成本

Claude Code 为每次交互消耗令牌。平均成本为每位开发者每天 $6，90% 的用户每日成本保持在 $12 以下。

​

跟踪您的成本

• 使用 /cost 查看当前会话使用情况
• Anthropic Console 用户：
  • 在 Anthropic Console 中查看历史使用情况（需要管理员或计费角色）
  • 为 Claude Code 工作区设置工作区支出限制（需要管理员角色）
• Max 计划用户：使用包含在您的 Max 计划订阅中

​

减少令牌使用

• 压缩对话：

  • Claude 在上下文超过 95% 容量时默认使用自动压缩

  • 切换自动压缩：运行 /config 并导航到”启用自动压缩”

  • 当上下文变大时手动使用 /compact

  • 添加自定义指令：/compact 专注于代码示例和 API 使用

  • 通过添加到 CLAUDE.md 自定义压缩：

    # 摘要指令
    
    当您使用压缩时，请专注于测试输出和代码更改
    

• 编写具体查询： 避免触发不必要扫描的模糊请求

• 分解复杂任务： 将大型任务分解为重点交互

• 在任务之间清除历史记录： 使用 /clear 重置上下文

成本可能因以下因素而显著变化：

• 被分析的代码库大小
• 查询复杂性
• 被搜索或修改的文件数量
• 对话历史长度
• 压缩对话的频率

​

模型配置

默认情况下，Claude Code 使用 claude-opus-4-20250514。您可以使用以下环境变量覆盖此设置：

# Anthropic API
ANTHROPIC_MODEL='claude-opus-4-20250514'
ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku-20241022'

# Amazon Bedrock
ANTHROPIC_MODEL='us.anthropic.claude-opus-4-20250514-v1:0'
ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-3-5-haiku-20241022-v1:0'

# Google Vertex AI
ANTHROPIC_MODEL='claude-opus-4@20250514'
ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

您也可以使用全局配置设置这些变量：

# 为 Anthropic API 配置
claude config set --global env '{"ANTHROPIC_MODEL": "claude-opus-4-20250514"}'

# 为 Bedrock 配置
claude config set --global env '{"CLAUDE_CODE_USE_BEDROCK": "true", "ANTHROPIC_MODEL": "us.anthropic.claude-opus-4-20250514-v1:0"}'

# 为 Vertex AI 配置
claude config set --global env '{"CLAUDE_CODE_USE_VERTEX": "true", "ANTHROPIC_MODEL": "claude-opus-4@20250514"}'

​

与第三方 API 一起使用

​

连接到 Amazon Bedrock

CLAUDE_CODE_USE_BEDROCK=1

如果您想通过代理访问 Claude Code，可以使用 ANTHROPIC_BEDROCK_BASE_URL 环境变量：

ANTHROPIC_BEDROCK_BASE_URL='https://your-proxy-url'

如果您没有启用提示缓存，还需设置：

DISABLE_PROMPT_CACHING=1

需要标准 AWS SDK 凭证（例如，~/.aws/credentials 或相关环境变量，如 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY）。要设置 AWS 凭证，请运行：

aws configure

联系 Amazon Bedrock 获取提示缓存，以降低成本并提高速率限制。

​

连接到 Google Vertex AI

CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

如果您想通过代理访问 Claude Code，可以使用 ANTHROPIC_VERTEX_BASE_URL 环境变量：

ANTHROPIC_VERTEX_BASE_URL='https://your-proxy-url'

如果您没有启用提示缓存，还需设置：

DISABLE_PROMPT_CACHING=1

需要通过 google-auth-library 配置的标准 GCP 凭证。要设置 GCP 凭证，请运行：

gcloud auth application-default login

为获得最佳体验，请联系 Google 获取更高的速率限制。

​

通过代理连接

当使用 LLM 代理（如 LiteLLM）与 Claude Code 一起使用时，您可以使用以下环境变量和配置控制身份验证行为。请注意，您可以将这些与 Bedrock 和 Vertex 特定设置混合使用。

​

环境变量

• ANTHROPIC_AUTH_TOKEN：Authorization 和 Proxy-Authorization 头的自定义值（您在此处设置的值将以 Bearer 为前缀）
• ANTHROPIC_CUSTOM_HEADERS：您想添加到请求的自定义头（采用 Name: Value 格式）
• HTTP_PROXY：设置 HTTP 代理 URL
• HTTPS_PROXY：设置 HTTPS 代理 URL

如果您更喜欢通过文件而不是环境变量进行配置，可以将这些变量添加到全局 Claude 配置中的 env 对象（在 ~/.claude.json 中）。

​

全局配置选项

• apiKeyHelper：获取 API 密钥的自定义 shell 脚本（在启动时调用一次，并在每个会话期间缓存）

​

开发容器参考实现

Claude Code 为需要一致、安全环境的团队提供开发容器配置。这个预配置的 devcontainer 设置与 VS Code 的 Remote - Containers 扩展和类似工具无缝协作。

容器的增强安全措施（隔离和防火墙规则）允许您运行 claude --dangerously-skip-permissions 以绕过权限提示，实现无人值守操作。我们提供了一个参考实现，您可以根据需要进行自定义。

​

主要特点

• 生产就绪的 Node.js：基于 Node.js 20，带有基本开发依赖
• 安全设计：自定义防火墙仅限制网络访问必要服务
• 开发者友好工具：包括 git、带生产力增强的 ZSH、fzf 等
• 无缝 VS Code 集成：预配置扩展和优化设置
• 会话持久性：在容器重启之间保留命令历史和配置
• 随处可用：兼容 macOS、Windows 和 Linux 开发环境

​

4 步入门

1. 安装 VS Code 和 Remote - Containers 扩展
2. 克隆 Claude Code 参考实现仓库
3. 在 VS Code 中打开仓库
4. 当提示时，点击”在容器中重新打开”（或使用命令面板：Cmd+Shift+P → “Remote-Containers: Reopen in Container”）

​

配置细分

devcontainer 设置由三个主要组件组成：

• devcontainer.json：控制容器设置、扩展和卷挂载
• Dockerfile：定义容器镜像和安装的工具
• init-firewall.sh：建立网络安全规则

​

安全特性

容器通过其防火墙配置实现多层安全方法：

• 精确访问控制：仅限制出站连接到白名单域（npm 注册表、GitHub、Anthropic API 等）
• 默认拒绝策略：阻止所有其他外部网络访问
• 启动验证：在容器初始化时验证防火墙规则
• 隔离：创建与主系统分离的安全开发环境

​

自定义选项

devcontainer 配置设计为适应您的需求：

• 根据您的工作流程添加或删除 VS Code 扩展
• 为不同硬件环境修改资源分配
• 调整网络访问权限
• 自定义 shell 配置和开发工具

​

后续步骤

​

许可和数据使用

Claude Code 作为 Beta 研究预览版根据 Anthropic 的商业服务条款提供。

​

我们如何使用您的数据

我们旨在完全透明地说明我们如何使用您的数据。我们可能会使用反馈来改进我们的产品和服务，但我们不会使用您从 Claude Code 提供的反馈来训练生成模型。鉴于其潜在的敏感性，我们仅存储用户反馈记录 30 天。

​

反馈记录

如果您选择向我们发送关于 Claude Code 的反馈，例如您使用情况的记录，Anthropic 可能会使用该反馈来调试相关问题并改进 Claude Code 的功能（例如，减少类似错误在未来发生的风险）。我们不会使用此反馈来训练生成模型。

​

隐私保障

我们已实施多项保障措施来保护您的数据，包括敏感信息的有限保留期、对用户会话数据的访问限制，以及明确禁止使用反馈进行模型训练的政策。

有关完整详情，请查看我们的商业服务条款和隐私政策。

​

许可

© Anthropic PBC. 保留所有权利。使用受 Anthropic 的商业服务条款约束。