Claude Code 最新版本 完整使用手册

Claude Code - Anthropic 官方 CLI 工具，让 AI 直接在终端中协助您的编程工作

---

📖 目录

1. 工具简介
2. 快速开始
3. 核心概念
4. 命令详解
5. 使用场景
6. 最佳实践
7. 故障排除

---

📌 工具简介

Claude Code 是 Anthropic 官方提供的命令行工具，允许开发者直接在终端中使用 Claude 的 AI 能力来完成各种编程任务。

主要特点

• ✅ 终端原生 - 无需离开命令行即可获得 AI 辅助
• ✅ 代码库感知 - 自动理解和操作本地代码
• ✅ 交互式/批处理 - 支持对话模式和一次性输出
• ✅ 权限控制 - 细粒度的工具访问控制
• ✅ 会话持久化 - 可恢复之前的对话
• ✅ 多模型支持 - 支持 Opus、Sonnet、Haiku 等 Claude 模型

---

🚀 快速开始

安装

# 安装稳定版
claude-code install stable

# 或安装最新版
claude-code install latest

基础使用

# 交互式对话（默认模式）
claude-code "帮我优化这个函数"

# 打印模式（适用于管道）
claude-code -p "解释这段代码" < input.py

# 继续之前的对话
claude-code -c

---

🎯 核心概念

1. 会话模式

模式	说明	使用场景
交互式	默认模式，持续对话	复杂任务、多轮讨论
打印模式	-p，一次性输出	脚本集成、管道处理

2. 权限模式

模式	说明	安全级别
default	每次询问用户	🔒 最安全
acceptEdits	自动接受文件编辑	⚠️ 中等
dontAsk	自动执行所有操作	⚠️ 较低
plan	仅规划，不执行	🔒 最安全
bypassPermissions	完全跳过权限检查	❌ 仅沙箱

3. 模型选择

# 使用别名（推荐）
--model opus    # Claude Opus 4.6（最强）
--model sonnet  # Claude Sonnet 4.6（平衡）
--model haiku   # Claude Haiku 4.5（快速）

# 完整模型名
--model claude-opus-4-6

---

📚 命令详解

🔧 一、选项参数

1. 会话控制

--continue / -c

作用: 在当前目录继续最近的对话

使用场景:

• 你正在调试一个复杂问题，中断后想继续
• 多次迭代改进同一代码

# 第一次对话
claude-code "帮我实现用户认证功能"

# 中断后继续
claude-code -c "继续刚才的工作，添加登出功能"

---

--resume / -r

作用: 通过会话 ID 恢复对话

使用场景:

• 跨目录恢复之前的对话
• 团队共享会话上下文

# 直接指定会话 ID
claude-code -r abc123-def456

# 交互式选择会话
claude-code -r

# 带搜索词的选择
claude-code -r "认证功能"

---

--session-id

作用: 使用特定的会话 ID（必须是有效 UUID）

使用场景:

• 脚本中需要稳定会话标识
• 调试特定会话问题

claude-code --session-id "550e8400-e29b-41d4-a716-446655440000" "添加日志"

---

--print / -p

作用: 打印响应并退出

使用场景:

• 脚本自动化
• 管道操作
• CI/CD 集成

# 基础用法
claude-code -p "解释这段代码" < file.py

# 管道操作
cat error.log | claude-code -p "分析这些错误"

# 保存到文件
claude-code -p "生成 API 文档" > docs.md

---

--fork-session

作用: 恢复时创建新的会话 ID

使用场景:

• 从旧会话开始新工作
• 保留原始会话不变

# 基于会话 123 创建新会话
claude-code -r 123 --fork-session

---

2. 模型与智能体

--model

作用: 指定使用的模型

使用场景:

• 根据任务复杂度选择模型
• 成本优化（Haiku 更便宜）
• 速度需求（Haiku 更快）

# 简单任务用 Haiku（快、便宜）
claude-code --model haiku "这个函数有什么bug?"

# 复杂重构用 Opus（最强）
claude-code --model opus "重构整个项目架构"

---

--agent

作用: 指定当前会话的 agent

使用场景:

• 使用预配置的专用 agent
• 不同任务用不同 agent

claude-code --agent reviewer "审查我的代码"
claude-code --agent debugger "帮我调试"

---

--agents

作用: 用 JSON 定义自定义 agent

使用场景:

• 为特定项目定制 agent
• 团队标准化工作流

claude-code --agents '{
  "reviewer": {
    "description": "Reviews code for best practices",
    "prompt": "You are a senior code reviewer..."
  },
  "doc-writer": {
    "description": "Writes documentation",
    "prompt": "You are a technical writer..."
  }
}' --agent doc-writer "为这个函数写文档"

