Codex 国内接入教程（2026）：config.toml 一次配好，直连 Responses API
Codex 是 OpenAI 的终端编程 Agent。国内使用它的第一道坎不是安装，而是 API 通道：Codex 走 Responses API（wire_api = "responses"），大量只做了 Chat Completions 转发的服务根本承接不了它的请求。本文用汕拓智算的 OpenAI 兼容面演示完整接入——原生支持 /v1/responses，填一个 Base URL 即可。
准备工作
- 在控制台创建一个分组平台为 OpenAI 的 API 密钥（形如
sk-...）。分组平台决定密钥走哪套协议面，这一步选错，后面全是 4xx。 - 本地已安装 Codex CLI 或 IDE 扩展。
- Base URL：
https://swato.ai/v1。
先做连通性验证（环境变量）
正式写配置文件之前，先用环境变量做一次临时验证，把变量问题和配置问题分开排查:
bash
export OPENAI_API_KEY="sk-your-key"
export OPENAI_BASE_URL="https://swato.ai/v1"
codex能启动、能对话,说明密钥与网络没问题,再进入下一步。
写入 config.toml 持久化
CLI 与 IDE 扩展共用同一份 ~/.codex/config.toml，推荐把配置固化在这里：
toml
model_provider = "SwatowAPI"
model = "gpt-5.3-codex"
review_model = "gpt-5.3-codex"
model_reasoning_effort = "high"
disable_response_storage = true
network_access = "enabled"
[model_providers.SwatowAPI]
name = "SwatowAPI"
base_url = "https://swato.ai/v1"
wire_api = "responses"
requires_openai_auth = true两个容易踩的点：
wire_api = "responses"不能省。这告诉 Codex 走 Responses API 协议，也是网关必须原生支持的端点。model里的gpt-5.3-codex仅为示例。确切的模型 id 以GET /v1/models或模型价格页为准，id 会随版本更新变化。
更省事的方式：一键脚本
控制台的 API 密钥页面里，对任意密钥点击「使用密钥」，切到「Codex 一键脚本」标签页，可以复制或下载 macOS/Linux 或 Windows 版脚本。脚本内嵌了你选定的密钥，运行前会自动备份你已有的 Codex 配置，适合不想手改 TOML 的场景。
首次运行：从只读任务开始
bash
cd /path/to/your/project
codex "请只读取项目结构，并总结这个项目的主要模块。"先跑只读任务确认认证、路由、网络都正常，再交给它写入类任务。这是接入任何 AI 编程 Agent 的通用安全习惯。
三层链路验证
- 客户端：Codex 能启动，并读到项目内容。
- 网关：请求打到站点的
/v1入口，而不是走了系统代理或旧的过期配置。 - 账本：控制台用量台账出现这次调用，能看到模型、延迟、token 与计费。
第三层最关键。汕拓智算每笔调用带 trace id、失败不计费、按官方定价结算，台账里能逐笔核对——能对账，才谈得上放心把日常开发流量交给它。
常见排障
| 现象 | 处理 |
|---|---|
401 / Unauthorized | 密钥必须是本站创建的；环境变量要在当前 shell 生效；配置里 env_key 名称要对得上 |
Invalid base URL | 必须带协议（https://swato.ai/v1）；不要用裸域名，也不要在 /v1 后面再接 /chat/completions |
| IDE 仍打到旧地址 | 重启 IDE 及扩展窗口；检查没有项目级配置覆盖 ~/.codex/config.toml |
| 请求成功但账本无记录 | 确认用的是同一个站点域名和同一把密钥；本地、预发、生产的账本互不相通 |
相关阅读
常见问题
为什么很多"中转 API"跑不了 Codex？
Codex 走的是 OpenAI 的 Responses API（wire_api = "responses"），不是传统的 Chat Completions。账号池式转发通常只实现了 /v1/chat/completions，缺少原生 /v1/responses 支持，Codex 一连就报错。能不能直连跑通 Codex，本身就是检验网关协议完整度的试金石。
Codex 接入用什么分组的密钥？
OpenAI 分组。汕拓智算按密钥分组决定协议面，Codex 的请求要落到 OpenAI 兼容面，所以创建密钥时分组平台选 OpenAI。
config.toml 里的 model 填什么？
以 GET /v1/models 或控制台模型价格页返回的确切 ID 为准。Codex 模型 id 会随版本更新变化，不要把示例里的 id 当固定值写死。
CLI 能用但 IDE 扩展连不上怎么办？
CLI 与 IDE 扩展读取的是同一份 ~/.codex/config.toml。先确认配置里的 Base URL 与密钥正确，然后重启 IDE 让扩展重新加载配置，并检查是否有项目级配置覆盖了全局配置。
怎么确认请求真的走了网关？
三层验证：Codex 能启动并读到项目内容；请求打到站点的 /v1 入口而不是残留的系统代理；控制台用量台账出现这次调用，能看到模型、token 用量与计费。台账里有记录，链路才算真正打通。