openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-03 04:53:45 +00:00
parent c5a68c2fb6
commit 2ae08c6424
9 changed files with 1364 additions and 1631 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
docs/zh-CN/concepts/agent-runtimes.md
View File

@ -1,53 +1,53 @@
---
read_when:
- 你正在 PI、Codex、ACP 或其他原生智能体运行时之间做选择
- 你对 Status 或配置中的提供商/模型/运行时标签感到困惑
- 你正在记录原生运行框架的支持对等性
summary: OpenClaw 如何分离模型提供商、模型、渠道和 Agent Runtimes
- 你正在 PI、Codex、ACP 或其他原生智能体运行时之间进行选择
- 你对状态或配置中的提供商/模型/运行时标签感到困惑
- 你正在记录原生运行框架的支持对等情况
summary: OpenClaw 如何区分模型提供商、模型、渠道和 Agent Runtimes
title: Agent Runtimes
x-i18n:
generated_at: "2026-05-02T02:37:23Z"
generated_at: "2026-05-03T04:51:01Z"
model: gpt-5.5
provider: openai
source_hash: bae2dd55491e5411983da942b2bdc4868d3b2cb5a4eb5d94fbb5a779dc4d679a
source_hash: 6cd0e0e8508f88c04db63ebcbbca61d9a023ee661f59ea1ed7a1341b357088c7
source_path: concepts/agent-runtimes.md
workflow: 16
---
**智能体运行时**是拥有一个已准备好模型循环的组件：它接收提示词、驱动模型输出、处理原生工具调用，并将完成的轮次返回给 OpenClaw。
**智能体运行时**是拥有一个已准备好模型循环的组件：它接收提示词，驱动模型输出，处理原生工具调用，并将完成后的回合返回给 OpenClaw。
运行时很容易和提供商混淆，因为二者都会出现在模型配置附近。它们是不同的层：
运行时很容易和提供商混淆，因为两者都会出现在模型配置附近。它们是不同的层：
| 层级 | 示例 | 含义 |
| 层级 | 示例 | 含义 |
| ------------- | ------------------------------------- | ------------------------------------------------------------------- |
| 提供商 | `openai`, `anthropic`, `openai-codex` | OpenClaw 如何进行身份验证、发现模型，以及命名模型引用。 |
| 模型 | `gpt-5.5`, `claude-opus-4-6` | 为智能体轮次选择的模型。 |
| 智能体运行时 | `pi`, `codex`, `claude-cli` | 执行已准备好轮次的底层循环或后端。 |
| 渠道 | Telegram, Discord, Slack, WhatsApp | 消息进入和离开 OpenClaw 的位置。 |
| 提供商 | `openai`, `anthropic`, `openai-codex` | OpenClaw 如何认证、发现模型并命名模型引用。 |
| 模型 | `gpt-5.5`, `claude-opus-4-6` | 为智能体回合选择的模型。 |
| 智能体运行时 | `pi`, `codex`, `claude-cli` | 执行已准备回合的底层循环或后端。 |
| 渠道 | Telegram, Discord, Slack, WhatsApp | 消息进入和离开 OpenClaw 的位置。 |
你还会在代码中看到 **harness** 这个词。harness 是提供智能体运行时的实现。例如，内置的 Codex harness 实现了 `codex` 运行时。公共配置使用 `agentRuntime.id`；`openclaw
doctor --fix` 会把较旧的运行时策略键重写为这种形状。
doctor --fix` 会把较旧的运行时策略键重写为这种结构。
运行时分为两个系列：
有两个运行时家族：
- **嵌入式 harness** 在 OpenClaw 已准备好的 Agent loop 内运行。目前这包括内置的 `pi` 运行时，以及已注册的插件 harness，例如 `codex`。
- **CLI 后端** 会运行本地 CLI 进程，同时保持模型引用规范化。例如，`anthropic/claude-opus-4-7` 配合 `agentRuntime.id: "claude-cli"` 表示“选择 Anthropic 模型，通过 Claude CLI 执行”。`claude-cli` 不是嵌入式 harness id，不能传给 AgentHarness 选择逻辑。
- **嵌入式 harness** 在 OpenClaw 准备好的智能体循环内运行。目前这包括内置的 `pi` 运行时，以及注册的插件 harness，例如 `codex`。
- **CLI 后端** 运行本地 CLI 进程，同时保持模型引用为规范形式。例如，`anthropic/claude-opus-4-7` 配合 `agentRuntime.id: "claude-cli"` 表示“选择 Anthropic 模型，通过 Claude CLI 执行”。`claude-cli` 不是嵌入式 harness id，不得传给 AgentHarness 选择逻辑。
## Codex 表面
大多数混淆来自几个不同表面都共享 Codex 名称：
大多数混淆来自多个不同表面共享 Codex 名称：
| 表面 | OpenClaw 名称/配置 | 作用 |
| 表面 | OpenClaw 名称/配置 | 作用 |
| ---------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| 原生 Codex 应用服务器运行时 | `openai/*` plus `agentRuntime.id: "codex"` | 通过 Codex 应用服务器运行嵌入式智能体轮次。这是常见的 ChatGPT/Codex 订阅设置。 |
| Codex OAuth 提供商路由 | `openai-codex/*` model refs | 通过普通 OpenClaw PI runner 使用 ChatGPT/Codex 订阅 OAuth。 |
| Codex ACP 适配器 | `runtime: "acp"`, `agentId: "codex"` | 通过外部 ACP/acpx 控制平面运行 Codex。仅在明确要求 ACP/acpx 时使用。 |
| 原生 Codex 聊天控制命令集 | `/codex ...` | 从聊天中绑定、恢复、Steering、停止和检查 Codex 应用服务器线程。 |
| 面向 GPT/Codex 风格模型的 OpenAI Platform API 路由 | `openai/*` model refs | 使用 OpenAI API key 认证，除非有运行时覆盖，例如 `agentRuntime.id: "codex"` 来运行该轮次。 |
| 原生 Codex app-server 运行时 | `openai/*` 加 `agentRuntime.id: "codex"` | 通过 Codex app-server 运行嵌入式智能体回合。这是常见的 ChatGPT/Codex 订阅设置。 |
| Codex OAuth 提供商路由 | `openai-codex/*` 模型引用 | 通过常规 OpenClaw PI runner 使用 ChatGPT/Codex 订阅 OAuth。 |
| Codex ACP 适配器 | `runtime: "acp"`, `agentId: "codex"` | 通过外部 ACP/acpx 控制平面运行 Codex。仅在明确要求 ACP/acpx 时使用。 |
| 原生 Codex 聊天控制命令集 | `/codex ...` | 从聊天中绑定、恢复、引导、停止并检查 Codex app-server 线程。 |
| 面向 GPT/Codex 风格模型的 OpenAI Platform API 路由 | `openai/*` 模型引用 | 使用 OpenAI API key 认证，除非通过运行时覆盖（例如 `agentRuntime.id: "codex"`）运行该回合。 |
这些表面有意相互独立。启用 `codex` 插件会让原生应用服务器功能可用；它不会把 `openai-codex/*` 重写为 `openai/*`，不会更改现有会话，也不会让 ACP 成为 Codex 默认项。选择 `openai-codex/*` 表示“使用 Codex OAuth 提供商路由”，除非你另行强制指定运行时。
这些表面有意彼此独立。启用 `codex` 插件会让原生 app-server 功能可用；它不会把 `openai-codex/*` 重写为 `openai/*`，不会更改现有会话，也不会让 ACP 成为 Codex 默认项。选择 `openai-codex/*` 表示“使用 Codex OAuth 提供商路由”，除非你另外强制指定运行时。
常见的 ChatGPT/Codex 订阅设置使用 Codex OAuth 进行身份验证，但模型引用保持为 `openai/*`，并选择 `codex` 运行时：
常见的 ChatGPT/Codex 订阅设置使用 Codex OAuth 进行认证，但将模型引用保持为 `openai/*`，并选择 `codex` 运行时：
```json5
{
@ -62,61 +62,60 @@ doctor --fix` 会把较旧的运行时策略键重写为这种形状。
}
```
这表示 OpenClaw 选择一个 OpenAI 模型引用，然后要求 Codex 应用服务器运行时运行嵌入式智能体轮次。它不表示“使用 API 计费”，也不表示渠道、模型提供商目录或 OpenClaw 会话存储会变成 Codex。
这表示 OpenClaw 选择一个 OpenAI 模型引用，然后要求 Codex app-server 运行时运行嵌入式智能体回合。它不表示“使用 API 计费”，也不表示渠道、模型提供商目录或 OpenClaw 会话存储会变成 Codex。
启用内置的 `codex` 插件后，自然语言 Codex 控制应使用原生 `/codex` 命令表面（`/codex bind`、`/codex threads`、`/codex resume`、`/codex steer`、`/codex stop`），而不是 ACP。只有当用户明确要求 ACP/acpx 或正在测试 ACP 适配器路径时，才对 Codex 使用 ACP。Claude Code、Gemini CLI、OpenCode、Cursor 和类似的外部 harness 仍然使用 ACP。
启用内置的 `codex` 插件时，自然语言 Codex 控制应使用原生 `/codex` 命令表面（`/codex bind`、`/codex threads`、`/codex resume`、`/codex steer`、`/codex stop`），而不是 ACP。仅当用户明确要求 ACP/acpx 或正在测试 ACP 适配器路径时，才将 ACP 用于 Codex。Claude Code、Gemini CLI、OpenCode、Cursor 以及类似的外部 harness 仍使用 ACP。
这是面向智能体的决策树：
1. 如果用户要求 **Codex 绑定/控制/线程/恢复/Steering/停止**，并且内置 `codex` 插件已启用，则使用原生 `/codex` 命令表面。
2. 如果用户要求 **Codex 作为嵌入式运行时**，或想要普通的订阅支持 Codex 智能体体验，请使用 `openai/<model>` 加 `agentRuntime.id: "codex"`。
3. 如果用户要求在普通 OpenClaw runner 上使用 **Codex OAuth/订阅认证**，请使用 `openai-codex/<model>`，并让运行时保持为 PI。
1. 如果用户要求 **Codex 绑定/控制/线程/恢复/引导/停止**，并且内置的 `codex` 插件已启用，请使用原生 `/codex` 命令表面。
2. 如果用户要求 **Codex 作为嵌入式运行时**，或希望获得常规的订阅支持 Codex 智能体体验，请使用 `openai/<model>` 加 `agentRuntime.id: "codex"`。
3. 如果用户要求在**常规 OpenClaw runner 上使用 Codex OAuth/订阅认证**，请使用 `openai-codex/<model>`，并让运行时保持为 PI。
4. 如果用户明确说 **ACP**、**acpx** 或 **Codex ACP 适配器**，请使用 ACP，并设置 `runtime: "acp"` 和 `agentId: "codex"`。
5. 如果请求针对 **Claude Code、Gemini CLI、OpenCode、Cursor、Droid 或其他外部 harness**，请使用 ACP/acpx，而不是原生子智能体运行时。
5. 如果请求面向 **Claude Code、Gemini CLI、OpenCode、Cursor、Droid 或其他外部 harness**，请使用 ACP/acpx，而不是原生子智能体运行时。
| 你的意思是…… | 使用…… |
| 你的意思是…… | 使用…… |
| --------------------------------------- | -------------------------------------------- |
| Codex 应用服务器聊天/线程控制 | 来自内置 `codex` 插件的 `/codex ...` |
| Codex 应用服务器嵌入式智能体运行时 | `agentRuntime.id: "codex"` |
| PI runner 上的 OpenAI Codex OAuth | `openai-codex/*` model refs |
| Claude Code 或其他外部 harness | ACP/acpx |
| Codex app-server 聊天/线程控制 | 来自内置 `codex` 插件的 `/codex ...` |
| Codex app-server 嵌入式智能体运行时 | `agentRuntime.id: "codex"` |
| PI runner 上的 OpenAI Codex OAuth | `openai-codex/*` 模型引用 |
| Claude Code 或其他外部 harness | ACP/acpx |
关于 OpenAI 系列前缀拆分，请参阅 [OpenAI](/zh-CN/providers/openai) 和
[模型提供商](/zh-CN/concepts/model-providers)。关于 Codex 运行时支持契约，请参阅 [Codex harness](/zh-CN/plugins/codex-harness#v1-support-contract)。
关于 OpenAI 家族前缀拆分，请参见 [OpenAI](/zh-CN/providers/openai) 和 [模型提供商](/zh-CN/concepts/model-providers)。关于 Codex 运行时支持契约，请参见 [Codex harness](/zh-CN/plugins/codex-harness#v1-support-contract)。
## 运行时所有权
不同运行时拥有循环中不同范围的内容。
不同运行时拥有循环的不同部分。
| 表面 | OpenClaw PI 嵌入式 | Codex 应用服务器 |
| --------------------------- | ------------------------------------------ | --------------------------------------------------------------------------- |
| 模型循环所有者 | OpenClaw 通过 PI 嵌入式 runner | Codex 应用服务器 |
| 规范线程状态 | OpenClaw 记录 | Codex 线程，以及 OpenClaw 记录镜像 |
| OpenClaw 动态工具 | 原生 OpenClaw 工具循环 | 通过 Codex 适配器桥接 |
| 原生 shell 和文件工具 | PI/OpenClaw 路径 | Codex 原生工具，并在支持时通过原生钩子桥接 |
| 上下文引擎 | 原生 OpenClaw 上下文组装 | OpenClaw 将项目组装的上下文投射到 Codex 轮次中 |
| 压缩 | OpenClaw 或所选上下文引擎 | Codex 原生压缩，配合 OpenClaw 通知和镜像维护 |
| 渠道投递 | OpenClaw | OpenClaw |
| 表面 | OpenClaw PI 嵌入式 | Codex app-server |
| --------------------------- | --------------------------------------- | --------------------------------------------------------------------------- |
| 模型循环所有者 | OpenClaw，通过 PI 嵌入式 runner | Codex app-server |
| 规范线程状态 | OpenClaw transcript | Codex thread，外加 OpenClaw transcript 镜像 |
| OpenClaw 动态工具 | 原生 OpenClaw 工具循环 | 通过 Codex 适配器桥接 |
| 原生 shell 和文件工具 | PI/OpenClaw 路径 | Codex 原生工具，在支持的位置通过原生钩子桥接 |
| 上下文引擎 | 原生 OpenClaw 上下文组装 | OpenClaw 将组装后的上下文投射到 Codex 回合中 |
| 压缩 | OpenClaw 或所选上下文引擎 | Codex 原生压缩，带有 OpenClaw 通知和镜像维护 |
| 渠道投递 | OpenClaw | OpenClaw |
这种所有权拆分是主要设计规则：
- 如果 OpenClaw 拥有该表面，OpenClaw 可以提供普通插件钩子行为。
- 如果 OpenClaw 拥有该表面，OpenClaw 可以提供常规插件钩子行为。
- 如果原生运行时拥有该表面，OpenClaw 需要运行时事件或原生钩子。
- 如果原生运行时拥有规范线程状态，OpenClaw 应镜像并投射上下文，而不是重写不受支持的内部机制。
- 如果原生运行时拥有规范线程状态，OpenClaw 应该镜像并投射上下文，而不是重写不受支持的内部状态。
## 运行时选择
OpenClaw 会在提供商和模型解析后选择嵌入式运行时：
OpenClaw 在提供商和模型解析之后选择嵌入式运行时：
1. 会话记录的运行时优先。配置更改不会把现有记录热切换到另一个原生线程系统。
2. `OPENCLAW_AGENT_RUNTIME=<id>` 会为新的或重置的会话强制使用该运行时。
3. `agents.defaults.agentRuntime.id` 或 `agents.list[].agentRuntime.id` 可以设置为 `auto`、`pi`、已注册的嵌入式 harness id（如 `codex`），或受支持的 CLI 后端别名（如 `claude-cli`）。
4. 在 `auto` 模式下，已注册的插件运行时可以声明其支持的提供商/模型配对。
5. 如果在 `auto` 模式下没有运行时声明某个轮次，并且设置了 `fallback: "pi"`（默认值），OpenClaw 会使用 PI 作为兼容性回退。设置 `fallback: "none"` 可让未匹配的 `auto` 模式选择失败。
1. 会话记录的运行时优先。配置更改不会把现有 transcript 热切换到另一个原生线程系统。
2. `OPENCLAW_AGENT_RUNTIME=<id>` 会强制新会话或重置会话使用该运行时。
3. `agents.defaults.agentRuntime.id` 或 `agents.list[].agentRuntime.id` 可以设置 `auto`、`pi`、已注册的嵌入式 harness id（例如 `codex`），或受支持的 CLI 后端别名（例如 `claude-cli`）。
4. 在 `auto` 模式中，已注册的插件运行时可以声明其支持的提供商/模型组合。
5. 如果在 `auto` 模式中没有运行时声明某个回合，OpenClaw 会使用 PI 作为兼容运行时。如果运行必须严格，请使用显式运行时 id。
显式插件运行时默认以关闭方式失败。例如，`agentRuntime.id: "codex"` 表示使用 Codex，否则给出清晰的选择错误，除非你在同一覆盖作用域中设置 `fallback: "pi"`。运行时覆盖不会继承更宽泛的回退设置，因此仅仅因为 defaults 使用了 `fallback: "pi"`，智能体级别的 `agentRuntime.id: "codex"` 并不会被静默路由回 PI。
显式插件运行时会失败关闭。例如，`agentRuntime.id: "codex"` 表示 Codex 或明确的选择/运行时错误；它绝不会被静默路由回 PI。
CLI 后端别名不同于嵌入式 harness id。首选的 Claude CLI 形式是：
CLI 后端别名不同于嵌入式 harness id。推荐的 Claude CLI 形式是：
```json5
{
@ -129,42 +128,38 @@ CLI 后端别名不同于嵌入式 harness id。首选的 Claude CLI 形式是
}
```
为了兼容性，仍然支持 `claude-cli/claude-opus-4-7` 等旧版引用，但新配置应保持提供商/模型规范化，并把执行后端放在 `agentRuntime.id` 中。
为了兼容性，仍支持 `claude-cli/claude-opus-4-7` 等旧式引用，但新配置应保持提供商/模型为规范形式，并把执行后端放在 `agentRuntime.id` 中。
`auto` 模式有意保持保守。插件运行时可以声明它们理解的提供商/模型配对，但 Codex 插件不会在 `auto` 模式下声明 `openai-codex` 提供商。这会让 `openai-codex/*` 保持为显式的 PI Codex OAuth 路由，并避免把订阅认证配置静默移动到原生应用服务器 harness。
`auto` 模式有意保持保守。插件运行时可以声明它们理解的提供商/模型组合，但 Codex 插件不会在 `auto` 模式中声明 `openai-codex` 提供商。这会让 `openai-codex/*` 保持为显式的 PI Codex OAuth 路由，并避免把订阅认证配置静默迁移到原生 app-server harness 上。
如果 `openclaw doctor` 警告说 `codex` 插件已启用，而 `openai-codex/*` 仍通过 PI 路由，请把它视为诊断，而不是迁移。当 PI Codex OAuth 是你想要的行为时，保持配置不变。只有当你想要原生 Codex 应用服务器执行时，才切换到 `openai/<model>` 加 `agentRuntime.id: "codex"`。
如果 `openclaw doctor` 警告 `codex` 插件已启用，而 `openai-codex/*` 仍通过 PI 路由，请把它视为诊断，而不是迁移。当 PI Codex OAuth 是你想要的行为时，请保持配置不变。只有在你想要原生 Codex app-server 执行时，才切换到 `openai/<model>` 加 `agentRuntime.id: "codex"`。
## 兼容性契约
当运行时不是 PI 时，它应记录自己支持哪些 OpenClaw 表面。运行时文档请使用这种形状：
当运行时不是 PI 时，它应记录自己支持哪些 OpenClaw 表面。运行时文档请使用这种结构：
| 问题 | 重要原因 |
| 问题 | 重要性 |
| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| 谁拥有模型循环？ | 决定重试、工具继续执行和最终答案决策发生在哪里。 |
| 谁拥有规范线程历史？ | 决定 OpenClaw 是否可以编辑历史，还是只能镜像历史。 |
| OpenClaw 动态工具是否可用？ | 消息、会话、cron 和 OpenClaw 拥有的工具都依赖这一点。 |
| 动态工具钩子是否可用？ | 插件期望围绕 OpenClaw 拥有的工具使用 `before_tool_call`、`after_tool_call` 和中间件。 |
| 原生工具钩子是否可用？ | Shell、patch 和运行时拥有的工具需要原生钩子支持，以便执行策略和观测。 |
| 上下文引擎生命周期是否运行？ | 记忆和上下文插件依赖组装、摄取、轮次后处理和压缩生命周期。 |
| 暴露了哪些压缩数据？ | 一些插件只需要通知，而另一些插件需要保留/丢弃的元数据。 |
| 哪些内容是有意不支持的？ | 用户不应在原生运行时拥有更多状态的地方假设 PI 等价性。 |
| 谁拥有模型循环？ | 决定重试、工具继续执行和最终答案决策发生在哪里。 |
| 谁拥有规范线程历史？ | 决定 OpenClaw 是可以编辑历史，还是只能镜像历史。 |
| OpenClaw 动态工具是否可用？ | 消息、会话、cron 和 OpenClaw 拥有的工具依赖于此。 |
| 动态工具钩子是否可用？ | 插件期望围绕 OpenClaw 拥有的工具使用 `before_tool_call`、`after_tool_call` 和中间件。 |
| 原生工具钩子是否可用？ | shell、patch 和运行时拥有的工具需要原生钩子支持以实现策略和观测。 |
| 上下文引擎生命周期是否运行？ | 记忆和上下文插件依赖组装、摄取、回合后以及压缩生命周期。 |
| 暴露哪些压缩数据？ | 一些插件只需要通知，而其他插件需要保留/丢弃的元数据。 |
| 有哪些有意不支持的内容？ | 用户不应在原生运行时拥有更多状态的地方假定它与 PI 等价。 |
Codex 运行时支持契约记录在
[Codex harness](/zh-CN/plugins/codex-harness#v1-support-contract)。
Codex 运行时支持契约记录在 [Codex harness](/zh-CN/plugins/codex-harness#v1-support-contract)。
## Status 标签
Status 输出可能同时显示 `Execution` 和 `Runtime` 标签。请将它们视为
诊断信息，而不是提供商名称。
Status 输出可能会同时显示 `Execution` 和 `Runtime` 标签。请将它们理解为诊断信息，而不是提供商名称。
- 像 `openai/gpt-5.5` 这样的模型引用会告诉你选中的提供商/模型。
- 像 `codex` 这样的运行时 ID 会告诉你哪个循环正在执行该轮次。
- 像 `openai/gpt-5.5` 这样的模型引用会告诉你所选的提供商/模型。
- 像 `codex` 这样的运行时 ID 会告诉你哪个循环正在执行这一轮。
- 像 Telegram 或 Discord 这样的渠道标签会告诉你对话发生在哪里。
如果更改运行时配置后，会话仍显示 PI，请用 `/new` 启动新会话，
或用 `/reset` 清除当前会话。现有会话会保留其记录的运行时，
这样同一份转录就不会通过两个不兼容的原生会话系统重放。
如果更改运行时配置后，会话仍然显示 PI，请用 `/new` 启动新会话，或用 `/reset` 清除当前会话。现有会话会保留其记录的运行时，这样同一份对话记录就不会通过两个不兼容的原生会话系统重放。
## 相关内容

210
docs/zh-CN/concepts/model-providers.md
View File

@ -3,32 +3,32 @@ read_when:
- 你需要一份按提供商划分的模型设置参考
- 你想要模型提供商的示例配置或 CLI 新手引导命令
sidebarTitle: Model providers
summary: 模型提供商概览，包含配置示例 + CLI 流程
summary: 模型提供商概览，包含示例配置 + CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-05-02T05:17:43Z"
generated_at: "2026-05-03T04:50:48Z"
model: gpt-5.5
provider: openai
source_hash: 02494bfb71c0e0449eacd9ec028316e7a1479e51c6591aea5885baf3941272d5
source_hash: bfb12090228ec89bc116558fe3e0bf9977c750550ef8efbf55b1af6c873c9825
source_path: concepts/model-providers.md
workflow: 16
---
模型选择规则请参阅 [Models](/zh-CN/concepts/models)。
LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）的参考。有关模型选择规则，请参阅 [Models](/zh-CN/concepts/models)。
## 快速规则
<AccordionGroup>
<Accordion title="模型引用和 CLI 辅助命令">
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
- 设置 `agents.defaults.models` 后，它会作为允许列表。
- 设置后，`agents.defaults.models` 会作为允许列表。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 会按模型覆盖它们。
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 按模型覆盖这些默认值。
- 回退规则、冷却探测和会话覆盖持久化：[模型故障转移](/zh-CN/concepts/model-failover)。
</Accordion>
<Accordion title="添加提供商凭证不会更改你的主模型">
当你添加提供商或重新授权提供商时，`openclaw configure` 会保留现有的 `agents.defaults.model.primary`。提供商插件仍可能在其凭证配置补丁中返回推荐的默认模型，但如果主模型已经存在，configure 会将其视为“让此模型可用”，而不是“替换当前主模型”。
<Accordion title="添加提供商认证不会更改你的主模型">
当你添加提供商或重新认证提供商时，`openclaw configure` 会保留现有的 `agents.defaults.model.primary`。提供商插件仍可能在它们的认证配置补丁中返回推荐的默认模型，但如果主模型已存在，configure 会将其视为“使此模型可用”，而不是“替换当前主模型”。
若要有意切换默认模型，请使用 `openclaw models set <provider/model>` 或 `openclaw models auth login --provider <id> --set-default`。
@ -38,31 +38,31 @@ x-i18n:
- `openai/<model>` 加上 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex 应用服务器 harness。这是常见的 ChatGPT/Codex 订阅设置。
- `openai-codex/<model>` 在 PI 中使用 Codex OAuth。
- 没有 Codex 运行时覆盖的 `openai/<model>` 使用 PI 中的直接 OpenAI API key 提供商。
- 没有 Codex 运行时覆盖的 `openai/<model>` 在 PI 中使用直接的 OpenAI API key 提供商。
请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果 provider/运行时拆分令人困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果 provider/运行时拆分让你困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
插件自动启用遵循相同边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/<model>` 引用启用。
设置 `agentRuntime.id: "codex"` 时，GPT-5.5 可通过原生 Codex 应用服务器 harness 使用；对于 Codex OAuth，可通过 PI 中的 `openai-codex/gpt-5.5` 使用；当你的账号开放该模型时，对于直接 API-key 流量，可通过 PI 中的 `openai/gpt-5.5` 使用。
当设置 `agentRuntime.id: "codex"` 时，GPT-5.5 可通过原生 Codex 应用服务器 harness 使用；对于 Codex OAuth，可通过 PI 中的 `openai-codex/gpt-5.5` 使用；当你的账号开放该模型时，对于直接 API key 流量，可通过 PI 中的 `openai/gpt-5.5` 使用。
</Accordion>
<Accordion title="CLI 运行时">
CLI 运行时使用相同拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在需要本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。
CLI 运行时使用相同的拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在你想使用本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。
旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并将运行时单独记录。
旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并单独记录运行时。
</Accordion>
</AccordionGroup>
## 插件拥有的提供商行为
大多数提供商特定逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、凭证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置等。
大多数提供商特定逻辑位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具架构清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置档案等能力。
提供商 SDK 钩子和内置插件示例的完整列表位于[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于单独且更深层的扩展面。
提供商 SDK 钩子和内置插件示例的完整列表位于 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于另一个更深层的扩展面。
<Note>
提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求辅助工具。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，不再由共享 runner 逻辑读取。
提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具架构规范化、流包装以及传输/请求辅助函数。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，共享 runner 逻辑不再读取它。
</Note>
## API key 轮换
@ -71,30 +71,30 @@ x-i18n:
<Accordion title="密钥来源和优先级">
通过以下方式配置多个密钥：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，优先级最高）
- `<PROVIDER>_API_KEYS`（逗号或分号列表）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。密钥选择顺序会保留优先级并对值去重。
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。密钥选择顺序会保留优先级并去重值。
</Accordion>
<Accordion title="何时触发轮换">
- 仅在速率限制响应时，请求才会使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 或周期性用量限制消息）。
- 请求只会在遇到速率限制响应时使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
- 非速率限制失败会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。
- 当所有候选密钥都失败时，会返回最后一次尝试的最终错误。
</Accordion>
</AccordionGroup>
## 内置提供商（pi-ai 目录）
OpenClaw 随附 pi-ai 目录。这些提供商**不**需要 `models.providers` 配置；只需设置凭证并选择模型。
OpenClaw 随附 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证并选择模型。
### OpenAI
- 提供商：`openai`
- 凭证：`OPENAI_API_KEY`
- 认证：`OPENAI_API_KEY`
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
- 示例模型：`openai/gpt-5.5`、`openai/gpt-5.4-mini`
- 如果特定安装或 API key 表现不同，请使用 `openclaw models list --provider openai` 验证账号/模型可用性。
@ -102,12 +102,12 @@ OpenClaw 随附 pi-ai 目录。这些提供商**不**需要 `models.providers`
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
- 通过 `agents.defaults.models["openai/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`）
- OpenAI 优先级处理可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用
- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- OpenAI 优先处理可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用
- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 当你想要显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不应用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、prompt-cache 提示以及 OpenAI reasoning 兼容载荷整形；代理路由不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未公开它
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、prompt-cache 提示和 OpenAI reasoning 兼容载荷塑形；代理路由不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，并且当前 Codex 目录未公开它
```json5
{
@ -118,18 +118,18 @@ OpenClaw 随附 pi-ai 目录。这些提供商**不**需要 `models.providers`
### Anthropic
- 提供商：`anthropic`
- 凭证：`ANTHROPIC_API_KEY`
- 认证：`ANTHROPIC_API_KEY`
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
- 示例模型：`anthropic/claude-opus-4-6`
- CLI：`openclaw onboard --auth-choice apiKey`
- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API-key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- 首选 Claude CLI 配置会保持模型引用规范，并单独选择 CLI
后端：`anthropic/claude-opus-4-7` 搭配
`agents.defaults.agentRuntime.id: "claude-cli"`。旧版
`claude-cli/claude-opus-4-7` 引用仍可用于兼容。
`claude-cli/claude-opus-4-7` 引用仍可用于兼容性。
<Note>
Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将此集成中的 Claude CLI 复用和 `claude -p` 用法视为已获准。Anthropic setup-token 仍作为受支持的 OpenClaw token 路径可用，但 OpenClaw 现在会在可用时优先使用 Claude CLI 复用和 `claude -p`。
Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用已再次被允许，因此除非 Anthropic 发布新策略，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 使用视为此集成的获准方式。Anthropic setup-token 仍可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在优先使用 Claude CLI 复用和可用时的 `claude -p`。
</Note>
```json5
@ -141,7 +141,7 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允
### OpenAI Codex OAuth
- 提供商：`openai-codex`
- 凭证：OAuth (ChatGPT)
- 认证：OAuth（ChatGPT）
- PI 模型引用：`openai-codex/gpt-5.5`
- 原生 Codex 应用服务器 harness 引用：`openai/gpt-5.5` 搭配 `agents.defaults.agentRuntime.id: "codex"`
- 原生 Codex 应用服务器 harness 文档：[Codex harness](/zh-CN/plugins/codex-harness)
@ -150,13 +150,13 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
- 通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 按 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上转发
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不附加到通用 OpenAI 兼容代理
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）中转发
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority`
- `openai-codex/gpt-5.5` 使用 Codex 目录原生 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- `openai-codex/gpt-5.5` 使用 Codex 目录原生的 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 这类外部工具/工作流。
- 对于常见的订阅加原生 Codex 运行时路由，请使用 `openai-codex` 凭证登录，但配置 `openai/gpt-5.5` 加上 `agents.defaults.agentRuntime.id: "codex"`。
- 仅当你希望通过 PI 使用 Codex OAuth/订阅路由时，才使用 `openai-codex/gpt-5.5`；当你的 API-key 设置和本地目录公开公共 API 路由时，请使用不带 Codex 运行时覆盖的 `openai/gpt-5.5`。
- 对于常见的订阅加原生 Codex 运行时路由，请使用 `openai-codex` 认证登录，但配置 `openai/gpt-5.5` 加 `agents.defaults.agentRuntime.id: "codex"`。
- 仅当你想通过 PI 使用 Codex OAuth/订阅路由时，才使用 `openai-codex/gpt-5.5`；当你的 API key 设置和本地目录公开公共 API 路由时，请使用没有 Codex 运行时覆盖的 `openai/gpt-5.5`。
```json5
{
@ -164,7 +164,7 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" },
agentRuntime: { id: "codex", fallback: "none" },
agentRuntime: { id: "codex" },
},
},
}
@ -198,7 +198,7 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允
### OpenCode
- 凭证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
- 认证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
- Zen 运行时提供商：`opencode`
- Go 运行时提供商：`opencode-go`
- 示例模型：`opencode/claude-opus-4-6`、`opencode-go/kimi-k2.6`
@ -216,11 +216,11 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允
- 凭证：`GEMINI_API_KEY`
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单一覆盖）
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会规范化为 `google/gemini-3-flash-preview`
- 别名：`google/gemini-3.1-pro` 可被接受，并规范化为 Google 实时 Gemini API ID：`google/gemini-3.1-pro-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview`
- 别名：接受 `google/gemini-3.1-pro`，并将其规范化为 Google 的实时 Gemini API id：`google/gemini-3.1-pro-preview`
- CLI：`openclaw onboard --auth-choice gemini-api-key`
- 思考：`/think adaptive` 使用 Google 动态思考。Gemini 3/3.1 会省略固定的 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。
- 直接运行 Gemini 也接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
- 思考：`/think adaptive` 使用 Google 动态思考。Gemini 3/3.1 省略固定的 `thinkingLevel`；Gemini 2.5 发送 `thinkingBudget: -1`。
- 直接 Gemini 运行也接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），用于转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会作为 OpenClaw `cacheRead` 显示
### Google Vertex 和 Gemini CLI
@ -228,13 +228,13 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允
- 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
<Warning>
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后遇到 Google 账号限制。如果你选择继续，请查看 Google 条款，并使用非关键账号。
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，使用第三方客户端后 Google 账号受到了限制。如果你选择继续，请查看 Google 条款并使用非关键账号。
</Warning>
Gemini CLI OAuth 作为内置 `google` 插件的一部分发布。
Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
<Steps>
<Step title="Install Gemini CLI">
<Step title="安装 Gemini CLI">
<Tabs>
<Tab title="brew">
```bash
@ -248,25 +248,25 @@ Gemini CLI OAuth 作为内置 `google` 插件的一部分发布。
</Tab>
</Tabs>
</Step>
<Step title="Enable plugin">
<Step title="启用插件">
```bash
openclaw plugins enable google
```
</Step>
<Step title="Login">
<Step title="登录">
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不**需要把客户端 ID 或密钥粘贴到 `openclaw.json`。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置文件中。
默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不**需要把客户端 id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会把令牌存储在 Gateway 网关主机上的凭证配置文件中。
</Step>
<Step title="Set project (if needed)">
<Step title="设置项目（如果需要）">
如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
</Step>
</Steps>
Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，并将 `stats.cached` 规范化为 OpenClaw `cacheRead`。
Gemini CLI JSON 回复会从 `response` 解析；用量回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
### Z.AI (GLM)
@ -275,40 +275,40 @@ Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，
- 示例模型：`zai/glm-5.1`
- CLI：`openclaw onboard --auth-choice zai-api-key`
- 别名：`z.ai/*` 和 `z-ai/*` 会规范化为 `zai/*`
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定表面
### Vercel AI Gateway 网关
### Vercel AI Gateway
- 提供商：`vercel-ai-gateway`
- 凭证：`AI_GATEWAY_API_KEY`
- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`、`vercel-ai-gateway/moonshotai/kimi-k2.6`
- CLI：`openclaw onboard --auth-choice ai-gateway-api-key`
### Kilo Gateway 网关
### Kilo Gateway
- 提供商：`kilocode`
- 凭证：`KILOCODE_API_KEY`
- 示例模型：`kilocode/kilo/auto`
- CLI：`openclaw onboard --auth-choice kilocode-api-key`
- 基础 URL：`https://api.kilo.ai/api/gateway/`
- 静态回退目录随 `kilocode/kilo/auto` 一起发布；实时 `https://api.kilo.ai/api/gateway/models` 设备发现可以进一步扩展运行时目录。
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 网关负责，而不是在 OpenClaw 中硬编码。
- Base URL：`https://api.kilo.ai/api/gateway/`
- 静态回退目录随附 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 设备发现可以进一步扩展运行时目录。
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 拥有，不在 OpenClaw 中硬编码。
有关设置详情，请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。
### 其他内置提供商插件
| 提供商 | ID | 凭证环境变量 | 示例模型 |
| 提供商 | Id | 凭证环境变量 | 示例模型 |
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
| Cloudflare AI Gateway 网关 | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
| DeepInfra | `deepinfra` | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V3.2` |
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` |
| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — |
| Groq | `groq` | `GROQ_API_KEY` | — |
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
| Kilo Gateway 网关 | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
| Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` |
| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` |
| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` |
@ -320,31 +320,31 @@ Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，
| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` |
| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` |
| Venice | `venice` | `VENICE_API_KEY` | — |
| Vercel AI Gateway 网关 | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4.3` |
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
#### 需要了解的特性
#### 需要了解的细节
<AccordionGroup>
<Accordion title="OpenRouter">
仅在已验证的 `openrouter.ai` 路由上应用其应用归属标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 托管提示缓存的缓存 TTL 条件，但不会接收 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的形态调整（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容）。Gemini 支持的引用仅保留代理 Gemini 思维签名清理。
仅在已验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 管理的提示缓存 cache-TTL 条件，但不会接收 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI reasoning 兼容性）。由 Gemini 支持的引用仅保留代理 Gemini 思考签名清理。
</Accordion>
<Accordion title="Kilo Gateway">
Gemini 支持的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。
由 Gemini 支持的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。
</Accordion>
<Accordion title="MiniMax">
API key 新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍使用插件拥有的 `MiniMax-VL-01` 媒体提供商。
API key 新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在插件拥有的 `MiniMax-VL-01` 媒体提供商上。
</Accordion>
<Accordion title="NVIDIA">
模型 ID 使用 `nvidia/<vendor>/<model>` 命名空间（例如 `nvidia/nvidia/nemotron-...` 以及 `nvidia/moonshotai/kimi-k2.5`）；选择器会保留字面上的 `<provider>/<model-id>` 组合，而发送到 API 的规范键保持单前缀。
模型 ID 使用 `nvidia/<vendor>/<model>` 命名空间（例如 `nvidia/nvidia/nemotron-...` 与 `nvidia/moonshotai/kimi-k2.5` 并列）；选择器会保留字面量 `<provider>/<model-id>` 组合，而发送到 API 的规范键保持单前缀。
</Accordion>
<Accordion title="xAI">
使用 xAI Responses 路径。`grok-4.3` 是内置的默认聊天模型。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 禁用。
使用 xAI Responses 路径。`grok-4.3` 是内置的默认聊天模型。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为对应的 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 禁用。
</Accordion>
<Accordion title="Cerebras">
作为内置的 `cerebras` 提供商插件交付。GLM 使用 `zai-glm-4.7`；OpenAI 兼容的基础 URL 是 `https://api.cerebras.ai/v1`。
作为内置的 `cerebras` 提供商插件提供。GLM 使用 `zai-glm-4.7`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。
</Accordion>
</AccordionGroup>
@ -354,11 +354,11 @@ Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，
下面许多内置提供商插件已经发布默认目录。仅当你想覆盖默认基础 URL、标头或模型列表时，才使用显式的 `models.providers.<id>` 条目。
Gateway 网关模型能力检查也会读取显式的 `models.providers.<id>.models[]` 元数据。如果自定义或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，以便 WebChat 和节点来源附件路径将图像作为原生模型输入传递，而不是作为纯文本媒体引用。
Gateway 网关模型能力检查还会读取显式的 `models.providers.<id>.models[]` 元数据。如果自定义模型或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，以便 WebChat 和节点来源的附件路径将图像作为原生模型输入传递，而不是作为纯文本媒体引用。
### Moonshot AI（Kimi）
Moonshot 作为内置提供商插件交付。默认使用内置提供商，仅当需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
Moonshot 作为内置提供商插件提供。默认使用内置提供商，仅当你需要覆盖基础 URL 或模型元数据时才添加显式的 `models.providers.moonshot` 条目：
- 提供商：`moonshot`
- 凭证：`MOONSHOT_API_KEY`
@ -417,7 +417,7 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
### Volcano Engine（Doubao）
Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。
Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型的访问能力。
- 提供商：`volcengine`（编码：`volcengine-plan`）
- 凭证：`VOLCANO_ENGINE_API_KEY`
@ -432,9 +432,9 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
}
```
新手引导默认使用编码入口，但同时会注册通用的 `volcengine/*` 目录。
新手引导默认使用编码能力面，但通用的 `volcengine/*` 目录也会同时注册。
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个按提供商范围过滤后为空的选择器。
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。
<Tabs>
<Tab title="标准模型">
@ -472,9 +472,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力
}
```
新手引导默认使用编码入口，但同时会注册通用的 `byteplus/*` 目录。
新手引导默认使用编码能力面，但通用的 `byteplus/*` 目录也会同时注册。
在新手引导/配置模型选择器中，BytePlus 凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个按提供商范围过滤后为空的选择器。
在新手引导/配置模型选择器中，BytePlus 凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。
<Tabs>
<Tab title="标准模型">
@ -531,28 +531,28 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax API key（中国）：`--auth-choice minimax-cn-api`
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
查看 [/providers/minimax](/zh-CN/providers/minimax) 了解设置详情、模型选项和配置片段。
有关设置详情、模型选项和配置片段，请参阅 [/providers/minimax](/zh-CN/providers/minimax)。
<Note>
在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，否则 OpenClaw 默认会禁用思考，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，否则 OpenClaw 默认会禁用 thinking，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
</Note>
插件拥有的能力划分：
插件拥有的能力拆分：
- 文本/聊天默认值保持在 `minimax/MiniMax-M2.7`
- 文本/聊天默认值保留在 `minimax/MiniMax-M2.7`
- 图像生成是 `minimax/image-01` 或 `minimax-portal/image-01`
- 图像理解是在两条 MiniMax 凭证路径上均由插件拥有的 `MiniMax-VL-01`
- Web 搜索保持在提供商 ID `minimax`
- 图像理解是在两个 MiniMax 凭证路径上都由插件拥有的 `MiniMax-VL-01`
- Web 搜索保留在提供商 ID `minimax`
### LM Studio
LM Studio 作为内置提供商插件提供，并使用原生 API：
LM Studio 作为内置提供商插件发布，使用原生 API：
- 提供商：`lmstudio`
- 凭证：`LM_API_TOKEN`
- 默认推理基础 URL：`http://localhost:1234/v1`
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的任一 ID）：
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
```json5
{
@ -562,14 +562,14 @@ LM Studio 作为内置提供商插件提供，并使用原生 API：
}
```
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。如果你希望由 LM Studio 的 JIT 加载、TTL 和自动驱逐来管理模型生命周期，请设置 `models.providers.lmstudio.params.preload: false`。查看 [/providers/lmstudio](/zh-CN/providers/lmstudio) 了解设置和故障排除。
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。如果你希望 LM Studio JIT 加载、TTL 和自动驱逐拥有模型生命周期，请设置 `models.providers.lmstudio.params.preload: false`。有关设置和故障排除，请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
### Ollama
Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API：
Ollama 作为内置提供商插件发布，并使用 Ollama 的原生 API：
- 提供商：`ollama`
- 凭证：无需（本地服务器）
- 凭证：不需要（本地服务器）
- 示例模型：`ollama/llama3.3`
- 安装：[https://ollama.com/download](https://ollama.com/download)
@ -586,23 +586,23 @@ ollama pull llama3.3
}
```
当你通过 `OLLAMA_API_KEY` 选择启用时，OpenClaw 会在本地 `http://127.0.0.1:11434` 检测 Ollama，且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。查看 [/providers/ollama](/zh-CN/providers/ollama) 了解新手引导、云端/本地模式和自定义配置。
当你通过 `OLLAMA_API_KEY` 选择启用时，Ollama 会在 `http://127.0.0.1:11434` 被本地检测到，并且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器。有关新手引导、云端/本地模式和自定义配置，请参阅 [/providers/ollama](/zh-CN/providers/ollama)。
### vLLM
vLLM 作为内置提供商插件提供，用于本地/自托管 OpenAI 兼容服务器：
vLLM 作为内置提供商插件发布，用于本地/自托管的 OpenAI 兼容服务器：
- 提供商：`vllm`
- 凭证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:8000/v1`
要在本地选择启用自动发现（如果你的服务器不强制凭证，任意值都可以）：
要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）：
```bash
export VLLM_API_KEY="vllm-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的任一 ID）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -612,23 +612,23 @@ export VLLM_API_KEY="vllm-local"
}
```
查看 [/providers/vllm](/zh-CN/providers/vllm) 了解详情。
有关详情，请参阅 [/providers/vllm](/zh-CN/providers/vllm)。
### SGLang
SGLang 作为内置提供商插件提供，用于快速自托管 OpenAI 兼容服务器：
SGLang 作为内置提供商插件发布，用于快速自托管的 OpenAI 兼容服务器：
- 提供商：`sglang`
- 凭证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:30000/v1`
要在本地选择启用自动发现（如果你的服务器不强制凭证，任意值都可以）：
要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）：
```bash
export SGLANG_API_KEY="sglang-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的任一 ID）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -638,7 +638,7 @@ export SGLANG_API_KEY="sglang-local"
}
```
查看 [/providers/sglang](/zh-CN/providers/sglang) 了解详情。
有关详情，请参阅 [/providers/sglang](/zh-CN/providers/sglang)。
### 本地代理（LM Studio、vLLM、LiteLLM 等）
@ -678,7 +678,7 @@ export SGLANG_API_KEY="sglang-local"
<AccordionGroup>
<Accordion title="默认可选字段">
对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。省略时，OpenClaw 默认使用：
对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 是可选的。省略时，OpenClaw 默认使用：
- `reasoning: false`
- `input: ["text"]`
@ -689,15 +689,15 @@ export SGLANG_API_KEY="sglang-local"
建议：设置与你的代理/模型限制匹配的显式值。
</Accordion>
<Accordion title="代理路由塑形规则">
- 对非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl` 且其主机不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
- 代理式 OpenAI 兼容路由还会跳过仅适用于原生 OpenAI 的请求塑形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有提示缓存提示，没有 OpenAI 推理兼容载荷塑形，也没有隐藏的 OpenClaw 归因标头。
<Accordion title="代理路由整形规则">
- 对于非原生端点（任何非空 `baseUrl` 且其主机不是 `api.openai.com`）上的 `api: "openai-completions"`，OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持的 `developer` 角色而返回 400 错误。
- 代理风格的 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求整形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有提示缓存提示，没有 OpenAI reasoning 兼容载荷整形，也没有隐藏的 OpenClaw 归因头。
- 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求体中。
- 对于 vLLM 聊天模板控制，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话思考级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
- 对于缓慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers.<id>.timeoutSeconds`。这会扩展提供商模型 HTTP 请求处理，包括连接、标头、正文流式传输以及总的受保护 fetch 中止时间，而不会增加整个智能体运行时超时。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保持默认的 OpenAI 行为（解析到 `api.openai.com`）。
- 为安全起见，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
- 对非直连端点上的 `api: "anthropic-messages"`（canonical `anthropic` 以外的任何提供商，或自定义 `models.providers.anthropic.baseUrl` 且其主机不是公开 `api.anthropic.com` 端点），OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，因此自定义 Anthropic 兼容代理不会拒绝不支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 `models.providers.<id>.headers["anthropic-beta"]`。
- 对于 vLLM 聊天模板控制，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话 thinking 级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
- 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers.<id>.timeoutSeconds`。这会扩展提供商模型 HTTP 请求处理，包括连接、标头、正文流式传输以及总的受保护 fetch 中止时间，而不会增加整个智能体运行时超时时间。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。
- 为了安全，显式的 `compat.supportsDeveloperRole: true` 在非原生 `openai-completions` 端点上仍会被覆盖。
- 对于非直连端点（canonical `anthropic` 以外的任何提供商，或主机不是公开 `api.anthropic.com` 端点的自定义 `models.providers.anthropic.baseUrl`）上的 `api: "anthropic-messages"`，OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，因此自定义 Anthropic 兼容代理不会拒绝不支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 `models.providers.<id>.headers["anthropic-beta"]`。
</Accordion>
</AccordionGroup>
@ -710,7 +710,7 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
另见：[配置](/zh-CN/gateway/configuration) 了解完整配置示例。
另请参阅：[配置](/zh-CN/gateway/configuration)，了解完整配置示例。
## 相关内容

462
docs/zh-CN/gateway/config-agents.md
View File

@ -1,22 +1,20 @@
---
read_when:
- 调优智能体默认设置（模型、思考、工作区、Heartbeat、媒体、Skills）
- 调整智能体默认设置（模型、思考、工作区、Heartbeat、媒体、Skills）
- 配置多智能体路由和绑定
- 调整会话、消息投递和 talk-mode 行为
summary: 智能体默认设置、多智能体路由、会话、消息和 talk 配置
- 调整会话、消息投递和对话模式行为
summary: 智能体默认值、多智能体路由、会话、消息和对话配置
title: 配置 — 智能体
x-i18n:
generated_at: "2026-05-02T06:09:02Z"
generated_at: "2026-05-03T04:51:02Z"
model: gpt-5.5
provider: openai
source_hash: 559bb427555768c91720bac10ee60bf2ba5a081117b741a02c140b14267ce1bf
source_hash: b25371c34b9f8b0cacce021879e43e6a65b86d626dc87d5bfa05dcae80ac32e4
source_path: gateway/config-agents.md
workflow: 16
---
`agents.*`、`multiAgent.*`、`session.*`、
`messages.*` 和 `talk.*` 下的智能体作用域配置键名。对于渠道、工具、Gateway 网关运行时和其他
顶级键名，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。
智能体作用域的配置键位于 `agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下。关于渠道、工具、Gateway 网关运行时以及其他顶层键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。
## 智能体默认值
@ -32,7 +30,7 @@ x-i18n:
### `agents.defaults.repoRoot`
系统提示词 Runtime 行中显示的可选仓库根目录。如果未设置，OpenClaw 会从工作区向上遍历自动检测。
可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历自动检测。
```json5
{
@ -42,8 +40,7 @@ x-i18n:
### `agents.defaults.skills`
可选的默认技能允许列表，用于未设置
`agents.list[].skills` 的智能体。
可选的默认 Skills 允许列表，用于未设置 `agents.list[].skills` 的智能体。
```json5
{
@ -61,8 +58,7 @@ x-i18n:
- 省略 `agents.defaults.skills` 表示默认不限制 Skills。
- 省略 `agents.list[].skills` 表示继承默认值。
- 设置 `agents.list[].skills: []` 表示没有 Skills。
- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它
不会与默认值合并。
- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。
### `agents.defaults.skipBootstrap`
@ -76,7 +72,7 @@ x-i18n:
### `agents.defaults.skipOptionalBootstrapFiles`
跳过创建所选可选工作区文件，同时仍写入必需的引导文件。有效值：`SOUL.md`、`USER.md`、`HEARTBEAT.md` 和 `IDENTITY.md`。
跳过创建选定的可选工作区文件，同时仍写入必需的引导文件。有效值：`SOUL.md`、`USER.md`、`HEARTBEAT.md` 和 `IDENTITY.md`。
```json5
{
@ -92,8 +88,8 @@ x-i18n:
控制何时将工作区引导文件注入系统提示词。默认值：`"always"`。
- `"continuation-skip"`：安全的延续轮次（在已完成的助手回复之后）会跳过重新注入工作区引导内容，从而减少提示词大小。Heartbeat 运行和压缩后的重试仍会重建上下文。
- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅将此用于完全自行掌控提示词生命周期的智能体（自定义上下文引擎、构建自身上下文的原生运行时，或专用的无引导工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。
- `"continuation-skip"`：安全的续接轮次（在 assistant 响应完成后）会跳过重新注入工作区引导内容，从而减少提示词大小。Heartbeat 运行和压缩后的重试仍会重建上下文。
- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅将其用于完全自行管理提示词生命周期的智能体（自定义上下文引擎、构建自身上下文的原生运行时，或不需要引导的专用工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。
```json5
{
@ -113,7 +109,7 @@ x-i18n:
### `agents.defaults.bootstrapTotalMaxChars`
注入的所有工作区引导文件的总最大字符数。默认值：`60000`。
跨所有工作区引导文件注入的最大总字符数。默认值：`60000`。
```json5
{
@ -123,12 +119,11 @@ x-i18n:
### `agents.defaults.bootstrapPromptTruncationWarning`
控制引导上下文被截断时智能体可见的警告文本。
默认值：`"once"`。
控制引导上下文被截断时智能体可见的警告文本。默认值：`"once"`。
- `"off"`：绝不将警告文本注入系统提示词。
- `"once"`：对每个唯一的截断签名只注入一次警告（推荐）。
- `"always"`：存在截断时在每次运行中都注入警告。
- `"off"`：绝不向系统提示词注入警告文本。
- `"once"`：每个唯一截断签名只注入一次警告（推荐）。
- `"always"`：存在截断时，每次运行都注入警告。
```json5
{
@ -136,37 +131,30 @@ x-i18n:
}
```
### 上下文预算归属映射
### 上下文预算归属图
OpenClaw 有多个高容量提示词/上下文预算，它们
有意按子系统拆分，而不是全部经过一个通用
开关。
OpenClaw 有多个高容量提示词/上下文预算，它们有意按子系统拆分，而不是全部通过一个通用旋钮控制。
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`：
普通工作区引导注入。
- `agents.defaults.startupContext.*`：
一次性重置/启动模型运行前序内容，包括最近的每日
`memory/*.md` 文件。裸聊天 `/new` 和 `/reset` 命令会
在不调用模型的情况下确认重置。
一次性的重置/启动模型运行前言，包括最近每日的 `memory/*.md` 文件。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置。
- `skills.limits.*`：
注入系统提示词的紧凑 Skills 列表。
- `agents.defaults.contextLimits.*`：
有界运行时摘录和注入的运行时拥有块。
有边界的运行时摘录和注入的运行时自有块。
- `memory.qmd.limits.*`：
索引化记忆搜索片段和注入大小设置。
已索引记忆搜索片段和注入大小。
仅当某个智能体需要不同
预算时，才使用匹配的按智能体覆盖项：
仅当某个智能体需要不同预算时，才使用匹配的按智能体覆盖项：
- `agents.list[].skillsLimits.maxSkillsPromptChars`
- `agents.list[].contextLimits.*`
#### `agents.defaults.startupContext`
控制在重置/启动模型运行时注入的第一轮启动前序内容。
裸聊天 `/new` 和 `/reset` 命令会在不调用
模型的情况下确认重置，因此不会加载此前序内容。
控制在重置/启动模型运行时注入的首轮启动前言。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置，因此不会加载此前言。
```json5
{
@ -187,7 +175,7 @@ OpenClaw 有多个高容量提示词/上下文预算，它们
#### `agents.defaults.contextLimits`
有界运行时上下文表面的共享默认值。
有边界运行时上下文表面的共享默认值。
```json5
{
@ -204,18 +192,14 @@ OpenClaw 有多个高容量提示词/上下文预算，它们
}
```
- `memoryGetMaxChars`：添加截断
元数据和延续提示前的默认 `memory_get` 摘录上限。
- `memoryGetDefaultLines`：省略 `lines` 时默认的 `memory_get` 行窗口。
- `toolResultMaxChars`：用于持久化结果和
溢出恢复的实时工具结果上限。
- `postCompactionMaxChars`：压缩后
刷新注入期间使用的 AGENTS.md 摘录上限。
- `memoryGetMaxChars`：添加截断元数据和续接通知前，默认的 `memory_get` 摘录上限。
- `memoryGetDefaultLines`：省略 `lines` 时，默认的 `memory_get` 行窗口。
- `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。
- `postCompactionMaxChars`：压缩后刷新注入期间使用的 AGENTS.md 摘录上限。
#### `agents.list[].contextLimits`
共享 `contextLimits` 开关的按智能体覆盖项。省略的字段会继承
自 `agents.defaults.contextLimits`。
共享 `contextLimits` 旋钮的按智能体覆盖项。省略的字段继承自 `agents.defaults.contextLimits`。
```json5
{
@ -241,8 +225,7 @@ OpenClaw 有多个高容量提示词/上下文预算，它们
#### `skills.limits.maxSkillsPromptChars`
注入系统提示词的紧凑 Skills 列表的全局上限。这
不会影响按需读取 `SKILL.md` 文件。
注入系统提示词的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。
```json5
{
@ -275,11 +258,9 @@ Skills 提示词预算的按智能体覆盖项。
### `agents.defaults.imageMaxDimensionPx`
在调用提供商之前，转录/工具图片块中图片最长边的最大像素尺寸。
默认值：`1200`。
在调用提供商前，转录/工具图像块中图像最长边的最大像素尺寸。默认值：`1200`。
较低的值通常会减少截图密集型运行中的视觉 token 使用量和请求载荷大小。
较高的值会保留更多视觉细节。
较低的值通常会减少大量截图运行中的视觉 token 用量和请求载荷大小。较高的值会保留更多视觉细节。
```json5
{
@ -340,7 +321,6 @@ Skills 提示词预算的按智能体覆盖项。
params: { cacheRetention: "long" }, // global default provider params
agentRuntime: {
id: "pi", // pi | auto | registered harness id, e.g. codex
fallback: "pi", // pi | none
},
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
@ -358,57 +338,57 @@ Skills 提示词预算的按智能体覆盖项。
```
- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 字符串形式仅设置主模型。
- 字符串形式只设置主模型。
- 对象形式设置主模型以及有序故障转移模型。
- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 由 `image` 工具路径用作其视觉模型配置。
- 当选定/默认模型无法接受图像输入时，也用作备用路由。
- 优先使用显式 `provider/model` 引用。裸 ID 为兼容性而接受；如果裸 ID 唯一匹配 `models.providers.*.models` 中已配置且支持图像的条目，OpenClaw 会将其限定到该提供商。存在歧义的已配置匹配需要显式提供商前缀。
- 被 `image` 工具路径用作其视觉模型配置。
- 当所选/默认模型无法接受图像输入时，也用作后备路由。
- 优先使用显式 `provider/model` 引用。为兼容性也接受裸 ID；如果裸 ID 唯一匹配 `models.providers.*.models` 中已配置且支持图像的条目，OpenClaw 会将其限定到该提供商。已配置匹配存在歧义时，需要显式提供商前缀。
- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 由共享图像生成能力以及任何未来生成图像的工具/插件界面使用。
- 典型值：`google/gemini-3.1-flash-image-preview` 用于原生 Gemini 图像生成，`fal/fal-ai/flux/dev` 用于 fal，`openai/gpt-image-2` 用于 OpenAI Images，或 `openai/gpt-image-1.5` 用于透明背景 OpenAI PNG/WebP 输出。
- 如果你直接选择提供商/模型，也要配置匹配的提供商凭证（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。
- 被共享图像生成能力以及任何未来会生成图像的工具/插件表面使用。
- 典型值：用于 Gemini 原生图像生成的 `google/gemini-3.1-flash-image-preview`、用于 fal 的 `fal/fal-ai/flux/dev`、用于 OpenAI Images 的 `openai/gpt-image-2`，或用于透明背景 OpenAI PNG/WebP 输出的 `openai/gpt-image-1.5`。
- 如果你直接选择提供商/模型，也要配置匹配的提供商凭证（例如用于 `google/*` 的 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，用于 `openai/gpt-image-2` / `openai/gpt-image-1.5` 的 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，用于 `fal/*` 的 `FAL_KEY`）。
- 如果省略，`image_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。
- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 由共享音乐生成能力以及内置 `music_generate` 工具使用。
- 被共享音乐生成能力和内置 `music_generate` 工具使用。
- 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。
- 如果省略，`music_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。
- 如果你直接选择提供商/模型，也要配置匹配的提供商凭证/API key。
- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 由共享视频生成能力以及内置 `video_generate` 工具使用。
- 被共享视频生成能力和内置 `video_generate` 工具使用。
- 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
- 如果省略，`video_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。
- 如果你直接选择提供商/模型，也要配置匹配的提供商凭证/API key。
- 内置 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 由 `pdf` 工具用于模型路由。
- 如果省略，PDF 工具会回退到 `imageModel`，再回退到已解析的会话/默认模型。
- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。
- `pdfMaxPages`：`pdf` 工具中提取备用模式考虑的默认最大页数。
- 被 `pdf` 工具用于模型路由。
- 如果省略，PDF 工具会回退到 `imageModel`，再回退到解析后的会话/默认模型。
- `pdfMaxBytesMb`：调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。
- `pdfMaxPages`：`pdf` 工具中提取后备模式考虑的默认最大页数。
- `verboseDefault`：智能体的默认详细级别。值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
- `reasoningDefault`：智能体的默认推理可见性。值：`"off"`、`"on"`、`"stream"`。每智能体的 `agents.list[].reasoningDefault` 会覆盖此默认值。仅当没有设置每消息或会话推理覆盖时，已配置的推理默认值才会应用于所有者、已授权发送者或操作员管理员 Gateway 网关上下文。
- `reasoningDefault`：智能体的默认推理可见性。值：`"off"`、`"on"`、`"stream"`。每个智能体的 `agents.list[].reasoningDefault` 会覆盖此默认值。已配置的推理默认值只会在没有设置单条消息或会话推理覆盖项时，应用于所有者、授权发送者，或操作员管理员 Gateway 网关上下文。
- `elevatedDefault`：智能体的默认提升输出级别。值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
- `model.primary`：格式为 `provider/model`（例如 API key 访问使用 `openai/gpt-5.5`，Codex OAuth 使用 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试该精确模型 ID 的唯一已配置提供商匹配，最后才回退到已配置的默认提供商（已弃用的兼容行为，因此优先使用显式 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露陈旧的已移除提供商默认值。
- `model.primary`：格式为 `provider/model`（例如用于 API key 访问的 `openai/gpt-5.5`，或用于 Codex OAuth 的 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后为该精确模型 ID 尝试唯一的已配置提供商匹配，最后才回退到已配置的默认提供商（已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露陈旧的已移除提供商默认值。
- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可以包含 `alias`（快捷方式）和 `params`（提供商特定，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。
- 安全编辑：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝移除现有允许列表条目的替换。
- 提供商范围的配置/新手引导流程会将选定的提供商模型合并到此映射，并保留已配置的无关提供商。
- 安全编辑：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换。
- 提供商作用域的配置/新手引导流程会把所选提供商模型合并到此映射中，并保留已配置的无关提供商。
- 对于直接 OpenAI Responses 模型，服务器端压缩会自动启用。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务器端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
- `params`：应用到所有模型的全局默认提供商参数。在 `agents.defaults.params` 设置（例如 `{ cacheRetention: "long" }`）。
- `params`：应用到所有模型的全局默认提供商参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。
- `params` 合并优先级（配置）：`agents.defaults.params`（全局基准）会被 `agents.defaults.models["provider/model"].params`（每模型）覆盖，然后 `agents.list[].params`（匹配智能体 ID）按键覆盖。详情参见 [提示缓存](/zh-CN/reference/prompt-caching)。
- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，额外 body 获胜；非原生 completions 路由随后仍会剥离仅 OpenAI 支持的 `store`。
- `params.chat_template_kwargs`：vLLM/OpenAI 兼容聊天模板参数，会合并到顶层 `api: "openai-completions"` 请求体中。对于关闭 thinking 的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式 `chat_template_kwargs` 会覆盖生成的默认值，且 `extra_body.chat_template_kwargs` 仍具有最终优先级。对于 vLLM Qwen thinking 控制，在该模型条目上将 `params.qwenThinkingFormat` 设置为 `"chat-template"` 或 `"top-level"`。
- `compat.supportedReasoningEfforts`：每模型 OpenAI 兼容推理强度列表。对于真正接受它的自定义端点，包含 `"xhigh"`；OpenClaw 随后会在命令菜单、Gateway 网关会话行、会话补丁验证、智能体 CLI 验证以及 `llm-task` 验证中为该已配置提供商/模型公开 `/think xhigh`。当后端需要某个规范级别的提供商特定值时，使用 `compat.reasoningEffortMap`。
- `params.preserveThinking`：仅 Z.AI 的保留 thinking 选择加入项。启用且 thinking 开启时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放先前的 `reasoning_content`；参见 [Z.AI thinking 与保留 thinking](/zh-CN/providers/zai#thinking-and-preserved-thinking)。
- `agentRuntime`：默认低级智能体运行时策略。省略的 ID 默认使用 OpenClaw Pi。使用 `id: "pi"` 强制内置 PI harness，使用 `id: "auto"` 让已注册插件 harness 认领受支持的模型，使用已注册 harness ID（如 `id: "codex"`），或使用受支持的 CLI 后端别名（如 `id: "claude-cli"`）。设置 `fallback: "none"` 可禁用自动 PI 回退。显式插件运行时（如 `codex`）默认关闭失败，除非你在同一覆盖范围内设置 `fallback: "pi"`。保持模型引用为规范的 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧版运行时提供商前缀。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，了解它与提供商/模型选择的区别。
- 会改写这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及备用添加/移除命令）会保存规范对象形式，并尽可能保留现有备用列表。
- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍会串行化）。默认值：4。
- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，则额外请求体优先；非原生 completions 路由之后仍会剥离仅 OpenAI 使用的 `store`。
- `params.chat_template_kwargs`：vLLM/OpenAI 兼容的聊天模板参数，会合并到顶层 `api: "openai-completions"` 请求体中。对于关闭 thinking 的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式 `chat_template_kwargs` 会覆盖生成的默认值，且 `extra_body.chat_template_kwargs` 仍拥有最终优先级。对于 vLLM Qwen thinking 控制，在该模型条目上将 `params.qwenThinkingFormat` 设置为 `"chat-template"` 或 `"top-level"`。
- `compat.supportedReasoningEfforts`：每模型的 OpenAI 兼容推理强度列表。对于真正接受它的自定义端点，包含 `"xhigh"`；随后 OpenClaw 会在命令菜单、Gateway 网关会话行、会话补丁验证、智能体 CLI 验证和 `llm-task` 验证中，为该已配置提供商/模型暴露 `/think xhigh`。当后端需要某个规范级别对应的提供商特定值时，使用 `compat.reasoningEffortMap`。
- `params.preserveThinking`：仅 Z.AI 的 preserved thinking 选择启用项。启用后且 thinking 打开时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放先前的 `reasoning_content`；参见 [Z.AI thinking 与 preserved thinking](/zh-CN/providers/zai#thinking-and-preserved-thinking)。
- `agentRuntime`：默认低级智能体运行时策略。省略 ID 时默认使用 OpenClaw Pi。使用 `id: "pi"` 强制使用内置 PI harness，使用 `id: "auto"` 让已注册的插件 harness 声明支持的模型并在没有匹配时使用 PI，使用已注册 harness ID（例如 `id: "codex"`）要求使用该 harness，或使用受支持的 CLI 后端别名（例如 `id: "claude-cli"`）。显式插件运行时在 harness 不可用或失败时会关闭失败。保持模型引用为规范的 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧版运行时提供商前缀。关于它与提供商/模型选择的区别，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及后备添加/移除命令）会保存规范对象形式，并在可能时保留现有后备列表。
- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话内部仍会串行化）。默认值：4。
### `agents.defaults.agentRuntime`
`agentRuntime` 控制哪个低级执行器运行智能体轮次。大多数
部署应保留默认 OpenClaw Pi 运行时。当可信
插件提供原生 harness（例如内置 Codex app-server harness）时使用它，
或者当你想使用受支持的 CLI 后端（例如 Claude CLI）时使用它。关于心智
插件提供原生 harness（例如内置 Codex 应用服务器 harness）时使用它，
或者在你需要受支持的 CLI 后端（例如 Claude CLI）时使用它。关于心智
模型，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
```json5
@ -418,23 +398,22 @@ Skills 提示词预算的按智能体覆盖项。
model: "openai/gpt-5.5",
agentRuntime: {
id: "codex",
fallback: "none",
},
},
},
}
```
- `id`：`"auto"`、`"pi"`、已注册插件 harness ID，或受支持的 CLI 后端别名。内置 Codex 插件注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。
- `fallback`：`"pi"` 或 `"none"`。在 `id: "auto"` 中，省略的 fallback 默认为 `"pi"`，以便旧配置在没有插件 harness 认领运行时继续使用 PI。在显式插件运行时模式中，例如 `id: "codex"`，省略的 fallback 默认为 `"none"`，因此缺少 harness 会失败，而不是静默使用 PI。运行时覆盖不会从更广范围继承 fallback；当你有意需要该兼容性回退时，请在显式运行时旁设置 `fallback: "pi"`。选定插件 harness 的失败始终会直接暴露。
- 环境覆盖：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 覆盖 `id`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 覆盖该进程的 fallback。
- 对于仅 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。你也可以显式设置 `agentRuntime.fallback: "none"` 以提高可读性；它是显式插件运行时的默认值。
- 对于 Claude CLI 部署，优先使用 `model: "anthropic/claude-opus-4-7"` 加 `agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 模型引用仍可用于兼容，但新配置应保持提供商/模型选择规范，并将执行后端放在 `agentRuntime.id` 中。
- `id`：`"auto"`、`"pi"`、已注册的插件 harness ID，或受支持的 CLI 后端别名。内置 Codex 插件注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。
- `id: "auto"` 让已注册的插件 harness 声明支持的轮次，并在没有 harness 匹配时使用 PI。显式插件运行时（例如 `id: "codex"`）要求使用该 harness，并在它不可用或失败时关闭失败。
- 环境覆盖：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 会覆盖该进程的 `id`。
- 对于仅 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。
- 对于 Claude CLI 部署，建议使用 `model: "anthropic/claude-opus-4-7"` 加 `agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 模型引用仍可兼容工作，但新配置应保持提供商/模型选择规范，并将执行后端放在 `agentRuntime.id` 中。
- 旧版运行时策略键会由 `openclaw doctor --fix` 重写为 `agentRuntime`。
- 首次嵌入式运行后，harness 选择会按会话 ID 固定。配置/环境变更会影响新的或重置的会话，而不会影响现有转录。具有转录历史但没有记录固定选择的旧版会话会被视为已固定到 PI。`/status` 会报告有效运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
- 这仅控制文本智能体轮次执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。
- 第一次嵌入式运行后，harness 选择会按会话 ID 固定。配置/环境变更会影响新的或重置的会话，而不是现有 transcript。具有 transcript 历史但没有记录固定项的旧版会话会被视为固定到 PI。`/status` 会报告有效运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
- 这只控制文本智能体轮次执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们的提供商/模型设置。
**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）：
**内置别名简写**（仅在模型位于 `agents.defaults.models` 中时适用）：
| 别名 | 模型 |
| ------------------- | ------------------------------------------ |
@ -450,12 +429,12 @@ Skills 提示词预算的按智能体覆盖项。
你配置的别名始终优先于默认值。
Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。
Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设置为 `false` 可将其禁用。
Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adaptive` 思考。
Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设置为 `false` 可禁用它。
Anthropic Claude 4.6 模型在未设置明确思考级别时默认使用 `adaptive` 思考。
### `agents.defaults.cliBackends`
用于纯文本回退运行的可选 CLI 后端（无工具调用）。在 API 提供商失败时可作为备用方案。
用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，可作为备用方案。
```json5
{
@ -486,11 +465,11 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
- CLI 后端以文本优先；工具始终禁用。
- 设置 `sessionArg` 时支持会话。
- 当 `imageArg` 接受文件路径时，支持图片透传。
- 当 `imageArg` 接受文件路径时，支持图像透传。
### `agents.defaults.systemPromptOverride`
将整个 OpenClaw 组装的系统提示词替换为固定字符串。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅包含空白字符的值会被忽略。适用于受控提示词实验。
用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅包含空白的值会被忽略。适用于受控提示词实验。
```json5
{
@ -504,7 +483,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
### `agents.defaults.promptOverlays`
按模型族应用的、与提供商无关的提示词叠加层。GPT-5 家族模型 ID 会跨提供商接收共享行为契约；`personality` 仅控制友好的交互风格层。
按模型族应用的、与提供商无关的提示词叠加层。GPT-5 族模型 ID 会在不同提供商之间获得共享行为契约；`personality` 只控制友好的交互风格层。
```json5
{
@ -521,12 +500,12 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
```
- `"friendly"`（默认）和 `"on"` 启用友好的交互风格层。
- `"off"` 仅禁用友好层；带标记的 GPT-5 行为契约仍保持启用。
- `"off"` 只禁用友好层；带标签的 GPT-5 行为契约仍保持启用。
- 当此共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。
### `agents.defaults.heartbeat`
周期性 Heartbeat 运行。
定期 Heartbeat 运行。
```json5
{
@ -554,16 +533,16 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
}
```
- `every`：时长字符串（ms/s/m/h）。默认：`30m`（API key 凭证）或 `1h`（OAuth 凭证）。设为 `0m` 可禁用。
- `includeSystemPromptSection`：为 false 时，会从系统提示词中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认：`true`。
- `suppressToolErrorWarnings`：为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。
- `timeoutSeconds`：Heartbeat 智能体回合在被中止前允许的最长秒数。未设置时使用 `agents.defaults.timeoutSeconds`。
- `directPolicy`：直连/私信投递策略。`allow`（默认）允许投递到直连目标。`block` 会抑制投递到直连目标并发出 `reason=dm-blocked`。
- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。
- `includeSystemPromptSection`：为 false 时，会从系统提示词中省略 Heartbeat 章节，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。
- `suppressToolErrorWarnings`：为 true 时，在 Heartbeat 运行期间抑制工具错误警告载荷。
- `timeoutSeconds`：Heartbeat 智能体回合被中止前允许的最长秒数。未设置时使用 `agents.defaults.timeoutSeconds`。
- `directPolicy`：直接/私信投递策略。`allow`（默认）允许投递到直接目标。`block` 会抑制直接目标投递并发出 `reason=dm-blocked`。
- `lightContext`：为 true 时，Heartbeat 运行使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。
- `isolatedSession`：为 true 时，每次 Heartbeat 都在没有先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 的隔离模式相同。将每次 Heartbeat 的 token 成本从约 100K 降至约 2-5K token。
- `skipWhenBusy`：为 true 时，Heartbeat 运行会因额外忙碌通道而推迟：子智能体或嵌套命令工作。即使没有此标志，cron 通道也始终会推迟 Heartbeat。
- `isolatedSession`：为 true 时，每次 Heartbeat 都在没有先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同隔离模式。将每次 Heartbeat 的 token 成本从约 100K 降至约 2-5K token。
- `skipWhenBusy`：为 true 时，Heartbeat 运行会在额外忙碌通道上延后：子智能体或嵌套命令工作。即使没有此标志，Cron 通道也始终会延后 Heartbeat。
- 按智能体：设置 `agents.list[].heartbeat`。当任何智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。
- Heartbeat 会运行完整的智能体回合 — 更短的间隔会消耗更多 token。
- Heartbeat 会运行完整的智能体回合，间隔越短消耗的 token 越多。
### `agents.defaults.compaction`
@ -599,19 +578,19 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
}
```
- `mode`：`default` 或 `safeguard`（用于长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。
- `provider`：已注册压缩提供商插件的 ID。设置后，会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时回退到内置摘要。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
- `timeoutSeconds`：单次压缩操作在 OpenClaw 中止前允许的最长秒数。默认：`900`。
- `keepRecentTokens`：用于逐字保留最新转录尾部的 Pi 截断点预算。手动 `/compact` 在显式设置时会遵循此值；否则手动压缩是硬检查点。
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要期间前置内置的不透明标识符保留指导。
- `mode`：`default` 或 `safeguard`（用于长历史的分块摘要）。参见 [压缩](/zh-CN/concepts/compaction)。
- `provider`：已注册压缩提供商插件的 ID。设置后，将调用提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [压缩](/zh-CN/concepts/compaction)。
- `timeoutSeconds`：OpenClaw 中止单次压缩操作前允许的最长秒数。默认值：`900`。
- `keepRecentTokens`：用于逐字保留最近转录尾部的 Pi 截断点预算。手动 `/compact` 在明确设置时会遵循此项；否则手动压缩是硬检查点。
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要期间前置内置的不透明标识符保留指南。
- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。
- `qualityGuard`：针对 safeguard 摘要的格式异常输出重试检查。safeguard 模式默认启用；设置 `enabled: false` 可跳过审计。
- `midTurnPrecheck`：可选的 Pi 工具循环压力检查。当 `enabled: true` 时，OpenClaw 会在附加工具结果后、下一次模型调用前检查上下文压力。如果上下文不再适配，它会在提交提示词前中止当前尝试，并复用现有预检查恢复路径来截断工具结果，或进行压缩后重试。适用于 `default` 和 `safeguard` 两种压缩模式。默认：禁用。
- `postCompactionSections`：压缩后要重新注入的可选 AGENTS.md H2/H3 章节名称。默认为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置或显式设置为该默认对时，旧版 `Every Session`/`Safety` 标题也会作为兼容回退被接受。
- `qualityGuard`：用于 safeguard 摘要的格式异常输出重试检查。在 safeguard 模式中默认启用；设置 `enabled: false` 可跳过审计。
- `midTurnPrecheck`：可选的 Pi 工具循环压力检查。当 `enabled: true` 时，OpenClaw 会在追加工具结果后、下一次模型调用前检查上下文压力。如果上下文不再适配，它会在提交提示词前中止当前尝试，并复用现有的预检查恢复路径来截断工具结果，或进行压缩后重试。适用于 `default` 和 `safeguard` 两种压缩模式。默认：禁用。
- `postCompactionSections`：压缩后要重新注入的可选 AGENTS.md H2/H3 章节名称。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置或明确设置为该默认组合时，也会接受旧版 `Every Session`/`Safety` 标题作为旧版回退。
- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型、但压缩摘要应在另一个模型上运行时使用；未设置时，压缩使用会话的主模型。
- `maxActiveTranscriptBytes`：可选字节阈值（`number` 或类似 `"20mb"` 的字符串），当活动 JSONL 超过该阈值时，会在运行前触发普通本地压缩。需要 `truncateAfterCompaction`，以便成功压缩后可以轮转到更小的后继转录。未设置或为 `0` 时禁用。
- `notifyUser`：为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如，“正在压缩上下文...”和“压缩完成”）。默认禁用，以保持压缩静默。
- `memoryFlush`：自动压缩前的静默 agentic 回合，用于存储持久记忆。当此维护回合应停留在本地模型上时，将 `model` 设置为精确的提供商/模型，例如 `ollama/qwen3:8b`；该覆盖不会继承活动会话回退链。工作区为只读时跳过。
- `maxActiveTranscriptBytes`：可选字节阈值（`number` 或类似 `"20mb"` 的字符串），当活跃 JSONL 超过该阈值时，会在运行前触发常规本地压缩。需要 `truncateAfterCompaction`，以便成功压缩后可以轮换到更小的后继转录。未设置或为 `0` 时禁用。
- `notifyUser`：为 `true` 时，在压缩开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认禁用，以保持压缩静默。
- `memoryFlush`：自动压缩前用于存储持久记忆的静默智能体回合。当此维护回合应停留在本地模型上时，将 `model` 设置为精确的提供商/模型，例如 `ollama/qwen3:8b`；该覆盖不会继承活跃会话的回退链。当工作区为只读时跳过。
### `agents.defaults.contextPruning`
@ -637,25 +616,25 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
}
```
<Accordion title="cache-ttl mode behavior">
<Accordion title="cache-ttl 模式行为">
- `mode: "cache-ttl"` 启用修剪过程。
- `ttl` 控制修剪多久可以再次运行（在上次缓存触达之后）。
- `ttl` 控制修剪多久可以再次运行（在上次缓存触碰之后）。
- 修剪会先软修剪过大的工具结果，然后在需要时硬清除更旧的工具结果。
**软修剪**会保留开头 + 结尾，并在中间插入 `...`。
**硬清除**会用占位符替换整个工具结果。
注意：
注意事项：
- 图片块永远不会被修剪/清除。
- 比率基于字符（近似），不是精确 token 计数。
- 如果助手消息少于 `keepLastAssistants` 条，则跳过修剪。
- 图像块永远不会被修剪/清除。
- 比率基于字符（近似），不是精确 token 数。
- 如果存在的 assistant 消息少于 `keepLastAssistants`，则跳过修剪。
</Accordion>
行为详情见 [Session Pruning](/zh-CN/concepts/session-pruning)。
有关行为详情，请参见 [会话修剪](/zh-CN/concepts/session-pruning)。
### 分块流式传输
@ -674,10 +653,10 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
```
- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。
- 渠道覆盖项：`channels.<channel>.blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。
请参阅 [流式传输](/zh-CN/concepts/streaming)，了解行为和分块详情。
有关行为和分块详情，请参见 [流式传输](/zh-CN/concepts/streaming)。
### 输入指示器
@ -695,13 +674,13 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
- 默认值：直接聊天/提及时为 `instant`，未提及的群聊为 `message`。
- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。
请参阅 [输入指示器](/zh-CN/concepts/typing-indicators)。
参见[输入状态指示器](/zh-CN/concepts/typing-indicators)。
<a id="agentsdefaultssandbox"></a>
### `agents.defaults.sandbox`
嵌入式智能体的可选沙箱隔离。完整指南请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。
嵌入式智能体的可选沙箱隔离。完整指南见[沙箱隔离](/zh-CN/gateway/sandboxing)。
```json5
{
@ -804,36 +783,36 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
- `ssh`：通用 SSH 支持的远程运行时
- `openshell`：OpenShell 运行时
选择 `backend: "openshell"` 时，运行时专用设置会移动到
选择 `backend: "openshell"` 时，运行时专用设置会移至
`plugins.entries.openshell.config`。
**SSH 后端配置：**
- `target`：`user@host[:port]` 形式的 SSH 目标
- `target`：`user@host[:port]` 格式的 SSH 目标
- `command`：SSH 客户端命令（默认：`ssh`）
- `workspaceRoot`：用于按作用域工作区的绝对远程根目录
- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时物化为临时文件的内联内容或 SecretRefs
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关
- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时具现化为临时文件的内联内容或 SecretRef
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略旋钮
**SSH 凭证优先级：**
**SSH 认证优先级：**
- `identityData` 优先于 `identityFile`
- `certificateData` 优先于 `certificateFile`
- `knownHostsData` 优先于 `knownHostsFile`
- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从活跃的密钥运行时快照中解析
- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前，从活动的密钥运行时快照解析
**SSH 后端行为：**
- 创建或重新创建后，会为远程工作区播种一次
- 然后保持远程 SSH 工作区为权威副本
- 创建或重新创建后，对远程工作区进行一次种子填充
- 随后保持远程 SSH 工作区为权威副本
- 通过 SSH 路由 `exec`、文件工具和媒体路径
- 不会自动将远程更改同步回主机
- 不会自动将远程变更同步回主机
- 不支持沙箱浏览器容器
**工作区访问：**
- `none`：`~/.openclaw/sandboxes` 下的按作用域沙箱工作区
- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区
- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent`
- `rw`：智能体工作区以读/写方式挂载到 `/workspace`
@ -871,30 +850,30 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
**OpenShell 模式：**
- `mirror`：执行前从本地播种到远程，执行后同步回来；本地工作区保持为权威副本
- `remote`：创建沙箱时播种远程一次，然后保持远程工作区为权威副本
- `mirror`：执行前从本地向远程种子填充，执行后同步回来；本地工作区保持为权威副本
- `remote`：创建沙箱时对远程进行一次种子填充，之后保持远程工作区为权威副本
在 `remote` 模式下，播种步骤之后，在 OpenClaw 外部进行的主机本地编辑不会自动同步到沙箱中。
传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。
在 `remote` 模式下，种子填充步骤之后，在 OpenClaw 外部进行的主机本地编辑不会自动同步进沙箱。
传输方式是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期和可选的镜像同步。
**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根目录和 root 用户。
**`setupCommand`** 在容器创建后运行一次（通过 `sh -lc`）。需要网络出站、可写根目录、root 用户。
**容器默认使用 `network: "none"`** — 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。
`"host"` 被阻止。默认情况下 `"container:<id>"` 被阻止，除非你显式设置
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（应急开关）。
`"host"` 会被阻止。默认情况下，`"container:<id>"` 也会被阻止，除非你显式设置
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（应急破玻璃）。
**入站附件** 会暂存到活跃工作区中的 `media/inbound/*`。
**入站附件** 会暂存到活动工作区中的 `media/inbound/*`。
**`docker.binds`** 会挂载其他主机目录；全局绑定和按智能体绑定会合并。
**`docker.binds`** 挂载额外的主机目录；全局绑定和按智能体绑定会合并。
**沙箱浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。
noVNC 观察者访问默认使用 VNC 认证，并且 OpenClaw 会发出短期有效的令牌 URL（而不是在共享 URL 中暴露密码）。
**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示词。不需要在 `openclaw.json` 中启用 `browser.enabled`。
noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会生成短期有效的令牌 URL（而不是在共享 URL 中暴露密码）。
- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。
- `network` 默认使用 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确需要全局桥接连通性时，才设置为 `bridge`。
- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制到一个 CIDR 范围（例如 `172.21.0.1/32`）。
- `sandbox.browser.binds` 只会把其他主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机调优：
- `allowHostControl: false`（默认）会阻止沙箱隔离会话将主机浏览器作为目标。
- `network` 默认值为 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确需要全局桥接连通性时才设置为 `bridge`。
- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制为一个 CIDR 范围（例如 `172.21.0.1/32`）。
- `sandbox.browser.binds` 仅将额外的主机目录挂载进沙箱浏览器容器。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优：
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
- `--user-data-dir=${HOME}/.chrome`
@ -913,38 +892,37 @@ noVNC 观察者访问默认使用 VNC 认证，并且 OpenClaw 会发出短期
- `--metrics-recording-only`
- `--disable-extensions`（默认启用）
- `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
默认启用；如果 WebGL/3D 使用需要它们，可以通过
默认启用；如果 WebGL/3D 使用需要，可以通过
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用。
- 如果你的工作流依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。
- `--renderer-process-limit=2` 可以通过
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 更改；设置为 `0` 可使用 Chromium 的
默认进程限制。
- 当启用 `noSandbox` 时，还会加上 `--no-sandbox`。
- 默认值是容器镜像基线；要更改容器默认值，请使用带有自定义
- 默认值是容器镜像基线；若要更改容器默认值，请使用带有自定义
入口点的自定义浏览器镜像。
</Accordion>
浏览器沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。
构建镜像（从源码检出目录）：
构建镜像（从源码检出）：
```bash
scripts/sandbox-setup.sh # main sandbox image
scripts/sandbox-browser-setup.sh # optional browser image
```
对于没有源码检出目录的 npm 安装，请参阅 [沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)，了解内联 `docker build` 命令。
对于没有源码检出的 npm 安装，内联 `docker build` 命令见[沙箱隔离 § 镜像与设置](/zh-CN/gateway/sandboxing#images-and-setup)。
### `agents.list`（按智能体覆盖）
使用 `agents.list[].tts` 为某个智能体指定自己的 TTS 提供商、语音、模型、
使用 `agents.list[].tts` 为智能体指定自己的 TTS 提供商、语音、模型、
风格或自动 TTS 模式。智能体块会深度合并到全局
`messages.tts` 之上，因此共享凭证可以保留在一个位置，而各个
智能体只覆盖它们需要的语音或提供商字段。活跃智能体的
覆盖适用于自动语音回复、`/tts audio`、`/tts status` 和
`tts` 智能体工具。请参阅 [文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides)，
了解提供商示例和优先级。
`messages.tts` 之上，因此共享凭证可以保留在一个位置，而单个
智能体只覆盖它们需要的语音或提供商字段。活动智能体的
覆盖会应用于自动语音回复、`/tts audio`、`/tts status` 和
`tts` 智能体工具。提供商示例和优先级见[文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides)。
```json5
{
@ -960,7 +938,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
thinkingDefault: "high", // per-agent thinking level override
reasoningDefault: "on", // per-agent reasoning visibility override
fastModeDefault: false, // per-agent fast mode override
agentRuntime: { id: "auto", fallback: "pi" },
agentRuntime: { id: "auto" },
params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
tts: {
providers: {
@ -998,28 +976,28 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
- `id`：稳定的智能体 ID（必填）。
- `default`：设置多个时，第一个生效（会记录警告）。如果未设置，则列表中的第一项为默认项。
- `model`：字符串形式会为每个智能体设置严格的主模型，不带模型回退；对象形式 `{ primary }` 也同样严格，除非你添加 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 可让该智能体启用回退，或使用 `{ primary, fallbacks: [] }` 明确启用严格行为。仅覆盖 `primary` 的 Cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。
- `params`：每个智能体的流参数，会覆盖合并到 `agents.defaults.models` 中选中的模型条目。可用它为智能体设置专属覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，无需复制整个模型目录。
- `tts`：可选的每个智能体文本转语音覆盖项。该块会深度合并到 `messages.tts` 之上，因此请将共享的提供商凭证和回退策略保留在 `messages.tts`，并只在此处设置人设专属值，例如提供商、语音、模型、风格或自动模式。
- `skills`：可选的每个智能体 Skills 允许列表。如果省略，智能体会在设置了 `agents.defaults.skills` 时继承它；显式列表会替换默认项而不是合并，`[]` 表示不使用 Skills。
- `thinkingDefault`：可选的每个智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置每条消息或会话覆盖项时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。选中的提供商/模型配置决定哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商拥有的动态思考（Gemini 3/3.1 中省略 `thinkingLevel`，Gemini 2.5 中使用 `thinkingBudget: -1`）。
- `reasoningDefault`：可选的每个智能体默认推理可见性（`on | off | stream`）。当未设置每条消息或会话推理覆盖项时，会覆盖该智能体的 `agents.defaults.reasoningDefault`。
- `fastModeDefault`：可选的每个智能体快速模式默认值（`true | false`）。当未设置每条消息或会话快速模式覆盖项时适用。
- `agentRuntime`：可选的每个智能体底层运行时策略覆盖项。使用 `{ id: "codex" }` 可让一个智能体仅使用 Codex，而其他智能体在 `auto` 模式中保留默认的 PI 回退。
- `runtime`：可选的每个智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
- `identity.avatar`：相对于工作区的路径、`http(s)` URL 或 `data:` URI。
- `identity` 会派生默认值：从 `emoji` 派生 `ackReaction`，从 `name`/`emoji` 派生 `mentionPatterns`。
- `subagents.allowAgents`：用于显式 `sessions_spawn.agentId` 目标的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。当应允许以自身为目标的 `agentId` 调用时，请包含请求者 ID。
- 沙箱继承保护：如果请求者会话已沙箱隔离，`sessions_spawn` 会拒绝那些将以非沙箱隔离方式运行的目标。
- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。
- `id`: 稳定智能体 id（必需）。
- `default`: 设置了多个时，第一个生效（会记录警告）。如果未设置，列表中的第一个条目为默认值。
- `model`: 字符串形式会为每个智能体设置严格主模型，且没有模型回退；对象形式 `{ primary }` 也同样严格，除非你添加 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 可让该智能体启用回退，或使用 `{ primary, fallbacks: [] }` 显式采用严格行为。仅覆盖 `primary` 的 Cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。
- `params`: 每个智能体的流参数，会合并覆盖 `agents.defaults.models` 中选定的模型条目。使用它可为智能体设置特定覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。
- `tts`: 可选的每个智能体文本转语音覆盖项。该块会深度合并覆盖 `messages.tts`，因此请将共享提供商凭证和回退策略保留在 `messages.tts` 中，并仅在此处设置角色特定值，例如提供商、voice、模型、style 或自动模式。
- `skills`: 可选的每个智能体 Skills 允许列表。如果省略，智能体会在设置后继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。
- `thinkingDefault`: 可选的每个智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置每条消息或会话覆盖时，会为此智能体覆盖 `agents.defaults.thinkingDefault`。选定的提供商/模型配置文件会控制哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商拥有的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。
- `reasoningDefault`: 可选的每个智能体默认推理可见性（`on | off | stream`）。当未设置每条消息或会话推理覆盖时，会为此智能体覆盖 `agents.defaults.reasoningDefault`。
- `fastModeDefault`: 可选的每个智能体快速模式默认值（`true | false`）。当未设置每条消息或会话快速模式覆盖时适用。
- `agentRuntime`: 可选的每个智能体低层运行时策略覆盖。使用 `{ id: "codex" }` 可让一个智能体仅使用 Codex，同时其他智能体在 `auto` 模式下保持默认 PI 回退。
- `runtime`: 可选的每个智能体运行时描述符。当智能体应默认使用 ACP 运行框架会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
- `identity.avatar`: 工作区相对路径、`http(s)` URL 或 `data:` URI。
- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。
- `subagents.allowAgents`: 用于显式 `sessions_spawn.agentId` 目标的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。当应允许面向自身的 `agentId` 调用时，请包含请求者 id。
- 沙箱继承保护：如果请求者会话是沙箱隔离的，`sessions_spawn` 会拒绝将以非沙箱隔离方式运行的目标。
- `subagents.requireAgentId`: 为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。
---
## 多智能体路由
在一个 Gateway 网关内运行多个隔离的智能体。请参阅 [多智能体](/zh-CN/concepts/multi-agent)。
在一个 Gateway 网关内运行多个隔离智能体。请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent)。
```json5
{
@ -1038,11 +1016,11 @@ scripts/sandbox-browser-setup.sh # optional browser image
### 绑定匹配字段
- `type`（可选）：`route` 用于普通路由（缺少 type 时默认使用 route），`acp` 用于持久 ACP 对话绑定。
- `match.channel`（必填）
- `type`（可选）：`route` 用于普通路由（缺失 type 时默认为 route），`acp` 用于持久 ACP 对话绑定。
- `match.channel`（必需）
- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号）
- `match.peer`（可选；`{ kind: direct|group|channel, id }`）
- `match.guildId` / `match.teamId`（可选；渠道专属）
- `match.guildId` / `match.teamId`（可选；特定渠道）
- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }`
**确定性匹配顺序：**
@ -1050,15 +1028,15 @@ scripts/sandbox-browser-setup.sh # optional browser image
1. `match.peer`
2. `match.guildId`
3. `match.teamId`
4. `match.accountId`（精确匹配，无 peer/guild/team）
5. `match.accountId: "*"`（整个渠道）
4. `match.accountId`（精确，无 peer/guild/team）
5. `match.accountId: "*"`（全渠道）
6. 默认智能体
在每一层级内，第一个匹配的 `bindings` 条目生效。
对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的路由绑定层级顺序。
对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + 账号 + `match.peer.id`）解析，并且不使用上面的 route 绑定层级顺序。
### 每个智能体访问配置文件
### 每智能体访问配置文件
<Accordion title="完全访问（无沙箱）">
@ -1107,7 +1085,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
</Accordion>
<Accordion title="无文件系统访问（仅消息）">
<Accordion title="无文件系统访问权限（仅消息传递）">
```json5
{
@ -1153,7 +1131,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
</Accordion>
有关优先级详情，请参阅 [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools)。
有关优先级详情，请参阅 [多智能体沙箱和工具](/zh-CN/tools/multi-agent-sandbox-tools)。
---
@ -1209,29 +1187,29 @@ scripts/sandbox-browser-setup.sh # optional browser image
- `global`：一个渠道上下文中的所有参与者共享单个会话（仅在需要共享上下文时使用）。
- **`dmScope`**：私信的分组方式。
- `main`：所有私信共享主会话。
- `per-peer`：跨渠道按发送者 id 隔离。
- `per-peer`：跨渠道按发送者 ID 隔离。
- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
- `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。
- **`identityLinks`**：将规范 id 映射到带提供商前缀的对端，用于跨渠道共享会话。`/dock_discord` 等 Dock 命令使用同一映射，将活动会话的回复路由切换到另一个已链接的渠道对端；参见 [渠道停靠](/zh-CN/concepts/channel-docking)。
- **`reset`**：主重置策略。`daily` 在 `atHour` 本地时间重置；`idle` 在 `idleMinutes` 后重置。两者同时配置时，先到期者生效。每日重置的新鲜度使用会话行的 `sessionStartedAt`；空闲重置的新鲜度使用 `lastInteractionAt`。heartbeat、cron 唤醒、exec 通知和 Gateway 网关记账等后台/系统事件写入可以更新 `updatedAt`，但它们不会让每日/空闲会话保持新鲜。
- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 作为 `direct` 的别名被接受。
- **`mainKey`**：旧版字段。运行时始终使用 `"main"` 作为主直接聊天存储桶。
- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间，智能体之间的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 会禁用往返链式回复。
- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则生效。
- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，用于跨渠道会话共享。诸如 `/dock_discord` 之类的停靠命令会使用同一个映射，把当前会话的回复路由切换到另一个已关联的渠道对端；请参阅[渠道停靠](/zh-CN/concepts/channel-docking)。
- **`reset`**：主要重置策略。`daily` 在本地时间 `atHour` 重置；`idle` 在 `idleMinutes` 后重置。两者都配置时，先过期者生效。每日重置新鲜度使用会话行的 `sessionStartedAt`；空闲重置新鲜度使用 `lastInteractionAt`。Heartbeat、cron 唤醒、exec 通知和 Gateway 网关记账等后台/系统事件写入可以更新 `updatedAt`，但它们不会让每日/空闲会话保持新鲜。
- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。
- **`mainKey`**：旧版字段。运行时始终对主直接聊天桶使用 `"main"`。
- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间，智能体之间的最大来回复轮数（整数，范围：`0`–`5`）。`0` 会禁用来回链式回复。
- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，含旧版 `dm` 别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则生效。
- **`maintenance`**：会话存储清理 + 保留控制。
- `mode`：`warn` 仅发出警告；`enforce` 会执行清理。
- `mode`：`warn` 仅发出警告；`enforce` 应用清理。
- `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。
- `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。对于生产规模的上限，运行时写入批量清理时会保留一个小的高水位缓冲；`openclaw sessions cleanup --enforce` 会立即应用该上限。
- `rotateBytes`：已弃用并被忽略；`openclaw doctor --fix` 会将其从旧配置中移除。
- `resetArchiveRetention`：`*.reset.<timestamp>` 记录归档的保留期。默认使用 `pruneAfter`；设为 `false` 可禁用。
- `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会先删除最旧的构件/会话。
- `highWaterBytes`：预算清理后的可选目标。默认是 `maxDiskBytes` 的 `80%`。
- `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时会为生产规模的上限写入带小型高水位缓冲区的批量清理；`openclaw sessions cleanup --enforce` 会立即应用上限。
- `rotateBytes`：已弃用且会被忽略；`openclaw doctor --fix` 会将其从较旧配置中移除。
- `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留期。默认为 `pruneAfter`；设置为 `false` 可禁用。
- `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会先移除最旧的工件/会话。
- `highWaterBytes`：预算清理后的可选目标。默认为 `maxDiskBytes` 的 `80%`。
- **`threadBindings`**：线程绑定会话功能的全局默认值。
- `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
- `idleHours`：默认不活动自动取消聚焦时间，单位为小时（`0` 禁用；提供商可以覆盖）
- `maxAgeHours`：默认硬性最长年龄，单位为小时（`0` 禁用；提供商可以覆盖）
- `spawnSessions`：从 `sessions_spawn` 和 ACP 线程生成创建线程绑定工作会话的默认门控。线程绑定启用时默认为 `true`；提供商/账号可以覆盖。
- `defaultSpawnContext`：线程绑定生成的默认原生子智能体上下文（`"fork"` 或 `"isolated"`）。默认是 `"fork"`。
- `idleHours`：默认空闲自动取消聚焦时间，单位为小时（`0` 禁用；提供商可以覆盖）
- `maxAgeHours`：默认硬性最大年龄，单位为小时（`0` 禁用；提供商可以覆盖）
- `spawnSessions`：通过 `sessions_spawn` 和 ACP 线程生成创建线程绑定工作会话的默认门控。启用线程绑定时默认为 `true`；提供商/账号可以覆盖。
- `defaultSpawnContext`：线程绑定生成的默认原生子智能体上下文（`"fork"` 或 `"isolated"`）。默认为 `"fork"`。
</Accordion>
@ -1267,38 +1245,38 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
### 回复前缀
### 响应前缀
按渠道/账号覆盖：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
按渠道/账号的覆盖项：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
解析顺序（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。
解析规则（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生出 `[{identity.name}]`。
**模板变量：**
| 变量 | 描述 | 示例 |
| ----------------- | ---------------- | --------------------------- |
| `{model}` | 短模型名称 | `claude-opus-4-6` |
| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
| `{provider}` | 提供商名称 | `anthropic` |
| `{thinkingLevel}` | 当前思考级别 | `high`, `low`, `off` |
| `{identity.name}` | 智能体身份名称 |（与 `"auto"` 相同） |
| 变量 | 描述 | 示例 |
| ----------------- | -------------------- | --------------------------- |
| `{model}` | 短模型名称 | `claude-opus-4-6` |
| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
| `{provider}` | 提供商名称 | `anthropic` |
| `{thinkingLevel}` | 当前思考级别 | `high`, `low`, `off` |
| `{identity.name}` | 智能体 identity 名称 | （与 `"auto"` 相同） |
变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。
### 确认反应
### 确认响应
- 默认使用活动智能体的 `identity.emoji`，否则使用 `"👀"`。设为 `""` 可禁用。
- 按渠道覆盖：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
- 解析顺序：账号 → 渠道 → `messages.ackReaction` → 身份回退。
- 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。
- `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles 等支持反应的渠道上，回复后移除确认反应。
- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期 Status 反应。
在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则会保持 Status 反应启用。
在 Telegram 上，显式设为 `true` 才能启用生命周期 Status 反应。
- 默认使用当前智能体的 `identity.emoji`，否则使用 `"👀"`。设置为 `""` 可禁用。
- 按渠道覆盖项：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。
- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。
- `removeAckAfterReply`：在支持响应的渠道（例如 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles）上，回复后移除确认响应。
- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期 Status 响应。
在 Slack 和 Discord 上，未设置时，如果确认响应处于启用状态，则保持 Status 响应启用。
在 Telegram 上，需要显式设置为 `true` 才能启用生命周期 Status 响应。
### 入站防抖
将同一发送者快速发送的纯文本消息批处理为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
将同一发送者快速发送的纯文本消息合并为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
### TTS（文本转语音）
@ -1348,19 +1326,19 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示有效状态。
- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好设置，`/tts status` 会显示生效状态。
- `summaryModel` 会为自动摘要覆盖 `agents.defaults.model.primary`。
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认是 `false`（选择加入）。
- API 密钥会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
- 内置语音提供商由插件拥有。如果设置了 `plugins.allow`，请包含你想使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` 提供商 id 会作为 `microsoft` 的别名被接受。
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（选择启用）。
- API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
- 内置语音提供商归插件所有。如果设置了 `plugins.allow`，请包含你想使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` 提供商 id 会作为 `microsoft` 的别名被接受。
- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，然后是 `https://api.openai.com/v1`。
- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音验证。
- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型/语音验证。
---
## 语音对话
## Talk
语音对话模式（macOS/iOS/Android）的默认值。
Talk 模式（macOS/iOS/Android）的默认值。
```json5
{
@ -1389,16 +1367,16 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
- 配置多个语音对话提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。
- 旧版扁平语音对话键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.<provider>`。
- 配置多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的一个键。
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.<provider>`。
- 语音 ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
- `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。
- `ELEVENLABS_API_KEY` 回退仅在未配置语音对话 API 密钥时适用。
- `providers.*.voiceAliases` 让语音对话指令可以使用友好名称。
- `providers.mlx.modelId` 选择 macOS 本地 MLX 辅助程序使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。
- macOS MLX 播放会通过内置的 `openclaw-mlx-tts` 辅助程序（如果存在）运行，或通过 `PATH` 上的可执行文件运行；`OPENCLAW_MLX_TTS_BIN` 会为开发覆盖辅助程序路径。
- `speechLocale` 设置 iOS/macOS 语音对话语音识别使用的 BCP 47 区域设置 id。留空则使用设备默认值。
- `silenceTimeoutMs` 控制语音对话模式在用户静默后等待多久再发送转录。未设置时保持平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。
- `ELEVENLABS_API_KEY` 回退仅在未配置 Talk API key 时适用。
- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。
- `providers.mlx.modelId` 选择 macOS 本地 MLX helper 使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。
- macOS MLX 播放会在存在时通过内置的 `openclaw-mlx-tts` helper 运行，或使用 `PATH` 上的可执行文件；`OPENCLAW_MLX_TTS_BIN` 会覆盖开发用 helper 路径。
- `speechLocale` 设置 iOS/macOS Talk 语音识别使用的 BCP 47 语言区域 id。留空则使用设备默认值。
- `silenceTimeoutMs` 控制 Talk 模式在用户沉默后等待多久再发送转写文本。未设置时会保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。
---

369
docs/zh-CN/help/testing-live.md
View File

@ -1,26 +1,29 @@
---
read_when:
- 运行真实模型矩阵 / CLI 后端 / ACP / media-provider 冒烟测试
- 运行实时模型矩阵 / CLI 后端 / ACP / 媒体提供商冒烟测试
- 调试实时测试凭证解析
- 添加新的特定于提供商的实时测试
- 添加新的提供商专用真实环境测试
sidebarTitle: Live tests
summary: 在线（会访问网络的）测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证
title: 测试：实时测试套件
summary: 实网（涉及网络访问）测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证
title: 测试：实时套件
x-i18n:
generated_at: "2026-05-02T07:52:30Z"
generated_at: "2026-05-03T04:51:08Z"
model: gpt-5.5
provider: openai
source_hash: 2268f20ce5c0bbee8bf610938851fe529f5e21fa31fe08a70400df94e9241cc3
source_hash: 4057d8875fa3404108e89e4381c1dd14e96abbc2af13c4934fc6c0dbf878fc00
source_path: help/testing-live.md
workflow: 16
---
有关快速开始、QA 运行器、单元/集成测试套件和 Docker 流程，请参见
[测试](/zh-CN/help/testing)。本页涵盖**实时**（会访问网络的）测试套件：模型矩阵、CLI 后端、ACP 和媒体提供商实时测试，以及凭证处理。
如需快速开始、QA 运行器、单元/集成套件和 Docker 流程，请参阅
[测试](/zh-CN/help/testing)。本页涵盖 **live**（会触达网络的）测试
套件：模型矩阵、CLI 后端、ACP、媒体提供商 live 测试，以及
凭证处理。
## 实时：本地 profile 冒烟命令
## Live：本地配置档冒烟测试命令
在临时实时检查前 source `~/.profile`，以便提供商密钥和本地工具路径与你的 shell 匹配：
在临时 live 检查前 source `~/.profile`，以便提供商密钥和本地工具
路径与你的 shell 匹配：
```bash
source ~/.profile
@ -41,95 +44,97 @@ pnpm openclaw voicecall setup --json
pnpm openclaw voicecall smoke --to "+15555550123"
```
除非同时带有 `--yes`，否则 `voicecall smoke` 是一次空运行。只有在你有意发起真实通知通话时才使用 `--yes`。对于 Twilio、Telnyx 和 Plivo，成功的就绪检查需要一个公开 webhook URL；local loopback/私有回退按设计会被拒绝。
`voicecall smoke` 默认是空运行，除非同时传入 `--yes`。只有在你有意发起真实通知通话时才使用 `--yes`。对于 Twilio、Telnyx 和
Plivo，成功的就绪检查需要一个公网 webhook URL；按设计会拒绝仅本地
loopback/私有回退。
## 实时：Android 节点能力扫描
## Live：Android 节点能力扫描
- 测试：`src/gateway/android-node.capabilities.live.test.ts`
- 脚本：`pnpm android:test:integration`
- 目标：调用已连接 Android 节点**当前宣告的每个命令**，并断言命令契约行为。
- 目标：调用已连接 Android 节点 **当前公布的每一个命令**，并断言命令契约行为。
- 范围：
- 带前置条件的手动设置（该套件不会安装/运行/配对应用）。
- 对选定 Android 节点逐命令执行 Gateway 网关 `node.invoke` 验证。
- 需要预置条件/手动设置（该套件不会安装/运行/配对应用）。
- 对所选 Android 节点逐个命令进行 Gateway 网关 `node.invoke` 验证。
- 必需的预先设置：
- Android 应用已连接并配对到 Gateway 网关。
- 应用保持在前台。
- 已授予你预期会通过的能力所需的权限/捕获同意。
- 已为你期望通过的能力授予权限/捕获同意。
- 可选目标覆盖：
- `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。
- 完整 Android 设置详情：[Android 应用](/zh-CN/platforms/android)
## 实时：模型冒烟测试（profile 密钥）
## Live：模型冒烟测试（配置档密钥）
实时测试拆分为两层，便于隔离故障：
Live 测试拆分为两层，便于我们隔离故障：
- “直接模型”会告诉我们给定密钥下提供商/模型本身是否能回答。
- “Gateway 网关冒烟测试”会告诉我们该模型的完整 Gateway 网关 + agent 管道是否可用（会话、历史记录、工具、沙箱策略等）。
- “直接模型”告诉我们，在给定密钥下该提供商/模型是否完全能回答。
- “Gateway 网关冒烟测试”告诉我们，该模型的完整 Gateway 网关+智能体流水线是否可用（会话、历史、工具、沙箱策略等）。
### 第 1 层：直接模型补全（无 Gateway 网关）
- 测试：`src/agents/models.profiles.live.test.ts`
- 目标：
- 枚举已发现的模型
- 使用 `getApiKeyForModel` 选择你拥有凭证的模型
- 对每个模型运行一次小型补全（并在需要时运行定向回归）
- 枚举发现的模型
- 使用 `getApiKeyForModel` 选择你已有凭证的模型
- 对每个模型运行一个小型补全（以及必要时的定向回归）
- 启用方式：
- `pnpm test:live`（或直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，作为 modern 的别名）才会实际运行此套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试
- `pnpm test:live`（或在直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）以实际运行此套件；否则它会跳过，以保持 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试
- 选择模型的方式：
- `OPENCLAW_LIVE_MODELS=modern` 运行现代允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
- `OPENCLAW_LIVE_MODELS=all` 是现代允许列表的别名
- `OPENCLAW_LIVE_MODELS=modern` 运行 modern 允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
- `OPENCLAW_LIVE_MODELS=all` 是 modern 允许列表的别名
- 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."`（逗号分隔允许列表）
- Modern/all 扫描默认使用经过策划的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可进行详尽的 modern 扫描，或设置正数作为更小的上限。
- 详尽扫描使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS` 作为整个直接模型测试超时时间。默认值：60 分钟。
- Modern/all 扫描默认使用精选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可进行详尽 modern 扫描，或设置正数以使用更小上限。
- 详尽扫描会将 `OPENCLAW_LIVE_TEST_TIMEOUT_MS` 用作整个直接模型测试超时。默认值：60 分钟。
- 直接模型探测默认以 20 路并行运行；设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY` 可覆盖。
- 选择提供商的方式：
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔允许列表）
- 密钥来源：
- 默认：profile 存储和环境变量回退
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以强制**仅使用 profile 存储**
- 默认：配置档存储和环境变量回退
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以强制 **仅使用配置档存储**
- 存在原因：
- 将“提供商 API 损坏/密钥无效”与“Gateway 网关 agent 管道损坏”分离
- 包含小型、隔离的回归测试（示例：OpenAI Responses/Codex Responses 推理重放 + 工具调用流程）
- 将“提供商 API 损坏/密钥无效”与“Gateway 网关智能体流水线损坏”分离
- 包含小型、隔离的回归（示例：OpenAI Responses/Codex Responses reasoning replay + 工具调用流程）
### 第 2 层：Gateway 网关 + 开发 agent 冒烟测试（“@openclaw” 实际执行的内容）
### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（“@openclaw”实际执行的内容）
- 测试：`src/gateway/gateway-models.profiles.live.test.ts`
- 目标：
- 启动进程内 Gateway 网关
- 创建/修补一个 `agent:dev:*` 会话（每次运行覆盖模型）
- 迭代有密钥的模型并断言：
- “有意义”的响应（无工具）
- 遍历有密钥的模型并断言：
- “有意义的”响应（无工具）
- 真实工具调用可用（读取探测）
- 可选的额外工具探测（执行 + 读取探测）
- OpenAI 回归路径（仅工具调用 → 后续回合）持续可用
- 可选的额外工具探测（执行+读取探测）
- OpenAI 回归路径（仅工具调用 → 跟进）持续可用
- 探测详情（便于你快速解释故障）：
- `read` 探测：测试在工作区写入一个 nonce 文件，并要求 agent `read` 它并回显 nonce。
- `exec+read` 探测：测试要求 agent 通过 `exec` 将 nonce 写入临时文件，然后再 `read` 读回。
- 图像探测：测试附加一个生成的 PNG（cat + 随机代码），并期望模型返回 `cat <CODE>`。
- `read` 探测：测试在工作区写入一个 nonce 文件，并要求智能体 `read` 它并回显 nonce。
- `exec+read` 探测：测试要求智能体通过 `exec` 将 nonce 写入临时文件，然后 `read` 回来。
- 图片探测：测试附加一张生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
- 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。
- 启用方式：
- `pnpm test:live`（或直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
- `pnpm test:live`（或在直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
- 选择模型的方式：
- 默认：现代允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代允许列表的别名
- 默认：modern 允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是 modern 允许列表的别名
- 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）以缩小范围
- Modern/all Gateway 网关扫描默认使用经过策划的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可进行详尽的 modern 扫描，或设置正数作为更小的上限。
- 选择提供商的方式（避免“OpenRouter 全部内容”）：
- Modern/all Gateway 网关扫描默认使用精选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可进行详尽 modern 扫描，或设置正数以使用更小上限。
- 选择提供商的方式（避免“OpenRouter everything”）：
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔允许列表）
- 工具 + 图像探测在此实时测试中始终启用：
- `read` 探测 + `exec+read` 探测（工具压力）
- 当模型宣告支持图像输入时运行图像探测
- 工具 + 图片探测在此 live 测试中始终开启：
- `read` 探测 + `exec+read` 探测（工具压力测试）
- 当模型公布支持图片输入时运行图片探测
- 流程（高层）：
- 测试生成带有“CAT”+ 随机代码的小型 PNG（`src/gateway/live-image-probe.ts`）
- 测试生成一张带有 “CAT” + 随机代码的小 PNG（`src/gateway/live-image-probe.ts`）
- 通过 `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]` 发送
- Gateway 网关将附件解析到 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
- 嵌入式 agent 将多模态用户消息转发给模型
- Gateway 网关将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
- 嵌入式智能体将多模态用户消息转发给模型
- 断言：回复包含 `cat` + 该代码（OCR 容错：允许轻微错误）
<Tip>
要查看你的机器上可以测试什么（以及精确的 `provider/model` ID），请运行：
要查看你的机器上可以测试什么（以及精确的 `provider/model` id），请运行：
```bash
openclaw models list
@ -138,27 +143,27 @@ openclaw models list --json
</Tip>
## 实时：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI）
## Live：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI）
- 测试：`src/gateway/gateway-cli-backend.live.test.ts`
- 目标：使用本地 CLI 后端验证 Gateway 网关 + agent 管道，而不触碰你的默认配置。
- 后端专用冒烟默认值位于所属插件的 `cli-backend.ts` 定义中。
- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线，且不触碰你的默认配置。
- 后端特定的冒烟测试默认值位于所属插件的 `cli-backend.ts` 定义中。
- 启用：
- `pnpm test:live`（或直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
- `pnpm test:live`（或在直接调用 Vitest 时使用 `OPENCLAW_LIVE_TEST=1`）
- `OPENCLAW_LIVE_CLI_BACKEND=1`
- 默认值：
- 默认提供商/模型：`claude-cli/claude-sonnet-4-6`
- 命令/参数/图像行为来自所属 CLI 后端插件元数据。
- 命令/参数/图片行为来自所属 CLI 后端插件元数据。
- 覆盖（可选）：
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会注入到提示词中）。Docker 配方默认关闭此项，除非显式请求。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 将图像文件路径作为 CLI 参数传递，而不是注入提示词。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）在设置 `IMAGE_ARG` 时控制图像参数的传递方式。
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二回合并验证恢复流程。
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` 当所选模型支持切换目标时，选择启用 Claude Sonnet -> Opus 同会话连续性探测。Docker 配方为提升聚合可靠性默认关闭此项。
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 选择启用 MCP/工具 loopback 探测。Docker 配方默认关闭此项，除非显式请求。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图片附件（路径会注入到提示中）。Docker 配方默认关闭此项，除非显式请求。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 将图片文件路径作为 CLI 参数传递，而不是注入提示。
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）在设置 `IMAGE_ARG` 时控制图片参数的传递方式。
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮并验证恢复流程。
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` 当所选模型支持切换目标时，选择加入 Claude Sonnet -> Opus 同会话连续性探测。Docker 配方为聚合可靠性默认关闭此项。
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 选择加入 MCP/工具 loopback 探测。Docker 配方默认关闭此项，除非显式请求。
示例：
@ -175,7 +180,9 @@ OPENCLAW_LIVE_TEST=1 \
pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts
```
这不会要求 Gemini 生成响应。它会写入 OpenClaw 提供给 Gemini 的同一套系统设置，然后运行 `gemini --debug mcp list`，以证明已保存的 `transport: "streamable-http"` 服务器会规范化为 Gemini 的 HTTP MCP 形态，并且可以连接到本地 streamable-HTTP MCP 服务器。
这不会要求 Gemini 生成响应。它会写入 OpenClaw 提供给 Gemini 的相同系统
设置，然后运行 `gemini --debug mcp list`，以证明已保存的 `transport: "streamable-http"` 服务器会规范化为 Gemini 的 HTTP MCP
形态，并且可以连接到本地 streamable-HTTP MCP 服务器。
Docker 配方：
@ -195,27 +202,27 @@ pnpm test:docker:live-cli-backend:gemini
说明：
- Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。
- 它以非 root `node` 用户在仓库 Docker 镜像内运行实时 CLI 后端冒烟测试。
- 它从所属插件解析 CLI 冒烟元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 的缓存可写前缀中（默认：`~/.cache/openclaw/docker-cli-tools`）。
- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可移植的 Claude Code 订阅 OAuth，可以通过含有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它先证明 Docker 中的直接 `claude -p` 可用，然后在不保留 Anthropic API 密钥环境变量的情况下运行两次 Gateway 网关 CLI 后端回合。此订阅通道默认禁用 Claude MCP/工具和图像探测，因为 Claude 当前会将第三方应用使用路由到额外用量计费，而不是普通订阅计划额度。
- 实时 CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 运行相同的端到端流程：文本回合、图像分类回合，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得之前的笔记。
- 它以非 root `node` 用户在仓库 Docker 镜像内运行 live CLI 后端冒烟测试。
- 它从所属插件解析 CLI 冒烟测试元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到 `OPENCLAW_DOCKER_CLI_TOOLS_DIR`（默认：`~/.cache/openclaw/docker-cli-tools`）处的可写缓存前缀中。
- `pnpm test:docker:live-cli-backend:claude-subscription` 需要通过带有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json` 或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供可移植的 Claude Code 订阅 OAuth。它先在 Docker 中证明直接 `claude -p` 可用，然后在不保留 Anthropic API-key 环境变量的情况下运行两轮 Gateway 网关 CLI 后端。该订阅通道默认禁用 Claude MCP/工具和图片探测，因为 Claude 目前将第三方应用使用量路由到额外用量计费，而不是正常订阅计划限额。
- live CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮、图片分类轮，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得早先的备注。
## 实时：ACP 绑定冒烟测试（`/acp spawn ... --bind here`）
## Live：ACP 绑定冒烟测试（`/acp spawn ... --bind here`）
- 测试：`src/gateway/gateway-acp-bind.live.test.ts`
- 目标：使用实时 ACP 智能体验证真实的 ACP 对话绑定流程：
- 目标：使用实时 ACP 智能体验证真实的 ACP 会话绑定流程：
- 发送 `/acp spawn <agent> --bind here`
- 就地绑定一个合成的消息渠道对话
- 在同一对话中发送普通后续消息
- 验证后续消息落入已绑定的 ACP 会话 transcript
- 在原地绑定一个合成的消息渠道会话
- 在同一个会话上发送普通的后续消息
- 验证该后续消息落入已绑定 ACP 会话的转录中
- 启用：
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
- `OPENCLAW_LIVE_ACP_BIND=1`
- 默认值：
- Docker 中的 ACP 智能体：`claude,codex,gemini`
- 直接运行 `pnpm test:live ...` 时使用的 ACP 智能体：`claude`
- 合成渠道：Slack 私信风格的对话上下文
- 合成渠道：Slack 私信风格的会话上下文
- ACP 后端：`acpx`
- 覆盖项：
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
@ -231,9 +238,9 @@ pnpm test:docker:live-cli-backend:gemini
- `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`
- `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.5`
- 说明：
- 此通道使用 Gateway 网关的 `chat.send` 表面，并带有仅限管理员的合成 originating-route 字段，以便测试可以附加消息渠道上下文，而无需假装向外部投递。
- 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用嵌入式 `acpx` 插件的内置智能体注册表，为选定的 ACP harness 智能体提供支持。
- 默认情况下，绑定会话的 cron MCP 创建是尽力而为的，因为外部 ACP harness 可能会在绑定/image 证明通过后取消 MCP 调用；设置 `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` 可使绑定后的 cron 探测变为严格模式。
- 此测试线使用 Gateway 网关 `chat.send` 表面以及仅限管理员的合成 originating-route 字段，因此测试可以附加消息渠道上下文，而不必假装向外部投递。
- 未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用嵌入式 `acpx` 插件的内置智能体注册表来选择 ACP harness 智能体。
- 默认情况下，已绑定会话的 cron MCP 创建会尽力执行，因为外部 ACP harness 可能会在绑定/图像证明通过后取消 MCP 调用；设置 `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` 可让绑定后的 cron 探测变为严格模式。
示例：
@ -263,35 +270,29 @@ Docker 说明：
- Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。
- 默认情况下，它会按顺序针对聚合的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后是 `gemini`。
- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` 缩小矩阵范围。
- 它会 source `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，然后在缺失时安装请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex`、通过 `https://app.factory.ai/cli` 安装的 Factory Droid、`@google/gemini-cli` 或 `opencode-ai`）。ACP 后端本身是来自官方 `acpx` 插件的嵌入式 `acpx/runtime` 包。
- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` 来缩小矩阵范围。
- 它会加载 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，然后在缺失时安装请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex`、通过 `https://app.factory.ai/cli` 安装的 Factory Droid、`@google/gemini-cli` 或 `opencode-ai`）。ACP 后端本身是官方 `acpx` 插件中嵌入的 `acpx/runtime` 包。
- Droid Docker 变体会暂存 `~/.factory` 作为设置，转发 `FACTORY_API_KEY`，并且需要该 API key，因为本地 Factory OAuth/keyring 认证无法移植到容器中。它使用 ACPX 内置的 `droid exec --output-format acp` 注册表条目。
- OpenCode Docker 变体是严格的单智能体回归通道。它会在 source `~/.profile` 后，从 `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL`（默认 `opencode/kimi-k2.6`）写入一个临时的 `OPENCODE_CONFIG_CONTENT` 默认模型，并且 `pnpm test:docker:live-acp-bind:opencode` 要求存在已绑定的 assistant transcript，而不是接受通用的绑定后跳过。
- 直接调用 `acpx` CLI 只是一个手动/变通路径，用于比较 Gateway 网关之外的行为。Docker ACP 绑定冒烟测试会执行 OpenClaw 的嵌入式 `acpx` 运行时后端。
- OpenCode Docker 变体是严格的单智能体回归测试线。它在加载 `~/.profile` 后，根据 `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL`（默认 `opencode/kimi-k2.6`）写入临时 `OPENCODE_CONFIG_CONTENT` 默认模型，并且 `pnpm test:docker:live-acp-bind:opencode` 要求存在已绑定助手转录，而不是接受通用的绑定后跳过。
- 直接调用 `acpx` CLI 仅是用于比较 Gateway 网关外部行为的手动/变通路径。Docker ACP 绑定冒烟测试会运行 OpenClaw 嵌入的 `acpx` 运行时后端。
## 实时：Codex app-server harness 冒烟测试
- 目标：通过普通 Gateway 网关
`agent` 方法验证插件拥有的 Codex harness：
- 目标：通过正常的 Gateway 网关 `agent` 方法验证插件拥有的 Codex harness：
- 加载内置的 `codex` 插件
- 选择 `OPENCLAW_AGENT_RUNTIME=codex`
- 在强制使用 Codex harness 的情况下，向 `openai/gpt-5.5` 发送第一个 Gateway 网关智能体轮次
- 向同一个 OpenClaw 会话发送第二个轮次，并验证 app-server
thread 可以恢复
- 向 `openai/gpt-5.5` 发送第一个 Gateway 网关智能体轮次，并强制使用 Codex harness
- 向同一个 OpenClaw 会话发送第二个轮次，并验证 app-server 线程可以恢复
- 通过同一个 Gateway 网关命令路径运行 `/codex status` 和 `/codex models`
- 可选运行两个经过 Guardian 审查的提权 shell 探测：一个应被批准的无害
命令，以及一个应被拒绝、从而让智能体回问的假 secret 上传
- 可选运行两个经 Guardian 审核的提升权限 shell 探测：一个应获批准的无害命令，以及一个应被拒绝的虚假密钥上传，以便智能体回问
- 测试：`src/gateway/gateway-codex-harness.live.test.ts`
- 启用：`OPENCLAW_LIVE_CODEX_HARNESS=1`
- 默认模型：`openai/gpt-5.5`
- 可选 image 探测：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- 可选 MCP/tool 探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- 可选图像探测：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- 可选 MCP/工具探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- 可选 Guardian 探测：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
- 该冒烟测试设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，因此损坏的 Codex
harness 无法通过静默回退到 PI 来通过测试。
- 认证：来自本地 Codex 订阅登录的 Codex app-server 认证。Docker
冒烟测试也可以在适用时为非 Codex 探测提供 `OPENAI_API_KEY`，
以及可选复制的 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
- 该冒烟测试使用 `agentRuntime.id: "codex"`，因此损坏的 Codex harness 无法通过静默回退到 PI 而通过。
- 凭证：来自本地 Codex 订阅登录的 Codex app-server 认证。Docker 冒烟测试在适用时也可以为非 Codex 探测提供 `OPENAI_API_KEY`，并可选择复制 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
本地配方：
@ -315,72 +316,64 @@ pnpm test:docker:live-codex-harness
Docker 说明：
- Docker 运行器位于 `scripts/test-live-codex-harness-docker.sh`。
- 它会 source 挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI
认证文件，将 `@openai/codex` 安装到可写的挂载 npm
prefix 中，暂存源码树，然后只运行 Codex-harness 实时测试。
- Docker 默认启用 image、MCP/tool 和 Guardian 探测。需要更窄的调试
运行时，设置
`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或
`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
- Docker 还会导出 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，与实时
测试配置保持一致，因此旧版别名或 PI 回退无法隐藏 Codex harness
回归。
- 它会加载已挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI 认证文件，将 `@openai/codex` 安装到可写的已挂载 npm 前缀中，暂存源码树，然后只运行 Codex harness 实时测试。
- Docker 默认启用图像、MCP/工具和 Guardian 探测。当你需要更窄的调试运行时，设置 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`、`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
- Docker 使用相同的显式 Codex 运行时配置，因此旧别名或 PI 回退无法隐藏 Codex harness 回归。
### 推荐的实时配方
窄而明确的 allowlist 最快，也最不容易不稳定：
范围窄且显式的允许列表最快，也最不易波动：
- 单模型，直接运行（不经过 Gateway 网关）：
- 单个模型，直接运行（无 Gateway 网关）：
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts`
- 单模型，Gateway 网关冒烟测试：
- 单个模型，Gateway 网关冒烟测试：
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- 跨多个提供商的工具调用：
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Google 聚焦（Gemini API key + Antigravity）：
- Google 重点测试（Gemini API key + Antigravity）：
- Gemini（API key）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Google adaptive thinking 冒烟测试：
- 如果本地 key 存在于 shell profile 中：`source ~/.profile`
- Gemini 3 dynamic default：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
- Gemini 2.5 dynamic budget：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`
- 如果本地密钥位于 shell profile 中：`source ~/.profile`
- Gemini 3 动态默认值：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
- Gemini 2.5 动态预算：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`
说明：
- `google/...` 使用 Gemini API（API key）。
- `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist 风格的智能体端点）。
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立认证 + 工具链特性）。
- `google-antigravity/...` 使用 Antigravity OAuth 桥接（Cloud Code Assist 风格的智能体端点）。
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立认证 + 工具差异）。
- Gemini API 与 Gemini CLI：
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / profile 认证）；这也是大多数用户所说的“Gemini”。
- CLI：OpenClaw shell out 到本地 `gemini` 二进制；它有自己的认证，并且行为可能不同（streaming/tool 支持/版本偏差）。
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / profile 认证）；这是多数用户所说的 “Gemini”。
- CLI：OpenClaw 调用本地 `gemini` 二进制文件；它有自己的认证，并且行为可能不同（流式传输/工具支持/版本偏差）。
## 实时：模型矩阵（我们覆盖的内容）
## 实时：模型矩阵（覆盖范围）
没有固定的“CI 模型列表”（实时测试是选择性启用的），但以下是建议在有 key 的开发机器上定期覆盖的**推荐**模型。
没有固定的 “CI 模型列表”（实时测试是选择性启用），但以下是建议在有密钥的开发机器上定期覆盖的**推荐**模型。
### 现代冒烟集合（工具调用 + image）
### 现代冒烟集合（工具调用 + 图像）
这是我们期望保持可用的“常用模型”运行：
这是我们期望持续可用的“常用模型”运行：
- OpenAI（非 Codex）：`openai/gpt-5.5`
- OpenAI Codex OAuth：`openai-codex/gpt-5.5`
- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
- Google（Gemini API）：`google/gemini-3.1-pro-preview` 和 `google/gemini-3-flash-preview`（避免旧版 Gemini 2.x 模型）
- Google（Gemini API）：`google/gemini-3.1-pro-preview` 和 `google/gemini-3-flash-preview`（避免较旧的 Gemini 2.x 模型）
- Google（Antigravity）：`google-antigravity/claude-opus-4-6-thinking` 和 `google-antigravity/gemini-3-flash`
- DeepSeek：`deepseek/deepseek-v4-flash` 和 `deepseek/deepseek-v4-pro`
- Z.AI（GLM）：`zai/glm-5.1`
- MiniMax：`minimax/MiniMax-M2.7`
使用工具 + image 运行 Gateway 网关冒烟测试：
运行带工具 + 图像的 Gateway 网关冒烟测试：
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
### 基线：工具调用（Read + 可选 Exec）
每个提供商系列至少选择一个：
每个提供商家族至少选择一个：
- OpenAI：`openai/gpt-5.5`
- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
@ -389,48 +382,48 @@ Docker 说明：
- Z.AI（GLM）：`zai/glm-5.1`
- MiniMax：`minimax/MiniMax-M2.7`
可选的额外覆盖（有则更好）：
可选的额外覆盖范围（建议具备）：
- xAI：`xai/grok-4.3`（或最新可用版本）
- Mistral：`mistral/`…（选择一个你已启用、支持“tools”的模型）
- Mistral：`mistral/`…（选择一个你已启用且支持“工具”的模型）
- Cerebras：`cerebras/`…（如果你有访问权限）
- LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式）
### Vision：发送 image（附件 → 多模态消息）
### 视觉：图像发送（附件 → 多模态消息）
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中包含至少一个支持 image 的模型（Claude/Gemini/OpenAI 支持 vision 的变体等），以执行 image 探测。
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中包含至少一个支持图像的模型（Claude/Gemini/OpenAI 中支持视觉的变体等），以运行图像探测。
### 聚合器 / 替代 Gateway 网关
### 聚合器 / 备用 Gateway 网关
如果你已启用 key，我们还支持通过以下方式测试：
如果你已启用密钥，我们也支持通过以下方式测试：
- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持 tool+image 的候选项）
- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具+图像的候选模型）
- OpenCode：`opencode/...` 用于 Zen，`opencode-go/...` 用于 Go（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
你可以包含在实时矩阵中的更多提供商（如果你有凭据/配置）：
你可以纳入实时矩阵的更多提供商（如果你有凭证/配置）：
- 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot`
- 通过 `models.providers`（自定义端点）：`minimax`（cloud/API），以及任何 OpenAI/Anthropic 兼容代理（LM Studio、vLLM、LiteLLM 等）
- 通过 `models.providers`（自定义端点）：`minimax`（云/API），以及任何 OpenAI/Anthropic 兼容代理（LM Studio、vLLM、LiteLLM 等）
<Tip>
不要在文档中硬编码“所有模型”。权威列表是你的机器上 `discoverModels(...)` 返回的内容，再加上可用的 key。
不要在文档中硬编码 “所有模型”。权威列表是你机器上 `discoverModels(...)` 返回的内容，加上可用的密钥。
</Tip>
## 凭据（切勿提交）
## 凭证（绝不要提交）
实时测试会以与 CLI 相同的方式发现凭据。实际影响：
实时测试会以 CLI 相同的方式发现凭证。实际影响：
- 如果 CLI 可用，实时测试应能找到相同的键。
- 如果实时测试提示“没有凭证”，请按调试 `openclaw models list` / 模型选择的同样方式进行调试。
- 如果 CLI 可用，实时测试应该能找到相同的密钥。
- 如果实时测试提示“no creds”，按调试 `openclaw models list` / 模型选择的相同方式调试。
- 每智能体凭证配置文件：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试中“profile keys”的含义）
- 每个智能体的身份验证配置文件：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试中“profile keys”的含义）
- 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时测试主目录中，但不是主要的 profile-key 存储位置）
- 本地实时运行默认会把当前配置、每智能体 `auth-profiles.json` 文件、旧版 `credentials/`，以及受支持的外部 CLI 凭证目录复制到临时测试主目录；暂存的实时测试主目录会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，以确保探测不会访问你真实主机上的工作区。
- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时测试主目录中，但不是主要的 profile-key 存储）
- 本地实时运行默认会将活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/`，以及支持的外部 CLI 身份验证目录复制到临时测试主目录；暂存的实时主目录会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，以便探测不会触碰你真实主机上的工作区。
如果你想依赖环境键（例如在你的 `~/.profile` 中导出的键），请在 `source ~/.profile` 后运行本地测试，或使用下面的 Docker 运行器（它们可以把 `~/.profile` 挂载到容器中）。
如果你想依赖环境变量密钥（例如在你的 `~/.profile` 中导出），请在 `source ~/.profile` 后运行本地测试，或使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。
## Deepgram 实时（音频转录）
## Deepgram 实时（音频转写）
- 测试：`extensions/deepgram/audio.live.test.ts`
- 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
@ -448,19 +441,19 @@ Docker 说明：
- 范围：
- 覆盖内置的 comfy 图像、视频和 `music_generate` 路径
- 除非已配置 `plugins.entries.comfy.config.<capability>`，否则跳过每项能力
- 适用于更改 comfy 工作流提交、轮询、下载或插件注册之后
- 适用于更改 comfy 工作流提交、轮询、下载或插件注册后
## 图像生成实时测试
- 测试：`test/image-generation.runtime.live.test.ts`
- 命令：`pnpm test:live test/image-generation.runtime.live.test.ts`
- 测试框架：`pnpm test:live:media image`
- Harness：`pnpm test:live:media image`
- 范围：
- 枚举每个已注册的图像生成提供商插件
- 探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
- 默认优先使用实时/环境 API key，而不是已存储的凭证配置文件，因此 `auth-profiles.json` 中过期的测试键不会掩盖真实的 shell 凭证
- 跳过没有可用凭证/配置文件/模型的提供商
- 通过共享图像生成运行时运行每个已配置提供商：
- 在探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
- 默认优先使用实时/环境 API 密钥，而不是已存储的身份验证配置文件，因此 `auth-profiles.json` 中的陈旧测试密钥不会掩盖真实的 shell 凭据
- 跳过没有可用身份验证/配置文件/模型的提供商
- 通过共享图像生成运行时运行每个已配置的提供商：
- `<provider>:generate`
- 当提供商声明支持编辑时运行 `<provider>:edit`
- 当前覆盖的内置提供商：
@ -477,10 +470,10 @@ Docker 说明：
- `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="deepinfra"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"`
- 可选凭证行为：
- 使用 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置文件存储的凭证，并忽略仅环境变量的覆盖
- 可选身份验证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于强制使用配置文件存储身份验证，并忽略仅环境变量的覆盖
对于已发布的 CLI 路径，请在提供商/运行时实时测试通过后添加一个 `infer` 冒烟测试：
对于已发布的 CLI 路径，在提供商/运行时实时测试通过后添加一个 `infer` 冒烟测试：
```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts
@ -492,21 +485,21 @@ openclaw infer image generate \
--json
```
这会覆盖 CLI 参数解析、配置/默认智能体解析、内置插件激活、共享图像生成运行时，以及实时提供商请求。插件依赖项应在运行时加载前已存在。
这会覆盖 CLI 参数解析、配置/默认智能体解析、内置插件激活、共享图像生成运行时，以及实时提供商请求。运行时加载前应已存在插件依赖。
## 音乐生成实时测试
- 测试：`extensions/music-generation-providers.live.test.ts`
- 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
- 测试框架：`pnpm test:live:media music`
- Harness：`pnpm test:live:media music`
- 范围：
- 覆盖共享的内置音乐生成提供商路径
- 当前覆盖 Google 和 MiniMax
- 探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用实时/环境 API key，而不是已存储的凭证配置文件，因此 `auth-profiles.json` 中过期的测试键不会掩盖真实的 shell 凭证
- 跳过没有可用凭证/配置文件/模型的提供商
- 可用时运行两个已声明的运行时模式：
- 使用仅提示输入的 `generate`
- 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用实时/环境 API 密钥，而不是已存储的身份验证配置文件，因此 `auth-profiles.json` 中的陈旧测试密钥不会掩盖真实的 shell 凭据
- 跳过没有可用身份验证/配置文件/模型的提供商
- 可用时运行两种声明的运行时模式：
- 使用仅提示词输入的 `generate`
- 当提供商声明 `capabilities.edit.enabled` 时运行 `edit`
- 当前共享通道覆盖范围：
- `google`：`generate`、`edit`
@ -515,52 +508,52 @@ openclaw infer image generate \
- 可选缩小范围：
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"`
- 可选凭证行为：
- 使用 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置文件存储的凭证，并忽略仅环境变量的覆盖
- 可选身份验证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于强制使用配置文件存储身份验证，并忽略仅环境变量的覆盖
## 视频生成实时测试
- 测试：`extensions/video-generation-providers.live.test.ts`
- 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
- 测试框架：`pnpm test:live:media video`
- Harness：`pnpm test:live:media video`
- 范围：
- 覆盖共享的内置视频生成提供商路径
- 默认使用适合发布的冒烟路径：非 FAL 提供商、每个提供商一个文本转视频请求、一秒龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每提供商操作上限（默认 `180000`）
- 默认跳过 FAL，因为提供商侧队列延迟可能占用大量发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它
- 探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用实时/环境 API key，而不是已存储的凭证配置文件，因此 `auth-profiles.json` 中过期的测试键不会掩盖真实的 shell 凭证
- 跳过没有可用凭证/配置文件/模型的提供商
- 默认使用适合发布的冒烟路径：非 FAL 提供商、每个提供商一次文本转视频请求、一秒钟龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每个提供商操作上限（默认 `180000`）
- 默认跳过 FAL，因为提供商侧队列延迟可能会主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它
- 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量
- 默认优先使用实时/环境 API 密钥，而不是已存储的身份验证配置文件，因此 `auth-profiles.json` 中的陈旧测试密钥不会掩盖真实的 shell 凭据
- 跳过没有可用身份验证/配置文件/模型的提供商
- 默认只运行 `generate`
- 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，也会在可用时运行已声明的转换模式：
- 当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商/模型在共享扫描中接受由缓冲区支持的本地图像输入时，运行 `imageToVideo`
- 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商/模型在共享扫描中接受由缓冲区支持的本地视频输入时，运行 `videoToVideo`
- 共享扫描中当前已声明但跳过的 `imageToVideo` 提供商：
- 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，也会在可用时运行声明的转换模式：
- 当提供商声明 `capabilities.imageToVideo.enabled`，并且所选提供商/模型在共享扫描中接受由 buffer 支持的本地图像输入时，运行 `imageToVideo`
- 当提供商声明 `capabilities.videoToVideo.enabled`，并且所选提供商/模型在共享扫描中接受由 buffer 支持的本地视频输入时，运行 `videoToVideo`
- 当前在共享扫描中已声明但跳过的 `imageToVideo` 提供商：
- `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL
- Vydra 的提供商特定覆盖：
- 提供商特定的 Vydra 覆盖范围：
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
- 该文件默认运行 `veo3` 文本转视频，以及使用远程图像 URL 固件的 `kling` 通道
- 当前 `videoToVideo` 实时覆盖：
- 该文件运行 `veo3` 文本转视频，以及默认使用远程图像 URL fixture 的 `kling` 通道
- 当前 `videoToVideo` 实时覆盖范围：
- 仅当所选模型为 `runway/gen4_aleph` 时覆盖 `runway`
- 共享扫描中当前已声明但跳过的 `videoToVideo` 提供商：
- 当前在共享扫描中已声明但跳过的 `videoToVideo` 提供商：
- `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL
- `google`，因为当前共享 Gemini/Veo 通道使用本地缓冲区支持的输入，而共享扫描不接受该路径
- `openai`，因为当前共享通道缺少组织特定视频修补/混剪访问保证
- `google`，因为当前共享的 Gemini/Veo 通道使用由本地 buffer 支持的输入，而共享扫描不接受该路径
- `openai`，因为当前共享通道缺少特定组织的视频修复/混剪访问保证
- 可选缩小范围：
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,google,openai,runway"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 可在默认扫描中包含每个提供商，包括 FAL
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 可降低每个提供商的操作上限，用于激进的冒烟运行
- 可选凭证行为：
- 使用 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 强制使用配置文件存储的凭证，并忽略仅环境变量的覆盖
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 用于在默认扫描中包含每个提供商，包括 FAL
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 用于在激进的冒烟运行中降低每个提供商的操作上限
- 可选身份验证行为：
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于强制使用配置文件存储身份验证，并忽略仅环境变量的覆盖
## 媒体实时测试框架
## 媒体实时 Harness
- 命令：`pnpm test:live:media`
- 用途：
- 通过一个仓库原生入口点运行共享的图像、音乐和视频实时测试套件
- 目的：
- 通过一个仓库原生入口点运行共享的图像、音乐和视频实时套件
- 从 `~/.profile` 自动加载缺失的提供商环境变量
- 默认自动将每个套件缩小到当前拥有可用凭证的提供商
- 复用 `scripts/test-live.mjs`，因此 Heartbeat 和静默模式行为保持一致
- 默认自动将每个套件缩小到当前拥有可用身份验证的提供商
- 复用 `scripts/test-live.mjs`，因此 Heartbeat 和安静模式行为保持一致
- 示例：
- `pnpm test:live:media`
- `pnpm test:live:media image video --providers openai,google,minimax`

437
docs/zh-CN/plan/codex-context-engine-harness.md
View File

@ -1,57 +1,52 @@
---
read_when:
- 你正在将上下文引擎生命周期行为接入 Codex harness
- 你需要让 lossless-claw 或其他上下文引擎插件能够与 codex/* 嵌入式 harness 会话一起工作
- 你正在比较嵌入式 PI 和 Codex app-server 的上下文行为
summary: 使内置 Codex app-server harness 遵循 OpenClaw 上下文引擎插件的规范
- 你正在将 context-engine 生命周期行为接入 Codex harness
- 你需要 lossless-claw 或其他 context-engine 插件，才能使用 codex/* 嵌入式 harness 会话
- 你正在比较嵌入式 PI 和 Codex 应用服务器的上下文行为
summary: 让内置的 Codex app-server harness 支持 OpenClaw 上下文引擎插件的规范
title: Codex Harness Context Engine Port
x-i18n:
generated_at: "2026-04-24T18:09:10Z"
model: gpt-5.4
generated_at: "2026-05-03T04:51:04Z"
model: gpt-5.5
provider: openai
source_hash: 61c29a6cd8955a41510b8da1575b89ed003565d564b25b37b3b0c7f65df6b663
source_hash: 6575c25973d43c04cada6157e39c52ea5ad1cc60171cf801fe36cbb9c54c9237
source_path: plan/codex-context-engine-harness.md
workflow: 15
workflow: 16
---
## 状态
## Status
草案实现规范。
## 目标
让内置的 Codex app-server harness 遵循与嵌入式 PI 回合已经遵循的同一套 OpenClaw 上下文引擎生命周期契约。
让内置的 Codex 应用服务器运行框架遵循与嵌入式 PI 回合已经遵循的相同 OpenClaw 上下文引擎生命周期契约。
当会话使用 `agents.defaults.embeddedHarness.runtime: "codex"` 或
`codex/*` 模型时，所选的上下文引擎插件（例如
`lossless-claw`）仍应尽可能在 Codex app-server 边界允许的范围内，控制上下文组装、回合后摄取、维护，以及 OpenClaw 级别的压缩策略。
使用 `agents.defaults.embeddedHarness.runtime: "codex"` 或 `codex/*` 模型的会话，仍应让所选上下文引擎插件（例如 `lossless-claw`）在 Codex 应用服务器边界允许的范围内控制上下文组装、回合后摄取、维护，以及 OpenClaw 级别的压缩策略。
## 非目标
- 不重新实现 Codex app-server 内部机制。
- 不让 Codex 原生线程压缩产出 lossless-claw 摘要。
- 不重新实现 Codex 应用服务器内部机制。
- 不让 Codex 原生线程压缩生成 `lossless-claw` 摘要。
- 不要求非 Codex 模型使用 Codex harness。
- 不更改 ACP/acpx 会话行为。本规范仅适用于
非 ACP 的嵌入式智能体 harness 路径。
- 不让第三方插件注册 Codex app-server 扩展工厂；
现有的内置插件信任边界保持不变。
- 不改变 ACP/acpx 会话行为。本规范仅适用于非 ACP 嵌入式智能体运行框架路径。
- 不让第三方插件注册 Codex 应用服务器扩展工厂；现有内置插件信任边界保持不变。
## 当前架构
嵌入式运行循环在选择具体底层 harness 之前，会为每次运行解析一次已配置的上下文引擎：
嵌入式运行循环会在每次运行中先解析已配置的上下文引擎，然后再选择具体的底层运行框架：
- `src/agents/pi-embedded-runner/run.ts`
- 初始化上下文引擎插件
- 调用 `resolveContextEngine(params.config)`
- 将 `contextEngine` 和 `contextTokenBudget` 传入
`runEmbeddedAttemptWithBackend(...)`
- 将 `contextEngine` 和 `contextTokenBudget` 传入 `runEmbeddedAttemptWithBackend(...)`
`runEmbeddedAttemptWithBackend(...)` 会委托给所选的智能体 harness：
`runEmbeddedAttemptWithBackend(...)` 会委托给所选的智能体运行框架：
- `src/agents/pi-embedded-runner/run/backend.ts`
- `src/agents/harness/selection.ts`
Codex app-server harness 由内置 Codex 插件注册：
Codex 应用服务器运行框架由内置 Codex 插件注册：
- `extensions/codex/index.ts`
- `extensions/codex/harness.ts`
@ -60,20 +55,17 @@ Codex harness 实现接收与 PI 支持的尝试相同的 `EmbeddedRunAttemptPar
- `extensions/codex/src/app-server/run-attempt.ts`
这意味着所需的钩子点位于 OpenClaw 可控代码中。外部
边界是 Codex app-server 协议本身：OpenClaw 可以控制它发送到
`thread/start`、`thread/resume` 和 `turn/start` 的内容，并且可以观察
通知，但无法更改 Codex 的内部线程存储或原生压缩器。
这意味着所需的钩子点位于 OpenClaw 控制的代码中。外部边界是 Codex 应用服务器协议本身：OpenClaw 可以控制发送给 `thread/start`、`thread/resume` 和 `turn/start` 的内容，也可以观察通知，但不能更改 Codex 的内部线程存储或原生压缩器。
## 当前缺口
嵌入式 PI 尝试会直接调用上下文引擎生命周期：
- 在尝试前执行 bootstrap / maintenance
- 在模型调用前执行 assemble
- 在尝试后执行 `afterTurn` 或 `ingest`
- 在成功回合后执行 maintenance
- 为拥有压缩职责的引擎执行上下文引擎压缩
- 尝试前的启动引导/维护
- 模型调用前的组装
- 尝试后的 `afterTurn` 或摄取
- 成功回合后的维护
- 由引擎自主管理压缩时的上下文引擎压缩
相关 PI 代码：
@ -81,11 +73,7 @@ Codex harness 实现接收与 PI 支持的尝试相同的 `EmbeddedRunAttemptPar
- `src/agents/pi-embedded-runner/run/attempt.context-engine-helpers.ts`
- `src/agents/pi-embedded-runner/context-engine-maintenance.ts`
Codex app-server 尝试当前会运行通用智能体 harness 钩子并镜像
转录内容，但不会调用 `params.contextEngine.bootstrap`、
`params.contextEngine.assemble`、`params.contextEngine.afterTurn`、
`params.contextEngine.ingestBatch`、`params.contextEngine.ingest` 或
`params.contextEngine.maintain`。
Codex 应用服务器尝试目前会运行通用智能体运行框架钩子并镜像转录记录，但不会调用 `params.contextEngine.bootstrap`、`params.contextEngine.assemble`、`params.contextEngine.afterTurn`、`params.contextEngine.ingestBatch`、`params.contextEngine.ingest` 或 `params.contextEngine.maintain`。
相关 Codex 代码：
@ -96,91 +84,83 @@ Codex app-server 尝试当前会运行通用智能体 harness 钩子并镜像
## 期望行为
对于 Codex harness 回合，OpenClaw 应保留以下生命周期：
对于 Codex harness 回合，OpenClaw 应保留此生命周期：
1. 读取镜像的 OpenClaw 会话转录。
2. 当存在先前会话文件时，对活动上下文引擎执行 bootstrap。
3. 在可用时运行 bootstrap maintenance。
4. 使用活动上下文引擎组装上下文。
5. 将组装后的上下文转换为与 Codex 兼容的输入。
6. 启动或恢复 Codex 线程，并将任何
上下文引擎 `systemPromptAddition` 包含在 developer instructions 中。
7. 使用组装后的面向用户提示词启动 Codex 回合。
8. 将 Codex 结果镜像回 OpenClaw 转录。
9. 如果实现了 `afterTurn` 则调用它，否则使用
镜像的转录快照调用 `ingestBatch`/`ingest`。
10. 在成功且未中止的回合后运行回合 maintenance。
1. 读取镜像的 OpenClaw 会话转录记录。
2. 当存在先前的会话文件时，启动引导当前上下文引擎。
3. 在可用时运行启动引导维护。
4. 使用当前上下文引擎组装上下文。
5. 将已组装的上下文转换为 Codex 兼容输入。
6. 使用包含任何上下文引擎 `systemPromptAddition` 的开发者指令来启动或恢复 Codex 线程。
7. 使用已组装的面向用户提示启动 Codex 回合。
8. 将 Codex 结果镜像回 OpenClaw 转录记录。
9. 如果实现了 `afterTurn`，则调用它；否则使用镜像的转录记录快照调用 `ingestBatch`/`ingest`。
10. 在成功且未中止的回合后运行回合维护。
11. 保留 Codex 原生压缩信号和 OpenClaw 压缩钩子。
## 设计约束
### Codex app-server 仍然是原生线程状态的权威来源
### Codex 应用服务器仍是原生线程状态的权威来源
Codex 拥有其原生线程及任何内部扩展历史。OpenClaw 不应
尝试通过受支持协议调用以外的方式修改 app-server 的内部历史。
Codex 拥有其原生线程和任何内部扩展历史。OpenClaw 不应尝试通过受支持协议调用之外的方式修改应用服务器的内部历史。
OpenClaw 的转录镜像仍然是 OpenClaw 功能的来源：
OpenClaw 的转录记录镜像仍是 OpenClaw 功能的来源：
- 聊天历史
- 搜索
- `/new` 和 `/reset` 记账
- 未来的模型或 harness 切换
- 未来模型或运行框架切换
- 上下文引擎插件状态
### 上下文引擎组装必须投影到 Codex 输入中
### 上下文引擎组装必须投射到 Codex 输入
上下文引擎接口返回的是 OpenClaw `AgentMessage[]`，而不是 Codex
线程补丁。Codex app-server 的 `turn/start` 接受当前用户输入，而
`thread/start` 和 `thread/resume` 接受 developer instructions。
上下文引擎接口返回 OpenClaw `AgentMessage[]`，而不是 Codex 线程补丁。Codex 应用服务器 `turn/start` 接受当前用户输入，而 `thread/start` 和 `thread/resume` 接受开发者指令。
因此，实现需要一个投影层。安全的第一版
应避免假装它可以替换 Codex 内部历史。它应将组装好的上下文作为围绕
当前回合的确定性提示词 / developer-instruction 材料注入。
因此实现需要一个投射层。安全的首版应避免假装可以替换 Codex 内部历史。它应围绕当前回合，将已组装上下文作为确定性的提示/开发者指令材料注入。
### Prompt-cache 稳定性很重要
### 提示缓存稳定性很重要
对于 lossless-claw 这样的引擎，组装后的上下文对于未变化的输入应保持确定性。不要向生成的上下文文本中加入时间戳、随机 id 或非确定性排序。
对于 `lossless-claw` 这样的引擎，在输入不变时，已组装上下文应是确定性的。不要向生成的上下文文本添加时间戳、随机 ID 或不确定排序。
### PI 回退语义不变
### 运行时选择语义不变
Harness 选择保持现状：
运行框架选择保持现状：
- `runtime: "pi"` 强制使用 PI
- `runtime: "codex"` 选择已注册的 Codex harness
- `runtime: "auto"` 让插件 harness 声明支持的 provider
- `fallback: "none"` 在没有插件 harness 匹配时禁用 PI 回退
- `runtime: "auto"` 允许插件运行框架声明支持的提供商
- 未匹配的 `auto` 运行使用 PI
这项工作更改的是 Codex harness 被选中之后发生的事情。
此项工作改变的是选择 Codex harness 之后发生的事情。
## 实现计划
### 1. 导出或迁移可复用的上下文引擎尝试辅助函数
当前，可复用的生命周期辅助函数位于 PI runner 下：
目前可复用的生命周期辅助函数位于 PI runner 下：
- `src/agents/pi-embedded-runner/run/attempt.context-engine-helpers.ts`
- `src/agents/pi-embedded-runner/run/attempt.prompt-helpers.ts`
- `src/agents/pi-embedded-runner/context-engine-maintenance.ts`
如果可以避免，Codex 不应从一个名称暗示 PI 的实现路径导入。
如果可以避免，Codex 不应从名称暗示 PI 的实现路径导入。
创建一个与 harness 无关的模块，例如：
创建一个与运行框架无关的模块，例如：
- `src/agents/harness/context-engine-lifecycle.ts`
迁移或重新导出：
移动或重新导出：
- `runAttemptContextEngineBootstrap`
- `assembleAttemptContextEngine`
- `finalizeAttemptContextEngineTurn`
- `buildAfterTurnRuntimeContext`
- `buildAfterTurnRuntimeContextFromUsage`
- 一个围绕 `runContextEngineMaintenance` 的小型包装器
- 围绕 `runContextEngineMaintenance` 的小型包装器
通过从旧文件重新导出，或在同一个 PR 中更新 PI
调用点，以保持 PI 导入仍可工作。
保持 PI 导入可用，可以通过从旧文件重新导出，或在同一个 PR 中更新 PI 调用点。
中立的辅助函数命名不应提及 PI。
中立辅助函数名称不应提到 PI。
建议名称：
@ -190,20 +170,18 @@ Harness 选择保持现状：
- `buildHarnessContextEngineRuntimeContext`
- `runHarnessContextEngineMaintenance`
### 2. 添加一个 Codex 上下文投影辅助函数
### 2. 添加 Codex 上下文投射辅助函数
添加一个新模块：
添加新模块：
- `extensions/codex/src/app-server/context-engine-projection.ts`
职责：
- 接收已组装的 `AgentMessage[]`、原始镜像历史和当前
提示词。
- 判断哪些上下文应放入 developer instructions，哪些应放入当前用户
输入。
- 保留当前用户提示词作为最终可执行请求。
- 以稳定、显式的格式渲染先前消息。
- 接收已组装的 `AgentMessage[]`、原始镜像历史和当前提示。
- 判断哪些上下文属于开发者指令，哪些属于当前用户输入。
- 将当前用户提示保留为最终可执行请求。
- 以稳定、明确的格式渲染先前消息。
- 避免易变元数据。
建议 API：
@ -224,15 +202,15 @@ export function projectContextEngineAssemblyForCodex(params: {
}): CodexContextProjection;
```
推荐的第一版投影：
建议的首版投射：
- 将 `systemPromptAddition` 放入 developer instructions。
- 将组装后的转录上下文放在 `promptText` 中当前提示词之前。
- 清晰标记它是 OpenClaw 组装的上下文。
- 保持当前提示词位于最后。
- 如果当前用户提示词已经出现在尾部，则排除重复项。
- 将 `systemPromptAddition` 放入开发者指令。
- 将已组装的转录记录上下文放在 `promptText` 中当前提示之前。
- 清晰标注为 OpenClaw 已组装上下文。
- 保持当前提示位于最后。
- 如果当前用户提示已经出现在末尾，则排除重复项。
示例提示词形状：
示例提示形态：
```text
OpenClaw assembled context for this turn:
@ -249,21 +227,18 @@ Current user request:
...
```
这不如原生 Codex 历史修补优雅，但它可以在 OpenClaw 内部实现，并保留上下文引擎语义。
这不如原生 Codex 历史手术优雅，但它可在 OpenClaw 内部实现，并保留上下文引擎语义。
未来改进：如果 Codex app-server 暴露了用于替换或
补充线程历史的协议，则将此投影层切换为使用该 API。
未来改进：如果 Codex 应用服务器公开用于替换或补充线程历史的协议，则将此投射层切换为使用该 API。
### 3. 在 Codex 线程启动前接入 bootstrap
### 3. 在 Codex 线程启动前接入启动引导
在 `extensions/codex/src/app-server/run-attempt.ts` 中：
- 按当前方式读取镜像会话历史。
- 判断本次运行前会话文件是否已存在。优先使用一个
在镜像写入之前检查 `fs.stat(params.sessionFile)` 的辅助函数。
- 打开一个 `SessionManager`，或者如果辅助函数
需要它，则使用一个窄化的会话管理器适配器。
- 当 `params.contextEngine` 存在时，调用中立的 bootstrap 辅助函数。
- 像现在一样读取镜像的会话历史。
- 判断会话文件在此次运行前是否存在。优先使用在镜像写入前检查 `fs.stat(params.sessionFile)` 的辅助函数。
- 打开 `SessionManager`，或在辅助函数需要时使用窄会话管理器适配器。
- 当 `params.contextEngine` 存在时，调用中立启动引导辅助函数。
伪流程：
@ -285,22 +260,20 @@ await bootstrapHarnessContextEngine({
});
```
使用与 Codex 工具桥接和转录镜像相同的 `sessionKey` 约定。当前 Codex 会根据 `params.sessionKey` 或
`params.sessionId` 计算 `sandboxSessionKey`；除非有理由保留原始 `params.sessionKey`，否则应一致使用它。
使用与 Codex 工具桥接和转录记录镜像相同的 `sessionKey` 约定。如今 Codex 会从 `params.sessionKey` 或 `params.sessionId` 计算 `sandboxSessionKey`；除非有理由保留原始 `params.sessionKey`，否则应一致使用它。
### 4. 在 `thread/start` / `thread/resume` 和 `turn/start` 之前接入 assemble
### 4. 在 `thread/start` / `thread/resume` 和 `turn/start` 之前接入组装
在 `runCodexAppServerAttempt` 中：
1. 先构建动态工具，以便上下文引擎能看到实际可用的
工具名称。
2. 读取镜像会话历史。
3. 当 `params.contextEngine` 存在时运行上下文引擎 `assemble(...)`。
4. 将组装结果投影为：
- developer instruction addition
- 用于 `turn/start` 的提示词文本
1. 先构建动态工具，让上下文引擎看到实际可用的工具名称。
2. 读取镜像的会话历史。
3. 当 `params.contextEngine` 存在时，运行上下文引擎 `assemble(...)`。
4. 将已组装结果投射到：
- 开发者指令追加内容
- `turn/start` 的提示文本
现有的钩子调用：
现有钩子调用：
```ts
resolveAgentHarnessBeforePromptBuildResult({
@ -311,51 +284,46 @@ resolveAgentHarnessBeforePromptBuildResult({
});
```
应变为具备上下文感知能力：
应变为感知上下文：
1. 使用 `buildDeveloperInstructions(params)` 计算基础 developer instructions
2. 应用上下文引擎组装 / 投影
3. 使用投影后的提示词 / developer instructions 运行 `before_prompt_build`
1. 使用 `buildDeveloperInstructions(params)` 计算基础开发者指令
2. 应用上下文引擎组装/投射
3. 使用已投射的提示/开发者指令运行 `before_prompt_build`
这种顺序可让通用提示词钩子看到 Codex 将实际接收的同一提示词。如果
需要严格的 PI 对齐，则应在钩子组合之前运行上下文引擎组装，
因为 PI 会在其提示词流水线之后，将上下文引擎 `systemPromptAddition` 应用到最终系统提示词中。重要的不变量是：上下文
引擎和钩子都获得一个确定且有文档说明的顺序。
此顺序让通用提示钩子看到与 Codex 将接收内容相同的提示。如果需要严格 PI 对齐，则在钩子组合前运行上下文引擎组装，因为 PI 会在其提示流水线之后将上下文引擎 `systemPromptAddition` 应用于最终系统提示。重要不变式是：上下文引擎和钩子都获得确定性且有文档说明的顺序。
第一版实现的推荐顺序：
建议首版实现顺序：
1. `buildDeveloperInstructions(params)`
2. 上下文引擎 `assemble()`
3. 将 `systemPromptAddition` 追加 / 前置到 developer instructions
4. 将组装后的消息投影到提示词文本中
3. 将 `systemPromptAddition` 追加/前置到开发者指令
4. 将已组装消息投射到提示文本
5. `resolveAgentHarnessBeforePromptBuildResult(...)`
6. 将最终 developer instructions 传入 `startOrResumeThread(...)`
7. 将最终提示词文本传入 `buildTurnStartParams(...)`
6. 将最终开发者指令传给 `startOrResumeThread(...)`
7. 将最终提示文本传给 `buildTurnStartParams(...)`
该规范应通过测试编码，以防未来更改不小心重排顺序。
该规范应编码进测试，避免未来更改意外重排顺序。
### 5. 保持 prompt-cache 格式稳定
### 5. 保留提示缓存稳定格式
投影辅助函数必须对相同输入产出字节级稳定的输出：
投射辅助函数必须对相同输入生成字节稳定输出：
- 稳定的消息顺序
- 稳定的角色标签
- 无生成的时间戳
- 稳定消息顺序
- 稳定角色标签
- 无生成时间戳
- 无对象键顺序泄漏
- 无随机分隔符
- 无每次运行 id
- 无每次运行 ID
使用固定分隔符和显式分节。
使用固定分隔符和明确分区。
### 6. 在转录镜像之后接入回合后流程
### 6. 在转录记录镜像后接入回合后处理
Codex 的 `CodexAppServerEventProjector` 会为当前回合构建一个本地 `messagesSnapshot`。
`mirrorTranscriptBestEffort(...)` 会将该快照写入 OpenClaw 转录镜像。
Codex 的 `CodexAppServerEventProjector` 会为当前轮次构建本地 `messagesSnapshot`。`mirrorTranscriptBestEffort(...)` 会把该快照写入 OpenClaw 转录镜像。
无论镜像成功还是失败，在此之后都应使用最佳可用的消息快照调用上下文引擎终结器：
镜像写入成功或失败后，使用可用的最佳消息快照调用上下文引擎终结器：
- 优先使用写入后的完整镜像会话上下文，因为 `afterTurn`
期望的是会话快照，而不只是当前回合。
- 优先使用写入后的完整镜像会话上下文，因为 `afterTurn` 期望的是会话快照，而不仅是当前轮次。
- 如果无法重新打开会话文件，则回退到 `historyMessages + result.messagesSnapshot`。
伪流程：
@ -391,83 +359,73 @@ await finalizeHarnessContextEngineTurn({
});
```
如果镜像失败，仍然要使用回退快照调用 `afterTurn`，但要记录
上下文引擎正在使用回退回合数据进行摄取。
如果镜像写入失败，仍然使用回退快照调用 `afterTurn`，但要记录上下文引擎正在从回退轮次数据摄取。
### 7. 规范化 usage 和 prompt-cache 运行时上下文
### 7. 规范化用量和提示缓存运行时上下文
Codex 结果在可用时会包含来自 app-server token 通知的规范化 usage。
将该 usage 传入上下文引擎运行时上下文。
Codex 结果会在可用时包含来自应用服务器令牌通知的规范化用量。将该用量传入上下文引擎运行时上下文。
如果 Codex app-server 将来暴露 cache read/write 详情，则将其映射到
`ContextEnginePromptCacheInfo`。在此之前，应省略 `promptCache`，而不是虚构零值。
如果 Codex 应用服务器最终公开缓存读写详情，请将其映射到 `ContextEnginePromptCacheInfo`。在此之前，省略 `promptCache`，不要编造零值。
### 8. 压缩策略
存在两套压缩系统：
有两个压缩系统：
1. OpenClaw 上下文引擎 `compact()`
2. Codex app-server 原生 `thread/compact/start`
2. Codex 应用服务器原生 `thread/compact/start`
不要静默地将它们混为一谈。
不要悄悄把它们混为一谈。
#### `/compact` 和显式 OpenClaw 压缩
当所选上下文引擎满足 `info.ownsCompaction === true` 时，显式
OpenClaw 压缩应优先使用上下文引擎的 `compact()` 结果来处理 OpenClaw 转录镜像和插件状态。
当所选上下文引擎的 `info.ownsCompaction === true` 时，显式 OpenClaw 压缩应优先把上下文引擎的 `compact()` 结果用于 OpenClaw 转录镜像和插件状态。
当所选 Codex harness 具有原生线程绑定时，我们还可以额外请求
Codex 原生压缩，以保持 app-server 线程健康，但这必须在 details 中作为一个独立的后端动作报告。
当所选 Codex harness 具有原生线程绑定时，我们还可以额外请求 Codex 原生压缩，以保持应用服务器线程健康，但这必须在详情中报告为单独的后端操作。
建议行为：
推荐行为：
- 如果 `contextEngine.info.ownsCompaction === true`：
- 先调用上下文引擎 `compact()`
- 然后在存在线程绑定时尽最大努力调用 Codex 原生压缩
- 返回上下文引擎结果作为主结果
- 然后在存在线程绑定时尽力调用 Codex 原生压缩
- 将上下文引擎结果作为主结果返回
- 在 `details.codexNativeCompaction` 中包含 Codex 原生压缩状态
- 如果活动上下文引擎不拥有压缩职责：
- 如果活动上下文引擎不拥有压缩：
- 保留当前 Codex 原生压缩行为
这很可能需要更改 `extensions/codex/src/app-server/compact.ts`，或从通用压缩路径对其进行包装，具体取决于
`maybeCompactAgentHarnessSession(...)` 的调用位置。
这可能需要修改 `extensions/codex/src/app-server/compact.ts`，或从通用压缩路径对其进行封装，具体取决于 `maybeCompactAgentHarnessSession(...)` 的调用位置。
#### 回合内 Codex 原生 `contextCompaction` 事件
#### 轮次内 Codex 原生 `contextCompaction` 事件
Codex 可能会在回合期间发出 `contextCompaction` item 事件。保留当前
`event-projector.ts` 中 before/after 压缩钩子的发出逻辑，但不要将其视为一次已完成的上下文引擎压缩。
Codex 可能会在轮次期间发出 `contextCompaction` 条目事件。保留 `event-projector.ts` 中当前的压缩前/后钩子发出逻辑，但不要把它视为已完成的上下文引擎压缩。
对于拥有压缩职责的引擎，当 Codex 仍然执行原生压缩时，发出一个显式诊断：
对于拥有压缩的引擎，当 Codex 仍然执行原生压缩时，发出显式诊断：
- 流 / 事件名称：现有的 `compaction` 流可以接受
- details：`{ backend: "codex-app-server", ownsCompaction: true }`
- 流/事件名称：可以使用现有 `compaction` 流
- 详情：`{ backend: "codex-app-server", ownsCompaction: true }`
这样可以让这一区分具有可审计性。
这使两者的拆分可审计。
### 9. 会话重置和绑定行为
现有的 Codex harness `reset(...)` 会从
OpenClaw 会话文件中清除 Codex app-server 绑定。保留这一行为。
现有 Codex harness 的 `reset(...)` 会从 OpenClaw 会话文件中清除 Codex 应用服务器绑定。保留该行为。
同时还要确保上下文引擎状态清理继续通过现有的
OpenClaw 会话生命周期路径进行。不要添加 Codex 特定的清理逻辑，除非当前所有 harness 的上下文引擎生命周期都遗漏了 reset/delete 事件。
还要确保上下文引擎状态清理继续通过现有 OpenClaw 会话生命周期路径进行。除非当前上下文引擎生命周期对所有 harness 都遗漏了重置/删除事件，否则不要添加 Codex 专属清理逻辑。
### 10. 错误处理
遵循 PI 语义：
- bootstrap 失败时发出警告并继续
- assemble 失败时发出警告，并回退到未组装的流水线消息 / 提示词
- afterTurn/ingest 失败时发出警告，并将回合后终结标记为不成功
- maintenance 仅在成功、未中止、未 yield 的回合后运行
- 压缩错误不应作为新的提示词进行重试
- 启动失败时警告并继续
- 组装失败时警告，并回退到未组装的管线消息/提示
- `afterTurn`/摄取失败时警告，并标记轮次后终结不成功
- 维护仅在成功、非中止、非让出中止的轮次后运行
- 压缩错误不应作为新提示重试
Codex 特定补充：
Codex 专属补充：
- 如果上下文投影失败，发出警告并回退到原始提示词。
- 如果转录镜像失败，仍然尝试使用回退消息执行上下文引擎终结。
- 如果在上下文引擎压缩成功之后，Codex 原生压缩失败，
则当上下文引擎是主路径时，不应让整个 OpenClaw 压缩失败。
- 如果上下文投影失败，警告并回退到原始提示。
- 如果转录镜像失败，仍然尝试使用回退消息进行上下文引擎终结。
- 如果上下文引擎压缩成功后 Codex 原生压缩失败，当上下文引擎是主系统时，不要让整个 OpenClaw 压缩失败。
## 测试计划
@ -476,54 +434,49 @@ Codex 特定补充：
在 `extensions/codex/src/app-server` 下添加测试：
1. `run-attempt.context-engine.test.ts`
- 当会话文件存在时，Codex 会调用 `bootstrap`。
- Codex 会使用镜像消息、token budget、工具名称、
citations 模式、model id 和 prompt 调用 `assemble`。
- `systemPromptAddition` 会包含在 developer instructions 中。
- 组装后的消息会在当前请求之前投影到提示词中。
- Codex 会在转录镜像后调用 `afterTurn`。
- 没有 `afterTurn` 时，Codex 会调用 `ingestBatch` 或逐消息 `ingest`。
- 回合 maintenance 会在成功回合后运行。
- 当提示词错误、中止或 yield 中止时，不会运行回合 maintenance。
- 存在会话文件时，Codex 调用 `bootstrap`。
- Codex 使用镜像消息、令牌预算、工具名称、引用模式、模型 ID 和提示调用 `assemble`。
- `systemPromptAddition` 被包含在开发者指令中。
- 组装后的消息会在当前请求前投影到提示中。
- Codex 在转录镜像后调用 `afterTurn`。
- 没有 `afterTurn` 时，Codex 调用 `ingestBatch` 或逐条消息的 `ingest`。
- 轮次维护在成功轮次后运行。
- 轮次维护不会在提示错误、中止或让出中止时运行。
2. `context-engine-projection.test.ts`
- 对相同输入输出稳定
- 当组装历史已包含当前提示词时，不重复当前提示词
- 相同输入的输出稳定
- 当组装历史已经包含当前提示时，不重复当前提示
- 处理空历史
- 保留角色顺序
- 仅在 developer instructions 中包含 system prompt addition
- 仅在开发者指令中包含系统提示补充
3. `compact.context-engine.test.ts`
- 拥有压缩职责的上下文引擎主结果优先生效
- 当也尝试了 Codex 原生压缩时，details 中会出现其状态
- Codex 原生失败不会导致拥有压缩职责的上下文引擎压缩失败
- 不拥有压缩职责的上下文引擎会保留当前原生压缩行为
- 拥有压缩的上下文引擎主结果胜出
- 同时尝试 Codex 原生压缩时，其状态会出现在详情中
- Codex 原生失败不会导致拥有压缩的上下文引擎压缩失败
- 不拥有压缩的上下文引擎保留当前原生压缩行为
### 需要更新的现有测试
- `extensions/codex/src/app-server/run-attempt.test.ts`，如果存在；否则更新
最接近的 Codex app-server 运行测试。
- `extensions/codex/src/app-server/event-projector.test.ts`，仅当压缩
事件 details 发生变化时。
- `src/agents/harness/selection.test.ts` 应无需更改，除非配置
行为发生变化；它应保持稳定。
- PI 上下文引擎测试应继续保持不变并通过。
- 如存在，更新 `extensions/codex/src/app-server/run-attempt.test.ts`；否则更新最近的 Codex 应用服务器运行测试。
- 仅在压缩事件详情变化时更新 `extensions/codex/src/app-server/event-projector.test.ts`。
- 除非配置行为变化，否则 `src/agents/harness/selection.test.ts` 不应需要修改；它应保持稳定。
- PI 上下文引擎测试应继续原样通过。
### 集成 / 实时测试
### 集成 / 现场测试
添加或扩展实时 Codex harness 冒烟测试：
添加或扩展现场 Codex harness 冒烟测试：
- 将 `plugins.slots.contextEngine` 配置为测试引擎
- 将 `agents.defaults.model` 配置为 `codex/*` 模型
- 配置 `agents.defaults.embeddedHarness.runtime = "codex"`
- 断言测试引擎观察到了：
- 断言测试引擎观察到：
- bootstrap
- assemble
- afterTurn 或 ingest
- maintenance
避免在 OpenClaw 核心测试中要求使用 lossless-claw。请使用仓库内一个小型的 fake
上下文引擎插件。
避免在 OpenClaw 核心测试中要求 lossless-claw。使用一个小型仓库内伪上下文引擎插件。
## 可观测性
@ -532,15 +485,15 @@ Codex 特定补充：
- `codex context engine bootstrap started/completed/failed`
- `codex context engine assemble applied`
- `codex context engine finalize completed/failed`
- `codex context engine maintenance skipped` 并附带原因
- `codex context engine maintenance skipped`，带原因
- `codex native compaction completed alongside context-engine compaction`
避免记录完整提示词或转录内容。
避免记录完整提示或转录内容。
在合适时添加结构化字段：
在有用的地方添加结构化字段：
- `sessionId`
- `sessionKey` 根据现有日志实践进行脱敏或省略
- `sessionKey` 按现有日志实践脱敏或省略
- `engineId`
- `threadId`
- `turnId`
@ -552,52 +505,38 @@ Codex 特定补充：
这应当向后兼容：
- 如果未配置上下文引擎，则旧版上下文引擎行为应与当前 Codex harness 行为等价。
- 如果上下文引擎 `assemble` 失败，Codex 应继续使用原始
提示词路径。
- 现有 Codex 线程绑定应继续有效。
- 动态工具指纹不应包含上下文引擎输出；否则
每次上下文变化都可能强制创建一个新 Codex 线程。只有工具目录
应影响动态工具指纹。
- 如果未配置上下文引擎，旧版上下文引擎行为应等同于当前 Codex harness 行为。
- 如果上下文引擎 `assemble` 失败，Codex 应继续使用原始提示路径。
- 现有 Codex 线程绑定应保持有效。
- 动态工具指纹不应包含上下文引擎输出；否则每次上下文变化都可能强制创建新的 Codex 线程。只有工具目录应影响动态工具指纹。
## 未决问题
1. 组装后的上下文应全部注入到用户提示词中、全部
注入到 developer instructions 中，还是拆分处理？
1. 组装后的上下文应完全注入用户提示、完全注入开发者指令，还是拆分？
建议：拆分。将 `systemPromptAddition` 放入 developer instructions；
将组装后的转录上下文放入用户提示词包装中。这最符合
当前 Codex 协议，同时不会修改原生线程历史。
建议：拆分。将 `systemPromptAddition` 放入开发者指令；将组装后的转录上下文放入用户提示包装器。这最符合当前 Codex 协议，且不会改变原生线程历史。
2. 当上下文引擎拥有
压缩职责时，是否应禁用 Codex 原生压缩？
2. 当上下文引擎拥有压缩时，是否应禁用 Codex 原生压缩？
建议：不，至少初期不这样做。Codex 原生压缩可能仍然
是维持 app-server 线程存活所必需的。但它必须被报告为
Codex 原生压缩，而不是上下文引擎压缩。
建议：一开始不要。Codex 原生压缩可能仍然是保持应用服务器线程存活所必需的。但必须将其报告为原生 Codex 压缩，而不是上下文引擎压缩。
3. `before_prompt_build` 应在上下文引擎组装之前还是之后运行？
建议：对于 Codex，在上下文引擎投影之后运行，这样通用 harness
钩子就能看到 Codex 将实际接收的提示词 / developer instructions。如果为了与 PI
保持一致需要相反顺序，请在测试中编码选定顺序，并在
此处记录。
建议：对于 Codex，在上下文引擎投影之后运行，这样通用 harness 钩子能看到 Codex 实际会收到的提示/开发者指令。如果 PI 对等性要求相反顺序，请在测试中编码所选顺序，并在此处记录。
4. Codex app-server 是否可以接受未来的结构化上下文 / 历史覆盖？
4. Codex 应用服务器未来能否接受结构化上下文/历史覆盖？
未知。如果可以，则用该协议替换文本投影层，并保持生命周期调用不变。
未知。如果可以，用该协议替换文本投影层，并保持生命周期调用不变。
## 验收标准
- 一个 `codex/*` 嵌入式 harness 回合会调用所选上下文引擎的
assemble 生命周期。
- 上下文引擎 `systemPromptAddition` 会影响 Codex developer instructions。
- 组装后的上下文会以确定性方式影响 Codex 回合输入。
- 成功的 Codex 回合会调用 `afterTurn` 或 ingest 回退路径。
- 成功的 Codex 回合会运行上下文引擎回合 maintenance。
- 失败 / 中止 / yield 中止的回合不会运行回合 maintenance。
- 由上下文引擎拥有的压缩对于 OpenClaw / 插件状态仍然是主路径。
- Codex 原生压缩仍然可以作为原生 Codex 行为被审计。
- 现有 PI 上下文引擎行为保持不变。
- 当未选择非旧版上下文引擎
或当组装失败时，现有 Codex harness 行为保持不变。
- `codex/*` embedded harness 轮次会调用所选上下文引擎的组装生命周期。
- 上下文引擎的 `systemPromptAddition` 会影响 Codex 开发者指令。
- 组装后的上下文会确定性地影响 Codex 轮次输入。
- 成功的 Codex 轮次会调用 `afterTurn` 或摄取回退。
- 成功的 Codex 轮次会运行上下文引擎轮次维护。
- 失败/中止/让出中止的轮次不会运行轮次维护。
- 上下文引擎拥有的压缩仍然是 OpenClaw/插件状态的主结果。
- Codex 原生压缩仍可作为原生 Codex 行为审计。
- 现有 PI 上下文引擎行为不变。
- 当未选择非旧版上下文引擎或组装失败时，现有 Codex harness 行为不变。

234
docs/zh-CN/plugins/codex-computer-use.md
View File

@ -4,56 +4,59 @@ read_when:
- 你正在 Codex Computer Use、PeekabooBridge 和直接使用 cua-driver MCP 之间做选择
- 你正在 Codex Computer Use 和直接的 cua-driver MCP 设置之间做选择
- 你正在为内置 Codex 插件配置 computerUse
- 你正在排查 /codex computer-use status 或 install
summary: 为 Codex 模式的 OpenClaw 智能体设置 Codex Computer Use
- 你正在对 /codex computer-use status 或 install 进行故障排除
summary: 为 Codex 模式的 OpenClaw 智能体设置 Codex 计算机使用
title: Codex 计算机使用
x-i18n:
generated_at: "2026-04-29T21:01:18Z"
generated_at: "2026-05-03T04:51:13Z"
model: gpt-5.5
provider: openai
source_hash: 3e3551b9005cdc8084d159c107f9b5039a4b4624847b8cc6e5bcb620510fd54f
source_hash: 08383e88ca02dccc86c622c3295478e950fdd222ef16947465e0de1dacafa56c
source_path: plugins/codex-computer-use.md
workflow: 16
---
Computer Use 是用于本地桌面控制的 Codex 原生 MCP 插件。OpenClaw
不会内置该桌面应用、自己执行桌面操作，也不会绕过 Codex 权限。内置的 `codex` 插件只会准备 Codex app-server：
Computer Use 是 Codex 原生的 MCP 插件，用于本地桌面控制。OpenClaw
不会内置该桌面应用、自己执行桌面操作，也不会绕过
Codex 权限。内置的 `codex` 插件只会准备 Codex app-server：
它会启用 Codex 插件支持，查找或安装已配置的 Codex
Computer Use 插件，检查 `computer-use` MCP 服务器是否可用，然后
在 Codex 模式回合期间让 Codex 拥有原生 MCP 工具调用。
在 Codex 模式轮次期间让 Codex 负责原生 MCP 工具调用。
当 OpenClaw 已经在使用原生 Codex harness 时，请使用本页面。关于
当 OpenClaw 已经在使用原生 Codex harness 时，请使用此页面。关于
运行时设置本身，请参阅 [Codex harness](/zh-CN/plugins/codex-harness)。
## OpenClaw.app 和 Peekaboo
OpenClaw.app 的 Peekaboo 集成独立于 Codex Computer Use。该
macOS 应用可以托管一个 PeekabooBridge socket，以便 `peekaboo` CLI 可以复用该
应用本地的辅助功能和屏幕录制授权，供 Peekaboo 自己的
自动化工具使用。该 bridge 不会安装或代理 Codex Computer Use，并且
Codex Computer Use 不会通过 PeekabooBridge socket 调用。
macOS 应用可以托管 PeekabooBridge 套接字，让 `peekaboo` CLI 复用
应用的本地辅助功能和屏幕录制授权，以供 Peekaboo 自身的自动化
工具使用。该桥接不会安装或代理 Codex Computer Use，且
Codex Computer Use 不会通过 PeekabooBridge 套接字调用。
当你希望 OpenClaw.app 成为 Peekaboo CLI 自动化的
权限感知主机时，请使用 [Peekaboo bridge](/zh-CN/platforms/mac/peekaboo)。当一个
Codex 模式的 OpenClaw 智能体需要在回合开始前可用 Codex 原生的 `computer-use` MCP 插件时，请使用本页面。
当你希望 OpenClaw.app 成为 Peekaboo CLI 自动化的权限感知宿主时，
请使用 [Peekaboo bridge](/zh-CN/platforms/mac/peekaboo)。当 Codex 模式的
OpenClaw 智能体应在轮次开始前可使用 Codex 原生的 `computer-use` MCP 插件时，
请使用此页面。
## iOS 应用
iOS 应用独立于 Codex Computer Use。它不会安装或代理
Codex `computer-use` MCP 服务器，也不是桌面控制后端。
相反，iOS 应用会作为 OpenClaw 节点连接，并通过节点命令暴露移动端
能力，例如 `canvas.*`、`camera.*`、`screen.*`、
`location.*` 和 `talk.*`。
相反，iOS 应用会作为 OpenClaw 节点连接，并通过
`canvas.*`、`camera.*`、`screen.*`、`location.*` 和 `talk.*` 等节点命令暴露移动端
能力。
当你希望智能体通过 Gateway 网关驱动 iPhone 节点时，请使用 [iOS](/zh-CN/platforms/ios)。
当 Codex 模式智能体应通过 Codex 原生 Computer Use 插件控制本地
macOS 桌面时，请使用本页面。
当你希望智能体通过 Gateway 网关驱动 iPhone 节点时，请使用
[iOS](/zh-CN/platforms/ios)。当 Codex 模式智能体应通过 Codex 原生的
Computer Use 插件控制本地 macOS 桌面时，请使用此页面。
## 直接使用 cua-driver MCP
Codex Computer Use 不是暴露桌面控制的唯一方式。如果你希望
OpenClaw 管理的运行时直接调用 TryCua 的 driver，请通过 OpenClaw 的 MCP 注册表使用上游
`cua-driver mcp` 服务器，而不是 Codex 专用的 marketplace 流程。
Codex Computer Use 并不是暴露桌面控制的唯一方式。如果你希望
OpenClaw 管理的运行时直接调用 TryCua 的驱动，请通过 OpenClaw 的
MCP 注册表使用上游 `cua-driver mcp` 服务器，而不是使用
Codex 专用的 marketplace 流程。
安装 `cua-driver` 后，可以让它输出 OpenClaw 命令：
@ -61,27 +64,25 @@ OpenClaw 管理的运行时直接调用 TryCua 的 driver，请通过 OpenClaw
cua-driver mcp-config --client openclaw
```
或者自行注册 stdio 服务器：
或自行注册 stdio 服务器：
```bash
openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'
```
这条路径会保持上游 MCP 工具表面不变，包括 driver
schema 和结构化 MCP 响应。当你希望 CUA driver
作为普通 OpenClaw MCP 服务器可用时，请使用它。当 Codex app-server 应在
Codex 模式回合内负责插件安装、MCP 重载和原生工具调用时，请使用本页面的
Codex Computer Use 设置。
该路径会保持上游 MCP 工具接口不变，包括驱动
schema 和结构化 MCP 响应。当你希望 CUA 驱动作为普通的 OpenClaw MCP 服务器
可用时，请使用它。当 Codex app-server 应在 Codex 模式轮次内负责插件安装、
MCP 重新加载和原生工具调用时，请使用本页的 Codex Computer Use 设置。
CUA 的 driver 仅适用于 macOS，并且仍然需要其应用提示的本地 macOS 权限，
例如辅助功能和屏幕录制。OpenClaw
不会安装 `cua-driver`、授予这些权限，也不会绕过上游
driver 的安全模型。
CUA 的驱动仅适用于 macOS，并且仍然需要其应用提示获取的本地 macOS 权限，
例如辅助功能和屏幕录制。OpenClaw 不会安装 `cua-driver`、授予这些权限，
或绕过上游驱动的安全模型。
## 快速设置
当 Codex 模式回合必须在 thread 开始前可用
Computer Use 时，设置 `plugins.entries.codex.config.computerUse`：
当 Codex 模式轮次必须在会话串开始前可使用 Computer Use 时，请设置
`plugins.entries.codex.config.computerUse`：
```json5
{
@ -102,30 +103,28 @@ Computer Use 时，设置 `plugins.entries.codex.config.computerUse`：
model: "openai/gpt-5.5",
agentRuntime: {
id: "codex",
fallback: "none",
},
},
},
}
```
使用此配置时，OpenClaw 会在每个 Codex 模式回合前检查 Codex app-server。
如果缺少 Computer Use，但 Codex app-server 已经发现了可安装的
marketplace，OpenClaw 会要求 Codex app-server 安装或重新启用
该插件并重载 MCP 服务器。在 macOS 上，如果没有注册匹配的 marketplace，
并且标准 Codex 应用 bundle 存在，OpenClaw 还会尝试从
`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 注册内置 Codex marketplace，
然后才会失败。如果设置仍然无法让 MCP 服务器可用，该回合会在
thread 开始前失败。
使用此配置时，OpenClaw 会在每个 Codex 模式轮次前检查 Codex app-server。
如果缺少 Computer Use，但 Codex app-server 已发现可安装的 marketplace，
OpenClaw 会请求 Codex app-server 安装或重新启用该插件并重新加载 MCP 服务器。
在 macOS 上，如果没有注册匹配的 marketplace 且存在标准 Codex 应用包，
OpenClaw 还会在失败前尝试从
`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 注册内置的 Codex marketplace。
如果设置仍无法让 MCP 服务器可用，该轮次会在会话串开始前失败。
现有会话会保留其运行时和 Codex thread 绑定。更改
`agentRuntime` 或 Computer Use 配置后，请在受影响的
聊天中使用 `/new` 或 `/reset`，然后再测试。
现有会话会保留其运行时和 Codex 会话串绑定。更改
`agentRuntime` 或 Computer Use 配置后，请在受影响的聊天中使用
`/new` 或 `/reset` 后再测试。
## 命令
在任何提供 `codex` 插件命令表面的聊天界面中使用 `/codex computer-use`
命令。这些是 OpenClaw 聊天/运行时命令，
在任何可使用 `codex` 插件命令界面的聊天表面中使用
`/codex computer-use` 命令。这些是 OpenClaw 聊天/运行时命令，
不是 `openclaw codex ...` CLI 子命令：
```text
@ -136,42 +135,42 @@ thread 开始前失败。
/codex computer-use install --marketplace <name>
```
`status` 是只读的。它不会添加 marketplace source、安装插件，也不会
启用 Codex 插件支持。
`status` 是只读的。它不会添加 marketplace 来源、安装插件，
或启用 Codex 插件支持。
`install` 会启用 Codex app-server 插件支持，可选地添加已配置的
marketplace source，通过 Codex app-server 安装或重新启用已配置的插件，
重载 MCP 服务器，并验证 MCP 服务器是否暴露工具。
marketplace 来源，通过 Codex app-server 安装或重新启用已配置的插件，
重新加载 MCP 服务器，并验证 MCP 服务器是否暴露工具。
## Marketplace 选择
OpenClaw 使用 Codex 自身暴露的同一个 app-server API。
marketplace 字段用于选择 Codex 应从哪里找到 `computer-use`。
marketplace 字段用于选择 Codex 应从哪里查找 `computer-use`。
| 字段 | 适用场景 | 安装支持 |
| -------------------- | --------------------------------------------------------------- | -------------------------------------------------------- |
| 无 marketplace 字段 | 你希望 Codex app-server 使用它已知的 marketplace。 | 是，当 app-server 返回本地 marketplace 时。 |
| `marketplaceSource` | 你有 Codex app-server 可以添加的 Codex marketplace source。 | 是，用于显式 `/codex computer-use install`。 |
| `marketplacePath` | 你已经知道主机上的本地 marketplace 文件路径。 | 是，用于显式安装和回合开始自动安装。 |
| `marketplaceName` | 你希望按名称选择一个已注册的 marketplace。 | 仅当所选 marketplace 有本地路径时支持。 |
| 无 marketplace 字段 | 你希望 Codex app-server 使用它已经知道的 marketplace。 | 支持，当 app-server 返回本地 marketplace 时。 |
| `marketplaceSource` | 你有一个 Codex marketplace 来源，app-server 可以添加它。 | 支持，用于显式 `/codex computer-use install`。 |
| `marketplacePath` | 你已经知道主机上的本地 marketplace 文件路径。 | 支持，用于显式安装和轮次开始自动安装。 |
| `marketplaceName` | 你希望按名称选择一个已注册的 marketplace。 | 仅当所选 marketplace 有本地路径时支持。 |
新的 Codex home 可能需要短暂时间来填充官方 marketplace。
安装期间，OpenClaw 会轮询 `plugin/list`，最长
全新的 Codex 主目录可能需要短暂时间来填充其官方 marketplace。
安装期间，OpenClaw 会轮询 `plugin/list`，最长持续
`marketplaceDiscoveryTimeoutMs` 毫秒。默认值为 60 秒。
如果多个已知 marketplace 包含 Computer Use，OpenClaw 会优先选择
`openai-bundled`，然后是 `openai-curated`，再是 `local`。未知的歧义匹配
`openai-bundled`，其次是 `openai-curated`，然后是 `local`。未知的歧义匹配
会安全失败，并要求你设置 `marketplaceName` 或 `marketplacePath`。
## 内置 macOS marketplace
近期 Codex 桌面版构建会在这里内置 Computer Use：
较新的 Codex 桌面版构建会在这里内置 Computer Use：
```text
/Applications/Codex.app/Contents/Resources/plugins/openai-bundled/plugins/computer-use
```
当 `computerUse.autoInstall` 为 true 且没有注册包含
当 `computerUse.autoInstall` 为 true 且未注册包含
`computer-use` 的 marketplace 时，OpenClaw 会尝试自动添加标准内置
marketplace 根目录：
@ -179,25 +178,25 @@ marketplace 根目录：
/Applications/Codex.app/Contents/Resources/plugins/openai-bundled
```
你也可以从 shell 使用 Codex 显式注册它：
你也可以通过 shell 使用 Codex 显式注册它：
```bash
codex plugin marketplace add /Applications/Codex.app/Contents/Resources/plugins/openai-bundled
```
如果你使用非标准 Codex 应用路径，请将 `computerUse.marketplacePath` 设置为
本地 marketplace 文件路径，或先运行一次 `/codex computer-use install --source
如果你使用非标准 Codex 应用路径，请将 `computerUse.marketplacePath` 设置为本地
marketplace 文件路径，或运行一次 `/codex computer-use install --source
<marketplace-source>`。
## 远程目录限制
Codex app-server 可以列出和读取仅远程目录条目，但目前不支持
远程 `plugin/install`。这意味着 `marketplaceName` 可以选择仅远程
marketplace 用于状态检查，但安装和重新启用仍然需要通过
`marketplaceSource` 或 `marketplacePath` 提供本地 marketplace。
Codex app-server 可以列出和读取仅远程的目录条目，但目前不支持远程
`plugin/install`。这意味着 `marketplaceName` 可以为状态检查选择
仅远程 marketplace，但安装和重新启用仍然需要通过 `marketplaceSource` 或
`marketplacePath` 提供本地 marketplace。
如果状态显示该插件在远程 Codex marketplace 中可用，但不支持远程
安装，请使用本地 source 或 path 运行 install：
如果状态显示该插件在远程 Codex marketplace 中可用，但不支持远程安装，
请使用本地来源或路径运行安装：
```text
/codex computer-use install --source <marketplace-source>
@ -208,74 +207,67 @@ marketplace 用于状态检查，但安装和重新启用仍然需要通过
| 字段 | 默认值 | 含义 |
| ------------------------------- | -------------- | ------------------------------------------------------------------------------ |
| `enabled` | 推断 | 要求 Computer Use。设置其他 Computer Use 字段时默认为 true。 |
| `autoInstall` | false | 在回合开始时从已发现的 marketplace 安装或重新启用。 |
| `marketplaceDiscoveryTimeoutMs` | 60000 | install 等待 Codex app-server marketplace 发现的时长。 |
| `marketplaceSource` | 未设置 | 传递给 Codex app-server `marketplace/add` 的 source 字符串。 |
| `marketplacePath` | 未设置 | 包含该插件的本地 Codex marketplace 文件路径。 |
| `marketplaceName` | 未设置 | 要选择的已注册 Codex marketplace 名称。 |
| `pluginName` | `computer-use` | Codex marketplace 插件名称。 |
| `mcpServerName` | `computer-use` | 已安装插件暴露的 MCP 服务器名称。 |
| `enabled` | inferred | 要求使用 Computer Use。当设置了另一个 Computer Use 字段时，默认为 true。 |
| `autoInstall` | false | 在轮次开始时从已发现的 marketplace 安装或重新启用。 |
| `marketplaceDiscoveryTimeoutMs` | 60000 | 安装等待 Codex app-server 发现 marketplace 的时长。 |
| `marketplaceSource` | unset | 传递给 Codex app-server `marketplace/add` 的来源字符串。 |
| `marketplacePath` | unset | 包含该插件的本地 Codex marketplace 文件路径。 |
| `marketplaceName` | unset | 要选择的已注册 Codex marketplace 名称。 |
| `pluginName` | `computer-use` | Codex marketplace 插件名称。 |
| `mcpServerName` | `computer-use` | 已安装插件暴露的 MCP 服务器名称。 |
回合开始自动安装会有意拒绝已配置的 `marketplaceSource`
值。添加新 source 是显式设置操作，因此请先使用
`/codex computer-use install --source <marketplace-source>` 一次，然后让
`autoInstall` 以后从已发现的本地 marketplace 处理重新启用。
回合开始自动安装可以使用已配置的 `marketplacePath`，因为它
已经是主机上的本地路径。
轮次开始自动安装会有意拒绝已配置的 `marketplaceSource` 值。
添加新来源是显式设置操作，因此请先运行一次
`/codex computer-use install --source <marketplace-source>`，然后让
`autoInstall` 处理以后从已发现本地 marketplace 的重新启用。
轮次开始自动安装可以使用已配置的 `marketplacePath`，因为它已经是主机上的
本地路径。
## OpenClaw 会检查什么
## OpenClaw 检查的内容
OpenClaw 会在内部报告稳定的设置原因，并为聊天格式化面向用户的
Status：
OpenClaw 会在内部报告稳定的设置原因，并为聊天格式化面向用户的状态：
| 原因 | 含义 | 下一步 |
| ---------------------------- | ------------------------------------------------------ | --------------------------------------------- |
| `disabled` | `computerUse.enabled` 解析为 false。 | 设置 `enabled` 或其他 Computer Use 字段。 |
| `marketplace_missing` | 没有可用的匹配 marketplace。 | 配置 source、path 或 marketplace name。 |
| `plugin_not_installed` | marketplace 存在，但插件未安装。 | 运行 install 或启用 `autoInstall`。 |
| `plugin_disabled` | 插件已安装，但在 Codex 配置中被禁用。 | 运行 install 以重新启用它。 |
| `remote_install_unsupported` | 所选 marketplace 仅远程可用。 | 使用 `marketplaceSource` 或 `marketplacePath`。 |
| `mcp_missing` | 插件已启用，但 MCP 服务器不可用。 | 检查 Codex Computer Use 和操作系统权限。 |
| `ready` | 插件和 MCP 工具可用。 | 开始 Codex 模式回合。 |
| `check_failed` | 状态检查期间 Codex app-server 请求失败。 | 检查 app-server 连接和日志。 |
| `auto_install_blocked` | 回合开始设置需要添加新 source。 | 先运行显式 install。 |
| `disabled` | `computerUse.enabled` 解析为 false。 | 设置 `enabled` 或另一个 Computer Use 字段。 |
| `marketplace_missing` | 没有可用的匹配 marketplace。 | 配置来源、路径或 marketplace 名称。 |
| `plugin_not_installed` | marketplace 存在，但插件未安装。 | 运行安装或启用 `autoInstall`。 |
| `plugin_disabled` | 插件已安装但在 Codex 配置中被禁用。 | 运行安装以重新启用它。 |
| `remote_install_unsupported` | 所选 marketplace 仅支持远程。 | 使用 `marketplaceSource` 或 `marketplacePath`。 |
| `mcp_missing` | 插件已启用，但 MCP 服务器不可用。 | 检查 Codex Computer Use 和 OS 权限。 |
| `ready` | 插件和 MCP 工具可用。 | 启动 Codex 模式轮次。 |
| `check_failed` | 状态检查期间 Codex app-server 请求失败。 | 检查 app-server 连接和日志。 |
| `auto_install_blocked` | 轮次开始设置需要添加新来源。 | 先运行显式安装。 |
聊天输出包含插件状态、MCP 服务器状态、marketplace、可用时的工具，
聊天输出会包含插件状态、MCP 服务器状态、marketplace、可用时的工具，
以及失败设置步骤的具体消息。
## macOS 权限
Computer Use 仅适用于 macOS。Codex 拥有的 MCP 服务器可能需要本地操作系统
权限，才能检查或控制应用。如果 OpenClaw 表示 Computer Use
已安装但 MCP 服务器不可用，请先验证 Codex 侧的 Computer
Use 设置：
Computer Use 仅适用于 macOS。Codex 负责的 MCP 服务器在检查或控制应用前
可能需要本地 OS 权限。如果 OpenClaw 表示 Computer Use 已安装但
MCP 服务器不可用，请先验证 Codex 侧的 Computer Use 设置：
- Codex app-server 正在应发生桌面控制的同一台主机上运行。
- Codex 配置中已启用 Computer Use 插件。
- Codex app-server 正在需要进行桌面控制的同一台主机上运行。
- Computer Use 插件已在 Codex 配置中启用。
- `computer-use` MCP 服务器出现在 Codex app-server MCP Status 中。
- macOS 已为桌面控制应用授予所需权限。
- 当前主机会话可以访问正在控制的桌面。
- macOS 已授予桌面控制应用所需的权限。
- 当前主机会话可以访问被控制的桌面。
当 `computerUse.enabled` 为 true 时，OpenClaw 会有意采用失败即关闭策略。
Codex 模式的轮次不应在缺少配置所要求的原生桌面工具时静默继续。
当 `computerUse.enabled` 为 true 时，OpenClaw 会有意采用默认拒绝策略。Codex 模式的回合不应在缺少配置所要求的原生桌面工具时静默继续。
## 故障排除
**Status 显示未安装。** 运行 `/codex computer-use install`。如果未发现
marketplace，请传入 `--source` 或 `--marketplace-path`。
**Status 显示未安装。** 运行 `/codex computer-use install`。如果未发现市场，请传入 `--source` 或 `--marketplace-path`。
**Status 显示已安装但已禁用。** 再次运行 `/codex computer-use install`。
Codex app-server 安装会把插件配置写回为启用状态。
**Status 显示已安装但已禁用。** 再次运行 `/codex computer-use install`。Codex app-server 安装会将插件配置写回为已启用。
**Status 显示不支持远程安装。** 使用本地 marketplace 源或路径。仅远程目录条目可以检查，但不能通过当前 app-server API 安装。
**Status 显示不支持远程安装。** 使用本地市场源或路径。仅远程的目录条目可以查看，但无法通过当前 app-server API 安装。
**Status 显示 MCP 服务器不可用。** 重新运行一次安装，以便 MCP
服务器重新加载。如果仍不可用，请修复 Codex Computer Use 应用、Codex app-server MCP Status，或 macOS 权限。
**Status 显示 MCP 服务器不可用。** 重新运行一次安装，让 MCP 服务器重新加载。如果仍不可用，请修复 Codex Computer Use 应用、Codex app-server MCP Status 或 macOS 权限。
**Status 或探测在 `computer-use.list_apps` 上超时。** 插件和 MCP
服务器已存在，但本地 Computer Use 桥接没有响应。退出或重启 Codex Computer Use，必要时重新启动 Codex Desktop，然后在新的 OpenClaw 会话中重试。
**Status 或探测在 `computer-use.list_apps` 上超时。** 插件和 MCP 服务器都存在，但本地 Computer Use 桥接没有响应。退出或重启 Codex Computer Use，必要时重新启动 Codex Desktop，然后在新的 OpenClaw 会话中重试。
**某个 Computer Use 工具显示 `Native hook relay unavailable`。** Codex 原生工具钩子无法通过本地桥接或 Gateway 网关回退连接到活动的 OpenClaw 中继。使用 `/new` 或 `/reset` 启动新的 OpenClaw 会话。如果持续发生，请重启 Gateway 网关，以丢弃旧的 app-server 线程和钩子注册，然后重试。
**Computer Use 工具提示 `Native hook relay unavailable`。** Codex 原生工具钩子无法通过本地桥接或 Gateway 网关后备路径连接到活动的 OpenClaw 中继。使用 `/new` 或 `/reset` 启动新的 OpenClaw 会话。如果持续发生，请重启 Gateway 网关，以便丢弃旧的 app-server 线程和钩子注册，然后重试。
**轮次开始时自动安装拒绝某个源。** 这是有意设计。请先使用显式的 `/codex computer-use install --source <marketplace-source>` 添加该源，之后轮次开始时的自动安装就可以使用已发现的本地 marketplace。
**回合开始时的自动安装拒绝某个源。** 这是有意设计的。请先使用显式命令 `/codex computer-use install --source <marketplace-source>` 添加该源，之后回合开始时的自动安装就可以使用已发现的本地市场。

577
docs/zh-CN/plugins/codex-harness.md
View File

@ -2,39 +2,39 @@
read_when:
- 你想使用内置的 Codex app-server harness
- 你需要 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-05-02T22:26:00Z"
generated_at: "2026-05-03T04:51:04Z"
model: gpt-5.5
provider: openai
source_hash: 8ffa0cbb28422b2ed8d7c0eef6ee0222072c523d170b4b33597bb37bd3fa9700
source_hash: 83cb442bb2b87fdfe530619e8951bc8f4f5a7d3bfd68ca49eeb16bbdd8b189b4
source_path: plugins/codex-harness.md
workflow: 16
---
内置的 `codex` 插件让 OpenClaw 通过 Codex 应用服务器运行嵌入式智能体轮次，而不是使用内置 Pi harness。
内置的 `codex` 插件让 OpenClaw 通过 Codex 应用服务器运行嵌入式智能体轮次，而不是使用内置的 PI harness。
当你希望 Codex 接管底层智能体会话时，请使用它：模型发现、原生线程恢复、原生压缩和应用服务器执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体投递和可见 transcript 镜像。
当你希望 Codex 拥有底层智能体会话时使用它：模型发现、原生线程恢复、原生压缩和应用服务器执行。OpenClaw 仍然拥有聊天渠道、会话文件、模型选择、工具、审批、媒体投递和可见的转录镜像。
当源聊天轮次通过 Codex harness 运行时，如果部署没有显式配置 `messages.visibleReplies`，可见回复默认使用 OpenClaw `message` 工具。智能体仍然可以私下完成它的 Codex 轮次；只有在调用 `message(action="send")` 时才会发布到渠道。设置 `messages.visibleReplies: "automatic"` 可让直接聊天的最终回复继续使用旧版自动投递路径。
当源聊天轮次通过 Codex harness 运行时，如果部署没有显式配置 `messages.visibleReplies`，可见回复默认使用 OpenClaw `message` 工具。智能体仍然可以私下完成它的 Codex 轮次；它只会在调用 `message(action="send")` 时发布到渠道。设置 `messages.visibleReplies: "automatic"` 可让直接聊天的最终回复继续走旧版自动投递路径。
Codex heartbeat 轮次默认也会获得 `heartbeat_respond` 工具，因此智能体可以记录这次唤醒应保持静默还是发出通知，而不需要把该控制流编码到最终文本中。
Codex 心跳轮次默认也会获得 `heartbeat_respond` 工具，因此智能体可以记录本次唤醒应保持安静还是发送通知，而不需要把该控制流编码进最终文本。
如果你正在尝试了解方向，请从 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 开始。简短版本是：`openai/gpt-5.5` 是模型 ref，`codex` 是运行时，而 Telegram、Discord、Slack 或其他渠道仍然是通信界面。
如果你想先建立整体概念，请从 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 开始。简短版本是：`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、Discord、Slack 或其他渠道仍然是通信界面。
## 快速配置
大多数想要“OpenClaw 中的 Codex”的用户想要这条路径：使用 ChatGPT/Codex 订阅登录，然后通过原生 Codex 应用服务器运行时运行嵌入式智能体轮次。模型 ref 仍然保持规范形式 `openai/gpt-*`；订阅凭证来自 Codex 账号/profile，而不是来自 `openai-codex/*` 模型前缀。
大多数想要“在 OpenClaw 中使用 Codex”的用户需要这条路线：使用 ChatGPT/Codex 订阅登录，然后通过原生 Codex 应用服务器运行时运行嵌入式智能体轮次。模型引用仍然保持规范的 `openai/gpt-*`；订阅凭证来自 Codex 账号/配置文件，而不是来自 `openai-codex/*` 模型前缀。
如果你还没有登录，请先使用 Codex OAuth 登录：
如果你尚未登录，请先使用 Codex OAuth 登录：
```bash
openclaw models auth login --provider openai-codex
```
然后启用内置的 `codex` 插件，并强制使用 Codex 运行时：
然后启用内置的 `codex` 插件并强制使用 Codex 运行时：
```json5
{
@ -50,14 +50,13 @@ openclaw models auth login --provider openai-codex
model: "openai/gpt-5.5",
agentRuntime: {
id: "codex",
fallback: "none",
},
},
},
}
```
如果你的配置使用 `plugins.allow`，也要在其中包含 `codex`：
如果你的配置使用 `plugins.allow`，也要在那里包含 `codex`：
```json5
{
@ -72,154 +71,144 @@ openclaw models auth login --provider openai-codex
}
```
当你想要原生 Codex 运行时时，不要使用 `openai-codex/gpt-*`。该前缀是显式的“通过 Pi 使用 Codex OAuth”路径。配置变更会应用到新的或重置后的会话；现有会话会保留其已记录的运行时。
当你想要原生 Codex 运行时时，不要使用 `openai-codex/gpt-*`。该前缀是显式的“通过 PI 使用 Codex OAuth”路线。配置更改会应用于新的或重置后的会话；现有会话会保留其已记录的运行时。
## 这个插件会改变什么
## 此插件会改变什么
内置的 `codex` 插件提供几项独立能力：
| 能力 | 使用方式 | 作用 |
| 能力 | 使用方式 | 作用 |
| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex 应用服务器运行 OpenClaw 嵌入式智能体轮次。 |
| 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 从消息会话中绑定并控制 Codex 应用服务器线程。 |
| Codex 应用服务器提供商/catalog | `codex` 内部机制，通过 harness 暴露 | 让运行时发现并验证应用服务器模型。 |
| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 为支持的图像理解模型运行有边界的 Codex 应用服务器轮次。 |
| 原生钩子中继 | 围绕 Codex 原生事件的插件钩子 | 让 OpenClaw 观察/阻止受支持的 Codex 原生工具/最终化事件。 |
| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex 应用服务器运行 OpenClaw 嵌入式智能体轮次。 |
| 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 从消息对话中绑定和控制 Codex 应用服务器线程。 |
| Codex 应用服务器提供商/目录 | `codex` 内部机制，通过 harness 暴露 | 让运行时发现并校验应用服务器模型。 |
| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 针对受支持的图像理解模型运行有界的 Codex 应用服务器轮次。 |
| 原生钩子中继 | 围绕 Codex 原生事件的插件钩子 | 让 OpenClaw 观察/阻止受支持的 Codex 原生工具/最终化事件。 |
启用插件会让这些能力可用。它**不会**：
启用该插件会让这些能力可用。它**不会**：
- 开始对每个 OpenAI 模型使用 Codex
- 将 `openai-codex/*` 模型 ref 转换为原生运行时
- 使 ACP/acpx 成为默认 Codex 路径
- 热切换已记录 Pi 运行时的现有会话
- 替换 OpenClaw 渠道投递、会话文件、auth-profile 存储或消息路由
- 将 `openai-codex/*` 模型引用转换为原生运行时
- 让 ACP/acpx 成为默认 Codex 路径
- 热切换已经记录 PI 运行时的现有会话
- 替换 OpenClaw 渠道投递、会话文件、凭证配置文件存储或消息路由
同一个插件还拥有原生 `/codex` 聊天控制命令界面。如果插件已启用，并且用户要求从聊天中绑定、恢复、steer、停止或检查 Codex 线程，智能体应优先使用 `/codex ...` 而不是 ACP。当用户要求 ACP/acpx，或正在测试 ACP Codex 适配器时，ACP 仍然是显式 fallback。
同一个插件也拥有原生 `/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`，用于镜像 transcript 记录
- `before_message_write` 用于镜像转录记录
- 通过 Codex `Stop` 中继的 `before_agent_finalize`
- `agent_end`
插件还可以注册运行时中立的工具结果中间件，在 OpenClaw 执行工具之后、结果返回给 Codex 之前，重写 OpenClaw 动态工具结果。这不同于公开的 `tool_result_persist` 插件钩子，后者会转换 OpenClaw 所拥有的 transcript 工具结果写入。
插件还可以注册运行时中立的工具结果中间件，用于在 OpenClaw 执行工具之后、结果返回给 Codex 之前重写 OpenClaw 动态工具结果。这与公共 `tool_result_persist` 插件钩子是分开的，后者会转换由 OpenClaw 拥有的转录工具结果写入。
关于插件钩子语义本身，请参阅 [插件钩子](/zh-CN/plugins/hooks) 和 [插件防护行为](/zh-CN/tools/plugin)。
harness 默认关闭。新配置应将 OpenAI 模型 ref 保持为规范形式 `openai/gpt-*`，并在需要原生应用服务器执行时显式强制使用 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。旧版 `codex/*` 模型 ref 仍会为了兼容性自动选择 harness，但由运行时支持的旧版提供商前缀不会显示为普通模型/提供商选项。
harness 默认关闭。新配置应将 OpenAI 模型引用保持为规范的 `openai/gpt-*`，并在需要原生应用服务器执行时显式强制设置 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。旧版 `codex/*` 模型引用仍会为兼容性自动选择该 harness，但运行时支持的旧版提供商前缀不会作为常规模型/提供商选项显示。
如果已启用 `codex` 插件，但主模型仍然是 `openai-codex/*`，`openclaw doctor` 会发出警告，而不会更改路径。这是有意的：`openai-codex/*` 仍然是 Pi Codex OAuth/订阅路径，而原生应用服务器执行仍是显式运行时选择。
如果 `codex` 插件已启用，但主模型仍是 `openai-codex/*`，`openclaw doctor` 会发出警告，而不是更改路线。这是有意设计：`openai-codex/*` 仍然是 PI Codex OAuth/订阅路径，而原生应用服务器执行仍然是一个显式运行时选择。
## 路径映射
## 路线图
更改配置前请使用此表：
| 期望行为 | 模型 ref | 运行时配置 | 凭证/profile 路径 | 预期 Status 标签 |
| 期望行为 | 模型引用 | 运行时配置 | 凭证/配置文件路线 | 预期 Status 标签 |
| ---------------------------------------------------- | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ |
| 使用原生 Codex 运行时的 ChatGPT/Codex 订阅 | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth 或 Codex 账号 | `Runtime: OpenAI Codex` |
| 通过普通 OpenClaw runner 使用 OpenAI API | `openai/gpt-*` | 省略或 `runtime: "pi"` | OpenAI API key | `Runtime: OpenClaw Pi Default` |
| 通过 Pi 使用 ChatGPT/Codex 订阅 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` |
| 使用保守 auto 模式的混合提供商 | 提供商特定 ref | `agentRuntime.id: "auto"` | 按所选提供商 | 取决于所选运行时 |
| 显式 Codex ACP 适配器会话 | 取决于 ACP prompt/模型 | `sessions_spawn`，带 `runtime: "acp"` | ACP 后端凭证 | ACP 任务/会话 Status |
| 使用原生 Codex 运行时的 ChatGPT/Codex 订阅 | `openai/gpt-*` | `agentRuntime.id: "codex"` | Codex OAuth 或 Codex 账号 | `Runtime: OpenAI Codex` |
| 通过常规 OpenClaw runner 使用 OpenAI API | `openai/gpt-*` | 省略或 `runtime: "pi"` | OpenAI API key | `Runtime: OpenClaw Pi Default` |
| 通过 PI 使用 ChatGPT/Codex 订阅 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` |
| 使用保守自动模式的混合提供商 | 提供商特定引用 | `agentRuntime.id: "auto"` | 按选定提供商 | 取决于选定的运行时 |
| 显式 Codex ACP 适配器会话 | 取决于 ACP 提示/模型 | `sessions_spawn` 搭配 `runtime: "acp"` | ACP 后端凭证 | ACP 任务/会话 Status |
关键区别是提供商与运行时：
重要的区分是提供商与运行时：
- `openai-codex/*` 回答“Pi 应使用哪个提供商/凭证路径？”
- `agentRuntime.id: "codex"` 回答“哪个 loop 应执行这个嵌入式轮次？”
- `/codex ...` 回答“这个聊天应绑定或控制哪个原生 Codex 会话？”
- `openai-codex/*` 回答“PI 应使用哪条提供商/凭证路线？”
- `agentRuntime.id: "codex"` 回答“哪个循环应执行此嵌入式轮次？”
- `/codex ...` 回答“此聊天应绑定或控制哪个原生 Codex 对话？”
- ACP 回答“acpx 应启动哪个外部 harness 进程？”
## 选择正确的模型前缀
OpenAI 系列路径按前缀区分。对于常见的订阅加原生 Codex 运行时设置，请使用 `openai/*` 并搭配 `agentRuntime.id: "codex"`。只有在你有意想要通过 Pi 使用 Codex OAuth 时，才使用 `openai-codex/*`：
OpenAI 系列路线按前缀区分。对于常见的订阅加原生 Codex 运行时设置，请使用 `openai/*` 搭配 `agentRuntime.id: "codex"`。只有在你有意通过 PI 使用 Codex OAuth 时，才使用 `openai-codex/*`：
| 模型 ref | 运行时路径 | 使用场景 |
| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| `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 应用服务器 harness | 你想用原生 Codex 执行使用 ChatGPT/Codex 订阅凭证。 |
| 模型引用 | 运行时路径 | 使用场景 |
| --------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
| `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 应用服务器 harness | 你想通过原生 Codex 执行使用 ChatGPT/Codex 订阅凭证。 |
当你的账号暴露这些能力时，GPT-5.5 可以同时出现在直接 OpenAI API key 路径和 Codex 订阅路径上。原生 Codex 运行时请使用 `openai/gpt-5.5` 搭配 Codex 应用服务器 harness；Pi OAuth 请使用 `openai-codex/gpt-5.5`；直接 API key 流量请使用不带 Codex 运行时覆盖的 `openai/gpt-5.5`。
当你的账号暴露这些路线时，GPT-5.5 可以同时出现在直接 OpenAI API key 和 Codex 订阅路线中。原生 Codex 运行时请使用 `openai/gpt-5.5` 搭配 Codex 应用服务器 harness，PI OAuth 请使用 `openai-codex/gpt-5.5`，直接 API key 流量请使用不带 Codex 运行时覆盖的 `openai/gpt-5.5`。
旧版 `codex/gpt-*` ref 仍作为兼容别名被接受。Doctor 兼容性迁移会把旧版主运行时 ref 重写为规范模型 ref，并单独记录运行时策略；而 fallback-only 旧版 ref 会保持不变，因为运行时是为整个智能体容器配置的。新的 Pi Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生应用服务器 harness 配置应使用 `openai/gpt-*` 加 `agentRuntime.id: "codex"`。
旧版 `codex/gpt-*` 引用仍作为兼容别名被接受。Doctor 兼容性迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略；而仅回退的旧版引用会保持不变，因为运行时是为整个智能体容器配置的。新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生应用服务器 harness 配置应使用 `openai/gpt-*` 加 `agentRuntime.id: "codex"`。
`agents.defaults.imageModel` 遵循同样的前缀区分。当图像理解应通过 OpenAI Codex OAuth 提供商路径运行时，请使用 `openai-codex/gpt-*`。当图像理解应通过有边界的 Codex 应用服务器轮次运行时，请使用 `codex/gpt-*`。Codex 应用服务器模型必须声明支持图像输入；纯文本 Codex 模型会在媒体轮次开始前失败。
`agents.defaults.imageModel` 遵循相同的前缀区分。当图像理解应通过 OpenAI Codex OAuth 提供商路径运行时，请使用 `openai-codex/gpt-*`。当图像理解应通过有界 Codex 应用服务器轮次运行时，请使用 `codex/gpt-*`。Codex 应用服务器模型必须声明支持图像输入；纯文本 Codex 模型会在媒体轮次开始前失败。
使用 `/status` 确认当前会话的有效 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含所选 harness id、选择原因、运行时/fallback 策略，以及在 `auto` 模式下每个插件候选项的支持结果。
使用 `/status` 确认当前会话的有效 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含选定的 harness id、选择原因、运行时/回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。
### Doctor 警告是什么意思
### Doctor 警告的含义
当以下条件全部为真时，`openclaw doctor` 会发出警告：
- 内置的 `codex` 插件已启用或被允许
- 内置的 `codex` 插件已启用或允许
- 某个智能体的主模型是 `openai-codex/*`
- 该智能体的有效运行时不是 `codex`
这个警告存在，是因为用户经常以为“已启用 Codex 插件”意味着“原生 Codex 应用服务器运行时”。OpenClaw 不会做这种推断。该警告表示：
该警告存在的原因是，用户常常期望“Codex 插件已启用”意味着“原生 Codex 应用服务器运行时”。OpenClaw 不会做出这种跳跃。该警告表示：
- 如果你本来就想通过 Pi 使用 ChatGPT/Codex OAuth，**无需更改**。
- 如果你想要原生应用服务器执行，请把模型改为 `openai/<model>`，并设置 `agentRuntime.id: "codex"`。
- 运行时变更后，现有会话仍然需要 `/new` 或 `/reset`，因为会话运行时 pin 是粘性的。
- 如果你本来就想通过 PI 使用 ChatGPT/Codex OAuth，**不需要任何更改**。
- 如果你想要原生应用服务器执行，请将模型改为 `openai/<model>` 并设置 `agentRuntime.id: "codex"`。
- 运行时更改后，现有会话仍然需要 `/new` 或 `/reset`，因为会话运行时固定是粘性的。
harness 选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会在该会话上记录所选 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来会话使用另一个 harness 时，请更改 `agentRuntime` 配置或 `OPENCLAW_AGENT_RUNTIME`；在 Pi 和 Codex 之间切换现有会话之前，请使用 `/new` 或 `/reset` 开始一个新会话。这可以避免把同一份 transcript 通过两个不兼容的原生会话系统重放。
harness 选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会在该会话上记录选定的 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来会话使用另一个 harness 时，请更改 `agentRuntime` 配置或 `OPENCLAW_AGENT_RUNTIME`；在现有对话中从 PI 切换到 Codex 之前，请使用 `/new` 或 `/reset` 启动新会话。这可以避免让同一份转录通过两个不兼容的原生会话系统重放。
在 harness pin 出现之前创建的旧版会话，一旦已有 transcript 历史，就会被视为 Pi-pinned。更改配置后，请使用 `/new` 或 `/reset` 将该会话选择加入 Codex。
在 harness 固定机制之前创建的旧版会话，一旦具有转录历史，就会被视为固定到 PI。更改配置后，请使用 `/new` 或 `/reset` 让该对话选择进入 Codex。
`/status` 会显示生效的模型运行时。默认的 PI harness 显示为
`Runtime: OpenClaw Pi Default`，Codex app-server harness 显示为
`/status` 会显示有效的模型运行时。默认 PI 运行框架显示为
`Runtime: OpenClaw Pi Default`，Codex app-server 运行框架显示为
`Runtime: OpenAI Codex`。
## 要求
- OpenClaw 中可用内置的 `codex` 插件。
- Codex app-server `0.125.0` 或更高版本。内置插件默认会管理兼容的
Codex app-server 二进制文件，因此 `PATH` 上的本地 `codex` 命令不会
影响正常的 harness 启动。
- app-server 进程或 OpenClaw 的 Codex 凭证桥接可用 Codex 凭证。
本地 app-server 启动会为每个智能体使用 OpenClaw 管理的 Codex home，
并使用隔离的子 `HOME`，因此默认不会读取你的个人
- OpenClaw，并且可用内置的 `codex` 插件。
- Codex app-server `0.125.0` 或更高版本。默认情况下，内置插件会管理兼容的
Codex app-server 二进制文件，因此 `PATH` 上的本地 `codex` 命令不会影响正常的运行框架启动。
- app-server 进程或 OpenClaw 的 Codex 凭证桥接可用的 Codex 凭证。本地 app-server 启动会为每个
智能体使用 OpenClaw 管理的 Codex home，并使用隔离的子进程 `HOME`，因此默认不会读取你的个人
`~/.codex` 账户、Skills、插件、配置、线程状态或原生
`$HOME/.agents/skills`。
插件会阻止较旧或无版本号的 app-server 握手。这样可以让 OpenClaw 保持在
已经测试过的协议表面上。
该插件会阻止旧版或无版本号的 app-server 握手。这样可以让 OpenClaw 保持在已经测试过的协议表面上。
对于实时和 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`。
## 工作区引导文件
Codex 通过原生项目文档发现自行处理 `AGENTS.md`。OpenClaw 不会写入合成的
Codex 项目文档文件，也不依赖 Codex 的备用 persona 文件名，因为 Codex 备用机制
只在缺少 `AGENTS.md` 时适用。
Codex 会通过原生项目文档发现自行处理 `AGENTS.md`。OpenClaw
不会写入合成的 Codex 项目文档文件，也不会依赖 Codex 的 persona 文件回退文件名，因为 Codex 回退只会在缺少
`AGENTS.md` 时应用。
为了保持 OpenClaw 工作区一致性，Codex harness 会解析其他引导文件
（存在时包括 `SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、
`HEARTBEAT.md`、`BOOTSTRAP.md` 和 `MEMORY.md`），并在 `thread/start`
和 `thread/resume` 上通过 Codex 配置指令转发它们。这样无需复制
`AGENTS.md`，也能让 `SOUL.md` 及相关工作区 persona/配置档上下文可见。
为了实现 OpenClaw 工作区一致性，Codex harness 会解析其他引导文件（存在时包括 `SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、
`BOOTSTRAP.md` 和 `MEMORY.md`），并通过 `thread/start` 和 `thread/resume` 上的 Codex
配置指令转发它们。这样可以让 `SOUL.md` 和相关的工作区 persona/配置文件上下文保持可见，而无需复制
`AGENTS.md`。
## 将 Codex 与其他模型一起添加
如果同一个智能体需要在 Codex 与非 Codex 提供商模型之间自由切换，不要全局设置
`agentRuntime.id: "codex"`。强制运行时会应用到该智能体或会话的每个嵌入式回合。
如果在强制该运行时时选择 Anthropic 模型，OpenClaw 仍会尝试 Codex harness，
并以失败关闭结束，而不是静默地将该回合路由到 PI。
如果同一个智能体需要在 Codex 和非 Codex 提供商模型之间自由切换，请不要全局设置 `agentRuntime.id: "codex"`。强制运行时会应用于该智能体或会话的每个嵌入式轮次。如果在强制使用该运行时时选择 Anthropic 模型，OpenClaw 仍会尝试 Codex 运行框架并失败关闭，而不是静默地通过 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
{
@ -234,7 +223,6 @@ Codex 项目文档文件，也不依赖 Codex 的备用 persona 文件名，因
defaults: {
agentRuntime: {
id: "auto",
fallback: "pi",
},
},
list: [
@ -256,37 +244,33 @@ Codex 项目文档文件，也不依赖 Codex 的备用 persona 文件名，因
}
```
使用这种形态时：
使用这种形式时：
- 默认的 `main` 智能体使用正常的提供商路径和 PI 兼容性回退。
- `codex` 智能体使用 Codex app-server harness。
- 如果 `codex` 智能体缺少 Codex 或不受支持，该回合会失败，
而不是静默使用 PI。
- 默认 `main` 智能体使用正常的提供商路径和 PI 兼容性回退。
- `codex` 智能体使用 Codex app-server 运行框架。
- 如果 `codex` 智能体缺少 Codex 或不受支持，该轮次会失败，而不是静默使用 PI。
## 智能体命令路由
智能体应按意图路由用户请求，而不是只看 “Codex” 这个词：
智能体应按意图路由用户请求，而不是仅凭 “Codex” 这个词：
| 用户要求... | 智能体应使用... |
| 用户请求... | 智能体应使用... |
| ------------------------------------------------------ | ------------------------------------------------ |
| “将此聊天绑定到 Codex” | `/codex bind` |
| “在这里恢复 Codex 线程 `<id>`” | `/codex resume <id>` |
| “显示 Codex 线程” | `/codex threads` |
| “为一次异常的 Codex 运行提交支持报告” | `/diagnostics [note]` |
| “只为这个附加线程发送 Codex 反馈” | `/codex diagnostics [note]` |
| “将我的 ChatGPT/Codex 订阅用于 Codex 运行时” | `openai/*` 加 `agentRuntime.id: "codex"` |
| “为失败的 Codex 运行提交支持报告” | `/diagnostics [note]` |
| “仅为这个附加线程发送 Codex 反馈” | `/codex diagnostics [note]` |
| “通过 Codex 运行时使用我的 ChatGPT/Codex 订阅” | `openai/*` 加 `agentRuntime.id: "codex"` |
| “通过 PI 使用我的 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 spawn 指引。如果 ACP 不可用，系统提示词和插件 Skills 不应教智能体 ACP 路由。
## 仅 Codex 部署
当你需要证明每个嵌入式智能体回合都使用 Codex 时，请强制使用 Codex harness。
显式插件运行时默认没有 PI 回退，因此 `fallback: "none"` 是可选的，
但通常很适合用作文档说明：
当你需要证明每个嵌入式智能体轮次都使用 Codex 时，请强制使用 Codex 运行框架。显式插件运行时会失败关闭，绝不会静默地通过 PI 重试：
```json5
{
@ -295,7 +279,6 @@ Codex 项目文档文件，也不依赖 Codex 的备用 persona 文件名，因
model: "openai/gpt-5.5",
agentRuntime: {
id: "codex",
fallback: "none",
},
},
},
@ -308,13 +291,11 @@ Codex 项目文档文件，也不依赖 Codex 的备用 persona 文件名，因
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
```
强制使用 Codex 时，如果 Codex 插件被禁用、app-server 过旧，或 app-server 无法启动，
OpenClaw 会提前失败。仅当你有意让 PI 处理缺失的 harness 选择时，才设置
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。
强制使用 Codex 时，如果 Codex 插件被禁用、app-server 版本过旧，或 app-server 无法启动，OpenClaw 会提前失败。
## 按智能体使用 Codex
你可以让一个智能体仅使用 Codex，同时让默认智能体保持正常自动选择：
你可以让一个智能体仅使用 Codex，同时让默认智能体保持正常的自动选择：
```json5
{
@ -322,7 +303,6 @@ OpenClaw 会提前失败。仅当你有意让 PI 处理缺失的 harness 选择
defaults: {
agentRuntime: {
id: "auto",
fallback: "pi",
},
},
list: [
@ -337,7 +317,6 @@ OpenClaw 会提前失败。仅当你有意让 PI 处理缺失的 harness 选择
model: "openai/gpt-5.5",
agentRuntime: {
id: "codex",
fallback: "none",
},
},
],
@ -345,20 +324,18 @@ OpenClaw 会提前失败。仅当你有意让 PI 处理缺失的 harness 选择
}
```
使用正常会话命令来切换智能体和模型。`/new` 会创建新的 OpenClaw 会话，
Codex harness 会按需创建或恢复它的 sidecar app-server 线程。`/reset` 会清除
该线程的 OpenClaw 会话绑定，并让下一个回合再次从当前配置解析 harness。
使用普通会话命令切换智能体和模型。`/new` 会创建一个新的
OpenClaw 会话，Codex 运行框架会按需创建或恢复其 sidecar app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一轮再次从当前配置解析运行框架。
## 模型发现
默认情况下，Codex 插件会向 app-server 请求可用模型。如果发现失败或超时，
它会使用以下内置回退目录：
默认情况下，Codex 插件会向 app-server 请求可用模型。如果发现失败或超时，它会使用以下模型的内置回退目录：
- GPT-5.5
- GPT-5.4 mini
- GPT-5.2
你可以在 `plugins.entries.codex.config.discovery` 下调整发现行为：
你可以在 `plugins.entries.codex.config.discovery` 下调整发现：
```json5
{
@ -378,7 +355,7 @@ Codex harness 会按需创建或恢复它的 sidecar app-server 线程。`/reset
}
```
如果你希望启动时避免探测 Codex，并坚持使用回退目录，请禁用发现：
当你希望启动时避免探测 Codex，并固定使用回退目录时，请禁用发现：
```json5
{
@ -405,16 +382,13 @@ Codex harness 会按需创建或恢复它的 sidecar app-server 线程。`/reset
codex app-server --listen stdio://
```
托管二进制文件随 `codex` 插件包一起提供。这会让 app-server 版本绑定到内置插件，
而不是绑定到本地刚好安装的某个独立 Codex CLI。仅当你有意运行不同的可执行文件时，
才设置 `appServer.command`。
托管二进制文件随 `codex` 插件包一起发布。这样会让 app-server 版本绑定到内置插件，而不是绑定到本地恰好安装的另一个 Codex CLI。只有在你有意运行不同可执行文件时，才设置 `appServer.command`。
默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话：
默认情况下，OpenClaw 以 YOLO 模式启动本地 Codex 运行框架会话：
`approvalPolicy: "never"`、`approvalsReviewer: "user"` 和
`sandbox: "danger-full-access"`。这是用于自主 Heartbeat 的可信本地操作员姿态：
Codex 可以使用 shell 和网络工具，而不会停在无人应答的原生审批提示上。
`sandbox: "danger-full-access"`。这是用于自主 Heartbeat 的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会停在无人响应的原生审批提示上。
要选择使用由 Codex guardian 审核的审批，请设置 `appServer.mode:
要选择使用 Codex guardian 审阅的审批，请设置 `appServer.mode:
"guardian"`：
```json5
@ -435,18 +409,14 @@ Codex 可以使用 shell 和网络工具，而不会停在无人应答的原生
}
```
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` 审核器值仍作为兼容性别名被接受，但新配置应使用
单个策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。较旧的 `guardian_subagent` 审阅者值仍可作为兼容性别名接受，但新配置应使用
`auto_review`。
对于已在运行的 app-server，请使用 WebSocket 传输协议：
对于已运行的 app-server，请使用 WebSocket 传输：
```json5
{
@ -468,41 +438,29 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
}
```
Stdio app-server 启动默认继承 OpenClaw 的进程环境，但 OpenClaw 拥有 Codex
app-server 账户桥接，并将 `CODEX_HOME` 和 `HOME` 都设置为该智能体 OpenClaw
状态下的按智能体目录。Codex 自身的 skill loader 会读取 `$CODEX_HOME/skills`
和 `$HOME/.agents/skills`，因此对于本地 app-server 启动，这两个值都是隔离的。
这样会把 Codex 原生 Skills、插件、配置、账户和线程状态限定在 OpenClaw 智能体范围内，
而不会从操作员的个人 Codex CLI home 泄漏进来。
默认情况下，Stdio app-server 启动会继承 OpenClaw 的进程环境，但 OpenClaw 拥有 Codex app-server 账户桥接，并将 `CODEX_HOME` 和 `HOME` 都设置为该智能体 OpenClaw 状态下的按智能体目录。Codex 自身的 Skills 加载器会读取 `$CODEX_HOME/skills` 和
`$HOME/.agents/skills`，因此这两个值在本地 app-server 启动中都是隔离的。这样可以将 Codex 原生 Skills、插件、配置、账户和线程状态限定到 OpenClaw 智能体，而不会从操作员个人 Codex CLI home 泄漏进来。
OpenClaw 插件和 OpenClaw Skill 快照仍会通过 OpenClaw 自己的插件注册表和 skill loader
流转。个人 Codex CLI 资产不会流转。如果你有有用的 Codex CLI Skills 或插件，
希望它们成为 OpenClaw 智能体的一部分，请显式盘点它们：
OpenClaw 插件和 OpenClaw Skills 快照仍会通过 OpenClaw 自身的插件注册表和 Skills 加载器流转。个人 Codex CLI 资产不会。如果你有应该成为 OpenClaw 智能体一部分的有用 Codex CLI Skills 或插件，请显式盘点它们：
```bash
openclaw migrate codex --dry-run
openclaw migrate apply codex --yes
```
Codex 迁移提供商会将 Skills 复制到当前 OpenClaw 智能体工作区。Codex 原生插件、
钩子和配置文件会被报告或归档以供人工审查，而不是自动激活，因为它们可能执行命令、
暴露 MCP 服务器或携带凭据。
Codex 迁移提供商会将 Skills 复制到当前 OpenClaw 智能体工作区。Codex 原生插件、钩子和配置文件会被报告或归档以供人工审阅，而不会自动激活，因为它们可以执行命令、暴露 MCP 服务器，或携带凭据。
凭证按以下顺序选择：
1. 该智能体的显式 OpenClaw Codex 凭证配置档。
1. 该智能体的显式 OpenClaw Codex 凭证配置。
2. 该智能体 Codex home 中 app-server 的现有账户。
3. 仅对于本地 stdio app-server 启动，当不存在 app-server 账户且仍需要 OpenAI
凭证时，先使用 `CODEX_API_KEY`，再使用 `OPENAI_API_KEY`。
3. 仅对于本地 stdio app-server 启动，当不存在 app-server 账户且仍需要 OpenAI 凭证时，依次使用 `CODEX_API_KEY`、`OPENAI_API_KEY`。
当 OpenClaw 发现 ChatGPT 订阅风格的 Codex 凭证配置档时，会从生成的 Codex 子进程中
移除 `CODEX_API_KEY` 和 `OPENAI_API_KEY`。这样可以让 Gateway 网关级 API key 继续用于
嵌入或直接 OpenAI 模型，而不会让原生 Codex app-server 回合意外通过 API 计费。
显式 Codex API-key 配置档和本地 stdio 环境变量 key 回退使用 app-server 登录，
而不是继承的子进程环境。WebSocket app-server 连接不会接收 Gateway 网关环境 API-key
回退；请使用显式凭证配置档或远程 app-server 自己的账户。
当 OpenClaw 看到 ChatGPT 订阅风格的 Codex 凭证配置时，它会从生成的 Codex 子进程中移除
`CODEX_API_KEY` 和 `OPENAI_API_KEY`。这样可以让 Gateway 网关级 API key 继续用于嵌入或直接 OpenAI 模型，同时避免原生 Codex app-server 轮次意外通过 API 计费。显式 Codex API key 配置和本地 stdio env-key 回退会使用 app-server 登录，而不是继承的子进程环境。WebSocket app-server 连接不会接收 Gateway 网关环境 API-key 回退；请使用显式凭证配置或远程 app-server 自身的账户。
如果部署需要额外的环境隔离，请将这些变量添加到 `appServer.clearEnv`：
如果部署需要额外的环境隔离，请将这些变量添加到
`appServer.clearEnv`：
```json5
{
@ -523,48 +481,36 @@ Codex 迁移提供商会将 Skills 复制到当前 OpenClaw 智能体工作区
`appServer.clearEnv` 只影响生成的 Codex app-server 子进程。
Codex 动态工具默认使用 `native-first` 配置。在该模式下，
OpenClaw 不会暴露与 Codex 原生工作区操作重复的动态工具：
`read`、`write`、`edit`、`apply_patch`、`exec`、`process` 和
`update_plan`。OpenClaw 集成工具，如消息、会话、媒体、cron、
浏览器、节点、Gateway 网关、`heartbeat_respond` 和 `web_search` 仍然
可用。
Codex 动态工具默认使用 `native-first` 配置。在该模式下，OpenClaw 不会暴露与 Codex 原生工作区操作重复的动态工具：`read`、`write`、`edit`、`apply_patch`、`exec`、`process` 和 `update_plan`。OpenClaw 集成工具，例如消息、会话、媒体、cron、浏览器、节点、Gateway 网关、`heartbeat_respond` 和 `web_search` 仍然可用。
支持的顶层 Codex 插件字段：
| 字段 | 默认值 | 含义 |
| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `codexDynamicToolsProfile` | `"native-first"` | 使用 `"openclaw-compat"` 向 Codex app-server 暴露完整的 OpenClaw 动态工具集。 |
| `codexDynamicToolsExclude` | `[]` | 要从 Codex app-server turn 中省略的其他 OpenClaw 动态工具名称。 |
| 字段 | 默认值 | 含义 |
| -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
| `codexDynamicToolsProfile` | `"native-first"` | 使用 `"openclaw-compat"` 向 Codex app-server 暴露完整的 OpenClaw 动态工具集。 |
| `codexDynamicToolsExclude` | `[]` | 要从 Codex app-server 回合中省略的其他 OpenClaw 动态工具名称。 |
支持的 `appServer` 字段：
| 字段 | 默认值 | 含义 |
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `transport` | `"stdio"` | `"stdio"` 会生成 Codex；`"websocket"` 会连接到 `url`。 |
| `command` | 托管的 Codex 二进制文件 | stdio 传输的可执行文件。保持未设置以使用托管二进制文件；只有在需要显式覆盖时才设置它。 |
| `args` | `["app-server", "--listen", "stdio://"]` | stdio 传输的参数。 |
| `url` | 未设置 | WebSocket app-server URL。 |
| `authToken` | 未设置 | WebSocket 传输的 Bearer token。 |
| `headers` | `{}` | 额外的 WebSocket 标头。 |
| `clearEnv` | `[]` | 在 OpenClaw 构建继承的环境之后，从生成的 stdio app-server 进程中移除的额外环境变量名称。`CODEX_HOME` 和 `HOME` 是为 OpenClaw 在本地启动时按智能体隔离 Codex 而保留的。 |
| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 |
| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 |
| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/turn 的原生 Codex 批准策略。 |
| `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 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 进程中移除的额外环境变量名称。`CODEX_HOME` 和 `HOME` 保留用于本地启动时 OpenClaw 的每智能体 Codex 隔离。 |
| `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 返回失败的动态工具响应，使该 turn 可以继续，而不是让会话停留在
`processing` 状态。
OpenClaw 拥有的动态工具调用与 `appServer.requestTimeoutMs` 分开独立限制：每个 Codex `item/tool/call` 请求都必须在 30 秒内收到 OpenClaw 响应。超时时，OpenClaw 会在支持的地方中止工具信号，并向 Codex 返回失败的动态工具响应，以便该回合可以继续，而不是让会话停留在 `processing`。
OpenClaw 响应 Codex 的 turn 作用域 app-server 请求后，harness
还期望 Codex 以 `turn/completed` 完成原生 turn。如果 app-server 在该响应后
静默 60 秒，OpenClaw 会尽力中断 Codex turn，记录诊断超时，并释放
OpenClaw 会话通道，这样后续聊天消息就不会排在陈旧的原生 turn 后面。
OpenClaw 响应 Codex 回合范围的 app-server 请求后，harness 还会期望 Codex 使用 `turn/completed` 完成原生回合。如果 app-server 在该响应后静默 60 秒，OpenClaw 会尽力中断 Codex 回合，记录诊断超时，并释放 OpenClaw 会话通道，以便后续聊天消息不会排在过时原生回合之后。
环境覆盖仍可用于本地测试：
@ -576,24 +522,16 @@ OpenClaw 会话通道，这样后续聊天消息就不会排在陈旧的原生 t
当 `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 Computer Use](/zh-CN/plugins/codex-computer-use)。
计算机使用在自己的设置指南中说明：
[Codex 计算机使用](/zh-CN/plugins/codex-computer-use)。
简而言之：OpenClaw 不会内置桌面控制应用，也不会自行执行
桌面操作。它会准备 Codex app-server，验证 `computer-use` MCP 服务器可用，
然后让 Codex 在 Codex 模式的 turn 中处理原生 MCP 工具调用。
简而言之：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 Computer Use](/zh-CN/plugins/codex-computer-use)，了解
Codex 拥有的 Computer Use 与直接 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 注册之间的区别。
最小配置：
@ -616,7 +554,6 @@ Codex 拥有的 Computer Use 与直接 MCP 注册之间的区别。
model: "openai/gpt-5.5",
agentRuntime: {
id: "codex",
fallback: "none",
},
},
},
@ -630,21 +567,13 @@ Codex 拥有的 Computer Use 与直接 MCP 注册之间的区别。
- `/codex computer-use install --source <marketplace-source>`
- `/codex computer-use install --marketplace-path <path>`
Computer Use 仅适用于 macOS，并且可能需要本地 OS 权限，之后
Codex MCP 服务器才能控制应用。如果 `computerUse.enabled` 为 true 且 MCP
服务器不可用，Codex 模式的 turn 会在线程启动前失败，而不是在没有原生 Computer Use 工具的情况下
静默运行。请参阅 [Codex Computer Use](/zh-CN/plugins/codex-computer-use)，了解 marketplace 选择、
远程目录限制、状态原因和故障排除。
计算机使用仅适用于 macOS，并且在 Codex MCP 服务器可以控制应用之前，可能需要本地 OS 权限。如果 `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。更改运行时或 Computer Use 配置后，请使用 `/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：
使用默认 stdio 传输协议的本地 Codex：
```json5
{
@ -658,7 +587,7 @@ Codex Desktop marketplace。更改运行时或 Computer Use 配置后，请使
}
```
仅 Codex 的 harness 验证：
仅 Codex harness 验证：
```json5
{
@ -680,7 +609,7 @@ Codex Desktop marketplace。更改运行时或 Computer Use 配置后，请使
}
```
由 guardian 审核的 Codex 批准：
guardian 审核的 Codex 审批：
```json5
{
@ -725,208 +654,144 @@ Codex Desktop marketplace。更改运行时或 Computer Use 配置后，请使
}
```
模型切换仍由 OpenClaw 控制。当 OpenClaw 会话附加到现有 Codex 线程时，
下一个 turn 会再次向 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` 显示实时应用服务器连接、模型、账号、速率限制、MCP 服务器和 Skills。
- `/codex models` 列出实时 Codex 应用服务器模型。
- `/codex status` 显示实时 app-server 连接、模型、账户、速率限制、MCP 服务器和 Skills。
- `/codex models` 列出实时 Codex app-server 模型。
- `/codex threads [filter]` 列出最近的 Codex 线程。
- `/codex resume <thread-id>` 将当前 OpenClaw 会话附加到现有 Codex 线程。
- `/codex compact` 请求 Codex 应用服务器压缩已附加的线程。
- `/codex compact` 要求 Codex app-server 压缩已附加的线程。
- `/codex review` 为已附加的线程启动 Codex 原生审查。
- `/codex diagnostics [note]` 在发送已附加线程的 Codex 诊断反馈之前先请求确认。
- `/codex computer-use status` 检查已配置的 Computer Use 插件和 MCP 服务器。
- `/codex computer-use install` 安装已配置的 Computer Use 插件并重新加载 MCP 服务器。
- `/codex account` 显示账号和速率限制状态。
- `/codex mcp` 列出 Codex 应用服务器 MCP 服务器状态。
- `/codex skills` 列出 Codex 应用服务器 Skills。
- `/codex diagnostics [note]` 在发送已附加线程的 Codex 诊断反馈前询问。
- `/codex computer-use status` 检查已配置的计算机使用插件和 MCP 服务器。
- `/codex computer-use install` 安装已配置的计算机使用插件并重新加载 MCP 服务器。
- `/codex account` 显示账户和速率限制 Status。
- `/codex mcp` 列出 Codex app-server MCP 服务器 Status。
- `/codex skills` 列出 Codex app-server Skills。
### 常见调试工作流
当由 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 <thread-id>`，并会打开
原生 Codex 线程，这样你可以检查对话、在本地继续对话，
或询问 Codex 为什么选择了某个特定工具或计划。
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 <thread-id>`，会打开原生 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 会发送一份可粘贴的报告，其中包含本地包路径和清单摘要。当当前 OpenClaw 会话正在使用 Codex harness 时，同一次批准也会授权将相关的 Codex 反馈包发送到 OpenAI 服务器。批准提示会说明将发送 Codex 反馈，但不会在批准前列出 Codex 会话或线程 ID。
如果 `/diagnostics` 由群聊中的所有者调用，OpenClaw 会保持
共享渠道整洁：群组只会收到一条简短通知，而
诊断说明、批准提示，以及 Codex 会话/线程 ID 会通过
私有批准路由发送给所有者。如果没有私有所有者路由，
OpenClaw 会拒绝群组请求，并要求所有者从私信中运行。
如果 owner 在群聊中调用 `/diagnostics`，OpenClaw 会保持共享渠道整洁：群里只会收到一条简短通知，而诊断前言、批准提示和 Codex 会话/线程 ID 会通过私有批准路由发送给 owner。如果没有私有 owner 路由，OpenClaw 会拒绝该群组请求，并要求 owner 从私信中运行它。
已批准的 Codex 上传会调用 Codex 应用服务器 `feedback/upload`，并请求
应用服务器在可用时为每个列出的线程和派生的 Codex 子线程
包含日志。上传会通过 Codex 的常规反馈路径进入 OpenAI
服务器；如果该应用服务器中禁用了 Codex 反馈，该命令会返回
应用服务器错误。完成后的诊断回复会列出已发送线程对应的渠道、
OpenClaw 会话 ID、Codex 线程 ID，以及本地 `codex resume <thread-id>`
命令。如果你拒绝或忽略批准，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 <thread-id>` 命令。如果你拒绝或忽略批准，OpenClaw 不会打印这些 Codex ID。此上传不会取代本地 Gateway 网关诊断导出。
`/codex resume` 会写入与 harness 用于正常轮次相同的旁路绑定文件。
在下一条消息中，OpenClaw 会恢复该 Codex 线程，将
当前选中的 OpenClaw 模型传入应用服务器，并保持扩展历史记录
启用。
`/codex resume` 会写入与 harness 在普通轮次中使用的同一个 sidecar 绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选中的 OpenClaw 模型传给 app-server，并保持扩展历史记录启用。
### 从 CLI 检查 Codex 线程
理解一次异常 Codex 运行的最快方式，通常是直接打开原生 Codex
线程：
理解一次异常 Codex 运行的最快方式，通常是直接打开原生 Codex 线程：
```sh
codex resume <thread-id>
```
当你注意到渠道对话中有 bug，并想检查有问题的
Codex 会话、在本地继续会话，或询问 Codex 为什么做出
某个特定工具或推理选择时，请使用此命令。最简单的路径通常是先运行
`/diagnostics [note]`：批准之后，完成后的报告会列出
每个 Codex 线程，并打印一个 `Inspect locally` 命令，例如
`codex resume <thread-id>`。你可以直接将该命令复制到终端中。
当你在渠道对话中发现 bug，并想检查有问题的 Codex 会话、在本地继续它，或询问 Codex 为什么做出某个特定工具或推理选择时，请使用此命令。最简单的路径通常是先运行 `/diagnostics [note]`：批准后，完成的报告会列出每个 Codex 线程，并打印一个 `Inspect locally` 命令，例如 `codex resume <thread-id>`。你可以直接将该命令复制到终端中。
你也可以通过当前聊天的 `/codex binding`，或通过
`/codex threads [filter]` 获取最近 Codex 应用服务器线程的线程 ID，然后在你的 shell 中运行相同的
`codex resume` 命令。
你也可以通过当前聊天的 `/codex binding`，或最近 Codex app-server 线程的 `/codex threads [filter]` 获取线程 ID，然后在 shell 中运行同一个 `codex resume` 命令。
该命令界面要求 Codex 应用服务器 `0.125.0` 或更高版本。如果未来版本或自定义应用服务器没有暴露相应的 JSON-RPC 方法，单个
控制方法会报告为 `unsupported by this Codex app-server`。
该命令界面要求 Codex app-server `0.125.0` 或更高版本。如果未来或自定义 app-server 未公开相应 JSON-RPC 方法，单个控制方法会报告为 `unsupported by this Codex app-server`。
## 钩子边界
Codex harness 有三个钩子层：
Codex harness 有三层钩子：
| 层级 | 所有者 | 用途 |
| 层级 | Owner | 用途 |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| OpenClaw 插件钩子 | OpenClaw | 跨 PI 和 Codex harness 的产品/插件兼容性。 |
| Codex 应用服务器扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的逐轮适配器行为。 |
| Codex 原生钩子 | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 |
| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的每轮适配器行为。 |
| Codex 原生钩子 | Codex | 来自 Codex 配置的低层 Codex 生命周期和原生工具策略。 |
OpenClaw 不使用项目或全局 Codex `hooks.json` 文件来路由
OpenClaw 插件行为。对于受支持的原生工具和权限桥接，
OpenClaw 会为 `PreToolUse`、`PostToolUse`、
`PermissionRequest` 和 `Stop` 注入逐线程 Codex 配置。其他 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 通过应用服务器或原生钩子
回调暴露该操作，否则它不能重写原生 Codex
线程。
对于 OpenClaw 动态工具，OpenClaw 会在 Codex 请求调用之后执行该工具，因此 OpenClaw 会在 harness 适配器中触发它所拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范工具记录。OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生钩子回调公开该操作，否则 OpenClaw 无法重写原生 Codex 线程。
压缩和 LLM 生命周期投影来自 Codex 应用服务器
通知和 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` 应用服务器通知会
投影为 `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 拥有更多原生模型 loop，而 OpenClaw 会围绕该边界适配它的插件和会话界面。
Codex 运行时 v1 中支持：
Codex 运行时 v1 支持：
| 界面 | 支持情况 | 原因 |
| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex 应用服务器拥有 OpenAI 轮次、原生线程恢复和原生工具延续。 |
| OpenClaw 渠道路由和投递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 和其他渠道保持在模型运行时之外。 |
| OpenClaw 动态工具 | 支持 | Codex 请求 OpenClaw 执行这些工具，因此 OpenClaw 保持在执行路径中。 |
| 提示词和上下文插件 | 支持 | OpenClaw 会构建提示词叠加层，并在启动或恢复线程之前将上下文投影到 Codex 轮次中。 |
| 上下文引擎生命周期 | 支持 | 组装、摄取或轮次后维护，以及上下文引擎压缩协调会为 Codex 轮次运行。 |
| 动态工具钩子 | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕 OpenClaw 拥有的动态工具运行。 |
| 通过 Codex 的 OpenAI 模型 loop | 支持 | 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 应用服务器 `0.125.0` 或更高版本上的 MCP 载荷。支持阻止；不支持参数重写。 |
| 原生权限策略 | 通过原生钩子中继支持 | 在运行时暴露该能力时，Codex `PermissionRequest` 可以通过 OpenClaw 策略路由。如果 OpenClaw 没有返回决策，Codex 会继续走其常规 guardian 或用户批准路径。 |
| 应用服务器轨迹捕获 | 支持 | OpenClaw 会记录它发送给应用服务器的请求以及收到的应用服务器通知。 |
| 最终答案修订门控 | 通过原生钩子中继支持 | Codex `Stop` 会中继到 `before_agent_finalize`；`revise` 会要求 Codex 在最终定稿前再进行一次模型处理。 |
| 原生 shell、patch 和 MCP 阻止或观察 | 通过原生钩子中继支持 | Codex `PreToolUse` 和 `PostToolUse` 会针对已承诺的原生工具界面中继，包括 Codex app-server `0.125.0` 或更高版本中的 MCP 载荷。支持阻止；不支持参数重写。 |
| 原生权限策略 | 通过原生钩子中继支持 | 当运行时公开 `PermissionRequest` 时，Codex `PermissionRequest` 可以通过 OpenClaw 策略路由。如果 OpenClaw 不返回决定，Codex 会继续走它的常规 guardian 或用户批准路径。 |
| App-server 轨迹捕获 | 支持 | OpenClaw 会记录它发送给 app-server 的请求，以及它收到的 app-server 通知。 |
Codex 运行时 v1 中不支持：
Codex 运行时 v1 不支持：
| 表面 | V1 边界 | 未来路径 |
| 表面 | V1 边界 | 未来路径 |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 原生工具参数变更 | Codex 原生工具前置钩子可以阻止，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子/架构支持替换工具输入。 |
| 可编辑的 Codex 原生转录历史 | Codex 拥有规范原生线程历史。OpenClaw 拥有镜像并可投射未来上下文，但不应更改不受支持的内部机制。 | 如果需要原生线程手术式修改，请添加显式的 Codex 应用服务器 API。 |
| Codex 原生工具记录的 `tool_result_persist` | 该钩子转换 OpenClaw 拥有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范重写需要 Codex 支持。 |
| 丰富的原生压缩元数据 | OpenClaw 会观察压缩开始和完成，但不会收到稳定的保留/丢弃列表、令牌差值或摘要载荷。 | 需要更丰富的 Codex 压缩事件。 |
| 压缩干预 | 当前 OpenClaw 压缩钩子在 Codex 模式下是通知级别的。 | 如果插件需要否决或重写原生压缩，请添加 Codex 压缩前/后钩子。 |
| 逐字节捕获模型 API 请求 | OpenClaw 可以捕获应用服务器请求和通知，但 Codex 核心会在内部构建最终的 OpenAI API 请求。 | 需要 Codex 模型请求跟踪事件或调试 API。 |
| 原生工具参数变更 | Codex 原生 pre-tool 钩子可以阻止，但 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 核心会在内部构建最终的 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 钩子事件都是 OpenClaw 插件表面。
原生钩子中继有意保持通用，但 v1 支持契约仅限于 OpenClaw 测试过的 Codex 原生工具和权限路径。在 Codex 运行时中，这包括 shell、patch 和 MCP `PreToolUse`、`PostToolUse` 以及 `PermissionRequest` 载荷。在运行时契约明确命名之前，不要假设每个未来的 Codex 钩子事件都是 OpenClaw 插件表面。
对于 `PermissionRequest`，OpenClaw 只会在策略作出决定时返回显式允许或拒绝决定。无决定结果不是允许。Codex 会将其视为没有钩子决定，并继续进入自己的守护器或用户批准路径。
对于 `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 应用服务器 `turn/steer`。使用默认 `messages.queue.mode: "steer"` 时，OpenClaw 会在配置的静默窗口内批量处理排队的聊天消息，并按到达顺序将它们作为一个 `turn/steer` 请求发送。旧版 `queue` 模式会发送单独的 `turn/steer` 请求。Codex review 和手动压缩轮次可能会拒绝同轮引导，在这种情况下，当所选模式允许回退时，OpenClaw 会使用后续队列。参见 [Steering queue](/zh-CN/concepts/queue-steering)。
活跃运行队列引导会映射到 Codex app-server `turn/steer`。使用默认的 `messages.queue.mode: "steer"` 时，OpenClaw 会在配置的安静窗口内批处理排队聊天消息，并按到达顺序作为一个 `turn/steer` 请求发送。旧版 `queue` 模式会发送单独的 `turn/steer` 请求。Codex review 和手动压缩轮次可能拒绝同轮引导，在这种情况下，当所选模式允许回退时，OpenClaw 会使用 followup 队列。请参阅 [Steering queue](/zh-CN/concepts/queue-steering)。
当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex 应用服务器。OpenClaw 会为渠道历史、搜索、`/new`、`/reset` 以及未来的模型或 harness 切换保留转录镜像。镜像包含用户提示、最终助手文本，以及应用服务器发出时的轻量级 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 应用服务器，它的失败会直接暴露，而不需要额外的回退配置。
**OpenClaw 使用 PI 而不是 Codex：**当没有 Codex harness 认领运行时，`agentRuntime.id: "auto"` 仍可能使用 PI 作为兼容性后端。测试时设置 `agentRuntime.id: "codex"` 以强制选择 Codex。强制 Codex 运行时会失败，而不是回退到 PI。一旦选择 Codex app-server，其失败会直接浮现。
**应用服务器被拒绝：** 升级 Codex，使应用服务器握手报告版本 `0.125.0` 或更高版本。相同版本的预发布版或带构建后缀的版本（例如 `0.125.0-alpha.2` 或 `0.125.0+custom`）会被拒绝，因为稳定版 `0.125.0` 协议下限才是 OpenClaw 测试的目标。
**app-server 被拒绝：**升级 Codex，使 app-server 握手报告版本 `0.125.0` 或更新版本。相同版本的预发布版本或带构建后缀的版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，会被拒绝，因为稳定版 `0.125.0` 协议下限才是 OpenClaw 测试的基线。
**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` 或禁用发现。
**模型发现很慢：**降低 `plugins.entries.codex.config.discovery.timeoutMs` 或禁用发现。
**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`，并确认远程应用服务器使用相同的 Codex 应用服务器协议版本。
**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 后重试。
## 相关

165
docs/zh-CN/plugins/sdk-agent-harness.md
View File

@ -1,62 +1,62 @@
---
read_when:
- 你正在更改嵌入式智能体运行时或 harness 注册表
- 你正在更改嵌入式智能体运行时或框架注册表
- 你正在从内置或受信任的插件注册智能体运行框架
- 你需要了解 Codex 插件与模型提供商之间的关系
sidebarTitle: Agent Harness
summary: 用于替换低层嵌入式智能体执行器的插件实验性 SDK 表面
summary: 用于替换底层嵌入式智能体执行器的实验性 SDK 接口
title: Agent harness plugins
x-i18n:
generated_at: "2026-05-02T02:37:19Z"
generated_at: "2026-05-03T04:51:00Z"
model: gpt-5.5
provider: openai
source_hash: b6e55d2df09c3965e1397be72f19dec2a6ed941ac8b7b01be8eee0f9713400dc
source_hash: ed416bbb433fc502c60fd8c24d20cd0f862d45472ff2eb0e2484b256b58f1b35
source_path: plugins/sdk-agent-harness.md
workflow: 16
---
**智能体执行器**是一次已准备好的 OpenClaw 智能体轮次的低级执行器。它不是模型提供商，不是渠道，也不是工具注册表。关于面向用户的心智模型，请参阅 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
**智能体执行框架** 是一次已准备好的 OpenClaw agent 回合的低层级执行器。它不是模型提供商，不是渠道，也不是工具注册表。关于面向用户的心智模型，请参阅 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
仅将此表面用于内置或可信的原生插件。该契约仍处于实验阶段，因为参数类型有意镜像当前嵌入式运行器。
仅将这个接口用于内置或可信的原生插件。该契约仍处于实验阶段，因为参数类型有意映射当前的嵌入式运行器。
## 何时使用执行器
## 何时使用执行框架
当某个模型系列拥有自己的原生会话运行时，并且常规 OpenClaw 提供商传输不是合适抽象时，注册智能体执行器。
当某个模型族有自己的原生会话运行时，并且常规 OpenClaw 提供商传输抽象不适合时，注册一个智能体执行框架。
示例：
- 拥有线程和压缩逻辑的原生编码智能体服务器
- 必须流式传输原生计划、推理、工具事件的本地 CLI 或守护进程
- 除 OpenClaw 会话转录之外，还需要自己的恢复 ID 的模型运行时
- 必须流式传输原生计划、推理和工具事件的本地 CLI 或守护进程
- 除 OpenClaw 会话转录记录之外还需要自己的恢复 ID 的模型运行时
不要仅为了添加新的 LLM API 而注册执行器。对于常规 HTTP 或 WebSocket 模型 API，请构建[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。
不要仅为了添加新的 LLM API 而注册执行框架。对于常规 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。
## 核心仍然负责什么
## core 仍然负责什么
在选择执行器之前，OpenClaw 已经解析了：
在选择执行框架之前，OpenClaw 已经解析了：
- 提供商和模型
- 运行时身份验证状态
- 思考级别和上下文预算
- OpenClaw 转录/会话文件
- OpenClaw 转录记录/会话文件
- 工作区、沙箱和工具策略
- 渠道回复回调和流式传输回调
- 渠道回复回调和流式回调
- 模型回退和实时模型切换策略
这种拆分是有意设计的。执行器运行一次已准备好的尝试；它不会选择提供商、替代渠道投递，也不会静默切换模型。
这种拆分是有意设计的。执行框架运行一次已准备好的尝试；它不会选择提供商、替换渠道投递，也不会静默切换模型。
已准备好的尝试还包含 `params.runtimePlan`，这是 OpenClaw 拥有的策略包，用于必须在 PI 和原生执行器之间保持共享的运行时决策：
已准备好的尝试还包含 `params.runtimePlan`，这是由 OpenClaw 拥有的运行时决策策略包，必须在 PI 和原生执行框架之间保持共享：
- `runtimePlan.tools.normalize(...)` 和
`runtimePlan.tools.logDiagnostics(...)`，用于感知提供商的工具 schema 策略
- `runtimePlan.transcript.resolvePolicy(...)`，用于转录清理和工具调用修复策略
`runtimePlan.tools.logDiagnostics(...)`，用于具备提供商感知能力的工具 schema 策略
- `runtimePlan.transcript.resolvePolicy(...)`，用于转录记录清理和工具调用修复策略
- `runtimePlan.delivery.isSilentPayload(...)`，用于共享的 `NO_REPLY` 和媒体投递抑制
- `runtimePlan.outcome.classifyRunResult(...)`，用于模型回退分类
- `runtimePlan.observability`，用于已解析的提供商/模型/执行器元数据
- `runtimePlan.observability`，用于已解析的提供商/模型/执行框架元数据
执行器可以将该计划用于需要匹配 PI 行为的决策，但仍应将其视为宿主拥有的尝试状态。不要修改它，也不要在一个轮次内用它切换提供商/模型。
执行框架可以使用该计划来做出需要匹配 PI 行为的决策，但仍应将它视为宿主拥有的尝试状态。不要修改它，也不要用它在一个回合内切换提供商/模型。
## 注册执行器
## 注册执行框架
**导入：** `openclaw/plugin-sdk/agent-harness`
@ -94,62 +94,60 @@ export default definePluginEntry({
## 选择策略
OpenClaw 在提供商/模型解析之后选择执行器：
OpenClaw 会在提供商/模型解析后选择执行框架：
1. 现有会话记录的执行器 ID 优先，因此配置/环境变量变更不会将该转录热切换到另一个运行时。
2. `OPENCLAW_AGENT_RUNTIME=<id>` 会为尚未固定的会话强制使用具有该 ID 的已注册执行器。
3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置 PI 执行器。
4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册执行器是否支持已解析的提供商/模型。
5. 如果没有已注册执行器匹配，除非禁用了 PI 回退，否则 OpenClaw 会使用 PI。
1. 现有会话记录的执行框架 ID 优先，因此配置/环境变量变更不会将该转录记录热切换到另一个运行时。
2. `OPENCLAW_AGENT_RUNTIME=<id>` 会为尚未固定的会话强制使用具有该 ID 的已注册执行框架。
3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置 PI 执行框架。
4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册的执行框架是否支持已解析的提供商/模型。
5. 如果没有匹配的已注册执行框架，除非禁用了 PI 回退，否则 OpenClaw 会使用 PI。
插件执行器失败会表现为运行失败。在 `auto` 模式下，只有在没有已注册插件执行器支持已解析的提供商/模型时，才会使用 PI 回退。一旦某个插件执行器声明了一次运行，OpenClaw 就不会通过 PI 重放同一轮次，因为那可能改变身份验证/运行时语义，或造成副作用重复。
插件执行框架失败会表现为运行失败。在 `auto` 模式下，只有当没有已注册插件执行框架支持已解析的提供商/模型时，才会使用 PI 回退。一旦某个插件执行框架声明接管一次运行，OpenClaw 就不会通过 PI 重放同一个回合，因为这可能改变身份验证/运行时语义，或重复产生副作用。
选定的执行器 ID 会在嵌入式运行后随会话 ID 一起持久化。在执行器固定机制之前创建的旧会话，一旦有转录历史，就会被视为已固定到 PI。在 PI 与原生插件执行器之间切换时，请使用新的/重置后的会话。`/status` 会在 `Fast` 旁边显示非默认执行器 ID，例如 `codex`；PI 会保持隐藏，因为它是默认兼容路径。如果选中的执行器出乎意料，请启用 `agents/harness` 调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含选定的执行器 ID、选择原因、运行时/回退策略，并且在 `auto` 模式下还包含每个插件候选的支持结果。
在嵌入式运行后，所选执行框架 ID 会随会话 ID 一起持久化。执行框架固定机制出现之前创建的旧版会话，一旦已有转录记录历史，就会被视为已固定到 PI。在 PI 和原生插件执行框架之间切换时，请使用新的/重置后的会话。`/status` 会在 `Fast` 旁显示非默认执行框架 ID，例如 `codex`；PI 会保持隐藏，因为它是默认兼容路径。如果所选执行框架出乎意料，请启用 `agents/harness` 调试日志，并检查 gateway 的结构化 `agent harness selected` 记录。它包含所选执行框架 ID、选择原因、运行时/回退策略，并且在 `auto` 模式下还包含每个插件候选项的支持结果。
内置 Codex 插件将 `codex` 注册为其执行器 ID。核心将其视为普通插件执行器 ID；Codex 专用别名属于插件或操作员配置，而不属于共享运行时选择器。
内置 Codex 插件会将 `codex` 注册为其执行框架 ID。core 会把它视为普通插件执行框架 ID；Codex 专用别名应属于插件或操作员配置，而不是共享运行时选择器。
## 提供商加执行器配对
## 提供商与执行框架配对
大多数执行器也应该注册一个提供商。提供商会让模型引用、身份验证状态、模型元数据和 `/model` 选择对 OpenClaw 的其余部分可见。然后，执行器在 `supports(...)` 中声明该提供商。
大多数执行框架也应该注册一个提供商。提供商会让模型引用、身份验证状态、模型元数据和 `/model` 选择对 OpenClaw 的其他部分可见。然后执行框架在 `supports(...)` 中声明接管该提供商。
内置 Codex 插件遵循此模式：
- 首选用户模型引用：`openai/gpt-5.5` 加上
- 首选用户模型引用：`openai/gpt-5.5` 加
`agentRuntime.id: "codex"`
- 兼容性引用：旧版 `codex/gpt-*` 引用仍会被接受，但新配置不应将它们用作常规提供商/模型引用
- 执行器 ID：`codex`
- 身份验证：合成的提供商可用性，因为 Codex 执行器拥有原生 Codex 登录/会话
- 应用服务器请求：OpenClaw 将裸模型 ID 发送给 Codex，并让执行器与原生应用服务器协议通信
- 兼容性引用：旧版 `codex/gpt-*` 引用仍然被接受，但新配置不应将它们用作常规提供商/模型引用
- 执行框架 ID：`codex`
- 身份验证：合成的提供商可用性，因为 Codex 执行框架拥有原生 Codex 登录/会话
- app-server 请求：OpenClaw 会把裸模型 ID 发送给 Codex，并让执行框架与原生 app-server 协议通信
Codex 插件是增量式的。普通 `openai/gpt-*` 引用会继续使用常规 OpenClaw 提供商路径，除非你用 `agentRuntime.id: "codex"` 强制使用 Codex 执行器。较旧的 `codex/gpt-*` 引用仍会选择 Codex 提供商和执行器以保持兼容。
Codex 插件是增量式的。普通 `openai/gpt-*` 引用会继续使用常规 OpenClaw 提供商路径，除非你通过 `agentRuntime.id: "codex"` 强制使用 Codex 执行框架。较旧的 `codex/gpt-*` 引用仍会选择 Codex 提供商和执行框架以保持兼容。
关于操作员设置、模型前缀示例和仅 Codex 配置，请参阅 [Codex Harness](/zh-CN/plugins/codex-harness)。
关于操作员设置、模型前缀示例和 Codex 专用配置，请参阅 [Codex Harness](/zh-CN/plugins/codex-harness)。
OpenClaw 要求 Codex 应用服务器版本为 `0.125.0` 或更高。Codex 插件会检查应用服务器初始化握手，并阻止更旧或未标版本的服务器，从而确保 OpenClaw 只在已经过测试的协议表面上运行。`0.125.0` 下限包含在 Codex `0.124.0` 中落地的原生 MCP 钩子载荷支持，同时将 OpenClaw 固定到更新且已测试的稳定线。
OpenClaw 要求 Codex app-server 为 `0.125.0` 或更新版本。Codex 插件会检查 app-server 初始化握手，并阻止较旧或未带版本的服务器，因此 OpenClaw 只会针对它已经测试过的协议接口运行。`0.125.0` 下限包含 Codex `0.124.0` 中落地的原生 MCP 钩子载荷支持，同时将 OpenClaw 固定到更新的、已测试的稳定线。
### 工具结果中间件
当内置插件的清单在 `contracts.agentToolResultMiddleware` 中声明了目标运行时 ID 时，它们可以通过 `api.registerAgentToolResultMiddleware(...)` 附加运行时中立的工具结果中间件。这个可信接口用于异步工具结果转换，这些转换必须在 PI 或 Codex 将工具输出送回模型之前运行。
内置插件可以在其清单的 `contracts.agentToolResultMiddleware` 中声明目标运行时 ID 后，通过 `api.registerAgentToolResultMiddleware(...)` 挂接运行时中立的工具结果中间件。这个可信接口用于在 PI 或 Codex 将工具输出反馈给模型之前必须运行的异步工具结果转换。
旧版内置插件仍可使用 `api.registerCodexAppServerExtensionFactory(...)` 来实现仅 Codex 应用服务器的中间件，但新的结果转换应使用运行时中立 API。仅 Pi 的 `api.registerEmbeddedExtensionFactory(...)` 钩子已被移除；Pi 工具结果转换必须使用运行时中立中间件。
旧版内置插件仍可使用 `api.registerCodexAppServerExtensionFactory(...)` 处理仅限 Codex app-server 的中间件，但新的结果转换应使用运行时中立 API。仅限 Pi 的 `api.registerEmbeddedExtensionFactory(...)` 钩子已被移除；Pi 工具结果转换必须使用运行时中立中间件。
### 终端结果分类
拥有自身协议投影的原生执行器，可以在已完成轮次没有产生可见助手文本时，使用 `openclaw/plugin-sdk/agent-harness-runtime` 中的 `classifyAgentHarnessTerminalOutcome(...)`。该辅助函数会返回 `empty`、`reasoning-only` 或 `planning-only`，以便 OpenClaw 的回退策略决定是否在不同模型上重试。它有意不对提示错误、正在进行的轮次，以及诸如 `NO_REPLY` 之类的有意静默回复进行分类。
拥有自己协议投影的原生执行框架，在已完成回合未产生可见 assistant 文本时，可以使用来自 `openclaw/plugin-sdk/agent-harness-runtime` 的 `classifyAgentHarnessTerminalOutcome(...)`。该辅助函数会返回 `empty`、`reasoning-only` 或 `planning-only`，让 OpenClaw 的回退策略决定是否在不同模型上重试。它有意不对提示错误、进行中的回合以及 `NO_REPLY` 等有意的静默回复进行分类。
### 原生 Codex 执行器模式
### 原生 Codex 执行框架模式
内置 `codex` 执行器是嵌入式 OpenClaw 智能体轮次的原生 Codex 模式。先启用内置 `codex` 插件；如果你的配置使用限制性允许列表，请在 `plugins.allow` 中包含 `codex`。原生应用服务器配置应使用带有 `agentRuntime.id: "codex"` 的 `openai/gpt-*`。请使用 `openai-codex/*` 通过 PI 进行 Codex OAuth。旧版 `codex/*` 模型引用仍是原生执行器的兼容性别名。
内置 `codex` 执行框架是嵌入式 OpenClaw agent 回合的原生 Codex 模式。先启用内置 `codex` 插件；如果你的配置使用限制性允许列表，请在 `plugins.allow` 中包含 `codex`。原生 app-server 配置应使用带有 `agentRuntime.id: "codex"` 的 `openai/gpt-*`。请使用 `openai-codex/*` 通过 PI 使用 Codex OAuth。旧版 `codex/*` 模型引用仍然是原生执行框架的兼容性别名。
当此模式运行时，Codex 拥有原生线程 ID、恢复行为、压缩和应用服务器执行。OpenClaw 仍负责聊天渠道、可见转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex 应用服务器路径可以声明该运行时，请使用不带 `fallback` 覆盖的 `agentRuntime.id: "codex"`。显式插件运行时默认已经是封闭失败。仅当你有意希望 PI 处理缺失的执行器选择时，才设置 `fallback: "pi"`。Codex 应用服务器失败已经会直接失败，而不会通过 PI 重试。
当此模式运行时，Codex 拥有原生线程 ID、恢复行为、压缩和 app-server 执行。OpenClaw 仍然拥有聊天渠道、可见转录记录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径可以声明接管运行时，请使用 `agentRuntime.id: "codex"`。显式插件运行时会失败关闭；Codex app-server 选择失败和运行时失败不会通过 PI 重试。
## 禁用 PI 回退
## 运行时严格性
默认情况下，OpenClaw 以 `agents.defaults.agentRuntime` 设置为 `{ id: "auto", fallback: "pi" }` 的方式运行嵌入式智能体。在 `auto` 模式下，已注册插件执行器可以声明提供商/模型对。如果没有匹配项，OpenClaw 会回退到 PI。
默认情况下，OpenClaw 使用 OpenClaw Pi 运行嵌入式智能体。在 `auto` 模式下，已注册插件执行框架可以声明接管某个提供商/模型组合；如果没有匹配项，则由 PI 处理该回合。当缺失执行框架选择应失败而不是路由到 PI 时，请使用显式插件运行时，例如 `agentRuntime.id: "codex"`。所选插件执行框架失败始终会硬失败。这不会阻止显式的 `agentRuntime.id: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。
在 `auto` 模式下，当你需要缺失的插件执行器选择失败而不是使用 PI 时，请设置 `fallback: "none"`。显式插件运行时（例如 `agentRuntime.id: "codex"`）默认已经是封闭失败，除非在相同配置或环境覆盖范围中设置了 `fallback: "pi"`。选定插件执行器的失败始终会硬失败。这不会阻止显式的 `agentRuntime.id: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。
对于仅 Codex 的嵌入式运行：
对于仅限 Codex 的嵌入式运行：
```json
{
@ -164,15 +162,14 @@ OpenClaw 要求 Codex 应用服务器版本为 `0.125.0` 或更高。Codex 插
}
```
如果你希望任何已注册插件执行器都能声明匹配模型，但绝不希望 OpenClaw 静默回退到 PI，请保留 `runtime: "auto"` 并禁用回退：
如果你希望任何已注册插件执行框架声明接管匹配模型，并在其他情况下使用 PI，请设置 `id: "auto"`：
```json
{
"agents": {
"defaults": {
"agentRuntime": {
"id": "auto",
"fallback": "none"
"id": "auto"
}
}
}
@ -185,72 +182,58 @@ OpenClaw 要求 Codex 应用服务器版本为 `0.125.0` 或更高。Codex 插
{
"agents": {
"defaults": {
"agentRuntime": {
"id": "auto",
"fallback": "pi"
}
"agentRuntime": { "id": "auto" }
},
"list": [
{
"id": "codex-only",
"model": "openai/gpt-5.5",
"agentRuntime": {
"id": "codex",
"fallback": "none"
}
"agentRuntime": { "id": "codex" }
}
]
}
}
```
`OPENCLAW_AGENT_RUNTIME` 仍会覆盖已配置的运行时。使用 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 从环境中禁用 PI 回退。
`OPENCLAW_AGENT_RUNTIME` 仍会覆盖已配置的运行时。
```bash
OPENCLAW_AGENT_RUNTIME=codex \
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
```
禁用回退后，当请求的执行器未注册、不支持已解析的提供商/模型，或在产生轮次副作用之前失败时，会话会提前失败。这对于仅 Codex 部署以及必须证明 Codex 应用服务器路径确实正在使用的实时测试来说是有意设计的。
使用显式插件运行时时，如果请求的执行框架未注册、不支持已解析的提供商/模型，或在产生回合副作用之前失败，会话会提前失败。这对仅限 Codex 的部署以及必须证明 Codex app-server 路径确实正在使用的实时测试是有意设计的。
此设置只控制嵌入式智能体执行器。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商专用模型路由。
此设置只控制嵌入式智能体执行框架。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商专用模型路由。
## 原生会话和转录镜像
## 原生会话和转录记录镜像
执行器可以保留原生会话 ID、线程 ID 或守护进程侧恢复令牌。请将该绑定明确关联到 OpenClaw 会话，并持续将用户可见的助手/工具输出镜像到 OpenClaw 转录中。
执行框架可以保留原生会话 ID、线程 ID 或守护进程端恢复 token。请将该绑定明确关联到 OpenClaw 会话，并持续将用户可见的 assistant/工具输出镜像到 OpenClaw 转录记录中。
OpenClaw 转录仍是以下内容的兼容层：
OpenClaw 转录记录仍是以下内容的兼容层：
- 渠道可见会话历史
- 转录搜索和索引
- 在之后的轮次切换回内置 PI 执行器
- 渠道可见的会话历史
- 转录记录搜索和索引
- 在后续回合切换回内置 PI 执行框架
- 通用 `/new`、`/reset` 和会话删除行为
如果你的执行器存储边车绑定，请实现 `reset(...)`，以便在所属 OpenClaw 会话重置时，OpenClaw 可以清除它。
如果你的执行框架存储旁路绑定，请实现 `reset(...)`，这样 OpenClaw 就可以在所属 OpenClaw 会话被重置时清除它。
## 工具和媒体结果
核心会构建 OpenClaw 工具列表，并将其传入准备好的尝试。
当运行框架执行动态工具调用时，请通过运行框架的结果形状返回工具结果，
而不是自行发送渠道媒体。
core 会构造 OpenClaw 工具列表，并将其传入已准备好的尝试。当执行框架执行动态工具调用时，请通过执行框架结果形状返回工具结果，而不是自行发送渠道媒体。
这会让文本、图片、视频、音乐、TTS、审批和消息工具输出
与 PI 支持的运行使用相同的交付路径。
这会让文本、图像、视频、音乐、TTS、审批和消息工具输出与 PI 支持的运行保持在同一条投递路径上。
## 当前限制
- 公共导入路径是通用的，但某些尝试/结果类型别名为了兼容性仍然
带有 `Pi` 名称。
- 第三方运行框架安装仍处于实验阶段。优先使用提供商插件，
直到你需要原生会话运行时。
- 支持跨轮次切换运行框架。不要在原生工具、审批、助手文本或消息
发送已经开始后，在同一轮中途切换运行框架。
- 公共导入路径是通用的，但一些 attempt/result 类型别名仍然保留 `Pi` 名称以保持兼容。
- 第三方 harness 安装仍处于实验阶段。优先使用提供商插件，直到你需要原生会话运行时。
- 支持跨轮次切换 harness。不要在原生工具、审批、智能体文本或消息发送开始之后，在同一轮中途切换 harness。
## 相关内容
## 相关
- [插件 SDK 概览](/zh-CN/plugins/sdk-overview)
- [运行时助手](/zh-CN/plugins/sdk-runtime)
- [SDK 概览](/zh-CN/plugins/sdk-overview)
- [运行时辅助工具](/zh-CN/plugins/sdk-runtime)
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins)
- [Codex Harness](/zh-CN/plugins/codex-harness)
- [Codex harness](/zh-CN/plugins/codex-harness)
- [模型提供商](/zh-CN/concepts/model-providers)

384
docs/zh-CN/providers/openai.md
View File

@ -1,84 +1,84 @@
---
read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 订阅凭证而不是 API 密钥
- 你想使用 Codex 订阅身份验证，而不是 API 密钥
- 你需要更严格的 GPT-5 智能体执行行为
summary: 通过 API 密钥或 Codex 订阅在 OpenClaw 中使用 OpenAI
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
title: OpenAI
x-i18n:
generated_at: "2026-05-02T06:35:45Z"
generated_at: "2026-05-03T04:52:01Z"
model: gpt-5.5
provider: openai
source_hash: 0caf43895c1bc8494b1a0d4aeef98e575bb31aca047430a63156875bed3bb112
source_hash: cdffcdf53d9b17a19450c2ce47103db116e54a71a8dd432d981f5ece81cc38b3
source_path: providers/openai.md
workflow: 16
---
OpenAI 为 GPT 模型提供开发者 API，Codex 也可作为通过 OpenAI 的 Codex 客户端使用的 ChatGPT 方案编码智能体。OpenClaw 将这些表面分开，以保持配置可预测。
OpenAI 提供面向 GPT 模型的开发者 API，Codex 也可通过 OpenAI 的 Codex 客户端作为 ChatGPT 方案中的编码智能体使用。OpenClaw 将这些使用面保持分离，确保配置保持可预测。
OpenClaw 支持三种 OpenAI 系列路线。大多数想要 Codex 行为的 ChatGPT/Codex 订阅用户应使用原生 Codex app-server 运行时。模型前缀选择提供商/模型名称；单独的运行时设置选择谁来执行嵌入式 Agent loop：
OpenClaw 支持三种 OpenAI 系列路由。大多数想要 Codex 行为的 ChatGPT/Codex 订阅用户应使用原生 Codex 应用服务器运行时。模型前缀选择提供商/模型名称；单独的运行时设置选择由谁执行嵌入式 Agent loop：
- **API key** - 使用按量计费的直接 OpenAI Platform 访问（`openai/*` 模型）
- **使用原生 Codex 运行时的 Codex 订阅** - ChatGPT/Codex 登录加 Codex app-server 执行（`openai/*` 模型加 `agents.defaults.agentRuntime.id: "codex"`）
- **通过 PI 使用 Codex 订阅** - ChatGPT/Codex 登录，使用正常的 OpenClaw PI runner（`openai-codex/*` 模型）
- **API key** - 使用按量计费的 OpenAI Platform 直接访问（`openai/*` 模型）
- **带原生 Codex 运行时的 Codex 订阅** - ChatGPT/Codex 登录加 Codex 应用服务器执行（`openai/*` 模型加 `agents.defaults.agentRuntime.id: "codex"`）
- **通过 PI 的 Codex 订阅** - 使用普通 OpenClaw PI 运行器的 ChatGPT/Codex 登录（`openai-codex/*` 模型）
OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。
OpenAI 明确支持在外部工具和 OpenClaw 这类工作流中使用订阅 OAuth。
提供商、模型、运行时和渠道是分开的层。如果这些标签混在一起，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再更改配置。
提供商、模型、运行时和渠道是彼此独立的层。如果这些标签混在一起，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再更改配置。
## 快速选择
| 目标 | 使用方式 | 备注 |
| 目标 | 使用 | 说明 |
| ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- |
| 使用原生 Codex 运行时的 ChatGPT/Codex 订阅 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 推荐给大多数用户的 Codex 设置。使用 `openai-codex` 凭证登录。 |
| 带原生 Codex 运行时的 ChatGPT/Codex 订阅 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 推荐给大多数用户的 Codex 设置。使用 `openai-codex` 凭证登录。 |
| 直接 API key 计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API key 新手引导。 |
| 通过 PI 使用 ChatGPT/Codex 订阅凭证 | `openai-codex/gpt-5.5` | 仅在你明确想使用正常 PI runner 时使用。 |
| 图片生成或编辑 | `openai/gpt-image-2` | 可配合 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 使用。 |
| 透明背景图片 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 |
| 通过 PI 使用 ChatGPT/Codex 订阅凭证 | `openai-codex/gpt-5.5` | 仅在你有意使用普通 PI 运行器时使用。 |
| 图像生成或编辑 | `openai/gpt-image-2` | 可与 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 配合使用。 |
| 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 |
## 命名映射
这些名称相似，但不可互换：
| 你看到的名称 | 层级 | 含义 |
| 你看到的名称 | 层 | 含义 |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `openai` | 提供商前缀 | 直接 OpenAI Platform API 路线。 |
| `openai-codex` | 提供商前缀 | 通过正常 OpenClaw PI runner 使用的 OpenAI Codex OAuth/订阅路线。 |
| `codex` 插件 | 插件 | 内置 OpenClaw 插件，提供原生 Codex app-server 运行时和 `/codex` 聊天控制。 |
| `agentRuntime.id: codex` | Agent 运行时 | 强制嵌入式轮次使用原生 Codex app-server harness。 |
| `/codex ...` | 聊天命令集 | 在会话中绑定/控制 Codex app-server 线程。 |
| `runtime: "acp", agentId: "codex"` | ACP 会话路线 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 |
| `openai` | 提供商前缀 | 直接 OpenAI Platform API 路由。 |
| `openai-codex` | 提供商前缀 | 通过普通 OpenClaw PI 运行器使用的 OpenAI Codex OAuth/订阅路由。 |
| `codex` 插件 | 插件 | 内置 OpenClaw 插件，提供原生 Codex 应用服务器运行时和 `/codex` 聊天控制。 |
| `agentRuntime.id: codex` | Agent runtime | 强制嵌入式轮次使用原生 Codex 应用服务器 harness。 |
| `/codex ...` | 聊天命令集 | 从会话中绑定/控制 Codex 应用服务器线程。 |
| `runtime: "acp", agentId: "codex"` | ACP 会话路由 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 |
这意味着配置可以有意同时包含 `openai-codex/*` 和 `codex` 插件。当你想通过 PI 使用 Codex OAuth，并且还想提供原生 `/codex` 聊天控制时，这是有效的。`openclaw doctor` 会对该组合发出警告，以便你确认这是有意为之；它不会重写该配置。
这意味着配置可以有意同时包含 `openai-codex/*` 和 `codex` 插件。当你既想通过 PI 使用 Codex OAuth，又想让原生 `/codex` 聊天控制可用时，这是有效的。`openclaw doctor` 会针对这种组合发出警告，以便你确认这是有意设置；它不会重写该配置。
<Note>
GPT-5.5 可通过直接 OpenAI Platform API key 访问以及订阅/OAuth 路线使用。对于 ChatGPT/Codex 订阅加原生 Codex 执行，请使用带有 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。仅在通过 PI 使用 Codex OAuth 时使用 `openai-codex/gpt-5.5`，或者在没有 Codex 运行时覆盖的直接 `OPENAI_API_KEY` 流量中使用 `openai/gpt-5.5`。
GPT-5.5 可通过直接 OpenAI Platform API key 访问和订阅/OAuth 路由使用。对于 ChatGPT/Codex 订阅加原生 Codex 执行，请使用带 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。仅在通过 PI 使用 Codex OAuth 时使用 `openai-codex/gpt-5.5`；或者在不覆盖 Codex 运行时的情况下使用 `openai/gpt-5.5` 处理直接 `OPENAI_API_KEY` 流量。
</Note>
<Note>
启用 OpenAI 插件或选择 `openai-codex/*` 模型，并不会启用内置 Codex app-server 插件。OpenClaw 只会在你使用 `agentRuntime.id: "codex"` 明确选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时启用该插件。
如果内置 `codex` 插件已启用，但 `openai-codex/*` 仍通过 PI 解析，`openclaw doctor` 会发出警告并保持该路线不变。
启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会启用内置 Codex 应用服务器插件。OpenClaw 只会在你通过 `agentRuntime.id: "codex"` 显式选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时启用该插件。
如果内置 `codex` 插件已启用，但 `openai-codex/*` 仍通过 PI 解析，`openclaw doctor` 会发出警告并保持路由不变。
</Note>
## OpenClaw 功能覆盖
| OpenAI 能力 | OpenClaw 表面 | Status |
| OpenAI 能力 | OpenClaw 使用面 | Status |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
| Codex app-server harness | 使用 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，启用 Web 搜索且未固定提供商时 |
| 图片 | `image_generate` | 是 |
| Codex 应用服务器 harness | 带 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | 语音通话 `streaming.provider: "openai"` | 是 |
| 实时语音 | 语音通话 `realtime.provider: "openai"` / Control UI Talk | 是 |
| Embeddings | 记忆嵌入提供商 | 是 |
| 嵌入 | 记忆嵌入提供商 | 是 |
## 记忆嵌入
OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_search` 建立索引和生成查询嵌入：
OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_search` 索引和查询嵌入提供支持：
```json5
{
@ -93,11 +93,11 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
}
```
对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 `memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将它们作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用 `queryInputType`；已索引的记忆片段和批量索引使用 `documentInputType`。完整示例见 [记忆配置参考](/zh-CN/reference/memory-config#provider-specific-config)。
对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 `memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将它们作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用 `queryInputType`；已索引的记忆片段和批量索引使用 `documentInputType`。完整示例见[记忆配置参考](/zh-CN/reference/memory-config#provider-specific-config)。
## 入门指南
选择你偏好的凭证方法并按设置步骤操作。
选择你偏好的凭证方法并按照设置步骤操作。
<Tabs>
<Tab title="API key（OpenAI Platform）">
@ -105,14 +105,14 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
<Steps>
<Step title="获取你的 API key">
从 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 创建或复制 API key。
从 [OpenAI Platform 控制台](https://platform.openai.com/api-keys)创建或复制 API key。
</Step>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice openai-api-key
```
或直接传入密钥：
或直接传入 key：
```bash
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
@ -125,16 +125,16 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
</Step>
</Steps>
### 路线摘要
### 路由摘要
| 模型引用 | 运行时配置 | 路线 | 凭证 |
| 模型引用 | 运行时配置 | 路由 | 凭证 |
| ---------------------- | -------------------------- | --------------------------- | ---------------- |
| `openai/gpt-5.5` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex 应用服务器 harness | Codex 应用服务器 |
<Note>
`openai/*` 是直接 OpenAI API key 路线，除非你明确强制使用 Codex app-server harness。使用 `openai-codex/*` 可通过默认 PI runner 使用 Codex OAuth，或使用带有 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5` 进行原生 Codex app-server 执行。
`openai/*` 是直接 OpenAI API key 路由，除非你显式强制使用 Codex 应用服务器 harness。通过默认 PI 运行器使用 Codex OAuth 时使用 `openai-codex/*`；使用原生 Codex 应用服务器执行时，使用带 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。
</Note>
### 配置示例
@ -147,13 +147,13 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
```
<Warning>
OpenClaw **不**公开 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也没有公开它。
OpenClaw **不会**暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也不会暴露它。
</Warning>
</Tab>
<Tab title="Codex 订阅">
**最适合：** 使用你的 ChatGPT/Codex 订阅和原生 Codex app-server 执行，而不是单独的 API key。Codex cloud 需要 ChatGPT 登录。
**最适合：** 使用你的 ChatGPT/Codex 订阅，通过原生 Codex 应用服务器执行，而不是单独的 API key。Codex 云需要 ChatGPT 登录。
<Steps>
<Step title="运行 Codex OAuth">
@ -167,7 +167,7 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
openclaw models auth login --provider openai-codex
```
对于无头或不适合回调的设置，请添加 `--device-code`，用 ChatGPT 设备码流程登录，而不是 localhost 浏览器回调：
对于无头或不适合回调的设置，添加 `--device-code`，使用 ChatGPT 设备码流程登录，而不是 localhost 浏览器回调：
```bash
openclaw models auth login --provider openai-codex --device-code
@ -177,7 +177,7 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
```bash
openclaw config set plugins.entries.codex '{"enabled":true}' --strict-json --merge
openclaw config set agents.defaults.model.primary openai/gpt-5.5
openclaw config set agents.defaults.agentRuntime '{"id":"codex","fallback":"none"}' --strict-json
openclaw config set agents.defaults.agentRuntime '{"id":"codex"}' --strict-json
```
</Step>
<Step title="验证 Codex 凭证可用">
@ -185,25 +185,25 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
openclaw models list --provider openai-codex
```
Gateway 网关运行后，在聊天中发送 `/codex status` 或 `/codex models`，以验证原生 app-server 运行时。
Gateway 网关运行后，在聊天中发送 `/codex status` 或 `/codex models`，验证原生应用服务器运行时。
</Step>
</Steps>
### 路线摘要
### 路由摘要
| 模型引用 | 运行时配置 | 路线 | 凭证 |
| 模型引用 | 运行时配置 | 路由 | 凭证 |
|-----------|----------------|-------|------|
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | 原生 Codex app-server harness | Codex 登录或选定的 `openai-codex` 配置文件 |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | 原生 Codex 应用服务器 harness | Codex 登录或所选 `openai-codex` 配置文件 |
| `openai-codex/gpt-5.5` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.4-mini` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 除非某个插件明确声明 `openai-codex`，否则仍为 PI | Codex 登录 |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍为 PI，除非插件显式声明 `openai-codex` | Codex 登录 |
<Note>
对凭证/配置命令继续使用 `openai-codex` 提供商 id。
继续对 auth/profile 命令使用 `openai-codex` 提供商 ID。
`openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路由。
它不会选择或自动启用内置的 Codex 应用服务器 harness。对于
常见的订阅加原生运行时设置，请使用 `openai-codex` 登录，但保持
模型引用为 `openai/gpt-5.5`，并设置 `agentRuntime.id: "codex"`。
它不会选择或自动启用内置的 Codex app-server harness。对于常见的订阅加原生运行时设置，请使用
`openai-codex` 登录，但保持模型引用为 `openai/gpt-5.5`，并设置
`agentRuntime.id: "codex"`。
</Note>
### 配置示例
@ -214,46 +214,42 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" },
agentRuntime: { id: "codex", fallback: "none" },
agentRuntime: { id: "codex" },
},
},
}
```
若要改为让 Codex OAuth 继续使用常规 PI 运行器，请使用
如果要改为让 Codex OAuth 保持在普通 PI runner 上，请使用
`openai-codex/gpt-5.5`，并省略 Codex 运行时覆盖。
<Note>
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备代码流程登录，OpenClaw 会在自己的智能体凭证存储中管理生成的凭证。
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备代码流程登录，OpenClaw 会在自己的 agent 认证存储中管理生成的凭证。
</Note>
### Status 指示器
聊天 `/status` 会显示当前会话正在使用哪个模型运行时。
默认 PI harness 显示为 `Runtime: OpenClaw Pi Default`。选中
内置 Codex 应用服务器 harness 时，`/status` 会显示
`Runtime: OpenAI Codex`。现有会话会保留记录的 harness id，因此如果你希望 `/status`
反映新的 PI/Codex 选择，请在更改 `agentRuntime` 后使用
聊天中的 `/status` 会显示当前会话正在使用哪个模型运行时。
默认 PI harness 显示为 `Runtime: OpenClaw Pi Default`。选择内置的 Codex app-server harness 时，`/status` 会显示
`Runtime: OpenAI Codex`。现有会话会保留其记录的 harness ID，因此如果你希望 `/status` 反映新的 PI/Codex 选择，请在更改 `agentRuntime` 后使用
`/new` 或 `/reset`。
### Doctor 警告
如果启用了内置 `codex` 插件，同时选择了 `openai-codex/*` 路由，
`openclaw doctor` 会警告该模型仍通过 PI 解析。
只有在这个 PI 订阅凭证路由是有意使用时，才保持配置不变。
当你想使用原生 Codex 应用服务器执行时，请切换到 `openai/<model>`
加 `agentRuntime.id: "codex"`。
`openclaw doctor` 会警告该模型仍然通过 PI 解析。
只有在该 PI 订阅认证路由是有意为之时，才保持配置不变。当你想要原生 Codex app-server 执行时，请切换到 `openai/<model>` 加 `agentRuntime.id: "codex"`。
### 上下文窗口上限
OpenClaw 会将模型元数据和运行时上下文上限视为两个独立值。
OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。
对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`：
- 原生 `contextWindow`：`1000000`
- 默认运行时 `contextTokens` 上限：`272000`
较小的默认上限在实践中具有更好的延迟和质量特征。可用 `contextTokens` 覆盖它：
较小的默认上限在实践中具有更好的延迟和质量特征。使用 `contextTokens` 覆盖它：
```json5
{
@ -273,45 +269,41 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
### 目录恢复
当上游 Codex 目录元数据中存在 `gpt-5.5` 时，OpenClaw 会使用它。
如果账号已完成凭证认证，但实时 Codex 设备发现省略了 `openai-codex/gpt-5.5` 行，
OpenClaw 会合成该 OAuth 模型行，避免 cron、子智能体和已配置的默认模型运行因
当存在 `gpt-5.5` 的上游 Codex 目录元数据时，OpenClaw 会使用它。如果 live Codex 设备发现遗漏了 `openai-codex/gpt-5.5` 行，而账号已通过认证，OpenClaw 会合成该 OAuth 模型行，这样 cron、子 agent 和配置的默认模型运行就不会因
`Unknown model` 而失败。
</Tab>
</Tabs>
## 原生 Codex 应用服务器凭证
## 原生 Codex app-server 认证
原生 Codex 应用服务器 harness 使用 `openai/*` 模型引用加
`agentRuntime.id: "codex"`，但它的凭证仍基于账号。OpenClaw
按以下顺序选择凭证：
原生 Codex app-server harness 使用 `openai/*` 模型引用加
`agentRuntime.id: "codex"`，但其认证仍然基于账号。OpenClaw
按以下顺序选择认证：
1. 绑定到智能体的显式 OpenClaw `openai-codex` 凭证配置文件。
2. 应用服务器的现有账号，例如本地 Codex CLI ChatGPT 登录。
3. 仅对本地 stdio 应用服务器启动，在应用服务器报告没有账号且仍需要
OpenAI 凭证时，使用 `CODEX_API_KEY`，然后是 `OPENAI_API_KEY`。
1. 绑定到 agent 的显式 OpenClaw `openai-codex` 认证配置文件。
2. app-server 的现有账号，例如本地 Codex CLI ChatGPT 登录。
3. 仅对于本地 stdio app-server 启动，当 app-server 报告没有账号但仍需要
OpenAI 认证时，使用 `CODEX_API_KEY`，然后使用
`OPENAI_API_KEY`。
这意味着，本地 ChatGPT/Codex 订阅登录不会仅因为 Gateway 网关进程也有用于直接 OpenAI 模型
或嵌入的 `OPENAI_API_KEY` 而被替换。环境变量 API key 回退仅用于本地 stdio 无账号路径；
它不会发送到 WebSocket 应用服务器连接。选择订阅式 Codex 配置文件时，
OpenClaw 还会将 `CODEX_API_KEY` 和 `OPENAI_API_KEY`
排除在生成的 stdio 应用服务器子进程之外，并通过应用服务器登录 RPC 发送选中的凭证。
这意味着本地 ChatGPT/Codex 订阅登录不会仅仅因为 Gateway 网关进程也为直接 OpenAI 模型或嵌入设置了 `OPENAI_API_KEY` 而被替换。环境 API key 回退只适用于本地 stdio 无账号路径；它不会发送到 WebSocket app-server 连接。选择订阅式 Codex 配置文件时，OpenClaw 还会将 `CODEX_API_KEY` 和 `OPENAI_API_KEY`
排除在生成的 stdio app-server 子进程之外，并通过 app-server login RPC 发送所选凭证。
## 图像生成
内置 `openai` 插件通过 `image_generate` 工具注册图像生成。
它通过同一个 `openai/gpt-image-2` 模型引用同时支持 OpenAI API key 图像生成和 Codex OAuth 图像生成。
它通过同一个 `openai/gpt-image-2` 模型引用，同时支持 OpenAI API key 图像生成和 Codex OAuth 图像生成。
| 能力 | OpenAI API key | Codex OAuth |
| ------------------------- | ---------------------------------- | ------------------------------------ |
| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` |
| 凭证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
| 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
| 传输 | OpenAI Images API | Codex Responses 后端 |
| 每次请求最大图像数 | 4 | 4 |
| 每次请求的最大图像数 | 4 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） |
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 |
| 宽高比/分辨率 | 不转发给 OpenAI Images API | 安全时映射到受支持的尺寸 |
| 纵横比 / 分辨率 | 不转发到 OpenAI Images API | 安全时映射到支持的尺寸 |
```json5
{
@ -327,17 +319,12 @@ OpenClaw 还会将 `CODEX_API_KEY` 和 `OPENAI_API_KEY`
请参阅[图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。
</Note>
`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认值。
`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为
显式模型覆盖使用。对于透明背景 PNG/WebP 输出，请使用 `openai/gpt-image-1.5`；
当前 `gpt-image-2` API 会拒绝 `background: "transparent"`。
`gpt-image-2` 是 OpenAI 文本到图像生成和图像编辑的默认值。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可用作显式模型覆盖。对于透明背景 PNG/WebP 输出，请使用 `openai/gpt-image-1.5`；当前的 `gpt-image-2` API 会拒绝
`background: "transparent"`。
对于透明背景请求，智能体应调用 `image_generate`，并带上
`model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，
以及 `background: "transparent"`；较旧的 `openai.background` 提供商选项
仍会被接受。OpenClaw 还会保护公共 OpenAI 和 OpenAI Codex OAuth 路由，
将默认 `openai/gpt-image-2` 透明请求重写为 `gpt-image-1.5`；
Azure 和自定义 OpenAI 兼容端点会保留其已配置的部署/模型名称。
对于透明背景请求，agent 应使用 `model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"` 以及
`background: "transparent"` 调用 `image_generate`；较旧的 `openai.background` 提供商选项仍被接受。OpenClaw 还会保护公共 OpenAI 和
OpenAI Codex OAuth 路由，将默认 `openai/gpt-image-2` 透明请求重写为 `gpt-image-1.5`；Azure 和自定义 OpenAI 兼容端点会保留其配置的部署/模型名称。
同一设置也暴露给无头 CLI 运行：
@ -350,19 +337,14 @@ openclaw infer image generate \
--json
```
从输入文件开始时，请在 `openclaw infer image edit` 中使用相同的
`--output-format` 和 `--background` 标志。
从输入文件开始时，请对 `openclaw infer image edit` 使用相同的 `--output-format` 和 `--background` 标志。
`--openai-background` 仍可作为 OpenAI 专用别名使用。
对于 Codex OAuth 安装，请保持相同的 `openai/gpt-image-2` 引用。
配置了 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该存储的 OAuth
访问令牌，并通过 Codex Responses 后端发送图像请求。
它不会先尝试 `OPENAI_API_KEY`，也不会为该请求静默回退到 API key。
当你想改用直接的 OpenAI Images API 路由时，请使用 API key、
自定义基础 URL 或 Azure 端点显式配置 `models.providers.openai`。
如果该自定义图像端点位于受信任的 LAN/专用地址，还要设置
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非存在此选择加入项，
OpenClaw 会继续阻止专用/内部 OpenAI 兼容图像端点。
对于 Codex OAuth 安装，请保持相同的 `openai/gpt-image-2` 引用。配置了
`openai-codex` OAuth 配置文件时，OpenClaw 会解析该存储的 OAuth
访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会为该请求静默回退到 API key。若要改用直接 OpenAI Images API 路由，请显式配置 `models.providers.openai`，并设置 API key、自定义 base URL 或 Azure 端点。
如果该自定义图像端点位于受信任的 LAN/私有地址上，还要设置
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非存在此选择加入，OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。
生成：
@ -386,13 +368,13 @@ OpenClaw 会继续阻止专用/内部 OpenAI 兼容图像端点。
内置 `openai` 插件通过 `video_generate` 工具注册视频生成。
| 能力 | 值 |
| ---------------- | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文生视频、图生视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 |
| 能力 | 值 |
| ------------ | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文本到视频、图像到视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略并产生工具警告 |
```json5
{
@ -408,19 +390,19 @@ OpenClaw 会继续阻止专用/内部 OpenAI 兼容图像端点。
请参阅[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。
</Note>
## GPT-5 提示词贡献
## GPT-5 提示贡献
OpenClaw 为跨提供商的 GPT-5 系列运行添加共享 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 和其他兼容的 GPT-5 引用都会收到同一个覆盖层。较旧的 GPT-4.x 模型不会收到。
OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享 GPT-5 提示贡献。它按模型 ID 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 和其他兼容的 GPT-5 引用都会收到相同的叠加层。较旧的 GPT-4.x 模型不会收到。
内置原生 Codex harness 通过 Codex 应用服务器开发者指令使用相同的 GPT-5 行为和 Heartbeat 覆盖层，因此通过 `agentRuntime.id: "codex"` 强制使用的 `openai/gpt-5.x` 会话会保留相同的跟进执行和主动 Heartbeat 指导，即使 harness 提示词的其余部分由 Codex 拥有。
内置原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 Heartbeat 叠加层，因此即使 Codex 拥有 harness 提示的其余部分，通过 `agentRuntime.id: "codex"` 强制路由的 `openai/gpt-5.x` 会话仍保留相同的跟进和主动 Heartbeat 指导。
GPT-5 贡献会添加带标签的行为契约，涵盖人设持久性、执行安全、工具纪律、输出形态、完成检查和验证。特定渠道的回复和静默消息行为仍位于共享 OpenClaw 系统提示词和出站投递策略中。匹配模型始终启用 GPT-5 指导。友好的交互风格层是独立且可配置的。
GPT-5 贡献添加了一个带标签的行为契约，涵盖人格持久性、执行安全、工具纪律、输出形状、完成检查和验证。渠道特定的回复和静默消息行为保留在共享 OpenClaw 系统提示和出站投递策略中。GPT-5 指导始终为匹配模型启用。友好的交互风格层是独立且可配置的。
| 值 | 效果 |
| ---------------------- | ---------------------------- |
| `"friendly"`（默认） | 启用友好的交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
| 值 | 效果 |
| ------------------------ | ---------------------------- |
| `"friendly"`（默认） | 启用友好的交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
<Tabs>
<Tab title="配置">
@ -444,11 +426,11 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人设持久性、执行
</Tabs>
<Tip>
值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
运行时值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
</Tip>
<Note>
当未设置共享 `agents.defaults.promptOverlays.gpt5.personality` 设置时，仍会读取旧版 `plugins.entries.openai.config.personality` 作为兼容性回退。
当共享 `agents.defaults.promptOverlays.gpt5.personality` 设置未设置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。
</Note>
## 语音和语音识别
@ -461,16 +443,16 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人设持久性、执行
|---------|------------|---------|
| 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| 语音 | `messages.tts.providers.openai.voice` | `coral` |
| 速度 | `messages.tts.providers.openai.speed` |（未设置）|
| 指令 | `messages.tts.providers.openai.instructions` |（未设置，仅 `gpt-4o-mini-tts`）|
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音备注使用 `opus`，文件使用 `mp3` |
| 速度 | `messages.tts.providers.openai.speed` | （未设置） |
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音留言使用 `opus`，文件使用 `mp3` |
| API key | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
| 基础 URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
| 额外请求体 | `messages.tts.providers.openai.extraBody` / `extra_body` |（未设置）|
| 额外请求体 | `messages.tts.providers.openai.extraBody` / `extra_body` | （未设置） |
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
在 OpenClaw 生成的字段之后，`extraBody` 会合并到 `/audio/speech` 请求 JSON 中，因此可用于需要 `lang` 等额外键的 OpenAI 兼容端点。原型键会被忽略。
`extraBody` 会在 OpenClaw 生成的字段之后合并到 `/audio/speech` 请求 JSON 中，因此可将它用于需要额外键（例如 `lang`）的 OpenAI 兼容端点。原型键会被忽略。
```json5
{
@ -485,20 +467,21 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人设持久性、执行
```
<Note>
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 基础 URL，而不会影响聊天 API 端点。
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 基础 URL，且不影响聊天 API 端点。
</Note>
</Accordion>
<Accordion title="语音转文本">
内置的 `openai` 插件通过 OpenClaw 的媒体理解转写表面注册批量语音转文本。
内置 `openai` 插件通过 OpenClaw 的媒体理解转写接口注册批量语音转文本。
- 默认模型：`gpt-4o-transcribe`
- 端点：OpenAI REST `/v1/audio/transcriptions`
- 输入路径：multipart 音频文件上传
- 在 OpenClaw 中，凡是入站音频转写使用 `tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道音频附件
- OpenClaw 中任何使用入站音频转写的地方都支持，包括 Discord 语音频道片段和渠道音频附件，即
`tools.media.audio`
要强制对入站音频转写使用 OpenAI：
若要强制入站音频转写使用 OpenAI：
```json5
{
@ -523,25 +506,25 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人设持久性、执行
</Accordion>
<Accordion title="实时转写">
内置的 `openai` 插件为 Voice Call 插件注册实时转写。
内置 `openai` 插件为 Voice Call 插件注册实时转写。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| 语言 | `...openai.language` |（未设置）|
| 提示词 | `...openai.prompt` |（未设置）|
| 静音时长 | `...openai.silenceDurationMs` | `800` |
| 语言 | `...openai.language` | （未设置） |
| 提示词 | `...openai.prompt` | （未设置） |
| 静默时长 | `...openai.silenceDurationMs` | `800` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| API key | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，音频采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）。此流式提供商用于 Voice Call 的实时转写路径；Discord 语音目前会录制短片段，并改用批量 `tools.media.audio` 转写路径。
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，音频为 G.711 u-law（`g711_ulaw` / `audio/pcmu`）。此流式提供商用于 Voice Call 的实时转写路径；Discord 语音目前会录制短片段，并改用批量 `tools.media.audio` 转写路径。
</Note>
</Accordion>
<Accordion title="实时语音">
内置的 `openai` 插件为 Voice Call 插件注册实时语音。
内置 `openai` 插件为 Voice Call 插件注册实时语音。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
@ -549,15 +532,15 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人设持久性、执行
| 语音 | `...openai.voice` | `alloy` |
| 温度 | `...openai.temperature` | `0.8` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| 静音时长 | `...openai.silenceDurationMs` | `500` |
| 静默时长 | `...openai.silenceDurationMs` | `500` |
| API key | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
通过后端实时桥接的 `azureEndpoint` 和 `azureDeployment` 配置键支持 Azure OpenAI。支持双向工具调用。使用 G.711 u-law 音频格式。
通过后端实时桥接的 `azureEndpoint` 和 `azureDeployment` 配置键支持 Azure OpenAI。支持双向 tool 调用。使用 G.711 u-law 音频格式。
</Note>
<Note>
Control UI Talk 使用 OpenAI 浏览器实时会话，其中包含由 Gateway 网关签发的临时客户端密钥，并通过浏览器直接与 OpenAI Realtime API 进行 WebRTC SDP 交换。维护者可通过 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 进行实时验证；OpenAI 这一段会在 Node 中签发客户端密钥，使用模拟麦克风媒体生成浏览器 SDP offer，将其发送到 OpenAI，并在不记录密钥的情况下应用 SDP answer。
Control UI Talk 使用 OpenAI 浏览器实时会话，通过 Gateway 网关签发的临时客户端密钥，并针对 OpenAI Realtime API 直接进行浏览器 WebRTC SDP 交换。维护者可使用 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 进行实时验证；OpenAI 这一段会在 Node 中签发客户端密钥，使用模拟麦克风媒体生成浏览器 SDP offer，将其发布到 OpenAI，并应用 SDP answer，且不会记录密钥。
</Note>
</Accordion>
@ -565,21 +548,24 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人设持久性、执行
## Azure OpenAI 端点
内置的 `openai` 提供商可以通过覆盖基础 URL，将图像生成目标指向 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到 Azure 的请求形态。
内置 `openai` provider 可以通过覆盖基础 URL，将图像生成指向 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到 Azure 的请求形态。
<Note>
实时语音使用单独的配置路径（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），不受 `models.providers.openai.baseUrl` 影响。请参阅 [语音和语音识别](#voice-and-speech) 下的 **实时语音** 折叠项，了解其 Azure 设置。
实时语音使用单独的配置路径
（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），
不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置见 [语音和语音功能](#voice-and-speech) 下的 **实时语音** 折叠面板。
</Note>
在以下情况使用 Azure OpenAI：
在以下情况下使用 Azure OpenAI：
- 你已经拥有 Azure OpenAI 订阅、配额或企业协议
- 你已有 Azure OpenAI 订阅、配额或企业协议
- 你需要 Azure 提供的区域数据驻留或合规控制
- 你希望将流量保留在现有 Azure 租户内
- 你想让流量保留在现有 Azure 租户内
### 配置
要通过内置的 `openai` 提供商使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI key（不是 OpenAI Platform key）：
若要通过内置 `openai` provider 使用 Azure 图像生成，请将
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI key（不是 OpenAI Platform key）：
```json5
{
@ -594,7 +580,7 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人设持久性、执行
}
```
OpenClaw 会识别以下 Azure 主机后缀，用于 Azure 图像生成路由：
OpenClaw 会识别以下 Azure 主机后缀，并用于 Azure 图像生成路由：
- `*.openai.azure.com`
- `*.services.ai.azure.com`
@ -603,15 +589,15 @@ OpenClaw 会识别以下 Azure 主机后缀，用于 Azure 图像生成路由：
对于已识别 Azure 主机上的图像生成请求，OpenClaw 会：
- 发送 `api-key` 标头，而不是 `Authorization: Bearer`
- 使用部署范围路径（`/openai/deployments/{deployment}/...`）
- 为每个请求追加 `?api-version=...`
- 对 Azure 图像生成调用使用 600 秒默认请求超时。
每次调用的 `timeoutMs` 值仍会覆盖此默认值。
- 使用按部署限定的路径（`/openai/deployments/{deployment}/...`）
- 向每个请求追加 `?api-version=...`
- 对 Azure 图像生成调用使用默认 600 秒请求超时。
单次调用的 `timeoutMs` 值仍会覆盖此默认值。
其他基础 URL（公共 OpenAI、OpenAI 兼容代理）会保留标准 OpenAI 图像请求形态。
其他基础 URL（公共 OpenAI、OpenAI 兼容代理）会保持标准 OpenAI 图像请求形态。
<Note>
`openai` 提供商的图像生成路径的 Azure 路由要求 OpenClaw 2026.4.22 或更高版本。早期版本会将任何自定义 `openai.baseUrl` 视为公共 OpenAI 端点，并且在 Azure 图像部署上会失败。
`openai` provider 的图像生成路径上的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。早期版本会将任何自定义 `openai.baseUrl` 当作公共 OpenAI 端点处理，并且在对接 Azure 图像部署时会失败。
</Note>
### API 版本
@ -622,49 +608,51 @@ OpenClaw 会识别以下 Azure 主机后缀，用于 Azure 图像生成路由：
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
```
当该变量未设置时，默认值为 `2024-12-01-preview`。
变量未设置时，默认值为 `2024-12-01-preview`。
### 模型名称就是部署名称
Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**，而不是公共 OpenAI 模型 ID。
Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**，而不是公共 OpenAI 模型 ID。
如果你创建了一个名为 `gpt-image-2-prod`、用于服务 `gpt-image-2` 的部署：
如果你创建了名为 `gpt-image-2-prod`、用于提供 `gpt-image-2` 的部署：
```
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
```
同样的部署名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
同样的部署名称规则也适用于通过内置 `openai` provider 路由的图像生成调用。
### 区域可用性
Azure 图像生成目前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。创建部署前，请查看 Microsoft 当前的区域列表，并确认你的区域提供该特定模型。
Azure 图像生成目前仅在部分区域可用
（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
`uaenorth`）。创建部署前，请检查 Microsoft 当前的区域列表，并确认你的区域提供具体模型。
### 参数差异
Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公共 OpenAI 允许的选项（例如 `gpt-image-2` 上某些 `background` 值），或只在特定模型版本上公开这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的具体部署和 API 版本支持的参数集。
Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公共 OpenAI 允许的选项（例如 `gpt-image-2` 上的某些 `background` 值），或仅在特定模型版本上公开这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的具体部署和 API 版本支持的参数集。
<Note>
Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因标头 —— 请参阅 [高级配置](#advanced-configuration) 下的 **原生与 OpenAI 兼容路由** 折叠项。
Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因标头 — 见 [高级配置](#advanced-configuration) 下的 **原生与 OpenAI 兼容路由** 折叠面板。
对于 Azure 上的聊天或 Responses 流量（图像生成之外），请使用新手引导流程或专用 Azure 提供商配置，单独设置 `openai.baseUrl` 不会采用 Azure API/认证形态。另有一个单独的 `azure-openai-responses/*` 提供商；请参阅下方的服务器端压缩折叠项。
对于 Azure 上的聊天或 Responses 流量（图像生成之外），请使用新手引导流程或专用 Azure provider 配置；仅设置 `openai.baseUrl` 不会套用 Azure API/鉴权形态。另有一个单独的 `azure-openai-responses/*` provider；见下方服务器端压缩折叠面板。
</Note>
## 高级配置
<AccordionGroup>
<Accordion title="传输（WebSocket 与 SSE）">
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 优先使用 WebSocket，并以 SSE 作为回退（`"auto"`）。
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都优先使用 WebSocket，并以 SSE 作为回退（`"auto"`）。
在 `"auto"` 模式下，OpenClaw：
- 在回退到 SSE 之前，重试一次早期 WebSocket 失败
- 在回退到 SSE 前，会重试一次早期 WebSocket 失败
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 为重试和重新连接附加稳定的会话和轮次身份标头
- 为重试和重新连接附加稳定的会话和回合身份标头
- 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
| `"auto"`（默认）| 优先 WebSocket，SSE 回退 |
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
| `"sse"` | 仅强制使用 SSE |
| `"websocket"` | 仅强制使用 WebSocket |
@ -686,13 +674,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
```
相关 OpenAI 文档：
- [通过 WebSocket 使用 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
- [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
- [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)
</Accordion>
<Accordion title="WebSocket 预热">
OpenClaw 默认为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首轮延迟。
OpenClaw 默认为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首次回合延迟。
```json5
// Disable warm-up
@ -717,7 +705,7 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
- **聊天/UI：** `/fast status|on|off`
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
启用后，OpenClaw 会将快速模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。
启用后，OpenClaw 会将快速模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有 `service_tier` 值会保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。
```json5
{
@ -732,13 +720,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
```
<Note>
会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，会话会恢复为已配置的默认值。
会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，会话会回到已配置的默认值。
</Note>
</Accordion>
<Accordion title="优先处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 暴露优先处理。在 OpenClaw 中按模型设置：
OpenAI 的 API 通过 `service_tier` 暴露优先处理。可在 OpenClaw 中按模型设置它：
```json5
{
@ -755,19 +743,19 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
支持的值：`auto`、`default`、`flex`、`priority`。
<Warning>
`serviceTier` 只会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
</Warning>
</Accordion>
<Accordion title="服务端压缩（Responses API）">
对于直接的 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi harness 流包装器会自动启用服务端压缩：
对于直接的 OpenAI Responses 模型（`openai/*` 位于 `api.openai.com`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩：
- 强制使用 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
- 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
这适用于内置 Pi harness 路径，以及嵌入式运行使用的 OpenAI provider 钩子。原生 Codex 应用服务器 harness 会通过 Codex 管理自己的上下文，并通过 `agents.defaults.agentRuntime.id` 单独配置。
这适用于内置的 Pi harness 路径，以及嵌入式运行使用的 OpenAI provider 钩子。原生 Codex 应用服务器 harness 通过 Codex 管理自己的上下文，并通过 `agents.defaults.agentRuntime.id` 单独配置。
<Tabs>
<Tab title="显式启用">
@ -823,7 +811,7 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
</Tabs>
<Note>
`responsesServerCompaction` 只控制 `context_management` 注入。直接的 OpenAI Responses 模型仍会强制使用 `store: true`，除非兼容性设置了 `supportsStore: false`。
`responsesServerCompaction` 只控制 `context_management` 注入。直接的 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。
</Note>
</Accordion>
@ -841,51 +829,51 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
}
```
使用 `strict-agentic` 时，OpenClaw 会：
- 当工具操作可用时，不再把仅有计划的轮次视为成功进展
- 使用立即行动 steer 重试该轮次
- 对实质性工作自动启用 `update_plan`
- 如果模型持续只规划而不行动，则显式呈现阻塞状态
使用 `strict-agentic` 时，OpenClaw：
- 当工具操作可用时，不再将仅计划的轮次视为成功进展
- 使用立即行动引导重试该轮次
- 为实质性工作自动启用 `update_plan`
- 如果模型持续只做计划而不行动，则暴露明确的阻塞状态
<Note>
仅限 OpenAI 和 Codex GPT-5 系列运行。其他提供商和较旧模型系列保持默认行为。
仅限 OpenAI 和 Codex GPT-5 系列运行。其他提供商和更早的模型系列保持默认行为。
</Note>
</Accordion>
<Accordion title="原生路由与 OpenAI 兼容路由">
OpenClaw 对待直接 OpenAI、Codex 和 Azure OpenAI 端点的方式不同于通用 OpenAI 兼容 `/v1` 代理：
OpenClaw 对待直接的 OpenAI、Codex 和 Azure OpenAI 端点的方式不同于通用的 OpenAI 兼容 `/v1` 代理：
**原生路由**（`openai/*`、Azure OpenAI）：
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
- 对会拒绝 `reasoning.effort: "none"` 的模型或代理省略已禁用的 reasoning
- 默认将工具 schema 设置为严格模式
- 对拒绝 `reasoning.effort: "none"` 的模型或代理省略已禁用的推理
- 默认将工具 schema 设为严格模式
- 仅在已验证的原生主机上附加隐藏归因标头
- 保留仅限 OpenAI 的请求整形（`service_tier`、`store`、reasoning 兼容性、提示缓存提示）
- 保留仅 OpenAI 使用的请求塑形（`service_tier`、`store`、推理兼容性、prompt-cache 提示）
**代理/兼容路由：**
- 使用更宽松的兼容行为
- 从非原生 `openai-completions` 载荷中移除 Completions `store`
- 接受高级 `params.extra_body`/`params.extraBody` 透传 JSON，用于 OpenAI 兼容 Completions 代理
- 接受 `params.chat_template_kwargs`，用于 vLLM 等 OpenAI 兼容 Completions 代理
- 不强制使用严格工具 schema 或仅限原生的标头
- 从非原生 `openai-completions` 载荷中剥离 Completions `store`
- 接受高级 `params.extra_body`/`params.extraBody` 透传 JSON，用于 OpenAI 兼容的 Completions 代理
- 接受 `params.chat_template_kwargs`，用于 vLLM 等 OpenAI 兼容的 Completions 代理
- 不强制使用严格工具 schema 或仅原生使用的标头
Azure OpenAI 使用原生传输和兼容行为，但不会收到隐藏归因标头。
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因标头。
</Accordion>
</AccordionGroup>
## 相关内容
## 相关
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
共享的图像工具参数和提供商选择。
共享图像工具参数和提供商选择。
</Card>
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享的视频工具参数和提供商选择。
共享视频工具参数和提供商选择。
</Card>
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
认证详情和凭据复用规则。