Appearance
在 OpenClaw 的 Codex 模式下，原生模型循环、工具执行、会话管理和诊断都有明确的职责边界：OpenClaw 负责渠道路由、会话文件、动态工具、媒体投递和 transcript 镜像，Codex 负责原生线程、模型 loop、原生工具 continuation 和 compaction。visible replies 默认需要 message(action="send")，可通过设置 messages.visibleReplies: "automatic" 恢复自动发送。Hook 分为 OpenClaw 插件钩子、Codex app-server 扩展中间件和 Codex 原生钩子三层；原生钩子中 PermissionRequest 在 app-server 启用审批时默认跳过。Compaction 由 Codex app-server 管理，除非当前 context engine 声明 ownsCompaction: true。反馈上传使用 /diagnostics [note] 或 /codex diagnostics [note]。v1 不支持原生工具参数改写、不可编辑 Codex 原生 transcript 历史。
OpenClaw Codex 运行时配置与排查指南
本页说明 Codex harness turn 的运行时约定。安装和路由配置请先阅读 Codex harness，配置字段请参考 Codex harness reference。
概述
Codex 模式并非简单地用不同模型调用替换 PI（Personal Intelligence）。Codex 掌管更多原生模型循环，OpenClaw 则围绕这一边界调整其插件、工具、会话和诊断界面。
OpenClaw 仍负责：渠道路由、会话文件、可见消息投递、OpenClaw 动态工具、审批、媒体投递和 transcript 镜像。 Codex 负责：规范原生线程、原生模型循环、原生工具 continuation 以及原生 compaction（除非当前启用的 OpenClaw 上下文引擎声明自己拥有 compaction）。
提示（Prompt）路由遵循所选的运行时，而非仅依赖 provider 字符串。原生 Codex turn 会收到 Codex app-server 开发者指令；而显式的 PI 兼容性路由即使使用了 Codex 风格的 OpenAI 认证或传输，仍保留正常的 OpenClaw/PI 系统提示。
原生 Codex 会根据当前 Codex 线程配置保留 Codex 拥有的 base/model/personality 指令和项目文档行为。轻量级 OpenClaw 运行仍然保留已有的项目文档抑制。OpenClaw 开发者指令涵盖了 OpenClaw 运行时关注点，例如源渠道投递、OpenClaw 动态工具、ACP 代理、适配器上下文以及当前智能体工作区配置文件。OpenClaw 技能目录、MEMORY.md 和当前 BOOTSTRAP.md 的内容会作为 turn 输入参考上下文投影到原生 Codex 中。
线程绑定与模型变更
当 OpenClaw 会话附加到现有的 Codex 线程时，下一个 turn 会将当前选中的 OpenAI 模型、审批策略、沙箱和服务等级重新发送到 app-server。从 openai/gpt-5.5 切换到 openai/gpt-5.2 会保持线程绑定，但要求 Codex 使用新选模型继续。
可见回复与心跳
当 direct/source chat turn 通过 Codex harness 运行时，可见回复默认使用 message 工具：最终助手文本保持私有，除非智能体调用 message(action="send")。这对 GPT 模型很合适，因为模型可以决定是否需要输出到源渠道。设置 messages.visibleReplies: "automatic" 可恢复旧模式——最终助手文本自动发送。
Codex 心跳 turn 默认也会在可搜索的 OpenClaw 工具目录中包含 heartbeat_respond，因此智能体可以记录唤醒应该保持安静还是发送通知，而无需在最终文本中编码控制流。
心跳专用的引导指令在心跳 turn 本身作为 Codex 协作模式开发者指令发送。普通聊天 turn 会恢复为 Codex Default 模式，不会在心运行时提示中携带心跳哲学。当存在非空的 HEARTBEAT.md 时，心跳协作模式指令会指向该文件，而非内联其内容。
钩子边界
Codex harness 包含三层钩子：
| 层级 | 所有者 | 目的 |
|---|---|---|
| OpenClaw 插件钩子 | OpenClaw | 跨 PI 和 Codex harness 的产品/插件兼容性。 |
| Codex app-server 扩展中间件 | OpenClaw 捆绑插件 | 围绕 OpenClaw 动态工具的逐 turn 适配器行为。 |
| Codex 原生钩子 | Codex | 来自 Codex 配置的低级 Codex 生命周期和原生工具策略。 |
OpenClaw 不使用项目或全局 Codex hooks.json 文件来路由 OpenClaw 插件行为。对于受支持的原生工具和权限桥，OpenClaw 会向每个 Codex 线程注入用于 PreToolUse、PostToolUse、PermissionRequest 和 Stop 的配置。
当 Codex app-server 审批启用时（即 approvalPolicy 并非 "never"），默认注入的原生钩子配置会省略 PermissionRequest，以使 Codex 的 app-server 审核者和 OpenClaw 的审批桥在处理实际升级时先经过审核。当需要兼容中继时，操作者可以显式将 permission_request 添加到 nativeHookRelay.events。
其他 Codex 钩子（如 SessionStart 和 UserPromptSubmit）仍属于 Codex 级别的控制，在 v1 合约中不作为 OpenClaw 插件钩子暴露。
对于 OpenClaw 动态工具，OpenClaw 在 Codex 请求调用后执行该工具，因此 OpenClaw 会在 harness 适配器中触发其拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范的工具记录。OpenClaw 可以镜像选定事件，但无法重写原生 Codex 线程，除非 Codex 通过 app-server 或原生钩子回调暴露该操作。
Codex app-server 项目通知也提供异步的 after_tool_call 观察，用于原生工具完成情况（不在原生 PostToolUse 中继中的部分）。这些观察仅用于遥测和插件兼容性，不能阻塞、延迟或修改原生工具调用。
Compaction 和 LLM 生命周期投影来自 Codex app-server 通知和 OpenClaw 适配器状态，而非原生 Codex 钩子命令。OpenClaw 的 before_compaction、after_compaction、llm_input 和 llm_output 事件是适配器级别的观察，并非对 Codex 内部请求或 compaction 负载的逐字节捕获。
Codex 原生 hook/started 和 hook/completed app-server 通知会投影为 codex_app_server.hook 智能体事件用于轨迹和调试，不会调用 OpenClaw 插件钩子。
V1 支持合同
Codex 运行时 v1 中支持的功能：
| 表面 | 支持情况 | 原因 |
|---|---|---|
| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex app-server 拥有 OpenAI turn、原生线程恢复和原生工具 continuation。 |
| OpenClaw 渠道路由和投递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 等渠道位于模型运行时之外。 |
| OpenClaw 动态工具 | 支持 | Codex 要求 OpenClaw 执行这些工具，因此 OpenClaw 仍在执行路径中。 |
| 提示和上下文插件 | 支持 | OpenClaw 将 OpenClaw 特定的提示/上下文投影到 Codex turn 中，同时将 Codex 拥有的 base、model、personality 和已配置的项目文档提示保留在原生 Codex lane 中。原生 Codex 开发者指令仅接受显式限定于 codex_app_server 的命令指导；遗留的全局命令提示保留给非 Codex 提示表面。 |
| 上下文引擎生命周期 | 支持 | 为 Codex turn 运行 assemble、ingest、turn 后维护和上下文引擎 compaction 协调。 |
| 动态工具钩子 | 支持 | before_tool_call、after_tool_call 和工具结果中间件在 OpenClaw 拥有的动态工具周围运行。 |
| 生命周期钩子 | 支持（作为适配器观察） | llm_input、llm_output、agent_end、before_compaction、after_compaction 会以真实的 Codex 模式负载触发。 |
| 最终答案修订门 | 通过原生钩子中继支持 | Codex Stop 被中继到 before_agent_finalize；revise 要求 Codex 在最终化前再做一次模型 pass。 |
| 原生 shell、patch 和 MCP 阻塞或观察 | 通过原生钩子中继支持 | Codex PreToolUse 和 PostToolUse 被中继用于已承诺的原生工具表面，包括 Codex app-server 0.125.0 或更新版本上的 MCP 负载。支持阻塞，不支持参数重写。 |
| 原生权限策略 | 通过 Codex app-server 审批和兼容原生钩子中继支持 | Codex app-server 审批请求在 Codex 审核后路由到 OpenClaw。PermissionRequest 原生钩子中继在原生审批模式下是 opt-in 的，因为 Codex 会在守护者审核之前触发它。 |
| App-server 轨迹捕获 | 支持 | OpenClaw 记录发送给 app-server 的请求以及接收到的 app-server 通知。 |
Codex 运行时 v1 中不支持的功能：
| 表面 | V1 边界 | 未来路径 |
|---|---|---|
| 原生工具参数修改 | Codex 原生前工具钩子可以阻塞，但 OpenClaw 不重写 Codex 原生工具参数。 | 需要 Codex 钩子/架构支持替换工具输入。 |
| 可编辑的 Codex 原生 transcript 历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有镜像，可以投影未来上下文，但不应当修改不支持的内部结构。 | 如果原生的线程手术是必需的，需添加明确的 Codex app-server API。 |
用于 Codex 原生工具结果的 tool_result_persist | 该钩子转换 OpenClaw 拥有的 transcript 写入，而非 Codex 原生工具记录。 | 可镜像转换后的记录，但规范重写需要 Codex 支持。 |
| 丰富的原生 compaction 元数据 | OpenClaw 观察到 compaction 开始和完成，但不接收稳定的 kept/dropped 列表、token 变化或摘要负载。 | 需要更丰富的 Codex compaction 事件。 |
| Compaction 干预 | 当前 OpenClaw compaction 钩子在 Codex 模式下是通知级别的。 | 如果插件需要否决或重写原生 compaction，添加 Codex 前后 compaction 钩子。 |
| 逐字节的模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但 Codex 核心内部构造最终的 OpenAI API 请求。 | 需要 Codex 的模型请求追踪事件或调试 API。 |
原生权限和 MCP 诱导
对于 PermissionRequest，OpenClaw 仅在策略决定时返回明确的允许或拒绝决策。无决策结果不视为允许。Codex 将其视为无钩子决策，并回退到自身的守护者或用户审批路径。
Codex app-server 审批模式默认省略此原生钩子。当 permission_request 被显式包含在 nativeHookRelay.events 中，或由兼容性运行时安装时，此行为生效。
当操作者为 Codex 原生权限请求选择 allow-always 时，OpenClaw 会在有界的会话窗口中记住该确切的 provider/session/tool input/cwd 指纹。记住的决策是精确匹配的：更改的命令、参数、工具负载或 cwd 都会产生新的审批。
当 Codex 标记 _meta.codex_approval_kind 为 "mcp_tool_call" 时，Codex MCP 工具审批诱导会通过 OpenClaw 的插件审批流程路由。Codex request_user_input 提示会发送回原始聊天，下一条排队的后续消息会响应那个原生服务器请求，而不是被引导为额外上下文。其他 MCP 诱导请求会失败关闭。
队列转向
活动运行队列转向映射到 Codex app-server turn/steer。使用默认的 messages.queue.mode: "steer" 时，OpenClaw 会批量收集转向模式的聊天消息，等待配置的静默窗口，然后按到达顺序发送一个 turn/steer 请求。
Codex review 和 manual compaction turn 可以拒绝同 turn 转向。此时，OpenClaw 等待活动运行结束后再启动提示。当消息应默认排队而非转向时，使用 /queue followup 或 /queue collect。参见 Steering queue。
Codex 反馈上传
当 /diagnostics [note] 在使用了原生 Codex harness 的会话中获得批准时，OpenClaw 还会对相关的 Codex 线程调用 Codex app-server feedback/upload。上传会要求 app-server 包含每个列出线程及派生的 Codex 子线程的日志（如果可用）。
上传通过 Codex 的正常反馈路径发送到 OpenAI 服务器。如果该 app-server 禁用了 Codex 反馈，该命令会返回 app-server 错误。完成的诊断回复会列出所发送线程的渠道、OpenClaw 会话 ID、Codex 线程 ID 和本地的 codex resume <thread-id> 命令。
如果您拒绝或忽略审批，OpenClaw 不会打印这些 Codex ID，也不会发送 Codex 反馈。该上传不会取代本地 Gateway 诊断导出。审批、隐私、本地包和群聊行为请参见 Diagnostics export。
当您只想要当前附加线程的 Codex 反馈上传，而不需要完整的 Gateway 诊断包时，可使用 /codex diagnostics [note]。
Compaction 和 transcript 镜像
当所选模型使用 Codex harness 时，原生线程 compaction 委派给 Codex app-server，除非当前上下文引擎声明 ownsCompaction: true。拥有 compaction 的上下文引擎会先进行 compaction，并导致 OpenClaw 放弃旧的 Codex 后端线程，以便下一个 turn 能从引擎管理的上下文中重建新线程。OpenClaw 保持一个 transcript 镜像用于渠道历史、搜索、/new、/reset 以及未来的模型或 harness 切换。
当上下文引擎请求 Codex 线程引导投影时，OpenClaw 会将工具调用名称和 ID、输入形状以及已脱敏的工具结果内容投影到新的 Codex 线程中。它不会将原始工具调用参数值复制到投影中。
镜像包含用户提示、最终助手文本以及 app-server 发出时的轻量级 Codex 推理或计划记录。目前，OpenClaw 仅记录原生 compaction 开始和完成信号，尚未暴露人类可读的 compaction 摘要或 Codex 在 compaction 后保留哪些条目的可审计列表。
由于 Codex 拥有规范的原生线程，tool_result_persist 目前不会重写 Codex 原生工具结果记录。它仅在 OpenClaw 写入 OpenClaw 拥有的会话 transcript 工具结果时生效。
媒体和投递
OpenClaw 继续拥有媒体投递和媒体提供者选择。图像、视频、音乐、PDF、TTS 和媒体理解使用匹配的 provider/model 设置，例如 agents.defaults.imageGenerationModel、videoGenerationModel、pdfModel 和 messages.tts。
文本、图像、视频、音乐、TTS、审批和消息工具输出继续通过正常的 OpenClaw 投递路径。媒体生成不需要 PI。当 Codex 发出带有 savedPath 的原生图像生成项时，即使 Codex turn 没有助手文本，OpenClaw 也会将该确切文件通过正常的回复媒体路径转发。
相关
- Codex harness
- Codex harness reference
- Native Codex plugins
- Plugin hooks
- Agent harness plugins
- Diagnostics export
- Trajectory export
常见问题
为什么 Codex 模式下智能体回复不自动发送到聊天中？
在 Codex harness 中，visible replies 默认使用 message 工具——最终助手文本不会自动投递回源渠道，除非智能体调用 message(action="send")。要恢复旧模式，在配置中设置 messages.visibleReplies: "automatic"。
如何启用 Codex 原生钩子中继（如 PermissionRequest）？
原生钩子中继默认只包含 PreToolUse、PostToolUse 和 Stop。要启用 PermissionRequest，请在 nativeHookRelay.events 列表中显式添加 "permission_request"。注意，当 Codex app-server 审批启用（approvalPolicy 不为 "never"）时，此选项默认省略以避免与 app-server 审批冲突。
诊断反馈上传失败，报错 "app-server error" 怎么办？
如果 app-server error 出现在 /diagnostics [note] 或 /codex diagnostics [note] 命令后，说明该 app-server 已禁用 Codex 反馈上传。您仍可使用本地 Gateway 诊断导出（/diagnostics 的基础流程）获取诊断包，且需要审批通过。反馈上传不会影响本地诊断包的生成。