---

3. 权限与安全

--permission-mode

作用: 设置会话的权限模式

使用场景:

• 自动化脚本（acceptEdits）
• 安全审查（plan）
• 信任环境（dontAsk）

# 自动化脚本中自动接受编辑
claude-code --permission-mode acceptEdits -p "格式化代码"

# 只看计划不执行
claude-code --permission-mode plan "如何重构这个项目？"

# 完全信任的环境
claude-code --permission-mode dontAsk "运行测试并修复失败"

---

--allowed-tools / --disallowed-tools

作用: 明确允许/拒绝的工具列表

使用场景:

• 限制操作范围
• 安全敏感任务
• 只读分析

# 只允许读取和分析
claude-code --allowed-tools "Read,Grep" "分析代码结构"

# 禁止 git 操作
claude-code --disallowed-tools "Bash(git:*)" "解释代码"

# 组合使用
claude-code \
  --allowed-tools "Read,Edit,Grep" \
  --disallowed-tools "Bash(*:delete)" \
  "重构函数"

---

--dangerously-skip-permissions

作用: 完全跳过所有权限检查

⚠️ 仅用于: 无网络访问的沙箱环境

# 沙箱环境中使用
claude-code --dangerously-skip-permissions "处理数据"

---

4. 输出与调试

--output-format

作用: 设置输出格式（仅与 --print 配合）

使用场景:

• JSON API 集成
• 流式处理
• 机器解析

# 标准文本（默认）
claude-code -p --output-format text "分析代码"

# 单次 JSON 输出
claude-code -p --output-format json "生成配置" > config.json

# 实时流式 JSON
claude-code -p --output-format stream-json "长任务"

---

--debug / -d

作用: 启用调试模式

使用场景:

• 诊断工具问题
• 性能分析
• 开发 MCP 插件

# 启用所有调试
claude-code -d "测试"

# 过滤特定类别
claude-code -d "api,hooks" "测试"

# 排除类别
claude-code -d "!1p,!file" "测试"

# 输出到文件
claude-code --debug-file /tmp/debug.log "测试"

---

--verbose

作用: 覆盖详细模式设置

使用场景:

• 需要更多输出信息
• 了解执行详情

claude-code --verbose "详细解释这个错误"

---

5. 文件与资源

--file

作用: 下载文件资源到启动时

使用场景:

• 使用 Claude Code 共享的文件
• 多文件协作

# 格式: file_id:relative_path
claude-code \
  --file file_abc:source.py \
  --file file_def:image.png \
  "基于这些文件做什么？"

---

6. 集成功能

--chrome

作用: 启用 Chrome 集成

使用场景:

• 与浏览器配合工作
• Web 开发调试

claude-code --chrome "调试这个网页"

---

--ide

作用: 启动时自动连接 IDE

使用场景:

• IDE 集成开发
• 需要编辑器功能

# 自动检测并连接
claude-code --ide "重构这个组件"

---

--worktree / -w

作用: 创建新的 git worktree

使用场景:

• 并行开发多分支
• 隔离实验性工作
• 代码审查

# 创建命名 worktree
claude-code -w feature-new-api "实现新 API"

# 自动命名
claude-code -w "实验性功能"

# 与 tmux 配合
claude-code -w experiment --tmux "尝试这个想法"

---

--tmux

作用: 为 worktree 创建 tmux 会话

使用场景:

• 需要终端多面板
• 保持工作环境

# iTerm2 原生面板（默认）
claude-code -w bugfix --tmux "修复这个 bug"

# 传统 tmux
claude-code -w feature --tmux=classic "开发功能"

---

7. 高级选项

--max-budget-usd

作用: 限制 API 调用最大费用

使用场景:

• 成本控制
• 试用测试

claude-code -p --max-budget-usd 0.5 "生成大量代码"

---

--append-system-prompt / --system-prompt

作用: 追加/设置系统提示词

使用场景:

• 自定义行为
• 团队规范

# 完全替换
claude-code --system-prompt "你是 Python 专家" "分析代码"

# 追加
claude-code --append-system-prompt "始终使用中文" "解释"

---

--json-schema

作用: 结构化输出的 JSON Schema 验证

使用场景:

• 需要特定格式的输出
• API 集成

claude-code -p --json-schema '{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "count": {"type": "number"}
  },
  "required": ["name"]
}' "提取用户信息"

---

--betas

作用: 添加 Beta 功能头

使用场景:

• 测试新功能
• Beta 用户

claude-code --betas feature-1,feature-2 "测试"

---

8. 配置管理

--settings

