简短答案
max_tokens 用来限制模型单次最多输出多少 token。不同 API 和模型对这个字段的名称、必填要求和默认行为不同。
为了获得稳定输出，建议在长回复、代码生成、文档生成等任务中显式设置输出上限。对于 Claude / Anthropic-compatible API，通常需要显式传入 max_tokens。
核心概念
max_tokens 设置得太小，回复可能被截断。设置得很大，不代表模型一定会输出那么多内容，但可能让长输出任务消耗更多费用。
不同参数名
如果你使用的是 Codex CLI 或其他基于 Responses API 的工具，要以工具或 provider 当前支持的字段为准。不要把所有模型都固定写成同一个参数名。
不设置会怎样
不同厂商和 API 的行为不完全一样：
因此，同一段代码换模型后，输出长度可能发生变化。为了减少不确定性，生产调用里建议显式设置输出上限。
推荐设置
实际最大值请以模型广场和上游模型文档为准。不同模型的最大输出 token 数会随版本变化。
输出被截断怎么办
如果响应里出现finish_reason: "length"，通常表示模型达到输出上限。
可以按这个顺序排查：
- 提高当前 API 支持的输出上限字段。
- 检查是否使用了正确的参数名。
- 让 prompt 更聚焦，减少不必要的输出。
- 换用支持更大输出窗口的模型。
- 把长任务拆成多个步骤。
常见误区
- 以为
max_tokens越大，模型就一定输出越长。 - 输出被截断后只重试，不检查
finish_reason。 - 对推理模型仍使用旧字段名。
- 忽略 hidden reasoning tokens 对上下文和成本的影响。
- 不看模型自身最大输出上限。