Providers 导读
OpenAI 接入:先分清 API Key 和 Codex 订阅,再决定用哪条路
OpenClaw 支持两种 OpenAI 认证:API Key(按量计费,模型前缀 openai/*)和 Codex 订阅(ChatGPT 登录,模型前缀 openai-codex/*)。首次配置时,先选认证方式,再运行 `openclaw onboard` 传入 key 或走 OAuth。最容易踩的坑是模型前缀写错——API Key 用户用了 `openai-codex/*` 模型会报错。
先讲这一页到底在解决什么
OpenAI 接入:先分清 API Key 和 Codex 订阅,再决定用哪条路
OpenClaw 支持两种 OpenAI 认证:API Key(按量计费,模型前缀 openai/*)和 Codex 订阅(ChatGPT 登录,模型前缀 openai-codex/*)。首次配置时,先选认证方式,再运行 `openclaw onboard` 传入 key 或走 OAuth。最容易踩的坑是模型前缀写错——API Key 用户用了 `openai-codex/*` 模型会报错。
第一站
🗝 先分清楚两种进门方式
这页如果一开始没分清,很容易后面越看越乱。其实 OpenAI 在这里主要就两种接法。
像拿 OpenAI 平台发给你的钥匙。你自己控制调用,自己按用量付钱,最适合想清清楚楚管配额和账单的人。
像拿一张订阅会员卡。你不是直接塞 API key,而是用已经有资格的 ChatGPT / Codex 账号登录。
意思是有些云端场景根本不认你自己塞的 API key,它要看的是“你这个 ChatGPT / Codex 账号到底有没有这张票”。
API key 像钥匙,Codex 登录像会员卡,先决定你手里拿哪一种。
第二站
🔑 如果你走 API key 路线,重点就是“把钥匙放对地方”
这一段最适合想要直接、明确、可控的人。你有自己的 OpenAI 平台 key,就走这条。
你想按调用量计费,想自己挑模型,想把账单和使用记录都握在自己手里时,这条路最顺。
openai/gpt-5.4 这种写法,前半截像在写“这是哪家店的”,后半截像在写“你要买哪种型号”。
openclaw onboard --auth-choice openai-api-key:像在 onboarding 里直接告诉系统“我要走钥匙路线”。openclaw onboard --openai-api-key "$OPENAI_API_KEY":像你自己已经把钥匙拿在手里,现在直接塞进去,不走对话式向导。env: { OPENAI_API_KEY: "sk-..." }:像把钥匙放进配置柜里,方便系统以后取用。primary: "openai/gpt-5.4":像告诉 OpenClaw“默认先去找这位模型老师来帮我答题”。
意思不是故意刁难你,而是在说:有些旧模型名字虽然还在某些库里出现,但 OpenAI 实际已经不让你这样叫了,所以 OpenClaw 直接帮你拦住,免得你走一条死路。
第三站
🪪 如果你走 Codex 路线,重点就是“你的账号有没有资格”
这条路跟 API key 最大的不同,不是命令长得不一样,而是它在看“你这个账号有没有那张票”。
如果你已经有 ChatGPT / Codex 订阅,想直接用账号权限,不想额外单独管理 API key,这条会更顺。
因为它不像普通模型那样“有就有、没有就没有”,它更像特定账号才发的特别门票。所以官方一直在提醒你:这东西看 entitlement,不是你想叫就能叫。
openclaw onboard --auth-choice openai-codex:像在 onboarding 里说“这次别让我拿钥匙,我用会员卡刷进去”。openclaw models auth login --provider openai-codex:像单独去办一次会员登录,不走整套 onboarding。primary: "openai-codex/gpt-5.4":像告诉系统“默认走 Codex 这条专属通道”。
Codex 路线不只是“换个登录方式”,而是在看你的账号到底有没有这张模型入场券。
第四站
🚚 transport、WebSocket、SSE,这些都在讲“消息走哪条路”
这一段最容易把人看晕。其实别想太多,它就是在讲 OpenClaw 和 OpenAI 之间,消息到底走哪条路更顺。
像一条一直保持连通的快车道。连上以后,后面说话来回更流畅。
像一条也能送消息的备用路,通常比 WebSocket 更朴素,但兼容性好。
像先试试快车道,不行就改走备用路。默认这么做,是因为它最省心。
像在正式开跑前先热一下车。官方说它是可选的,但 OpenClaw 默认帮你开着,是为了让第一轮响应别那么慢吞吞。
第五站
⚡ fast mode、priority、service tier,都在讲“要不要插队走快一点”
这一段不是在讲新模型,而是在讲同一个模型用什么跑法。
像跟系统说:“这次别慢慢抠细节了,先快一点给我答。”它会自动把一些参数往更低延迟方向拧。
像给请求贴一张“这份比较急”的标签。能更快,但通常也意味着成本和资源策略不同。
serviceTier: "priority":像给请求加急。fastMode: true:像告诉系统“这轮先讲快一点、短一点、别想太久”。/fast on
像会话里临时按下“加速按钮”,比改大配置更像一次性现场切换。
fast mode 不是换模型,而是给模型换跑法。
第六站
🧳 server-side compaction 在讲“聊天太长了,要不要帮你先收拾书包”
这段如果直读很容易像论文。其实它就在说:当上下文越来越长时,要不要先在服务器那边帮你压一压。
因为对话越拖越长,书包就越塞越满。再不整理,后面拿东西会越来越笨、越来越贵。
像在书包快装不下的时候,先帮你把旧纸条压成更紧凑的一包,再继续往里放。
responsesServerCompaction: true:像明确说“对,这个书包要有人帮我定期整理”。responsesCompactThreshold: 120000:像告诉整理员“等书包塞到这个程度再开始收拾”。responsesServerCompaction: false:像说“别自动整理,我自己来”。
compaction 不是新能力,它是聊天太长时的收纳术。
最后总结
🎈 把 OpenAI 这页压缩成一句最好记的话
这页最核心的不是参数,而是先选进门方式,再决定消息怎么跑、要不要加速、要不要收拾长上下文。
如果你接下来只继续看一页,我建议先看模型总览或你真正要用的那条认证路径页面。因为 OpenAI 这页的关键,不是全背下来,而是先选对路。