Codex 配置实战：官方主力 + Profile 隔离，第三方模型的二等公民现实

TL;DR

Codex 是一套围绕 Agent Loop 的运行框架（不是某个固定模型）。OpenAI 自家模型是原生主力，第三方模型通过 wire_api = "responses" + Profile 机制也能接进来，但受限明显：协议门槛、任务内不能跨 provider 自由切换、部分高级模式受限。这篇文章从配置最佳实践出发，把"官方主力 + Profile 隔离第三方"这条主线讲清楚。

背景

最近在配置 Codex 把不同模型接进来的过程中，整理出一些实战要点。资料来源：OpenAI 官方文档、openai/codex GitHub 仓库、社区资料加上自己踩过的坑。下面把"官方主力 + Profile 隔离第三方"这条主线讲清楚。

一、Codex 的核心架构：Agent Loop + Responses API

Codex 的运行框架（Agent Loop）负责协调用户、模型、工具三者：模型发出工具调用，框架执行，结果回流给模型继续推理。这个循环靠 Responses API 协议驱动——只有支持 Responses API 的模型才能完整接入，旧的 Chat Completions API 路径已经停止支持。

由此得出一个判断：

• "主力"不强制是 OpenAI 模型，关键是模型得能驱动完整的 Agent Loop。换句话说只要 Responses API 兼容，本地模型、第三方云、企业网关都可以当主力。
• "官方主力 + 第三方辅助"是社区共识的稳妥选择，不是强制的。
• 分工通过 Profile 灵活控制，可以在启动时切换，没有硬编码的优先级。

二、配置最佳实践：Profile 隔离

核心原则：日常使用保持纯净的官方登录链路，第三方模型通过 Profile 机制实现隔离管理，互不干扰。

配置文件结构

# ~/.codex/config.toml

# 默认走 ChatGPT OAuth
profile = "chatgpt"
model = "gpt-5"          # 以官方模型当前稳定版本为准
model_reasoning_effort = "medium"

# 1. 官方登录 Profile
[profiles.chatgpt]
model_provider = "openai"
model = "gpt-5"
model_reasoning_effort = "medium"

# 2. 第三方中转 Profile（按需启用）
[profiles.my-gateway]
model_provider = "my_gateway"
model = "<third-party-model>"

# Provider 定义
[model_providers.my_gateway]
name = "my_gateway"
base_url = "https://your-third-party-gateway.com/v1"
wire_api = "responses"      # ← 关键：必须 Responses API
env_key = "MY_GATEWAY_API_KEY"   # 用环境变量名，不直接写 key

使用方式

codex                              # 默认 profile = chatgpt，走官方
codex --profile my-gateway         # 启动时切到第三方

如果想得更直白，可建 shell 别名：

alias codexfox='codex --profile my-gateway'

一定要避开的误区

三、第三方模型"二等公民"的三条现实约束

不是"能不能用"的问题，是好不好用的问题。三条约束：

已验证可直连的方案

实测发现，国内一些厂商提供的官方 API 可以直接填进 Codex Provider 配置走 Responses 协议，不需要额外接协议转接桥。例如某国产厂商的 m3 系列模型，把它声明成 Provider 即可：

[model_providers.minimax-cn]
name = "minimax-cn"
base_url = "<该厂商官方 API 入口>"
wire_api = "responses"
env_key = "MINIMAX_API_KEY"

[profiles.minimax-m3]
model_provider = "minimax-cn"
model = "minimax-m3"

调用方式与官方一致：codex --profile minimax-m3。这种方式绕开了"三方默认只给 Chat Completions 端点"的协议门槛，是目前国内接入 Codex 最干净的路径。

1. 协议门槛：大多数国产模型不能直连

Responses API 是基础门槛。DeepSeek、Kimi、智谱 GLM 这些主流国产模型默认只暴露 Chat Completions 端点（/v1/chat/completions），直连 Codex 会得到 404。

可选方案：

• 协议转接桥：本地或网关层做 Chat Completions ↔ Responses 双向翻译。
• 使用原生支持 Responses API 的服务：例如阿里百炼是国内少数原生落地 /v1/responses 端点的。
• 本地模型（Ollama / LM Studio）：走保留 ID，不受协议限制直接支持。

2. 灵活性受限：任务内不能跨 provider 动态切

官方账号下，用户可以在一个 Codex 会话里通过 /model 在不同 OpenAI 模型间切换——这是 OpenAI 内建能力。

第三方 Provider 走的是启动时 --profile 锁定，启动后整个会话只能用启动时指定的那个型号。想换就得退出会话再启动。

3. 高级 Agent 模式受限

把 Chat Completions 假装成 Responses API 的转接方案里，部分 Responses 独有的事件字段会在转换中丢失；长上下文任务的会话恢复成功率会下降；某些与官方模型深度整合的高级功能只对原生 OpenAI 模型开放。整体表现就是响应更慢、生态更薄。

本质

"二等公民"的根源是 协议 + 灵活性 + 生态完整性 三层叠加。不是说不能做主力，而是"做主力时的体验不平等"。

四、场景决策表

五、沙盒与权限：一句话原则

Codex 默认 workspace-write 沙盒 + on-request 批准策略，三档沙盒分别是 read-only / workspace-write（默认）/ danger-full-access。不要为了少弹窗而直接上 danger-full-access + never 组合——需要扩大可写范围时，用 sandbox_workspace_write.writable_roots 加特定目录，而不是掀掉整个沙箱。

六、常见问题

Q: 看起来卡住了怎么办？

按顺序：

1. 先检查终端是否有待批准的 approval 请求（最常见原因）
2. 跑一条简单命令（如 git status）验证终端活着
3. 还不行就开一个更小、更聚焦的新会话

Q: 配置文件写了但没生效？

三层排查：

1. 项目是否被标记为不可信（项目级配置只对可信项目加载）
2. 是否有 CLI 参数或 Profile 文件在更上层覆盖了它
3. 项目根目录是否有 AGENTS.md（不是 CLAUDE.md），会被项目级配置读取

Q: 模型元数据警告 Model metadata for 'xxx' not found

不影响调用，但可能导致性能下降。可手动补：

model_context_window = 200000
model_max_output_tokens = 64000

七、参考与查证

本文内容由 agent 整理。已核对的内容：

• Codex CLI 配置 Profile 机制存在且按 ~/.codex/config.toml [profiles.<name>] 形式组织
• 第三方 provider 通过 wire_api = "responses" 接入是当前正确做法

以下信息仅作转述，读者需自行核对：

• 阿里百炼是否原生落地 /v1/responses 端点
• 第三方模型实测具体成本数字
• "Tibo 这位 OpenAI Codex 团队负责人的公开发言" 引用

如发现错漏，欢迎 issue 指正。