codex 插件让 OpenClaw 能通过 Codex app-server 运行嵌入式 OpenAI 代理轮次,
而不是使用内置的 OpenClaw harness。
当你希望由 Codex 接管底层代理会话时,请使用 Codex harness:原生线程恢复、原生工具续接、原生压缩,以及 app-server 执行。OpenClaw 仍然负责聊天通道、会话文件、模型选择、OpenClaw 动态工具、审批、媒体传递,以及可见的转录镜像。
常规设置使用规范的 OpenAI 模型引用,例如 openai/gpt-5.5。
不要配置旧版 Codex GPT 引用。将 OpenAI 代理认证顺序放在
auth.order.openai 下;旧的 legacy Codex 认证配置文件 id 和
legacy Codex 认证顺序条目属于遗留状态,会由
openclaw doctor --fix 修复。
当没有 OpenClaw 沙箱处于活动状态时,OpenClaw 会在启用 Codex 原生代码模式的情况下启动 Codex app-server 线程,同时默认保持仅代码模式关闭。这样可以让 Codex 原生工作区和代码能力可用,而 OpenClaw 动态工具则继续通过 app-server 的 item/tool/call 桥接运行。活动中的 OpenClaw 沙箱和受限工具策略会完全禁用原生代码模式,除非你选择实验性的 sandbox exec-server 路径。
此 Codex 原生功能与
OpenClaw 代码模式 是分开的,后者是一个可选的 QuickJS-WASI
运行时,用于通用 OpenClaw 运行,并具有不同的 exec 输入形状。
关于更广泛的模型/提供方/运行时拆分,请先阅读
代理运行时。简而言之:
openai/gpt-5.5 是模型引用,codex 是运行时,而 Telegram、Discord、Slack 或其他通道仍然是通信界面。
需求
- 支持捆绑
codex插件的 OpenClaw。 - 如果你的配置使用
plugins.allow,请包含codex。 - Codex app-server
0.125.0或更新版本。捆绑插件默认会管理一个兼容的 Codex app-server 二进制文件,因此PATH上本地的codex命令不会 影响正常的 harness 启动。 - 可通过
openclaw models auth login --provider openai使用的 Codex 认证, 或代理的 Codex home 中的 app-server 账户,或显式的 Codex API 密钥 认证配置文件。
快速开始
大多数希望在 OpenClaw 中使用 Codex 的用户都希望走这条路径:使用 ChatGPT/Codex 订阅登录,启用捆绑的codex 插件,并使用规范的 openai/gpt-* 模型引用。
使用 Codex OAuth 登录:
codex 插件并选择一个 OpenAI 代理模型:
plugins.allow,也请在其中添加 codex:
/new 或 /reset,这样下一轮会从当前配置解析 harness。
配置
快速开始配置是最小可用的 Codex harness 配置。在 OpenClaw 配置中设置 Codex harness 选项,并且仅将 CLI 用于 Codex 认证:| 需求 | 设置 | 位置 |
|---|---|---|
| 启用 harness | plugins.entries.codex.enabled: true | OpenClaw config |
| 保持允许列表中的插件安装 | 在 plugins.allow 中包含 codex | OpenClaw config |
| 通过 Codex 路由 OpenAI 代理轮次 | agents.defaults.model 或 agents.list[].model 为 openai/gpt-* | OpenClaw agent config |
| 使用 ChatGPT/Codex OAuth 登录 | openclaw models auth login --provider openai | CLI auth profile |
| 为 Codex 运行添加 API 密钥备用 | 在 auth.order.openai 中将 openai:* API 密钥配置文件放在订阅认证之后 | CLI auth profile + OpenClaw config |
| 当 Codex 不可用时关闭失败 | 提供方或模型 agentRuntime.id: "codex" | OpenClaw model/provider config |
| 使用直接 OpenAI API 流量 | 提供方或模型 agentRuntime.id: "openclaw" 并使用正常的 OpenAI 认证 | OpenClaw model/provider config |
| 调整 app-server 行为 | plugins.entries.codex.config.appServer.* | Codex plugin config |
| 启用原生 Codex 插件应用 | plugins.entries.codex.config.codexPlugins.* | Codex plugin config |
| 启用 Codex Computer Use | plugins.entries.codex.config.computerUse.* | Codex plugin config |
openai/gpt-* 模型引用。优先使用
auth.order.openai 进行“订阅优先/API 密钥备用”排序。现有的
legacy Codex 认证配置文件 id 和 legacy Codex 认证顺序都属于仅供 doctor 处理的
遗留状态;不要写入新的 legacy Codex GPT 引用。
不要在由 Codex 支持的代理上设置 compaction.model 或 compaction.provider。Codex 通过其原生 app-server 线程状态执行压缩,因此 OpenClaw 在运行时会忽略这些本地摘要器覆盖,并且当该代理使用 Codex 时,openclaw doctor --fix 会将它们移除。
Lossless 仍然支持作为 Codex 轮次周围的组装、摄取和维护的上下文引擎。请通过
plugins.slots.contextEngine: "lossless-claw" 和
plugins.entries.lossless-claw.config.summaryModel 进行配置,而不是通过
agents.defaults.compaction.provider。当 Codex 是活动运行时的时候,openclaw doctor --fix 会将旧的
compaction.provider: "lossless-claw" 结构迁移到 Lossless 上下文引擎插槽中,但原生 Codex 仍然拥有压缩控制权。
原生 Codex app-server harness 支持需要预提示组装的上下文引擎。通用 CLI 后端,包括 codex-cli,不提供该主机能力。
对于由 Codex 支持的代理,/compact 会在绑定线程上启动原生 Codex app-server 压缩。OpenClaw 不会等待完成、施加 OpenClaw 超时、重启共享 app-server,或回退到上下文引擎或公共 OpenAI 摘要器。如果原生 Codex 线程绑定缺失或过期,该命令会失败关闭,因此操作员会看到真实的运行时边界,而不是静默切换压缩后端。
openai/gpt-* 代理轮次。API 密钥只是认证备用,而不是切换到 OpenClaw 或
原生 OpenAI Responses 的请求。
本页其余部分涵盖用户必须在其中做出选择的常见变体:部署形态、关闭失败路由、guardian 审批策略、原生 Codex 插件,以及 Computer Use。完整选项列表、默认值、枚举、发现、环境隔离、超时以及 app-server 传输字段,请参见
Codex harness 参考。
验证 Codex 运行时
在你预期使用 Codex 的聊天中使用/status。一个由 Codex 支持的 OpenAI 代理轮次会显示:
/codex status 会报告 app-server 连通性、账户、速率限制、MCP 服务器和技能。/codex models 列出该 harness 和账户的实时 Codex app-server 目录。如果 /status 的结果出乎意料,请参见
故障排除。
路由和模型选择
将提供方引用和运行时策略分开:- 对通过 Codex 运行的 OpenAI 代理轮次使用
openai/gpt-*。 - 不要在配置中使用旧版 Codex GPT 引用。运行
openclaw doctor --fix来 修复旧引用和过期的会话路由固定值。 agentRuntime.id: "codex"对于正常的 OpenAI 自动模式是可选的,但在部署需要在 Codex 不可用时关闭失败时很有用。agentRuntime.id: "openclaw"会在这是预期行为时,将某个提供方或模型纳入 OpenClaw 嵌入式运行时。/codex ...从聊天中控制原生 Codex app-server 对话。- ACP/acpx 是一个单独的外部 harness 路径。只有当用户明确要求 ACP/acpx 或外部 harness 适配器时才使用它。
| 用户意图 | 使用 |
|---|---|
| 绑定当前聊天 | /codex bind [--cwd <path>] |
| 恢复一个现有的 Codex 线程 | /codex resume <thread-id> |
| 列出或过滤 Codex 线程 | /codex threads [filter] |
| 列出原生 Codex 插件 | /codex plugins list |
| 启用或禁用已配置的原生 Codex 插件 | /codex plugins enable <name>, /codex plugins disable <name> |
| 附加到配对节点上的现有 Codex CLI 会话 | /codex sessions --host <node> [filter], then /codex resume <session-id> --host <node> --bind here |
| 仅发送 Codex 反馈 | /codex diagnostics [note] |
| 启动 ACP/acpx 任务 | ACP/acpx 会话命令,而不是 /codex |
| 使用场景 | 配置 | 验证 | 说明 |
|---|---|---|---|
| 使用 ChatGPT/Codex 订阅与原生 Codex 运行时 | openai/gpt-* 加上已启用的 codex 插件 | /status 显示 Runtime: OpenAI Codex | 推荐路径 |
| 若 Codex 不可用则关闭失败 | 提供方或模型 agentRuntime.id: "codex" | 轮次失败而不是嵌入式回退 | 适用于仅 Codex 部署 |
| 通过 OpenClaw 直接使用 OpenAI API 密钥流量 | 提供方或模型 agentRuntime.id: "openclaw" 并使用正常的 OpenAI 认证 | /status 显示 OpenClaw runtime | 仅在 OpenClaw 是预期行为时使用 |
| 遗留配置 | legacy Codex GPT 引用 | openclaw doctor --fix 会重写它 | 不要以这种方式写入新配置 |
| ACP/acpx Codex 适配器 | ACP sessions_spawn({ runtime: "acp" }) | ACP 任务/会话状态 | 与原生 Codex harness 分离 |
agents.defaults.imageModel 也遵循相同的前缀划分。正常的 OpenAI 路由使用 openai/gpt-*,
只有在图像理解应通过受限的 Codex app-server 轮次运行时才使用 codex/gpt-*。不要使用
旧版 Codex GPT 引用;doctor 会把该旧前缀重写为 openai/gpt-*。
部署模式
基本 Codex 部署
当所有 OpenAI agent 回合都应默认使用 Codex 时,请使用快速开始配置。混合提供商部署
这种结构将 Claude 保持为默认 agent,并添加一个命名的 Codex agent:main agent 使用其正常的提供商路径,而 codex agent 使用 Codex app-server。
失败即关闭的 Codex 部署
对于 OpenAI agent 回合,当捆绑插件可用时,openai/gpt-* 已经会解析为 Codex。若你想要写明一条失败即关闭的规则,请添加显式运行时策略:
App-server 策略
默认情况下,插件会使用 stdio 传输在本地启动 OpenClaw 托管的 Codex 二进制文件。仅当你有意运行其他可执行文件时,才设置appServer.command。只有在 app-server 已在其他地方运行时,才使用 WebSocket 传输:
approvalPolicy: "never"、approvalsReviewer: "user",以及
sandbox: "danger-full-access"。如果本地 Codex 要求不允许这种
隐式 YOLO 姿态,OpenClaw 会改为选择允许的 guardian 权限。
当会话中有 OpenClaw 沙箱处于激活状态时,OpenClaw 会禁用 Codex
原生 Code Mode、用户 MCP 服务器,以及由 app 支持的插件执行,
而不是依赖 Codex 主机侧沙箱。Shell 访问通过
OpenClaw 沙箱支持的动态工具暴露,例如 sandbox_exec 和
sandbox_process,前提是常规 exec/process 工具可用。
当你希望在沙箱逃逸或额外权限之前使用 Codex 原生自动审查时,请使用规范化的 OpenClaw exec 模式:
tools.exec.mode: "auto" 映射为 Codex Guardian 审核通过的授权,通常在本地要求允许这些值时为 approvalPolicy: "on-request"、approvalsReviewer: "auto_review",以及 sandbox: "workspace-write"。在 tools.exec.mode: "auto" 中,OpenClaw 不会保留旧版不安全的 Codex approvalPolicy: "never" 或 sandbox: "danger-full-access" 覆盖;若你想要有意采用无审批的 Codex 姿态,请使用 tools.exec.mode: "full"。旧版 plugins.entries.codex.config.appServer.mode: "guardian" 预设仍然可用,但 tools.exec.mode: "auto" 才是规范化的 OpenClaw 表面。
关于与主机 exec 授权和 ACPX 权限的模式级比较,请参见 权限模式。
关于每个 app-server 字段、认证顺序、环境隔离、发现与超时行为,请参见 Codex harness 参考。
命令与诊断
捆绑插件会将/codex 注册为任何支持 OpenClaw 文本命令的频道上的斜杠命令。
常见形式:
/codex status检查 app-server 连通性、模型、账户、速率限制、 MCP 服务器和技能。/codex models列出实时的 Codex app-server 模型。/codex threads [filter]列出最近的 Codex app-server 线程。/codex resume <thread-id>将当前 OpenClaw 会话附加到一个 现有的 Codex 线程。/codex compact请求 Codex app-server 压缩所附加的线程。/codex review为所附加的线程启动 Codex 原生审查。/codex diagnostics [note]在发送所附加线程的 Codex 反馈前先请求确认。/codex account显示账户和速率限制状态。/codex mcp列出 Codex app-server MCP 服务器状态。/codex skills列出 Codex app-server 技能。
/diagnostics [note]。它会创建一份 Gateway 诊断报告,并且对于 Codex harness 会话,会请求批准发送相关的 Codex 反馈包。关于隐私模型和群聊行为,请参见 Diagnostics export。
仅当你明确希望为当前附加线程上传 Codex 反馈,而不需要完整的 Gateway 诊断包时,才使用 /codex diagnostics [note]。
在本地检查 Codex 线程
检查一次有问题的 Codex 运行,最快的方法通常是直接打开原生 Codex 线程:/diagnostics 回复、/codex binding 或
/codex threads [filter] 中获取线程 id。
有关上传机制和运行时级诊断边界,请参见
Codex harness 运行时。
认证按以下顺序选择:
- 适用于该 agent 的有序 OpenAI 认证配置文件,优先使用
auth.order.openai下的配置。运行openclaw doctor --fix可迁移较旧 的传统 Codex 认证配置文件 id 和传统 Codex 认证顺序。 - 该 agent 的 Codex 主目录中 app-server 现有的账户。
- 对于仅本地 stdio app-server 启动,在没有 app-server 账户且仍需要 OpenAI 认证时,
依次使用
CODEX_API_KEY,然后是OPENAI_API_KEY。
CODEX_API_KEY 和 OPENAI_API_KEY。这可以让 Gateway 级别的 API key 继续可用于 embeddings 或直接的 OpenAI 模型,而不会让原生 Codex app-server turn 意外地按 API 计费。显式的 Codex API key 配置文件以及本地 stdio 环境 key 回退会使用 app-server 登录,而不是继承的子进程环境。WebSocket app-server 连接不会获得 Gateway 环境 API key 回退;请使用显式认证配置文件或远程 app-server 自己的账户。
如果某个订阅配置文件遇到 Codex 使用限制,OpenClaw 会在 Codex 报告时记录重置时间,并为同一次 Codex 运行尝试下一个按顺序排列的认证配置文件。当重置时间过去后,无需更改所选的 openai/gpt-* 模型或 Codex 运行时,该订阅配置文件就会再次具备资格。
对于本地 stdio app-server 启动,OpenClaw 会将 CODEX_HOME 设置为每个 agent 各自的目录,这样 Codex 配置、认证/账户文件、插件缓存/数据以及原生线程状态默认不会读写操作员的个人 ~/.codex。OpenClaw 会保留正常的进程 HOME;Codex 运行的子进程仍可找到用户主目录下的配置和令牌,并且 Codex 可能会发现共享的
$HOME/.agents/skills 和 $HOME/.agents/plugins/marketplace.json 条目。
如果部署需要额外的环境隔离,请将这些变量添加到
appServer.clearEnv:
appServer.clearEnv 只影响被启动的 Codex app-server 子进程。OpenClaw 会在本地启动规范化期间将 CODEX_HOME 和 HOME 从该列表中移除:CODEX_HOME 保持为每个 agent 独立,HOME 保持继承,以便子进程可以使用正常的用户主目录状态。
Codex 动态工具默认使用 searchable 加载。OpenClaw 不会暴露
与 Codex 原生工作区操作重复的动态工具:read、write、
edit、apply_patch、exec、process 和 update_plan。大多数其余的
OpenClaw 集成工具,如消息、媒体、cron、浏览器、节点、
gateway、heartbeat_respond 和 web_search,都可通过 Codex 工具
搜索在 openclaw 命名空间下使用,从而保持初始模型上下文
更小。
sessions_yield 和仅消息工具的源回复仍保持直接返回,因为
它们属于回合控制契约。sessions_spawn 保持可搜索,因此 Codex 的
原生 spawn_agent 仍然是主要的 Codex 子代理入口,而显式的
OpenClaw 或 ACP 委派仍可通过 openclaw 动态工具命名空间使用。Heartbeat 协作说明会告诉 Codex 在结束 heartbeat 回合前,
当该工具尚未加载时先搜索 heartbeat_respond。
仅当连接到一个无法搜索延迟动态工具的自定义 Codex app-server,或在调试完整工具负载时,才将 codexDynamicToolsLoading: "direct" 设为直连。
支持的顶层 Codex 插件字段:
| 字段 | 默认值 | 含义 |
|---|---|---|
codexDynamicToolsLoading | "searchable" | 使用 "direct" 可将 OpenClaw 动态工具直接放入初始 Codex 工具上下文中。 |
codexDynamicToolsExclude | [] | 额外要从 Codex app-server 回合中省略的 OpenClaw 动态工具名称。 |
codexPlugins | disabled | 用于迁移后的源安装精选插件的原生 Codex 插件/app 支持。 |
appServer 字段:
| Field | Default | Meaning |
|---|---|---|
transport | "stdio" | "stdio" spawns Codex; "websocket" connects to url. |
command | managed Codex binary | Executable for stdio transport. Leave unset to use the managed binary; set it only for an explicit override. |
args | ["app-server", "--listen", "stdio://"] | Arguments for stdio transport. |
url | unset | WebSocket app-server URL. |
authToken | unset | Bearer token for WebSocket transport. |
headers | {} | Extra WebSocket headers. |
clearEnv | [] | Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. OpenClaw keeps per-agent CODEX_HOME and inherited HOME for local launches. |
codeModeOnly | false | Opt into Codex’s code-mode-only tool surface. OpenClaw dynamic tools remain registered with Codex so nested tools.* calls return through the app-server item/tool/call bridge. |
requestTimeoutMs | 60000 | Timeout for app-server control-plane calls. |
turnCompletionIdleTimeoutMs | 60000 | Quiet window after Codex accepts a turn or after a turn-scoped app-server request while OpenClaw waits for turn/completed. |
postToolRawAssistantCompletionIdleTimeoutMs | 300000 | Completion-idle and progress guard used after a tool handoff, native tool completion, post-tool raw assistant progress, raw reasoning completion, or reasoning progress while OpenClaw waits for turn/completed. Use this for trusted or heavy workloads where post-tool synthesis can legitimately stay quiet longer than the final assistant release budget. |
mode | "yolo" unless local Codex requirements disallow YOLO | Preset for YOLO or guardian-reviewed execution. Local stdio requirements that omit danger-full-access, never approval, or the user reviewer make the implicit default guardian. |
approvalPolicy | "never" or an allowed guardian approval policy | Native Codex approval policy sent to thread start/resume/turn. Guardian defaults prefer "on-request" when allowed. |
sandbox | "danger-full-access" or an allowed guardian sandbox | Native Codex sandbox mode sent to thread start/resume. Guardian defaults prefer "workspace-write" when allowed, otherwise "read-only". When an OpenClaw sandbox is active, danger-full-access turns use Codex workspace-write with network access derived from the OpenClaw sandbox egress setting. |
approvalsReviewer | "user" or an allowed guardian reviewer | Use "auto_review" to let Codex review native approval prompts when allowed, otherwise guardian_subagent or user. guardian_subagent remains a legacy alias. |
serviceTier | unset | Optional Codex app-server service tier. "priority" enables fast-mode routing, "flex" requests flex processing, null clears the override, and legacy "fast" is accepted as "priority". |
experimental.sandboxExecServer | false | Preview opt-in that registers an OpenClaw sandbox-backed Codex environment with Codex app-server 0.132.0 or newer so native Codex execution can run inside the active OpenClaw sandbox. |
appServer.requestTimeoutMs: Codex item/tool/call requests use a 90 second
OpenClaw watchdog by default. A positive per-call timeoutMs argument extends
or shortens that specific tool budget. The image_generate tool uses
agents.defaults.imageGenerationModel.timeoutMs when the tool call does not
provide its own timeout, or a 120 second image-generation default otherwise.
The media-understanding image tool uses
tools.media.image.timeoutSeconds or its 60 second media default. Dynamic tool
budgets are capped at 600000 ms. On timeout, OpenClaw aborts the tool signal
where supported and returns a failed dynamic-tool response to Codex so the turn
can continue instead of leaving the session in processing.
After Codex accepts a turn, and after OpenClaw responds to a turn-scoped
app-server request, the harness expects Codex to make current-turn progress and
eventually finish the native turn with turn/completed. If the app-server goes
quiet for appServer.turnCompletionIdleTimeoutMs, OpenClaw best-effort
interrupts the Codex turn, records a diagnostic timeout, and releases the
OpenClaw session lane so follow-up chat messages are not queued behind a stale
native turn. Most non-terminal notifications for the same turn disarm that short
watchdog because Codex has proven the turn is still alive. Tool handoffs use a
longer post-tool idle budget: after OpenClaw returns an item/tool/call
response, after native tool items such as commandExecution complete, after raw
custom_tool_call_output completions, and after post-tool raw assistant
progress, raw reasoning completions, or reasoning progress. The guard uses
appServer.postToolRawAssistantCompletionIdleTimeoutMs when configured and
defaults to five minutes otherwise. That same post-tool budget also extends the
progress watchdog for the silent synthesis window before Codex emits the next
current-turn event. Global app-server notifications, such as rate-limit updates,
do not reset turn-idle progress. Reasoning completions, commentary
agentMessage completions, and pre-tool raw reasoning or assistant progress can
be followed by an automatic final reply, so they use the post-progress reply
guard instead of releasing the session lane immediately. Only
final/non-commentary completed agentMessage items and pre-tool raw
assistant completions arm the assistant-output release: if Codex then goes quiet
without turn/completed, OpenClaw best-effort interrupts the native turn and
releases the session lane. Replay-safe stdio app-server failures, including
turn-completion idle timeouts without assistant, tool, active-item, or
side-effect evidence, are retried once on a fresh app-server attempt. Unsafe
timeouts still retire the stuck app-server client and release the OpenClaw
session lane. They also clear the stale native thread binding instead of being
replayed automatically. Completion-watch timeouts surface Codex-specific timeout
text: replay-safe cases say the response may be incomplete, while unsafe cases
tell the user to verify current state before retrying. Public timeout diagnostics
include structural fields such as the last app-server notification method,
raw assistant response item id/type/role, active request/item counts, and armed
watch state. When the last notification is a raw assistant response item, they
also include a bounded assistant text preview. They do not include raw prompt or
tool content.
本地测试仍可使用环境变量覆盖:
OPENCLAW_CODEX_APP_SERVER_BINOPENCLAW_CODEX_APP_SERVER_ARGSOPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardianOPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICYOPENCLAW_CODEX_APP_SERVER_SANDBOX
appServer.command 未设置时,OPENCLAW_CODEX_APP_SERVER_BIN 会绕过托管二进制文件。
OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 已移除。请改用 plugins.entries.codex.config.appServer.mode: "guardian",或在一次性本地测试中使用 OPENCLAW_CODEX_APP_SERVER_MODE=guardian。对于可重复部署,更推荐使用配置,因为它将插件行为与 Codex harness 设置的其余部分放在同一个经过审查的文件中。
原生 Codex 插件
原生 Codex 插件支持使用 Codex app-server 自身的 app 和插件能力,并且与 OpenClaw harness turn 处于同一个 Codex 线程中。OpenClaw 不会将 Codex 插件转换为合成的codex_plugin_* OpenClaw 动态工具。
codexPlugins 仅影响选择原生 Codex harness 的会话。它对内置 harness 运行、普通 OpenAI provider 运行、ACP 对话绑定或其他 harness 没有影响。
迁移后的最小配置:
codexPlugins 后,请使用 /new、/reset 或重启网关,以便后续 Codex harness 会话使用更新后的应用集合启动。
关于迁移资格、app 库存、破坏性操作策略、询问机制和原生插件诊断,请参见
原生 Codex 插件。
OpenAI 侧的 app 和插件访问由登录的 Codex 账户控制;对于 Business 和 Enterprise/Edu 工作区,还受工作区 app 控制的约束。有关 OpenAI 账户和工作区控制的概览,请参见
在你的 ChatGPT 套餐中使用 Codex。
Computer Use
计算机使用在其单独的设置指南中有说明: Codex 计算机使用。 简而言之:OpenClaw 不会提供桌面控制 app,也不会自行执行桌面操作。它会准备 Codex app-server,验证computer-use MCP server 是否可用,然后在 Codex 模式轮次中让 Codex 自主处理原生 MCP 工具调用。
运行时边界
Codex harness 只会改变底层嵌入式 agent 执行器。- 支持 OpenClaw 动态工具。Codex 会请求 OpenClaw 执行这些工具,因此 OpenClaw 仍然处于执行路径中。
- Codex 原生 shell、patch、MCP 和原生 app 工具由 Codex 管理。OpenClaw 可以通过受支持的中继观察或阻止选定的原生事件,但不会重写原生工具参数。
- Codex 管理原生压缩。OpenClaw 会保留一份转录镜像,用于通道历史、搜索、
/new、/reset以及未来的模型或 harness 切换,但不会用 OpenClaw 或上下文引擎的摘要器替代 Codex 压缩。 - 媒体生成、媒体理解、TTS、审批以及消息工具输出仍通过匹配的 OpenClaw provider/model 设置进行。
tool_result_persist适用于 OpenClaw 所管理的转录工具结果,而不适用于 Codex 原生工具结果记录。
故障排查
Codex 没有作为普通的/model provider 出现: 对于新配置来说,这是预期行为。请选择 openai/gpt-* 模型,启用 plugins.entries.codex.enabled,并检查 plugins.allow 是否排除了 codex。
OpenClaw 使用的是内置 harness,而不是 Codex: 请确认模型引用在官方 OpenAI provider 上为 openai/gpt-*,并且 Codex 插件已安装且启用。如果在测试时需要严格证明,请将 provider 或 model 的 agentRuntime.id 设置为 "codex"。强制使用 Codex runtime 时如果失败,会直接报错,而不会回退到 OpenClaw。
OpenAI Codex runtime 回退到 API key 路径: 收集一段已脱敏的网关摘录,显示模型、runtime、所选 provider 和失败信息。请受影响的协作者在其 OpenClaw 主机上运行以下只读命令:
openai/gpt-5.5 或 openai/gpt-5.4、Runtime: OpenAI Codex、agentRuntime.id 或 harnessRuntime、candidateProvider: "openai",以及 401、Incorrect API key 或 No API key 的结果。修正后的运行应显示 OpenAI OAuth 路径,而不是普通的 OpenAI API key 失败。
旧版 Codex 模型引用配置仍然存在: 运行 openclaw doctor --fix。Doctor 会将旧版模型引用重写为 openai/*,移除过期的会话和整 agent runtime 固定配置,并保留现有的 auth-profile 覆盖。
app-server 被拒绝: 请使用 Codex app-server 0.125.0 或更高版本。同版本的预发布版本或带构建后缀的版本,例如 0.125.0-alpha.2 或 0.125.0+custom,都会被拒绝,因为 OpenClaw 会测试稳定的 0.125.0 协议下限。
/codex status 无法连接: 检查内置的 codex 插件是否已启用;如果配置了 allowlist,请确认 plugins.allow 包含它;并检查任何自定义的 appServer.command、url、authToken 或 headers 是否有效。
模型发现很慢: 降低 plugins.entries.codex.config.discovery.timeoutMs,或禁用 discovery。请参见
Codex harness 参考。
WebSocket 传输立即失败: 检查 appServer.url、authToken、headers,以及远程 app-server 是否支持相同的 Codex app-server 协议版本。
原生 shell 或 patch 工具被 Native hook relay unavailable 阻止:
Codex 线程仍在尝试使用一个 OpenClaw 不再注册的原生 hook relay id。这是一个原生 Codex hook 传输问题,不是 ACP 后端、provider、GitHub 或 shell 命令故障。在受影响的聊天中使用 /new 或 /reset 开启新会话,然后重试一个无害命令。如果这一次可行,但下一次原生工具调用又失败,那么应将 /new 视为临时解决方案:在重启 Codex app-server 或 OpenClaw Gateway 后,将提示复制到新会话中,以便旧线程被丢弃并重新创建原生 hook 注册。
非 Codex 模型使用的是内置 harness: 除非 provider 或 model runtime policy 将其路由到其他 harness,否则这是预期行为。普通的非 OpenAI provider 引用在 auto 模式下会保持其正常的 provider 路径。
Computer Use 已安装但工具不运行: 在新会话中检查 /codex computer-use status。如果工具报告 Native hook relay unavailable,请使用上面的原生 hook relay 恢复方法。请参见
Codex Computer Use。