Hook 边界

围绕一个 Codex 轮次的三层钩子，以及每一层负责的事件。属于 Codex harness runtime 指南的一部分；各章节迁移位置 列出了所有章节。

钩子边界¶

对于普通持久会话，包含 systemPrompt 的 before_prompt_build 结果 会替换完整的 OpenClaw 通用开发者策略。显式 空字符串会撤回该策略。未变更且已证明配置的 warm 线程 保持 warm，并在插件策略等待之后重新检查保留的订阅和主机权限。已关闭或已归档的线程不能仅因为其 连接仍然打开而被复用。冷恢复和策略变更恢复会保留原生线程和 历史，验证 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 不使用项目或全局 Codex hooks.json 文件来路由插件行为。对于原生工具和权限桥接，OpenClaw 会为 PreToolUse、PostToolUse、PermissionRequest 和 Stop 注入按线程的 Codex 配置。

在启动或恢复线程之前，OpenClaw 会准备原生 relay 的已存储 MCP 审批快照和直接发布尝试，然后重新检查当前运行的权限。如果 listener 或 SQLite locator 不可用，钩子命令可以使用现有的 Gateway 回退。策略准备仍必须成功；Gateway 调用独立于发布而等待该快照。 注册返回一个同步句柄，其可选 deferMcpToolApprovals 字段在策略准备完成前保持未定义。

冷钩子 CLI 读取 locator，而不加载共享状态写入器启动。 在 Node 上，此一次性进程使用无 SQLite 锁等待的只读连接；瞬态锁竞争会让位于现有的重试和截止时间所有者。 在 Bun 上，它使用专用只读 worker，并在使用结果前 join 该 worker，以便释放原生数据库句柄。两条路径都保留模式准入，并在查找后关闭数据库。

桥接发布、续期、查找和移除在共享状态 worker 中运行。 发布和续期会在其写事务内重新检查当前主机注册，清理会在关闭 listener 前 join 已接受的工作。

没有监听直接桥接的 relay 仍可以续期其逻辑过期时间；监听桥接会在延长可见过期时间前更新其存储的 locator。注销会立即使前台访问失效。 清理会排空已接受的 locator 写入，并在 relay 退役后执行 listener 关闭。成功 yield 后保留的迟到钩子和直接子进程的现有宽限窗口会被保留；排空待处理存储工作不会关闭这些子进程。

当 Codex app-server 审批启用（approvalPolicy 不是 "never"）时，默认注入的原生 hook 配置会省略 PermissionRequest，以便 Codex 的 app-server 审查器和 OpenClaw 的审批桥在审查后处理真实升级。无论如何，将 permission_request 添加到 nativeHookRelay.events 可强制启用兼容性 relay。其他 Codex hook，例如 SessionStart 和 UserPromptSubmit，仍属于 Codex 级别控制；在 v1 契约中，它们不作为 OpenClaw 插件 hook 暴露。

对于 OpenClaw 动态工具，OpenClaw 会在 Codex 请求调用后执行工具，因此插件和中间件行为在 harness adapter 中运行。Codex Code Mode 以文本形式接收通用动态结果，并串行化嵌套动态调用；调用方必须解析看似 JSON 的结果，并且不能依赖 Promise.all 进行并发提交。对于 Codex 原生工具，Codex 拥有规范工具记录；OpenClaw 可以镜像选定事件，但不能重写 原生线程，除非 Codex 通过 app-server 或原生 hook 回调暴露该能力。

Codex app-server report-mode PreToolUse 事件会将插件审批延迟到匹配的 app-server 审批。如果 OpenClaw before_tool_call hook 返回 requireApproval，而原生负载设置 openclaw_approval_mode: "report"，则原生 hook relay 会记录插件审批要求，并且不返回原生决策。当 Codex 稍后为同一工具使用发送 app-server 审批 请求时，OpenClaw 会打开插件审批提示，并将决策映射回 Codex。Codex PermissionRequest 事件是 另一条审批路径，在配置该桥时仍可通过 OpenClaw 审批路由。

Codex app-server item 通知还为尚未被原生 PostToolUse relay 覆盖的原生工具完成提供异步 after_tool_call 观察。它们仅用于遥测/兼容性；不能 阻塞、延迟或修改原生工具调用。

Compaction 和 LLM 生命周期投影来自 Codex app-server 通知和 OpenClaw adapter 状态，而不是原生 Codex hook 命令。 before_compaction、after_compaction、llm_input 和 llm_output 是 adapter 级别观察，而不是 Codex 内部 请求或 compaction 负载的逐字节捕获。

Codex 原生 hook/started 和 hook/completed app-server 通知会被 投影为 codex_app_server.hook agent 事件，用于轨迹和 调试。它们不会调用 OpenClaw 插件 hook。