了解由 Anthropic 开发的智能体式编程工具 Claude Code（编者注：这有别于Cursor等聊天式编程工具），目前作为研究预览版处于测试阶段。
npm install -g @anthropic-ai/claude-code
请勿使用 sudo npm install -g，这可能导致权限问题和安全风险。若遇到权限错误，可参考 配置 Claude Code 获得推荐解决方案。
Claude Code 是一款运行在终端中的智能体编码工具，它能理解你的代码库，并通过自然语言命令帮助你更快地编写代码。通过直接集成到开发环境中，Claude Code 无需额外服务器或复杂设置即可简化你的工作流程。
Claude Code 的核心功能，包括：
跨代码库编辑文件和修复 bug 解答关于代码架构和逻辑的问题 执行和修复测试、代码检查（linting）等命令 搜索 git 历史、解决合并冲突，以及创建提交和拉取请求（PR）
研究预览版
当前代码作为研究预览版处于测试阶段。我们正在收集开发者对 AI 协作偏好的反馈，哪些工作流程最受益于 AI 辅助，以及如何优化智能体体验。
这个早期版本将根据用户反馈不断演进。未来几周内，我们计划提升工具执行的可靠性、对长时间运行命令的支持、终端渲染效果，以及 Claude 对自身能力的认知。
如需报告 bug，可直接使用 /bug 命令或通过我们的 GitHub 仓库 提交。
开始前准备
检查系统要求
- 操作系统：macOS 10.15+、Ubuntu 20.04+/Debian 10+，或通过 WSL 在 Windows 上运行
- 硬件：至少 4GB RAM
- 软件：
Node.js 18+ git 2.23+（可选） 用于 PR 工作流程的 GitHub 或 GitLab CLI（可选） 用于增强文件搜索的 ripgrep（rg，可选） - 网络：需要互联网连接进行身份验证和 AI 处理
- 地区：仅在支持的国家/地区可用
解决 WSL 安装问题
目前 Claude Code 无法直接在 Windows 上运行，需通过 WSL 使用。若在 WSL 中遇到问题：
- 操作系统/平台检测问题：安装时若报错，可能是 WSL 使用了 Windows 的 npm。尝试：
安装前运行 npm config set os linux
使用 npm install -g @anthropic-ai/claude-code --force --no-os-check 安装（请勿使用 sudo） - 找不到 Node 错误：运行
claude时若出现exec: node: not found，可能是 WSL 环境使用了 Windows 的 Node.js 安装。可通过which npm和which node确认路径，正确路径应以/usr/开头（Linux 路径）而非/mnt/c/（Windows 路径）。解决方法：尝试通过 Linux 发行版的包管理器或nvm安装 Node。
安装与认证
安装 Claude Code
在终端运行：npm install -g @anthropic-ai/claude-code请勿使用
sudo npm install -g，这可能导致权限问题和安全风险。若遇到权限错误，可参考 配置 Claude Code 获得推荐解决方案。进入项目目录
cd 你的项目目录启动 Claude Code
运行claude启动工具完成认证
按照提示通过 Console 账户完成一次性 OAuth 认证流程。需在 console.anthropic.com 开启有效计费功能。
核心功能与工作流程
Claude Code 直接在终端中运行，理解项目上下文并执行实际操作。无需手动添加文件到上下文中，Claude 会根据需要自动探索代码库。默认使用 claude-3-7-sonnet-20250219 模型。
安全与隐私设计
代码安全至关重要，Claude Code 的架构确保：
直接 API 连接：查询直接发送至 Anthropic API，无中间服务器 本地运行：直接在终端中操作，无需上传代码 上下文感知：保持对整个项目结构的认知 执行操作：支持文件编辑、创建提交等真实操作
秒级从问题到解决方案
# 询问代码库相关问题
claude > 我们的认证系统如何工作？
# 一键创建提交
claude commit
# 修复多个文件中的问题
claude "修复认证模块中的类型错误"
初始化项目
首次使用建议：
运行 claude启动工具尝试简单命令如 summarize this project（总结项目）使用 /init生成 CLAUDE.md 项目指南让 Claude 将生成的 CLAUDE.md 提交到代码仓库
常见任务使用场景
Claude Code 直接在终端中运行，理解项目上下文并执行实际操作，无需手动添加文件到上下文中。
理解陌生代码
> 支付处理系统的功能是什么？
> 查找用户权限检查的位置
> 解释缓存层的工作原理
自动化 Git 操作
> 提交我的更改
> 创建拉取请求
> 去年 12 月哪个提交添加了 Markdown 测试？
> 基于 main 分支变基并解决合并冲突
智能编辑代码
> 为注册表单添加输入验证
> 重构日志器以使用新 API
> 修复工作队列中的竞态条件
测试与调试代码
> 运行认证模块的测试并修复失败用例
> 查找并修复安全漏洞
> 解释这个测试失败的原因
引导深度思考
处理复杂问题时，显式要求 Claude 深度思考：
> 思考如何设计新支付服务的架构
> 仔细考虑认证流程中的边缘情况
当 Claude（3.7 Sonnet）使用扩展思考时会显示提示。建议先描述任务让 Claude 收集项目上下文，再要求其 “思考” 以制定计划。使用 “think hard” 等关键词会触发更深度的思考。
自动化 CI 和基础设施工作流程
Claude Code 支持非交互式模式（无头执行），适用于脚本、流水线和 GitHub Actions 等场景。
使用 --print（-p）进入非交互式模式，可通过环境变量 ANTHROPIC_API_KEY 提供自定义 API 密钥：
exportANTHROPIC_API_KEY=sk_...
claude -p "用最新更改更新 README"--allowedTools"Bash(git diff:*)""Bash(git log:*)" Edit
用命令控制 Claude Code
CLI 命令
claude | claude | |
claude "query" | claude "解释这个项目" | |
claude -p "query" | claude -p "解释这个函数" | |
claude config | claude config set --global theme dark | |
claude update | claude update | |
claude MCP |
CLI 标志：
--print：打印响应而不进入交互模式--verbose：启用详细日志--dangerously-skip-permissions：跳过权限提示（仅在无网络的 Docker 容器中使用）
斜杠命令（会话内控制）
/bug | |
/clear | |
/compact | |
/config | |
/cost | |
/doctor | |
/help | |
/init | |
/login | |
/logout | |
/pr_comments | |
/review | |
/terminal-setup | |
/vim |
权限与安全管理
Claude Code 使用分层权限系统平衡功能与安全性：
Claude 可用工具
防范提示注入攻击
提示注入是攻击者试图通过恶意文本覆盖或操纵 AI 指令的技术。Claude Code 包含多重防护：
权限系统：敏感操作需显式审批 上下文感知分析：通过分析完整请求检测潜在有害指令 输入净化：处理用户输入以防止命令注入 命令黑名单：阻止 curl、wget等从网络获取任意内容的危险命令
处理不可信内容的最佳实践：
审批前审查建议的命令 避免直接将不可信内容通过管道传给 Claude 验证关键文件的修改建议 发现可疑行为时用 /bug报告
尽管这些保护措施显著降低风险，但没有系统能完全抵御所有攻击。使用任何 AI 工具时均需保持良好的安全习惯。
配置网络访问
Claude Code 需要访问以下地址：
api.anthropic.com statsig.anthropic.com sentry.io
在容器化环境中使用时，请将这些 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>
默认修改项目配置，如需管理全局配置，使用 --global（或 -g）标志。
全局配置
通过 claude config set -g <key> <value> 设置全局配置：
autoUpdaterStatus | disabledenabled | enabled） |
preferredNotifChannel | iterm2iterm2_with_bell, terminal_bell, notifications_disabled | iterm2） |
theme | darklight, light-daltonized, dark-daltonized | |
verbose | truefalse | false） |
自动更新权限选项
当 Claude Code 检测到无足够权限写入全局 npm 前缀目录（自动更新所需），会显示警告。详细解决方案见 故障排除指南。
推荐方案：创建用户可写的 npm 前缀目录
# 1. 备份现有全局包
npm list -g--depth=0> ~/npm-global-packages.txt
# 2. 创建新目录
mkdir -p ~/.npm-global
# 3. 配置 npm 使用新路径
npm config set prefix ~/.npm-global
# 4. 更新 PATH（根据 shell 类型修改文件，如 ~/.zshrc、~/.profile 等）
echo ‘export PATH=~/.npm-global/bin:$PATH'>> ~/.bashrc
source ~/.bashrc
# 5. 重新安装 Claude Code
npm Install -g @anthropic-ai/claude-code
# （可选）恢复原有全局包
# npm install -g $(cat ~/npm-global-packages.txt | grep -oP '(?<=`).*(?=`)')
推荐原因：避免修改系统目录权限，创建专用全局包位置，遵循安全最佳实践。
禁用自动更新
若选择禁用而非修复权限：
claude config set -g autoUpdaterStatus disabled
项目配置
通过 claude config set <key> <value> 管理项目配置（无 -g 标志）：
allowedTools | ||
ignorePatterns |
示例：
# 允许 npm test 无需审批
claude config add allowedTools "Bash(npm test)"
# 允许 npm test 及其子命令
claude config add allowedTools "Bash(npm test:*)"
# 忽略 node_modules
claude config add ignorePatterns node_modules
claude config add ignorePatterns "node_modules/**"
优化终端设置
Claude Code 在终端配置正确时效果最佳，按以下指南优化体验：
支持的 Shell：
Bash Zsh Fish
主题与外观
Claude 无法控制终端主题（由终端应用决定），可在首次设置或通过 /config 命令匹配 Claude Code 主题与终端主题。
换行输入
支持多种换行方式：
快速转义：输入 \<后按 Enter 生成换行键盘快捷键：配置后按 Option+Enter（Meta+Enter）
配置 Option+Enter 快捷键：
- Mac Terminal.app：进入设置 → 配置文件 → 键盘，勾选 “将 Option 键用作 Meta 键”
- iTerm2 和 VSCode 终端：进入设置 → 配置文件 → 按键，将左右 Option 键设置为 “Esc+”
提示：在 iTerm2 和 VSCode 中运行/terminal-setup可自动配置 Shift+Enter 作为更直观的替代方案。
通知设置
通过配置确保不遗漏任务完成提示：
终端铃声通知
启用任务完成声音提醒：
claude config set--global preferredNotifChannel terminal_bell
macOS 用户需在系统设置 → 通知 → [终端应用] 中启用通知权限。
iTerm 2 系统通知
配置 iTerm 2 任务完成提醒：
打开 iTerm 2 偏好设置 进入配置文件 → 终端 启用 “静音铃声” 和 “空闲时发送通知” 设置偏好的通知延迟
注意：此功能仅适用于 iTerm 2，默认 macOS 终端不支持。
处理大输入
处理大量代码或长指令时：
避免直接粘贴：过长内容可能导致 Claude 处理困难 使用文件工作流：将内容写入文件后让 Claude 读取 注意 VS Code 限制：其终端易截断长粘贴内容
有效管理成本
Claude Code 每次交互消耗 token，典型使用成本为每位开发者每天 5-10 美元，密集使用时每小时可能超过 100 美元。
跟踪成本
使用 /cost查看当前会话用量退出时查看成本摘要 在 Anthropic Console 查看历史用量
控制支出
减少 token 消耗
压缩对话：上下文过大时使用 /compact精准提问：避免触发不必要扫描的模糊请求 拆分任务：将复杂任务分解为专注的交互 清除历史：任务间用 /clear重置上下文
成本因以下因素差异较大：
分析的代码库大小 查询复杂度 搜索/修改的文件数量 对话历史长度 压缩对话的频率
团队部署时，建议先通过小规模试点建立使用模式，再全面推广。
与第三方 API 配合使用
无论使用哪家 API 提供商，Claude Code 均需访问 Claude 3.7 Sonnet 和 3.5 Haiku 模型。
连接 Amazon Bedrock
CLAUDE_CODE_USE_BEDROCK=1
如需覆盖默认模型，通过环境变量设置：
ANTHROPIC_MODEL='us.anthropic.claude-3-7-sonnet-20250219-v1:0'
如需通过代理访问：
ANTHROPIC_BEDROCK_BASE_URL='https://你的代理地址'
若未启用提示缓存，同时设置：
DISABLE_PROMPT_CACHING=1
需配置标准 AWS SDK 凭证（如 ~/.aws/credentials 或环境变量 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY），通过 aws configure 完成设置。
如需降低成本和提高速率限制，联系 Amazon Bedrock 启用提示缓存。
用户需在 AWS 账户中拥有 Claude 3.7 Sonnet 和 3.5 Haiku 模型的访问权限，必要时申请权限。
连接 Google Vertex AI
CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=你的项目 ID
如需覆盖默认模型：
ANTHROPIC_MODEL='us.anthropic.claude-3-7-sonnet-20250219-v1:0'
如需通过代理访问：
ANTHROPIC_VERTEX_BASE_URL='https://你的代理地址'
若未启用提示缓存，同时设置：
DISABLE_PROMPT_CACHING=1
Claude Code on Vertex AI 目前仅支持 us-east5 区域，确保项目在此区域分配了配额。
需通过 google-auth-library 配置标准 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 步上手
安装 VS Code 和 Remote - Containers 扩展 克隆 Claude Code 参考实现仓库 在 VS Code 中打开仓库 提示时点击 “在容器中重新打开”（或通过命令面板：Cmd+Shift+P → “Remote-Containers: 在容器中重新打开”）
配置分解
包含三个主要组件：
devcontainer.json：控制容器设置、扩展和卷挂载 Dockerfile：定义容器镜像和安装工具 init-firewall.sh：建立网络安全规则
安全特性
容器通过防火墙实现多层安全：
精准访问控制：仅允许连接白名单域名（npm 仓库、GitHub、Anthropic API 等） 默认拒绝策略：阻止所有其他外部网络访问 启动验证：容器初始化时验证防火墙规则 隔离性：创建与主机系统分离的安全开发环境
自定义选项
可根据需求调整：
添加/删除 VS Code 扩展 修改不同硬件环境的资源分配 调整网络访问权限 自定义 shell 配置和开发工具
