跳到主要内容

claude CLI：真正会改变结果的标志

进阶

大多数人只学会命令行的三样东西——claude、claude -c 和 claude -p——然后就停下了。如果你只是坐在它面前使用，停在这里完全合理。可一旦你把 Claude Code 放进脚本、CI 任务、后台队列或同事手里，这些标志就不再只是便利，而是决定一次运行花一美元还是卡住一小时的关键。

本页不是参考表格的第二份拷贝。它讲的是学习这套界面的顺序、真正会改变结果的标志，以及让人实实在在浪费过时间的四个陷阱。

What you'll learn
  • 你可以启动的六种会话，以及哪个标志选择哪一种
  • 让无人值守运行有边界、可应答、可解析的五标志约定
  • 为什么修改 --append-system-prompt 后再运行 --continue 看起来毫无作用——已记录提示词规则
  • --bare、--safe-mode 和 --restricted 有何区别，何时该用哪个
  • 从 shell 驱动后台会话：agents、attach、logs、respawn、rm、daemon
  • 人们容易混淆的标志对：--tools、--allowedTools 与 --disallowedTools

从问题开始：这是哪一种会话？​

其他所有决定都由此而来。Claude Code 可以启动六种本质不同的东西，而选择其中一种的标志，通常是你最先输入的内容。

你想要标志你得到
一场你全程观看的对话（无）在当前终端中的交互式会话
一个答案，然后退出-p / --print非交互式运行，输出到 stdout
能在当前终端关闭后继续的工作--bg / --background一个后台会话；打印其 ID 以及如何管理它
一个隔离的分支用来试验-w / --worktree位于 <repo>/.claude/worktrees/<name> 的 git worktree
在 Anthropic 的机器上工作--cloud一个云会话，或排入现有云会话的后续任务
用手机驱动当前会话--rc / --remote-control一个同时可从 claude.ai 或 Claude 应用控制的交互式会话

其中两个不能组合：--bg 和 -p 互斥，因为一个立即返回，另一个要等待答案。如果你想在后台运行的是 shell 命令而不是 Claude 会话，请将 --bg 与 --exec 搭配使用：

Run the test suite as a background job, not a Claude session

claude --bg --exec 'pytest -x'

另外，--bg 在启动前会检查该目录的工作区信任状态——因此在不受信任的仓库里启动后台会话，会在一开始就失败，而不是做到一半才失败。

无人值守运行的五标志约定​

这是本页价值最高的内容。无人值守的 claude -p 运行有三种出错方式，是交互式会话根本不会遇到的：它可能在没人应答的权限提示上停滞，可能循环得远超你的预期，也可能在你的脚本需要数据时输出散文。五个标志把这三种情况都堵住了。

Guided walkthrough1 of 5
  1. `claude -p "query"` 打印答案后退出。下面的一切都只适用于 print 模式，所以这个标志是其余各项的入口。

A CI step that cannot hang, cannot loop forever, and cannot overspend

claude -p "Review the staged diff and list bugs" \
--permission-prompts none \
--allowedTools "Read" "Bash(git diff *)" \
--max-turns 6 \
--max-budget-usd 2.00 \
--output-format json
--max-budget-usd 是估算，不是你的账单
  • Claude Code 是用它自己的客户端成本估算来对照上限的，这可能与你实际被计费的金额不同。
  • 当你用 --continue 或 --resume 回到一段对话时，从先前运行恢复的总额不计入上限——所以在 2 美元上限下连续三次恢复运行，总花费可能超过 2 美元。
  • 把它当作单次运行的断路器。如果需要对整个账户或项目设置真正的上限，请参阅 Hard Spend Caps。

关于在没有人在场的情况下放手让运行继续的完整做法——允许什么、屏蔽什么、记录什么——请参阅加固自主运行和无头模式与 Agent SDK。关于服务商层面的上限，请参阅 Hard Spend Caps。

系统提示词家族，以及其中的陷阱​

