Claude Code 深度学习手册

主题

CLI 参考（命令行 flag） ​

Claude Code 命令行的完整参考：所有 claude 子命令与 CLI flag 的名称、用途和语法。

对你最常用的几个 flag（按你的工作方式） ​

完整 flag 见下方参考；结合你"前后端联调 + 重度 subagent/MCP + bypassPermissions"的用法，最该记的：

flag干什么你为啥用得上
claude --resume / -c选/续上次会话你会话多，切回特定任务
claude --worktree <名> / -w隔离分支开会话并行改前端 + SpringBlade 不踩脚
claude --add-dir ../x临时加目录访问跨 kj-frontend / SpringBlade 联调
claude -p "..."非交互一次性跑接脚本 / CI / 管道
claude --model opus[1m]指定模型/1M 上下文大仓库审计时
claude --bare跳过插件/技能/MCP/CLAUDE.md想要一个干净环境复现问题

你已是 native 安装 v2.1.158；claude doctor / claude mcp / claude plugin 这些子命令也常用到。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

这是 Claude Code 官方 CLI reference 页面的内容，分两大块：CLI commands（如何启动会话、管道传内容、恢复对话、管理更新）和 CLI flags（用命令行参数定制 Claude Code 行为）。它还单列了 System prompt flags（4 个改写/追加系统提示词的 flag）。页面明确提醒：claude --help 并不会列出每一个 flag，所以某个 flag 没出现在 --help 里并不代表它不可用。

怎么工作 ​

  • 启动形态由命令决定：claude 进入交互式会话；claude "query" 带初始提示进交互式；claude -p "query" 走 SDK 打印模式（print mode）后退出；cat file | claude -p "query" 处理管道内容。
  • 会话延续：claude -c(=--continue) 加载当前目录最近一次对话（含用 /add-dir 加进来的目录的会话）；claude -r "<session>" "query"(=--resume) 按 ID 或名字恢复，或不带参数弹交互式选择器；--fork-session 在恢复时生成新 session ID 而不复用原 ID。
  • print mode（-p/--print）是一大批 flag 的前提：--max-turns、--max-budget-usd、--json-schema、--init、--maintenance、--no-session-persistence、--fallback-model(仅在 -p 和后台会话生效，交互式忽略) 等都标注为 print mode only 或需配合 -p。
  • 结构化/流式输出靠组合 flag：--output-format 取 text/json/stream-json；很多增强项要求 --output-format stream-json 且常需 --verbose，例如 --include-hook-events、--include-partial-messages、--prompt-suggestions、--replay-user-messages。
  • 权限控制三套机制：--permission-mode 选起始模式(default/acceptEdits/plan/auto/dontAsk/bypassPermissions)；--dangerously-skip-permissions 等价于 --permission-mode bypassPermissions；--allowedTools/--disallowedTools 用规则匹配放行/拒绝具体调用，--tools 则限制有哪些内置工具可用。
  • 系统提示词有 4 个 flag：--system-prompt/--system-prompt-file 整体替换默认提示词（二者互斥）；--append-system-prompt/--append-system-prompt-file 在默认提示词后追加；append 类可与某个 replace 类组合。
  • 后台/并行会话：--bg 把会话作为后台 agent 启动并立即返回（打印 session ID）；claude agents 打开 agent view 监控/派发；配套 claude attach/logs/respawn/rm/stop(kill) 从 shell 管理；claude daemon status 查 supervisor 状态。
  • 子命令拼错时 Claude Code 会给出最接近的建议并退出而不启动会话，例如 claude udpate 会打印 Did you mean claude update?。

怎么配置 / 用法 ​

flag 持久化与配置位置示例：1) --add-dir 只对本会话授予文件访问，要跨会话持久化需在 settings 里设 permissions.additionalDirectories。2) --settings 接受 settings JSON 文件路径或内联 JSON 字符串，会覆盖 settings.json 中同名 key（未写的 key 保留文件值）：claude --settings ./settings.json。3) --setting-sources 用逗号分隔指定加载哪些来源：claude --setting-sources user,project（可选 user/project/local）。4) MCP：claude --mcp-config ./mcp.json，加 --strict-mcp-config 则只用该文件的 MCP 服务器。5) 结构化输出：claude -p --json-schema '{"type":"object","properties":{...} }' "query"。6) 多用户缓存复用：claude -p --exclude-dynamic-system-prompt-sections "query"（仅默认系统提示词生效，设了 --system-prompt/--system-prompt-file 时忽略）。7) 长效 token：claude setup-token（需 Claude 订阅，打印 token 到终端但不保存）。

