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

技术与健康

674人浏览 · 2026-06-29 10:26:34

技术与健康 · 2026-06-29 10:26:34 发布

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

📖 目录

工具简介
快速开始
核心概念
命令详解
使用场景
最佳实践
故障排除

📌 工具简介

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。

DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

告别千万级学费：AI编程双剑合璧 Cursor + Claude Code

DeepSeek技术社区

2026年AI协同底座深度评测：让外部Agent真正跑通企业业务流

2026年AI协同底座深度评测：打通外部Agent与企业业务流过去两年，主流外部Agent（如Cursor、ClaudeCode、Codex、GeminiCLI）在单点任务上表现卓越，但始终受限于“本地工具”定位，难以融入团队协作流。通过飞书aily协同底座的实践，实现了外部Agent与企业业务流的无缝衔接，核心逻辑为：分工明确：外部Agent专注专业领域计算（如代码生成、日志分析），协同底座

DeepSeek技术社区

2026年AI协同底座深度评测｜多外部Agent落地企业业务流的上下文管理指南

我自己作为互联网公司的技术负责人，同时也是玩了快两年的AI Power User，Codex、Cursor、Claude Code、Gemini CLI这些主流外部Agent我几乎都深度用过，单拎出来每一个的单点能力都足够惊艳：Cursor写业务代码的补全准确率能到80%以上，Claude Code处理几十万行的日志文件不用拆分，Codex爬取公开行业数据的效率比我手下两个运营加起来还高。

DeepSeek技术社区

所有评论(0)

查看更多评论

技术与健康

@Practicer2015

已为社区贡献1条内容

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

技术与健康

📖 目录

📌 工具简介

主要特点

🚀 快速开始

安装

基础使用

🎯 核心概念

1. 会话模式

2. 权限模式

3. 模型选择

📚 命令详解

🔧 一、选项参数

1. 会话控制

--continue / -c

--resume / -r

--session-id

--print / -p

--fork-session

2. 模型与智能体

--model

--agent

--agents

3. 权限与安全

--permission-mode

--allowed-tools / --disallowed-tools

--dangerously-skip-permissions

4. 输出与调试

--output-format

--debug / -d

--verbose

5. 文件与资源

--file

6. 集成功能

--chrome

--ide

--worktree / -w

--tmux

7. 高级选项

--max-budget-usd

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

--json-schema

--betas

8. 配置管理

--settings

--setting-sources

--plugin-dir

9. MCP 服务器

--mcp-config

--mcp-debug

10. 其他选项

--no-chrome

--no-session-persistence

--tools

--add-dir

--include-partial-messages

--input-format

--replay-user-messages

--fallback-model

--effort

--disable-slash-commands

--version / -v

--help / -h

📋 二、主命令

agents - 列出配置的 agents

auth - 管理认证

doctor - 健康检查

install - 安装原生构建

mcp - 配置 MCP 服务器

plugin - 管理插件

setup-token - 设置长期令牌

update / upgrade - 检查并安装更新

🎬 使用场景

场景 1: 日常代码审查

场景 2: 重构大型项目

场景 3: CI/CD 集成

场景 4: 文档生成

场景 5: Bug 调试

场景 6: 代码学习

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

`--continue` / `-c`

`--resume` / `-r`

`--session-id`

`--print` / `-p`

`--fork-session`

`--model`

`--agent`

`--agents`

`--permission-mode`

`--allowed-tools` / `--disallowed-tools`

`--dangerously-skip-permissions`

`--output-format`

`--debug` / `-d`

`--verbose`

`--file`

`--chrome`

`--ide`

`--worktree` / `-w`

`--tmux`

`--max-budget-usd`

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

`--json-schema`

`--betas`

`--settings`

`--setting-sources`

`--plugin-dir`

`--mcp-config`

`--mcp-debug`

`--no-chrome`

`--no-session-persistence`

`--tools`

`--add-dir`

`--include-partial-messages`

`--input-format`

`--replay-user-messages`

`--fallback-model`

`--effort`

`--disable-slash-commands`

`--version` / `-v`

`--help` / `-h`

`agents` - 列出配置的 agents

`auth` - 管理认证

`doctor` - 健康检查

`install` - 安装原生构建

`mcp` - 配置 MCP 服务器

`plugin` - 管理插件

`setup-token` - 设置长期令牌

`update` / `upgrade` - 检查并安装更新