OpenClaw 5.12 故障修复:Codex Harness 未注册的定位与恢复

摘要

一次 OpenClaw agent 无法回复的排障记录：从日志中的 `Requested agent harness “codex” is not registered` 出发，定位到缺失 `@openclaw/codex` 插件，并通过安装、启用、重启 Gateway 完成修复。

OpenClaw 5.12 更新故障：agent 在收到消息后没有正常回复，日志里反复出现下面的错误：

Embedded agent failed before reply: Requested agent harness "codex" is not registered.Agent failed before reply: Requested agent harness "codex" is not registered.

飞书里出现的提示如下：

⚠️ Something went wrong while processing your request. Please try again, or use /new to start a fresh session.

这篇文章记录一下完整排查过程。结论先说：

> 配置里已经指定使用 `codex` agent runtime，但本机没有安装注册这个 runtime 的 `@openclaw/codex` 插件。安装插件并重启 Gateway 后恢复。

1. 故障现象

OpenClaw 的外部表现是 agent 不回复，日志中核心错误是：

Requested agent harness "codex" is not registered.

这个错误很关键。

它不是说模型不可用，也不是说 OpenAI OAuth 一定失效，而是 OpenClaw 在执行 agent turn 时，配置要求使用名为 `codex` 的 harness，但当前 Gateway 运行时没有任何插件注册这个 harness。

换句话说：

> 配置想用 `codex`，但运行时不知道 `codex` 是谁。

2. 初步检查

先确认 OpenClaw CLI、配置和服务状态是否正常：

openclaw --helpopenclaw config validateopenclaw statusopenclaw models statusopenclaw agents listopenclaw memory status

检查结果显示：

OpenClaw CLI 正常
版本为2026.5.12
配置文件有效：~/.openclaw/openclaw.json
Gateway 服务在运行
openai-codex OAuth profile 存在
多个 agent 的主模型都是openai/gpt-5.5

继续查看 agent 配置，发现 `openai/gpt-5.5` 相关配置里都有：

{  "agentRuntime": {    "id": "codex"  }}

这说明 OpenClaw 当前明确要求通过 Codex harness 来运行 agent。

3. 关键定位：插件没装

接着查看插件列表：

openclaw plugins list

已启用插件里有：

openaigoogleollamaopenroutermemory-corebrowseropenclaw-larkopenclaw-weixin

但没有：

codex

这就很可疑了。

继续查本地 OpenClaw 文档，看到 Codex harness 的配置要求是：

{  "plugins": {    "entries": {      "codex": {        "enabled": true      }    }  }}

如果配置里使用了 `plugins.allow`，还必须包含：

codex

再看 OpenClaw 的插件说明，`codex` 插件的分发包是：

@openclaw/codex

至此基本定位：

> 当前配置使用了 `agentRuntime.id = “codex”`，但本机缺少 `@openclaw/codex` 插件，所以 Gateway 无法注册 `codex` harness。

4. 修复：安装 Codex 插件

执行插件安装：

openclaw plugins install npm:@openclaw/codex

第一次安装时遇到网络错误：

npm error code ENOTFOUNDrequest to https://registry.npmjs.org/@openclaw%2fcodex failed

这是 npm registry 访问失败，不是 OpenClaw 配置错误。

网络恢复后重新执行，安装成功：

Installing @openclaw/codex into ~/.openclaw/npm…Installed plugin: codexRestart the gateway to load plugins.

安装过程自动修改了配置，并生成了备份：

~/.openclaw/openclaw.json.bak

5. 确认配置

检查 `codex` 插件配置：

openclaw config get plugins.entries.codex

结果：

{  "enabled": true,    "config": {      "codexDynamicToolsLoading": "searchable",      "codexDynamicToolsExclude": []    }}

再检查 `plugins.allow`：

openclaw config get plugins.allow

结果里已经包含：

codex

这说明插件已经被允许并启用。

6. 重启 Gateway

插件安装后，需要重启 Gateway 才会真正加载：

openclaw gateway restart

重启成功：

Restarted LaunchAgent: gui/501/ai.openclaw.gateway

7. 验证插件加载

检查 `codex` 插件状态：

openclaw plugins inspect codex

结果显示：

Codexid: codexStatus: loadedSource: ~/.openclaw/npm/node_modules/@openclaw/codex/dist/index.jsVersion: 2026.5.12Capabilities:text-inference: codexmedia-understanding: codex

再看 Gateway 日志，启动时已经加载了 `codex`：

http server listening (5 plugins: browser, codex, memory-core, openclaw-lark, openclaw-weixin)gateway ready

这说明 `codex` harness 已经进入运行时插件注册表。

8. 根因总结

这次故障的根因是运行时依赖缺失。

OpenClaw 配置中已经指定：

{  "agentRuntime": {    "id": "codex"  }}

但本机没有安装对应插件：

@openclaw/codex

于是 Gateway 在执行 agent turn 时找不到 `codex` harness，最终报错：

Requested agent harness "codex" is not registered.

安装并启用 `@openclaw/codex` 后，问题解决。

9. 排查经验

遇到类似错误：

Requested agent harness "" is not registered

可以按这个顺序排查：

openclaw config validateopenclaw agents listopenclaw models statusopenclaw plugins listopenclaw plugins inspectopenclaw logs --limit 200 --plain

重点看三件事：

1. agent 配置里是否指定了 `agentRuntime.id`

2. 对应插件是否安装并启用

3. Gateway 是否已经重启并加载插件

这次的核心判断是：

> model 配置决定“要用谁跑”，plugin 注册表决定“谁真的存在”。

`openai/gpt-5.5` 本身没有问题，真正缺的是让它以 Codex app-server harness 方式运行的 `codex` 插件。

结语

这类问题容易被误判成模型、账号、OAuth 或网络问题，但日志里的 `harness is not registered` 其实指向的是运行时注册表。

一句话总结：

> 配置选择了 Codex，运行时却没有 Codex。安装 `@openclaw/codex`，启用插件，重启 Gateway，问题解决。