OpenClaw Codex 引擎插件深度研究

> 来源: https://docs.openclaw.ai/plugins/codex-harness

> 日期: 2026-05-03

> 分类: OpenClaw / 插件 / Agent Runtime

> 报告人: Researcher Agent

一句话版本

OpenClaw 的 Codex 引擎插件让你能用 ChatGPT/Codex 订阅账号作为 AI 的执行引擎，而不是用默认的 OpenClaw PI 运行时。简单说就是：模型还是用 openai/gpt-5.5，但背后跑的是 Codex 的原生 app-server，而不是 OpenClaw 自己的 runner。聊天频道（Telegram/Discord/Slack）不动，OpenClaw 继续管工具调用、权限审批和消息路由。

1. 核心概念

什么是 Codex 引擎（Harness）？

OpenClaw 有多个 "agent runtime"（AI 执行引擎）：

• PI（默认）：OpenClaw 自己的内置 runner，直接调用模型 API
• Codex（本插件）：把执行交给 Codex 原生 app-server
• ACP：通过 Agent Client Protocol 调用外部工具（Codex CLI、Claude Code 等）

关键区分：codex 插件 ≠ Codex CLI。前者是 OpenClaw 内部把 AI 推理交给原生 Codex app-server 执行（跑在后台的 stdio 进程）；后者是独立的终端工具。

谁拥有什么？

2. 快速配置（三分钟上手）

前提条件

# 1. 先登录 Codex OAuth（需要有效的 ChatGPT/Codex 订阅）
openclaw models auth login --provider openai-codex

# 2. 新版需要 Codex app-server >= 0.125.0（插件自带兼容版本）

基础配置

在 openclaw.json5 中：

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

环境变量方式：

OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run

3. 路由路线图（非常重要！）

这是最容易混淆的部分。OpenAI 系列有几个不同的前缀，含义完全不同：

记住核心区分：

• openai/* = 模型标识（哪个模型）
• agentRuntime.id: "codex" = 运行时选择（谁执行）
• openai-codex/* = 认证路径（Codex OAuth 通过 PI 执行）
• /codex ... = 聊天控制命令（绑定/恢复 Codex 线程）
• ACP = 外部进程执行

4. 插件能力清单

这个 codex 插件不只是一个运行时切换，它贡献了 5 个独立能力：

插件不做什么

• 不会自动把所有 OpenAI 模型切到 Codex
• 不会把 openai-codex/* 变成原生运行时
• 不会让 ACP 成为默认的 Codex 路径
• 不会热切换已有会话的运行时
• 不会替换 OpenClaw 的频道投递、会话文件、认证存储等功能

5. 详细配置选项

模型发现

插件默认询问 app-server 可用模型，超时或失败时用内置目录：

• GPT-5.5
• GPT-5.4 mini
• GPT-5.2

可配置发现参数或完全禁用：

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
        },
      },
    },
  },
}

App-server 连接方式

WebSocket 配置示例：

{
  appServer: {
    transport: "websocket",
    url: "ws://127.0.0.1:39175",
    authToken: "${CODEX_APP_SERVER_TOKEN}",
    requestTimeoutMs: 60000,
  },
}

安全策略

YOLO 模式（默认）：approvalPolicy: "never"，sandbox: "danger-full-access"

• 适合无人值守的 heartbeat 任务
• Codex 可以完全使用 shell 和网络工具

Guardian 模式：

{
  appServer: {
    mode: "guardian",
    serviceTier: "fast",
  },
}

• 展开为：approvalPolicy: "on-request" + approvalsReviewer: "auto_review" + sandbox: "workspace-write"
• Codex 的自动审批系统审查风险请求
• 适合需要更多护栏但仍需无人值守的场景

6. 多 Agent 配置（Codex + 其他模型共存）

不要把 agentRuntime.id: "codex" 设为全局默认，否则选 Anthropic 模型也会强制走 Codex（然后失败）。

推荐方案：建一个单独的 Codex agent：

{
  agents: {
    defaults: {
      agentRuntime: { id: "auto" },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: { id: "codex" },
      },
    ],
  },
}

这样 main agent 走正常的 provider + PI 路径，codex agent 走 Codex 原生运行时。如果 Codex 不可用，codex agent 的 turn 会失败而不是静默回退到 PI。

7. Agent 命令路由

用户意图 → 正确的工具路径：

8. 工作区引导文件

Codex 原生支持 AGENTS.md。对于 OpenClaw 的其他引导文件（SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md），Codex 插件会在 thread/start 和 thread/resume 时把它们作为 Codex config instructions 转发过去。这样你的 persona 配置在 Codex 运行时也是可见的。

9. 与 Jay 项目的关联

Jay 已经在运行 OpenClaw，且使用了 researcher agent 和多种 ACP 工具（Codex ACP、Claude Code ACP）。

当前状态： Jay 的 OpenClaw 使用默认模型 deepseek/deepseek-v4-flash（从 Runtime 信息可见），runtime 走 PI（OpenClaw Pi Default），没有启用 Codex 引擎。

可能的用法：

1. GPT-5.5 原生运行时：如果你有 ChatGPT Plus/Pro 订阅，可以配置一个 codex agent 专门跑 OpenAI 最新模型，利用 Codex 的原生线程管理和压缩能力

2. YOLO 模式适合 heartbeat：如果你有一些定时任务需要 Agent 自动执行（如健康检查、知识库维护），Codex 的 YOLO 模式适合无人值守

3. 与现有 ACP 系统互补：ACP 调用外部工具（Claude Code、Codex CLI），Codex 引擎是内部把推理交给原生 Codex 执行——二者定位不同，可以并存

如果不订阅 ChatGPT/Codex： 这个插件对你基本没用。它要求有效的 ChatGPT/Codex 订阅才能通过 Codex OAuth 认证。直接用 openai/* + API Key 走 PI 在功能上已经覆盖了大部分场景。

10. 评分

参考资料

• Codex Harness 官方文档
• Agent Runtimes 概念
• ACP 配置指南 - Nemo Feng
• OpenClaw GitHub