Codex 使用 OpenAI Responses 协议（wire_api 为 responses），a4api 勾选 codex 目标的配置方案会把服务商与模型写入 ~/.codex/config.toml，并同步维护模型目录 models.json。上游原生支持 Responses 时直连，否则经本地翻译代理把 Responses 翻译为 Chat Completions 转发，让智谱等只有 Chat Completions 的服务商也能驱动 Codex。本文章介绍该目标的托管字段、写入示例、直连与代理两种链路、模型目录的维护逻辑与常见问题。
1. 写入哪个文件、写哪些内容
目标文件为 ~/.codex/config.toml（可用环境变量 A4API_CODEX_CONFIG_PATH 覆盖）。切换时更新两类内容：
| 位置 | 字段 | 写入内容 |
|---|---|---|
| 顶层 | model |
配置方案中的模型名 |
| 顶层 | model_provider |
指向 a4api 托管的服务商条目键名 |
[model_providers.a4api_p<服务商ID>] |
name / base_url / wire_api / experimental_bearer_token | 服务商条目本体 |
托管条目以 a4api_p 为前缀加服务商 ID 命名；切换时会先移除旧的 a4api 托管条目再写入新条目，用户自己定义的其他 model_providers 条目原样保留。wire_api 固定为 responses，适配 Codex CLI 的 Responses 协议。
1.1 直连上游（原生 Responses）
服务商勾选了「原生 Responses」（当前预置模板中仅 DeepSeek-openai）时，Codex 直接访问上游：
model = "deepseek-v4-flash"
model_provider = "a4api_p3"
[model_providers.a4api_p3]
name = "DeepSeek-openai"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
experimental_bearer_token = "sk-真实APIKey"
1.2 经本地代理转发（非原生上游)
上游只提供 Chat Completions 时（智谱 v4、OpenRouter、本地 LLM Studio 等），base_url 指向本地翻译代理，鉴权 token 换成代理 token，真实 API Key 不落盘：
model = "glm-4.7"
model_provider = "a4api_p4"
[model_providers.a4api_p4]
name = "智谱-openai"
base_url = "http://127.0.0.1:17890"
wire_api = "responses"
experimental_bearer_token = "本地代理鉴权token"
代理在转发前把 Responses 请求翻译为 Chat Completions，详见本地翻译代理。
2. 模型目录 models.json
Codex 解析一个自定义模型时需要完整的元数据（上下文窗口、推理档位、工具形态等），这些信息来自模型目录：默认 ~/.codex/models.json，或跟随 config.toml 中 model_catalog_json 指定的路径（可用环境变量 A4API_CODEX_CATALOG_PATH 覆盖）。
切换时 a4api 确保所用模型出现在目录里，规则如下：
| 目录现状 | a4api 的动作 |
|---|---|
| 已有该模型的完整条目（含消息模板等深度字段） | 不做任何改动 |
| 已有该模型的简略条目 | 移除后按完整模板重建，避免 Codex 解析失败 |
| 没有该模型 | 优先复制目录中已有条目的结构（如 deepseek-v4-flash），目录为空时使用内置默认模板，仅替换标识字段 |
重建条目时统一设置 slug 与 display_name 为模型名、描述标注 via a4api local proxy，并把 context_window 与 max_context_window 设为 200000、有效窗口占比 95%。models.json 的写法同样是先备份语义上的安全写入——临时文件加原子替换。
3. 切换后的生效方式
Codex 在进程启动时读取 config.toml 与模型目录，切换完成后界面会明确提示「重启 Codex 后生效」。a4api 不代管 Codex 进程的重启（与 Claude Code 的一键重启不同），手动重开终端里的 Codex 即可。
含 codex 目标] --> B{服务商是否
原生 Responses} B -->|是| C[config.toml
指向上游+真实Key] B -->|否| D[启动本地代理
config.toml 指向代理] C --> E[维护 models.json
模型元数据] D --> E E --> F[提示重启 Codex] F --> G[Codex 重启后
新配置生效] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style D fill:#ffecd6,stroke:#e67e22,stroke-width:2px style E fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style F fill:#fdebd0,stroke:#b7950b,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
4. 备份与合并保护
与 Claude Code 目标一致，写入 config.toml 前自动备份到数据目录（命名 codex.config.时间戳.toml.bak，滚动保留 5 份），写入采用临时文件加原子替换。合并策略上只动顶层 model、model_provider 与 a4api 前缀的服务商条目，用户手工维护的 MCP 配置、审批策略等其他 TOML 内容不受影响。
三端统一的备份与回滚方法见配置方案与一键切换第 5 节；config.toml 及相关文件的实际落盘位置见数据目录与日志说明。
5. 常见问题
问：为什么我的 Codex 配置没有走本地代理？
答：说明你选的服务商带有「原生 Responses」标记，Codex 直连上游 /responses 接口，这是设计内的最优路径，延迟更低、少一跳转发。目前仅 DeepSeek 官方满足条件。
问：请求报 400 上游错误怎么办？
答：0.1.1 至 0.1.3 版本已修复三类典型 400（developer 角色映射、残缺 tool_call 历史、tool 响应顺序），若仍遇到请确认升级到最新版；仍复现时附上 ~/.a4api/logs/a4api.log 相关片段反馈，见版本更新说明。
问：models.json 里多了一个我没建过的条目？
答：那是 a4api 为切换所用模型补全的元数据条目，描述会标注 via a4api local proxy。它只增不删、不影响你自己维护的条目；不需要时删除该条目即可，下次切换会按需重建。
问：同一个服务商想同时给 Claude Code 和 Codex 用？
答：直接在配置方案里同时勾选两个目标即可。注意此时应选择 OpenAI 兼容类型服务商：Claude Code 一侧由本地翻译代理供给 Anthropic 流量，Codex 一侧视原生能力直连或走代理，两端互不干扰。
举手提问