OpenClaw 接入 Codex Harness：不是换个模型，而是换了一套更原生的 Agent 运行方式

很多人第一次看到 Codex Harness，会下意识把它理解成一件很简单的事：

“哦，就是把 OpenClaw 背后的模型换成了 GPT-5.5。”

但如果你认真看完文档，就会发现事情完全不是这么回事。

它不是单纯换模型，而是在 OpenClaw 里引入了一条更原生的 Codex 运行链路。

这件事的意义，比“换个更强的模型”大得多。

因为一套 Agent 系统，真正决定体验的，往往不只是模型本身，而是它背后那条运行时链路是不是足够原生、足够稳定、足够可恢复。

一、先把三个概念分开：模型、运行时、聊天表面

OpenClaw 这套设计里，有一个非常关键但很容易被忽略的拆分：

• openai/gpt-5.5
  
   是模型引用
• codex
  
   是运行时
• Telegram、Discord、Slack、WebChat 这些只是交互表面

这意味着什么？

意味着你不能再用“我选了哪个模型”去代替“这套 Agent 实际怎么跑”的判断。

模型只决定“脑子是谁”。

运行时决定的是：

• 会话线程怎么保留
• 工具调用怎么续跑
• 上下文怎么压缩
• 失败后怎么恢复
• 执行到底是宿主在兜，还是原生链路在兜

而 Codex Harness，真正切换的就是这层能力。

二、Codex Harness 到底在做什么

文档里讲得很直白。

OpenClaw 自带一个 codex 插件。启用之后，OpenClaw 可以把嵌入式的 OpenAI agent turn 交给 Codex app-server 去执行，而不是继续走内置的 OpenClaw harness。

也就是说，Codex 开始接管更底层的 Agent 会话能力，比如：

• 原生 thread resume
• 原生 tool continuation
• 原生 compaction
• app-server 级别执行

而 OpenClaw 仍然保留外层能力：

• 聊天渠道
• 会话文件
• 模型选择
• 动态工具
• 审批策略
• 媒体分发
• 可见转录镜像

这不是替代关系，而是分工关系。

OpenClaw 管外层编排，Codex 管底层执行。

这也是为什么我会说，这不是“换模型”，而是“换运行时”。

三、它解决的不是能不能用，而是够不够原生

很多集成在功能表上都能写一句“支持某某模型”，但真正用起来，差距非常大。

原因就在这里。

支持调用一个模型，不代表你支持它原生的线程、工具续跑、压缩和状态恢复能力。

而 Codex Harness 的价值，恰恰就是尽量保留 Codex 原生那套能力。

对于重度 Agent 用户来说，这种差别不是“锦上添花”，而是底层体验分水岭。

因为复杂任务真正容易崩的地方，通常不是模型不会答，而是这些问题：

• 会话能不能稳定续上
• 工具半路中断后能不能接着跑
• 长线程压缩是否自然
• 线程状态是否前后一致

这些全都是运行时问题，不是模型参数问题。

四、配置时最容易踩的坑：模型名别再写旧前缀

这份文档里有一个点被反复强调，我建议所有人记住：

新配置里请用 canonical 的 OpenAI model ref，比如：

1"openai/gpt-5.5"

不要再写：

1"openai-codex/gpt-*"

为什么？

因为 OpenClaw 现在在刻意把“模型提供方”和“运行时策略”分开。

也就是说：

• 你使用的是 openai/gpt-*
• 但底层是不是由 codex runtime 承接，是另一层策略决定的

旧的 openai-codex:* auth profile 仍然兼容，老安装也还能跑，但它已经不该是新配置的写法了。

这个变化非常重要。

它说明 OpenClaw 正在把架构从“把运行时揉进模型名前缀里”，升级成“模型归模型，运行时归运行时”。

这是更干净、更长期主义的设计。

五、最推荐的接入方式：Codex OAuth + bundled codex plugin

如果你的目标不是研究边角配置，而是尽快跑起来，那么最推荐的路径非常简单：

先登录 Codex OAuth：

1openclaw models auth login --provider openai-codex

然后启用 bundled codex 插件，并把默认模型设成：

1"openai/gpt-5.5"

最小可用配置大概长这样：

1{2  plugins: {3    entries: {4      codex: {5        enabled: true,6      },7    },8  },9  agents: {10    defaults: {11      model: "openai/gpt-5.5",12    },13  },14}

如果你本身用了 plugins.allow，记得把 codex 也加进去。

这套路径的优点很现实：

• 配置简单
• 含义清楚
• 跟官方文档一致
• 后续排障最省力

