概述
Codex Harness 是 OpenClaw 内置的 codex 插件，让 OpenClaw 通过 Codex app-server 运行嵌入式 OpenAI Agent 轮次，而非使用内置的 PI harness。OpenClaw 仍然负责 chat channel、会话文件、模型选择、动态工具、审批、媒体投递和可见转录镜像；Codex 负责原生线程恢复、原生工具续接、原生压缩和 app-server 执行。
核心功能
- 原生 Codex 运行时：通过
openai/gpt-*模型 ref 将 OpenAI Agent 轮次路由到 Codex app-server - 双传输模式：默认 stdio 本地启动托管 Codex 二进制；WebSocket 模式连接已运行的远程 app-server
- Fail-closed 路由：设置
agentRuntime.id: "codex"可在 Codex 不可用时直接失败而非回退到 PI - Guardian 模式：
appServer.mode: "guardian"启用 Codex 原生自动审查，适合沙箱逃逸前的审批 - 动态工具搜索：OpenClaw 动态工具默认以
searchable方式加载，保持初始上下文较小 - 诊断命令：
/codex status、/codex models、/codex threads、/codex diagnostics等
配置/使用
最小配置：
{
plugins: { entries: { codex: { enabled: true } } },
agents: { defaults: { model: "openai/gpt-5.5" } }
}关键配置项：
| 需求 | 配置 |
|---|---|
| 启用 harness | plugins.entries.codex.enabled: true |
| Fail-closed | provider/model agentRuntime.id: "codex" |
| WebSocket 传输 | appServer.transport: "websocket" + url + authToken |
| Guardian 模式 | appServer.mode: "guardian" |
| 环境隔离 | appServer.clearEnv: [...] |
认证顺序：
- OpenClaw 配置的 Codex auth profile（
auth.order.openai） - app-server 已有账号（agent 的 Codex home）
- 仅 stdio 本地启动时：
CODEX_API_KEY→OPENAI_API_KEY
相关页面
- concepts/plugin-codex-harness-reference — 完整配置字段参考
- concepts/plugin-codex-harness-runtime — 运行时边界、钩子层、权限处理
- concepts/plugin-codex-native-plugins — 原生 Codex 插件支持
- concepts/plugin-codex-computer-use — Codex Computer Use 桌面控制
- agent-runtimes — 运行时类型总览（PI/Codex/CLI）