什么时候用 ​

  • 脚本/CI 里非交互运行：用 -p/--print，配 --output-format json 或 --json-schema 取结构化结果；用 --max-turns/--max-budget-usd 设上限防跑飞；用 --fallback-model 在默认模型过载/下线时自动回退。
  • 想让脚本调用启动更快：用 --bare（跳过 hooks/skills/plugins/MCP/auto memory/CLAUDE.md 的自动发现，只留 Bash、file read、file edit），会设 CLAUDE_CODE_SIMPLE。
  • 只想在默认编码助手身份上加几条规则：用 append 类（--append-system-prompt/--append-system-prompt-file），保留默认工具指引和安全说明；当任务的身份/权限模型与 Claude Code 不同（如流水线里无人值守的非编码 agent）才用 replace 类。
  • 别把临时 flag 当持久人格：页面建议持久人格用 output styles，项目级长期约定用 CLAUDE.md，而这些 flag 只对当次调用生效。
  • 多用户/多机跑同一任务想提升 prompt-cache 命中率：用 --exclude-dynamic-system-prompt-sections，把工作目录、环境信息、memory 路径、git-repo 标记挪到首条 user 消息。

限制 / 坑 ​

  • claude --help 不会列出全部 flag——flag 不在 --help 里不代表不可用。
  • --enable-auto-mode 已在 v2.1.111 移除（max-version 标注 2.1.110）；auto mode 现默认在 Shift+Tab 循环里，改用 --permission-mode auto 起始。
  • --system-prompt 与 --system-prompt-file 互斥；replace 类会丢掉全部默认提示词（含工具指引和安全说明），需自行承担任务所需的一切。
  • --fallback-model 只在 print mode(-p)和后台会话(非交互)生效，交互式会话里被忽略。
  • --add-dir 只授予文件读写访问，大多数 .claude/ 配置不会从这些目录被发现；要持久化得写进 settings 的 permissions.additionalDirectories。
  • 大量增强输出 flag 有硬性前置：--include-hook-events/--include-partial-messages/--prompt-suggestions/--replay-user-messages 都要求 --output-format stream-json（多数还要 --verbose），--replay-user-messages 还要求 --input-format stream-json。
  • --session-id 必须是合法 UUID；--tmux 必须配 --worktree。
  • --no-session-persistence 仅 print mode；同样效果在任何模式可用环境变量 CLAUDE_CODE_SKIP_PROMPT_HISTORY。
  • --exclude-dynamic-system-prompt-sections 设了 --system-prompt/--system-prompt-file 时被忽略。
  • --channels 是 Research preview 且需要 Claude.ai 认证；--dangerously-load-development-channels 会绕开 allowlist 并提示确认。
  • claude setup-token 需要 Claude 订阅，且只打印不保存 token。