六、一个容易误解的点：API Key 兜底，不代表运行时切回 OpenClaw

文档里还有一个很值得注意的设计。

你可以在 auth.order.openai 里配置“订阅优先、API Key 兜底”，比如：

1{2  auth: {3    order: {4      openai: ["openai-codex:user@example.com", "openai:api-key-backup"],5    },6  },7}

很多人看到这一段，第一反应是：

“那一旦切到 API Key，是不是就不走 Codex 了？”

不是。

文档明确说了，API Key 只是认证 fallback，不代表运行时从 Codex 切回 OpenClaw，也不代表请求变成普通 OpenAI Responses。

这其实很成熟。

因为它把两件经常被混淆的事情彻底拆开了：

• 用谁认证
• 由谁执行

认证策略和运行时策略，不应该硬绑在一起。

七、什么时候你应该显式设置 fail-closed

默认情况下，只要 bundled codex 插件可用，openai/gpt-* 的 OpenAI agent turn 就会解析到 Codex。

但有一种场景，你应该更激进一点：

你想明确规定，这个部署必须走 Codex，不能悄悄回退。

这时候就要显式设置：

1agentRuntime.id: "codex"

它的意义是 fail-closed。

也就是：

• codex
  
   插件没启用，不跑
• app-server 版本太旧，不跑
• app-server 启动失败，不跑

直接失败，而不是偷偷换一条别的路径。

我个人非常赞同这个设计。

因为复杂系统里，最危险的不是报错，而是静默回退。

你以为自己在验证 Codex，其实系统早就帮你切去另一条链路了。 这种“表面正常”的假象，最容易让排障变得很痛苦。

八、验证自己是不是已经真正跑在 Codex 上

不要只看配置写得像不像，直接看运行结果。

最简单的一步，是在目标聊天里执行：

1/status

如果当前 OpenAI agent turn 真的是走 Codex runtime，你会看到：

1Runtime: OpenAI Codex

然后继续看：

1/codex status2/codex models

按照文档说明：

• /codex status
  
   可以查看 app-server 连通性、账号、限额、MCP servers、skills
• /codex models
  
   可以列出当前 Codex app-server 暴露出来的实时模型目录

我建议把验证拆成三层：

1. /status
   
    看 runtime 名字对不对
2. /codex status
   
    看 app-server 状态通不通
3. /codex models
   
    看模型目录是否正常

这三步都过了，才算真正跑顺了。

九、它和 OpenClaw 自己的 code mode 不是同一件事

这个点文档也专门提了一下，但很多人第一次看会忽略。

Codex Harness 不是 OpenClaw 自己的 code mode。

两者不是同一套机制。

可以粗暴理解为：

• OpenClaw code mode
  
   是 OpenClaw 自己的执行能力
• Codex Harness
  
   是让 Codex app-server 原生承接 Agent 执行能力

它们目标有重叠，但技术路线完全不同。

如果把这两件事混为一谈，后面做排障、看运行边界、理解能力归属时就会越来越乱。

十、为什么这件事值得写进你的 Agent 基建里

如果你只是偶尔问两句，Codex Harness 未必会给你一种立刻炸裂的体感。

但如果你正在做下面这些事，它就非常值得：

• 长线程任务
• 高频工具调用
• 工具中断后的续跑
• 更稳定的原生上下文压缩
• 让 OpenClaw 作为统一入口，但保留 Codex 的原生味道

本质上，这不是一个“模型切换功能”。

它更像是一个 Agent runtime 升级点。

它代表的是一种更成熟的系统分层方式：

• 通讯层归 OpenClaw
• 执行层归 Codex
• 路由策略清晰
• 失败边界明确
• 原生能力尽量不打折

我觉得，这才是这篇文档真正有价值的地方。

最后

如果只能用一句话总结 Codex Harness，我会这么说：

它不是让 OpenClaw“支持 Codex”而已，而是让 OpenClaw 真正学会把 Codex 当成原生运行时来使用。

你真正需要记住的只有几条：

• 用 openai/gpt-*，不要再写 openai-codex/gpt-*
• 把认证顺序放在 auth.order.openai
• 推荐使用 bundled codex plugin + Codex OAuth
• 想严格不回退，就显式设置 agentRuntime.id: "codex"
• 用 /status、/codex status、/codex models 验证实际运行状态
• 不要把它和 OpenClaw 自己的 code mode 混为一谈

如果你正在把 OpenClaw 往真正的 Agent 操作系统方向搭，这篇 Codex Harness 文档，值得认真吃透。