Hook 边界
围绕 Codex 轮次的三个钩子层,以及每一层负责的事件。属于 Codex harness runtime 指南的一部分;每个章节移动到了哪里 列出了所有章节。
钩子边界¶
对于普通持久会话,包含
systemPrompt 的 before_prompt_build 结果会替换完整的 OpenClaw 通用开发者策略。显式
空字符串会撤回该策略。未变更且已证明配置的温热线程保持温热,保留的订阅和主机权限在插件
策略等待之后重新检查。已关闭或已归档的线程不能仅因为其连接仍然打开而被重用。冷恢复和策略变更恢复保留原生线程和
历史,验证 Codex 已卸载先前的配置,然后在允许该轮次之前追加一条完整的取代策略消息。历史策略
文本可以保留在转录中;后续策略明确取代它。
普通会话在本地 stdio、WebSocket、Unix-socket 和 stdio-proxy 连接上使用相同的取消订阅并恢复流程。原生会话 ID 和历史保持不变。OpenClaw 会验证原始 app-server 客户端仍然有效、线程没有活动轮次,并且 Codex 在安装当前策略之前已卸载先前的配置。
此刷新要求 OpenClaw 是原生会话的唯一生命周期所有者。当没有独立客户端能在交接期间重新加载同一会话时,由 Gateway 拥有的远程 app-server 满足此部署契约。连接检查和卸载检查不会在独立客户端之间提供原子交接:竞争的恢复可能会重新安装旧的原生配置。具有竞争会话所有者的共享 app-server 不在此刷新契约范围内。
如果订阅者或失败的原生卸载阻止了配置证明,该轮次会在推理之前停止。预写所有权拒绝会保持健康的共享客户端及其其他会话可用。策略拒绝以及不确定或已确认的策略写入失败会保留会话,并停止自动 auth-profile、model-fallback 和整轮重试。
受监督的外部连接保留其现有的共享连接租约语义;现有的 native-home 和 tool-catalog 限制仍然适用。这些租约检查不会建立对外部原生进程的独占所有权;加强该保证是一项独立限制,不属于普通策略刷新的一部分。手动普通采用仍然需要其 agent-home 和 tool-catalog 检查,以及原生进程证明。
普通隐身会话保留其活动的临时历史。标准 Codex 无法更新其通用会话配置或从磁盘恢复它们,因此变更或显式清空的通用策略会在推理之前停止下一轮次。恢复先前的策略以继续会话,或为新的策略启动一个新的隐身会话。策略未变更的轮次继续;此检查不会为隐身历史添加空闲过期或持久化。
预检拒绝保持正常的外部聊天诊断隐私和群组静默策略。详细模式可以显示有界的恢复细节;Control UI 保留其常规诊断渲染。外部关闭的临时线程不能被承诺可恢复。
| 层 | 所有者 | 目的 |
|---|---|---|
| OpenClaw 插件钩子 | OpenClaw | 跨 OpenClaw 和 Codex harness 的产品/插件兼容性。 |
| Codex app-server 扩展中间件 | OpenClaw 捆绑插件 | 围绕 OpenClaw 动态工具的每轮适配器行为。 |
| Codex 原生钩子 | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 |
OpenClaw 不使用项目或全局 Codex hooks.json 文件来路由插件行为。对于原生工具和权限桥接,OpenClaw 会为每个线程注入 Codex 配置,用于 PreToolUse、PostToolUse、PermissionRequest 和 Stop。
在启动或恢复线程之前,OpenClaw 会准备原生 relay 的已存储 MCP 审批快照和直接发布尝试,然后重新检查当前运行的权限。对于本地 app-server,如果监听器或 SQLite 定位器不可用,钩子命令可以使用现有的 Gateway 回退。策略准备仍必须成功;Gateway 调用独立于发布而等待该快照。注册返回一个同步句柄,其可选 deferMcpToolApprovals 字段在策略准备完成之前保持未定义。
冷钩子 CLI 读取定位器,而不加载共享状态写入器启动。在 Node 上,此一次性进程使用只读连接,没有 SQLite 锁等待;瞬态锁竞争会让位于现有的重试和截止时间所有者。在 Bun 上,它使用专用的只读 worker,并在使用结果之前 join 该 worker,以便释放原生数据库句柄。两条路径都保留模式准入,并在查找后关闭数据库。
桥接发布、续期、查找和移除在共享状态 worker 中运行。发布和续期在其写事务内重新检查当前主机注册,清理在关闭监听器之前 join 已接受的工作。
没有监听直接桥接的 relay 仍然可以续期其逻辑过期时间;监听桥接在延长可见过期时间之前更新其存储的定位器。注销会立即使前台访问失效。清理会排空已接受定位器写入,并在 relay 退役后关闭监听器。现有针对迟到钩子和成功 yield 后保留的直接子进程的宽限窗口保持不变;排空待处理存储工作不会关闭这些子进程。
远程原生钩子回调¶
专用 Codex 应用服务器无法读取 Gateway 的 SQLite 定位器,也无法访问其回环监听器。请使用 url 和 credentialDirectory 设置 plugins.entries.codex.config.appServer.nativeHookRelay,改用受限的 HTTPS 回调。url 是 /__openclaw__/native-hook 的外部路由基础路径;适配器会附加中继 ID。OCE 会为专用 Codex Agents 生成此配置。
部署必须提供一个位于模型工作区和文件传输根目录之外的私有目录,并为钩子进程提供受信任的 CA 证书。在开始一轮对话之前,适配器通过经过身份验证的 Codex app-server 文件系统 API 写入一份凭据。钩子命令仅包含该文件的路径。回调接受当前中继令牌和精确的代次,然后应用与本地桥接器相同的事件策略和实时所有者检查。它不授予任何 Gateway 操作员访问权限。无效的显式远程配置或投递失败会停止本轮对话;回调绝不会回退到操作员 RPC 或本地 SQLite。
凭据路径在中继代次内保持稳定,因此 warm 和 incognito 线程可以复用其钩子命令。每次注册都会写入一个新令牌;有序写入和受所有者检查的清理可防止旧任务删除其替代者的凭据。保留的原生子进程可以在其现有中继生命周期结束前使用该凭据;销毁操作会移除该文件。 替换操作和 Gateway 重启会使旧令牌失效,即使远程文件无法删除也是如此。该目录并不是针对以同一 OS 用户身份运行的被入侵 Harness 代码的安全边界:仍然需要回调的受限权限。TLS 验证保持启用,并拒绝重定向。
当 Codex app-server 审批已启用(approvalPolicy 不是 "never")时,默认注入的原生钩子配置会省略 PermissionRequest,以便 Codex 的 app-server 审查者和 OpenClaw 的审批桥接器在审查后处理真正的升级。将 permission_request 添加到 nativeHookRelay.events 中,以强制使用兼容性中继。其他 Codex 钩子(如 SessionStart 和 UserPromptSubmit)仍然是 Codex 级别的控制项;它们不会在 v1 合约中作为 OpenClaw 插件钩子暴露。
对于 OpenClaw 动态工具,OpenClaw 会在 Codex 请求调用后执行该工具,因此插件和中间件行为在 harness 适配器中运行。Codex Code Mode 会将通用动态结果作为文本接收,并序列化嵌套的动态调用;调用方必须解析看似 JSON 的结果,并且不能依赖 Promise.all 进行并发提交。对于 Codex 原生工具,Codex 拥有规范的工具记录;OpenClaw 可以镜像选定的事件,但无法重写原生线程,除非 Codex 通过 app-server 或原生钩子回调暴露该能力。
Codex app-server 的报告模式 PreToolUse 事件会将插件审批延迟到匹配的 app-server 审批。如果 OpenClaw 的 before_tool_call 钩子返回 requireApproval,而原生载荷设置了 openclaw_approval_mode: "report",原生钩子中继会记录插件审批要求,并且不返回原生决策。当 Codex 稍后为同一工具调用发送 app-server 审批请求时,OpenClaw 会打开插件审批提示,并将决策映射回 Codex。Codex 的 PermissionRequest 事件是单独的审批路径,在配置为使用该桥接器时,仍可通过 OpenClaw 审批进行路由。
Codex app-server 的项目通知还为原生工具完成提供异步的 after_tool_call 观察结果,这些结果并未被原生 PostToolUse 中继覆盖。这些观察结果仅用于遥测/兼容性;它们不能阻止、延迟或改变原生工具调用。
压缩(compaction)和 LLM 生命周期投影来自 Codex app-server 通知和 OpenClaw 适配器状态,而不是原生 Codex 钩子命令。before_compaction、after_compaction、llm_input 和 llm_output 是适配器级别的观察结果,并非 Codex 内部请求或压缩载荷的逐字节捕获。
Codex 原生 hook/started 和 hook/completed app-server 通知会被投影为 codex_app_server.hook 代理事件,用于轨迹跟踪和调试。它们不会调用 OpenClaw 插件钩子。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw