它到底是什么

--max-turns 用来限制 agent 的回合数，只在 print mode（-p / --print）下生效。官方 CLI reference 的原文描述是：

Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default.

• 接受值：一个数字（--max-turns <number>）。
• 默认值：不限制。
• 触达上限时：进程以错误退出。官方文档没有写具体的退出码或输出格式。
• 与 --input-format stream-json 搭配时：如果上限结束了一个 turn，而此时仍有排队中的消息，该消息会继续排队，并启动一个有独立上限的新 turn。

关于"一个 turn 到底算什么"，官方文档没有定义。第三方站点 claudelog 称"每次 tool call 消耗一个 turn"，这只是第三方说法，不是官方定义。

用法

claude -p --max-turns 3 "query"

第三方站点的示例（非官方）：

claude -p "Fix linting errors" --max-turns 1
claude -p "Debug authentication" --max-turns 2 --verbose

与其他 flag 的组合 / 互斥

• 必须配合 -p / --print。官方明确标注 "print mode only"。
• 与 --max-budget-usd 是并列的 print mode 限制：前者限制回合数，后者限制估算花费。官方示例是 claude -p --max-budget-usd 5.00 "query"。两者可以同时使用，官方文档没有说明同时触发时的优先级。
• 与 --input-format stream-json 组合时的行为见上文。
• 官方文档没有列出与 --max-turns 互斥的 flag。

在 settings.json / env 的等价配置

截至本次访问的官方 CLI reference，没有为 --max-turns 列出对应的 env var 或 settings.json 字段，因此不在此给出对照表。

运行约束 / 限制

经典使用场景

• CI / 脚本中防止 agent 失控：对 claude -p 设置回合上限，避免 agent 在循环中持续运行。claudelog 也提到这个用途（第三方）。
• 与 --max-budget-usd 并用，同时限制回合数和估算花费（官方文档中两者并列，组合使用是据此作出的推断）。

常见坑

• 触达上限会报错退出，而不是正常结束。在 CI 里要处理这个非成功的结局，不要假设命令一定成功返回。
• 第三方站点 claudelog 建议，任务在预算内跑不完时就调大上限。这是第三方建议，不是官方说法。

来源

• CLI reference（官方，docs.claude.com 重定向至 code.claude.com）
• What is --max-turns in Claude Code（claudelog，第三方）