2026 Codex config.toml 自定义请求体：支持项、限制与替代方案

2026 Codex config.toml 自定义请求体：支持项、限制与替代方案

先说结论- Codex 的 config.toml 只能配置 base_url、env_key、http_headers 等有限字段，无法直接向请求体追加任意 JSON 字段；需要额外字段时只能加请求头、查询参数或自建兼容网关。- 自定义 provider 必须写在用户级 ~/.codex/config.toml，项目级配置会被忽略；wire_api 目前唯一支持 responses，第三方服务商必须兼容 Responses API 否则工具调用会失败。- 如果 Codex Desktop 下拉框不显示自定义模型，先不要改配置——用 CLI 的 /model 验证；CLI 能列出而桌面版不显示，多半是客户端过滤缺陷（issue #19694），改配置没用。> 围绕“自定义请求体”这个具体需求，拆解 Codex 官方配置能力的边界、第三方网关的兼容方案，以及桌面端不显示模型时的真实定位步骤先说结论：截至 2026 年 8 月，Codex 的官方配置项不支持直接向请求体追加任意 JSON 字段。如果你接的是国内中转站、企业内网网关或者某个刚开源的自托管模型服务，很可能遇到这样的需求：网关要求请求体里带一个 user_id 或者 workspace 字段，否则返回 400。翻遍 config.toml，发现能自定义的只有 base_url、env_key、http_headers、env_http_headers 和 query_params——没有 request_body_extra 这种东西。这是当前公开配置层的能力边界。Codex 当前 wire_api 只支持 responses，官方配置参考没有列出任意 JSON 注入字段。因此，更严谨的结论是：截至本文核验时，不能只靠 config.toml 给请求体追加任意字段；未来版本是否开放仍要以官方配置表为准。但“不能直接注入”不等于“没法用”。实际上有两条绕行路线：一是用请求头或查询参数传递额外信息，很多网关是兼容的；二是自建一个轻量兼容层，把 Codex 发出的 Responses 请求改写后再转发给上游。两条路各有代价，下面拆开说。## config.toml 自定义 provider 的实际配置边界先看 Codex 官方支持什么。用户级配置文件在 macOS / Linux 是 ~/.codex/config.toml，Windows 是 %USERPROFILE%\\.codex\\config.toml。自定义 provider 必须写在这里，项目级 .codex/config.toml 里的 model_provider 会被忽略。这是很多人踩的第一个坑。对应字段可在 Codex 官方配置参考 中逐项核对。一个典型的自定义 provider 配置长这样：tomlmodel = "your-model-id"model_provider = "mygateway"[model_providers.mygateway]name = "My Gateway"base_url = "https://gateway.example.com/v1"env_key = "MYGATEWAY_API_KEY"wire_api = "responses"# 可选：额外请求头[model_providers.mygateway.http_headers]X-Custom-Header = "value"# 可选：查询参数[model_providers.mygateway.query_params]api-version = "2026-01-01"注意：env_key 是环境变量的名称，不是密钥本身。用环境变量传 Key 比直接写死在配置里干净，而且不会污染 auth.json。官方明确把 auth.json 按密码文件管理，别手工去改它。http_headers 和 query_params 是官方留的口子。网关需要的一些元信息，比如租户 ID、来源标记、版本号，完全可以通过 header 或 query 传。如果你的服务商接受这种方式，那根本不需要注入请求体。但现实是，很多自建网关或者企业平台把校验逻辑写在请求体里，header 传过去不认。这时候就得考虑兼容层了。## 验证接口兼容性：Responses API 才是分水岭在配置任何东西之前，先确认你的网关到底支不支持 Responses API。可以用 curl 直接测，注意路径要打到 /responses：bashcurl https://gateway.example.com/v1/responses \\ -H "Authorization: Bearer $YOUR_KEY" \\ -H "Content-Type: application/json" \\ -d '{ "model": "your-model-id", "input": "ping" }'如果返回 404 或 model not found，就说明网关只支持 chat completions，不支持 responses。Codex 发出去的是 responses 格式，即使你在 config.toml 里写了 wire_api = "responses"，网关不认就是白搭。这里有个容易混淆的点：/v1/models 返回 200 只能证明域名、Key 和模型列表链路通，不代表 Responses 接口可用。常见误区是把 /models 测通后就直接配置 Codex，直到工具调用报错，才发现网关根本没有实现 responses。所以，配置后的验证不能只看“能对话”，还要看工具调用。可以让 Codex 执行一个确实需要工具的任务，例如读取当前目录文件，并在网关日志中检查完整调用链。Responses API 的函数工具输出项使用 function_call 类型，客户端执行后还要能正确回传对应的 function_call_output；只有这组往返正常，才算基本兼容。服务商文档即使写了“兼容 Responses API”，也要实际测过才算数。## 桌面版不显示自定义模型：先诊断再动手CLI 跑得好好的，但 Codex Desktop 的模型下拉框里找不到你配置的模型，甚至只有 “Custom” 一个灰标签。这个问题跟请求体无关，但也是自定义配置里的高频状况。先做一个分层诊断：在用户级配置中直接设置 model 和 model_provider，再分别验证 CLI 调用与桌面端模型选择器。如果模型可以实际调用，但桌面列表不显示，问题更可能位于模型目录或客户端展示层，而不是 API 请求体。OpenAI Codex 仓库曾记录 模型目录已被后端加载、但桌面选择器过滤掉自定义模型的问题 #19694。该 Issue 当前显示为已关闭，但不同客户端版本、模型目录格式和 provider 类型仍可能表现不同，不能仅凭 Issue 编号断言本机一定命中同一问题。这种情况下，你在桌面版改配置、重启、重装，都解决不了。有效的办法有两个：1. 在 config.toml 里直接写死 model = "your-model-id"，不要只依赖 provider 的目录元数据。这样请求照样会发到正确的模型，只是桌面版下拉框显示成 “Custom” 而已。2. 如果一定要在桌面版看到模型名并切换，需要检查 model_catalog_json 指向的目录文件、模型可见性字段和 provider 类型。CC Switch v3.16.5 为部分原生 Responses provider 增加了模型目录生成，但这不是所有场景的通用修复；openai_chat 加本地路由仍有过无法显示模型的反馈。升级前应先查看 CC Switch Changelog，再按自己的 apiFormat 验证。如果 CLI 的 /model 也列不出来，那问题就不在选择器，而在 provider 配置本身。先检查是不是 model_provider 写进了项目级 config，或者 base_url 填错了。按这个顺序排查，比瞎改快很多。## 更现实的换网关与自建兼容层思路如果你的网关真的必须要求请求体里带自定义字段，而你又没法让网关改成读 header，那剩下两条路：换网关，或者自建兼容层。换网关是最省事的。一些主流中转服务商一开始就支持 Responses API，并且允许通过 header 或 query 传自定义参数。选服务商的时候直接问清楚三点：支不支持 /v1/responses？允不允许额外请求头？模型 ID 是不是跟官方一致？三个问题都答“是”，就可以直接配进 config.toml。自建兼容层适合团队内部已经有一套模型网关、不想迁移的场景。做法是起一个轻量服务，对外暴露 /v1/responses 端点，收到 Codex 的请求后，把自定义字段塞进请求体再转发给上游。这一步本身不复杂，但坑在工具调用协议上：Responses API 的流式事件、消息类型、工具调用格式都得原样透传，否则 Codex 会莫名其妙中断或报 invalid response。更现实的做法是：先确认上游能否把 tenant 这类信息改为读取请求头。如果可以，在网关路由层使用 Nginx 的 proxy_set_header 就够了；如果它明确要求 JSON 请求体字段，则普通 proxy_set_header 无法解决，需要使用网关自带的请求体改写插件、njs/Lua，或编写一个很薄的应用层适配器。## 适用边界与最终选择建议回到“自定义请求体”这件事本身，更稳妥的选择顺序是：- 如果只是少量团队内部使用，优先跟网关开发者沟通，把额外信息放到 header 里。这是成本最低的方案。- 如果网关是买的商用产品，没法改，那就看它是否允许配置“额外请求头”，很多商业网关其实都支持。- 如果确实只有请求体这一条路，自建兼容层是最后的选择，但要做好维护请求转发和流式协议的觉悟。另外，不要把“支持响应式 API”和“兼容 Codex”画等号。市面上很多标着“OpenAI Compatible”的服务其实只实现了 /chat/completions，而 Codex 走的是 /responses。如果你按本文方法配置后发现请求 404，先查这一层。## 参考资料- Codex Configuration Reference- Codex Advanced Configuration- Codex Authentication- OpenAI Codex Issue #19694- CC Switch Changelog## 最后留一个讨论点如果你接第三方模型网关时遇到 Codex 不支持请求体扩展，你会选择在网关层补字段、改用请求头传参，还是干脆换一个原生支持 Responses API 的服务商？