作用: 从文件或 JSON 加载设置

使用场景:

• 项目配置
• 团队标准配置

# 从文件
claude-code --settings ./claude-config.json "任务"

# 从 JSON 字符串
claude-code --settings '{"model":"opus"}' "任务"

---

--setting-sources

作用: 指定加载设置的来源

使用场景:

• 覆盖默认配置加载

# 只加载项目设置
claude-code --setting-sources project "任务"

# 组合来源
claude-code --setting-sources user,project "任务"

---

--plugin-dir

作用: 为本次会话加载插件

使用场景:

• 临时使用插件
• 测试插件

claude-code --plugin-dir ./custom-plugins "任务"

---

9. MCP 服务器

--mcp-config

作用: 从 JSON 文件或字符串加载 MCP 服务器

使用场景:

• 使用 Model Context Protocol
• 集成外部工具

# 从文件
claude-code --mcp-config ./mcp-servers.json "任务"

# 从字符串
claude-code --mcp-config '{
  "filesystem": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]}
}' "任务"

# 严格模式（只使用指定的 MCP）
claude-code --strict-mcp-config --mcp-config config.json "任务"

---

--mcp-debug

作用: 启用 MCP 调试模式（显示服务器错误）

使用场景:

• 开发 MCP 服务器
• 诊断 MCP 问题

# 已废弃，建议使用
claude-code -d mcp "任务"

---

10. 其他选项

--no-chrome

作用: 禁用 Chrome 集成

claude-code --no-chrome "任务"

---

--no-session-persistence

作用: 禁用会话持久化

使用场景:

• 临时会话
• 隐私敏感

claude-code -p --no-session-persistence "敏感任务"

---

--tools

作用: 指定可用工具列表

使用场景:

• 限制工具集
• 安全操作

# 使用所有工具
claude-code --tools default "任务"

# 只用指定工具
claude-code --tools "Bash,Read" "任务"

# 禁用所有
claude-code --tools "" "只聊天"

---

--add-dir

作用: 额外允许工具访问的目录

使用场景:

• 多目录项目
• 符号链接目录

claude-code --add-dir ./shared --add-dir /external/libs "任务"

---

--include-partial-messages

作用: 包含部分消息块（仅限 stream-json）

claude-code -p --input-format stream-json --include-partial-messages

---

--input-format

作用: 输入格式

# 文本输入（默认）
claude-code --input-format text

# 流式 JSON
claude-code --input-format stream-json

---

--replay-user-messages

作用: 将 stdin 的用户消息重新发送回 stdout

claude-code -p \
  --input-format stream-json \
  --output-format stream-json \
  --replay-user-messages

---

--fallback-model

作用: 默认模型过载时自动回退

claude-code -p --fallback-model claude-sonnet-4-6 "任务"

---

--effort

作用: 努力级别

claude-code --effort high "复杂重构"
claude-code --effort low "简单格式化"

---

--disable-slash-commands

作用: 禁用所有 skills

claude-code --disable-slash-commands "任务"

---

--version / -v

作用: 输出版本号

claude-code -v

---

--help / -h

作用: 显示帮助信息

claude-code -h

---

📋 二、主命令

agents - 列出配置的 agents

# 列出所有 agents
claude-code agents

# 查看帮助
claude-code agents --help

---

auth - 管理认证

# 登录
claude-code auth login

# 登出
claude-code auth logout

# 查看状态
claude-code auth status

---

doctor - 健康检查

# 检查更新器
claude-code doctor

---

install - 安装原生构建

# 安装稳定版
claude-code install stable

# 安装最新版
claude-code install latest

# 安装特定版本
claude-code install 1.2.3

# 查看选项
claude-code install --help

---

mcp - 配置 MCP 服务器

# 查看帮助
claude-code mcp --help

# 通常用于配置管理
# 详细用法参考 MCP 文档

---

plugin - 管理插件

# 列出插件
claude-code plugin list

# 安装插件
claude-code plugin install <name>

# 卸载插件
claude-code plugin uninstall <name>

---

setup-token - 设置长期令牌

# 设置令牌（需要订阅）
claude-code setup-token

---

update / upgrade - 检查并安装更新

# 检查更新
claude-code update

# 自动更新
claude-code upgrade

---

🎬 使用场景

场景 1: 日常代码审查

# 交互式审查
claude-code --model sonnet "审查 src/auth.py 的代码质量"

# 批量审查多个文件
for file in src/**/*.py; do
  claude-code -p --model haiku "简要审查 $file" >> review.md
done

---

场景 2: 重构大型项目

# 1. 先规划
claude-code --permission-mode plan "如何重构这个单体项目？"

