Scope & Evidence
Codex 需要 Responses，不是普通 Chat Completions
Codex 自定义模型 Provider 的线路协议为 Responses。模型名称包含 “codex” 并不能证明它可通过 Responses 调用；唯一可靠入口是执行时查看模型广场的端点标签。
不要照名称选在 2026-07-18 的公开模型元数据快照中，gpt-5.3-codex* 仅显示 openai，没有 openai-response。因此本教程不推荐这些模型。以后标签若发生变化，也必须重新验证后才能调整结论。
| 等级 | 本页状态 | 含义 |
|---|
| E1 | 运行态公开信息已核对 | 目标模型必须带 openai-response 标签，地址为 https://api.muxllm.com/v1。 |
| E2 | Codex 官方手册已核对 | 自定义 Provider、用户级配置、env_key、Profile 与 wire_api 规则已复核。 |
| E3 | 本批未执行 | 没有启动 Codex 或使用真实 Key 发送请求，页面不声称完成端到端实测。 |
最后核验日期：2026-07-18。Codex 与模型元数据都会升级；配置前先运行本地版本检查并重新查看官方配置参考。
Install
安装或升级 Codex CLI
- 确认本机具备当前官方版本要求的系统环境；安装命令以 OpenAI 官方 Codex 文档为准。
- npm 与 Homebrew 二选一，不要保留多个来源的同名可执行文件。
- 使用
codex --version 记录版本，并用 command -v codex 核对实际路径。
- 开始配置前备份
~/.codex/config.toml；若文件不存在，先创建目录但不要创建项目级认证配置。
npm install -g @openai/codex
codex --version
brew install --cask codex
codex --version
Credential & Model
独立 Key 和模型筛选
- 在 MuxLLM 控制台创建仅供 Codex 使用的独立 Key，并设置合理额度与有效期。
- 在模型广场查找带 openai-response 标签的模型，复制其精确 ID。
- 配置中始终写
MODEL_NAME 占位符，实际执行时再替换；不在公开文档固化动态模型总数或默认模型。
- 为密钥使用专用变量
MUXLLM_API_KEY，避免覆盖其他程序正在使用的 OPENAI_API_KEY。
export MUXLLM_API_KEY="YOUR_API_KEY"
$env:MUXLLM_API_KEY="YOUR_API_KEY"
Provider
在用户级 config.toml 定义 Provider
Provider 和认证属于用户级配置，应写在 ~/.codex/config.toml。当前 Codex 会忽略项目级 .codex/config.toml 中的 model_provider 与 model_providers，并显示启动警告。
model = "MODEL_NAME"
model_provider = "muxllm"
[model_providers.muxllm]
name = "MuxLLM"
base_url = "https://api.muxllm.com/v1"
env_key = "MUXLLM_API_KEY"
wire_api = "responses"
model_provider引用自定义 Provider ID；不能使用保留 ID openai、ollama 或 lmstudio。
base_url写到 /v1 为止，不手工添加 /responses。
env_key告诉 Codex 从哪个环境变量读取密钥；TOML 中不出现真实 Key。
wire_api必须为 responses。普通 chat/completions 不是本教程的 Codex 线路。
不要加 OpenAI 登录MuxLLM 自定义 Provider 使用独立 API Key，不要设置 requires_openai_auth = true，也不要把 ChatGPT 登录状态当作 MuxLLM API 凭证。
Profiles
可选：把模型选择放入独立 Profile
需要在官方 Provider 与 MuxLLM 之间切换时，可在基础 config.toml 保留 Provider 定义，再按当前官方配置文档创建 $CODEX_HOME/profile-name.config.toml 独立 Profile 文件。
model = "MODEL_NAME"
model_provider = "muxllm"
现有配置如果使用 [profiles.muxllm] 等其他格式，不要直接与本页示例混用；先记录 codex --version，再按该版本对应的官方手册迁移。
Acceptance
从配置解析到真实请求逐层验证
- 01版本与路径
确认 codex --version、实际二进制和目标配置目录。
- 02配置无警告
启动时不出现 TOML 解析、保留 Provider ID 或项目级 Provider 警告。
- 03最短请求
使用新会话发一个短文本任务，不启用 MCP、联网或大范围写入。
- 04控制台核对
确认独立 Key、模型和用量符合预期，再用于真实仓库。
E3 尚未执行第 3、4 步会调用模型并可能计费。本次仅编写文档，没有代为运行 Codex 或验证真实响应。
Rollback
移除 Provider 或恢复备份
- 退出 Codex，恢复执行前的
~/.codex/config.toml 备份，或只删除 model_providers.muxllm 及对应顶层选择。
- 若创建了
~/.codex/muxllm.config.toml，确认无依赖后删除或改名保存。
- 清除当前 Shell 的
MUXLLM_API_KEY，并从 Shell Profile 或秘密管理器中移除持久注入。
- 在 MuxLLM 控制台停用不再使用的独立 Key；恢复官方登录时按 Codex 官方认证流程重新登录。
Troubleshooting
按状态码和配置层定位
| 现象 | 常见原因 | 处理方式 |
|---|
| 401 | MUXLLM_API_KEY 未注入、Key 无效或 env_key 拼写不一致 | 新开终端，确认变量名存在但不打印值；检查独立 Key 状态。 |
| 404 | Base URL 重复拼接 /v1、手写了 /responses，或模型没有 Responses 端点 | 恢复本页 Base URL；重新筛选 openai-response 标签。 |
| 429 | 余额、Key 限额、渠道并发或上游速率限制 | 停止自动连续重试，读取返回信息并在控制台核对用量与余额。 |
| 配置被忽略 | Provider 写进项目级 .codex/config.toml 或 Profile 格式与当前手册不一致 | 把 Provider 移到用户级配置；当前官方文档使用单独的 name.config.toml 文件。 |
| wire API 错误 | 省略或误写 wire_api | 精确设置 wire_api = "responses"，不要改成 Chat Completions。 |
Security
Provider 与仓库权限分离
- 密钥通过
env_key 引用，不直接写入 TOML，也不提交到仓库。
- Provider 与认证留在用户级配置；项目级配置只承载可信仓库允许覆盖的行为设置。
- 首次验证在无敏感代码的临时目录中进行，并保持最小审批、沙箱与网络权限。
- 分享日志时遮盖环境变量、Authorization、请求正文、本地路径和账户信息。
- 发现异常用量或疑似泄露时，先停用 Key，再排查本地配置与历史记录。
Official Sources
当前配置以官方手册为准
