Claude Code 概述

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 默认使用 claude-3-7-sonnet-20250219。

​

安全性和隐私设计

你的代码安全至关重要。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
> 哪个提交在十二月添加了 markdown 测试？
> 在 main 分支上变基并解决任何合并冲突

​

智能编辑代码

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

​

测试和调试代码

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

​

鼓励深入思考

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

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

当 Claude (3.7 Sonnet) 使用扩展思考时，Claude Code 会显示提示。你可以主动提示 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:*)" Edit

​

使用命令控制 Claude Code

​

CLI 命令

CLI 标志：

• --print：在非交互模式下打印响应
• --verbose：启用详细日志记录
• --dangerously-skip-permissions：跳过权限提示（仅在没有互联网的 Docker 容器中）

​

斜线命令

在会话中控制 Claude 的行为：

​

管理权限和安全性

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

​

Claude 可用的工具

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

​

防止提示注入

提示注入是攻击者试图通过插入恶意文本来覆盖或操纵 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 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/**"

​

优化你的终端设置

当你的终端正确配置时，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 终端特别容易截断长粘贴内容

通过配置这些设置，你将创建一个更流畅、更高效的 Claude Code 工作流程。

​

有效管理成本

Claude Code 为每次交互消耗令牌。典型使用成本每个开发者每天在 5-10 美元之间，但在密集使用期间可能超过每小时 100 美元。

​

跟踪你的成本

• 使用 /cost 查看当前会话使用情况
• 查看退出时显示的成本摘要
• 在 Anthropic Console 中检查历史使用情况
• 设置支出限制

​

减少令牌使用

• 压缩对话： 当上下文变大时使用 /compact
• 编写具体查询： 避免触发不必要扫描的模糊请求
• 分解复杂任务： 将大任务分解为重点交互
• 任务间清除历史： 使用 /clear 重置上下文

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

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

​

使用第三方 API

​

连接到 Amazon Bedrock

CLAUDE_CODE_USE_BEDROCK=1

如果你想覆盖默认模型，可以传入 ANTHROPIC_MODEL 环境变量（默认使用 Claude 3.7 Sonnet）：

ANTHROPIC_MODEL='us.anthropic.claude-3-7-sonnet-20250219-v1:0'

如果你想通过代理访问 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

如果你想覆盖默认模型，可以传入 ANTHROPIC_MODEL 环境变量（默认使用 Claude 3.7 Sonnet）：

ANTHROPIC_MODEL='us.anthropic.claude-3-7-sonnet-20250219-v1:0'

如果你想通过代理访问 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 获取更高的速率限制。

​

开发容器参考实现

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 作为测试版研究预览版根据 Anthropic 的商业服务条款提供。

​

我们如何使用你的数据

我们旨在完全透明地说明我们如何使用你的数据。我们可能使用反馈来改进我们的产品和服务，但我们不会使用你在 Claude Code 中的反馈来训练生成模型。考虑到它们可能的敏感性，我们只将用户反馈记录存储 30 天。

​

反馈记录

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

​

隐私保护措施

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

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

​

许可

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