它到底是什么

--max-budget-usd <amount> 是 Claude Code 的启动 flag，用来给单次运行设置 API 调用花费的美元上限，达到上限后停止。官方 CLI reference 的原文描述是："Maximum dollar amount to spend on API calls before stopping (print mode only)"。

• 参数：美元金额，官方示例为 5.00。
• 仅在 print 模式（-p）下有效。
• 官方文档没有给出默认值。截至可访问的官方文档，没有说明不传该 flag 时的行为。
• subagent 的花费计入上限。
• 达到上限后：
  • 再启动 subagent 会失败，报错 Budget limit reached。
  • Claude Code 会停止仍在运行的后台 subagent。
  • 官方注明这些"cap-enforcement"行为需要 Claude Code v2.1.217 或更高版本。

用法

# 官方示例
claude -p --max-budget-usd 5.00 "query"

与其他 flag 的组合 / 互斥

• 必须配合 -p。官方文档标注为 print mode only,GitHub issue #95964 中也明确写到交互式会话目前没有对应的累计花费上限。
• --max-turns：两者限制的维度不同，前者限 agentic turn 数，后者限美元。该 issue 把 --max-budget-usd 与 --max-turns / CLAUDE_CODE_MAX_TURNS 并列为仅适用于非交互运行的上限手段。
• --continue / --resume：官方文档说明，恢复对话时，从更早运行中恢复的累计总额不计入本次上限。

claude -p --max-turns 10 --max-budget-usd 1.0 "query"

运行约束 / 限制

经典使用场景

• CI / headless 脚本：在 claude -p 调用上加一道美元封顶，与 --max-turns 搭配使用（见上方组合示例）。
• 含 subagent 的任务：因为 subagent 花费计入上限，可以限制整体开销，而不只是主 agent 的花费。

常见坑

• 交互式会话不受它约束：在 TUI 里加这个 flag 得不到花费上限，这是官方文档标注的限制。

• 触发时的表现（第三方实测，官方文档未记录）：linuxjedi 的文章用 $0.01 的上限测试，观察到：

  • JSON 输出包含 "subtype": "error_max_budget_usd"，消息为 "Reached maximum budget ($0.01)"。
  • 进程退出码为 1。
  • 作者称该行为在其撰文时未见于文档。

  写脚本依赖这些字段前，请在你使用的版本上自行验证。

• 可能超出上限：同一篇文章的作者认为花费是在客户端累加后再与上限比较，因此上限被检测到之前可能已超出。这是作者的推断，不是官方说明。

• 官方文档没有给出的信息：CLI reference 中该 flag 的条目没有列出对应的 env var 或 settings.json 字段，也没有说明托管 settings 是否会覆盖该 flag，所以本文不列对照表。

来源

• CLI reference - Claude Code Docs（docs.claude.com/en/docs/claude-code/cli-reference 已 301 重定向至此）
• GitHub issue #95964:per-session spend cap for interactive sessions
• When the Docs Fall Short: Investigating Claude Code's Budget Cap