Claude Code - Anthropic 官方 CLI 工具让 AI 直接在终端中协助您的编程工作 目录工具简介快速开始核心概念命令详解使用场景最佳实践故障排除 工具简介Claude Code 是 Anthropic 官方提供的命令行工具允许开发者直接在终端中使用 Claude 的 AI 能力来完成各种编程任务。主要特点✅终端原生- 无需离开命令行即可获得 AI 辅助✅代码库感知- 自动理解和操作本地代码✅交互式/批处理- 支持对话模式和一次性输出✅权限控制- 细粒度的工具访问控制✅会话持久化- 可恢复之前的对话✅多模型支持- 支持 Opus、Sonnet、Haiku 等 Claude 模型 快速开始安装# 安装稳定版claude-codeinstallstable# 或安装最新版claude-codeinstalllatest基础使用# 交互式对话默认模式claude-code帮我优化这个函数# 打印模式适用于管道claude-code-p解释这段代码input.py# 继续之前的对话claude-code-c 核心概念1. 会话模式模式说明使用场景交互式默认模式持续对话复杂任务、多轮讨论打印模式-p一次性输出脚本集成、管道处理2. 权限模式模式说明安全级别default每次询问用户 最安全acceptEdits自动接受文件编辑⚠️ 中等dontAsk自动执行所有操作⚠️ 较低plan仅规划不执行 最安全bypassPermissions完全跳过权限检查❌ 仅沙箱3. 模型选择# 使用别名推荐--modelopus# Claude Opus 4.6最强--modelsonnet# Claude Sonnet 4.6平衡--modelhaiku# Claude Haiku 4.5快速# 完整模型名--modelclaude-opus-4-6 命令详解 一、选项参数1. 会话控制--continue/-c作用: 在当前目录继续最近的对话使用场景:你正在调试一个复杂问题中断后想继续多次迭代改进同一代码# 第一次对话claude-code帮我实现用户认证功能# 中断后继续claude-code-c继续刚才的工作添加登出功能--resume/-r作用: 通过会话 ID 恢复对话使用场景:跨目录恢复之前的对话团队共享会话上下文# 直接指定会话 IDclaude-code-rabc123-def456# 交互式选择会话claude-code-r# 带搜索词的选择claude-code-r认证功能--session-id作用: 使用特定的会话 ID必须是有效 UUID使用场景:脚本中需要稳定会话标识调试特定会话问题claude-code --session-id550e8400-e29b-41d4-a716-446655440000添加日志--print/-p作用: 打印响应并退出使用场景:脚本自动化管道操作CI/CD 集成# 基础用法claude-code-p解释这段代码file.py# 管道操作caterror.log|claude-code-p分析这些错误# 保存到文件claude-code-p生成 API 文档docs.md--fork-session作用: 恢复时创建新的会话 ID使用场景:从旧会话开始新工作保留原始会话不变# 基于会话 123 创建新会话claude-code-r123--fork-session2. 模型与智能体--model作用: 指定使用的模型使用场景:根据任务复杂度选择模型成本优化Haiku 更便宜速度需求Haiku 更快# 简单任务用 Haiku快、便宜claude-code--modelhaiku这个函数有什么bug?# 复杂重构用 Opus最强claude-code--modelopus重构整个项目架构--agent作用: 指定当前会话的 agent使用场景:使用预配置的专用 agent不同任务用不同 agentclaude-code--agentreviewer审查我的代码claude-code--agentdebugger帮我调试--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... } }--agentdoc-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-toolsRead,Grep分析代码结构# 禁止 git 操作claude-code --disallowed-toolsBash(git:*)解释代码# 组合使用claude-code\--allowed-toolsRead,Edit,Grep\--disallowed-toolsBash(*: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# 实时流式 JSONclaude-code-p--output-format stream-json长任务--debug/-d作用: 启用调试模式使用场景:诊断工具问题性能分析开发 MCP 插件# 启用所有调试claude-code-d测试# 过滤特定类别claude-code-dapi,hooks测试# 排除类别claude-code-d!1p,!file测试# 输出到文件claude-code --debug-file /tmp/debug.log测试--verbose作用: 覆盖详细模式设置使用场景:需要更多输出信息了解执行详情claude-code--verbose详细解释这个错误5. 文件与资源--file作用: 下载文件资源到启动时使用场景:使用 Claude Code 共享的文件多文件协作# 格式: file_id:relative_pathclaude-code\--filefile_abc:source.py\--filefile_def:image.png\基于这些文件做什么6. 集成功能--chrome作用: 启用 Chrome 集成使用场景:与浏览器配合工作Web 开发调试claude-code--chrome调试这个网页--ide作用: 启动时自动连接 IDE使用场景:IDE 集成开发需要编辑器功能# 自动检测并连接claude-code--ide重构这个组件--worktree/-w作用: 创建新的 git worktree使用场景:并行开发多分支隔离实验性工作代码审查# 创建命名 worktreeclaude-code-wfeature-new-api实现新 API# 自动命名claude-code-w实验性功能# 与 tmux 配合claude-code-wexperiment--tmux尝试这个想法--tmux作用: 为 worktree 创建 tmux 会话使用场景:需要终端多面板保持工作环境# iTerm2 原生面板默认claude-code-wbugfix--tmux修复这个 bug# 传统 tmuxclaude-code-wfeature--tmuxclassic开发功能7. 高级选项--max-budget-usd作用: 限制 API 调用最大费用使用场景:成本控制试用测试claude-code-p--max-budget-usd0.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--betasfeature-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]} }任务# 严格模式只使用指定的 MCPclaude-code --strict-mcp-config --mcp-config config.json任务--mcp-debug作用: 启用 MCP 调试模式显示服务器错误使用场景:开发 MCP 服务器诊断 MCP 问题# 已废弃建议使用claude-code-dmcp任务10. 其他选项--no-chrome作用: 禁用 Chrome 集成claude-code --no-chrome任务--no-session-persistence作用: 禁用会话持久化使用场景:临时会话隐私敏感claude-code-p--no-session-persistence敏感任务--tools作用: 指定可用工具列表使用场景:限制工具集安全操作# 使用所有工具claude-code--toolsdefault任务# 只用指定工具claude-code--toolsBash,Read任务# 禁用所有claude-code--tools只聊天--add-dir作用: 额外允许工具访问的目录使用场景:多目录项目符号链接目录claude-code --add-dir ./shared --add-dir /external/libs任务--include-partial-messages作用: 包含部分消息块仅限 stream-jsonclaude-code-p--input-format stream-json --include-partial-messages--input-format作用: 输入格式# 文本输入默认claude-code --input-format text# 流式 JSONclaude-code --input-format stream-json--replay-user-messages作用: 将 stdin 的用户消息重新发送回 stdoutclaude-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--efforthigh复杂重构claude-code--effortlow简单格式化--disable-slash-commands作用: 禁用所有 skillsclaude-code --disable-slash-commands任务--version/-v作用: 输出版本号claude-code-v--help/-h作用: 显示帮助信息claude-code-h 二、主命令agents- 列出配置的 agents# 列出所有 agentsclaude-code agents# 查看帮助claude-code agents--helpauth- 管理认证# 登录claude-code auth login# 登出claude-code authlogout# 查看状态claude-code auth statusdoctor- 健康检查# 检查更新器claude-code doctorinstall- 安装原生构建# 安装稳定版claude-codeinstallstable# 安装最新版claude-codeinstalllatest# 安装特定版本claude-codeinstall1.2.3# 查看选项claude-codeinstall--helpmcp- 配置 MCP 服务器# 查看帮助claude-code mcp--help# 通常用于配置管理# 详细用法参考 MCP 文档plugin- 管理插件# 列出插件claude-code plugin list# 安装插件claude-code plugininstallname# 卸载插件claude-code plugin uninstallnamesetup-token- 设置长期令牌# 设置令牌需要订阅claude-code setup-tokenupdate/upgrade- 检查并安装更新# 检查更新claude-code update# 自动更新claude-code upgrade 使用场景场景 1: 日常代码审查# 交互式审查claude-code--modelsonnet审查 src/auth.py 的代码质量# 批量审查多个文件forfileinsrc/**/*.py;doclaude-code-p--modelhaiku简要审查$filereview.mddone场景 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\--modelhaiku\基于 git diff 生成变更日志changelog.json# 运行测试并修复claude-code\--permission-mode acceptEdits\运行测试并修复所有失败用例场景 4: 文档生成# 生成 API 文档claude-code-p\--modelopus\为 src/api/ 生成完整的 API 文档Markdown 格式docs/api.md# 生成 READMEclaude-code-p为这个项目生成 README.mdREADME.md场景 5: Bug 调试# 交互式调试claude-code--modelopus 应用程序在处理大文件时崩溃。 错误日志在 error.log。 帮我找出问题并修复。 # 查看日志caterror.log|claude-code-p分析这些错误场景 6: 代码学习# 理解代码库claude-code 这个项目是做什么的 主要架构是什么 入口点在哪里 # 解释特定功能claude-code-c详细解释认证流程是如何工作的场景 7: 多分支并行开发# 创建功能分支 worktreeclaude-code-wfeature-a--tmux实现功能 A# 在另一个终端claude-code-wfeature-b--tmux实现功能 B# 修复 bug worktreeclaude-code-whotfix--tmux紧急修复场景 8: 安全代码审查# 只读模式不允许修改claude-code\--permission-mode default\--allowed-toolsRead,Grep\审查代码中的安全漏洞✅ 最佳实践1. 选择合适的模型任务推荐模型原因简单问答Haiku快速、便宜代码审查Sonnet平衡质量和速度复杂重构Opus最强能力文档生成Sonnet/Opus需要连贯性2. 权限管理原则✅默认使用default模式✅脚本中使用acceptEdits在信任的代码库✅只读任务使用--allowed-tools Read,Grep❌避免使用bypassPermissions除非沙箱3. 会话管理使用-c继续相关任务使用--session-id进行脚本化会话管理定期清理旧会话4. 成本优化# 简单任务用 Haikuclaude-code--modelhaiku这个函数做什么# 批量任务考虑使用 --max-budget-usdclaude-code-p--max-budget-usd1.0处理大量文件5. 调试技巧# 出问题时启用调试claude-code-d有问题的命令# 查看详细的工具调用claude-code-dapi,hooks任务 故障排除问题 1: 权限被拒绝解决方案:# 检查当前权限模式# 使用正确的模式claude-code --permission-mode acceptEdits任务问题 2: 会话无法恢复解决方案:# 列出所有会话claude-code-r# 使用完整 IDclaude-code-r完整的会话 ID问题 3: 输出格式问题解决方案:# 确保使用 -p 标志claude-code-p--output-format json任务# 检查 JSON Schemaclaude-code-p--json-schema{...}任务问题 4: MCP 服务器不工作解决方案:# 启用调试claude-code-dmcp任务# 检查配置claude-code --mcp-config config.json--debug任务问题 5: 工具访问被拒绝解决方案:# 添加额外目录claude-code --add-dir /path/to/dir任务# 检查工具限制claude-code --allowed-toolsRead,Edit,Write任务 附录A. 模型别名速查别名完整名称特点opusclaude-opus-4-6最强、最慢、最贵sonnetclaude-sonnet-4-6平衡haikuclaude-haiku-4-5最快、最便宜B. 常用组合# 快速代码审查claude-code-p--modelhaiku --output-format json# 重构任务claude-code--modelopus --permission-mode plan# 文档生成claude-code-p--modelsonnet --output-format text# 自动化测试修复claude-code --permission-mode acceptEdits--modelsonnetC. 环境变量如适用可参考官方文档手册版本: 1.0最后更新: 2026-06-25对应 Claude Code 版本: 最新稳定版提示: 这份手册涵盖了 Claude Code 的主要功能。对于最准确和最新的信息建议参考官方文档或使用claude-code --help。