diff --git a/docs/zh-CN/plugins/codex-harness.md b/docs/zh-CN/plugins/codex-harness.md index ea3e481e7..445c037f6 100644 --- a/docs/zh-CN/plugins/codex-harness.md +++ b/docs/zh-CN/plugins/codex-harness.md @@ -1,64 +1,69 @@ --- read_when: - - 你想使用内置的 Codex app-server harness + - 你想使用内置的 Codex app-server 运行框架 - 你需要 Codex harness 配置示例 - - 你希望仅使用 Codex 的部署直接失败，而不是回退到 Pi -summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次 + - 你希望仅 Codex 的部署失败，而不是回退到 PI +summary: 通过内置的 Codex app-server 承载框架运行 OpenClaw 嵌入式智能体轮次 title: Codex harness x-i18n: - generated_at: "2026-04-28T22:44:39Z" + generated_at: "2026-04-29T17:18:09Z" model: gpt-5.5 provider: openai - source_hash: ab5e03f02121aee4fd328382dfdfd9bfce6a87158758a25b980e7208b22855bd + source_hash: 4799d5d5c81d431e47e1f0af7fb408320c577b0a2900833e0b244e5987734f1c source_path: plugins/codex-harness.md workflow: 16 --- -捆绑的 `codex` 插件让 OpenClaw 通过 Codex app-server 而不是内置的 PI harness 来运行嵌入式智能体轮次。 +内置的 `codex` 插件让 OpenClaw 通过 Codex app-server 运行嵌入式智能体轮次，而不是使用内置的 PI harness。 -当你希望由 Codex 拥有底层智能体会话时使用它：模型发现、原生线程恢复、原生压缩以及 app-server 执行。OpenClaw 仍然拥有聊天渠道、会话文件、模型选择、工具、审批、媒体投递，以及可见的转录镜像。 +当你希望 Codex 拥有底层智能体会话时使用它：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体交付，以及可见的转录镜像。 -如果你正在尝试定位概念，请从 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 开始。简短版本是：`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、Discord、Slack 或其他渠道仍然是通信界面。 +如果你正在了解整体概念，请从 +[Agent Runtimes](/zh-CN/concepts/agent-runtimes) 开始。简短版本是： +`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、Discord、Slack 或其他渠道仍然是通信界面。 -## 这个插件会改变什么 +## 此插件会改变什么 -捆绑的 `codex` 插件提供了几项独立能力： +内置的 `codex` 插件提供了几项独立能力： -| 能力 | 如何使用 | 它的作用 | +| 能力 | 你如何使用 | 它的作用 | | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex app-server 运行 OpenClaw 嵌入式智能体轮次。 | -| 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 从消息对话绑定和控制 Codex app-server 线程。 | +| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex app-server 运行 OpenClaw 嵌入式智能体轮次。 | +| 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 从消息对话绑定并控制 Codex app-server 线程。 | | Codex app-server 提供商/目录 | `codex` 内部机制，通过 harness 暴露 | 让运行时发现并验证 app-server 模型。 | -| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 为受支持的图像理解模型运行有界的 Codex app-server 轮次。 | -| 原生钩子中继 | 围绕 Codex 原生事件的插件钩子 | 让 OpenClaw 观察/阻止受支持的 Codex 原生工具/完成事件。 | +| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 为受支持的图像理解模型运行有界的 Codex app-server 轮次。 | +| 原生钩子中继 | 围绕 Codex 原生事件的插件钩子 | 让 OpenClaw 观察/阻止受支持的 Codex 原生工具/完成事件。 | 启用该插件会让这些能力可用。它**不会**： -- 开始对每个 OpenAI 模型都使用 Codex +- 开始为每个 OpenAI 模型使用 Codex - 将 `openai-codex/*` 模型引用转换为原生运行时 -- 让 ACP/acpx 成为默认 Codex 路径 +- 将 ACP/acpx 设为默认 Codex 路径 - 热切换已经记录 PI 运行时的现有会话 -- 替换 OpenClaw 渠道投递、会话文件、认证配置文件存储或消息路由 +- 替换 OpenClaw 渠道交付、会话文件、认证配置文件存储，或消息路由 -同一个插件也拥有原生 `/codex` 聊天控制命令界面。如果插件已启用，并且用户要求从聊天中绑定、恢复、引导、停止或检查 Codex 线程，智能体应优先使用 `/codex ...` 而不是 ACP。当用户要求 ACP/acpx 或正在测试 ACP Codex 适配器时，ACP 仍是显式回退。 +同一个插件还拥有原生 `/codex` 聊天控制命令界面。如果插件已启用，并且用户要求从聊天中绑定、恢复、引导、停止或检查 Codex 线程，智能体应优先使用 `/codex ...`，而不是 ACP。当用户要求 ACP/acpx 或正在测试 ACP Codex 适配器时，ACP 仍然是显式回退。 -原生 Codex 轮次会保留 OpenClaw 插件钩子作为公共兼容层。这些是进程内 OpenClaw 钩子，而不是 Codex `hooks.json` 命令钩子： +原生 Codex 轮次保留 OpenClaw 插件钩子作为公共兼容层。这些是进程内 OpenClaw 钩子，不是 Codex `hooks.json` 命令钩子： - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` -- `before_message_write`，用于镜像转录记录 -- `before_agent_finalize`，通过 Codex `Stop` 中继 +- `before_message_write` 用于镜像转录记录 +- 通过 Codex `Stop` 中继的 `before_agent_finalize` - `agent_end` -插件也可以注册运行时中立的工具结果中间件，用于在 OpenClaw 执行工具之后、结果返回给 Codex 之前改写 OpenClaw 动态工具结果。这不同于公共 `tool_result_persist` 插件钩子，后者转换由 OpenClaw 拥有的转录工具结果写入。 +插件还可以注册运行时中立的工具结果中间件，用于在 OpenClaw 执行工具之后、结果返回给 Codex 之前，重写 OpenClaw 动态工具结果。这独立于公共 `tool_result_persist` 插件钩子，后者转换 OpenClaw 所拥有的转录工具结果写入。 -关于插件钩子语义本身，请参阅 [插件钩子](/zh-CN/plugins/hooks) 和 [插件守卫行为](/zh-CN/tools/plugin)。 +有关插件钩子语义本身，请参阅[插件钩子](/zh-CN/plugins/hooks) +和[插件守卫行为](/zh-CN/tools/plugin)。 -harness 默认关闭。新配置应将 OpenAI 模型引用保持为规范的 `openai/gpt-*`，并在需要原生 app-server 执行时显式强制设置 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。旧版 `codex/*` 模型引用仍会为了兼容性自动选择 harness，但由运行时支持的旧版提供商前缀不会作为普通模型/提供商选项显示。 +harness 默认关闭。新配置应将 OpenAI 模型引用保持为规范形式 `openai/gpt-*`，并在需要原生 app-server 执行时显式强制 +`agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。旧版 `codex/*` 模型引用仍会为兼容性自动选择 harness，但由运行时支持的旧版提供商前缀不会显示为普通模型/提供商选项。 -如果 `codex` 插件已启用，但主模型仍是 `openai-codex/*`，`openclaw doctor` 会发出警告，而不是更改路由。这是有意的：`openai-codex/*` 仍然是 PI Codex OAuth/订阅路径，而原生 app-server 执行仍是显式运行时选择。 +如果 `codex` 插件已启用，但主模型仍是 +`openai-codex/*`，`openclaw doctor` 会发出警告，而不是更改路由。这是有意的：`openai-codex/*` 仍然是 PI Codex OAuth/订阅路径，而原生 app-server 执行保持为显式运行时选择。 ## 路由映射 @@ -69,67 +74,75 @@ harness 默认关闭。新配置应将 OpenAI 模型引用保持为规范的 `op | 通过普通 OpenClaw runner 使用 OpenAI API | `openai/gpt-*` | 省略或 `runtime: "pi"` | OpenAI provider | `Runtime: OpenClaw Pi Default` | | 通过 PI 使用 Codex OAuth/订阅 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth 提供商 | `Runtime: OpenClaw Pi Default` | | 原生 Codex app-server 嵌入式轮次 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` 插件 | `Runtime: OpenAI Codex` | -| 使用保守自动模式的混合提供商 | 提供商特定引用 | `agentRuntime.id: "auto"` | 可选插件运行时 | 取决于选中的运行时 | -| 显式 Codex ACP 适配器会话 | 取决于 ACP 提示词/模型 | `sessions_spawn` 搭配 `runtime: "acp"` | 健康的 `acpx` 后端 | ACP 任务/会话 Status | +| 使用保守自动模式混合多个提供商 | 提供商特定引用 | `agentRuntime.id: "auto"` | 可选插件运行时 | 取决于所选运行时 | +| 显式 Codex ACP 适配器会话 | 取决于 ACP 提示词/模型 | 带有 `runtime: "acp"` 的 `sessions_spawn` | 健康的 `acpx` 后端 | ACP 任务/会话 Status | -重要的区分是提供商与运行时： +重要区分是提供商与运行时： - `openai-codex/*` 回答“PI 应使用哪个提供商/认证路由？” -- `agentRuntime.id: "codex"` 回答“哪个循环应执行这个嵌入式轮次？” -- `/codex ...` 回答“这个聊天应绑定或控制哪个原生 Codex 对话？” +- `agentRuntime.id: "codex"` 回答“哪个循环应执行此嵌入式轮次？” +- `/codex ...` 回答“此聊天应绑定或控制哪个原生 Codex 对话？” - ACP 回答“acpx 应启动哪个外部 harness 进程？” ## 选择正确的模型前缀 -OpenAI 系列路由是前缀特定的。想通过 PI 使用 Codex OAuth 时使用 `openai-codex/*`；想要直接 OpenAI API 访问，或正在强制使用原生 Codex app-server harness 时使用 `openai/*`： +OpenAI 系列路由与前缀相关。当你想通过 PI 使用 Codex OAuth 时，使用 `openai-codex/*`；当你想直接访问 OpenAI API，或强制使用原生 Codex app-server harness 时，使用 `openai/*`： -| 模型引用 | 运行时路径 | 使用场景 | -| --------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | 通过 OpenClaw/PI 管道使用 OpenAI provider | 你希望使用当前直接 OpenAI Platform API 访问，并提供 `OPENAI_API_KEY`。 | -| `openai-codex/gpt-5.5` | 通过 OpenClaw/PI 使用 OpenAI Codex OAuth | 你希望通过默认 PI runner 使用 ChatGPT/Codex 订阅认证。 | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你希望为嵌入式智能体轮次使用原生 Codex app-server 执行。 | +| 模型引用 | 运行时路径 | 适用场景 | +| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | +| `openai/gpt-5.4` | 通过 OpenClaw/PI 管道使用 OpenAI provider | 你想使用当前通过 `OPENAI_API_KEY` 直接访问的 OpenAI Platform API。 | +| `openai-codex/gpt-5.5` | 通过 OpenClaw/PI 使用 OpenAI Codex OAuth | 你想通过默认 PI runner 使用 ChatGPT/Codex 订阅认证。 | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你想为嵌入式智能体轮次使用原生 Codex app-server 执行。 | -GPT-5.5 目前在 OpenClaw 中仅支持订阅/OAuth。使用 `openai-codex/gpt-5.5` 走 PI OAuth，或将 `openai/gpt-5.5` 与 Codex app-server harness 搭配使用。一旦 OpenAI 在公共 API 上启用 GPT-5.5，就会支持 `openai/gpt-5.5` 的直接 API key 访问。 +GPT-5.5 目前在 OpenClaw 中仅支持订阅/OAuth。PI OAuth 请使用 +`openai-codex/gpt-5.5`，或将 `openai/gpt-5.5` 与 Codex +app-server harness 一起使用。一旦 OpenAI 在公共 API 上启用 GPT-5.5，就会支持对 `openai/gpt-5.5` 的直接 API key 访问。 -旧版 `codex/gpt-*` 引用仍作为兼容别名被接受。Doctor 兼容性迁移会将旧版主运行时引用改写为规范模型引用，并单独记录运行时策略；而仅用作回退的旧版引用会保持不变，因为运行时是为整个智能体容器配置的。新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server harness 配置应使用 `openai/gpt-*` 加 `agentRuntime.id: "codex"`。 +旧版 `codex/gpt-*` 引用仍作为兼容别名被接受。Doctor 兼容性迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略，而仅用于回退的旧版引用会保持不变，因为运行时是为整个智能体容器配置的。新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server harness 配置应使用 `openai/gpt-*` 加上 +`agentRuntime.id: "codex"`。 -`agents.defaults.imageModel` 遵循相同的前缀区分。当图像理解应通过 OpenAI Codex OAuth 提供商路径运行时，使用 `openai-codex/gpt-*`。当图像理解应通过有界的 Codex app-server 轮次运行时，使用 `codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；纯文本 Codex 模型会在媒体轮次开始前失败。 +`agents.defaults.imageModel` 遵循相同的前缀划分。当图像理解应通过 OpenAI Codex OAuth 提供商路径运行时，使用 +`openai-codex/gpt-*`。当图像理解应通过有界 Codex app-server 轮次运行时，使用 `codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；纯文本 Codex 模型会在媒体轮次开始前失败。 -使用 `/status` 确认当前会话的有效 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含选中的 harness id、选择原因、运行时/回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。 +使用 `/status` 确认当前会话的有效 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含所选 harness id、选择原因、运行时/回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。 -### Doctor 警告的含义 +### Doctor 警告是什么意思 当以下条件全部为真时，`openclaw doctor` 会发出警告： -- 捆绑的 `codex` 插件已启用或被允许 +- 内置 `codex` 插件已启用或被允许 - 某个智能体的主模型是 `openai-codex/*` - 该智能体的有效运行时不是 `codex` -该警告存在的原因是用户经常预期“Codex 插件已启用”意味着“原生 Codex app-server 运行时”。OpenClaw 不会做这个跳跃。该警告表示： +该警告存在的原因是用户经常期望“已启用 Codex 插件”意味着“原生 Codex app-server 运行时”。OpenClaw 不会做这个跳跃。该警告表示： -- 如果你本来就想通过 PI 使用 ChatGPT/Codex OAuth，**不需要更改**。 -- 如果你想要原生 app-server 执行，请将模型改为 `openai/` 并设置 `agentRuntime.id: "codex"`。 +- 如果你本来就想通过 PI 使用 ChatGPT/Codex OAuth，**无需更改**。 +- 如果你本来想使用原生 app-server 执行，请将模型更改为 `openai/`，并设置 + `agentRuntime.id: "codex"`。 - 运行时更改后，现有会话仍需要 `/new` 或 `/reset`，因为会话运行时固定是粘性的。 -harness 选择不是实时会话控制。当一个嵌入式轮次运行时，OpenClaw 会在该会话上记录所选 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来会话使用另一个 harness 时，请更改 `agentRuntime` 配置或 `OPENCLAW_AGENT_RUNTIME`；在现有对话于 PI 和 Codex 之间切换前，使用 `/new` 或 `/reset` 启动一个新会话。这样可以避免通过两个不兼容的原生会话系统重放同一份转录。 +harness 选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会在该会话上记录所选 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来会话使用另一个 harness 时，请更改 `agentRuntime` 配置或 +`OPENCLAW_AGENT_RUNTIME`；在 PI 和 Codex 之间切换现有对话前，请使用 `/new` 或 `/reset` 启动一个新会话。这可以避免通过两个不兼容的原生会话系统重放同一份转录。 -在 harness 固定之前创建的旧版会话，一旦已有转录历史，就会被视为已固定到 PI。更改配置后，使用 `/new` 或 `/reset` 将该对话选择加入 Codex。 +在 harness 固定功能出现之前创建的旧版会话，如果已经有转录历史，会被视为已固定到 PI。更改配置后，请使用 `/new` 或 `/reset` 将该对话选择加入 Codex。 -`/status` 会显示有效模型运行时。默认 PI harness 显示为 `Runtime: OpenClaw Pi Default`，Codex app-server harness 显示为 `Runtime: OpenAI Codex`。 +`/status` 会显示有效模型运行时。默认 PI harness 显示为 +`Runtime: OpenClaw Pi Default`，Codex app-server harness 显示为 +`Runtime: OpenAI Codex`。 ## 要求 -- OpenClaw 中可用的捆绑 `codex` 插件。 -- Codex app-server `0.125.0` 或更新版本。捆绑插件默认管理兼容的 Codex app-server 二进制文件，因此 `PATH` 上的本地 `codex` 命令不会影响正常 harness 启动。 +- OpenClaw 中有可用的内置 `codex` 插件。 +- Codex app-server `0.125.0` 或更新版本。默认情况下，内置插件会管理一个兼容的 Codex app-server 二进制文件，因此 `PATH` 上的本地 `codex` 命令不会影响普通 harness 启动。 - app-server 进程或 OpenClaw 的 Codex 认证桥接可用的 Codex 认证。 -该插件会阻止更旧或无版本的 app-server 握手。这让 OpenClaw 保持在已经测试过的协议表面上。 +该插件会阻止较旧或未带版本的 app-server 握手。这会让 OpenClaw 保持在已经测试过的协议界面上。 -对于 live 和 Docker 冒烟测试，认证通常来自 Codex CLI 账户或 OpenClaw `openai-codex` 认证配置文件。本地 stdio app-server 启动也可以在没有账户时回退到 `CODEX_API_KEY` / `OPENAI_API_KEY`。 +对于实时和 Docker 冒烟测试，认证通常来自 Codex CLI 账户或 OpenClaw `openai-codex` 认证配置文件。在没有账户时，本地 stdio app-server 启动也可以回退到 `CODEX_API_KEY` / `OPENAI_API_KEY`。 ## 最小配置 -使用 `openai/gpt-5.5`，启用捆绑插件，并强制使用 `codex` harness： +使用 `openai/gpt-5.5`，启用内置插件，并强制使用 `codex` harness： ```json5 { @@ -151,7 +164,7 @@ harness 选择不是实时会话控制。当一个嵌入式轮次运行时，Ope } ``` -如果你的配置使用 `plugins.allow`，也在那里包含 `codex`： +如果你的配置使用 `plugins.allow`，也要在那里包含 `codex`： ```json5 { @@ -166,19 +179,23 @@ harness 选择不是实时会话控制。当一个嵌入式轮次运行时，Ope } ``` -将 `agents.defaults.model` 或某个智能体模型设置为 `codex/` 的旧版配置仍会自动启用捆绑的 `codex` 插件。新配置应优先使用 `openai/` 加上面的显式 `agentRuntime` 条目。 +将 `agents.defaults.model` 或某个智能体模型设置为 +`codex/` 的旧版配置仍会自动启用内置 `codex` 插件。新配置应优先使用 `openai/` 加上上面的显式 `agentRuntime` 条目。 -## 将 Codex 与其他模型一起添加 +## 将 Codex 与其他模型并用 -如果同一个智能体应在 Codex 和非 Codex 提供商模型之间自由切换，不要全局设置 `agentRuntime.id: "codex"`。强制运行时会应用于该智能体或会话的每个嵌入式轮次。如果你在强制该运行时时选择 Anthropic 模型，OpenClaw 仍会尝试 Codex harness，并以失败关闭的方式处理，而不是静默地将该轮次通过 PI 路由。 +如果同一个智能体应在 Codex 和非 Codex 提供商模型之间自由切换，请不要全局设置 `agentRuntime.id: "codex"`。强制运行时会应用于该智能体或会话的每个嵌入式轮次。如果你在强制该运行时时选择 Anthropic 模型，OpenClaw 仍会尝试 Codex harness 并关闭失败，而不是静默地通过 PI 路由该轮次。 -改用以下一种形式： +改用以下任一形态： -- 将 Codex 放在专用智能体上，并设置 `agentRuntime.id: "codex"`。 -- 将默认智能体保留在 `agentRuntime.id: "auto"`，并为正常的混合提供商用法启用 PI 回退。 -- 仅为兼容性使用旧版 `codex/*` 引用。新配置应优先使用 `openai/*`，并显式设置 Codex 运行时策略。 +- 将 Codex 放在一个专用智能体上，并设置 `agentRuntime.id: "codex"`。 +- 让默认智能体保持 `agentRuntime.id: "auto"`，并在正常混合 + 提供商使用中启用 PI 回退。 +- 仅为兼容性使用旧版 `codex/*` 引用。新配置应优先使用 + `openai/*`，并加上显式的 Codex 运行时策略。 -例如，以下配置会让默认智能体保持正常的自动选择，并添加一个单独的 Codex 智能体： +例如，以下配置让默认智能体保持正常自动选择，并 +添加一个单独的 Codex 智能体： ```json5 { @@ -215,33 +232,37 @@ harness 选择不是实时会话控制。当一个嵌入式轮次运行时，Ope } ``` -使用这种形式时： +采用这种形态时： - 默认的 `main` 智能体使用正常的提供商路径和 PI 兼容性回退。 -- `codex` 智能体使用 Codex 应用服务器 harness。 -- 如果 `codex` 智能体缺少 Codex 或不受支持，该轮会失败，而不是静默改用 PI。 +- `codex` 智能体使用 Codex app-server harness。 +- 如果 `codex` 智能体缺少 Codex 或不受支持，该轮会失败， + 而不是静默改用 PI。 ## 智能体命令路由 -智能体应按意图路由用户请求，而不是只按 “Codex” 这个词路由： +智能体应按意图路由用户请求，而不是仅凭 “Codex” 这个词： -| 用户要求... | 智能体应使用... | +| 用户要求... | 智能体应使用... | | -------------------------------------------------------- | ------------------------------------------------ | -| “将此聊天绑定到 Codex” | `/codex bind` | -| “在这里恢复 Codex 线程 ``” | `/codex resume ` | -| “显示 Codex 线程” | `/codex threads` | -| “为一次异常 Codex 运行提交支持报告” | `/diagnostics [note]` | -| “只为这个附加线程发送 Codex 反馈” | `/codex diagnostics [note]` | -| “将 Codex 用作此智能体的运行时” | 将配置改为 `agentRuntime.id` | -| “在正常 OpenClaw 中使用我的 ChatGPT/Codex 订阅” | `openai-codex/*` 模型引用 | -| “通过 ACP/acpx 运行 Codex” | ACP `sessions_spawn({ runtime: "acp", ... })` | -| “在线程中启动 Claude Code/Gemini/OpenCode/Cursor” | ACP/acpx，而不是 `/codex`，也不是原生子智能体 | +| “将此聊天绑定到 Codex” | `/codex bind` | +| “在这里继续 Codex 线程 ``” | `/codex resume ` | +| “显示 Codex 线程” | `/codex threads` | +| “为一次异常 Codex 运行提交支持报告” | `/diagnostics [note]` | +| “仅为这个附加线程发送 Codex 反馈” | `/codex diagnostics [note]` | +| “将 Codex 用作此智能体的运行时” | 将配置改为 `agentRuntime.id` | +| “在正常 OpenClaw 中使用我的 ChatGPT/Codex 订阅” | `openai-codex/*` 模型引用 | +| “通过 ACP/acpx 运行 Codex” | ACP `sessions_spawn({ runtime: "acp", ... })` | +| “在线程中启动 Claude Code/Gemini/OpenCode/Cursor” | ACP/acpx，而不是 `/codex`，也不是原生子智能体 | -只有当 ACP 已启用、可分派，并由已加载的运行时后端支持时，OpenClaw 才会向智能体宣传 ACP 启动指导。如果 ACP 不可用，系统提示和插件 Skills 不应向智能体讲解 ACP 路由。 +只有当 ACP 已启用、可分派，并由已加载的运行时后端支持时，OpenClaw 才会向智能体宣传 ACP 生成指南。如果 ACP 不可用， +系统提示和插件 Skills 不应教智能体有关 ACP +路由的内容。 ## 仅 Codex 部署 -当你需要证明每个嵌入式智能体轮次都使用 Codex 时，强制使用 Codex harness。显式插件运行时默认没有 PI 回退，因此 `fallback: "none"` 是可选的，但通常可作为文档说明： +当你需要证明每个嵌入式智能体轮次都使用 Codex 时，强制使用 Codex harness。显式插件运行时默认没有 PI 回退，因此 +`fallback: "none"` 是可选的，但通常可用作说明文档： ```json5 { @@ -263,11 +284,14 @@ harness 选择不是实时会话控制。当一个嵌入式轮次运行时，Ope OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -强制使用 Codex 后，如果 Codex 插件被禁用、应用服务器版本过旧，或应用服务器无法启动，OpenClaw 会提前失败。只有当你有意希望 PI 处理缺失的 harness 选择时，才设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。 +强制使用 Codex 后，如果 Codex 插件被禁用、app-server 版本过旧，或 app-server 无法启动，OpenClaw 会提前失败。仅当你有意希望 PI 处理 +缺失的 harness 选择时，才设置 +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。 -## 按智能体使用 Codex +## 按智能体配置 Codex -你可以让一个智能体仅使用 Codex，同时默认智能体保持正常的自动选择： +你可以让一个智能体仅使用 Codex，同时让默认智能体保持正常 +自动选择： ```json5 { @@ -298,17 +322,21 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -使用正常的会话命令切换智能体和模型。`/new` 会创建新的 OpenClaw 会话，Codex harness 会按需创建或恢复其旁车应用服务器线程。`/reset` 会清除此线程的 OpenClaw 会话绑定，并让下一轮再次从当前配置解析 harness。 +使用普通会话命令切换智能体和模型。`/new` 会创建一个新的 +OpenClaw 会话，并由 Codex harness 按需创建或继续其 sidecar app-server +线程。`/reset` 会清除该线程的 OpenClaw 会话绑定， +并让下一轮再次从当前配置解析 harness。 ## 模型发现 -默认情况下，Codex 插件会向应用服务器请求可用模型。如果发现失败或超时，它会使用内置回退目录： +默认情况下，Codex 插件会向 app-server 查询可用模型。如果 +发现失败或超时，它会使用以下模型的内置回退目录： - GPT-5.5 - GPT-5.4 mini - GPT-5.2 -你可以在 `plugins.entries.codex.config.discovery` 下调整发现： +你可以在 `plugins.entries.codex.config.discovery` 下调整发现设置： ```json5 { @@ -328,7 +356,8 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -当你希望启动时避免探测 Codex，并固定使用回退目录时，可以禁用发现： +如果你希望启动时避免探测 Codex，并固定使用 +回退目录，请禁用发现： ```json5 { @@ -347,19 +376,23 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -## 应用服务器连接和策略 +## App-server 连接和策略 -默认情况下，插件会在本地启动 OpenClaw 管理的 Codex 二进制文件： +默认情况下，插件会使用以下命令在本地启动 OpenClaw 管理的 Codex 二进制文件： ```bash codex app-server --listen stdio:// ``` -受管理的二进制文件声明为内置插件运行时依赖，并与其余 `codex` 插件依赖一起暂存。这会将应用服务器版本绑定到内置插件，而不是绑定到本地碰巧安装的某个单独 Codex CLI。只有当你有意想运行不同的可执行文件时，才设置 `appServer.command`。 +托管二进制文件声明为内置插件运行时依赖，并随其余 `codex` 插件依赖一起暂存。这样可以让 app-server +版本绑定到内置插件，而不是取决于本地碰巧安装的某个独立 Codex CLI。 +仅当你有意运行不同的可执行文件时，才设置 `appServer.command`。 -默认情况下，OpenClaw 以 YOLO 模式启动本地 Codex harness 会话：`approvalPolicy: "never"`、`approvalsReviewer: "user"` 和 `sandbox: "danger-full-access"`。这是自主心跳所使用的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会停在无人响应的原生批准提示上。 +默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话： +`approvalPolicy: "never"`、`approvalsReviewer: "user"` 和 +`sandbox: "danger-full-access"`。这是用于自主心跳的可信本地操作者姿态：Codex 可以使用 shell 和网络工具，而不会停在无人回答的原生批准提示上。 -要启用由 Codex guardian 审核的批准，请设置 `appServer.mode: +若要选择使用 Codex guardian 审核的批准，请设置 `appServer.mode: "guardian"`： ```json5 @@ -380,11 +413,21 @@ codex app-server --listen stdio:// } ``` -Guardian 模式使用 Codex 的原生自动审核批准路径。当 Codex 请求离开沙箱、写入工作区外部，或添加网络访问等权限时，Codex 会将该批准请求路由到原生审核器，而不是人工提示。审核器会应用 Codex 的风险框架，并批准或拒绝该具体请求。当你需要比 YOLO 模式更多的护栏，但仍需要无人值守智能体继续推进时，请使用 Guardian。 +Guardian 模式使用 Codex 的原生自动审核批准路径。当 Codex 请求 +离开沙箱、写入工作区外部，或添加网络 +访问等权限时，Codex 会将该批准请求路由到原生审核器，而不是 +人工提示。审核器会应用 Codex 的风险框架，并批准或拒绝 +具体请求。当你需要比 YOLO 模式更多护栏、 +但仍需要无人值守智能体继续推进时，请使用 Guardian。 -`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。单独的策略字段仍会覆盖 `mode`，因此高级部署可以混用预设和显式选择。较旧的 `guardian_subagent` 审核器值仍作为兼容别名被接受，但新配置应使用 `auto_review`。 +`guardian` 预设会展开为 `approvalPolicy: "on-request"`、 +`approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。 +单个策略字段仍会覆盖 `mode`，因此高级部署可以将 +该预设与显式选择混用。旧的 `guardian_subagent` 审核器值 +仍作为兼容性别名被接受，但新配置应使用 +`auto_review`。 -对于已运行的应用服务器，请使用 WebSocket 传输： +对于已在运行的 app-server，请使用 WebSocket 传输： ```json5 { @@ -406,15 +449,25 @@ Guardian 模式使用 Codex 的原生自动审核批准路径。当 Codex 请求 } ``` -Stdio 应用服务器启动默认继承 OpenClaw 的进程环境，但 OpenClaw 拥有 Codex 应用服务器账号桥接。认证按以下顺序选择： +Stdio app-server 启动默认继承 OpenClaw 的进程环境， +但 OpenClaw 拥有 Codex app-server 账号桥接。Auth 按以下 +顺序选择： -1. 该智能体的显式 OpenClaw Codex 认证配置文件。 -2. 应用服务器的现有账号，例如本地 Codex CLI ChatGPT 登录。 -3. 仅限本地 stdio 应用服务器启动：当不存在应用服务器账号且仍需要 OpenAI 认证时，先使用 `CODEX_API_KEY`，再使用 `OPENAI_API_KEY`。 +1. 该智能体的显式 OpenClaw Codex auth profile。 +2. app-server 的现有账号，例如本地 Codex CLI ChatGPT 登录。 +3. 仅针对本地 stdio app-server 启动，在没有 app-server 账号且仍需要 OpenAI auth 时，使用 `CODEX_API_KEY`，然后是 + `OPENAI_API_KEY`。 -当 OpenClaw 看到 ChatGPT 订阅样式的 Codex 认证配置文件时，它会从生成的 Codex 子进程中移除 `CODEX_API_KEY` 和 `OPENAI_API_KEY`。这会让 Gateway 网关级 API 密钥仍可用于嵌入或直接 OpenAI 模型，而不会让原生 Codex 应用服务器轮次意外通过 API 计费。显式 Codex API 密钥配置文件和本地 stdio 环境密钥回退会使用应用服务器登录，而不是继承的子进程环境。WebSocket 应用服务器连接不会收到 Gateway 网关环境 API 密钥回退；请使用显式认证配置文件或远程应用服务器自己的账号。 +当 OpenClaw 看到 ChatGPT 订阅式 Codex auth profile 时，它会从生成的 Codex 子进程中移除 +`CODEX_API_KEY` 和 `OPENAI_API_KEY`。这样可以让 Gateway 网关级 API key 继续可用于 embeddings 或直接 OpenAI 模型， +而不会让原生 Codex app-server 轮次意外通过 API 计费。 +显式 Codex API-key profiles 和本地 stdio env-key 回退使用 app-server +登录，而不是继承的子进程环境。WebSocket app-server 连接 +不会接收 Gateway 网关环境 API-key 回退；请使用显式 auth profile，或使用 +远程 app-server 自己的账号。 -如果部署需要额外的环境隔离，请将这些变量添加到 `appServer.clearEnv`： +如果部署需要额外的环境隔离，请将这些变量添加到 +`appServer.clearEnv`： ```json5 { @@ -433,27 +486,33 @@ Stdio 应用服务器启动默认继承 OpenClaw 的进程环境，但 OpenClaw } ``` -`appServer.clearEnv` 只影响生成的 Codex 应用服务器子进程。 +`appServer.clearEnv` 仅影响生成的 Codex app-server 子进程。 支持的 `appServer` 字段： -| 字段 | 默认值 | 含义 | +| 字段 | 默认值 | 含义 | | ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | -| `command` | 托管的 Codex 二进制文件 | stdio 传输协议使用的可执行文件。保持未设置以使用托管二进制文件；仅在明确覆盖时设置。 | -| `args` | `["app-server", "--listen", "stdio://"]` | stdio 传输协议的参数。 | -| `url` | 未设置 | WebSocket app-server URL。 | -| `authToken` | 未设置 | WebSocket 传输协议的 Bearer 令牌。 | -| `headers` | `{}` | 额外的 WebSocket 标头。 | -| `clearEnv` | `[]` | OpenClaw 构建继承环境后，从派生的 stdio app-server 进程中移除的额外环境变量名称。 | -| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | -| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 | -| `approvalPolicy` | `"never"` | 发送到线程 start/resume/turn 的原生 Codex 审批策略。 | -| `sandbox` | `"danger-full-access"` | 发送到线程 start/resume 的原生 Codex 沙箱模式。 | -| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 让 Codex 审核原生审批提示。`guardian_subagent` 仍是旧版别名。 | -| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 | +| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | +| `command` | 托管的 Codex 二进制文件 | stdio 传输协议的可执行文件。留空会使用托管二进制文件；仅在需要显式覆盖时设置。 | +| `args` | `["app-server", "--listen", "stdio://"]` | stdio 传输协议的参数。 | +| `url` | 未设置 | WebSocket app-server URL。 | +| `authToken` | 未设置 | WebSocket 传输协议的 Bearer 令牌。 | +| `headers` | `{}` | 额外的 WebSocket 标头。 | +| `clearEnv` | `[]` | OpenClaw 构建其继承环境后，从生成的 stdio app-server 进程中移除的额外环境变量名称。 | +| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | +| `mode` | `"yolo"` | YOLO 或 guardian 审查执行的预设。 | +| `approvalPolicy` | `"never"` | 发送到线程开始/恢复/回合的原生 Codex 批准策略。 | +| `sandbox` | `"danger-full-access"` | 发送到线程开始/恢复的原生 Codex 沙箱模式。 | +| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 让 Codex 审查原生批准提示。`guardian_subagent` 仍是旧别名。 | +| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 | -本地测试仍可使用环境覆盖： +OpenClaw 拥有的动态工具调用会独立于 +`appServer.requestTimeoutMs` 进行限制：每个 Codex `item/tool/call` 请求都必须在 30 秒内收到 +OpenClaw 响应。超时时，OpenClaw 会在支持的位置中止工具 +信号，并向 Codex 返回失败的动态工具响应，使 +回合可以继续，而不是让会话停留在 `processing` 状态。 + +环境覆盖仍可用于本地测试： - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -463,22 +522,23 @@ Stdio 应用服务器启动默认继承 OpenClaw 的进程环境，但 OpenClaw 当 `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 设置相同的已审核文件中。 +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已移除。改用 +`plugins.entries.codex.config.appServer.mode: "guardian"`，或使用 +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` 进行一次性本地测试。对于可重复部署，优先使用配置，因为它会将插件行为保留在与其余 Codex harness 设置相同的已审查文件中。 ## 计算机使用 -计算机使用在自己的设置指南中说明： +计算机使用在其自己的设置指南中说明： [Codex 计算机使用](/zh-CN/plugins/codex-computer-use)。 -简短版本：OpenClaw 不会内置桌面控制应用，也不会自行执行桌面操作。它会准备 Codex app-server，验证 -`computer-use` MCP 服务器可用，然后让 Codex 在 Codex 模式轮次期间处理原生 +简短版本：OpenClaw 不内置桌面控制应用，也不自行执行 +桌面操作。它会准备 Codex app-server，验证 +`computer-use` MCP 服务器可用，然后让 Codex 在 Codex 模式回合期间处理原生 MCP 工具调用。 若要在 Codex marketplace 流程之外直接访问 TryCua 驱动，请使用 `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` 注册 `cua-driver mcp`。 -请参阅 [Codex 计算机使用](/zh-CN/plugins/codex-computer-use)，了解 Codex 拥有的计算机使用与直接 MCP 注册之间的区别。 +参见 [Codex 计算机使用](/zh-CN/plugins/codex-computer-use)，了解 Codex 拥有的计算机使用与直接 MCP 注册之间的区别。 最小配置： @@ -508,20 +568,26 @@ MCP 工具调用。 } ``` -可以从命令界面检查或安装该设置： +可以通过命令界面检查或安装该设置： - `/codex computer-use status` - `/codex computer-use install` - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -计算机使用仅适用于 macOS，并且在 Codex MCP 服务器能够控制应用前，可能需要本地操作系统权限。如果 `computerUse.enabled` 为 true 且 MCP 服务器不可用，Codex 模式轮次会在线程启动前失败，而不是在没有原生计算机使用工具的情况下静默运行。请参阅 -[Codex 计算机使用](/zh-CN/plugins/codex-computer-use)，了解 marketplace 选项、远程目录限制、Status 原因和故障排除。 +计算机使用仅适用于 macOS，并且在 +Codex MCP 服务器控制应用之前，可能需要本地操作系统权限。如果 `computerUse.enabled` 为 true 且 MCP +服务器不可用，Codex 模式回合会在线程开始前失败，而不是在没有原生计算机使用工具的情况下静默运行。参见 +[Codex 计算机使用](/zh-CN/plugins/codex-computer-use)，了解 marketplace 选项、 +远程目录限制、Status 原因和故障排除。 -当 `computerUse.autoInstall` 为 true 时，如果 Codex 尚未发现本地 marketplace，OpenClaw 可以从 -`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 注册标准内置 Codex Desktop marketplace。更改运行时或计算机使用配置后，请使用 `/new` 或 `/reset`，以免现有会话继续保留旧的 PI 或 Codex 线程绑定。 +当 `computerUse.autoInstall` 为 true 时，如果 Codex +尚未发现本地 marketplace，OpenClaw 可以从 +`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 注册标准的 +内置 Codex Desktop marketplace。更改运行时或计算机使用配置后，使用 `/new` 或 `/reset`，使现有会话不会保留旧的 +PI 或 Codex 线程绑定。 -## 常用配方 +## 常见配方 使用默认 stdio 传输协议的本地 Codex： @@ -559,7 +625,7 @@ MCP 工具调用。 } ``` -经过 guardian 审核的 Codex 审批： +由 guardian 审查的 Codex 批准： ```json5 { @@ -604,23 +670,24 @@ MCP 工具调用。 } ``` -模型切换仍由 OpenClaw 控制。当 OpenClaw 会话附加到现有 Codex 线程时，下一个轮次会再次将当前选择的 -OpenAI 模型、提供商、审批策略、沙箱和服务层级发送给 -app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但要求 Codex 使用新选择的模型继续。 +模型切换仍由 OpenClaw 控制。当 OpenClaw 会话附加到现有 Codex 线程时，下一回合会再次向 +app-server 发送当前选定的 +OpenAI 模型、提供商、批准策略、沙箱和服务层级。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但要求 Codex 使用新选择的模型继续。 ## Codex 命令 -内置插件会将 `/codex` 注册为授权斜杠命令。它是通用命令，适用于任何支持 OpenClaw 文本命令的渠道。 +内置插件会将 `/codex` 注册为授权斜杠命令。它是 +通用的，可在任何支持 OpenClaw 文本命令的渠道上使用。 -常用形式： +常见形式： - `/codex status` 显示实时 app-server 连接、模型、账户、速率限制、MCP 服务器和 Skills。 - `/codex models` 列出实时 Codex app-server 模型。 - `/codex threads [filter]` 列出最近的 Codex 线程。 - `/codex resume ` 将当前 OpenClaw 会话附加到现有 Codex 线程。 -- `/codex compact` 要求 Codex app-server 压缩已附加的线程。 -- `/codex review` 为已附加的线程启动 Codex 原生审查。 -- `/codex diagnostics [note]` 会在发送已附加线程的 Codex 诊断反馈前请求确认。 +- `/codex compact` 请求 Codex app-server 压缩附加的线程。 +- `/codex review` 为附加的线程启动 Codex 原生审查。 +- `/codex diagnostics [note]` 在为附加的线程发送 Codex 诊断反馈前询问。 - `/codex computer-use status` 检查已配置的计算机使用插件和 MCP 服务器。 - `/codex computer-use install` 安装已配置的计算机使用插件并重新加载 MCP 服务器。 - `/codex account` 显示账户和速率限制 Status。 @@ -629,42 +696,78 @@ app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑 ### 常见调试工作流 -当由 Codex 支持的智能体在 Telegram、Discord、Slack 或其他渠道中做出意外行为时，请从发生问题的对话开始： +当由 Codex 支持的智能体在 Telegram、Discord、Slack +或其他渠道中执行了意外操作时，从问题发生的对话开始： -1. 运行 `/diagnostics bad tool choice after image upload`，或另一条描述你所见情况的简短备注。 -2. 批准一次诊断请求。该批准会创建本地 Gateway 网关诊断 zip，并且因为该会话使用 Codex harness，还会将相关的 Codex 反馈包发送到 OpenAI 服务器。 -3. 将完成后的诊断回复复制到 bug 报告或支持讨论中。它包含本地包路径、隐私摘要、OpenClaw 会话 ID、Codex 线程 ID，以及每个 Codex 线程的一行 `Inspect locally`。 -4. 如果你想自行调试该运行，请在终端中运行打印出的 `Inspect locally` 命令。它看起来像 `codex resume `，会打开原生 Codex 线程，以便你检查对话、在本地继续，或询问 Codex 为什么选择某个特定工具或计划。 +1. 运行 `/diagnostics bad tool choice after image upload` 或另一条描述你所见内容的简短说明。 +2. 批准一次诊断请求。批准会创建本地 Gateway 网关 + 诊断 zip，并且由于该会话正在使用 Codex harness，还会 + 将相关 Codex 反馈包发送到 OpenAI 服务器。 +3. 将完成的诊断回复复制到错误报告或支持线程中。 + 它包含本地包路径、隐私摘要、OpenClaw 会话 ID、 + Codex 线程 ID，以及每个 Codex 线程的一行 `Inspect locally`。 +4. 如果你想自行调试该运行，请在终端中运行打印出的 `Inspect locally` + 命令。它看起来像 `codex resume `，并会打开 + 原生 Codex 线程，这样你可以检查对话、在本地继续对话， + 或询问 Codex 为什么选择了特定工具或计划。 -仅当你明确想为当前附加的线程上传 Codex 反馈，而不需要完整 OpenClaw -Gateway 网关诊断包时，才使用 `/codex diagnostics [note]`。对于大多数支持报告，`/diagnostics [note]` 是更好的起点，因为它会在一条回复中把本地 Gateway 网关状态和 Codex 线程 ID 关联起来。请参阅 [诊断导出](/zh-CN/gateway/diagnostics)，了解完整的隐私模型和群聊行为。 +仅当你明确希望为当前附加的线程上传 Codex +反馈，而不需要完整的 OpenClaw +Gateway 网关诊断包时，才使用 `/codex diagnostics [note]`。对于大多数支持报告，`/diagnostics [note]` 是 +更好的起点，因为它会在一条回复中把本地 Gateway 网关状态和 Codex +线程 ID 关联起来。参见 [诊断导出](/zh-CN/gateway/diagnostics) +了解完整的隐私模型和群聊行为。 -核心 OpenClaw 还公开了仅限所有者使用的 `/diagnostics [note]`，作为通用 -Gateway 网关诊断命令。它的审批提示会显示敏感数据前言，链接到 [诊断导出](/zh-CN/gateway/diagnostics)，并且每次都通过显式 exec 审批请求 -`openclaw gateway diagnostics export --json`。不要使用允许所有规则来批准诊断。批准后，OpenClaw 会发送一份可粘贴的报告，其中包含本地包路径和清单摘要。当活跃 OpenClaw 会话使用 Codex harness 时，同一个批准也会授权将相关 Codex 反馈包发送到 -OpenAI 服务器。审批提示会说明将发送 Codex 反馈，但不会在批准前列出 Codex 会话或线程 ID。 +核心 OpenClaw 还公开仅 owner 可用的 `/diagnostics [note]`，作为通用 +Gateway 网关诊断命令。其批准提示会显示敏感数据 +前言、链接到 [诊断导出](/zh-CN/gateway/diagnostics)，并且每次都通过显式 exec 批准请求 +`openclaw gateway diagnostics export --json`。 +不要使用 allow-all 规则批准诊断。批准后， +OpenClaw 会发送一份可粘贴的报告，其中包含本地包路径和 manifest +摘要。当活动 OpenClaw 会话使用 Codex harness 时，同一次批准也会授权将相关 Codex 反馈包发送到 +OpenAI 服务器。批准提示会说明将发送 Codex 反馈，但 +在批准前不会列出 Codex 会话或线程 ID。 -如果所有者在群聊中调用 `/diagnostics`，OpenClaw 会保持共享渠道整洁：群组只会收到一条简短通知，而诊断前言、审批提示以及 Codex 会话/线程 ID 会通过私有审批路由发送给所有者。如果没有私有所有者路由，OpenClaw 会拒绝群组请求，并要求所有者从私信中运行它。 +如果 `/diagnostics` 由 owner 在群聊中调用，OpenClaw 会保持 +共享渠道干净：群组只会收到一条简短通知，而 +诊断前言、批准提示和 Codex 会话/线程 ID 会通过 +私有批准路线发送给 owner。如果没有私有 owner 路线， +OpenClaw 会拒绝群组请求，并要求 owner 从私信运行它。 -已批准的 Codex 上传会调用 Codex app-server `feedback/upload`，并要求 -app-server 在可用时包含每个列出线程和派生 Codex 子线程的日志。上传通过 Codex 的常规反馈路径发送到 OpenAI 服务器；如果该 app-server 中禁用了 Codex 反馈，该命令会返回 app-server 错误。完成后的诊断回复会列出已发送线程的渠道、OpenClaw 会话 ID、Codex 线程 ID，以及本地 -`codex resume ` 命令。如果你拒绝或忽略审批，OpenClaw 不会打印这些 Codex ID。此上传不会替代本地 Gateway 网关诊断导出。 +获批的 Codex 上传会调用 Codex app-server `feedback/upload`，并要求 +app-server 在可用时包含每个列出线程和派生 Codex 子线程的日志。上传会通过 +Codex 的常规反馈路径发送到 OpenAI 服务器；如果该 app-server 中禁用了 +Codex 反馈，该命令会返回 app-server 错误。完成后的诊断回复会列出已发送 +线程的渠道、OpenClaw 会话 ID、Codex 线程 ID，以及本地 +`codex resume ` 命令。如果你拒绝或忽略批准，OpenClaw 不会打印 +这些 Codex ID。此上传不会替代本地 Gateway 网关诊断导出。 -`/codex resume` 会写入与 harness 正常轮次所用相同的 sidecar 绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选择的 OpenClaw 模型传入 app-server，并保持扩展历史记录启用。 +`/codex resume` 会写入 harness 用于常规轮次的同一份 sidecar 绑定文件。 +在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选中的 OpenClaw 模型 +传入 app-server，并保持扩展历史记录启用。 ### 从 CLI 检查 Codex 线程 -理解一次异常 Codex 运行的最快方式，通常是直接打开原生 Codex 线程： +理解一次有问题的 Codex 运行，最快的方法通常是直接打开原生 Codex +线程： ```sh codex resume ``` -当你在渠道对话中发现 bug，并想检查有问题的 Codex 会话、在本地继续它，或询问 Codex 为什么做出某个工具或推理选择时，请使用此方法。最简单的路径通常是先运行 `/diagnostics [note]`：你批准后，完成的报告会列出每个 Codex 线程，并打印一个 `Inspect locally` 命令，例如 `codex resume `。你可以将该命令直接复制到终端中。 +当你在渠道对话中发现 bug，并想检查有问题的 Codex 会话、在本地继续该会话， +或询问 Codex 为什么做出某个工具或推理选择时，请使用此方法。最简单的路径通常是先运行 +`/diagnostics [note]`：批准后，完成的报告会列出每个 Codex 线程，并打印一个 +`Inspect locally` 命令，例如 +`codex resume `。你可以直接将该命令复制到终端中。 -你也可以从当前聊天的 `/codex binding` 获取线程 ID，或从近期 Codex app-server 线程的 `/codex threads [filter]` 获取线程 ID，然后在 shell 中运行相同的 `codex resume` 命令。 +你也可以通过当前聊天的 `/codex binding` 或近期 Codex app-server 线程的 +`/codex threads [filter]` 获取线程 ID，然后在 shell 中运行同一个 +`codex resume` 命令。 -该命令接口要求 Codex app-server `0.125.0` 或更高版本。如果未来版本或自定义 app-server 未暴露相应的 JSON-RPC 方法，单个控制方法会报告为 `unsupported by this Codex app-server`。 +该命令表面要求 Codex app-server `0.125.0` 或更新版本。如果未来或自定义的 +app-server 未暴露相应 JSON-RPC 方法，单个控制方法会报告为 +`unsupported by this Codex app-server`。 ## 钩子边界 @@ -674,80 +777,103 @@ Codex harness 有三层钩子： | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | | OpenClaw 插件钩子 | OpenClaw | 跨 PI 和 Codex harness 的产品/插件兼容性。 | | Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的逐轮适配器行为。 | -| Codex 原生钩子 | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 | +| Codex 原生钩子 | Codex | 来自 Codex 配置的低层 Codex 生命周期和原生工具策略。 | -OpenClaw 不使用项目级或全局 Codex `hooks.json` 文件来路由 OpenClaw 插件行为。对于受支持的原生工具和权限桥接，OpenClaw 会为每个线程注入 Codex 配置，用于 `PreToolUse`、`PostToolUse`、`PermissionRequest` 和 `Stop`。其他 Codex 钩子（例如 `SessionStart` 和 `UserPromptSubmit`）仍然是 Codex 层级的控制项；它们不会在 v1 合约中作为 OpenClaw 插件钩子暴露。 +OpenClaw 不使用项目或全局 Codex `hooks.json` 文件来路由 +OpenClaw 插件行为。对于受支持的原生工具和权限桥接，OpenClaw 会为 +`PreToolUse`、`PostToolUse`、`PermissionRequest` 和 `Stop` 注入逐线程 +Codex 配置。其他 Codex 钩子（例如 `SessionStart` 和 +`UserPromptSubmit`）仍然是 Codex 层级的控制；它们不会在 v1 契约中暴露为 +OpenClaw 插件钩子。 -对于 OpenClaw 动态工具，OpenClaw 会在 Codex 请求调用后执行该工具，因此 OpenClaw 会在 harness 适配器中触发其拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范工具记录。OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生钩子回调暴露该操作，否则它无法重写原生 Codex 线程。 +对于 OpenClaw 动态工具，OpenClaw 会在 Codex 请求调用后执行该工具，因此 +OpenClaw 会在 harness 适配器中触发其拥有的插件和中间件行为。对于 +Codex 原生工具，Codex 拥有规范工具记录。OpenClaw 可以镜像选定事件，但除非 +Codex 通过 app-server 或原生钩子回调暴露该操作，否则它无法重写原生 +Codex 线程。 -压缩和 LLM 生命周期投影来自 Codex app-server 通知和 OpenClaw 适配器状态，而不是原生 Codex 钩子命令。OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 `llm_output` 事件是适配器层级的观察结果，不是 Codex 内部请求或压缩载荷的逐字节捕获。 +压缩和 LLM 生命周期投影来自 Codex app-server 通知和 OpenClaw 适配器状态， +而不是原生 Codex 钩子命令。OpenClaw 的 `before_compaction`、 +`after_compaction`、`llm_input` 和 `llm_output` 事件是适配器层级的观察， +不是对 Codex 内部请求或压缩载荷的逐字节捕获。 -Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会投影为 `codex_app_server.hook` 智能体事件，用于轨迹记录和调试。它们不会调用 OpenClaw 插件钩子。 +Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会被投影为 +`codex_app_server.hook` 智能体事件，用于轨迹记录和调试。它们不会调用 +OpenClaw 插件钩子。 -## V1 支持合约 +## V1 支持契约 -Codex 模式不是底层换了一个模型调用的 PI。Codex 拥有更多原生模型循环，而 OpenClaw 会围绕该边界适配其插件和会话表面。 +Codex 模式不是底层换了不同模型调用的 PI。Codex 拥有更多原生模型循环， +OpenClaw 会围绕该边界适配其插件和会话表面。 Codex 运行时 v1 支持： | 表面 | 支持情况 | 原因 | | --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex app-server 拥有 OpenAI 轮次、原生线程恢复和原生工具续接。 | -| OpenClaw 渠道路由和交付 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 和其他渠道仍位于模型运行时之外。 | -| OpenClaw 动态工具 | 支持 | Codex 要求 OpenClaw 执行这些工具，因此 OpenClaw 保持在执行路径中。 | -| 提示词和上下文插件 | 支持 | OpenClaw 会在启动或恢复线程前构建提示词叠加层，并将上下文投影到 Codex 轮次中。 | -| 上下文引擎生命周期 | 支持 | 组装、摄取或轮次后维护，以及上下文引擎压缩协调会为 Codex 轮次运行。 | -| 动态工具钩子 | 支持 | `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 在最终确定前再进行一次模型处理。 | -| 原生 shell、patch 和 MCP 阻止或观察 | 通过原生钩子中继支持 | Codex `PreToolUse` 和 `PostToolUse` 会针对已承诺的原生工具表面中继，包括 Codex app-server `0.125.0` 或更高版本上的 MCP 载荷。支持阻止；不支持参数重写。 | -| 原生权限策略 | 通过原生钩子中继支持 | 在运行时暴露该能力时，Codex `PermissionRequest` 可以通过 OpenClaw 策略路由。如果 OpenClaw 未返回决策，Codex 会继续走其正常 guardian 或用户批准路径。 | -| App-server 轨迹捕获 | 支持 | OpenClaw 会记录它发送给 app-server 的请求，以及它接收到的 app-server 通知。 | +| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex app-server 拥有 OpenAI 轮次、原生线程恢复和原生工具继续执行。 | +| OpenClaw 渠道路由和交付 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 和其他渠道保持在模型运行时之外。 | +| OpenClaw 动态工具 | 支持 | Codex 要求 OpenClaw 执行这些工具，因此 OpenClaw 保持在执行路径中。 | +| 提示词和上下文插件 | 支持 | OpenClaw 会构建提示词覆盖层，并在启动或恢复线程前将上下文投影到 Codex 轮次中。 | +| 上下文引擎生命周期 | 支持 | 组装、摄取或轮次后维护，以及上下文引擎压缩协调会为 Codex 轮次运行。 | +| 动态工具钩子 | 支持 | `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 在最终确定前再执行一次模型传递。 | +| 原生 shell、patch 和 MCP 阻止或观察 | 通过原生钩子中继支持 | 对于已承诺的原生工具表面，Codex `PreToolUse` 和 `PostToolUse` 会被中继，包括 Codex app-server `0.125.0` 或更新版本上的 MCP 载荷。支持阻止；不支持参数重写。 | +| 原生权限策略 | 通过原生钩子中继支持 | 在运行时暴露的地方，Codex `PermissionRequest` 可以通过 OpenClaw 策略路由。如果 OpenClaw 不返回决策，Codex 会继续走其常规 guardian 或用户批准路径。 | +| App-server 轨迹捕获 | 支持 | OpenClaw 会记录它发送给 app-server 的请求，以及它收到的 app-server 通知。 | Codex 运行时 v1 不支持： -| 表面 | V1 边界 | 未来路径 | +| 表面 | V1 边界 | 未来路径 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| 原生工具参数变更 | Codex 原生工具前置钩子可以阻止，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子/架构支持替换工具输入。 | -| 可编辑的 Codex 原生转录历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有镜像，并可以投影未来上下文，但不应变更不受支持的内部状态。 | 如果需要原生线程手术式修改，请添加显式 Codex app-server API。 | -| Codex 原生工具记录的 `tool_result_persist` | 该钩子转换 OpenClaw 拥有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范重写需要 Codex 支持。 | -| 丰富的原生压缩元数据 | OpenClaw 会观察压缩开始和完成，但不会接收稳定的保留/丢弃列表、token delta 或摘要载荷。 | 需要更丰富的 Codex 压缩事件。 | -| 压缩干预 | 当前 OpenClaw 压缩钩子在 Codex 模式下是通知层级的。 | 如果插件需要否决或重写原生压缩，请添加 Codex 前置/后置压缩钩子。 | -| 逐字节模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但 Codex core 会在内部构建最终 OpenAI API 请求。 | 需要 Codex 模型请求跟踪事件或调试 API。 | +| 原生工具参数变更 | Codex 原生工具前置钩子可以阻止，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子/架构支持替换工具输入。 | +| 可编辑的 Codex 原生转录历史 | Codex 拥有规范原生线程历史。OpenClaw 拥有镜像，并可以投影未来上下文，但不应修改不受支持的内部结构。 | 如果需要原生线程手术式修改，请添加显式 Codex app-server API。 | +| Codex 原生工具记录的 `tool_result_persist` | 该钩子转换的是 OpenClaw 拥有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范重写需要 Codex 支持。 | +| 丰富的原生压缩元数据 | OpenClaw 会观察压缩开始和完成，但不会收到稳定的保留/丢弃列表、token 差量或摘要载荷。 | 需要更丰富的 Codex 压缩事件。 | +| 压缩干预 | 当前 OpenClaw 压缩钩子在 Codex 模式中是通知层级的。 | 如果插件需要否决或重写原生压缩，请添加 Codex 前置/后置压缩钩子。 | +| 逐字节模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但 Codex core 会在内部构建最终 OpenAI API 请求。 | 需要 Codex 模型请求追踪事件或调试 API。 | ## 工具、媒体和压缩 -Codex harness 只改变底层嵌入式智能体执行器。 +Codex harness 只改变低层嵌入式智能体执行器。 -OpenClaw 仍然构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、批准和消息工具输出会继续通过正常 OpenClaw 交付路径。 +OpenClaw 仍然会构建工具列表，并从 harness 接收动态工具结果。文本、图片、视频、 +音乐、TTS、批准和消息工具输出会继续通过常规 OpenClaw 交付路径。 -原生钩子中继有意保持通用，但 v1 支持合约仅限于 OpenClaw 测试过的 Codex 原生工具和权限路径。在 Codex 运行时中，这包括 shell、patch 和 MCP `PreToolUse`、`PostToolUse` 以及 `PermissionRequest` 载荷。在运行时合约明确命名某个未来 Codex 钩子事件之前，不要假设每个未来 Codex 钩子事件都是 OpenClaw 插件表面。 +原生钩子中继有意保持通用，但 v1 支持契约仅限于 OpenClaw 测试过的 +Codex 原生工具和权限路径。在 Codex 运行时中，这包括 shell、patch 和 MCP +`PreToolUse`、`PostToolUse` 以及 `PermissionRequest` 载荷。不要假设每个未来的 +Codex 钩子事件都是 OpenClaw 插件表面，除非运行时契约明确命名它。 -对于 `PermissionRequest`，OpenClaw 只会在策略做出决定时返回显式允许或拒绝决策。无决策结果不是允许。Codex 会将其视为没有钩子决策，并回退到自己的 guardian 或用户批准路径。 +对于 `PermissionRequest`，OpenClaw 只有在策略做出决定时才返回显式允许或拒绝决策。 +无决策结果不是允许。Codex 会将其视为没有钩子决策，并回退到自己的 guardian 或用户批准路径。 -当 Codex 将 `_meta.codex_approval_kind` 标记为 `"mcp_tool_call"` 时，Codex MCP 工具批准请求会通过 OpenClaw 的插件批准流路由。Codex `request_user_input` 提示会发送回发起聊天，下一条排队的后续消息会回答该原生服务器请求，而不是被引导为额外上下文。其他 MCP 请求仍会默认关闭失败。 +当 Codex 将 `_meta.codex_approval_kind` 标记为 +`"mcp_tool_call"` 时，Codex MCP 工具批准征询会通过 OpenClaw 的插件批准流程路由。 +Codex `request_user_input` 提示会被发送回原始聊天，下一条排队的后续消息会回答该原生 +服务器请求，而不是被引导为额外上下文。其他 MCP 征询请求仍会失败关闭。 -当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一个转录镜像，用于渠道历史、搜索、`/new`、`/reset`，以及未来的模型或 harness 切换。该镜像包括用户提示、最终助手文本，以及 app-server 发出时的轻量级 Codex 推理或计划记录。目前，OpenClaw 只记录原生压缩开始和完成信号。它尚未暴露人类可读的压缩摘要，或可审计的 Codex 在压缩后保留了哪些条目的列表。 +当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。OpenClaw 会为渠道历史、搜索、`/new`、`/reset` 以及未来的模型或 harness 切换保留一份转录镜像。当 app-server 发出用户提示词、最终助手文本，以及轻量级 Codex 推理或计划记录时，镜像会包含这些内容。目前，OpenClaw 只记录原生压缩的开始和完成信号。它尚未公开可读的压缩摘要，也没有公开可审计的列表来说明 Codex 在压缩后保留了哪些条目。 -因为 Codex 拥有规范原生线程，`tool_result_persist` 当前不会重写 Codex 原生工具结果记录。它只在 OpenClaw 正在写入 OpenClaw 拥有的会话转录工具结果时适用。 +由于 Codex 拥有规范的原生线程，`tool_result_persist` 目前不会重写 Codex 原生工具结果记录。它只在 OpenClaw 写入由 OpenClaw 拥有的会话转录工具结果时适用。 媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 和媒体理解会继续使用匹配的提供商/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 ## 故障排除 -**Codex 不会显示为普通的 `/model` 提供商：** 对于新的配置，这是预期行为。选择一个带有 `agentRuntime.id: "codex"` 的 `openai/gpt-*` 模型（或旧版 `codex/*` 引用），启用 `plugins.entries.codex.enabled`，并检查 `plugins.allow` 是否排除了 `codex`。 +**Codex 不会作为普通 `/model` 提供商出现：** 对于新配置，这是预期行为。请选择带有 `agentRuntime.id: "codex"` 的 `openai/gpt-*` 模型（或旧版 `codex/*` 引用），启用 `plugins.entries.codex.enabled`，并检查 `plugins.allow` 是否排除了 `codex`。 -**OpenClaw 使用 PI 而不是 Codex：** 当没有 Codex harness 接管运行时，`agentRuntime.id: "auto"` 仍可使用 PI 作为兼容性后端。测试时，将 `agentRuntime.id: "codex"` 设置为强制选择 Codex。现在，强制 Codex 运行时会失败，而不是回退到 PI，除非你显式设置 `agentRuntime.fallback: "pi"`。一旦选中 Codex app-server，其失败会直接暴露，无需额外的回退配置。 +**OpenClaw 使用 PI 而不是 Codex：** 当没有 Codex harness 接管运行时，`agentRuntime.id: "auto"` 仍然可以使用 PI 作为兼容性后端。测试时请将 `agentRuntime.id: "codex"` 设置为强制选择 Codex。现在，强制的 Codex 运行时会失败，而不是回退到 PI，除非你显式设置 `agentRuntime.fallback: "pi"`。一旦选择了 Codex app-server，它的失败会直接暴露出来，而不需要额外的回退配置。 -**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告版本为 `0.125.0` 或更高。同版本预发布版或带构建后缀的版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，会被拒绝，因为 OpenClaw 测试的是稳定版 `0.125.0` 协议下限。 +**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告版本 `0.125.0` 或更高版本。相同版本的预发布版本或带构建后缀的版本（例如 `0.125.0-alpha.2` 或 `0.125.0+custom`）会被拒绝，因为 OpenClaw 测试的是稳定版 `0.125.0` 协议下限。 -**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`，或禁用发现。 +**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`，或禁用设备发现。 -**WebSocket 传输协议立即失败：** 检查 `appServer.url`、`authToken`，以及远程 app-server 是否使用相同的 Codex app-server 协议版本。 +**WebSocket 传输协议立即失败：** 检查 `appServer.url`、`authToken`，并确认远程 app-server 使用相同的 Codex app-server 协议版本。 -**非 Codex 模型使用 PI：** 这是预期行为，除非你为该智能体强制设置了 `agentRuntime.id: "codex"`，或选择了旧版 `codex/*` 引用。普通 `openai/gpt-*` 和其他提供商引用在 `auto` 模式下会保留在其正常提供商路径上。如果你强制设置 `agentRuntime.id: "codex"`，则该智能体的每个嵌入式轮次都必须是 Codex 支持的 OpenAI 模型。 +**非 Codex 模型使用 PI：** 除非你为该智能体强制设置了 `agentRuntime.id: "codex"`，或选择了旧版 `codex/*` 引用，否则这是预期行为。普通 `openai/gpt-*` 和其他提供商引用在 `auto` 模式下会保留在其正常提供商路径上。如果你强制设置 `agentRuntime.id: "codex"`，该智能体的每个嵌入式轮次都必须使用 Codex 支持的 OpenAI 模型。 -**Computer Use 已安装但工具未运行：** 从新的会话中检查 `/codex computer-use status`。如果某个工具报告 `Native hook relay unavailable`，请使用 `/new` 或 `/reset`；如果问题持续存在，请重启 Gateway 网关以清除过期的原生钩子注册。如果 `computer-use.list_apps` 超时，请重启 Codex Computer Use 或 Codex Desktop，然后重试。 +**Computer Use 已安装但工具不运行：** 在新的会话中检查 `/codex computer-use status`。如果某个工具报告 `Native hook relay unavailable`，请使用 `/new` 或 `/reset`；如果问题持续存在，请重启 Gateway 网关以清除过期的原生钩子注册。如果 `computer-use.list_apps` 超时，请重启 Codex Computer Use 或 Codex Desktop，然后重试。 ## 相关内容