生成配置与动态请求头

正确放置模型生成参数，区分整体替换、请求体扩展和动态会话标识。

This page has not been translated into English yet. The original Chinese version is shown below.

已在 modelProviders 中定义的模型，应把它的所有生成设置放在该条目的 generationConfig。顶层 model.generationConfig 不会给这个条目补齐缺省字段。

常见配置项

字段	用途
`timeout`	请求超时
`maxRetries`	重试次数设置
`retryInitialDelayMs` / `retryMaxDelayMs`	重试延迟参数，毫秒
`streamIdleTimeoutMs`	流分段之间的空闲超时
`contextWindowSize`	模型上下文窗口配置
`modalities`	声明模型媒体输入能力，例如 image
`enableCacheControl`	缓存控制配置
`samplingParams`	temperature、top_p、max_tokens 等采样参数
`customHeaders`	自定义 HTTP 请求头
`extra_body`	OpenAI 兼容请求的扩展字段
`reasoning`	推理配置或显式关闭

官方示例里的超时、上下文和采样数值不能当作所有协议默认。具体能力仍由模型与服务决定。

整体替换的影响

例如全局设置 samplingParams 同时有 temperature 与 max_tokens，而 provider 条目只设置 temperature，选中该 provider 后 max_tokens 不会从全局继承。

samplingParams、customHeaders、extra_body 也按整体对象处理，不做逐键合并。模型专用参数应完整写在该条目，避免以为分散在多处的对象会自动拼接。

Runtime Model 的解析行为不同，见模型解析。

请求体扩展边界

extra_body 主要用于 OpenAI 兼容请求，Anthropic 与 Gemini 会忽略它。Responses 还有“只填缺失字段”的限制，见Responses API。

samplingParams 与 reasoning 的相互作用因模型和端点而不同，不能仅以 JSON 中同时存在就认定两个设置都生效，见推理配置。

动态会话请求头

网关需要每个会话稳定的标识时，可在模型条目使用 ${session_id}：

{
  "outboundCorrelation": {
    "allowDynamicHeaderValues": true
  },
  "modelProviders": {
    "openai": [
      {
        "id": "my-model",
        "baseUrl": "https://gateway.example.com/v1",
        "envKey": "GATEWAY_API_KEY",
        "generationConfig": {
          "customHeaders": {
            "x-opencode-session": "${session_id}"
          }
        }
      }
    ]
  }
}

这是配置形状示例，模型和端点需替换。占位符在每次请求展开，/new、/resume 后按当前会话更新，无需重启 SDK。

必须同时启用全局 allowDynamicHeaderValues；未启用时，包含占位符的 header 会被丢弃并给出警告，不会发送字面量 ${session_id}。

该开关只是允许展开，不限制目标主机。哪些服务收到会话标识，由哪些模型条目携带请求头决定；接收方可据此关联同一会话的请求。