有五个标志影响系统提示词。四个设置其文本；第五个决定对话是否保留它起初所用的文本。

标志作用
--system-prompt用你的文本替换整个默认提示词
--system-prompt-file用某个文件的内容替换它
--append-system-prompt把你的文本追加到默认提示词后
--append-system-prompt-file把某个文件的内容追加到默认提示词后
--system-prompt-snapshotoff 在每次请求时重建提示词；on（默认）复用已记录的那一份

在追加与替换之间做选择，是在选择身份。追加会保留 Claude Code 默认的工具指引、安全说明和编码约定，并把你的规则叠加其上——适合每次运行的指令、输出格式或项目上下文。替换则会丢弃所有这些，包括工具指引，所以只有当这个场景确实不是编码助手时才适合：比如无人看管的流水线里的非编码代理。一旦替换，任务仍然需要的一切都由你负责。

你可以组合使用。把追加标志和替换标志一起传入，会先替换默认提示词，再追加你的文本。从 v2.1.283 起，你还可以把一个标志与它自己的文件形式一起传入——--append-system-prompt 以及 --append-system-prompt-file——Claude Code 会同时使用两者，无论你以什么顺序输入，文件内容都排在前面。

陷阱：恢复的对话会沿用它诞生时的提示词
  • Claude Code 在一段对话的第一次请求时构建一次系统提示词，并把它记录在会话中。
  • 在对话被压缩之前，之后的每次请求都使用这份已记录的提示词——包括 --resume 或 --continue 之后。
  • 所以你编辑了 --append-system-prompt 的文本，重新运行 claude --continue，却什么都没变。标志没有坏；只是这段对话仍在使用那份记录。
  • 新文本会在对话压缩之后，或在全新的对话中生效。
  • 若要在多次 --continue 运行之间迭代措辞，请传入 --system-prompt-snapshot off，这样每次请求都会重建提示词。需要 v2.1.257 或更高版本。

在混合了稳定指令与每次运行上下文的替换提示词中，还有一个值得了解的技巧。在两者之间放一行只含 __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ 的内容：Claude Code 会在第一个这样的行处切分并将其移除，因此上半部分保持缓存，下半部分则随运行变化。需要 v2.1.275 或更高版本。这为何会影响你的账单，见 Prompt Caching。

对于多用户的脚本化工作负载，--exclude-dynamic-system-prompt-sections 会把每个用户的上下文（比如自动记忆的位置）从系统提示词移到第一条用户消息中——这样不同机器上的同一任务可以共享同一个缓存前缀。它只作用于默认提示词，当你设置 --system-prompt 或 --system-prompt-file 时会被忽略。

三个“关闭东西”的标志，它们并不相同​

人们会混用它们，然后纳闷症状为什么没变。它们解决的是三个不同的问题。

--bare--safe-mode--restricted
它解决的问题启动对脚本化调用来说太慢我的配置坏了，却不知道是哪一部分评测框架不得触碰这台共享机器
CLAUDE.md、技能、命令、子代理、插件、MCP、自动记忆不会被发现不会被加载只加载托管设置和 --settings
内置工具Bash、文件读取、文件编辑正常工作运行命令/代码的工具和 WebFetch 会被移除，除非在 --tools 中逐个点名
文件访问正常正常限制在工作目录内
bypassPermissions允许允许拒绝
托管策略生效仍然生效，包括策略钩子和状态栏生效
副作用设置 CLAUDE_CODE_SIMPLE设置 CLAUDE_CODE_SAFE_MODE拒绝创建云会话

把这张表读作意图的递进：--bare 关乎速度，--safe-mode 关乎诊断，--restricted 关乎隔离。一个有用的细节：通过 --add-dir 传入的目录里的技能，在 --bare 下仍会加载，这就是在其余全被剥离的运行中恰好保留一项能力的办法。