# 2. 分步执行（继续会话）
claude-code -c "开始第一步，提取用户模块"

# 3. 持续迭代
claude-code -c "继续下一步"

---

场景 3: CI/CD 集成

#!/bin/bash
# ci-script.sh

# 生成变更日志
claude-code -p \
  --output-format json \
  --model haiku \
  "基于 git diff 生成变更日志" > changelog.json

# 运行测试并修复
claude-code \
  --permission-mode acceptEdits \
  "运行测试并修复所有失败用例"

---

场景 4: 文档生成

# 生成 API 文档
claude-code -p \
  --model opus \
  "为 src/api/ 生成完整的 API 文档（Markdown 格式）" > docs/api.md

# 生成 README
claude-code -p "为这个项目生成 README.md" > README.md

---

场景 5: Bug 调试

# 交互式调试
claude-code --model opus "
应用程序在处理大文件时崩溃。
错误日志在 error.log。
帮我找出问题并修复。
"

# 查看日志
cat error.log | claude-code -p "分析这些错误"

---

场景 6: 代码学习

# 理解代码库
claude-code "
这个项目是做什么的？
主要架构是什么？
入口点在哪里？
"

# 解释特定功能
claude-code -c "详细解释认证流程是如何工作的"

---

场景 7: 多分支并行开发

# 创建功能分支 worktree
claude-code -w feature-a --tmux "实现功能 A"

# 在另一个终端
claude-code -w feature-b --tmux "实现功能 B"

# 修复 bug worktree
claude-code -w hotfix --tmux "紧急修复"

---

场景 8: 安全代码审查

# 只读模式，不允许修改
claude-code \
  --permission-mode default \
  --allowed-tools "Read,Grep" \
  "审查代码中的安全漏洞"

---

✅ 最佳实践

1. 选择合适的模型

任务	推荐模型	原因
简单问答	Haiku	快速、便宜
代码审查	Sonnet	平衡质量和速度
复杂重构	Opus	最强能力
文档生成	Sonnet/Opus	需要连贯性

2. 权限管理原则

• ✅ 默认使用 default 模式
• ✅ 脚本中使用 acceptEdits（在信任的代码库）
• ✅ 只读任务使用 --allowed-tools "Read,Grep"
• ❌ 避免使用 bypassPermissions（除非沙箱）

3. 会话管理

• 使用 -c 继续相关任务
• 使用 --session-id 进行脚本化会话管理
• 定期清理旧会话

4. 成本优化

# 简单任务用 Haiku
claude-code --model haiku "这个函数做什么？"

# 批量任务考虑使用 --max-budget-usd
claude-code -p --max-budget-usd 1.0 "处理大量文件"

5. 调试技巧

# 出问题时启用调试
claude-code -d "有问题的命令"

# 查看详细的工具调用
claude-code -d api,hooks "任务"

---

🔧 故障排除

问题 1: 权限被拒绝

解决方案:

# 检查当前权限模式
# 使用正确的模式
claude-code --permission-mode acceptEdits "任务"

---

问题 2: 会话无法恢复

解决方案:

# 列出所有会话
claude-code -r

# 使用完整 ID
claude-code -r <完整的会话 ID>

---

问题 3: 输出格式问题

解决方案:

# 确保使用 -p 标志
claude-code -p --output-format json "任务"

# 检查 JSON Schema
claude-code -p --json-schema '{...}' "任务"

---

问题 4: MCP 服务器不工作

解决方案:

# 启用调试
claude-code -d mcp "任务"

# 检查配置
claude-code --mcp-config config.json --debug "任务"

---

问题 5: 工具访问被拒绝

解决方案:

# 添加额外目录
claude-code --add-dir /path/to/dir "任务"

# 检查工具限制
claude-code --allowed-tools "Read,Edit,Write" "任务"

---

📖 附录

A. 模型别名速查

别名	完整名称	特点
opus	claude-opus-4-6	最强、最慢、最贵
sonnet	claude-sonnet-4-6	平衡
haiku	claude-haiku-4-5	最快、最便宜

B. 常用组合

# 快速代码审查
claude-code -p --model haiku --output-format json

# 重构任务
claude-code --model opus --permission-mode plan

# 文档生成
claude-code -p --model sonnet --output-format text

# 自动化测试修复
claude-code --permission-mode acceptEdits --model sonnet

C. 环境变量

（如适用，可参考官方文档）

---

手册版本: 1.0
最后更新: 2026-06-25
对应 Claude Code 版本: 最新稳定版

---

💡 提示: 这份手册涵盖了 Claude Code 的主要功能。对于最准确和最新的信息，建议参考官方文档或使用 claude-code --help。