Claude Code CLI：权威技术参考指南
更新于 2025 年 12 月 12 日
2025 年 12 月更新： Claude Code 现已为企业工程工作流提供支持，包括智能多文件编辑、与 300 多个外部服务的 MCP 协议集成、用于复杂任务的专业子代理，以及用于 CI/CD 自动化的钩子系统。权限系统支持细粒度的安全控制。在 Haiku（快速/经济）和 Opus（强大）模型之间切换，可优化成本与性能的平衡。
在过去几个月里，我在生产代码库、CI/CD 流水线和企业部署中深入测试了 Claude Code 的极限。本指南将这些经验浓缩为我刚开始使用时就希望拥有的完整参考资料。内容涵盖从首次安装到大多数用户从未发现的高级模式。
Claude Code 不是一个碰巧懂编程的聊天界面。它是一个智能代理系统，能够读取你的代码库、执行命令、修改文件、管理 git 工作流、连接外部服务，并将复杂任务委派给专业子代理——所有这些都通过命令行界面完成，与开发者的实际工作方式无缝集成。
随意使用 Claude Code 与高效使用它之间的差异，在于理解其架构：控制行为的配置层级、门控操作的权限系统、实现确定性自动化的钩子系统、扩展功能的 MCP 协议，以及处理复杂多步骤任务的子代理系统。掌握这些系统，Claude Code 将成为效率倍增器。忽视它们，你将错失大部分价值。
本指南假设你熟悉命令行工具，并希望获得完整的技术全貌。每个功能都配有实际语法、真实配置示例，以及困扰资深用户的边缘情况。无论你是首次设置项目还是在企业工程组织中进行部署，所需信息尽在其中。
Claude Code 工作原理：心智模型
在深入了解功能之前，首先理解 Claude Code 的架构如何影响你的使用方式。系统分为三个层次：
┌─────────────────────────────────────────────────────────┐
│ CLAUDE CODE 层级 │
├─────────────────────────────────────────────────────────┤
│ 扩展层 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ MCP │ │ 钩子 │ │ 技能 │ │ 插件 │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ 外部工具、确定性自动化、领域 │
│ 专业知识、打包的扩展 │
├─────────────────────────────────────────────────────────┤
│ 委派层 │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 子代理（最多 10 个并行） │ │
│ │ Explore | Plan | General-purpose | Custom │ │
│ └─────────────────────────────────────────────────┘ │
│ 隔离的上下文用于专注工作，返回摘要 │
├─────────────────────────────────────────────────────────┤
│ 核心层 │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 主对话上下文 │ │
│ │ 工具：Read, Edit, Bash, Glob, Grep 等 │ │
│ └─────────────────────────────────────────────────┘ │
│ 你的主要交互；有限的上下文；产生费用 │
└─────────────────────────────────────────────────────────┘
核心层：你的主对话。每条消息、文件读取和工具输出都会消耗共享的 200K token 窗口（高级版为 1M）中的上下文。当上下文填满时，Claude 会丢失早期决策的追踪，质量随之下降。此层按 token 计费。
委派层：子代理以干净的上下文启动，完成专注的工作，然后返回摘要。探索结果不会膨胀你的主对话——只有结论会返回。使用 Haiku 子代理进行探索（经济、快速），使用 Sonnet 进行实现。
扩展层：MCP 连接外部服务（数据库、GitHub、Sentry）。钩子保证 shell 命令的执行，不受模型行为影响。技能编码领域专业知识，Claude 会自动应用。插件将所有这些打包以便分发。
关键洞察：大多数用户完全在核心层工作，眼看上下文膨胀、成本攀升。高级用户将探索和专业工作推送到委派层，为工作流配置扩展层，仅使用核心层进行编排和最终决策。
目录
- 安装和认证
- 核心交互模式
- 配置系统深入解析
- 模型选择和切换
- 权限系统和安全
- 钩子系统
- MCP（模型上下文协议）
- 子代理和任务委派
- 扩展思考模式
- 输出样式
- 斜杠命令
- 技能
- 插件系统
- 内存和上下文管理
- 图像和多模态输入
- Git 集成和工作流
- IDE 集成
- 高级使用模式
- Claude Code Remote
- 后台代理（2025 年 12 月）
- 成本管理和计费
- 性能优化
- 故障排除和调试
- 企业部署
- 键盘快捷键参考
- 最佳实践
安装和认证
系统要求
Claude Code 可在 macOS 10.15+、Ubuntu 20.04+/Debian 10+ 以及 Windows 10+（通过 WSL 或 Git Bash）上运行。系统需要至少 4 GB RAM 和活跃的网络连接。Shell 兼容性在 Bash、Zsh 或 Fish 下效果最佳。
对于 Windows，WSL 1 和 WSL 2 都可以使用。如果你更喜欢原生 Windows，Git Bash 也可以。Alpine Linux 和其他基于 musl 的系统需要额外的包：
apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0
安装方法
原生安装（推荐）
原生二进制文件提供最干净的体验，无需 Node.js 依赖：
# macOS 和 Linux
curl -fsSL https://claude.ai/install.sh | bash
# Homebrew 替代方案
brew install --cask claude-code
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
安装特定版本：
# 安装特定版本
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
# 显式安装最新版
curl -fsSL https://claude.ai/install.sh | bash -s latest
# Windows PowerShell - 特定版本
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
NPM 安装
对于偏好 npm 的环境：
npm install -g @anthropic-ai/claude-code
永远不要使用 sudo 进行 npm 安装——这会造成权限问题，使后续一切变得复杂。
从现有安装迁移
如果你有较旧的基于 npm 的安装，请迁移到原生二进制文件：
claude install
认证选项
Claude Code 支持三种认证路径，各有不同的权衡：
Claude 控制台（API 计费）
直接通过 console.anthropic.com 连接到 Anthropic 的 API。创建账户，设置计费，并通过 CLI 进行认证。这提供按使用量计费的完整 API 访问。系统会自动创建一个专用的"Claude Code"工作区——你无法为此工作区创建 API 密钥，但可以监控使用情况。
Claude Pro 或 Max 订阅
使用你的 claude.ai 账户凭据。订阅涵盖 Web 界面和 CLI 使用，统一在单一月度计划下。这简化了希望获得可预测成本的个人用户的计费。
企业平台
AWS Bedrock、Google Vertex AI 和 Microsoft Foundry 各自提供企业级访问，使用现有的云计费关系：
# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile
# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project
# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# 可选：API 密钥认证（否则使用 Entra ID）
export ANTHROPIC_FOUNDRY_API_KEY=your-key
对于代理后面或通过 LLM 网关的企业部署：
# 企业代理
export HTTPS_PROXY='https://proxy.example.com:8080'
# LLM 网关（跳过原生认证）
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
验证
claude doctor
这会报告安装类型、版本、系统配置和检测到的任何问题。
更新
Claude Code 默认自动更新，在启动时和会话期间定期检查。更新在后台下载，并在下次启动时应用。
禁用自动更新：
export DISABLE_AUTOUPDATER=1
或在 settings.json 中：
{
"env": {
"DISABLE_AUTOUPDATER": "1"
}
}
手动更新：
claude update
卸载
原生安装（macOS/Linux/WSL）：
rm -f ~/.local/bin/claude
rm -rf ~/.claude-code
原生安装（Windows PowerShell）：
Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force
清理配置（删除所有设置）：
rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json
核心交互模式
交互式 REPL
不带参数启动 Claude Code 进入交互式读取-求值-打印循环：
cd your-project
claude
REPL 在多轮对话中维护上下文。直接输入查询，接收响应，继续直到使用 /exit 或 Ctrl+D 退出。
使用初始提示词启动以聚焦会话：
claude "解释这个项目中的认证流程"
专家提示： REPL 在压缩事件中保持状态。当上下文变得过大时，Claude 会自动总结较旧的对话，同时保留关键决策和代码片段。你可以使用 /compact 手动触发此操作，或添加自定义指令说明要保留的内容。
非交互模式
打印模式（-p）执行单个查询后退出：
# 直接查询
claude -p "列出这个项目中的所有 TODO 注释"
# 处理管道输入
cat error.log | claude -p "识别这些失败的根本原因"
# 与其他工具链接
claude -p "生成一个 README" > README.md
对于适合在脚本中解析的结构化输出：
claude -p "按文件类型统计行数" --output-format json
JSON 输出包含自动化所需的所有内容：
{
"type": "result",
"subtype": "success",
"total_cost_usd": 0.0034,
"is_error": false,
"duration_ms": 2847,
"duration_api_ms": 1923,
"num_turns": 4,
"result": "响应文本在这里...",
"session_id": "abc-123-d
[内容因翻译而截断]