当某处出了问题而你分不清是 Claude Code 还是你自己的配置时，--safe-mode 是首选——包括你想弄清是否某个自定义项触发了自动模型回退的时候。把它与 claude doctor 搭配使用，后者无需启动会话就会打印只读的安装与设置诊断信息。（会话内的 /doctor 命令是另一回事：它还可以应用修复。）更多从症状出发的排查见排查 Claude Code 问题。--restricted 需要 v2.1.248 或更高版本。

从 shell 驱动后台会话​

一旦你用 --bg 启动会话，终端就成了控制面板。整个生命周期都有对应的命令，而且都不需要打开交互式界面。

Guided walkthrough1 of 6
  1. 打开代理视图，用于监控和调度并行的后台会话。用于脚本时，`--json` 以 JSON 数组形式打印活动会话，`--json --all` 还包括已完成的会话。`--cwd <path>` 将范围缩小到在该目录下启动的会话。打开视图本身需要交互式终端；JSON 形式则不需要。

与此相对、从会话内部看的另一面——工作如何转入后台，以及转入后会保留什么——见后台任务、/loop 与调度。

人们容易搞错的标志对​

值得预先澄清的六个混淆
  • --tools 限制存在哪些内置工具。--allowedTools 指定哪些调用可跳过权限提示。--disallowedTools 拒绝调用。这是三件不同的事，传错一个是“为什么它还在问我”最常见的原因。
  • --tools 完全不影响 MCP 工具。若要把它们也移除，请加上 --disallowedTools "mcp__*"。
  • --disallowedTools 中的裸名称会把该工具从 Claude 的上下文中移除；而像 Bash(rm *) 这样带范围的规则会让工具保持可用，只拒绝匹配的调用。
  • --dangerously-skip-permissions 会在 bypassPermissions 模式下启动。--allow-dangerously-skip-permissions 只是把该模式加入 Shift+Tab 循环，这样你可以先在 plan 模式启动，之后再切换。你真正想要的几乎总是第二个。
  • --add-dir 授予文件访问权限，但 Claude Code 不会从这些目录中发现大部分 .claude/ 配置。添加一个目录并不等于采纳它的配置。
  • --desktop 不接受提示词，也不接受除 --verbose 和 --debug 系列之外的其他标志，因为桌面应用会自己启动会话。需要 v2.1.285 或更高版本。

还有一个小小的体验细节：如果你把子命令敲错，Claude Code 会给出最接近的匹配建议并退出，而不会启动会话——claude udpate 会打印 Did you mean claude update?，而不是打开一段你并不想要的对话。

自我检测​

Check yourself

0/3
  1. 你的夜间任务在一个 Agent SDK 应用里运行 `claude -p`，该应用的 `canUseTool` 回调会询问真人，结果夜里一直挂起直到超时。最可能缺少哪个标志？
  2. 你调整了 --append-system-prompt 的文本，重新运行 `claude --continue`，行为却没有变化。为什么？
  3. 某个自定义项正在破坏你的会话，而你不知道是哪一个。哪个标志可以在让工具和权限照常工作的同时将其隔离出来？
按 Enter 或空格键翻转卡片。使用左右方向键在卡片之间切换。已显示术语。
1 / 8
Key takeaways
  • 先选会话类型——决定类型的那个标志会约束你之后能传的所有其他标志。
  • 无人值守运行需要五个标志，而不是一个：-p、--permission-prompts none、--max-turns、--max-budget-usd，以及结构化的输出格式。
  • 把 --max-budget-usd 当作单次运行的断路器，而不是账单上限。它是客户端估算，恢复的总额会漏过它。
  • 对话在第一次请求时记录其系统提示词。如果提示词的修改似乎被忽略，原因就在于此——迭代时使用 --system-prompt-snapshot off。
  • --bare 是速度，--safe-mode 是诊断，--restricted 是隔离。选错一个会浪费一个下午。
  • --help 在设计上就不完整。CLI 参考才是事实来源，版本下限也很重要——在怪罪某个标志之前，先检查 claude -v。

下一步​