diff --git a/docs/zh-CN/automation/hooks.md b/docs/zh-CN/automation/hooks.md index 01a9dc575..834bd82aa 100644 --- a/docs/zh-CN/automation/hooks.md +++ b/docs/zh-CN/automation/hooks.md @@ -1,60 +1,60 @@ --- read_when: - - 你希望为 `/new`、`/reset`、`/stop` 和智能体生命周期事件提供事件驱动自动化。 - - 你希望构建、安装或调试 hooks。 + - 你希望为 `/new`、`/reset`、`/stop` 以及智能体生命周期事件提供事件驱动自动化功能 + - 你希望构建、安装或调试 hooks summary: Hooks：用于命令和生命周期事件的事件驱动自动化 title: Hooks x-i18n: - generated_at: "2026-04-24T03:06:51Z" + generated_at: "2026-04-24T07:31:18Z" model: gpt-5.4 provider: openai - source_hash: 9e24d5a95748151059e34f8c9ff9910dbcd7a32e7cadb44d1fa25352ef3a09a6 + source_hash: 4e6246f25272208d9a9ff2f186bcd3a463c78ea24b833f0259174d0f7f0cbea6 source_path: automation/hooks.md workflow: 15 --- -Hooks 是在 Gateway 网关内部发生某些事件时运行的小型脚本。它们可以从目录中被发现，并可使用 `openclaw hooks` 进行检查。只有在你启用 hooks，或至少配置了一个 hook 条目、hook pack、旧版处理器或额外 hook 目录后，Gateway 网关才会加载内部 hooks。 +Hooks 是在 Gateway 网关内部发生某些事件时运行的小型脚本。它们可以从目录中被发现，并可通过 `openclaw hooks` 进行检查。只有在你启用 hooks，或至少配置了一个 hook 条目、hook pack、旧版处理器或额外 hook 目录后，Gateway 网关才会加载内部 hooks。 -OpenClaw 中有两种 hooks： +OpenClaw 中有两类 hooks： -- **内部 hooks**（本页）：当智能体事件触发时在 Gateway 网关内部运行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。 -- **Webhooks**：外部 HTTP 端点，允许其他系统在 OpenClaw 中触发任务。参见 [Webhooks](/zh-CN/automation/cron-jobs#webhooks)。 +- **内部 hooks**（本页）：当智能体事件触发时，在 Gateway 网关内部运行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。 +- **Webhooks**：外部 HTTP 端点，允许其他系统在 OpenClaw 中触发工作流。参见 [Webhooks](/zh-CN/automation/cron-jobs#webhooks)。 -Hooks 也可以打包在插件中。`openclaw hooks list` 会显示独立 hooks 和由插件管理的 hooks。 +Hooks 也可以打包在插件中。`openclaw hooks list` 会同时显示独立 hooks 和由插件管理的 hooks。 ## 快速开始 ```bash -# List available hooks +# 列出可用 hooks openclaw hooks list -# Enable a hook +# 启用一个 hook openclaw hooks enable session-memory -# Check hook status +# 检查 hook 状态 openclaw hooks check -# Get detailed information +# 获取详细信息 openclaw hooks info session-memory ``` ## 事件类型 -| Event | 触发时机 | +| 事件 | 触发时机 | | ------------------------ | ------------------------------------------------ | -| `command:new` | 发出 `/new` 命令时 | -| `command:reset` | 发出 `/reset` 命令时 | -| `command:stop` | 发出 `/stop` 命令时 | -| `command` | 任意命令事件（通用监听器） | -| `session:compact:before` | 压缩总结历史记录之前 | -| `session:compact:after` | 压缩完成之后 | -| `session:patch` | 修改会话属性时 | -| `agent:bootstrap` | 注入工作区 bootstrap 文件之前 | -| `gateway:startup` | 渠道启动并加载 hooks 后 | -| `message:received` | 来自任意渠道的入站消息 | -| `message:transcribed` | 音频转录完成后 | -| `message:preprocessed` | 所有媒体和链接理解完成后 | -| `message:sent` | 出站消息已送达 | +| `command:new` | 发出 `/new` 命令时 | +| `command:reset` | 发出 `/reset` 命令时 | +| `command:stop` | 发出 `/stop` 命令时 | +| `command` | 任意命令事件（通用监听器） | +| `session:compact:before` | 在压缩汇总历史记录之前 | +| `session:compact:after` | 压缩完成之后 | +| `session:patch` | 修改会话属性时 | +| `agent:bootstrap` | 注入工作区 bootstrap 文件之前 | +| `gateway:startup` | 渠道启动并加载 hooks 之后 | +| `message:received` | 从任意渠道接收到入站消息时 | +| `message:transcribed` | 音频转写完成后 | +| `message:preprocessed` | 所有媒体和链接理解完成后 | +| `message:sent` | 出站消息已送达时 | ## 编写 hooks @@ -62,40 +62,40 @@ openclaw hooks info session-memory 每个 hook 都是一个包含两个文件的目录： -```text +``` my-hook/ -├── HOOK.md # Metadata + documentation -└── handler.ts # Handler implementation +├── HOOK.md # 元数据 + 文档 +└── handler.ts # 处理器实现 ``` -### HOOK.md 格式 +### `HOOK.md` 格式 ```markdown --- name: my-hook -description: "Short description of what this hook does" +description: "这个 hook 的简短说明" metadata: { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } --- -# My Hook +# 我的 Hook -Detailed documentation goes here. +此处填写详细文档。 ``` -**Metadata 字段**（`metadata.openclaw`）： +**元数据字段**（`metadata.openclaw`）： -| Field | 说明 | +| 字段 | 说明 | | ---------- | ---------------------------------------------------- | -| `emoji` | 用于 CLI 显示的表情符号 | -| `events` | 要监听的事件数组 | -| `export` | 要使用的具名导出（默认为 `"default"`） | -| `os` | 所需平台（例如 `["darwin", "linux"]`） | -| `requires` | 必需的 `bins`、`anyBins`、`env` 或 `config` 路径 | -| `always` | 绕过资格检查（布尔值） | -| `install` | 安装方式 | +| `emoji` | CLI 中显示的 emoji | +| `events` | 要监听的事件数组 | +| `export` | 要使用的具名导出（默认为 `"default"`） | +| `os` | 所需平台（例如 `["darwin", "linux"]`） | +| `requires` | 所需的 `bins`、`anyBins`、`env` 或 `config` 路径 | +| `always` | 跳过资格检查（布尔值） | +| `install` | 安装方式 | -### Handler 实现 +### 处理器实现 ```typescript const handler = async (event) => { @@ -113,7 +113,7 @@ const handler = async (event) => { export default handler; ``` -每个事件都包含：`type`、`action`、`sessionKey`、`timestamp`、`messages`（可 push 以向用户发送消息）以及 `context`（事件特定数据）。 +每个事件都包含：`type`、`action`、`sessionKey`、`timestamp`、`messages`（可 `push` 以向用户发送消息）以及 `context`（事件特定数据）。智能体和工具插件 hook 的上下文还可以包含 `trace`，这是一个只读、兼容 W3C 的诊断追踪上下文，插件可以将其传入结构化日志中，以便进行 OTEL 关联。 ### 事件上下文要点 @@ -131,20 +131,20 @@ export default handler; **会话 patch 事件**（`session:patch`）：`context.sessionEntry`、`context.patch`（仅包含变更字段）、`context.cfg`。只有特权客户端可以触发 patch 事件。 -**压缩事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 还会增加 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。 +**压缩事件**：`session:compact:before` 包含 `messageCount`、`tokenCount`。`session:compact:after` 额外包含 `compactedCount`、`summaryLength`、`tokensBefore`、`tokensAfter`。 -## Hook 发现 +## Hook 发现机制 -Hooks 会按以下目录进行发现，覆盖优先级依次递增： +Hooks 会从以下目录中发现，覆盖优先级按从低到高排序： -1. **内置 hooks**：随 OpenClaw 一起提供 +1. **内置 hooks**：随 OpenClaw 一起发布 2. **插件 hooks**：打包在已安装插件中的 hooks -3. **托管 hooks**：`~/.openclaw/hooks/`（用户安装，在各工作区间共享）。来自 `hooks.internal.load.extraDirs` 的额外目录也具有相同优先级。 -4. **工作区 hooks**：`/hooks/`（按智能体划分，默认禁用，直到显式启用） +3. **受管 hooks**：`~/.openclaw/hooks/`（用户安装，在各工作区间共享）。来自 `hooks.internal.load.extraDirs` 的额外目录与此具有相同优先级。 +4. **工作区 hooks**：`/hooks/`（每个智能体单独使用，默认禁用，需显式启用） -工作区 hooks 可以添加新的 hook 名称，但不能覆盖同名的内置、托管或插件提供的 hooks。 +工作区 hooks 可以新增新的 hook 名称，但不能覆盖同名的内置、受管或插件提供的 hooks。 -在配置内部 hooks 之前，Gateway 网关会在启动时跳过内部 hook 发现。你可以通过 `openclaw hooks enable ` 启用某个内置或托管 hook，安装 hook pack，或设置 `hooks.internal.enabled=true` 来选择启用。当你启用一个具名 hook 时，Gateway 网关只会加载该 hook 的 handler；而 `hooks.internal.enabled=true`、额外 hook 目录和旧版处理器会启用广泛发现。 +在启动时，除非已配置内部 hooks，否则 Gateway 网关会跳过内部 hook 发现。你可以通过 `openclaw hooks enable ` 启用一个内置或受管 hook、安装一个 hook pack，或设置 `hooks.internal.enabled=true` 来选择启用。当你启用一个具名 hook 时，Gateway 网关只会加载该 hook 的处理器；而 `hooks.internal.enabled=true`、额外 hook 目录和旧版处理器则会启用广泛发现。 ### Hook packs @@ -154,16 +154,16 @@ Hook packs 是通过 `package.json` 中的 `openclaw.hooks` 导出 hooks 的 npm openclaw plugins install ``` -Npm 规格仅支持 registry 形式（包名 + 可选的精确版本或 dist-tag）。Git/URL/文件规格和 semver 范围都不受支持。 +npm spec 仅支持 registry 形式（包名 + 可选的精确版本或 dist-tag）。Git/URL/file 形式的 spec 和 semver 范围都会被拒绝。 ## 内置 hooks -| Hook | Events | 作用 | +| Hook | 事件 | 功能 | | --------------------- | ------------------------------ | ----------------------------------------------------- | -| session-memory | `command:new`, `command:reset` | 将会话上下文保存到 `/memory/` | -| bootstrap-extra-files | `agent:bootstrap` | 从 glob 模式注入额外的 bootstrap 文件 | -| command-logger | `command` | 将所有命令记录到 `~/.openclaw/logs/commands.log` | -| boot-md | `gateway:startup` | 在 gateway 启动时运行 `BOOT.md` | +| session-memory | `command:new`, `command:reset` | 将会话上下文保存到 `/memory/` | +| bootstrap-extra-files | `agent:bootstrap` | 从 glob 模式中注入额外的 bootstrap 文件 | +| command-logger | `command` | 将所有命令记录到 `~/.openclaw/logs/commands.log` | +| boot-md | `gateway:startup` | 在 gateway 启动时运行 `BOOT.md` | 启用任意内置 hook： @@ -175,7 +175,7 @@ openclaw hooks enable ### session-memory 详情 -提取最近 15 条用户/助手消息，通过 LLM 生成描述性文件名 slug，并保存到 `/memory/YYYY-MM-DD-slug.md`。要求已配置 `workspace.dir`。 +提取最近 15 条用户/助手消息，通过 LLM 生成一个描述性文件名 slug，并保存到 `/memory/YYYY-MM-DD-slug.md`。要求已配置 `workspace.dir`。 @@ -196,7 +196,7 @@ openclaw hooks enable } ``` -路径相对于工作区解析。仅会加载已识别的 bootstrap 基础文件名（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。 +路径相对于工作区解析。只会加载已识别的 bootstrap 基础文件名（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`、`MEMORY.md`）。 @@ -208,13 +208,13 @@ openclaw hooks enable ### boot-md 详情 -在 gateway 启动时，从当前活动工作区运行 `BOOT.md`。 +在 gateway 启动时，从当前工作区运行 `BOOT.md`。 ## 插件 hooks -插件可以通过插件 SDK 注册 hooks，以实现更深度的集成：拦截工具调用、修改提示词、控制消息流等。插件 SDK 暴露了 28 个 hooks，覆盖模型解析、智能体生命周期、消息流、工具执行、子智能体协调以及 gateway 生命周期。 +插件可以通过插件 SDK 注册 hooks，以实现更深入的集成：拦截工具调用、修改提示词、控制消息流等等。插件 SDK 暴露了 28 个 hooks，覆盖模型解析、智能体生命周期、消息流、工具执行、子智能体协作和 gateway 生命周期。 -有关完整的插件 hook 参考，包括 `before_tool_call`、`before_agent_reply`、`before_install` 以及所有其他插件 hooks，请参见 [Plugin Architecture](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 +完整的插件 hook 参考，包括 `before_tool_call`、`before_agent_reply`、`before_install` 以及所有其他插件 hooks，请参见 [Plugin Architecture](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 ## 配置 @@ -264,43 +264,43 @@ openclaw hooks enable ``` -旧版的 `hooks.internal.handlers` 数组配置格式仍然受支持，以保持向后兼容，但新的 hooks 应使用基于发现的系统。 +旧版 `hooks.internal.handlers` 数组配置格式仍然受支持，以保持向后兼容，但新的 hooks 应使用基于发现的系统。 ## CLI 参考 ```bash -# List all hooks (add --eligible, --verbose, or --json) +# 列出所有 hooks（可添加 --eligible、--verbose 或 --json） openclaw hooks list -# Show detailed info about a hook +# 显示某个 hook 的详细信息 openclaw hooks info -# Show eligibility summary +# 显示资格摘要 openclaw hooks check -# Enable/disable +# 启用/禁用 openclaw hooks enable openclaw hooks disable ``` ## 最佳实践 -- **让 handlers 保持快速。** Hooks 会在命令处理期间运行。对于较重的任务，使用 `void processInBackground(event)` 以即发即弃方式处理。 -- **优雅地处理错误。** 用 try/catch 包装有风险的操作；不要抛出异常，以便其他 handlers 可以继续运行。 -- **尽早过滤事件。** 如果事件类型/操作无关，立即返回。 -- **使用具体事件键。** 优先使用 `"events": ["command:new"]`，而不是 `"events": ["command"]`，以减少开销。 +- **保持处理器快速。** Hooks 会在命令处理期间运行。对于较重的工作，可使用 `void processInBackground(event)` 以即发即弃方式处理。 +- **优雅地处理错误。** 用 try/catch 包裹高风险操作；不要抛出异常，以便其他处理器仍可继续运行。 +- **尽早过滤事件。** 如果事件类型/动作不相关，立即返回。 +- **使用具体事件键。** 优先使用 `"events": ["command:new"]` 而不是 `"events": ["command"]`，以减少开销。 ## 故障排除 ### Hook 未被发现 ```bash -# Verify directory structure +# 验证目录结构 ls -la ~/.openclaw/hooks/my-hook/ -# Should show: HOOK.md, handler.ts +# 应显示：HOOK.md, handler.ts -# List all discovered hooks +# 列出所有已发现的 hooks openclaw hooks list ``` @@ -320,7 +320,7 @@ openclaw hooks info my-hook ## 相关内容 -- [CLI 参考：hooks](/zh-CN/cli/hooks) +- [CLI Reference: hooks](/zh-CN/cli/hooks) - [Webhooks](/zh-CN/automation/cron-jobs#webhooks) - [Plugin Architecture](/zh-CN/plugins/architecture-internals#provider-runtime-hooks) — 完整插件 hook 参考 -- [配置](/zh-CN/gateway/configuration-reference#hooks) +- [Configuration](/zh-CN/gateway/configuration-reference#hooks) diff --git a/docs/zh-CN/plugins/codex-harness.md b/docs/zh-CN/plugins/codex-harness.md index efcb25959..b5e2fc9ba 100644 --- a/docs/zh-CN/plugins/codex-harness.md +++ b/docs/zh-CN/plugins/codex-harness.md @@ -2,80 +2,68 @@ read_when: - 你想使用内置的 Codex app-server harness - 你需要 Codex 模型引用和配置示例 - - 你想为仅 Codex 的部署禁用 Pi 回退 + - 你想为仅使用 Codex 的部署禁用 Pi 回退机制 summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次 title: Codex harness x-i18n: - generated_at: "2026-04-24T04:06:19Z" + generated_at: "2026-04-24T07:31:18Z" model: gpt-5.4 provider: openai - source_hash: 095933d2c32df302c312c67fdc266d2f01b552dddb1607d6e4ecc4f3c3326acf + source_hash: c02b1e6cbaaefee858db7ebd7e306261683278ed9375bca6fe74855ca84eabd8 source_path: plugins/codex-harness.md workflow: 15 --- -内置的 `codex` 插件允许 OpenClaw 通过 Codex app-server 运行嵌入式智能体轮次，而不是使用内置的 Pi harness。 +内置的 `codex` 插件让 OpenClaw 可以通过 Codex app-server，而不是内置的 Pi harness，来运行嵌入式智能体轮次。 -当你希望由 Codex 接管底层智能体会话时，请使用此方式：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体投递，以及可见的转录镜像。 +当你希望由 Codex 接管底层智能体会话时，可使用此方式：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。 -原生 Codex 轮次会保留 OpenClaw 插件 hook 作为公开兼容层。 -这些是进程内的 OpenClaw hook，而不是 Codex `hooks.json` 命令 hook： +原生 Codex 轮次会将 OpenClaw 插件 hooks 保持为公共兼容层。这些是进程内的 OpenClaw hooks，而不是 Codex `hooks.json` 命令 hooks： - `before_prompt_build` -- `before_compaction`, `after_compaction` -- `llm_input`, `llm_output` +- `before_compaction`、`after_compaction` +- `llm_input`、`llm_output` - `after_tool_call` - 用于镜像转录记录的 `before_message_write` - `agent_end` -内置插件还可以注册一个 Codex app-server 扩展工厂，以添加异步 `tool_result` 中间件。该中间件运行在 OpenClaw 动态工具之后：即 OpenClaw 执行完工具之后、结果返回给 Codex 之前。它与公开的 `tool_result_persist` 插件 hook 是分离的；后者会转换由 OpenClaw 拥有的转录工具结果写入。 +内置插件还可以注册一个 Codex app-server 扩展工厂，以添加异步 `tool_result` 中间件。该中间件会在 OpenClaw 执行工具之后、将结果返回给 Codex 之前，对 OpenClaw 动态工具生效。它独立于公共的 `tool_result_persist` 插件 hook；后者用于转换由 OpenClaw 负责写入转录的工具结果。 -该 harness 默认关闭。新配置应保持 OpenAI 模型引用的规范形式为 `openai/gpt-*`，并在希望使用原生 app-server 执行时显式强制设置 -`embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。为兼容性考虑，旧版 `codex/*` 模型引用仍会自动选择该 harness。 +该 harness 默认关闭。新配置应将 OpenAI 模型引用保持为规范形式 `openai/gpt-*`，并在希望使用原生 app-server 执行时，显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。出于兼容性考虑，旧版 `codex/*` 模型引用仍会自动选择该 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/*`： -| Model ref | Runtime path | Use when | +| 模型引用 | 运行时路径 | 使用场景 | | ----------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | 通过 OpenClaw/Pi 管线的 OpenAI 提供商 | 你希望使用带有 `OPENAI_API_KEY` 的当前直接 OpenAI Platform API 访问。 | -| `openai-codex/gpt-5.5` | 通过 OpenClaw/Pi 的 OpenAI Codex OAuth | 你希望使用带默认 Pi 运行器的 ChatGPT/Codex 订阅认证。 | -| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | 你希望为嵌入式智能体轮次使用原生 Codex app-server 执行。 | +| `openai/gpt-5.4` | 通过 OpenClaw/Pi plumbing 的 OpenAI 提供商 | 你希望使用 `OPENAI_API_KEY` 访问当前直接可用的 OpenAI Platform API。 | +| `openai-codex/gpt-5.5` | 通过 OpenClaw/Pi 的 OpenAI Codex OAuth | 你希望使用默认 Pi runner 搭配 ChatGPT/Codex 订阅认证。 | +| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | 你希望对嵌入式智能体轮次使用原生 Codex app-server 执行。 | -在 OpenClaw 中，GPT-5.5 当前仅支持订阅/OAuth。对于 Pi OAuth，请使用 -`openai-codex/gpt-5.5`；对于 Codex app-server harness，请使用 `openai/gpt-5.5`。 -一旦 OpenAI 在公共 API 上启用 GPT-5.5，就会支持对 `openai/gpt-5.5` 的直接 API key 访问。 +目前，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 访问。 -旧版 `codex/gpt-*` 引用仍然接受，并作为兼容别名。新的 Pi Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server harness 配置应使用 `openai/gpt-*` 加上 `embeddedHarness.runtime: -"codex"`。 +旧版 `codex/gpt-*` 引用仍可作为兼容别名继续使用。新的 Pi Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server harness 配置应使用 `openai/gpt-*`，并加上 `embeddedHarness.runtime: "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` 模式下每个插件候选项的支持结果。 -Harness 选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会在该会话上记录所选 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来会话使用另一个 harness 时，请更改 `embeddedHarness` 配置或 -`OPENCLAW_AGENT_RUNTIME`；在已有对话在 Pi 和 Codex 之间切换前，请使用 `/new` 或 `/reset` 启动新会话。这样可以避免将同一份转录内容通过两个不兼容的原生会话系统重放。 +Harness 选择不是一个实时会话控制项。当嵌入式轮次运行时，OpenClaw 会在该会话上记录所选 harness id，并在同一 session id 的后续轮次中继续使用它。当你希望未来的会话使用其他 harness 时，请修改 `embeddedHarness` 配置或 `OPENCLAW_AGENT_RUNTIME`；在将现有对话从 Pi 切换到 Codex 之前，请使用 `/new` 或 `/reset` 启动一个新会话。这样可以避免将同一份转录通过两个不兼容的原生会话系统重放。 -在引入 harness 固定机制之前创建的旧会话，一旦拥有转录历史，就会被视为固定到 Pi。更改配置后，请使用 `/new` 或 `/reset` 将该对话切换到 Codex。 +在引入 harness 固定机制之前创建的旧会话，一旦已有转录历史，就会被视为固定到 Pi。更改配置后，使用 `/new` 或 `/reset` 可让该对话改为使用 Codex。 -`/status` 会在 `Fast` 旁显示实际生效的非 Pi harness，例如 -`Fast · codex`。默认的 Pi harness 仍显示为 `Runner: pi (embedded)`，不会额外添加单独的 harness 徽标。 +`/status` 会在 `Fast` 旁边显示实际生效的非 Pi harness，例如 `Fast · codex`。默认的 Pi harness 仍显示为 `Runner: pi (embedded)`，不会额外添加单独的 harness 标记。 ## 要求 - OpenClaw，且内置 `codex` 插件可用。 - Codex app-server `0.118.0` 或更高版本。 -- app-server 进程可用的 Codex auth。 +- app-server 进程可用的 Codex 认证信息。 -该插件会阻止旧版或无版本的 app-server 握手。这可确保 -OpenClaw 使用它已经测试过的协议能力。 +该插件会阻止较旧版本或未带版本信息的 app-server 握手。这可确保 OpenClaw 始终运行在它已测试过的协议表面上。 -对于 live 和 Docker 冒烟测试，auth 通常来自 `OPENAI_API_KEY`，再加上可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 -`~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的 auth 材料。 +对于 live 和 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的认证材料。 ## 最小配置 @@ -102,7 +90,7 @@ OpenClaw 使用它已经测试过的协议能力。 } ``` -如果你的配置使用 `plugins.allow`，也请在其中包含 `codex`： +如果你的配置使用了 `plugins.allow`，也要将 `codex` 包含进去： ```json5 { @@ -117,12 +105,11 @@ OpenClaw 使用它已经测试过的协议能力。 } ``` -仍将 `agents.defaults.model` 或某个智能体模型设置为 -`codex/` 的旧版配置，依然会自动启用内置 `codex` 插件。新配置应优先使用 `openai/` 加上上面的显式 `embeddedHarness` 条目。 +如果旧版配置将 `agents.defaults.model` 或某个智能体模型设置为 `codex/`，仍会自动启用内置 `codex` 插件。新配置应优先使用 `openai/`，并搭配上面显式的 `embeddedHarness` 配置项。 ## 在不替换其他模型的情况下添加 Codex -如果你希望旧版 `codex/*` 引用选择 Codex，而其他所有情况都使用 Pi，请保持 `runtime: "auto"`。对于新配置，优先在应使用该 harness 的智能体上显式设置 `runtime: "codex"`。 +当你希望旧版 `codex/*` 引用选择 Codex，而其他所有内容继续使用 Pi 时，请保持 `runtime: "auto"`。对于新配置，建议在应使用该 harness 的智能体上显式设置 `runtime: "codex"`。 ```json5 { @@ -152,13 +139,13 @@ OpenClaw 使用它已经测试过的协议能力。 } ``` -采用这种形式时： +在这种结构下： -- `/model gpt` 或 `/model openai/gpt-5.5` 会在此配置中使用 Codex app-server harness。 +- `/model gpt` 或 `/model openai/gpt-5.5` 会为此配置使用 Codex app-server harness。 - `/model opus` 会使用 Anthropic 提供商路径。 -- 如果选择的是非 Codex 模型，Pi 仍然是兼容性 harness。 +- 如果选择了非 Codex 模型，Pi 仍然是兼容性 harness。 -## 仅 Codex 的部署 +## 仅使用 Codex 的部署 当你需要证明每个嵌入式智能体轮次都使用 Codex harness 时，请禁用 Pi 回退： @@ -184,12 +171,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -禁用回退后，如果 Codex 插件被禁用、app-server 版本过旧，或者 -app-server 无法启动，OpenClaw 会尽早失败。 +禁用回退后，如果 Codex 插件被禁用、app-server 版本过旧，或者 app-server 无法启动，OpenClaw 会尽早失败。 -## 按智能体使用 Codex +## 按智能体配置 Codex -你可以让某一个智能体仅使用 Codex，而默认智能体保持正常的自动选择： +你可以让某一个智能体仅使用 Codex，而默认智能体仍保持正常的自动选择： ```json5 { @@ -220,13 +206,11 @@ app-server 无法启动，OpenClaw 会尽早失败。 } ``` -使用常规会话命令切换智能体和模型。`/new` 会创建一个新的 -OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其 sidecar app-server -线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一轮根据当前配置重新解析 harness。 +使用正常的会话命令切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一轮重新根据当前配置解析 harness。 ## 模型发现 -默认情况下，Codex 插件会请求 app-server 提供可用模型。如果发现失败或超时，它会使用一个内置回退目录，其中包括： +默认情况下，`codex` 插件会向 app-server 查询可用模型。如果发现失败或超时，它会使用一个内置的回退目录，包含： - GPT-5.5 - GPT-5.4 mini @@ -252,7 +236,7 @@ OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其 sidecar ap } ``` -当你希望启动时避免探测 Codex，并固定使用回退目录时，请禁用发现： +当你希望启动时避免探测 Codex，并固定使用回退目录时，可禁用发现： ```json5 { @@ -273,18 +257,15 @@ OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其 sidecar ap ## App-server 连接和策略 -默认情况下，插件会通过以下方式在本地启动 Codex： +默认情况下，插件会在本地通过以下命令启动 Codex： ```bash codex app-server --listen stdio:// ``` -默认情况下，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: -"guardian"`： +如果要启用由 Codex guardian 审核的审批，请设置 `appServer.mode: "guardian"`： ```json5 { @@ -304,9 +285,9 @@ codex app-server --listen stdio:// } ``` -Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工作区外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给审核子智能体，而不是向人类发出提示。审核器会应用 Codex 的风险框架，并批准或拒绝该特定请求。如果你希望比 YOLO 模式有更多防护，同时仍需要无人值守的智能体持续推进工作，请使用 Guardian。 +Guardian 是原生 Codex 审批审查器。当 Codex 请求离开沙箱、写入工作区之外的位置，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给一个审查子智能体，而不是向人类发出提示。该审查器会应用 Codex 的风险框架，并批准或拒绝该具体请求。当你希望比 YOLO 模式有更多防护，但仍需要无人值守智能体持续推进时，请使用 Guardian。 -`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"`，以及 `sandbox: "workspace-write"`。单独的策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选择混用。 +`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。各个单独的策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。 对于已在运行的 app-server，请使用 WebSocket 传输： @@ -332,22 +313,22 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 支持的 `appServer` 字段： -| Field | Default | Meaning | +| 字段 | 默认值 | 含义 | | ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | | `command` | `"codex"` | 用于 stdio 传输的可执行文件。 | | `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 | -| `url` | unset | WebSocket app-server URL。 | -| `authToken` | unset | 用于 WebSocket 传输的 Bearer token。 | -| `headers` | `{}` | 额外的 WebSocket 头。 | +| `url` | 未设置 | WebSocket app-server URL。 | +| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 | +| `headers` | `{}` | 额外的 WebSocket headers。 | | `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | -| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 | +| `mode` | `"yolo"` | 用于 YOLO 或 guardian 审核执行的预设。 | | `approvalPolicy` | `"never"` | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。 | | `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 Codex 沙箱模式。 | | `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 让 Codex Guardian 审核提示。 | -| `serviceTier` | unset | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 | +| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 | -较旧的环境变量在对应配置字段未设置时，仍可作为本地测试的回退方式： +当对应的配置字段未设置时，旧的环境变量仍可作为本地测试的回退方案使用： - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -355,9 +336,7 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`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 设置保存在同一个经过审查的文件中。 ## 常见配方 @@ -375,7 +354,7 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 } ``` -禁用 Pi 回退的仅 Codex harness 验证： +仅使用 Codex 的 harness 验证，禁用 Pi 回退： ```json5 { @@ -392,7 +371,7 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 } ``` -使用 Guardian 审核的 Codex 审批： +由 Guardian 审核的 Codex 审批： ```json5 { @@ -414,7 +393,7 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 } ``` -带显式头的远程 app-server： +带显式 headers 的远程 app-server： ```json5 { @@ -437,88 +416,77 @@ Guardian 是原生 Codex 审批审核器。当 Codex 请求离开沙箱、在工 } ``` -模型切换仍由 OpenClaw 控制。当某个 OpenClaw 会话附加到现有 Codex 线程时，下一轮会再次向 app-server 发送当前选定的 -OpenAI 模型、提供商、审批策略、沙箱和服务层级。从 `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 status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和 skills。 - `/codex models` 列出实时 Codex app-server 模型。 - `/codex threads [filter]` 列出最近的 Codex 线程。 -- `/codex resume ` 将当前 OpenClaw 会话附加到现有 Codex 线程。 +- `/codex resume ` 将当前 OpenClaw 会话附加到一个现有的 Codex 线程。 - `/codex compact` 请求 Codex app-server 压缩已附加的线程。 -- `/codex review` 启动已附加线程的 Codex 原生审查。 -- `/codex account` 显示账号和速率限制状态。 +- `/codex review` 对已附加的线程启动 Codex 原生审查。 +- `/codex account` 显示账户和速率限制状态。 - `/codex mcp` 列出 Codex app-server MCP 服务器状态。 -- `/codex skills` 列出 Codex app-server Skills。 +- `/codex skills` 列出 Codex app-server skills。 -`/codex resume` 会写入与 harness 正常轮次使用的同一个 sidecar 绑定文件。在下一条消息到来时，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw 模型传入 app-server，并保持扩展历史启用。 +`/codex resume` 会写入与 harness 正常轮次相同的 sidecar 绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw 模型传入 app-server，并保持启用扩展历史记录。 -该命令能力要求 Codex app-server `0.118.0` 或更高版本。如果未来或自定义 app-server 未暴露某个 JSON-RPC 方法，则单个控制方法会报告为 `unsupported by this Codex app-server`。 +该命令面要求 Codex app-server `0.118.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，则相应的控制方法会显示为 `unsupported by this Codex app-server`。 ## Hook 边界 Codex harness 有三层 hook： -| Layer | Owner | Purpose | +| 层级 | 所有者 | 目的 | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| OpenClaw 插件 hook | OpenClaw | 在 Pi 和 Codex harness 之间提供产品/插件兼容性。 | -| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 在 OpenClaw 动态工具周围提供逐轮适配器行为。 | -| Codex 原生 hook | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 | +| OpenClaw 插件 hooks | OpenClaw | 在 Pi 和 Codex harness 之间提供产品/插件兼容性。 | +| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的逐轮适配器行为。 | +| Codex 原生 hooks | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 | -OpenClaw 不使用项目级或全局 Codex `hooks.json` 文件来路由 OpenClaw 插件行为。Codex 原生 hook 对于由 Codex 拥有的操作很有用，例如 shell 策略、原生工具结果审查、停止处理，以及原生压缩/模型生命周期，但它们不是 OpenClaw 插件 API。 +OpenClaw 不会使用项目级或全局的 Codex `hooks.json` 文件来路由 OpenClaw 插件行为。Codex 原生 hooks 适用于由 Codex 负责的操作，例如 shell 策略、原生工具结果审查、停止处理，以及原生压缩/模型生命周期，但它们不是 OpenClaw 插件 API。 -对于 OpenClaw 动态工具，Codex 发出调用请求后，OpenClaw 会执行该工具，因此 OpenClaw 会在 harness 适配器中触发它所拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范的工具记录。OpenClaw 可以镜像选定事件，但无法重写原生 Codex 线程，除非 Codex 通过 app-server 或原生 hook 回调暴露该操作。 +对于 OpenClaw 动态工具，Codex 发起调用请求后，OpenClaw 才会执行工具，因此 OpenClaw 会在 harness 适配器中触发它所拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范工具记录。OpenClaw 可以镜像选定事件，但不能重写原生 Codex 线程，除非 Codex 通过 app-server 或原生 hook 回调暴露了该操作。 -当较新的 Codex app-server 构建暴露原生压缩和模型生命周期 hook 事件时，OpenClaw 应按版本门控该协议支持，并在语义真实的前提下，将这些事件映射到现有的 OpenClaw hook 契约中。在此之前，OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 -`llm_output` 事件都只是适配器层面的观察，而不是对 Codex 内部请求或压缩载荷的逐字节捕获。 +当更新版本的 Codex app-server 暴露原生压缩和模型生命周期 hook 事件时，OpenClaw 应对该协议支持进行版本门控，并在语义真实的前提下将这些事件映射到现有的 OpenClaw hook 合约中。在此之前，OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 `llm_output` 事件都只是适配器级观察，而不是对 Codex 内部请求或压缩载荷的逐字节捕获。 + +Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会被投影为 `codex_app_server.hook` 智能体事件，用于轨迹记录和调试。它们不会调用 OpenClaw 插件 hooks。 ## 工具、媒体和压缩 -Codex harness 仅改变底层嵌入式智能体执行器。 +Codex harness 只会改变底层嵌入式智能体执行器。 -OpenClaw 仍然会构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出，仍然通过常规 OpenClaw 投递路径处理。 +OpenClaw 仍会构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出，仍然通过正常的 OpenClaw 传递路径处理。 -当 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`。 +媒体生成不需要 Pi。图像、视频、音乐、PDF、TTS 和媒体理解仍会继续使用对应的提供商/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 ## 故障排除 -**`/model` 中未出现 Codex：** 启用 `plugins.entries.codex.enabled`， -选择 `embeddedHarness.runtime: "codex"` 下的 `openai/gpt-*` 模型（或旧版 `codex/*` 引用），并检查 `plugins.allow` 是否排除了 `codex`。 +**`/model` 中没有显示 Codex：** 启用 `plugins.entries.codex.enabled`，选择一个带有 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-*` 模型（或旧版 `codex/*` 引用），并检查 `plugins.allow` 是否排除了 `codex`。 -**OpenClaw 使用了 Pi 而不是 Codex：** 如果没有 Codex harness 声明该运行， -OpenClaw 可能会使用 Pi 作为兼容性后端。测试时请设置 -`embeddedHarness.runtime: "codex"` 以强制选择 Codex，或设置 -`embeddedHarness.fallback: "none"` 以在没有匹配插件 harness 时直接失败。一旦选中 Codex app-server，其失败会直接暴露出来，而不会再经过额外回退配置。 +**OpenClaw 使用了 Pi 而不是 Codex：** 如果没有 Codex harness 认领此次运行，OpenClaw 可能会使用 Pi 作为兼容后端。测试时请设置 `embeddedHarness.runtime: "codex"` 以强制选择 Codex，或设置 `embeddedHarness.fallback: "none"`，以便在没有匹配的插件 harness 时直接失败。一旦选中了 Codex app-server，它的失败会直接暴露出来，而不需要额外的回退配置。 -**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告版本 -`0.118.0` 或更高。 +**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告的版本为 `0.118.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：** 这是预期行为，除非你强制设置了 -`embeddedHarness.runtime: "codex"`（或选择了旧版 `codex/*` 引用）。普通 -`openai/gpt-*` 和其他提供商引用会继续走其正常提供商路径。 +**某个非 Codex 模型使用了 Pi：** 这是预期行为，除非你强制设置了 `embeddedHarness.runtime: "codex"`（或选择了旧版 `codex/*` 引用）。普通的 `openai/gpt-*` 和其他提供商引用会继续使用它们正常的提供商路径。 ## 相关内容 -- [Agent Harness Plugins](/zh-CN/plugins/sdk-agent-harness) +- [智能体 Harness 插件](/zh-CN/plugins/sdk-agent-harness) - [模型提供商](/zh-CN/concepts/model-providers) - [配置参考](/zh-CN/gateway/configuration-reference) - [测试](/zh-CN/help/testing-live#live-codex-app-server-harness-smoke)