OpenAI
OpenAI 这一页最容易让人混乱，因为名字很像：
openai：模型提供商前缀，也就是模型写成openai/gpt-5.5。openai-codex：旧配置和 Codex OAuth 登录资料的名字。codex：OpenClaw 里负责原生 Codex app-server 运行时的插件/运行时。
先记住一句话：
新配置里，OpenAI Agent 模型优先写 openai/gpt-5.5。
就算你用的是 ChatGPT/Codex 订阅登录，模型名也不要写成 openai-codex/gpt-*。旧的 openai-codex/* 不是推荐的新模型路线。升级后请运行：
openclaw doctor --fix
openclaw config validateDoctor 会尽量把旧模型引用修成 openai/*，并保留能用的 Codex 登录资料。
先选你是哪一种用法
| 你想做什么 | 推荐模型写法 | 登录/付费方式 |
|---|---|---|
| 用 ChatGPT/Codex 订阅跑 Agent | openai/gpt-5.5 | openai-codex OAuth 登录 |
| 用 OpenAI Platform API Key 跑 Agent | openai/gpt-5.5 | 配好 OpenAI API Key，并按需要设置 auth order |
| 用 OpenAI 图片、语音、Embedding | openai/gpt-image-2 等 | OpenAI API Key 或支持的 OAuth 路线 |
| 试 ChatGPT Instant 最新别名 | openai/chat-latest | 只建议 API Key 实验，不建议生产默认 |
把这三层分开看：模型名决定用哪个模型，登录方式决定用哪份凭据，运行时决定由哪个执行后端处理 Agent turn。 新手只需要先把模型写成 openai/gpt-5.5。
方式 A：ChatGPT/Codex 订阅登录
适合：你有 ChatGPT/Codex 订阅，想让 OpenClaw 走原生 Codex 运行时。
第一步：登录 Codex OAuth
openclaw onboard --auth-choice openai-codex或者只登录模型认证：
openclaw models auth login --provider openai-codex如果服务器没有方便打开浏览器，用设备码：
openclaw models auth login --provider openai-codex --device-code第二步：设置模型
openclaw config set agents.defaults.model.primary openai/gpt-5.5配置文件里等价写法：
{
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" }
}
}
}OpenAI Agent turn 默认会选择原生 Codex app-server 运行时。 普通用户不需要写 agents.defaults.agentRuntime。
第三步：检查是否真的登录成功
openclaw models auth list --provider openai-codex
openclaw models statusGateway 已经运行后，也可以在聊天里发：
/codex status方式 B：OpenAI API Key
适合：你想走 OpenAI Platform 按量计费，或者需要图片、Embedding、Realtime 等平台能力。
CLI 设置
openclaw onboard --auth-choice openai-api-key也可以非交互式传入：
openclaw onboard --openai-api-key "$OPENAI_API_KEY"配置示例
{
env: {
OPENAI_API_KEY: "sk-..."
},
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" }
}
}
}如果你同时有 Codex 订阅和 API Key，并希望订阅优先、API Key 备用，可以把认证顺序放在 auth.order.openai 下。 这样模型名仍然保持 openai/gpt-5.5：
{
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" }
}
},
auth: {
order: {
openai: [
"openai-codex:user@example.com",
"openai:api-key-backup"
]
}
}
}openai-codex/* 旧写法怎么办？
如果配置里还有旧引用：
openai-codex/gpt-*
codex-cli/gpt-*先运行：
openclaw doctor --fix
openclaw config validateDoctor 会尽量：
- 把旧模型名修成
openai/*。 - 保留已有的
openai-codexOAuth 登录资料。 - 清理旧的 runtime pin，避免会话继续走过期路线。
不要把 openai-codex 当成新模型前缀
openai-codex 现在更多是旧配置和登录资料命名。新 Agent 模型引用优先使用 openai/gpt-5.5。 只有账号目录明确暴露的特殊 Codex 模型，才可能需要保留特殊旧路线；普通用户不要从这里开始。
Realtime 语音账单要特别注意
OpenAI Realtime 语音不是消耗 ChatGPT/Codex 订阅额度。 它走的是 OpenAI Platform Realtime API，需要 OpenAI Platform 组织有可用额度或账单。
所以可能出现这种情况：
文字聊天能用，因为 Codex OAuth 正常。
Realtime 语音失败，因为 OpenAI Platform 没有充值或没有账单。如果看到 insufficient_quota 或 “You exceeded your current quota”，请到 OpenAI Platform Billing 检查对应组织的额度。
openai/chat-latest 是什么？
openai/chat-latest 是 OpenAI API 的移动别名，适合实验 ChatGPT 当前 Instant 模型。
不建议把它当生产默认模型，因为它会随 OpenAI 调整而变化。 生产配置优先使用明确模型，例如：
{
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" }
}
}
}