Anthropic官方：Claude Code - 安装配置手册

显示全部楼层

Claude Code 概述

了解由 Anthropic 开发的智能体式编程工具Claude Code（编者注：这有别于Cursor等聊天式编程工具），目前作为研究预览版处于测试阶段。

npminstall-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。尝试：
安装前运行npmconfigsetos linux 使用npminstall-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
在终端运行：
```
npminstall-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`	启动交互式 REPL	`claude`
`claude "query"`	启动 REPL 并附带初始提示	`claude "解释这个项目"`
`claude -p "query"`	执行单次查询后退出	`claude -p "解释这个函数"`
`cat file	claude -p "query"`	处理管道输入内容
`claude config`	配置设置	`claude config set --global theme dark`
`claude update`	更新到最新版本	`claude update`
`claude MCP`	配置模型上下文协议（MCP）服务器	见教程中的 MCP 部分

CLI 标志：

--print：打印响应而不进入交互模式
--verbose：启用详细日志
--dangerously-skip-permissions：跳过权限提示（仅在无网络的 Docker 容器中使用）

斜杠命令（会话内控制）

命令	用途
`/bug`	报告 bug（将对话发送给 Anthropic）
`/clear`	清除对话历史
`/compact`	压缩对话以节省上下文空间
`/config`	查看/修改配置
`/cost`	显示 token 使用统计信息
`/doctor`	检查 Claude Code 安装状态
`/help`	获取使用帮助
`/init`	用 CLAUDE.md 指南初始化项目
`/login`	切换 Anthropic 账户
`/logout`	退出 Anthropic 账户登录
`/pr_comments`	查看拉取请求评论
`/review`	请求代码审查
`/terminal-setup`	安装 Shift+Enter 换行快捷键（仅 iTerm2 和 VSCode）
`/vim`	进入 Vim 模式（切换插入和命令模式）

权限与安全管理

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

工具类型	示例	审批要求	“是，不再询问” 行为
只读	文件读取、LS、Grep	无需	无
Bash 命令	shell 执行	需要	按项目目录和命令永久授权
文件修改	编辑/写入文件	需要	仅在当前会话有效

Claude 可用工具

工具	描述	权限要求
AgentTool	运行子智能体处理复杂多步骤任务	无需
BashTool	在环境中执行 shell 命令	需要
GlobTool	按模式匹配查找文件	无需
GrepTool	在文件内容中搜索模式	无需
LSTool	列出文件和目录	无需
FileReadTool	读取文件内容	无需
FileEditTool	对特定文件进行目标编辑	需要
FileWriteTool	创建或覆盖文件	需要
NotebookReadTool	读取和显示 Jupyter 笔记本内容	无需
NotebookEditTool	修改 Jupyter 笔记本单元格	需要

防范提示注入攻击

提示注入是攻击者试图通过恶意文本覆盖或操纵 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`	`disabled` 或`enabled`	启用/禁用自动更新（默认：`enabled`）
`preferredNotifChannel`	`iterm2` ,`iterm2_with_bell`,`terminal_bell`,`notifications_disabled`	通知接收方式（默认：`iterm2`）
`theme`	`dark` ,`light`,`light-daltonized`,`dark-daltonized`	主题颜色
`verbose`	`true` 或`false`	是否显示完整 bash 和命令输出（默认：`false`）

自动更新权限选项

当 Claude Code 检测到无足够权限写入全局 npm 前缀目录（自动更新所需），会显示警告。详细解决方案见故障排除指南。
推荐方案：创建用户可写的 npm 前缀目录

# 1. 备份现有全局包
npmlist-g--depth=0>~/npm-global-packages.txt
# 2. 创建新目录
mkdir-p~/.npm-global
# 3. 配置 npm 使用新路径
npmconfigsetprefix ~/.npm-global
# 4. 更新 PATH（根据 shell 类型修改文件，如 ~/.zshrc、~/.profile 等）
echo‘export PATH=~/.npm-global/binPATH'>>~/.bashrc
source~/.bashrc
# 5. 重新安装 Claude Code
npmInstall-g@anthropic-ai/claude-code
# （可选）恢复原有全局包
# npm install -g $(cat ~/npm-global-packages.txt | grep -oP '(?<=`).*(?=`)')

推荐原因：避免修改系统目录权限，创建专用全局包位置，遵循安全最佳实践。

禁用自动更新

若选择禁用而非修复权限：

claude configset-gautoUpdaterStatus disabled

项目配置

通过claude config set <key> <value>管理项目配置（无-g标志）：

键	值	描述
`allowedTools`	工具数组	无需手动审批即可运行的工具
`ignorePatterns`	glob 字符串数组	使用工具时忽略的文件/目录

示例：

# 允许 npm test 无需审批
claude configaddallowedTools"Bash(npm test)"
# 允许 npm test 及其子命令
claude configaddallowedTools"Bash(npm test:*)"
# 忽略 node_modules
claude configaddignorePatterns node_modules
claude configaddignorePatterns"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 configset--globalpreferredNotifChannel 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 配置和开发工具

#编程智能体#AI编程 #Code #Claude #氛围编程