硬事实速查（45 条） ​

  • CLI commands：claude(交互)、claude "query"(带初始提示)、claude -p "query"(SDK 后退出)、cat file | claude -p "query"(管道)、claude -c(续最近对话)、claude -c -p "query"(SDK 续)、claude -r "<session>" "query"(按 ID/名恢复)。
  • claude update(更新到最新)；claude install [version] 接受版本号如 2.1.118，或 stable/latest。
  • claude auth login(支持 --email 预填、--sso 强制 SSO、--console 用 Console 走 API 计费)；claude auth logout；claude auth status(输出 JSON，--text 人类可读，登录退 0 未登录退 1)。
  • claude agents(打开 agent view，支持 --cwd <path>、--json、--permission-mode、--model、--effort、--settings、--add-dir、--plugin-dir、--mcp-config，需交互式终端)。
  • 后台会话管理：claude attach <id>、claude logs <id>、claude respawn <id>(--all 重启全部运行中)、claude rm <id>、claude stop <id>(也接受 claude kill)。
  • claude auto-mode defaults(打印内置 auto mode 分类器规则 JSON)；claude auto-mode config(看应用 settings 后的有效配置)。
  • claude daemon status(打印 supervisor 状态/版本/socket 目录/worker 数，未运行退 1)。
  • claude mcp(配置 MCP 服务器)；claude plugin(管理插件，别名 claude plugins)。
  • claude project purge [path](删项目本地状态：transcripts/task lists/debug logs/file-edit history/prompt history/~/.claude.json 中该项目条目；flags：--dry-run、-y/--yes、-i/--interactive、--all)。
  • claude remote-control(启动 Remote Control 服务器，server 模式无本地交互)；claude setup-token(生成长效 OAuth token，需订阅)。
  • claude ultrareview [target](非交互跑 ultrareview，成功退 0 失败退 1，--json 原始负载，--timeout <minutes> 覆盖 30 分钟默认)。
  • --add-dir(加额外工作目录)；--agent(指定 agent)；--agents(JSON 动态定义 subagent，字段同 frontmatter 加 prompt)。
  • --allow-dangerously-skip-permissions(把 bypassPermissions 加进 Shift+Tab 循环但不以此起始)；--dangerously-skip-permissions(=--permission-mode bypassPermissions)。
  • --allowedTools(免提示执行的工具，规则匹配)；--disallowedTools(裸工具名从 context 移除，带域规则如 Bash(rm *) 只拒匹配调用)；--tools(限制可用内置工具，"" 全禁、"default" 全开、或 "Bash,Edit,Read")。
  • --append-system-prompt / --append-system-prompt-file(追加)；--system-prompt / --system-prompt-file(整体替换，前两组与后两组可组合，后两个互斥)。
  • --bare(最小模式，设 CLAUDE_CODE_SIMPLE)；--betas(beta header，仅 API key 用户，如 interleaved-thinking)。
  • --bg(后台 agent 启动并返回 session ID，可配 --exec/--agent)；--exec(把 shell 命令作为 PTY 后台 job，配 --bg)。
  • --channels(Research preview，空格分隔 plugin:<name>@<marketplace>，需 Claude.ai 认证)；--dangerously-load-development-channels(接受 plugin:<name>@<marketplace> 和 server:<name>，提示确认)。
  • --chrome / --no-chrome(Chrome 浏览器集成开/关)。
  • --continue,-c；--resume,-r(v2.1.144 起后台会话在选择器里标 bg)；--fork-session(配 --resume/--continue)；--from-pr(接受 PR 号、GitHub/GitHub Enterprise PR URL、GitLab MR URL、Bitbucket PR URL)。
  • --debug(可带类目过滤如 "api,hooks" 或 "!statsig,!file")；--debug-file <path>(隐式开 debug，优先级高于 CLAUDE_CODE_DEBUG_LOGS_DIR)。
  • --disable-slash-commands(禁所有 skills 和 commands)。
  • --effort(取 low/medium/high/xhigh/max，可用级别看模型，覆盖 effortLevel 不持久)。
  • --exclude-dynamic-system-prompt-sections(把 per-machine 段挪到首条 user 消息，仅默认系统提示词生效)。
  • --fallback-model(默认模型过载/下线时自动回退，仅 -p 和后台会话)。
  • --ide(恰有一个有效 IDE 时自动连)。
  • --init / --maintenance(print mode 下用对应 matcher 跑 Setup hooks)；--init-only(跑 Setup 和 SessionStart hooks 后退出不开对话)。
  • --include-hook-events / --include-partial-messages(均需 --output-format stream-json，后者还需 --print)。
  • --input-format(print 模式输入格式：text/stream-json)；--output-format(text/json/stream-json)。
  • --json-schema(print mode only，agent 完成后输出符合 JSON Schema 的校验过的输出)。
  • --max-budget-usd(print mode only，达上限停)；--max-turns(print mode only，达上限报错退出，默认无限)。
  • --mcp-config(从 JSON 文件或字符串加载 MCP，空格分隔)；--strict-mcp-config(只用 --mcp-config 的 MCP)。
  • --model(别名 sonnet/opus 或全名如 claude-sonnet-4-6，覆盖 model 设置和 ANTHROPIC_MODEL)。
  • --name,-n(会话显示名，可 claude --resume <name> 恢复；/rename 中途改名)。
  • --no-session-persistence(print mode only，等效 env CLAUDE_CODE_SKIP_PROMPT_HISTORY)。
  • --permission-mode(default/acceptEdits/plan/auto/dontAsk/bypassPermissions，覆盖 settings 的 defaultMode)；--permission-prompt-tool(非交互下用 MCP 工具处理权限提示)。
  • --plugin-dir(从目录或 .zip 加载插件，单 flag 一路径，可重复)；--plugin-url(从 URL 拉 .zip 插件，可重复或空格分隔)。
  • --print,-p；--prompt-suggestions(需 --print + --output-format stream-json + --verbose)。
  • --remote(在 claude.ai 建 web 会话)；--remote-control,--rc(交互式会话同时开 Remote Control，可带名字)；--remote-control-session-name-prefix <prefix>(默认 hostname，等效 env CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX)。
  • --replay-user-messages(需 --input-format stream-json 且 --output-format stream-json)。
  • --session-id(须合法 UUID，如 550e8400-e29b-41d4-a716-446655440000)。
  • --setting-sources(逗号分隔 user/project/local)；--settings(JSON 文件或内联字符串)。
  • --teleport(在本地终端恢复 web 会话)；--teammate-mode(auto(默认)/in-process/tmux，覆盖 teammateMode)。
  • --tmux(为 worktree 建 tmux，需 --worktree；有 iTerm2 用原生 pane，--tmux=classic 用传统 tmux)。
  • --verbose(覆盖 viewMode)；--version,-v；--worktree,-w(在 <repo>/.claude/worktrees/<name> 起隔离 worktree，可传 #<number> 或 GitHub PR URL)。

官方出处：https://code.claude.com/docs/en/cli-reference