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-02 02:40:08 +00:00
parent 07909bdbe1
commit c8ed9a1fc5
9 changed files with 1448 additions and 1335 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

@ -1,54 +1,54 @@
---
read_when:
- 你需要一份按提供商划分的模型设置参考
- 你需要模型提供商的示例配置或 CLI 新手引导命令
- 你想要模型提供商的配置示例或 CLI 新手引导命令
sidebarTitle: Model providers
summary: 模型提供商概览：示例配置 + CLI 流程
summary: 模型提供商概览，包含配置示例和 CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-05-02T02:28:46Z"
generated_at: "2026-05-02T02:37:18Z"
model: gpt-5.5
provider: openai
source_hash: 6b1523616a846b2bf0cad46f9f4a713fbb5e8bd7327108ab593eea8c841d5eef
source_hash: 34e6a6b691b447a66a94f69a7b609f26c587eaa5bc55c5ed62460ce14cc288fd
source_path: concepts/model-providers.md
workflow: 16
---
模型提供商（**LLM/模型提供商**，不是 WhatsApp/Telegram 这类聊天渠道）参考。模型选择规则见 [Models](/zh-CN/concepts/models)。
LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）参考。模型选择规则见 [Models](/zh-CN/concepts/models)。
## 快速规则
<AccordionGroup>
<Accordion title="模型引用和 CLI 助手">
<Accordion title="模型引用和 CLI 辅助命令">
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
- 设置后，`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` 会按模型覆盖它们。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- `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`。
</Accordion>
<Accordion title="OpenAI provider/运行时拆分">
<Accordion title="OpenAI 提供商/运行时拆分">
OpenAI 系列路由按前缀区分：
- `openai/<model>` 使用 PI 中的直接 OpenAI API key 提供商。
- `openai-codex/<model>` 使用 PI 中的 Codex OAuth。
- `openai/<model>` 加上 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex 应用服务器 harness。
- `openai/<model>` 加上 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex 应用服务器 harness。这是常见的 ChatGPT/Codex 订阅设置。
- `openai-codex/<model>` 在 PI 中使用 Codex OAuth。
- 没有 Codex 运行时覆盖的 `openai/<model>` 在 PI 中使用直接 OpenAI API key 提供商。
见 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果提供商/运行时拆分让人困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
见 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果提供商/运行时拆分让人困惑，请先阅读 [Agent runtimes](/zh-CN/concepts/agent-runtimes)。
插件自动启用遵循相同边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/<model>` 引用启用。
插件自动启用遵循同一边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/<model>` 引用启用。
GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API key 流量，可在 PI 中通过 `openai-codex/gpt-5.5` 用于 Codex OAuth，也可在设置 `agentRuntime.id: "codex"` 时通过原生 Codex 应用服务器 harness 使用。
设置 `agentRuntime.id: "codex"` 时，可通过原生 Codex 应用服务器 harness 使用 GPT-5.5；在 PI 中可通过 `openai-codex/gpt-5.5` 使用 Codex OAuth；当你的账号暴露该模型时，在 PI 中可通过 `openai/gpt-5.5` 使用直接 API key 流量。
</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/*` 引用会迁移回规范提供商引用，并单独记录运行时。
@ -57,18 +57,18 @@ x-i18n:
## 插件拥有的提供商行为
大多数提供商特定逻辑位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、思考/推理配置文件等。
大多数提供商专用逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、凭证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、思考/推理 profile 等能力。
提供商 SDK 钩子和内置插件示例的完整列表位于 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于另一个更深层的扩展表面。
提供商 SDK 钩子和内置插件示例的完整列表位于 [Provider plugins](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于一个独立且更深的扩展面。
<Note>
提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求助手。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，共享 runner 逻辑不再读取它。
提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求辅助函数。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，不再由共享 runner 逻辑读取。
</Note>
## API key 轮换
<AccordionGroup>
<Accordion title="key 来源和优先级">
<Accordion title="Key 来源和优先级">
通过以下方式配置多个 key：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
@ -76,38 +76,38 @@ x-i18n:
- `<PROVIDER>_API_KEY`（主 key）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。key 选择顺序会保留优先级并对值去重。
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。Key 选择顺序会保留优先级并对值去重。
</Accordion>
<Accordion title="何时触发轮换">
- 仅在速率限制响应时，才会使用下一个 key 重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 或周期性用量限制消息）。
- 非速率限制失败会立即失败；不会尝试 key 轮换。
- 当所有候选 key 都失败时，将返回最后一次尝试的最终错误。
<Accordion title="轮换何时触发">
- 只有在限流响应时，请求才会使用下一个 key 重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
- 非限流失败会立即失败；不会尝试 key 轮换。
- 当所有候选 key 都失败时，会返回最后一次尝试的最终错误。
</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` 验证账号/模型可用性。
- 如果特定安装或 API key 表现不同，请使用 `openclaw models list --provider openai` 验证账号/模型可用性。
- CLI：`openclaw onboard --auth-choice openai-api-key`
- 默认传输为 `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` 启用
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先处理
- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 当你想使用显式 tier 而不是共享 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI 推理兼容载荷整形；代理路由不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未公开它
- 当你需要显式层级而不是共享的 `/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 目录未暴露它
```json5
{
@ -118,18 +118,18 @@ OpenClaw 随附 pi‑ai 目录。这些提供商不需要任何 `models.provider
### 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` 引用仍可用于兼容性。
<Note>
Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 使用方式已重新允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 使用视为此集成的获准方式，除非 Anthropic 发布新策略。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,16 +150,23 @@ 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 OAuth 明确支持 OpenClaw 等外部工具/工作流。
- 当你想使用 Codex OAuth/订阅路由时，请使用 `openai-codex/gpt-5.5`；当你的 API key 设置和本地目录公开公共 API 路由时，请使用 `openai/gpt-5.5`。
- `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`。
```json5
{
agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } },
plugins: { entries: { codex: { enabled: true } } },
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" },
agentRuntime: { id: "codex", fallback: "none" },
},
},
}
```
@ -179,19 +186,19 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 使用方式已重
<CardGroup cols={3}>
<Card title="GLM 模型" href="/zh-CN/providers/glm">
Z.AI Coding Plan 或通用 API endpoint。
Z.AI Coding Plan 或通用 API 端点。
</Card>
<Card title="MiniMax" href="/zh-CN/providers/minimax">
MiniMax Coding Plan OAuth 或 API key 访问。
</Card>
<Card title="Qwen Cloud" href="/zh-CN/providers/qwen">
Qwen Cloud 提供商表面，以及 Alibaba DashScope 和 Coding Plan endpoint 映射。
Qwen Cloud 提供商表面，以及 Alibaba DashScope 和 Coding Plan 端点映射。
</Card>
</CardGroup>
### 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`
@ -206,28 +213,28 @@ Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 使用方式已重
### Google Gemini（API key）
- 提供商：`google`
- 认证：`GEMINI_API_KEY`
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
- 凭证：`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`
- 直接运行 Gemini 时，也接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`）来转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
### Google Vertex 和 Gemini CLI
- 提供商：`google-vertex`、`google-gemini-cli`
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
- 凭证：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="安装 Gemini CLI">
<Step title="Install Gemini CLI">
<Tabs>
<Tab title="brew">
```bash
@ -241,68 +248,68 @@ Gemini CLI OAuth 作为内置 `google` 插件的一部分发布。
</Tab>
</Tabs>
</Step>
<Step title="启用插件">
<Step title="Enable plugin">
```bash
openclaw plugins enable google
```
</Step>
<Step title="登录">
<Step title="Login">
```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 或密钥粘贴到 `openclaw.json`。CLI 登录流程会把令牌存储在 Gateway 网关主机上的凭证配置文件中。
</Step>
<Step title="设置项目（如需要）">
<Step title="Set project (if needed)">
如果登录后请求失败，请在 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)
### Z.AI（GLM）
- 提供商：`zai`
- 身份验证：`ZAI_API_KEY`
- 凭证：`ZAI_API_KEY`
- 示例模型：`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`
- 身份验证：`AI_GATEWAY_API_KEY`
- 凭证：`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 网关
- 提供商：`kilocode`
- 身份验证：`KILOCODE_API_KEY`
- 凭证：`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 中硬编码。
- 静态回退目录内置 `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` |
| Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` |
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
| Kimi Coding | `kimi` | `KIMI_API_KEY` or `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` |
| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` |
@ -313,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` |
| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
| 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 管理的提示缓存 TTL 条件，但不会收到 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的塑形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容）。Gemini 后端引用仅保留代理 Gemini 思维签名清理。
</Accordion>
<Accordion title="Kilo Gateway 网关">
<Accordion title="Kilo Gateway">
Gemini 后端引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。
</Accordion>
<Accordion title="MiniMax">
API 密钥新手引导会写入显式的纯文本 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` 禁用。
</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>
@ -345,16 +352,16 @@ Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。
下面的许多内置提供商插件已经发布默认目录。仅当你想覆盖默认基础 URL、标头或模型列表时，才使用显式 `models.providers.<id>` 条目。
下面许多内置提供商插件已经发布默认目录。仅当你想覆盖默认基础 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 AI (Kimi)
Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
Moonshot 作为内置提供商插件发布。默认使用内置提供商，并且仅在需要覆盖基础 URL 或模型元数据时才添加显式的 `models.providers.moonshot` 条目：
- 提供商：`moonshot`
- 凭证：`MOONSHOT_API_KEY`
- 认证：`MOONSHOT_API_KEY`
- 示例模型：`moonshot/kimi-k2.6`
- CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`
@ -389,12 +396,12 @@ Kimi K2 模型 ID：
}
```
### Kimi 编码
### Kimi 编程
Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
- 提供商：`kimi`
- 凭证：`KIMI_API_KEY`
- 认证：`KIMI_API_KEY`
- 示例模型：`kimi/kimi-code`
```json5
@ -406,11 +413,11 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
}
```
旧版 `kimi/k2p5` 仍作为兼容模型 ID 被接受。
旧版 `kimi/k2p5` 仍作为兼容性模型 ID 被接受。
### Volcano Engine（豆包）
Volcano Engine（火山引擎）提供对中国区豆包和其他模型的访问。
Volcano Engine（火山引擎）提供在中国访问豆包和其他模型的能力。
- 提供商：`volcengine`（编码：`volcengine-plan`）
- 凭证：`VOLCANO_ENGINE_API_KEY`
@ -425,20 +432,20 @@ Volcano Engine（火山引擎）提供对中国区豆包和其他模型的访问
}
```
新手引导默认使用编码表面，但通用的 `volcengine/*` 目录会同时注册。
新手引导默认使用编码接口，但通用 `volcengine/*` 目录会同时注册。
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。
在新手引导/配置模型选择器中，Volcengine 凭证选项优先显示 `volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。
<Tabs>
<Tab title="标准模型">
- `volcengine/doubao-seed-1-8-251228` (Doubao Seed 1.8)
- `volcengine/doubao-seed-1-8-251228`（Doubao Seed 1.8）
- `volcengine/doubao-seed-code-preview-251028`
- `volcengine/kimi-k2-5-260127` (Kimi K2.5)
- `volcengine/glm-4-7-251222` (GLM 4.7)
- `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K)
- `volcengine/kimi-k2-5-260127`（Kimi K2.5）
- `volcengine/glm-4-7-251222`（GLM 4.7）
- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K）
</Tab>
<Tab title="编码模型 (volcengine-plan)">
<Tab title="编码模型（volcengine-plan）">
- `volcengine-plan/ark-code-latest`
- `volcengine-plan/doubao-seed-code`
- `volcengine-plan/kimi-k2.5`
@ -450,10 +457,10 @@ Volcano Engine（火山引擎）提供对中国区豆包和其他模型的访问
### BytePlus（国际版）
BytePlus ARK 为国际用户提供与火山引擎相同模型的访问能力。
BytePlus ARK 为国际用户提供访问与 Volcano Engine 相同模型的能力。
- 提供商：`byteplus`（编码：`byteplus-plan`）
- 认证：`BYTEPLUS_API_KEY`
- 凭证：`BYTEPLUS_API_KEY`
- 示例模型：`byteplus-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
@ -465,18 +472,18 @@ BytePlus ARK 为国际用户提供与火山引擎相同模型的访问能力。
}
```
新手引导默认使用编码界面，但通用 `byteplus/*` 目录会同时注册。
新手引导默认使用编码接口，但通用 `byteplus/*` 目录会同时注册。
在新手引导/配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的、限定提供商范围的选择器。
在新手引导/配置模型选择器中，BytePlus 凭证选项优先显示 `byteplus/*` 和 `byteplus-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。
<Tabs>
<Tab title="标准模型">
- `byteplus/seed-1-8-251228` (Seed 1.8)
- `byteplus/kimi-k2-5-260127` (Kimi K2.5)
- `byteplus/glm-4-7-251222` (GLM 4.7)
- `byteplus/seed-1-8-251228`（Seed 1.8）
- `byteplus/kimi-k2-5-260127`（Kimi K2.5）
- `byteplus/glm-4-7-251222`（GLM 4.7）
</Tab>
<Tab title="编码模型 (byteplus-plan)">
<Tab title="编码模型（byteplus-plan）">
- `byteplus-plan/ark-code-latest`
- `byteplus-plan/doubao-seed-code`
- `byteplus-plan/kimi-k2.5`
@ -488,10 +495,10 @@ BytePlus ARK 为国际用户提供与火山引擎相同模型的访问能力。
### Synthetic
Synthetic 在 `synthetic` 提供商后方提供 Anthropic 兼容模型：
Synthetic 在 `synthetic` 提供商后提供 Anthropic 兼容模型：
- 提供商：`synthetic`
- 认证：`SYNTHETIC_API_KEY`
- 凭证：`SYNTHETIC_API_KEY`
- 示例模型：`synthetic/hf:MiniMaxAI/MiniMax-M2.5`
- CLI：`openclaw onboard --auth-choice synthetic-api-key`
@ -522,30 +529,30 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax OAuth（中国）：`--auth-choice minimax-cn-oauth`
- MiniMax API key（全球）：`--auth-choice minimax-global-api`
- MiniMax API key（中国）：`--auth-choice minimax-cn-api`
- 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
设置详情、模型选项和配置片段见 [/providers/minimax](/zh-CN/providers/minimax)。
<Note>
在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，OpenClaw 默认会禁用思考，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，否则 OpenClaw 默认禁用思考，并且 `/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`
- 图像理解是在两个 MiniMax 凭证路径上由插件拥有的 `MiniMax-VL-01`
- Web 搜索保持在提供商 ID `minimax`
### LM Studio
LM Studio 作为内置提供商插件提供，并使用原生 API：
LM Studio 作为内置提供商插件发布，并使用原生 API：
- 提供商：`lmstudio`
- 认证：`LM_API_TOKEN`
- 凭证：`LM_API_TOKEN`
- 默认推理基础 URL：`http://localhost:1234/v1`
然后设置模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
```json5
{
@ -555,14 +562,14 @@ LM Studio 作为内置提供商插件提供，并使用原生 API：
}
```
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 做设备发现 + 自动加载，并默认用 `/v1/chat/completions` 做推理。设置与故障排除见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。设置和故障排除见 [/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)
@ -579,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` 选择启用时，OpenClaw 会在本地 `http://127.0.0.1:11434` 检测 Ollama，且内置提供商插件会把 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
{
@ -609,19 +616,19 @@ export VLLM_API_KEY="vllm-local"
### 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
{
@ -683,14 +690,14 @@ export SGLANG_API_KEY="sglang-local"
</Accordion>
<Accordion title="代理路由塑形规则">
- 对非原生端点（任何非空 `baseUrl` 且其主机不是 `api.openai.com`）上的 `api: "openai-completions"`，OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持的 `developer` 角色返回 400 错误。
- 代理式 OpenAI 兼容路由还会跳过仅适用于原生 OpenAI 的请求塑形：没有 `service_tier`、没有 Responses `store`、没有 Completions `store`、没有提示缓存提示、没有 OpenAI 推理兼容载荷塑形，也没有隐藏的 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 请求处理，包括连接、标头、正文流式传输以及总的受保护抓取中止时间，而不会增加整个 Agent 运行时超时。
- 对于非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl` 且其主机不是 `api.openai.com`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免提供商因不支持的 `developer` 角色返回 400 错误。
- 代理风格的 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求塑形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有提示缓存提示，没有 OpenAI 推理兼容载荷塑形，也没有隐藏的 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 请求处理时间，包括连接、标头、正文流式传输和总的受保护获取中止时间，而不会增加整个智能体运行时超时。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。
- 为了安全，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
- 对非直连端点（canonical `anthropic` 以外的任何提供商，或自定义 `models.providers.anthropic.baseUrl` 且其主机不是公开 `api.anthropic.com` 端点）上的 `api: "anthropic-messages"`，OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，这样自定义 Anthropic 兼容代理就不会拒绝不支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 `models.providers.<id>.headers["anthropic-beta"]`。
- 为安全起见，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
- 对于非直连端点上的 `api: "anthropic-messages"`（除规范 `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"]`。
</Accordion>
</AccordionGroup>
@ -703,11 +710,11 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
另请参阅：[配置](/zh-CN/gateway/configuration)，了解完整配置示例。
另见：[配置](/zh-CN/gateway/configuration) 了解完整配置示例。
## 相关内容
## 相关
- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键
- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链和重试行为
- [Models](/zh-CN/concepts/models) — 模型配置和别名
- [提供商](/zh-CN/providers) — 各提供商设置指南
- [提供商](/zh-CN/providers) — 按提供商划分的设置指南

140
docs/zh-CN/concepts/models.md
View File

@ -1,38 +1,38 @@
---
read_when:
- 添加或修改 models CLI（models list/set/scan/aliases/fallbacks）
- 更改模型回退行为或选择用户体验
- 更新模型扫描探针（工具/图像）
- 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks）
- 更改模型回退行为或选择体验
- 更新模型扫描探测（工具/图像）
sidebarTitle: Models CLI
summary: Models CLI：列出、设置、别名、回退、扫描、状态
summary: Models CLI：列出、设置、别名、回退、扫描、Status
title: Models CLI
x-i18n:
generated_at: "2026-04-29T17:09:47Z"
generated_at: "2026-05-02T02:37:21Z"
model: gpt-5.5
provider: openai
source_hash: 64b97ddfcc6f804044580dfc9a441d426f737e9e7d007d78b0b045a52068b34f
source_hash: 620df60ee1117a32f0232bf4b56fbc5a9558be5cc3b73a31336f8ab64fd29ebb
source_path: concepts/models.md
workflow: 16
---
<CardGroup cols={2}>
<Card title="模型故障转移" href="/zh-CN/concepts/model-failover">
凭证配置轮换、冷却时间，以及它如何与回退交互。
凭证配置档轮换、冷却时间，以及它们如何与回退交互。
</Card>
<Card title="模型提供商" href="/zh-CN/concepts/model-providers">
快速提供商概览和示例。
</Card>
<Card title="Agent Runtimes" href="/zh-CN/concepts/agent-runtimes">
PI、Codex 和其他 Agent loop 运行时。
Pi、Codex 和其他 Agent loop 运行时。
</Card>
<Card title="配置参考" href="/zh-CN/gateway/config-agents#agent-defaults">
模型配置键。
</Card>
</CardGroup>
模型引用会选择提供商和模型。它们通常不会选择底层智能体运行时。例如，`openai/gpt-5.5` 可以通过常规 OpenAI provider 路径运行，也可以通过 Codex 应用服务器运行时运行，具体取决于 `agents.defaults.agentRuntime.id`。请参阅 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
模型引用会选择一个提供商和模型。它们通常不会选择底层 Agent Runtimes。例如，`openai/gpt-5.5` 可以通过常规 OpenAI provider 路径运行，也可以通过 Codex 应用服务器运行时运行，具体取决于 `agents.defaults.agentRuntime.id`。在 Codex 运行时模式下，`openai/gpt-*` 引用并不意味着 API key 计费；凭证可以来自 Codex 账户或 `openai-codex` 凭证配置档。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
## 模型选择如何工作
## 模型选择的工作方式
OpenClaw 按以下顺序选择模型：
@ -44,39 +44,39 @@ OpenClaw 按以下顺序选择模型：
`agents.defaults.model.fallbacks`（按顺序）。
</Step>
<Step title="提供商凭证故障转移">
凭证故障转移发生在提供商内部，然后才会移到下一个模型。
凭证故障转移会先在提供商内部发生，然后才移动到下一个模型。
</Step>
</Steps>
<AccordionGroup>
<Accordion title="相关模型界面">
- `agents.defaults.models` 是 OpenClaw 可以使用的模型允许列表/目录（以及别名）。
<Accordion title="相关模型表面">
- `agents.defaults.models` 是 OpenClaw 可用模型的允许列表/目录（加上别名）。
- `agents.defaults.imageModel` **仅在**主模型无法接受图片时使用。
- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到已解析的会话/默认模型。
- `agents.defaults.imageGenerationModel` 由共享图片生成能力使用。如果省略，`image_generate` 仍然可以推断一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的图片生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。
- `agents.defaults.musicGenerationModel` 由共享音乐生成能力使用。如果省略，`music_generate` 仍然可以推断一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。
- `agents.defaults.videoGenerationModel` 由共享视频生成能力使用。如果省略，`video_generate` 仍然可以推断一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的视频生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。
- 每个智能体的默认值可以通过 `agents.list[].model` 加绑定来覆盖 `agents.defaults.model`（参见[多智能体路由](/zh-CN/concepts/multi-agent)）。
- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到解析后的会话/默认模型。
- `agents.defaults.imageGenerationModel` 由共享图片生成能力使用。如果省略，`image_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图片生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。
- `agents.defaults.musicGenerationModel` 由共享音乐生成能力使用。如果省略，`music_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。
- `agents.defaults.videoGenerationModel` 由共享视频生成能力使用。如果省略，`video_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。
- 单个智能体默认值可以通过 `agents.list[].model` 加绑定来覆盖 `agents.defaults.model`（参见[多智能体路由](/zh-CN/concepts/multi-agent)）。
</Accordion>
</AccordionGroup>
## 选择来源和回退行为
同一个 `provider/model` 可能因来源不同而含义不同：
同一个 `provider/model` 可能含义不同，具体取决于它来自哪里：
- 配置的默认值（`agents.defaults.model.primary` 和智能体专属主模型）是常规起点，并使用 `agents.defaults.model.fallbacks`。
- 自动回退选择是临时恢复状态。它们会以 `modelOverrideSource: "auto"` 存储，因此后续轮次可以继续使用回退链，而不必先探测已知不可用的主模型。
- 用户会话选择是精确的。`/model`、模型选择器、`session_status(model=...)` 和 `sessions.patch` 会存储 `modelOverrideSource: "user"`；如果所选 provider/model 无法访问，OpenClaw 会明确失败，而不是落到另一个已配置模型。
- Cron `--model` / 载荷 `model` 是每个作业的主模型。它仍会使用已配置的回退，除非作业提供显式载荷 `fallbacks`（严格的 cron 运行请使用 `fallbacks: []`）。
- CLI 默认模型和允许列表选择器会遵循 `models.mode: "replace"`，列出显式的 `models.providers.*.models`，而不是加载完整内置目录。
- Control UI 模型选择器会向 Gateway 网关请求其已配置的模型视图：存在时使用 `agents.defaults.models`，否则使用显式的 `models.providers.*.models` 加上具有可用凭证的提供商。完整内置目录只保留给显式浏览视图，例如带有 `view: "all"` 的 `models.list` 或 `openclaw models list --all`。
- 已配置默认值（`agents.defaults.model.primary` 和智能体专属主模型）是常规起点，并使用 `agents.defaults.model.fallbacks`。
- 自动回退选择是临时恢复状态。它们会以 `modelOverrideSource: "auto"` 存储，因此后续轮次可以继续使用回退链，而无需先探测已知不可用的主模型。
- 用户会话选择是精确的。`/model`、模型选择器、`session_status(model=...)` 和 `sessions.patch` 会存储 `modelOverrideSource: "user"`；如果所选提供商/模型不可达，OpenClaw 会显式失败，而不是落到另一个已配置模型。
- Cron `--model` / payload `model` 是单个作业的主模型。它仍会使用已配置回退，除非作业提供显式 payload `fallbacks`（严格 cron 运行请使用 `fallbacks: []`）。
- CLI 默认模型和允许列表选择器会遵守 `models.mode: "replace"`，列出显式的 `models.providers.*.models`，而不是加载完整内置目录。
- Control UI 模型选择器会向 Gateway 网关请求其已配置的模型视图：存在时使用 `agents.defaults.models`，否则使用显式的 `models.providers.*.models` 加上有可用凭证的提供商。完整内置目录仅保留给显式浏览视图，例如带有 `view: "all"` 的 `models.list` 或 `openclaw models list --all`。
## 快速模型策略
- 将你的主模型设为你可用的最强最新一代模型。
- 将回退用于对成本/延迟敏感的任务和低风险聊天。
- 对于启用工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。
- 将主模型设置为你可用的最强新一代模型。
- 对成本/延迟敏感任务和低风险聊天使用回退。
- 对启用工具的智能体或不可信输入，避免使用较旧/较弱的模型层级。
## 新手引导（推荐）
@ -114,25 +114,25 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json
<AccordionGroup>
<Accordion title="覆盖保护规则">
`openclaw config set` 会保护模型/提供商映射，避免意外覆盖。当普通对象赋值给 `agents.defaults.models`、`models.providers` 或 `models.providers.<id>.models` 会移除现有条目时，该赋值会被拒绝。增量更改请使用 `--merge`；仅当提供的值应成为完整目标值时才使用 `--replace`。
`openclaw config set` 会保护模型/提供商映射，避免意外覆盖。对 `agents.defaults.models`、`models.providers` 或 `models.providers.<id>.models` 的普通对象赋值，如果会移除现有条目，将被拒绝。使用 `--merge` 进行增量更改；仅当提供的值应该成为完整目标值时，才使用 `--replace`。
交互式提供商设置和 `openclaw configure --section model` 也会将提供商范围的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商不会丢弃无关的模型条目。重新应用提供商凭证时，Configure 会保留现有的 `agents.defaults.model.primary`。显式默认值设置命令，例如 `openclaw models auth login --provider <id> --set-default` 和 `openclaw models set <model>`，仍会替换 `agents.defaults.model.primary`。
交互式提供商设置和 `openclaw configure --section model` 也会将提供商作用域的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商不会删除无关的模型条目。重新应用提供商凭证时，configure 会保留现有 `agents.defaults.model.primary`。显式默认值设置命令（例如 `openclaw models auth login --provider <id> --set-default` 和 `openclaw models set <model>`）仍会替换 `agents.defaults.model.primary`。
</Accordion>
</AccordionGroup>
## “Model is not allowed”（以及回复为什么会停止）
## “不允许使用模型”（以及回复为什么停止）
如果设置了 `agents.defaults.models`，它会成为 `/model` 和会话覆盖的**允许列表**。当用户选择的模型不在该允许列表中时，OpenClaw 会返回：
如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择不在该允许列表中的模型时，OpenClaw 会返回：
```
Model "provider/model" is not allowed. Use /model to list available models.
```
<Warning>
这发生在生成正常回复**之前**，因此消息可能让人感觉它“没有响应”。修复方法是以下任一项：
这发生在生成常规回复**之前**，所以这条消息可能让人感觉像是“没有响应”。修复方式是以下任一项：
- 将模型添加到 `agents.defaults.models`，或
- 将该模型添加到 `agents.defaults.models`，或
- 清除允许列表（移除 `agents.defaults.models`），或
- 从 `/model list` 中选择一个模型。
@ -140,8 +140,8 @@ Model "provider/model" is not allowed. Use /model to list available models.
对于本地/GGUF 模型，请在允许列表中存储带完整提供商前缀的引用，
例如 `ollama/gemma4:26b`、`lmstudio/Gemma4-26b-a4-it-gguf`，或
`openclaw models list --provider <provider>` 显示的精确 provider/model。
当允许列表处于激活状态时，仅有本地裸文件名或显示名称是不够的。
`openclaw models list --provider <provider>` 显示的确切提供商/模型。
当允许列表处于活动状态时，仅有本地文件名或显示名称是不够的。
允许列表示例配置：
@ -159,7 +159,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
## 在聊天中切换模型（`/model`）
你可以在不重启的情况下为当前会话切换模型：
你可以在不重启的情况下切换当前会话的模型：
```
/model
@ -172,7 +172,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
<AccordionGroup>
<Accordion title="选择器行为">
- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型系列 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及提交步骤。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及一个 Submit 步骤。
- `/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。
- `/model <#>` 会从该选择器中选择。
@ -180,10 +180,10 @@ Model "provider/model" is not allowed. Use /model to list available models.
<Accordion title="持久化和实时切换">
- `/model` 会立即持久化新的会话选择。
- 如果智能体处于空闲状态，下一次运行会立即使用新模型。
- 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只在干净的重试点重启进入新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到之后的重试机会或下一轮用户输入。
- 用户选择的 `/model` 引用对该会话是严格的：如果所选 provider/model 无法访问，回复会明确失败，而不是静默地从 `agents.defaults.model.fallbacks` 回答。这不同于已配置默认值和 cron 作业主模型，后者仍可使用回退链。
- `/model status` 是详细视图（凭证候选项，以及配置时的提供商端点 `baseUrl` + `api` 模式）。
- 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队到后续重试机会或下一个用户轮次。
- 用户选择的 `/model` 引用对该会话是严格的：如果所选提供商/模型不可达，回复会显式失败，而不是悄悄从 `agents.defaults.model.fallbacks` 作答。这不同于已配置默认值和 cron 作业主模型，后两者仍可使用回退链。
- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。
</Accordion>
<Accordion title="引用解析">
@ -191,8 +191,8 @@ Model "provider/model" is not allowed. Use /model to list available models.
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 会按以下顺序解析输入：
1. 别名匹配
2. 对该精确无前缀模型 ID 的唯一已配置提供商匹配
3. 已弃用的回退到已配置默认提供商——如果该提供商不再公开已配置的默认模型，OpenClaw 会改为回退到第一个已配置 provider/model，以避免暴露过时的已移除提供商默认值。
2. 与该精确无前缀模型 ID 唯一匹配的已配置提供商
3. 已弃用的回退到已配置默认提供商 — 如果该提供商不再公开已配置默认模型，OpenClaw 会改为回退到第一个已配置提供商/模型，以避免暴露陈旧的已移除提供商默认值。
</Accordion>
</AccordionGroup>
@ -228,13 +228,13 @@ openclaw models image-fallbacks clear
默认显示已配置/凭证可用的模型。实用标志：
<ParamField path="--all" type="boolean">
完整目录。包括在配置凭证之前由内置提供商拥有的静态目录行，因此仅用于设备发现的视图可以显示在添加匹配提供商凭证之前不可用的模型。
完整目录。包含在配置凭证前由内置提供商拥有的静态目录行，因此仅设备发现视图可以显示在你添加匹配的提供商凭证前不可用的模型。
</ParamField>
<ParamField path="--local" type="boolean">
仅本地提供商。
</ParamField>
<ParamField path="--provider <id>" type="string">
按提供商 ID 过滤，例如 `moonshot`。不接受交互式选择器中的显示标签。
按提供商 id 过滤，例如 `moonshot`。不接受交互式选择器中的显示标签。
</ParamField>
<ParamField path="--plain" type="boolean">
每行一个模型。
@ -245,21 +245,21 @@ openclaw models image-fallbacks clear
### `models status`
显示解析后的主模型、备用模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 到期 Status（默认在 24 小时内发出警告）。`--plain` 仅打印解析后的主模型。
显示解析后的主模型、备用模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 过期 Status（默认在 24h 内警告）。`--plain` 仅打印解析后的主模型。
<AccordionGroup>
<Accordion title="凭证和探测行为">
- OAuth Status 始终显示（并包含在 `--json` 输出中）。如果配置的提供商没有凭据，`models status` 会打印 **Missing auth** 部分。
- JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效凭证，包括由环境变量支持的凭据）。`auth.oauth` 仅表示凭证存储配置文件健康状态；仅使用环境变量的提供商不会出现在其中。
- 使用 `--check` 进行自动化（缺失/已过期时退出 `1`，即将过期时退出 `2`）。
- 使用 `--probe` 进行实时凭证检查；探测行可以来自凭证配置文件、环境变量凭据或 `models.json`。
- 如果显式 `auth.order.<provider>` 省略了已存储的配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试使用它。如果存在凭证，但无法为该提供商解析可探测的模型，探测会报告 `status: no_model`。
- OAuth Status 始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **缺少凭证** 部分。
- JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效凭证，包括由环境变量支持的凭证）。`auth.oauth` 仅表示凭证存储配置文件健康状况；仅环境变量提供商不会出现在其中。
- 使用 `--check` 进行自动化（缺失/过期时退出 `1`，即将过期时退出 `2`）。
- 使用 `--probe` 进行实时凭证检查；探测行可以来自凭证配置文件、环境变量凭证或 `models.json`。
- 如果显式的 `auth.order.<provider>` 省略了已存储的配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果凭证存在但无法为该提供商解析出可探测模型，探测会报告 `status: no_model`。
</Accordion>
</AccordionGroup>
<Note>
凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API key 通常最可预测；也支持复用 Claude CLI 以及现有的 Anthropic OAuth/token 配置文件。
凭证选择取决于提供商/账号。对于常驻 Gateway 网关主机，API key 通常最可预测；也支持复用 Claude CLI 以及已有的 Anthropic OAuth/token 配置文件。
</Note>
示例（Claude CLI）：
@ -271,7 +271,7 @@ openclaw models status
## 扫描（OpenRouter 免费模型）
`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并且可以选择探测模型对工具和图像的支持。
`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型的工具和图像支持。
<ParamField path="--no-probe" type="boolean">
跳过实时探测（仅元数据）。
@ -289,14 +289,14 @@ openclaw models status
备用列表大小。
</ParamField>
<ParamField path="--set-default" type="boolean">
将 `agents.defaults.model.primary` 设为第一个选择。
将 `agents.defaults.model.primary` 设置为第一个选择项。
</ParamField>
<ParamField path="--set-image" type="boolean">
将 `agents.defaults.imageModel.primary` 设为第一个图像选择。
将 `agents.defaults.imageModel.primary` 设置为第一个图像选择项。
</ParamField>
<Note>
OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没有密钥的情况下列出免费候选项。探测和推理仍需要 OpenRouter API key（来自凭证配置文件或 `OPENROUTER_API_KEY`）。如果没有可用密钥，`openclaw models scan` 会回退到仅元数据输出，并保持配置不变。使用 `--no-probe` 可以显式请求仅元数据模式。
OpenRouter `/models` 目录是公开的，因此仅元数据扫描无需 key 即可列出免费候选项。探测和推理仍需要 OpenRouter API key（来自凭证配置文件或 `OPENROUTER_API_KEY`）。如果没有可用 key，`openclaw models scan` 会回退到仅元数据输出，并保持配置不变。使用 `--no-probe` 可显式请求仅元数据模式。
</Note>
扫描结果按以下顺序排名：
@ -313,36 +313,36 @@ OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没
- 可选过滤器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
- 请求/探测控制：`--timeout`、`--concurrency`
在 TTY 中运行实时探测时，你可以交互式选择备用模型。在非交互模式下，传入 `--yes` 以接受默认值。仅元数据结果仅供参考；`--set-default` 和 `--set-image` 需要实时探测，这样 OpenClaw 才不会配置无法使用的无密钥 OpenRouter 模型。
当实时探测在 TTY 中运行时，你可以交互式选择备用模型。在非交互模式下，传入 `--yes` 接受默认值。仅元数据结果只提供信息；`--set-default` 和 `--set-image` 需要实时探测，因此 OpenClaw 不会配置一个无法使用的无 key OpenRouter 模型。
## Models 注册表（`models.json`）
`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.openclaw/agents/<agentId>/agent/models.json`）。除非 `models.mode` 设为 `replace`，否则默认会合并此文件。
`models.providers` 中的自定义提供商会写入 Agent 目录下的 `models.json`（默认 `~/.openclaw/agents/<agentId>/agent/models.json`）。除非 `models.mode` 设置为 `replace`，否则默认会合并此文件。
<AccordionGroup>
<Accordion title="合并模式优先级">
匹配提供商 ID 时的合并模式优先级：
匹配提供商 ID 的合并模式优先级：
- 智能体 `models.json` 中已经存在的非空 `baseUrl` 优先。
- 智能体 `models.json` 中的非空 `apiKey` 仅在当前配置/凭证配置文件上下文中该提供商不是由 SecretRef 管理时优先。
- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`），而不是持久化解析后的密钥。
- 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`）。
- 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
- 其他提供商字段会从配置和规范化目录数据刷新。
- Agent `models.json` 中已有的非空 `baseUrl` 优先。
- Agent `models.json` 中的非空 `apiKey` 仅在该提供商未在当前配置/凭证配置文件上下文中由 SecretRef 管理时优先。
- 由 SecretRef 管理的提供商 `apiKey` 值会从来源标记刷新（环境变量引用为 `ENV_VAR_NAME`，文件/exec 引用为 `secretref-managed`），而不是持久化解析后的密钥。
- 由 SecretRef 管理的提供商标头值会从来源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，文件/exec 引用为 `secretref-managed`）。
- 空的或缺失的 Agent `apiKey`/`baseUrl` 会回退到配置 `models.providers`。
- 其他提供商字段会从配置和规范化后的目录数据刷新。
</Accordion>
</AccordionGroup>
<Note>
标记持久化以来源为准：OpenClaw 会从活动源配置快照（解析前）写入标记，而不是从解析后的运行时密钥值写入。只要 OpenClaw 重新生成 `models.json`，包括 `openclaw agent` 等命令驱动路径，都会应用此规则。
标记持久化以来源为权威：OpenClaw 会从活动来源配置快照（解析前）写入标记，而不是从解析后的运行时密钥值写入。只要 OpenClaw 重新生成 `models.json`，这都会适用，包括像 `openclaw agent` 这样的命令驱动路径。
</Note>
## 相关内容
## 相关
- [Agent Runtimes](/zh-CN/concepts/agent-runtimes) — PI、Codex 和其他 Agent loop 运行时
- [Agent Runtimes](/zh-CN/concepts/agent-runtimes) — PI、Codex 以及其他 Agent loop 运行时
- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键
- [图像生成](/zh-CN/tools/image-generation) — 图像模型配置
- [模型故障切换](/zh-CN/concepts/model-failover) — 备用链
- [模型故障转移](/zh-CN/concepts/model-failover) — 备用链
- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由和凭证
- [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置
- [视频生成](/zh-CN/tools/video-generation) — 视频模型配置

344
docs/zh-CN/gateway/doctor.md
View File

@ -6,15 +6,15 @@ sidebarTitle: Doctor
summary: Doctor 命令：健康检查、配置迁移和修复步骤
title: Doctor
x-i18n:
generated_at: "2026-05-01T21:49:50Z"
generated_at: "2026-05-02T02:37:09Z"
model: gpt-5.5
provider: openai
source_hash: bbcac6787b25db196dfc6bf7afc44afc26e9b19d219106c407e32e1d090c2344
source_hash: ff4ab00fd6a11588abe790350fe139bc49f61e688bcd741389dd63732aa4430c
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的配置/状态，检查健康状况，并提供可执行的修复步骤。
`openclaw doctor` 是 OpenClaw 的修复 + 迁移工具。它会修复过时的配置/状态、检查健康状况，并提供可执行的修复步骤。
## 快速开始
@ -22,7 +22,7 @@ x-i18n:
openclaw doctor
```
### 无头模式和自动化模式
### 无头和自动化模式
<Tabs>
<Tab title="--yes">
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
不提示即接受默认值（包括适用时的重启/服务/沙箱修复步骤）。
不提示直接接受默认值（适用时包括重启/服务/沙箱修复步骤）。
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
不提示即应用推荐修复（在安全时执行修复 + 重启）。
不提示直接应用推荐的修复（在安全情况下执行修复 + 重启）。
</Tab>
<Tab title="--repair --force">
@ -46,7 +46,7 @@ openclaw doctor
openclaw doctor --repair --force
```
同时应用激进修复（会覆盖自定义 supervisor 配置）。
也应用激进修复（会覆盖自定义 supervisor 配置）。
</Tab>
<Tab title="--non-interactive">
@ -62,12 +62,12 @@ openclaw doctor
openclaw doctor --deep
```
扫描系统服务以查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。
扫描系统服务，查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。
</Tab>
</Tabs>
如果你想在写入前查看更改，请先打开配置文件：
如果你想在写入前查看变更，请先打开配置文件：
```bash
cat ~/.openclaw/openclaw.json
@ -77,61 +77,61 @@ cat ~/.openclaw/openclaw.json
<AccordionGroup>
<Accordion title="健康状况、UI 和更新">
- 对 git 安装执行可选的预检更新（仅限交互式）。
- git 安装的可选预检更新（仅交互模式）。
- UI 协议新鲜度检查（当协议 schema 更新时重建 Control UI）。
- 健康检查 + 重启提示。
- Skills 状态摘要（符合条件/缺失/被阻止）和插件状态。
- Skills 状态摘要（符合条件/缺失/受阻）和插件状态。
</Accordion>
<Accordion title="配置和迁移">
- 对旧版值进行配置规范化。
- 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.<provider>` Talk 配置。
- 检查旧版 Chrome 扩展配置的浏览器迁移和 Chrome MCP 就绪状态。
- 旧版值的配置规范化。
- 将旧版扁平 `talk.*` 字段迁移为 `talk.provider` + `talk.providers.<provider>` 的 Talk 配置迁移。
- 旧版 Chrome 扩展配置和 Chrome MCP 就绪状态的浏览器迁移检查。
- OpenCode 提供商覆盖警告（`models.providers.opencode` / `models.providers.opencode-go`）。
- Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。
- OpenAI Codex OAuth 配置文件的 OAuth TLS 前置条件检查。
- 当 `plugins.allow` 具有限制性但工具策略仍要求通配符或插件拥有的工具时，显示插件/工具 allowlist 警告。
- 旧版磁盘状态迁移（会话/智能体目录/WhatsApp 凭证）。
- 旧版插件清单契约键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单 `notify: true` webhook 回退任务）。
- 旧版 Agent Runtime 策略迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。
- 插件启用时清理过期插件配置；当 `plugins.enabled=false` 时，过期插件引用会被视为惰性隔离配置并保留。
- 当 `plugins.allow` 具有限制性但工具策略仍请求通配符或插件拥有的工具时，发出插件/工具 allowlist 警告。
- 旧版磁盘状态迁移（会话/agent 目录/WhatsApp 身份验证）。
- 旧版插件 manifest contract 键迁移（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders` → `contracts`）。
- 旧版 cron 存储迁移（`jobId`、`schedule.cron`、顶层 delivery/payload 字段、payload `provider`、简单的 `notify: true` webhook 回退作业）。
- 旧版 Agent 运行时策略迁移到 `agents.defaults.agentRuntime` 和 `agents.list[].agentRuntime`。
- 插件启用时清理过时插件配置；当 `plugins.enabled=false` 时，过时插件引用会被视为惰性隔离配置并被保留。
</Accordion>
<Accordion title="状态和完整性">
- 会话锁文件检查和过期锁清理。
- 修复受影响 2026.4.24 构建创建的重复 prompt-rewrite 分支的会话转录。
- 卡住的子智能体重启恢复 tombstone 检测，并支持使用 `--fix` 清除过期的已中止恢复标记，避免启动时继续将子项视为重启已中止。
- 会话锁文件检查和过时锁清理。
- 修复受影响的 2026.4.24 构建创建的重复 prompt-rewrite 分支的会话转录。
- 卡住的子 agent 重启恢复墓碑检测，并支持使用 `--fix` 清除过时的已中止恢复标志，让启动不再持续把该子项视为重启已中止。
- 状态完整性和权限检查（会话、转录、状态目录）。
- 本地运行时的配置文件权限检查（chmod 600）。
- 模型凭证健康状况：检查 OAuth 过期时间，可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。
- 模型身份验证健康状况：检查 OAuth 过期时间，可刷新即将过期的令牌，并报告 auth-profile 冷却/禁用状态。
- 额外工作区目录检测（`~/openclaw`）。
</Accordion>
<Accordion title="Gateway 网关、服务和 supervisor">
<Accordion title="Gateway 网关、服务和 supervisors">
- 启用沙箱隔离时修复沙箱镜像。
- 旧版服务迁移和额外 Gateway 网关检测。
- Matrix 渠道旧版状态迁移（在 `--fix` / `--repair` 模式下）。
- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd label）。
- 渠道状态警告（从正在运行的 Gateway 网关探测）。
- supervisor 配置审计（launchd/systemd/schtasks），带可选修复。
- supervisor 配置审计（launchd/systemd/schtasks），可选修复。
- 清理 Gateway 网关服务的嵌入式代理环境，这些服务在安装或更新期间捕获了 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值。
- Gateway 网关运行时最佳实践检查（Node 与 Bun、版本管理器路径）。
- Gateway 网关端口冲突诊断（默认 `18789`）。
</Accordion>
<Accordion title="凭证、安全和配对">
- 对开放私信策略的安全警告。
- local token 模式的 Gateway 网关凭证检查（在不存在令牌来源时提供令牌生成；不会覆盖 token SecretRef 配置）。
- 设备配对问题检测（待处理的首次配对请求、待处理的角色/范围升级、过期的本地 device-token 缓存漂移，以及 paired-record 凭证漂移）。
<Accordion title="身份验证、安全和配对">
- 开放私信策略的安全警告。
- local token 模式的 Gateway 网关身份验证检查（无 token 来源时提供 token 生成；不会覆盖 token SecretRef 配置）。
- 设备配对问题检测（待处理的首次配对请求、待处理的角色/范围升级、过时的本地 device-token 缓存漂移，以及已配对记录的身份验证漂移）。
</Accordion>
<Accordion title="工作区和 shell">
- Linux 上的 systemd linger 检查。
- 工作区 bootstrap 文件大小检查（上下文文件截断/接近限制警告）。
- shell 补全状态检查和自动安装/升级。
- 记忆搜索 embedding 提供商就绪状态检查（本地模型、远程 API key 或 QMD 二进制文件）。
- 源码安装检查（pnpm 工作区不匹配、缺少 UI 资产、缺少 tsx 二进制文件）。
- 工作区 bootstrap 文件大小检查（上下文文件的截断/接近限制警告）。
- Shell 补全状态检查和自动安装/升级。
- 记忆搜索嵌入提供商就绪状态检查（本地模型、远程 API key 或 QMD binary）。
- 源码安装检查（pnpm 工作区不匹配、缺少 UI assets、缺少 tsx binary）。
- 写入更新后的配置 + 向导元数据。
</Accordion>
@ -139,52 +139,52 @@ cat ~/.openclaw/openclaw.json
## Dreams UI 回填和重置
Control UI Dreams 场景包含用于 grounded dreaming 工作流的 **Backfill**、**Reset** 和 **Clear Grounded** 操作。这些操作使用 Gateway 网关 doctor 风格的 RPC 方法，但它们**不是** `openclaw doctor` CLI 修复/迁移的一部分。
Control UI 的 Dreams 场景包含 **Backfill**、**Reset** 和 **Clear Grounded** 操作，用于 grounded dreaming 工作流。这些操作使用 Gateway 网关 doctor 风格的 RPC 方法，但它们**不**属于 `openclaw doctor` CLI 修复/迁移。
它们会做什么：
- **Backfill** 会扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM diary pass，并将可逆的回填条目写入 `DREAMS.md`。
- **Reset** 只会从 `DREAMS.md` 中移除这些标记的回填日记条目。
- **Clear Grounded** 只会移除来自历史重放、且尚未积累实时回忆或每日支持的暂存 grounded-only 短期条目。
- **Backfill** 扫描活动工作区中的历史 `memory/YYYY-MM-DD.md` 文件，运行 grounded REM 日记流程，并将可逆回填条目写入 `DREAMS.md`。
- **Reset** 只从 `DREAMS.md` 中移除那些标记过的回填日记条目。
- **Clear Grounded** 只移除来自历史回放、且尚未积累实时回忆或日常支持的 staged grounded-only 短期条目。
它们本身**不会**做什么：
- 它们不会编辑 `MEMORY.md`
- 它们不会运行完整的 doctor 迁移
- 除非你先显式运行暂存 CLI 路径，否则它们不会自动把 grounded 候选项暂存到实时短期提升存储中
- 它们不会运行完整 doctor 迁移
- 除非你先显式运行 staged CLI 路径，否则它们不会自动将 grounded 候选项暂存到实时短期提升存储
如果你希望 grounded 历史重放影响正常的深度提升通道，请改用 CLI 流程：
如果你希望 grounded 历史回放影响正常的深度提升通道，请改用 CLI 流程：
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
这会将 grounded durable 候选项暂存到短期 dreaming 存储中，同时把 `DREAMS.md` 保持为 review surface。
这会将 grounded durable 候选项暂存到短期 dreaming 存储中，同时让 `DREAMS.md` 保持为审查界面。
## 详细行为和原因
## 详细行为和设计理由
<AccordionGroup>
<Accordion title="0. 可选更新（git 安装）">
如果这是 git checkout 且 doctor 正在交互式运行，它会在运行 doctor 前提供更新（fetch/rebase/build）选项。
如果这是 git checkout 且 doctor 正在交互运行，它会先询问是否更新（fetch/rebase/build），然后再运行 doctor。
</Accordion>
<Accordion title="1. 配置规范化">
如果配置包含旧版值形态（例如没有渠道专属覆盖的 `messages.ackReaction`），doctor 会将其规范化为当前 schema。
如果配置包含旧版值形状（例如没有特定渠道覆盖的 `messages.ackReaction`），doctor 会将其规范化为当前 schema。
这包括旧版 Talk 扁平字段。当前公开 Talk 配置是 `talk.provider` + `talk.providers.<provider>`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形态重写到提供商 map 中。
这包括旧版 Talk 扁平字段。当前公开 Talk 配置是 `talk.provider` + `talk.providers.<provider>`。Doctor 会将旧的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形状重写进提供商映射。
当 `plugins.allow` 非空且工具策略使用通配符或插件拥有的工具条目时，Doctor 也会发出警告。`tools.allow: ["*"]` 只匹配实际加载的插件中的工具；它不会绕过排他的插件 allowlist。
</Accordion>
<Accordion title="2. 旧版配置键迁移">
当配置包含已弃用的键时，其他命令会拒绝运行并要求你运行 `openclaw doctor`。
当配置包含已废弃键时，其他命令会拒绝运行，并要求你运行 `openclaw doctor`。
Doctor 会：
- 说明发现了哪些旧版键。
- 解释发现了哪些旧版键。
- 显示它应用的迁移。
- 用更新后的 schema 重写 `~/.openclaw/openclaw.json`。
- 使用更新后的 schema 重写 `~/.openclaw/openclaw.json`。
Gateway 网关在启动时检测到旧版配置格式时，也会自动运行 doctor 迁移，因此过期配置无需人工介入即可修复。Cron 任务存储迁移由 `openclaw doctor --fix` 处理。
Gateway 网关在启动时检测到旧版配置格式时，也会自动运行 doctor 迁移，因此过时配置无需人工介入即可修复。Cron 作业存储迁移由 `openclaw doctor --fix` 处理。
当前迁移：
@ -209,26 +209,26 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- 对于有命名 `accounts` 但仍残留单账户顶层渠道值的渠道，将这些账户作用域的值移入为该渠道选定的提升账户（大多数渠道使用 `accounts.default`；Matrix 可以保留现有匹配的命名/默认目标）
- 对于带有命名 `accounts` 但仍残留单账号顶层渠道值的渠道，将这些账号作用域值移入为该渠道选出的提升账号（多数渠道为 `accounts.default`；Matrix 可以保留现有匹配的命名/默认目标）
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*`（工具/提权/执行/沙箱/子智能体）
- `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents）
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- 移除 `agents.defaults.llm`；对较慢的提供商/模型超时使用 `models.providers.<id>.timeoutSeconds`
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- 移除 `browser.relayBindHost`（旧版扩展中继设置）
- 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 设为未来或未知枚举值的提供商，而不是关闭失败）
- 旧版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 网关启动时也会跳过 `api` 被设为未来或未知枚举值的提供商，而不是按失败关闭处理）
Doctor 警告还包括多账户渠道的账户默认值指引：
Doctor 警告还包括多账号渠道的账号默认值指导：
- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有 `channels.<channel>.defaultAccount` 或 `accounts.default`，Doctor 会警告回退路由可能选择意外账户。
- 如果 `channels.<channel>.defaultAccount` 设为未知账户 ID，Doctor 会警告并列出已配置的账户 ID。
- 如果配置了两个或更多 `channels.<channel>.accounts` 条目，但没有 `channels.<channel>.defaultAccount` 或 `accounts.default`，Doctor 会警告回退路由可能选中意外账号。
- 如果 `channels.<channel>.defaultAccount` 设置为未知账号 ID，Doctor 会警告并列出已配置的账号 ID。
</Accordion>
<Accordion title="2b. OpenCode provider overrides">
如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型使用错误的 API，或将成本清零。Doctor 会发出警告，这样你就可以移除覆盖项，并恢复每个模型的 API 路由和成本。
<Accordion title="2b. OpenCode 提供商覆盖">
如果你手动添加了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它会覆盖来自 `@mariozechner/pi-ai` 的内置 OpenCode 目录。这可能会强制模型使用错误 API，或把成本清零。Doctor 会发出警告，这样你就可以移除覆盖并恢复按模型配置的 API 路由和成本。
</Accordion>
<Accordion title="2c. Browser migration and Chrome MCP readiness">
<Accordion title="2c. 浏览器迁移和 Chrome MCP 就绪检查">
如果你的浏览器配置仍指向已移除的 Chrome 扩展路径，Doctor 会将其规范化为当前的主机本地 Chrome MCP 附加模型：
- `browser.profiles.*.driver: "extension"` 变为 `"existing-session"`
@ -236,262 +236,262 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
当你使用 `defaultProfile: "user"` 或已配置的 `existing-session` 配置文件时，Doctor 还会审计主机本地 Chrome MCP 路径：
- 检查同一主机上是否安装了 Google Chrome，用于默认自动连接配置文件
- 检查检测到的 Chrome 版本，并在低于 Chrome 144 时警告
- 提醒你在浏览器检查页面启用远程调试（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
- 检查同一主机上是否已安装 Google Chrome，以用于默认自动连接配置文件
- 检查检测到的 Chrome 版本，并在低于 Chrome 144 时发出警告
- 提醒你在浏览器 inspect 页面启用远程调试（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
Doctor 无法替你启用 Chrome 端设置。主机本地 Chrome MCP 仍要求：
Doctor 无法替你启用 Chrome 端设置。主机本地 Chrome MCP 仍需要：
- Gateway 网关/节点主机上有基于 Chromium 的浏览器 144+
- 浏览器在本地运行
- 该浏览器中已启用远程调试
- 在浏览器中批准首次附加同意提示
- 该浏览器已启用远程调试
- 在浏览器中批准第一次附加同意提示
这里的就绪状态只涉及本地附加前置条件。Existing-session 会保留当前 Chrome MCP 路由限制；`responsebody`、PDF 导出、下载拦截和批量操作等高级路由仍需要托管浏览器或原始 CDP 配置文件。
这里的就绪检查只涉及本地附加前置条件。Existing-session 会保留当前 Chrome MCP 路由限制；`responsebody`、PDF 导出、下载拦截和批量操作等高级路由仍需要托管浏览器或原始 CDP 配置文件。
此检查**不**适用于 Docker、沙箱、远程浏览器或其他无头流程。它们会继续使用原始 CDP。
此检查**不**适用于 Docker、沙箱、远程浏览器或其他无头流程。它们继续使用原始 CDP。
</Accordion>
<Accordion title="2d. OAuth TLS prerequisites">
配置 OpenAI Codex OAuth 配置文件后，Doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈能否验证证书链。如果探测因证书错误失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），Doctor 会打印平台特定的修复指引。在使用 Homebrew Node 的 macOS 上，修复方式通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，也会运行该探测。
<Accordion title="2d. OAuth TLS 前置条件">
配置 OpenAI Codex OAuth 配置文件时，Doctor 会探测 OpenAI 授权端点，以验证本地 Node/OpenSSL TLS 栈能否验证证书链。如果探测因证书错误而失败（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、证书过期或自签名证书），Doctor 会打印平台特定的修复指导。在使用 Homebrew Node 的 macOS 上，修复通常是 `brew postinstall ca-certificates`。使用 `--deep` 时，即使 Gateway 网关健康，也会运行该探测。
</Accordion>
<Accordion title="2e. Codex OAuth provider overrides">
如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽新版本自动使用的内置 Codex OAuth 提供商路径。当 Doctor 看到这些旧传输设置与 Codex OAuth 并存时会发出警告，这样你就可以移除或重写过时的传输覆盖项，并恢复内置路由/回退行为。自定义代理和仅标头覆盖仍受支持，且不会触发此警告。
<Accordion title="2e. Codex OAuth 提供商覆盖">
如果你之前在 `models.providers.openai-codex` 下添加了旧版 OpenAI 传输设置，它们可能会遮蔽较新版本自动使用的内置 Codex OAuth 提供商路径。Doctor 在看到这些旧传输设置与 Codex OAuth 同时存在时会发出警告，这样你就可以移除或重写过期的传输覆盖，并恢复内置路由/回退行为。自定义代理和仅标头覆盖仍受支持，并且不会触发此警告。
</Accordion>
<Accordion title="2f. Codex plugin route warnings">
启用内置 Codex 插件后，Doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI 运行器解析。当你想通过 PI 使用 Codex OAuth/订阅认证时，这种组合是有效的，但它很容易与原生 Codex 应用服务器 harness 混淆。Doctor 会发出警告，并指向显式应用服务器形态：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
<Accordion title="2f. Codex 插件路由警告">
启用内置 Codex 插件时，Doctor 还会检查 `openai-codex/*` 主模型引用是否仍通过默认 PI runner 解析。当你想通过 PI 使用 Codex OAuth/订阅凭证时，这种组合是有效的，但它很容易与原生 Codex app-server harness 混淆。Doctor 会警告并指向显式 app-server 形态：`openai/*` 加 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
Doctor 不会自动修复这一点，因为两条路由都有效：
Doctor 不会自动修复它，因为两条路由都有效：
- `openai-codex/*` + PI 表示“通过正常的 OpenClaw 运行器使用 Codex OAuth/订阅认证。”
- `openai/*` + `runtime: "codex"` 表示“通过原生 Codex 应用服务器运行嵌入回合。”
- `openai-codex/*` + PI 表示“通过普通 OpenClaw runner 使用 Codex OAuth/订阅凭证。”
- `openai/*` + `agentRuntime.id: "codex"` 表示“通过原生 Codex app-server 运行嵌入式轮次。”
- `/codex ...` 表示“从聊天中控制或绑定原生 Codex 对话。”
- `/acp ...` 或 `runtime: "acp"` 表示“使用外部 ACP/acpx 适配器。”
如果出现该警告，请选择你原本想使用的路由并手动编辑配置。当 PI Codex OAuth 是有意配置时，保留该警告不变。
如果出现该警告，请选择你原本想用的路由并手动编辑配置。当 PI Codex OAuth 是有意设置时，请保持该警告不变。
</Accordion>
<Accordion title="3. Legacy state migrations (disk layout)">
<Accordion title="3. 旧版状态迁移（磁盘布局）">
Doctor 可以将较旧的磁盘布局迁移到当前结构：
- 会话存储 + 转录记录：
- 从 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
- Agent 目录：
- 从 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
- WhatsApp 认证状态（Baileys）：
- 从旧版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
- 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账户 ID：`default`）
- WhatsApp 凭证状态（Baileys）：
- 从旧版 `~/.openclaw/credentials/*.json`（不包括 `oauth.json`）
- 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（默认账号 ID：`default`）
这些迁移是尽力而为且幂等的；当 Doctor 将任何旧版文件夹作为备份保留下来时，会发出警告。Gateway 网关/CLI 启动时也会自动迁移旧版会话和 Agent 目录，因此历史记录/认证/模型会进入按 Agent 划分的路径，无需手动运行 Doctor。WhatsApp 认证被有意设计为只通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在会按结构相等性比较，因此仅键顺序不同的差异不再触发重复的空操作 `doctor --fix` 变更。
这些迁移会尽力执行并且可重复运行；当 Doctor 将任何旧版文件夹作为备份保留下来时，它会发出警告。Gateway 网关/CLI 在启动时也会自动迁移旧版会话和 Agent 目录，因此历史记录、凭证和模型会落到按 Agent 划分的路径中，不需要手动运行 Doctor。WhatsApp 凭证有意只通过 `openclaw doctor` 迁移。Talk 提供商/提供商映射规范化现在会按结构相等性比较，因此仅键顺序不同的差异不再触发重复的空操作 `doctor --fix` 变更。
</Accordion>
<Accordion title="3a. Legacy plugin manifest migrations">
Doctor 会扫描所有已安装插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到后，它会提议将它们移入 `contracts` 对象，并原地重写清单文件。此迁移是幂等的；如果 `contracts` 键已有相同值，则会移除旧版键，而不会复制数据。
<Accordion title="3a. 旧版插件清单迁移">
Doctor 会扫描所有已安装插件清单，查找已弃用的顶层能力键（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。发现后，它会提议将它们移入 `contracts` 对象，并就地重写清单文件。此迁移可重复运行；如果 `contracts` 键中已有相同值，则会移除旧版键，而不会复制数据。
</Accordion>
<Accordion title="3b. Legacy cron store migrations">
Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或覆盖后的 `cron.store`），查找调度器仍为兼容性接受的旧作业形态。
<Accordion title="3b. 旧版 cron 存储迁移">
Doctor 还会检查 cron 作业存储（默认是 `~/.openclaw/cron/jobs.json`，或被覆盖时的 `cron.store`），查找调度器仍为兼容性接受的旧作业形态。
当前 cron 清理包括：
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- 顶层载荷字段（`message`、`model`、`thinking`、...）→ `payload`
- 顶层投递字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
- 载荷 `provider` 投递别名 → 显式 `delivery.channel`
- 简单旧版 `notify: true` webhook 回退作业 → 显式 `delivery.mode="webhook"`，并带有 `delivery.to=cron.webhook`
- 顶层 payload 字段（`message`、`model`、`thinking`、...）→ `payload`
- 顶层 delivery 字段（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
- payload `provider` 递送别名 → 显式 `delivery.channel`
- 简单旧版 `notify: true` webhook 回退作业 → 显式 `delivery.mode="webhook"` 并设置 `delivery.to=cron.webhook`
Doctor 只有在不会改变行为时，才会自动迁移 `notify: true` 作业。如果某个作业将旧版通知回退与现有非 webhook 投递模式组合使用，Doctor 会警告并留下该作业供手动审查。
Doctor 只有在不改变行为的情况下才会自动迁移 `notify: true` 作业。如果某个作业把旧版通知回退与现有非 webhook 递送模式组合在一起，Doctor 会警告并保留该作业以供手动审核。
在 Linux 上，当用户的 crontab 仍调用旧版 `~/.openclaw/bin/ensure-whatsapp.sh` 时，Doctor 也会警告。当前 OpenClaw 不维护该主机本地脚本，并且当 cron 无法访问 systemd 用户总线时，它可能会将错误的 `Gateway inactive` 消息写入 `~/.openclaw/logs/whatsapp-health.log`。使用 `crontab -e` 移除过时的 crontab 条目；当前健康检查请使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status`。
在 Linux 上，如果用户的 crontab 仍调用旧版 `~/.openclaw/bin/ensure-whatsapp.sh`，Doctor 也会发出警告。当前 OpenClaw 不维护这个主机本地脚本，并且当 cron 无法访问 systemd user bus 时，它可能会向 `~/.openclaw/logs/whatsapp-health.log` 写入错误的 `Gateway inactive` 消息。使用 `crontab -e` 移除过期的 crontab 条目；当前健康检查请使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status`。
</Accordion>
<Accordion title="3c. 会话锁清理">
Doctor 会扫描每个智能体会话目录，查找陈旧的写入锁文件 —— 也就是会话异常退出时留下的文件。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍然存活、锁存在时间，以及是否被视为陈旧（PID 已死亡或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动删除陈旧锁文件；否则会打印说明，并指示你使用 `--fix` 重新运行。
Doctor 会扫描每个智能体会话目录，查找过期的写入锁文件，即会话异常退出后留下的文件。对于找到的每个锁文件，它会报告：路径、PID、PID 是否仍然存活、锁的存在时长，以及是否被视为过期（PID 已终止或超过 30 分钟）。在 `--fix` / `--repair` 模式下，它会自动移除过期锁文件；否则会打印一条提示，并指示你使用 `--fix` 重新运行。
</Accordion>
<Accordion title="3d. 会话转录分支修复">
Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 提示转录重写 bug 创建的重复分支形态：一个已弃用的用户轮次，包含 OpenClaw 内部运行时上下文，旁边还有一个包含相同可见用户提示的活跃同级分支。在 `--fix` / `--repair` 模式下，doctor 会在原文件旁边备份每个受影响文件，并将转录重写为活跃分支，这样 Gateway 网关历史和记忆读取器就不会再看到重复轮次。
Doctor 会扫描智能体会话 JSONL 文件，查找由 2026.4.24 提示词转录重写 bug 创建的重复分支形态：一个包含 OpenClaw 内部运行时上下文的废弃用户轮次，以及一个包含相同可见用户提示词的活跃同级分支。在 `--fix` / `--repair` 模式下，Doctor 会在原文件旁备份每个受影响文件，并将转录重写到活跃分支，使 Gateway 网关历史记录和记忆读取器不再看到重复轮次。
</Accordion>
<Accordion title="4. 状态完整性检查（会话持久化、路由和安全）">
状态目录是操作层面的中枢。如果它消失，你会丢失会话、凭证、日志和配置（除非你在其他位置有备份）。
状态目录是运行层面的中枢。如果它消失，你会丢失会话、凭证、日志和配置（除非你在别处有备份）。
Doctor 会检查：
- **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒你它无法恢复缺失数据。
- **状态目录权限**：验证可写性；提供修复权限的选项（检测到所有者/组不匹配时会发出 `chown` 提示）。
- **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为同步支持的路径可能导致 I/O 变慢以及锁/同步竞争。
- **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为 SD 或 eMMC 支持的随机 I/O 在会话和凭证写入下可能更慢，并且磨损更快。
- **会话目录缺失**：需要 `sessions/` 和会话存储目录来持久化历史并避免 `ENOENT` 崩溃。
- **状态目录权限**：验证可写性；提供修复权限的选项（并在检测到所有者/组不匹配时输出 `chown` 提示）。
- **macOS 云同步状态目录**：当状态解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 下时发出警告，因为同步支持的路径可能导致更慢的 I/O 以及锁/同步竞争。
- **Linux SD 或 eMMC 状态目录**：当状态解析到 `mmcblk*` 挂载源时发出警告，因为 SD 或 eMMC 支持的随机 I/O 在会话和凭证写入下可能更慢且磨损更快。
- **会话目录缺失**：`sessions/` 和会话存储目录是持久保存历史记录并避免 `ENOENT` 崩溃所必需的。
- **转录不匹配**：当最近的会话条目缺少转录文件时发出警告。
- **主会话“1 行 JSONL”**：当主转录只有一行时标记（历史未累积）。
- **多个状态目录**：当多个主目录中存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史可能在多个安装之间分裂）。
- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态存储在那里）。
- **主会话“1 行 JSONL”**：当主转录只有一行时标记（历史记录没有持续累积）。
- **多个状态目录**：当多个主目录下存在多个 `~/.openclaw` 文件夹，或 `OPENCLAW_STATE_DIR` 指向其他位置时发出警告（历史记录可能在不同安装之间拆分）。
- **远程模式提醒**：如果 `gateway.mode=remote`，Doctor 会提醒你在远程主机上运行它（状态保存在那里）。
- **配置文件权限**：如果 `~/.openclaw/openclaw.json` 可被组/所有人读取，则发出警告，并提供收紧到 `600` 的选项。
</Accordion>
<Accordion title="5. 模型认证健康状况（OAuth 过期）">
Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已陈旧，它会建议使用 Anthropic API key 或 Anthropic 设置令牌路径。刷新提示仅在交互式运行（TTY）时出现；`--non-interactive` 会跳过刷新尝试。
<Accordion title="5. 模型认证健康状态（OAuth 过期）">
Doctor 会检查认证存储中的 OAuth 配置文件，在令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic OAuth/令牌配置文件已过期，它会建议使用 Anthropic API key 或 Anthropic 设置令牌路径。刷新提示只会在交互式运行（TTY）时出现；`--non-interactive` 会跳过刷新尝试。
当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商要求你重新登录），doctor 会报告需要重新认证，并打印要运行的精确 `openclaw models auth login --provider ...` 命令。
当 OAuth 刷新永久失败时（例如 `refresh_token_reused`、`invalid_grant`，或提供商要求你重新登录），Doctor 会报告需要重新认证，并打印要运行的确切 `openclaw models auth login --provider ...` 命令。
Doctor 还会报告由于以下原因暂时不可用的认证配置文件：
- 短暂冷却（速率限制/超时/认证失败）
- 更长时间的禁用（账单/额度失败）
- 更长时间的停用（账单/额度失败）
</Accordion>
<Accordion title="6. 钩子模型验证">
如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在无法解析或不被允许时发出警告。
如果设置了 `hooks.gmail.model`，Doctor 会根据目录和允许列表验证模型引用，并在其无法解析或不被允许时发出警告。
</Accordion>
<Accordion title="7. 沙箱镜像修复">
启用沙箱隔离时，doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧名称的选项。
启用沙箱隔离后，Doctor 会检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到旧名称的选项。
</Accordion>
<Accordion title="7b. 插件安装清理">
Doctor 会在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下删除旧版 OpenClaw 生成的插件依赖暂存状态。这包括陈旧的生成依赖根目录、旧安装阶段目录，以及早期内置插件依赖修复代码留下的包本地残留。
Doctor 会在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下移除旧版 OpenClaw 生成的插件依赖暂存状态。这涵盖过期的生成依赖根、旧安装阶段目录，以及早期内置插件依赖修复代码留下的包本地残留。
当配置引用了可下载插件但本地插件注册表找不到它们时，Doctor 也可以重新安装已配置的可下载插件。Gateway 网关启动和配置重新加载不会运行包管理器；插件安装仍然是显式的 doctor/install/update 工作。
当配置引用了可下载插件但本地插件注册表找不到它们时，Doctor 也可以重新安装已配置的可下载插件。Gateway 网关启动和配置重新加载不会运行包管理器；插件安装仍然是显式的 Doctor/安装/更新工作。
</Accordion>
<Accordion title="8. Gateway 网关服务迁移和清理提示">
Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供删除它们并使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关的服务并打印清理提示。带配置文件名称的 OpenClaw Gateway 网关服务被视为一等服务，不会被标记为“额外”。
Doctor 会检测旧版 Gateway 网关服务（launchd/systemd/schtasks），并提供移除它们以及使用当前 Gateway 网关端口安装 OpenClaw 服务的选项。它还可以扫描额外的类似 Gateway 网关的服务并打印清理提示。带配置文件名称的 OpenClaw Gateway 网关服务被视为一等服务，不会被标记为“额外”。
在 Linux 上，如果缺少用户级 Gateway 网关服务，但存在系统级 OpenClaw Gateway 网关服务，doctor 不会自动安装第二个用户级服务。请使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 检查，然后删除重复项，或在系统监督器拥有 Gateway 网关生命周期时设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
在 Linux 上，如果缺少用户级 Gateway 网关服务，但存在系统级 OpenClaw Gateway 网关服务，Doctor 不会自动安装第二个用户级服务。请用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 检查，然后移除重复项；如果系统监督进程拥有 Gateway 网关生命周期，则设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
</Accordion>
<Accordion title="8b. 启动 Matrix 迁移">
当 Matrix 渠道账号有待处理或可执行的旧版状态迁移时，doctor（在 `--fix` / `--repair` 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都是非致命的；错误会被记录，启动会继续。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。
当 Matrix 渠道账户有待处理或可执行的旧状态迁移时，Doctor（在 `--fix` / `--repair` 模式下）会创建迁移前快照，然后运行尽力而为的迁移步骤：旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤都不是致命的；错误会被记录，启动会继续。在只读模式（不带 `--fix` 的 `openclaw doctor`）下，此检查会被完全跳过。
</Accordion>
<Accordion title="8c. 设备配对和认证漂移">
Doctor 现在会将设备配对状态作为常规健康检查的一部分进行检查。
Doctor 现在会在常规健康检查中检查设备配对状态。
它报告的内容：
- 待处理的首次配对请求
- 已配对设备的待处理角色升级
- 已配对设备的待处理范围升级
- 公钥不匹配修复，其中设备 ID 仍匹配，但设备身份不再匹配已批准记录
- 已配对记录缺少已批准角色的活跃令牌
- 已配对令牌的范围漂移到已批准配对基线之外
- 当前机器的本地缓存设备令牌条目早于 Gateway 网关端令牌轮换，或携带陈旧的范围元数据
- 设备 id 仍然匹配但设备身份不再匹配已批准记录的公钥不匹配修复
- 缺少已批准角色的活跃令牌的配对记录
- 范围漂移到已批准配对基线之外的配对令牌
- 当前机器的本地缓存设备令牌条目，早于 Gateway 网关侧令牌轮换，或携带过期范围元数据
Doctor 不会自动批准配对请求或自动轮换设备令牌。它会改为打印精确的后续步骤：
Doctor 不会自动批准配对请求，也不会自动轮换设备令牌。它会改为打印确切的后续步骤：
- 使用 `openclaw devices list` 检查待处理请求
- 使用 `openclaw devices approve <requestId>` 批准精确请求
- 使用 `openclaw devices approve <requestId>` 批准确切请求
- 使用 `openclaw devices rotate --device <deviceId> --role <role>` 轮换新令牌
- 使用 `openclaw devices remove <deviceId>` 删除并重新批准陈旧记录
- 使用 `openclaw devices remove <deviceId>` 移除并重新批准过期记录
这修复了常见的“已配对但仍要求配对”缺口：doctor 现在会区分首次配对、待处理的角色/范围升级，以及陈旧令牌/设备身份漂移。
这弥补了常见的“已经配对但仍收到需要配对”缺口：Doctor 现在会区分首次配对、待处理的角色/范围升级，以及过期令牌/设备身份漂移。
</Accordion>
<Accordion title="9. 安全警告">
当提供商在没有允许列表的情况下对私信开放，或策略以危险方式配置时，Doctor 会发出警告。
</Accordion>
<Accordion title="10. systemd linger（Linux）">
如果作为 systemd 用户服务运行，doctor 会确保已启用 linger，使 Gateway 网关在注销后仍保持运行。
如果作为 systemd 用户服务运行，Doctor 会确保启用 linger，使 Gateway 网关在登出后仍保持运行。
</Accordion>
<Accordion title="11. 工作区状态（Skills、插件和旧版目录）">
<Accordion title="11. 工作区状态（Skills、插件和旧目录）">
Doctor 会打印默认智能体的工作区状态摘要：
- **Skills 状态**：统计符合条件、缺少要求和被允许列表阻止的 skills。
- **Skills 状态**：统计符合条件、缺少要求以及被允许列表阻止的 Skills。
- **旧版工作区目录**：当 `~/openclaw` 或其他旧版工作区目录与当前工作区并存时发出警告。
- **插件状态**：统计已启用/已禁用/出错的插件；列出任何错误的插件 ID；报告包插件能力。
- **插件状态**：统计已启用/已禁用/出错的插件；列出所有错误对应的插件 ID；报告捆绑插件能力。
- **插件兼容性警告**：标记与当前运行时存在兼容性问题的插件。
- **插件诊断**：显示插件注册表在加载时发出的任何警告或错误。
- **插件诊断**：显示插件注册表在加载时输出的任何警告或错误。
</Accordion>
<Accordion title="11b. 引导文件大小">
Doctor 会检查工作区引导文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符占总预算的比例。当文件被截断或接近限制时，doctor 会打印用于调整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。
Doctor 会检查工作区引导文件（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的上下文文件）是否接近或超过配置的字符预算。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因（`max/file` 或 `max/total`），以及总注入字符数占总预算的比例。当文件被截断或接近限制时，Doctor 会打印调整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。
</Accordion>
<Accordion title="11d. 陈旧渠道插件清理">
当 `openclaw doctor --fix` 删除缺失的渠道插件时，它还会删除引用该插件的悬空渠道范围配置：`channels.<id>` 条目、命名该渠道的 Heartbeat 目标，以及 `agents.*.models["<channel>/*"]` 覆盖项。这可以防止渠道运行时已不存在但配置仍要求 Gateway 网关绑定到它而导致的 Gateway 网关启动循环。
<Accordion title="11d. 过期渠道插件清理">
当 `openclaw doctor --fix` 移除缺失的渠道插件时，它也会移除引用该插件的悬空渠道作用域配置：`channels.<id>` 条目、命名该渠道的 Heartbeat 目标，以及 `agents.*.models["<channel>/*"]` 覆盖。这会防止渠道运行时已消失但配置仍要求 Gateway 网关绑定到它而导致的 Gateway 网关启动循环。
</Accordion>
<Accordion title="11c. Shell 补全">
Doctor 会检查当前 shell（zsh、bash、fish 或 PowerShell）是否已安装 Tab 补全：
- 如果 shell 配置文件使用较慢的动态补全模式（`source <(openclaw completion ...)`），doctor 会将其升级为更快的缓存文件变体。
- 如果补全已在配置文件中配置，但缓存文件缺失，doctor 会自动重新生成缓存。
- 如果完全没有配置补全，doctor 会提示安装它（仅交互模式；使用 `--non-interactive` 时跳过）。
- 如果 shell 配置文件使用慢速动态补全模式（`source <(openclaw completion ...)`），Doctor 会将其升级为更快的缓存文件变体。
- 如果补全已在配置文件中配置但缓存文件缺失，Doctor 会自动重新生成缓存。
- 如果完全没有配置补全，Doctor 会提示安装它（仅交互模式；使用 `--non-interactive` 时跳过）。
运行 `openclaw completion --write-state` 可手动重新生成缓存。
</Accordion>
<Accordion title="12. Gateway 网关认证检查（本地令牌）">
Doctor 会检查本地 Gateway 网关令牌认证就绪情况。
Doctor 会检查本地 Gateway 网关令牌认证就绪状态。
- 如果令牌模式需要令牌而不存在令牌来源，doctor 会提供生成一个令牌的选项。
- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，doctor 会发出警告，并且不会用明文覆盖它。
- `openclaw doctor --generate-gateway-token` 仅在未配置令牌 SecretRef 时强制生成。
- 如果令牌模式需要令牌且不存在令牌来源，Doctor 会提供生成一个令牌的选项。
- 如果 `gateway.auth.token` 由 SecretRef 管理但不可用，Doctor 会发出警告，并且不会用明文覆盖它。
- `openclaw doctor --generate-gateway-token` 只会在未配置令牌 SecretRef 时强制生成。
</Accordion>
<Accordion title="12b. 感知 SecretRef 的只读修复">
一些修复流程需要检查已配置的凭证，而不削弱运行时快速失败行为。
一些修复流程需要检查已配置的凭证，同时不削弱运行时快速失败行为。
- `openclaw doctor --fix` 现在会使用与 status 系列命令相同的只读 SecretRef 摘要模型来进行目标配置修复。
- `openclaw doctor --fix` 现在会使用与 status 系列命令相同的只读 SecretRef 摘要模型来进行定向配置修复。
- 示例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修复会在可用时尝试使用已配置的机器人凭证。
- 如果 Telegram 机器人令牌通过 SecretRef 配置，但在当前命令路径中不可用，doctor 会报告该凭证已配置但不可用，并跳过自动解析，而不是崩溃或误报令牌缺失。
- 如果 Telegram 机器人令牌通过 SecretRef 配置，但在当前命令路径中不可用，Doctor 会报告该凭证已配置但不可用，并跳过自动解析，而不是崩溃或误报令牌缺失。
</Accordion>
<Accordion title="13. Gateway 网关健康检查 + 重启">
Doctor 会运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。
</Accordion>
<Accordion title="13b. 记忆搜索就绪情况">
Doctor 会检查为默认智能体配置的记忆搜索嵌入提供商是否就绪。行为取决于配置的后端和提供商：
<Accordion title="13b. 记忆搜索就绪状态">
Doctor 会检查默认智能体的已配置记忆搜索嵌入提供商是否就绪。其行为取决于已配置的后端和提供商：
- **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会打印修复指引，包括 npm 包和手动二进制路径选项。
- **QMD 后端**：探测 `qmd` 二进制文件是否可用且可启动。如果不可用，会打印修复指导，包括 npm package 和手动二进制路径选项。
- **显式本地提供商**：检查本地模型文件或可识别的远程/可下载模型 URL。如果缺失，建议切换到远程提供商。
- **显式远程提供商**（`openai`、`voyage` 等）：验证环境或认证存储中是否存在 API key。如果缺失，会打印可操作的修复提示。
- **显式远程提供商**（`openai`、`voyage` 等）：验证环境或 auth store 中是否存在 API key。如果缺失，会打印可执行的修复提示。
- **自动提供商**：先检查本地模型可用性，然后按自动选择顺序尝试每个远程提供商。
当有缓存的 Gateway 网关探测结果可用时（检查时 Gateway 网关健康），doctor 会将其结果与 CLI 可见配置交叉引用，并记录任何差异。Doctor 不会在默认路径上启动新的 embedding ping；如果你想进行实时提供商检查，请使用深度记忆状态命令。
当缓存的 Gateway 网关探测结果可用时（检查时 Gateway 网关健康），Doctor 会将其结果与 CLI 可见配置交叉对照，并指出任何差异。Doctor 不会在默认路径上启动新的 embedding ping；如果你想进行实时提供商检查，请使用深度记忆状态命令。
使用 `openclaw memory status --deep` 在运行时验证嵌入就绪状态。
使用 `openclaw memory status --deep` 在运行时验证 embedding 就绪状态。
</Accordion>
<Accordion title="14. 渠道状态警告">
如果 Gateway 网关健康，doctor 会运行渠道状态探测，并报告带有建议修复方案的警告。
如果 Gateway 网关健康，Doctor 会运行渠道状态探测，并报告警告及建议修复方式。
</Accordion>
<Accordion title="15. 监督进程配置审计 + 修复">
Doctor 会检查已安装的监督进程配置（launchd/systemd/schtasks）是否缺少默认值或默认值过时（例如 systemd network-online 依赖项和重启延迟）。发现不匹配时，它会建议更新，并可将服务文件/任务重写为当前默认值。
<Accordion title="15. supervisor 配置审计 + 修复">
Doctor 会检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否缺少默认值或默认值过时（例如 systemd network-online 依赖和重启延迟）。发现不匹配时，它会建议更新，并且可以将 service file/task 重写为当前默认值。
注意：
注意事项：
- `openclaw doctor` 会在重写监督进程配置前提示确认。
- `openclaw doctor --yes` 会接受默认修复提示。
- `openclaw doctor --repair` 会在不提示的情况下应用建议修复。
- `openclaw doctor --repair --force` 会覆盖自定义监督进程配置。
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` 会让 doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状态并运行非服务修复，但会跳过服务安装/启动/重启/引导、监督进程配置重写和旧版服务清理，因为该生命周期由外部监督进程拥有。
- 在 Linux 上，当匹配的 systemd Gateway 网关单元处于活动状态时，doctor 不会重写命令/入口点元数据。它还会在重复服务扫描期间忽略非活动的非旧版额外 Gateway 网关类单元，因此配套服务文件不会产生清理噪声。
- 如果令牌认证需要令牌且 `gateway.auth.token` 由 SecretRef 管理，doctor 服务安装/修复会验证 SecretRef，但不会将解析出的明文令牌值持久化到监督进程服务环境元数据中。
- Doctor 会检测旧版 LaunchAgent、systemd 或 Windows 计划任务安装曾内联嵌入的托管 `.env`/SecretRef 支持的服务环境值，并重写服务元数据，使这些值从运行时源加载，而不是从监督进程定义加载。
- Doctor 会检测服务命令在 `gateway.port` 更改后是否仍固定旧的 `--port`，并将服务元数据重写为当前端口。
- 如果令牌认证需要令牌且配置的令牌 SecretRef 未解析，doctor 会阻止安装/修复路径，并给出可操作指引。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且未设置 `gateway.auth.mode`，doctor 会阻止安装/修复，直到显式设置 mode。
- 对于 Linux 用户 systemd 单元，doctor 令牌漂移检查现在会在比较服务认证元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 源。
- 当配置最后由较新版本写入时，Doctor 服务修复会拒绝使用旧版 OpenClaw 二进制文件重写、停止或重启 Gateway 网关服务。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
- 你始终可以通过 `openclaw gateway install --force` 强制完整重写。
- `openclaw doctor` 会在重写 supervisor 配置前提示。
- `openclaw doctor --yes` 接受默认修复提示。
- `openclaw doctor --repair` 无提示应用建议修复。
- `openclaw doctor --repair --force` 覆盖自定义 supervisor 配置。
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` 会让 Doctor 对 Gateway 网关服务生命周期保持只读。它仍会报告服务健康状况并运行非服务修复，但会跳过服务安装/启动/重启/引导、supervisor 配置重写以及旧版服务清理，因为该生命周期由外部 supervisor 拥有。
- 在 Linux 上，当匹配的 systemd Gateway 网关单元处于活动状态时，Doctor 不会重写命令/入口点元数据。它还会在重复服务扫描期间忽略非活动的非旧版额外 Gateway 网关类单元，因此配套服务文件不会制造清理噪声。
- 如果 token auth 需要 token 且 `gateway.auth.token` 由 SecretRef 管理，Doctor 服务安装/修复会验证 SecretRef，但不会将解析出的明文 token 值持久化到 supervisor 服务环境元数据中。
- Doctor 会检测旧版 LaunchAgent、systemd 或 Windows Scheduled Task 安装内联嵌入的托管 `.env`/SecretRef 支持的服务环境值，并重写服务元数据，使这些值从运行时来源加载，而不是从 supervisor 定义加载。
- Doctor 会检测服务命令在 `gateway.port` 变更后是否仍固定使用旧的 `--port`，并将服务元数据重写为当前端口。
- 如果 token auth 需要 token 且配置的 token SecretRef 无法解析，Doctor 会阻止安装/修复路径，并给出可执行指导。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，Doctor 会阻止安装/修复，直到显式设置 mode。
- 对于 Linux user-systemd 单元，Doctor token 漂移检查现在会在比较服务 auth 元数据时同时包含 `Environment=` 和 `EnvironmentFile=` 来源。
- 当配置最后由更新版本写入时，Doctor 服务修复会拒绝重写、停止或重启来自旧版 OpenClaw 二进制文件的 Gateway 网关服务。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
- 你始终可以通过 `openclaw gateway install --force` 强制完全重写。
</Accordion>
<Accordion title="16. Gateway 网关运行时 + 端口诊断">
Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已运行、SSH 隧道）。
Doctor 会检查服务运行时（PID、上次退出状态），并在服务已安装但实际上未运行时发出警告。它还会检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能原因（Gateway 网关已在运行、SSH 隧道）。
</Accordion>
<Accordion title="17. Gateway 网关运行时最佳实践">
当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，而版本管理器路径可能会在升级后失效，因为服务不会加载你的 shell 初始化。Doctor 会在系统 Node 安装可用时（Homebrew/apt/choco）提供迁移到系统 Node 的选项。
当 Gateway 网关服务运行在 Bun 或版本管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，并且版本管理器路径可能在升级后失效，因为服务不会加载你的 shell 初始化。Doctor 会在可用时提议迁移到系统 Node 安装（Homebrew/apt/choco）。
新安装或修复的服务会保留显式环境根目录（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）和稳定的用户 bin 目录，但推测出的版本管理器回退目录只有在这些目录实际存在于磁盘上时，才会写入服务 PATH。这会让生成的监督进程 PATH 与 doctor 后续运行的相同最小 PATH 审计保持一致。
新安装或修复的服务会保留显式环境根目录（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）和稳定的 user-bin 目录，但推测出的版本管理器后备目录只有在这些目录实际存在于磁盘上时才会写入服务 PATH。这使生成的 supervisor PATH 与 Doctor 稍后运行的相同最小 PATH 审计保持一致。
</Accordion>
<Accordion title="18. 配置写入 + 向导元数据">
Doctor 会持久化任何配置更改，并写入向导元数据以记录 doctor 运行。
Doctor 会持久化任何配置变更，并写入向导元数据以记录 Doctor 运行。
</Accordion>
<Accordion title="19. 工作区提示（备份 + 记忆系统）">
当缺少工作区记忆系统时，Doctor 会给出建议；如果工作区尚未纳入 git 管理，则会打印备份提示。
当缺少工作区记忆系统时，Doctor 会建议设置一个；如果工作区尚未纳入 git 管理，则会打印备份提示。
请参阅 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)，获取工作区结构和 git 备份的完整指南（推荐使用私有 GitHub 或 GitLab）。
有关工作区结构和 git 备份（推荐私有 GitHub 或 GitLab）的完整指南，请参见 [/concepts/agent-workspace](/zh-CN/concepts/agent-workspace)。
</Accordion>
</AccordionGroup>
## 相关内容
## 相关
- [Gateway 网关运行手册](/zh-CN/gateway)
- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting)

474
docs/zh-CN/help/faq-first-run.md
View File

@ -1,16 +1,16 @@
---
read_when:
- 新安装、新手引导卡住或首次运行错误
- 选择凭证和提供商订阅
- 无法访问 docs.openclaw.ai，无法打开仪表盘，安装卡住
- 选择认证方式和提供商订阅
- 无法访问 docs.openclaw.ai，无法打开仪表板，安装卡住
sidebarTitle: First-run FAQ
summary: 常见问题：快速开始和首次运行设置 — 安装、新手引导、凭证、订阅、初始故障
summary: 常见问题：快速开始和首次运行设置 — 安装、新手引导、认证、订阅、初始故障
title: 常见问题：首次运行设置
x-i18n:
generated_at: "2026-04-28T11:55:26Z"
generated_at: "2026-05-02T02:37:22Z"
model: gpt-5.5
provider: openai
source_hash: 959e5c8a94cce6369af84d3d1e252dbfb22acb5891ac1d8b64722c4c40679e65
source_hash: 469fbd24fea69d91c5b0408dff9c7d7b2382f9c59430a1d5331cb5dcabdce295
source_path: help/faq-first-run.md
workflow: 16
---
@ -21,26 +21,26 @@ x-i18n:
<AccordionGroup>
<Accordion title="我卡住了，最快的解决问题方式">
使用一个可以**看到你的机器**的本地 AI 智能体。这比在 Discord 里提问有效得多，因为大多数“我卡住了”的情况都是**本地配置或环境问题**，远程协助者无法检查。
使用一个能**查看你的机器**的本地 AI 智能体。这比在 Discord 中询问有效得多，因为大多数“我卡住了”的情况都是**本地配置或环境问题**，远程协助者无法检查。
- **Claude Code**：[https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)
- **OpenAI Codex**：[https://openai.com/codex/](https://openai.com/codex/)
- **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)
- **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/)
这些工具可以读取仓库、运行命令、检查日志，并帮助修复你的机器级设置（PATH、服务、权限、凭证文件）。通过可改造的 (git) 安装方式，把**完整源码检出**交给它们：
这些工具可以读取仓库、运行命令、检查日志，并帮助修复你的机器级设置（PATH、服务、权限、凭证文件）。通过可修改的（git）安装方式，把**完整源码检出**交给它们：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
```
这会**从 git 检出**安装 OpenClaw，因此智能体可以读取代码和文档，并基于你正在运行的确切版本进行推理。之后你随时可以不带 `--install-method git` 重新运行安装器，切回稳定版。
这会**从 git 检出**安装 OpenClaw，因此智能体可以读取代码和文档，并根据你正在运行的确切版本进行推理。你之后随时可以通过不带 `--install-method git` 重新运行安装器切回稳定版。
提示：让智能体**规划并监督**修复（逐步进行），然后只执行必要命令。这样变更更小，也更容易审计。
提示：让智能体**规划并监督**修复（一步一步），然后只执行必要命令。这样改动更小，也更容易审计。
如果你发现了真实 bug 或修复，请提交 GitHub issue 或发送 PR：
[https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues)
[https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls)
从这些命令开始（寻求帮助时分享输出）：
从这些命令开始（求助时分享输出）：
```bash
openclaw status
@ -50,42 +50,43 @@ x-i18n:
它们的作用：
- `openclaw status`：Gateway 网关/智能体健康状况和基础配置的快速快照。
- `openclaw models status`：检查提供商凭证和模型可用性。
- `openclaw status`：Gateway 网关/智能体健康状况 + 基本配置的快速快照。
- `openclaw models status`：检查提供商凭证 + 模型可用性。
- `openclaw doctor`：验证并修复常见配置/状态问题。
其他有用的 CLI 检查：`openclaw status --all`、`openclaw logs --follow`、`openclaw gateway status`、`openclaw health --verbose`。
其他有用的 CLI 检查：`openclaw status --all`、`openclaw logs --follow`、
`openclaw gateway status`、`openclaw health --verbose`。
快速调试循环：[如果有东西坏了，最初的六十秒](#first-60-seconds-if-something-is-broken)。
快速调试循环：[如果某些东西坏了，最初的六十秒](#first-60-seconds-if-something-is-broken)。
安装文档：[安装](/zh-CN/install)、[安装器标志](/zh-CN/install/installer)、[更新](/zh-CN/install/updating)。
</Accordion>
<Accordion title="心跳一直跳过。跳过原因是什么意思？">
常见心跳跳过原因：
<Accordion title="Heartbeat 一直跳过。跳过原因是什么意思？">
常见 Heartbeat 跳过原因：
- `quiet-hours`：不在配置的活跃时段窗口内
- `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白/仅标题的脚手架
- `no-tasks-due`：`HEARTBEAT.md` 任务模式已启用，但还没有任务间隔到期
- `alerts-disabled`：所有心跳可见性都被禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）
- `quiet-hours`：不在配置的活跃时间窗口内
- `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白/仅标题脚手架
- `no-tasks-due`：`HEARTBEAT.md` 任务模式处于启用状态，但任务间隔尚未到期
- `alerts-disabled`：所有 Heartbeat 可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 都关闭）
在任务模式中，到期时间戳只会在一次真实心跳运行完成后推进。被跳过的运行不会将任务标记为已完成。
在任务模式中，到期时间戳只会在一次真实 Heartbeat 运行完成后推进。被跳过的运行不会将任务标记为已完成。
文档：[心跳](/zh-CN/gateway/heartbeat)、[自动化与任务](/zh-CN/automation)。
文档：[Heartbeat](/zh-CN/gateway/heartbeat)、[自动化与任务](/zh-CN/automation)。
</Accordion>
<Accordion title="推荐的 OpenClaw 安装和设置方式">
仓库建议从源码运行并使用新手引导：
<Accordion title="安装并设置 OpenClaw 的推荐方式">
仓库推荐从源码运行并使用新手引导：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
```
向导也可以自动构建 UI 资源。完成新手引导后，你通常会在端口 **18789** 上运行 Gateway 网关。
向导也可以自动构建 UI 资产。完成新手引导后，你通常会在端口 **18789** 上运行 Gateway 网关。
从源码安装（贡献者/开发）：
从源码运行（贡献者/开发者）：
```bash
git clone https://github.com/openclaw/openclaw.git
@ -96,84 +97,84 @@ x-i18n:
openclaw onboard
```
如果你还没有全局安装，请通过 `pnpm openclaw onboard` 运行。
如果你还没有全局安装，请通过 `pnpm openclaw onboard` 运行它。
</Accordion>
<Accordion title="新手引导后如何打开仪表盘？">
向导会在新手引导后立即用干净的（非令牌化）仪表盘 URL 打开你的浏览器，并在摘要中打印该链接。保持该标签页打开；如果没有启动，请在同一台机器上复制/粘贴打印出的 URL。
<Accordion title="新手引导后如何打开仪表板？">
向导会在新手引导后立即用干净的（非令牌化）仪表板 URL 打开你的浏览器，并且也会在摘要中打印链接。保持该标签页打开；如果没有启动，请在同一台机器上复制/粘贴打印出来的 URL。
</Accordion>
<Accordion title="localhost 和远程环境下如何认证仪表盘？">
<Accordion title="如何在 localhost 与远程环境中验证仪表板身份？">
**Localhost（同一台机器）：**
- 打开 `http://127.0.0.1:18789/`。
- 如果要求共享密钥凭证，请把配置的令牌或密码粘贴到 Control UI 设置中。
- 如果它要求共享密钥身份验证，请把配置的令牌或密码粘贴到控制 UI 设置中。
- 令牌来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。
- 密码来源：`gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。
- 如果还没有配置共享密钥，请用 `openclaw doctor --generate-gateway-token` 生成令牌。
**不在 localhost 上：**
- **Tailscale Serve**（推荐）：保持绑定到 loopback，运行 `openclaw gateway --tailscale serve`，打开 `https://<magicdns>/`。如果 `gateway.auth.allowTailscale` 为 `true`，身份头会满足 Control UI/WebSocket 凭证要求（无需粘贴共享密钥，前提是假定 Gateway 网关主机可信）；HTTP API 仍然需要共享密钥凭证，除非你有意使用 private-ingress `none` 或 trusted-proxy HTTP 凭证。
来自同一客户端的错误并发 Serve 凭证尝试会在失败凭证限速器记录之前被串行化，因此第二次错误重试可能已经显示 `retry later`。
- **Tailnet 绑定**：运行 `openclaw gateway --bind tailnet --token "<token>"`（或配置密码凭证），打开 `http://<tailscale-ip>:18789/`，然后在仪表盘设置中粘贴匹配的共享密钥。
- **具备身份感知的反向代理**：将 Gateway 网关置于可信代理之后，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开代理 URL。同主机 loopback 代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。
- **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。共享密钥凭证仍然适用于该隧道；如有提示，请粘贴配置的令牌或密码。
- **Tailscale Serve**（推荐）：保持绑定到 loopback，运行 `openclaw gateway --tailscale serve`，打开 `https://<magicdns>/`。如果 `gateway.auth.allowTailscale` 为 `true`，身份标头会满足控制 UI/WebSocket 身份验证（无需粘贴共享密钥，前提是假定 Gateway 网关主机可信）；HTTP API 仍然需要共享密钥身份验证，除非你有意使用 private-ingress `none` 或 trusted-proxy HTTP 身份验证。
来自同一客户端的并发错误 Serve 身份验证尝试会在失败身份验证限流器记录之前被串行化，因此第二次错误重试可能已经显示 `retry later`。
- **Tailnet 绑定**：运行 `openclaw gateway --bind tailnet --token "<token>"`（或配置密码身份验证），打开 `http://<tailscale-ip>:18789/`，然后在仪表板设置中粘贴匹配的共享密钥。
- **身份感知反向代理**：把 Gateway 网关放在可信代理后面，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开代理 URL。同主机 loopback 代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。
- **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。共享密钥身份验证仍然适用于该隧道；如果出现提示，请粘贴配置的令牌或密码。
绑定模式和凭证详情见[仪表盘](/zh-CN/web/dashboard)和 [Web 界面](/zh-CN/web)。
请参阅[仪表板](/zh-CN/web/dashboard)和 [Web 界面](/zh-CN/web)，了解绑定模式和身份验证详情。
</Accordion>
<Accordion title="为什么聊天审批有两个 exec 审批配置？">
它们控制不同层：
它们控制不同层级：
- `approvals.exec`：将审批提示转发到聊天目标
- `channels.<channel>.execApprovals`：让该渠道充当 exec 审批的原生审批客户端
- `approvals.exec`：把审批提示转发到聊天目的地
- `channels.<channel>.execApprovals`：让该渠道作为 exec 审批的原生审批客户端
主机 exec 策略仍然是真正的审批门禁。聊天配置只控制审批提示出现在哪里，以及人们如何回复它们。
主机 exec 策略仍然是真正的审批关口。聊天配置只控制审批提示出现在哪里，以及人们可以如何回应。
在大多数设置中，你**不**需要两者都配置：
在大多数设置中，你**不**需要两者：
- 如果聊天已经支持命令和回复，同一聊天里的 `/approve` 会通过共享路径工作。
- 如果受支持的原生渠道可以安全推断审批者，当 `channels.<channel>.execApprovals.enabled` 未设置或为 `"auto"` 时，OpenClaw 现在会自动启用私信优先的原生审批。
- 当原生审批卡片/按钮可用时，该原生 UI 是主要路径；只有在工具结果表明聊天审批不可用或手动审批是唯一路径时，智能体才应包含手动 `/approve` 命令。
- 只有在提示还必须转发到其他聊天或明确的运维房间时，才使用 `approvals.exec`。
- 只有在你明确希望审批提示回发到原始房间/主题时，才使用 `channels.<channel>.execApprovals.target: "channel"` 或 `"both"`。
- 插件审批又是独立的：默认使用同一聊天里的 `/approve`，可选 `approvals.plugin` 转发，并且只有部分原生渠道会在此之上保留插件审批原生处理。
- 如果聊天已经支持命令和回复，同一聊天中的 `/approve` 会通过共享路径工作。
- 如果受支持的原生渠道可以安全地推断审批人，当 `channels.<channel>.execApprovals.enabled` 未设置或为 `"auto"` 时，OpenClaw 现在会自动启用 DM 优先的原生审批。
- 当原生审批卡片/按钮可用时，该原生 UI 是主要路径；只有当工具结果说明聊天审批不可用或手动审批是唯一路径时，智能体才应包含手动 `/approve` 命令。
- 仅当提示还必须转发到其他聊天或显式运维房间时，才使用 `approvals.exec`。
- 仅当你明确希望审批提示发回原始房间/主题时，才使用 `channels.<channel>.execApprovals.target: "channel"` 或 `"both"`。
- 插件审批又是独立的：默认使用同一聊天中的 `/approve`，可选使用 `approvals.plugin` 转发，并且只有部分原生渠道在其上保留插件审批原生处理。
简短说法：转发用于路由，原生客户端配置用于更丰富的渠道特定 UX。
见 [Exec Approvals](/zh-CN/tools/exec-approvals)。
简短版本：转发用于路由，原生客户端配置用于更丰富的渠道特定用户体验。
请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。
</Accordion>
<Accordion title="我需要什么运行时？">
需要 Node **>= 22**。推荐使用 `pnpm`。Gateway 网关**不推荐**使用 Bun。
需要 Node **>= 22**。推荐使用 `pnpm`。**不推荐**将 Bun 用于 Gateway 网关。
</Accordion>
<Accordion title="它能在 Raspberry Pi 上运行吗？">
可以。Gateway 网关很轻量，文档列出的个人使用足够配置为 **512MB-1GB RAM**、**1 核**，以及约 **500MB** 磁盘，并说明 **Raspberry Pi 4 可以运行它**。
可以。Gateway 网关很轻量，文档列出的个人使用足够配置为 **512MB-1GB RAM**、**1 个核心**，以及约 **500MB** 磁盘，并说明 **Raspberry Pi 4 可以运行它**。
如果你想要额外余量（日志、媒体、其他服务），**推荐 2GB**，但这不是硬性最低要求。
如果你想要更多余量（日志、媒体、其他服务），**推荐 2GB**，但这不是硬性最低要求。
提示：小型 Pi/VPS 可以托管 Gateway 网关，你可以在笔记本电脑/手机上配对**节点**，用于本地屏幕/摄像头/画布或命令执行。见[节点](/zh-CN/nodes)。
提示：一台小型 Pi/VPS 可以托管 Gateway 网关，你也可以在笔记本电脑/手机上配对**节点**，用于本地屏幕/摄像头/canvas 或命令执行。请参阅[节点](/zh-CN/nodes)。
</Accordion>
<Accordion title="Raspberry Pi 安装有什么建议？">
简短说法：可以运行，但可能会遇到一些粗糙边缘。
简短版本：它可以工作，但可能会遇到一些边缘问题。
- 使用 **64 位**操作系统，并保持 Node >= 22。
- 优先使用**可改造的 (git) 安装**，这样你可以查看日志并快速更新。
- 先不启用渠道/Skills，然后逐个添加。
- 使用 **64 位** OS，并保持 Node >= 22。
- 优先使用**可修改的（git）安装**，这样你可以查看日志并快速更新。
- 先不启用渠道/Skills，随后逐个添加。
- 如果遇到奇怪的二进制问题，通常是 **ARM 兼容性**问题。
文档：[Linux](/zh-CN/platforms/linux)、[安装](/zh-CN/install)。
</Accordion>
<Accordion title="它卡在 wake up my friend / 新手引导无法 hatch。现在怎么办？">
该屏幕依赖 Gateway 网关可访问并已认证。TUI 还会在第一次 hatch 时自动发送“Wake up, my friend!”。如果你看到那行但**没有回复**，并且 token 保持为 0，说明智能体从未运行。
<Accordion title="它卡在 wake up my friend / 新手引导无法孵化。现在怎么办？">
该屏幕依赖 Gateway 网关可访问且已通过身份验证。TUI 也会在首次孵化时自动发送 “Wake up, my friend!”。如果你看到该行但**没有回复**，且令牌数保持为 0，则智能体从未运行。
1. 重启 Gateway 网关：
@ -181,7 +182,7 @@ x-i18n:
openclaw gateway restart
```
2. 检查 Status 和凭证：
2. 检查 Status + 凭证：
```bash
openclaw status
@ -189,68 +190,70 @@ x-i18n:
openclaw logs --follow
```
3. 如果仍然挂起，运行：
3. 如果仍然挂起，请运行：
```bash
openclaw doctor
```
如果 Gateway 网关是远程的，请确保隧道/Tailscale 连接已建立，并且 UI 指向正确的 Gateway 网关。见[远程访问](/zh-CN/gateway/remote)。
如果 Gateway 网关是远程的，请确保隧道/Tailscale 连接已开启，并且 UI 指向正确的 Gateway 网关。请参阅[远程访问](/zh-CN/gateway/remote)。
</Accordion>
<Accordion title="我可以把设置迁移到新机器（Mac mini）而不重新做新手引导吗？">
可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。只要你复制**这两个**位置，这会让你的 bot 保持“完全一样”（memory、会话历史、凭证和渠道状态）：
可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。只要你复制**两个**位置，这会让你的机器人保持“完全相同”（记忆、会话历史、凭证和渠道状态）：
1. 在新机器上安装 OpenClaw。
2. 从旧机器复制 `$OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）。
3. 复制你的工作区（默认：`~/.openclaw/workspace`）。
4. 运行 `openclaw doctor` 并重启 Gateway 网关服务。
这会保留配置、凭证配置文件、WhatsApp 凭据、会话和 memory。如果你处于远程模式，请记住 gateway 主机拥有会话存储和工作区。
这会保留配置、凭证配置文件、WhatsApp 凭据、会话和记忆。如果你处于远程模式，请记住 Gateway 网关主机拥有会话存储和工作区。
**重要：**如果你只是把工作区提交/推送到 GitHub，你备份的是 **memory + bootstrap 文件**，但**不是**会话历史或凭证。它们位于 `~/.openclaw/` 下（例如 `~/.openclaw/agents/<agentId>/sessions/`）。
**重要：**如果你只把工作区提交/推送到 GitHub，你备份的是**记忆 + bootstrap 文件**，但**不是**会话历史或凭证。它们位于 `~/.openclaw/` 下（例如 `~/.openclaw/agents/<agentId>/sessions/`）。
相关：[迁移](/zh-CN/install/migrating)、[磁盘上的内容位置](#where-things-live-on-disk)、[Agent 工作区](/zh-CN/concepts/agent-workspace)、[Doctor](/zh-CN/gateway/doctor)、[远程模式](/zh-CN/gateway/remote)。
相关：[迁移](/zh-CN/install/migrating)、[内容在磁盘上的位置](#where-things-live-on-disk)、
[Agent 工作区](/zh-CN/concepts/agent-workspace)、[Doctor](/zh-CN/gateway/doctor)、
[远程模式](/zh-CN/gateway/remote)。
</Accordion>
<Accordion title="在哪里查看最新版本的新内容？">
查看 GitHub 更新日志：
查看 GitHub 变更日志：
[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
最新条目位于顶部。如果顶部章节标记为 **Unreleased**，下一个带日期的章节就是最新已发布版本。条目按 **Highlights**、**Changes** 和 **Fixes** 分组（需要时还会有文档/其他章节）。
最新条目位于顶部。如果顶部部分标记为 **Unreleased**，则下一个带日期的部分就是最新已发布版本。条目按 **Highlights**、**Changes** 和 **Fixes** 分组（需要时还会有文档/其他部分）。
</Accordion>
<Accordion title="无法访问 docs.openclaw.ai（SSL 错误）">
某些 Comcast/Xfinity 连接会被 Xfinity Advanced Security 错误阻止访问 `docs.openclaw.ai`。禁用它或将 `docs.openclaw.ai` 加入允许列表，然后重试。
请在此处报告，帮助我们解除阻止：[https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。
某些 Comcast/Xfinity 连接会通过 Xfinity Advanced Security 错误地阻止 `docs.openclaw.ai`。请禁用它或将 `docs.openclaw.ai` 加入允许列表，然后重试。
请在这里报告，帮助我们解除阻止：[https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。
如果你仍然无法访问该站点，文档也镜像在 GitHub 上：
如果你仍然无法访问该站点，文档也镜像在 GitHub：
[https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)
</Accordion>
<Accordion title="stable 和 beta 的区别">
**Stable** 和 **beta** 是 **npm dist-tags**，不是独立的代码线：
<Accordion title="稳定版和 beta 的区别">
**稳定版** 和 **beta** 是 **npm dist-tags**，不是不同的代码线：
- `latest` = stable
- `latest` = 稳定版
- `beta` = 用于测试的早期构建
通常，稳定版本会先发布到 **beta**，然后通过一个显式的
提升步骤把同一个版本移到 `latest`。维护者也可以在需要时
直接发布到 `latest`。这就是为什么提升后 beta 和 stable 可能
指向**同一个版本**。
通常，稳定版本会先发布到 **beta**，然后通过一个明确的
提升步骤把同一个版本移动到 `latest`。维护者也可以在需要时
直接发布到 `latest`。这就是为什么提升后 beta 和稳定版可能
指向 **同一个版本**。
查看变更内容：
查看变更：
[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
有关安装一行命令以及 beta 和 dev 的区别，请看下面的折叠项。
如需安装一行命令以及 beta 和 dev 的区别，请查看下面的折叠项。
</Accordion>
<Accordion title="如何安装 beta 版本，beta 和 dev 有什么区别？">
<Accordion title="如何安装 beta 版本，以及 beta 和 dev 有什么区别？">
**Beta** 是 npm dist-tag `beta`（提升后可能与 `latest` 相同）。
**Dev** 是 `main` 的移动头部（git）；发布时，它使用 npm dist-tag `dev`。
@ -271,7 +274,7 @@ x-i18n:
</Accordion>
<Accordion title="如何试用最新内容？">
<Accordion title="如何试用最新构建？">
两个选项：
1. **Dev 渠道（git checkout）：**
@ -280,7 +283,7 @@ x-i18n:
openclaw update --channel dev
```
这会切换到 `main` 分支，并从源码更新。
这会切换到 `main` 分支并从源代码更新。
2. **可修改安装（来自安装器站点）：**
@ -288,9 +291,9 @@ x-i18n:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
```
这会给你一个可编辑的本地仓库，之后可通过 git 更新。
这会给你一个可以编辑的本地仓库，然后通过 git 更新。
如果你更喜欢手动进行干净克隆，请使用：
如果你更喜欢手动干净克隆，请使用：
```bash
git clone https://github.com/openclaw/openclaw.git
@ -304,11 +307,11 @@ x-i18n:
</Accordion>
<Accordion title="安装和新手引导通常需要多长时间？">
<Accordion title="安装和新手引导通常需要多久？">
粗略指南：
- **安装：** 2-5 分钟
- **新手引导：** 5-15 分钟，取决于你配置的渠道/模型数量
- **新手引导：** 5-15 分钟，取决于你配置了多少渠道/模型
如果卡住，请使用 [安装器卡住](#quick-start-and-first-run-setup)
以及 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。
@ -316,7 +319,7 @@ x-i18n:
</Accordion>
<Accordion title="安装器卡住？如何获得更多反馈？">
使用**详细输出**重新运行安装器：
使用 **详细输出** 重新运行安装器：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
@ -328,7 +331,7 @@ x-i18n:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
```
对于可修改（git）安装：
可修改（git）安装：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
@ -348,26 +351,26 @@ x-i18n:
</Accordion>
<Accordion title="Windows 安装提示找不到 git 或无法识别 openclaw">
两个常见 Windows 问题：
两个常见的 Windows 问题：
**1) npm error spawn git / 找不到 git**
**1）npm 错误 spawn git / 找不到 git**
- 安装 **Git for Windows**，并确保 `git` 位于你的 PATH 中。
- 安装 **Git for Windows**，并确保 `git` 在你的 PATH 上。
- 关闭并重新打开 PowerShell，然后重新运行安装器。
**2) 安装后无法识别 openclaw**
**2）安装后无法识别 openclaw**
- 你的 npm 全局 bin 文件夹不在 PATH 中。
- 你的 npm 全局 bin 文件夹不在 PATH 上。
- 检查路径：
```powershell
npm config get prefix
```
- 将该目录添加到你的用户 PATH（Windows 上不需要 `\bin` 后缀；在大多数系统上它是 `%AppData%\npm`）。
- 将该目录添加到你的用户 PATH（Windows 上不需要 `\bin` 后缀；在大多数系统上是 `%AppData%\npm`）。
- 更新 PATH 后关闭并重新打开 PowerShell。
如果你想获得最顺畅的 Windows 设置，请使用 **WSL2** 而不是原生 Windows。
如果你想要最顺畅的 Windows 设置，请使用 **WSL2** 而不是原生 Windows。
文档：[Windows](/zh-CN/platforms/windows)。
</Accordion>
@ -378,9 +381,9 @@ x-i18n:
症状：
- `system.run`/`exec` 输出把中文渲染成乱码
- 同一个命令在另一个终端配置文件中显示正常
- 同一条命令在另一个终端配置文件中显示正常
PowerShell 中的快速解决方法：
PowerShell 中的快速绕过方法：
```powershell
chcp 65001
@ -395,15 +398,15 @@ x-i18n:
openclaw gateway restart
```
如果你仍能在最新 OpenClaw 上复现，请在这里跟踪/报告：
如果你仍能在最新 OpenClaw 上复现此问题，请在这里跟踪/报告：
- [Issue #30640](https://github.com/openclaw/openclaw/issues/30640)
</Accordion>
<Accordion title="文档没有回答我的问题 - 如何获得更好的答案？">
使用**可修改（git）安装**，这样你本地就有完整源码和文档，然后从该文件夹
向你的机器人（或 Claude/Codex）提问，让它能够读取仓库并准确回答。
使用 **可修改（git）安装**，这样你就可以在本地拥有完整源代码和文档，然后
从该文件夹让你的机器人（或 Claude/Codex）提问，这样它就能读取仓库并精确回答。
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
@ -418,7 +421,7 @@ x-i18n:
- Linux 快速路径 + 服务安装：[Linux](/zh-CN/platforms/linux)。
- 完整演练：[入门指南](/zh-CN/start/getting-started)。
- 安装器 + 更新：[安装和更新](/zh-CN/install/updating)。
- 安装器 + 更新：[安装与更新](/zh-CN/install/updating)。
</Accordion>
@ -426,35 +429,35 @@ x-i18n:
任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH/Tailscale 访问 Gateway 网关。
指南：[exe.dev](/zh-CN/install/exe-dev)、[Hetzner](/zh-CN/install/hetzner)、[Fly.io](/zh-CN/install/fly)。
远程访问：[Gateway 网关远程访问](/zh-CN/gateway/remote)。
远程访问：[Gateway 网关远程](/zh-CN/gateway/remote)。
</Accordion>
<Accordion title="云/VPS 安装指南在哪里？">
我们维护了一个包含常见提供商的**托管中心**。选择一个并按照指南操作：
<Accordion title="云端/VPS 安装指南在哪里？">
我们维护一个包含常见提供商的 **托管中心**。选择一个并按照指南操作：
- [VPS 托管](/zh-CN/vps)（所有提供商集中在一处）
- [Fly.io](/zh-CN/install/fly)
- [Hetzner](/zh-CN/install/hetzner)
- [exe.dev](/zh-CN/install/exe-dev)
云端的工作方式：**Gateway 网关运行在服务器上**，你通过 Control UI（或 Tailscale/SSH）
从笔记本电脑/手机访问它。你的状态 + 工作区
存在服务器上，所以请把主机当作事实来源并做好备份。
它在云端的工作方式：**Gateway 网关运行在服务器上**，你通过 Control UI
（或 Tailscale/SSH）从笔记本/手机访问它。你的状态 + 工作区
存在服务器上，因此请将主机视为真实来源并做好备份。
你可以将**节点**（Mac/iOS/Android/headless）配对到该云端 Gateway 网关，以访问
本地屏幕/摄像头/canvas，或在笔记本电脑上运行命令，同时让
你可以将 **节点**（Mac/iOS/Android/headless）配对到该云端 Gateway 网关，以访问
本地屏幕/摄像头/canvas，或在你的笔记本上运行命令，同时让
Gateway 网关保留在云端。
中心：[平台](/zh-CN/platforms)。远程访问：[Gateway 网关远程访问](/zh-CN/gateway/remote)。
中心：[平台](/zh-CN/platforms)。远程访问：[Gateway 网关远程](/zh-CN/gateway/remote)。
节点：[节点](/zh-CN/nodes)、[节点 CLI](/zh-CN/cli/nodes)。
</Accordion>
<Accordion title="我可以让 OpenClaw 自己更新自己吗？">
<Accordion title="我可以让 OpenClaw 自行更新吗？">
简短回答：**可以，但不推荐**。更新流程可能会重启
Gateway 网关（这会断开活跃会话），可能需要干净的 git checkout，
并且可能提示确认。更安全的做法：由操作者从 shell 运行更新。
Gateway 网关（这会断开活动会话），可能需要干净的 git checkout，并且
可能提示确认。更安全的做法：由操作者从 shell 运行更新。
使用 CLI：
@ -478,34 +481,34 @@ x-i18n:
</Accordion>
<Accordion title="新手引导实际会做什么？">
`openclaw onboard` 是推荐的设置路径。在**本地模式**下，它会引导你完成：
`openclaw onboard` 是推荐的设置路径。在 **本地模式** 中，它会引导你完成：
- **模型/认证设置**（提供商 OAuth、API keys、Anthropic setup-token，以及 LM Studio 等本地模型选项）
- **工作区**位置 + 引导文件
- **模型/凭证设置**（提供商 OAuth、API key、Anthropic setup-token，以及 LM Studio 等本地模型选项）
- **工作区** 位置 + 引导文件
- **Gateway 网关设置**（bind/port/auth/tailscale）
- **渠道**（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage，以及 QQ Bot 等内置渠道插件）
- **Daemon 安装**（macOS 上的 LaunchAgent；Linux/WSL2 上的 systemd 用户单元）
- **健康检查**和 **skills** 选择
- **守护进程安装**（macOS 上的 LaunchAgent；Linux/WSL2 上的 systemd 用户单元）
- **健康检查** 和 **skills** 选择
如果你配置的模型未知或缺少认证，它也会发出警告。
如果你配置的模型未知或缺少凭证，它也会发出警告。
</Accordion>
<Accordion title="运行这个需要 Claude 或 OpenAI 订阅吗？">
不需要。你可以使用 **API keys**（Anthropic/OpenAI/其他）或
**仅本地模型**运行 OpenClaw，这样你的数据会保留在你的设备上。订阅（Claude
Pro/Max 或 OpenAI Codex）是用于认证这些提供商的可选方式。
不需要。你可以用 **API key**（Anthropic/OpenAI/其他）运行 OpenClaw，或者用
**纯本地模型**，让你的数据留在你的设备上。订阅（Claude
Pro/Max 或 OpenAI Codex）是这些提供商的可选认证方式。
对 OpenClaw 中的 Anthropic，实际划分是：
对 OpenClaw 中的 Anthropic，实际区分是：
- **Anthropic API key**：正常的 Anthropic API 计费
- **OpenClaw 中的 Claude CLI / Claude 订阅认证**：Anthropic 员工
告诉我们此用法已再次允许，且除非 Anthropic 发布新
政策，否则 OpenClaw 会将 `claude -p`
用法视为此集成的已批准用法
- **OpenClaw 中的 Claude CLI / Claude 订阅凭证**：Anthropic 员工
告诉我们这种用法再次被允许，并且 OpenClaw 会将 `claude -p`
用法视为对此集成已获准，除非 Anthropic 发布新的
策略
对长期运行的 gateway 主机，Anthropic API keys 仍是更
可预测的设置。OpenAI Codex OAuth 明确支持用于 OpenClaw 等外部
对于长期运行的 Gateway 网关主机，Anthropic API key 仍然是更
可预测的设置。OpenAI Codex OAuth 明确支持 OpenClaw 这样的外部
工具。
OpenClaw 还支持其他托管订阅式选项，包括
@ -519,25 +522,25 @@ x-i18n:
</Accordion>
<Accordion title="可以不使用 API key，直接使用 Claude Max 订阅吗？">
<Accordion title="可以在没有 API key 的情况下使用 Claude Max 订阅吗？">
可以。
Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法已再次允许，因此
除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude 订阅认证和 `claude -p`
用法视为此集成的已批准用法。如果你想要最可预测的服务器端设置，
请改用 Anthropic API key。
Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此
OpenClaw 会将 Claude 订阅凭证和 `claude -p` 用法视为
对此集成已获准，除非 Anthropic 发布新的策略。如果你想要
最可预测的服务端设置，请改用 Anthropic API key。
</Accordion>
<Accordion title="你们支持 Claude 订阅认证（Claude Pro 或 Max）吗？">
<Accordion title="你们支持 Claude 订阅凭证（Claude Pro 或 Max）吗？">
支持。
Anthropic 员工告诉我们此用法已再次允许，因此除非
Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p`
用法视为此集成的已批准用法。
Anthropic 员工告诉我们这种用法再次被允许，因此 OpenClaw 会将
Claude CLI 复用和 `claude -p` 用法视为对此集成已获准，
除非 Anthropic 发布新的策略。
Anthropic setup-token 仍可作为受支持的 OpenClaw token 路径，但 OpenClaw 现在会在可用时优先使用 Claude CLI 复用和 `claude -p`。
对生产或多用户工作负载，Anthropic API key 认证仍是
Anthropic setup-token 仍可作为受支持的 OpenClaw token 路径使用，但 OpenClaw 现在在可用时更偏向 Claude CLI 复用和 `claude -p`。
对于生产或多用户工作负载，Anthropic API key 凭证仍然是
更安全、更可预测的选择。如果你想在 OpenClaw 中使用其他订阅式托管
选项，请参阅 [OpenAI](/zh-CN/providers/openai)、[Qwen / Model
Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [GLM
@ -551,72 +554,75 @@ x-i18n:
<AccordionGroup>
<Accordion title="为什么我会看到来自 Anthropic 的 HTTP 429 rate_limit_error？">
这意味着你的**Anthropic 配额/速率限制**已在当前窗口内耗尽。如果你
使用 **Claude CLI**，请等待窗口重置或升级你的计划。如果你
这意味着你的 **Anthropic 配额/速率限制** 已在当前窗口耗尽。如果你
使用 **Claude CLI**，请等待窗口重置或升级你的套餐。如果你
使用 **Anthropic API key**，请在 Anthropic Console
检查用量/计费，并按需提高限制。
检查使用量/账单，并按需提高限制。
如果消息具体是：
`Extra usage is required for long context requests`，则该请求正在尝试使用
Anthropic 的 1M context beta（`context1m: true`）。只有当你的
凭证符合长上下文计费条件（API key 计费，或启用了 Extra Usage 的
OpenClaw Claude-login 路径）时，这才有效。
`Extra usage is required for long context requests`，则请求正在尝试使用
Anthropic 的 1M 上下文 beta（`context1m: true`）。这只有在你的
凭证具备长上下文计费资格时才有效（API key 计费，或启用 Extra Usage 的
OpenClaw Claude-login 路径）。
提示：设置一个**后备模型**，这样当提供商被限速时，OpenClaw 仍可继续回复。
提示：设置一个**备用模型**，这样当某个提供商受到速率限制时，OpenClaw 仍可继续回复。
请参阅 [Models](/zh-CN/cli/models)、[OAuth](/zh-CN/concepts/oauth) 和
[/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。
</Accordion>
<Accordion title="是否支持 AWS Bedrock？">
是。OpenClaw 内置了 **Amazon Bedrock (Converse)** 提供商。存在 AWS 环境变量标记时，OpenClaw 可以自动发现 Bedrock 流式/文本目录，并将其作为隐式 `amazon-bedrock` 提供商合并；否则，你可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled`，或添加手动提供商条目。请参阅 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [模型提供商](/zh-CN/providers/models)。如果你更偏好托管密钥流程，在 Bedrock 前放置一个兼容 OpenAI 的代理仍是有效选项。
<Accordion title="支持 AWS Bedrock 吗？">
是的。OpenClaw 内置了 **Amazon Bedrock (Converse)** 提供商。存在 AWS 环境标记时，OpenClaw 可以自动发现流式/文本 Bedrock 目录，并将其合并为隐式的 `amazon-bedrock` 提供商；否则，你可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled`，或添加手动提供商条目。请参阅 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [模型提供商](/zh-CN/providers/models)。如果你偏好托管式密钥流程，在 Bedrock 前面使用 OpenAI 兼容代理仍然是有效选项。
</Accordion>
<Accordion title="Codex 凭证如何工作？">
OpenClaw 支持通过 OAuth（ChatGPT 登录）使用 **OpenAI Code (Codex)**。通过默认 PI runner 使用
`openai-codex/gpt-5.5` 来进行 Codex OAuth。使用
`openai/gpt-5.5` 可直接通过 OpenAI API 密钥访问。GPT-5.5 也可以通过 `openai-codex/gpt-5.5` 使用
订阅/OAuth，或通过 `openai/gpt-5.5` 和 `agentRuntime.id: "codex"` 运行原生 Codex app-server。
OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code (Codex)**。常见设置使用
`openai/gpt-5.5` 并设置 `agentRuntime.id: "codex"`：
ChatGPT/Codex 订阅凭证加原生 Codex 应用服务器执行。仅当你希望通过默认
PI 运行器使用 Codex OAuth 时，才使用 `openai-codex/gpt-5.5`。不带 Codex 运行时覆盖时，使用
`openai/gpt-5.5` 可直接通过 OpenAI API key 访问。
请参阅 [模型提供商](/zh-CN/concepts/model-providers) 和 [新手引导（CLI）](/zh-CN/start/wizard)。
</Accordion>
<Accordion title="为什么 OpenClaw 仍会提到 openai-codex？">
`openai-codex` 是 ChatGPT/Codex OAuth 的提供商和凭证配置 ID。
`openai-codex` 是 ChatGPT/Codex OAuth 的提供商和凭证配置文件 id。
它也是 Codex OAuth 的显式 PI 模型前缀：
- `openai/gpt-5.5` = PI 中当前直接使用 OpenAI API 密钥的路径
- `openai-codex/gpt-5.5` = PI 中的 Codex OAuth 路径
- `openai/gpt-5.5` + `agentRuntime.id: "codex"` = 原生 Codex app-server 路径
- `openai-codex:...` = 凭证配置 ID，而不是模型引用
- `openai/gpt-5.5` + `agentRuntime.id: "codex"` = 使用原生 Codex 运行时的 ChatGPT/Codex 订阅凭证
- `openai-codex/gpt-5.5` = PI 中的 Codex OAuth 路由
- 不带 Codex 运行时覆盖的 `openai/gpt-5.5` = PI 中的直接 OpenAI API key 路由
- `openai-codex:...` = 凭证配置文件 id，不是模型引用
如果你想使用直接的 OpenAI Platform 计费/限额路径，请设置
`OPENAI_API_KEY`。如果你想使用 ChatGPT/Codex 订阅凭证，请使用
`openclaw models auth login --provider openai-codex` 登录，并在 PI 运行中使用
`openai-codex/*` 模型引用。
`OPENAI_API_KEY`。如果你想使用 ChatGPT/Codex 订阅凭证，请通过
`openclaw models auth login --provider openai-codex` 登录。对于原生 Codex
运行时，请保持模型引用为 `openai/gpt-5.5`，并设置
`agentRuntime.id: "codex"`。仅在 PI
运行中使用 `openai-codex/*` 模型引用。
</Accordion>
<Accordion title="为什么 Codex OAuth 限额可能与 ChatGPT 网页版不同？">
Codex OAuth 使用由 OpenAI 管理、依赖套餐的配额窗口。实践中，
这些限额可能与 ChatGPT 网站/应用体验不同，即使两者绑定的是同一个账户。
<Accordion title="为什么 Codex OAuth 限额可能不同于 ChatGPT 网页版？">
Codex OAuth 使用 OpenAI 管理的、依赖套餐的配额窗口。实际使用中，
这些限额可能不同于 ChatGPT 网站/应用体验，即使二者绑定到同一账户。
OpenClaw 可以在 `openclaw models status` 中显示当前可见的提供商用量/配额窗口，
但它不会凭空创建或规范化 ChatGPT 网页版权益为直接 API 访问。如果你想使用直接的 OpenAI Platform
计费/限额路径，请使用带 API 密钥的 `openai/*`。
但它不会虚构或规范化 ChatGPT 网页版权益为直接 API 访问。如果你想使用直接的 OpenAI Platform
计费/限额路径，请使用带 API key 的 `openai/*`。
</Accordion>
<Accordion title="你们支持 OpenAI 订阅凭证（Codex OAuth）吗？">
支持。OpenClaw 完全支持 **OpenAI Code (Codex) 订阅 OAuth**。
<Accordion title="支持 OpenAI 订阅凭证（Codex OAuth）吗？">
是的。OpenClaw 完全支持 **OpenAI Code (Codex) 订阅 OAuth**。
OpenAI 明确允许在 OpenClaw 这类外部工具/工作流中使用订阅 OAuth。
新手引导可以为你运行 OAuth 流程。
新手引导可以替你运行 OAuth 流程。
请参阅 [OAuth](/zh-CN/concepts/oauth)、[模型提供商](/zh-CN/concepts/model-providers) 和 [新手引导（CLI）](/zh-CN/start/wizard)。
</Accordion>
<Accordion title="如何设置 Gemini CLI OAuth？">
Gemini CLI 使用**插件凭证流程**，而不是在 `openclaw.json` 中配置客户端 ID 或密钥。
Gemini CLI 使用**插件凭证流程**，而不是 `openclaw.json` 中的客户端 id 或 secret。
步骤：
@ -628,36 +634,36 @@ x-i18n:
4. 登录后的默认模型：`google-gemini-cli/gemini-3-flash-preview`
5. 如果请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`
这会将 OAuth 令牌存储在 Gateway 网关主机上的凭证配置中。详情：[模型提供商](/zh-CN/concepts/model-providers)。
这会把 OAuth 令牌存储在 Gateway 网关主机上的凭证配置文件中。详情：[模型提供商](/zh-CN/concepts/model-providers)。
</Accordion>
<Accordion title="本地模型适合日常聊天吗？">
通常不适合。OpenClaw 需要大上下文和强安全性；小显存显卡会截断并泄漏。如果必须使用，请在本地运行你能承载的**最大**模型构建（LM Studio），并查看 [/gateway/local-models](/zh-CN/gateway/local-models)。更小/量化的模型会增加提示注入风险 - 请参阅 [安全](/zh-CN/gateway/security)。
通常不适合。OpenClaw 需要大上下文和强安全性；小显存卡会截断并泄漏。如果必须使用，请在本地运行你能运行的**最大**模型构建（LM Studio），并参阅 [/gateway/local-models](/zh-CN/gateway/local-models)。更小/量化模型会增加提示注入风险 - 请参阅 [安全](/zh-CN/gateway/security)。
</Accordion>
<Accordion title="如何让托管模型流量保留在特定区域？">
选择绑定区域的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供美国托管选项；选择美国托管变体以将数据保留在区域内。你仍然可以通过使用 `models.mode: "merge"` 将 Anthropic/OpenAI 与这些提供商一起列出，这样在尊重你选择的区域化提供商的同时，后备模型仍可用。
<Accordion title="如何把托管模型流量限制在特定区域？">
选择区域固定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供美国托管选项；选择美国托管变体可让数据保留在区域内。你仍可通过使用 `models.mode: "merge"` 同时列出 Anthropic/OpenAI，使备用模型在尊重你选择的区域化提供商的同时保持可用。
</Accordion>
<Accordion title="我必须买一台 Mac Mini 才能安装它吗？">
不需要。OpenClaw 可在 macOS 或 Linux 上运行（Windows 通过 WSL2）。Mac mini 是可选的 - 有些人
会买一台作为常开主机，但小型 VPS、家庭服务器或 Raspberry Pi 级别的设备也可以。
<Accordion title="我必须购买 Mac Mini 才能安装吗？">
不需要。OpenClaw 可在 macOS 或 Linux 上运行（Windows 通过 WSL2）。Mac mini 是可选的 - 有些人会
买一台作为常开主机，但小型 VPS、家用服务器或 Raspberry Pi 级别设备也可以。
你只在需要 **macOS 专属工具**时才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）- BlueBubbles 服务器可在任何 Mac 上运行，Gateway 网关可在 Linux 或其他地方运行。如果你想使用其他 macOS 专属工具，请在 Mac 上运行 Gateway 网关，或配对一个 macOS 节点。
只有在使用 **macOS 专用工具**时才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）- BlueBubbles 服务器可在任意 Mac 上运行，而 Gateway 网关可以在 Linux 或其他位置运行。如果你想使用其他 macOS 专用工具，请在 Mac 上运行 Gateway 网关，或配对一个 macOS 节点。
文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[节点](/zh-CN/nodes)、[Mac 远程模式](/zh-CN/platforms/mac/remote)。
</Accordion>
<Accordion title="我需要 Mac mini 才能支持 iMessage 吗？">
你需要登录了 Messages 的**某台 macOS 设备**。它**不**必须是 Mac mini -
任何 Mac 都可以。**使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）来支持 iMessage - BlueBubbles 服务器在 macOS 上运行，而 Gateway 网关可以在 Linux 或其他地方运行。
<Accordion title="iMessage 支持需要 Mac mini 吗？">
你需要**某台 macOS 设备**登录 Messages。它**不一定**必须是 Mac mini -
任意 Mac 都可以。对于 iMessage，**使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）- BlueBubbles 服务器在 macOS 上运行，而 Gateway 网关可以在 Linux 或其他位置运行。
常见设置：
- 在 Linux/VPS 上运行 Gateway 网关，并在任何已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。
- 如果你想要最简单的单机设置，就在 Mac 上运行所有组件。
- 在 Linux/VPS 上运行 Gateway 网关，并在任意已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。
- 如果想要最简单的单机设置，可以把所有内容都运行在 Mac 上。
文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[节点](/zh-CN/nodes)、
[Mac 远程模式](/zh-CN/platforms/mac/remote)。
@ -666,12 +672,12 @@ x-i18n:
<Accordion title="如果我买一台 Mac mini 来运行 OpenClaw，可以把它连接到我的 MacBook Pro 吗？">
可以。**Mac mini 可以运行 Gateway 网关**，你的 MacBook Pro 可以作为
**节点**（配套设备）连接。节点不运行 Gateway 网关 - 它们会提供额外
能力，比如屏幕/摄像头/canvas，以及在该设备上的 `system.run`。
**节点**（配套设备）连接。节点不运行 Gateway 网关 - 它们提供额外
能力，例如该设备上的屏幕/摄像头/canvas 和 `system.run`。
常见模式：
- Gateway 网关在 Mac mini 上运行（常开）。
- Gateway 网关运行在 Mac mini 上（常开）。
- MacBook Pro 运行 macOS 应用或节点主机，并与 Gateway 网关配对。
- 使用 `openclaw nodes status` / `openclaw nodes list` 查看它。
@ -680,8 +686,8 @@ x-i18n:
</Accordion>
<Accordion title="可以使用 Bun 吗？">
**不推荐**使用 Bun。我们观察到运行时错误，尤其是在 WhatsApp 和 Telegram 上。
使用 **Node** 运行稳定的 Gateway 网关。
**不推荐**使用 Bun。我们发现了运行时错误，尤其是在 WhatsApp 和 Telegram 中。
使用 **Node** 可获得稳定的 Gateway 网关。
如果你仍想试验 Bun，请在非生产 Gateway 网关上进行，
且不要使用 WhatsApp/Telegram。
@ -691,7 +697,7 @@ x-i18n:
<Accordion title="Telegram：allowFrom 中应该填什么？">
`channels.telegram.allowFrom` 是**真人发送者的 Telegram 用户 ID**（数字）。它不是机器人用户名。
设置过程只要求数字用户 ID。如果你的配置中已有旧版 `@username` 条目，`openclaw doctor --fix` 可以尝试解析它们。
设置流程只要求数字用户 ID。如果你的配置中已有旧版 `@username` 条目，`openclaw doctor --fix` 可以尝试解析它们。
更安全（无需第三方机器人）：
@ -710,11 +716,11 @@ x-i18n:
</Accordion>
<Accordion title="多个人可以用同一个 WhatsApp 号码连接不同的 OpenClaw 实例吗？">
可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信**（对等方 `kind: "direct"`，发送者 E.164 格式如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都有自己的工作区和会话存储。回复仍来自**同一个 WhatsApp 账户**，且私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）对每个 WhatsApp 账户是全局的。请参阅 [多智能体路由](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。
可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信**（peer `kind: "direct"`，发送者 E.164 如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都有自己的工作区和会话存储。回复仍来自**同一个 WhatsApp 账户**，并且私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）对每个 WhatsApp 账户是全局的。请参阅 [多智能体路由](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。
</Accordion>
<Accordion title='可以同时运行一个“快速聊天”智能体和一个“用 Opus 编码”的智能体吗？'>
可以。使用多智能体路由：为每个智能体设置自己的默认模型，然后将入站路由（提供商账户或特定对等方）绑定到各个智能体。示例配置位于 [多智能体路由](/zh-CN/concepts/multi-agent)。另请参阅 [Models](/zh-CN/concepts/models) 和 [配置](/zh-CN/gateway/configuration)。
<Accordion title='可以运行一个“快速聊天”智能体和一个“用于编码的 Opus”智能体吗？'>
可以。使用多智能体路由：为每个智能体设置自己的默认模型，然后把入站路由（提供商账户或特定 peer）绑定到每个智能体。示例配置位于 [多智能体路由](/zh-CN/concepts/multi-agent)。另请参阅 [Models](/zh-CN/concepts/models) 和 [配置](/zh-CN/gateway/configuration)。
</Accordion>
<Accordion title="Homebrew 可以在 Linux 上使用吗？">
@ -727,25 +733,25 @@ x-i18n:
brew install <formula>
```
如果你通过 systemd 运行 OpenClaw，请确保服务 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样通过 `brew` 安装的工具才能在非登录 shell 中解析。
最新构建还会在 Linux systemd 服务中预置常见用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在设置时遵循 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。
如果你通过 systemd 运行 OpenClaw，请确保服务 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样非登录 shell 中也能解析 `brew` 安装的工具。
最新构建还会在 Linux systemd 服务中预置常见用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在设置了 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR` 时尊重它们。
</Accordion>
<Accordion title="可修改的 git 安装与 npm 安装的区别">
- **可修改（git）安装：** 完整源码检出，可编辑，最适合贡献者。
你在本地运行构建，并可以修补代码/文档。
- **npm 安装：** 全局 CLI 安装，无仓库，最适合“直接运行”。
<Accordion title="可改造的 git 安装和 npm 安装有什么区别">
- **可改造（git）安装：**完整源码检出，可编辑，最适合贡献者。
你可以在本地运行构建并修补代码/文档。
- **npm 安装：**全局 CLI 安装，无仓库，最适合“只想运行它”的场景。
更新来自 npm dist-tags。
文档：[入门指南](/zh-CN/start/getting-started)、[更新](/zh-CN/install/updating)。
</Accordion>
<Accordion title="之后可以在 npm 和 git 安装之间切换吗？">
可以。当 OpenClaw 已安装时，使用 `openclaw update --channel ...`。
<Accordion title="以后可以在 npm 和 git 安装之间切换吗？">
可以。OpenClaw 已安装时，使用 `openclaw update --channel ...`。
这**不会删除你的数据** - 它只会更改 OpenClaw 代码安装。
你的状态（`~/.openclaw`）和工作区（`~/.openclaw/workspace`）保持不变。
你的状态（`~/.openclaw`）和工作区（`~/.openclaw/workspace`）会保持不变。
从 npm 切换到 git：
@ -759,9 +765,9 @@ x-i18n:
openclaw update --channel stable
```
添加 `--dry-run` 可先预览计划的模式切换。更新器会运行
Doctor 后续步骤，为目标渠道刷新插件源，并
重启 Gateway 网关，除非你传入 `--no-restart`。
添加 `--dry-run` 可先预览计划中的模式切换。更新器会运行
Doctor 后续操作，为目标渠道刷新插件源，并
重启 gateway，除非你传入 `--no-restart`。
安装器也可以强制使用任一模式：
@ -774,61 +780,61 @@ x-i18n:
</Accordion>
<Accordion title="我应该在笔记本电脑还是 VPS 上运行 Gateway 网关？">
简短答案：**如果你想要 24/7 可靠性，请使用 VPS**。如果你想要
最低摩擦，且可以接受睡眠/重启，就在本地运行。
<Accordion title="应该把 Gateway 网关运行在我的笔记本电脑上还是 VPS 上？">
简短回答：**如果你想要 24/7 可靠性，请使用 VPS**。如果你想要
最低操作成本，并且可以接受睡眠/重启，就在本地运行。
**笔记本电脑（本地 Gateway 网关）**
- **优点：** 无服务器成本，可直接访问本地文件，有可见的浏览器窗口。
- **缺点：** 睡眠/网络中断 = 断开连接，操作系统更新/重启会中断，必须保持唤醒。
- **优点：**无服务器成本，可直接访问本地文件，实时浏览器窗口。
- **缺点：**睡眠/网络中断 = 断开连接，操作系统更新/重启会中断，必须保持唤醒。
**VPS / 云**
- **优点：** 常开，网络稳定，没有笔记本睡眠问题，更容易持续运行。
- **缺点：** 通常以无头模式运行（使用截图），只能远程访问文件，必须通过 SSH 更新。
- **优点：** 始终在线、网络稳定、没有笔记本休眠问题，更容易持续运行。
- **缺点：** 通常以无头模式运行（使用截图），只能远程访问文件，你必须通过 SSH 更新。
**OpenClaw 特定说明：** WhatsApp/Telegram/Slack/Mattermost/Discord 都可以很好地在 VPS 上运行。唯一真正的权衡是**无头浏览器**与可见窗口。请参阅 [浏览器](/zh-CN/tools/browser)。
**OpenClaw 专属说明：** WhatsApp/Telegram/Slack/Mattermost/Discord 都可以很好地在 VPS 上运行。唯一真正的取舍是 **无头浏览器** 与可见窗口。参见 [浏览器](/zh-CN/tools/browser)。
**推荐默认选择：**如果你以前遇到过 Gateway 网关断连，选择 VPS。本地运行适合你正在主动使用 Mac，并且需要本地文件访问或带可见浏览器的 UI 自动化的情况。
**推荐默认选择：** 如果你以前遇到过 Gateway 网关断连，请使用 VPS。本地运行适合你正在主动使用 Mac，并且需要本地文件访问或带可见浏览器的 UI 自动化时。
</Accordion>
<Accordion title="在专用机器上运行 OpenClaw 有多重要？">
不是必需的，但**建议这样做以获得更好的可靠性和隔离性**。
不是必需的，但**为了可靠性和隔离性，建议这样做**。
- **专用主机（VPS/Mac mini/Pi）：**始终在线，较少受到睡眠/重启中断影响，权限更干净，也更容易持续运行。
- **共享笔记本/台式机：**完全适合测试和主动使用，但机器睡眠或更新时会暂停。
- **专用主机（VPS/Mac mini/Pi）：** 始终在线，休眠/重启中断更少，权限更清晰，更容易持续运行。
- **共用笔记本/台式机：** 用于测试和主动使用完全没问题，但机器休眠或更新时会暂停。
如果你想兼顾两者，可以将 Gateway 网关放在专用主机上，并将你的笔记本配对为本地屏幕/摄像头/exec 工具使用的**节点**。参见 [节点](/zh-CN/nodes)。
安全指导请阅读 [安全](/zh-CN/gateway/security)。
如果你想兼顾两者，请将 Gateway 网关放在专用主机上，并将你的笔记本配对为本地屏幕/摄像头/执行工具的**节点**。参见 [节点](/zh-CN/nodes)。
如需安全指南，请阅读 [安全](/zh-CN/gateway/security)。
</Accordion>
<Accordion title="VPS 的最低要求和推荐操作系统是什么？">
OpenClaw 很轻量。对于基础 Gateway 网关 + 一个聊天渠道：
- **绝对最低要求：**1 个 vCPU，1GB RAM，约 500MB 磁盘。
- **推荐：**1-2 个 vCPU，2GB RAM 或更多，以留出余量（日志、媒体、多个渠道）。节点工具和浏览器自动化可能比较占资源。
- **绝对最低要求：** 1 vCPU、1GB RAM、约 500MB 磁盘。
- **推荐：** 1-2 vCPU、2GB RAM 或更多，以留出余量（日志、媒体、多个渠道）。节点工具和浏览器自动化可能会消耗较多资源。
操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在这里测试最充分。
操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在这些系统上测试最充分。
文档：[Linux](/zh-CN/platforms/linux)、[VPS 托管](/zh-CN/vps)。
</Accordion>
<Accordion title="我可以在 VM 中运行 OpenClaw 吗？有什么要求？">
可以。把 VM 当作 VPS 一样对待：它需要始终在线、可访问，并且有足够的
<Accordion title="我可以在 VM 中运行 OpenClaw 吗？需要什么要求？">
可以。将 VM 视同 VPS：它需要始终在线、可访问，并且有足够的
RAM 来运行 Gateway 网关和你启用的任何渠道。
基准指导：
基线指南：
- **绝对最低要求：**1 个 vCPU，1GB RAM。
- **推荐：**如果你运行多个渠道、浏览器自动化或媒体工具，使用 2GB RAM 或更多。
- **操作系统：**Ubuntu LTS 或其他现代 Debian/Ubuntu。
- **绝对最低要求：** 1 vCPU、1GB RAM。
- **推荐：** 如果你运行多个渠道、浏览器自动化或媒体工具，请使用 2GB RAM 或更多。
- **操作系统：** Ubuntu LTS 或其他现代 Debian/Ubuntu。
如果你使用 Windows，**WSL2 是最简单的 VM 风格设置**，并且具有最佳工具
兼容性。参见 [Windows](/zh-CN/platforms/windows)、[VPS 托管](/zh-CN/vps)。
如果你使用 Windows，**WSL2 是最简单的 VM 风格设置**，并且工具链
兼容性最好。参见 [Windows](/zh-CN/platforms/windows)、[VPS 托管](/zh-CN/vps)。
如果你在 VM 中运行 macOS，请参见 [macOS VM](/zh-CN/install/macos-vm)。
</Accordion>

276
docs/zh-CN/help/faq-models.md
View File

@ -2,51 +2,51 @@
read_when:
- 选择或切换模型，配置别名
- 调试模型故障转移 / “所有模型均失败”
- 了解凭证配置档案及其管理方式
- 了解凭证配置文件以及如何管理它们
sidebarTitle: Models FAQ
summary: 常见问题：模型默认值、选择、别名、切换、故障转移和凭证配置文件
summary: 常见问题：模型默认设置、选择、别名、切换、故障转移和认证配置文件
title: 常见问题：模型和凭证
x-i18n:
generated_at: "2026-04-29T10:59:55Z"
generated_at: "2026-05-02T02:37:17Z"
model: gpt-5.5
provider: openai
source_hash: eaa72bf66d3f1528f95762e2a2763bc2f6bfddbc1d4c24a9ec2df7f943ebc14b
source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884
source_path: help/faq-models.md
workflow: 16
---
模型和身份验证配置文件问答。有关设置、会话、Gateway 网关、渠道和
模型和认证配置文件问答。关于设置、会话、Gateway 网关、渠道和
故障排除，请参阅主 [常见问题](/zh-CN/help/faq)。
## Models：默认值、选择、别名、切换
<AccordionGroup>
<Accordion title='什么是“默认模型”？'>
OpenClaw 的默认模型就是你设置为以下项的内容：
OpenClaw 的默认模型就是你设置为以下内容的模型：
```
agents.defaults.model.primary
```
模型以 `provider/model` 形式引用（例如：`openai/gpt-5.5` 或 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才会回退到已配置的默认提供商；这是已弃用的兼容路径。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个已过期的、已移除提供商的默认值。你仍应**显式**设置 `provider/model`。
模型以 `provider/model` 形式引用（示例：`openai/gpt-5.5` 或 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试精确模型 ID 的唯一已配置提供商匹配，最后才会回退到已配置的默认提供商，这是一条已弃用的兼容路径。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露已过时的已移除提供商默认值。你仍应**显式**设置 `provider/model`。
</Accordion>
<Accordion title="你推荐使用什么模型？">
<Accordion title="你推荐什么模型？">
**推荐默认值：** 使用你的提供商栈中可用的最强最新一代模型。
**对于启用工具或处理不受信任输入的智能体：** 优先考虑模型能力，而不是成本。
**对于启用工具或处理不受信任输入的智能体：** 优先考虑模型能力而不是成本。
**对于常规/低风险聊天：** 使用更便宜的回退模型，并按智能体角色路由。
MiniMax 有自己的文档：[MiniMax](/zh-CN/providers/minimax) 和
[本地模型](/zh-CN/gateway/local-models)。
经验法则：对高风险工作使用你**负担得起的最佳模型**，对常规聊天或摘要使用更便宜的
模型。你可以按智能体路由模型，并使用子智能体来
经验法则：对于高风险工作，使用你**负担得起的最佳模型**；对于常规聊天或摘要，使用更便宜的
模型。你可以为每个智能体路由模型，并使用子智能体来
并行处理长任务（每个子智能体都会消耗 token）。请参阅 [Models](/zh-CN/concepts/models) 和
[子智能体](/zh-CN/tools/subagents)。
强烈警告：较弱/过度量化的模型更容易受到提示词
注入和不安全行为影响。请参阅 [安全](/zh-CN/gateway/security)。
强烈警告：较弱或过度量化的模型更容易受到提示
注入和不安全行为的影响。请参阅[安全](/zh-CN/gateway/security)。
更多背景：[Models](/zh-CN/concepts/models)。
@ -62,10 +62,10 @@ x-i18n:
- `openclaw configure --section model`（交互式）
- 编辑 `~/.openclaw/openclaw.json` 中的 `agents.defaults.model`
避免对部分对象使用 `config.apply`，除非你确实想替换整个配置。
对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。查找载荷会提供规范化路径、浅层 schema 文档/约束，以及直接子项摘要。
避免对部分对象使用 `config.apply`，除非你有意替换整个配置。
对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。lookup 载荷会给出规范化路径、浅层 schema 文档/约束，以及直接子项摘要。
用于部分更新。
如果你已经覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。
如果你确实覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 修复。
文档：[Models](/zh-CN/concepts/models)、[配置](/zh-CN/cli/configure)、[配置](/zh-CN/cli/config)、[Doctor](/zh-CN/gateway/doctor)。
@ -78,18 +78,18 @@ x-i18n:
1. 从 `https://ollama.com/download` 安装 Ollama
2. 拉取一个本地模型，例如 `ollama pull gemma4`
3. 如果你也想使用云端模型，运行 `ollama signin`
3. 如果你也想使用云模型，运行 `ollama signin`
4. 运行 `openclaw onboard` 并选择 `Ollama`
5. 选择 `Local` 或 `Cloud + Local`
注意：
- `Cloud + Local` 会提供云端模型以及你的本地 Ollama 模型
- 像 `kimi-k2.5:cloud` 这样的云端模型不需要本地拉取
- 如需手动切换，使用 `openclaw models list` 和 `openclaw models set ollama/<model>`
- `Cloud + Local` 会为你提供云模型以及你的本地 Ollama 模型
- `kimi-k2.5:cloud` 等云模型不需要本地拉取
- 如需手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/<model>`
安全注意事项：较小或高度量化的模型更容易受到提示词
注入影响。对于任何可以使用工具的机器人，我们强烈推荐使用**大模型**。
安全注意事项：较小或重度量化的模型更容易受到提示
注入影响。对于任何可以使用工具的机器人，我们强烈建议使用**大模型**。
如果你仍想使用小模型，请启用沙箱隔离和严格的工具允许列表。
文档：[Ollama](/zh-CN/providers/ollama)、[本地模型](/zh-CN/gateway/local-models)、
@ -105,8 +105,8 @@ x-i18n:
</Accordion>
<Accordion title="如何动态切换模型（不重启）？">
将 `/model` 命令作为单独消息使用：
<Accordion title="如何即时切换模型（不重启）？">
将 `/model` 命令作为独立消息使用：
```
/model sonnet
@ -118,45 +118,46 @@ x-i18n:
/model gemini-flash-lite
```
这些是内置别名。可以通过 `agents.defaults.models` 添加自定义别名。
这些是内置别名。可通过 `agents.defaults.models` 添加自定义别名。
你可以使用 `/model`、`/model list` 或 `/model status` 列出可用模型。
你可以用 `/model`、`/model list` 或 `/model status` 列出可用模型。
`/model`（以及 `/model list`）会显示一个紧凑的编号选择器。按编号选择：
`/model`（以及 `/model list`）会显示紧凑的编号选择器。按编号选择：
```
/model 3
```
你也可以为提供商强制指定特定身份验证配置文件（按会话）：
你也可以为该提供商强制指定特定认证配置文件（按会话）：
```
/model opus@anthropic:default
/model opus@anthropic:work
```
提示：`/model status` 会显示哪个智能体处于活动状态、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个身份验证配置文件。
它还会在可用时显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。
提示：`/model status` 会显示哪个智能体处于活动状态、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个认证配置文件。
可用时，它还会显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。
**如何取消固定我用 @profile 设置的配置文件？**
重新运行 `/model`，但**不要**带上 `@profile` 后缀：
重新运行 `/model`，但**不带** `@profile` 后缀：
```
/model anthropic/claude-opus-4-6
```
如果你想回到默认值，请从 `/model` 中选择它（或发送 `/model <default provider/model>`）。
使用 `/model status` 确认哪个身份验证配置文件处于活动状态。
如果你想返回默认值，请从 `/model` 中选择它（或发送 `/model <default provider/model>`）。
使用 `/model status` 确认哪个认证配置文件处于活动状态。
</Accordion>
<Accordion title="我可以用 GPT 5.5 处理日常任务，用 Codex 5.5 编码吗？">
可以。将其中一个设为默认值，并按需切换：
<Accordion title="我可以将 GPT 5.5 用于日常任务，将 Codex 5.5 用于编码吗？">
可以。将模型选择和运行时选择分开处理：
- **快速切换（按会话）：** 对当前直接 OpenAI API key 任务使用 `/model openai/gpt-5.5`，或对 GPT-5.5 Codex OAuth 任务使用 `/model openai-codex/gpt-5.5`。
- **默认值：** 对 API key 用法，将 `agents.defaults.model.primary` 设置为 `openai/gpt-5.5`；对 GPT-5.5 Codex OAuth 用法，将其设置为 `openai-codex/gpt-5.5`。
- **子智能体：** 将编码任务路由到使用不同默认模型的子智能体。
- **原生 Codex 编码智能体：** 将 `agents.defaults.model.primary` 设置为 `openai/gpt-5.5`，并将 `agents.defaults.agentRuntime.id` 设置为 `"codex"`。当你想使用 ChatGPT/Codex 订阅认证时，使用 `openclaw models auth login --provider openai-codex` 登录。
- **通过 PI 直接执行 OpenAI API 任务：** 使用 `/model openai/gpt-5.5`，不要设置 Codex 运行时覆盖，并配置 `OPENAI_API_KEY`。
- **通过 PI 使用 Codex OAuth：** 仅当你有意使用带 Codex OAuth 的普通 PI runner 时，才使用 `/model openai-codex/gpt-5.5`。
- **子智能体：** 将编码任务路由到一个仅 Codex 的智能体，该智能体有自己的模型和 `agentRuntime` 默认值。
请参阅 [Models](/zh-CN/concepts/models) 和 [斜杠命令](/zh-CN/tools/slash-commands)。
@ -165,7 +166,7 @@ x-i18n:
<Accordion title="如何为 GPT 5.5 配置快速模式？">
使用会话开关或配置默认值：
- **按会话：** 当会话使用 `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` 时发送 `/fast on`。
- **按会话：** 当会话正在使用 `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` 时，发送 `/fast on`。
- **按模型默认值：** 将 `agents.defaults.models["openai/gpt-5.5"].params.fastMode` 或 `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` 设置为 `true`。
示例：
@ -186,9 +187,9 @@ x-i18n:
}
```
对于 OpenAI，快速模式会在支持的原生 Responses 请求上映射为 `service_tier = "priority"`。会话 `/fast` 覆盖优先于配置默认值。
对于 OpenAI，快速模式会在受支持的原生 Responses 请求上映射到 `service_tier = "priority"`。会话 `/fast` 覆盖优先级高于配置默认值。
请参阅 [思考和快速模式](/zh-CN/tools/thinking) 以及 [OpenAI 快速模式](/zh-CN/providers/openai#fast-mode)。
请参阅[思考和快速模式](/zh-CN/tools/thinking)以及 [OpenAI 快速模式](/zh-CN/providers/openai#fast-mode)。
</Accordion>
@ -200,26 +201,26 @@ x-i18n:
Model "provider/model" is not allowed. Use /model to list available models.
```
该错误会被返回，**而不是**正常回复。修复方法：将模型添加到
这个错误会**代替**正常回复返回。修复方法：将该模型添加到
`agents.defaults.models`，移除允许列表，或从 `/model list` 中选择一个模型。
</Accordion>
<Accordion title='为什么我会看到“Unknown model: minimax/MiniMax-M2.7”？'>
这意味着**提供商未配置**（未找到 MiniMax 提供商配置或身份验证
配置文件），因此无法解析模型。
这意味着**提供商尚未配置**（未找到 MiniMax 提供商配置或认证
配置文件），因此无法解析该模型。
修复清单：
修复检查清单：
1. 升级到当前 OpenClaw 版本（或从源码 `main` 运行），然后重启 Gateway 网关。
2. 确保 MiniMax 已配置（向导或 JSON），或者确保 MiniMax 身份验证
存在于环境变量/身份验证配置文件中，以便可以注入匹配的提供商
（`MINIMAX_API_KEY` 用于 `minimax`，`MINIMAX_OAUTH_TOKEN` 或存储的 MiniMax
1. 升级到当前的 OpenClaw 版本（或从源代码 `main` 运行），然后重启 Gateway 网关。
2. 确保 MiniMax 已配置（向导或 JSON），或者 MiniMax 认证
存在于环境变量/认证配置文件中，以便注入匹配的提供商
（`MINIMAX_API_KEY` 用于 `minimax`，`MINIMAX_OAUTH_TOKEN` 或已存储的 MiniMax
OAuth 用于 `minimax-portal`）。
3. 为你的身份验证路径使用精确模型 ID（区分大小写）：
`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed` 用于 API key
设置，或者 `minimax-portal/MiniMax-M2.7` /
`minimax-portal/MiniMax-M2.7-highspeed` 用于 OAuth 设置。
3. 为你的认证路径使用精确模型 ID（区分大小写）：
API key 设置使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`，
OAuth 设置使用 `minimax-portal/MiniMax-M2.7` /
`minimax-portal/MiniMax-M2.7-highspeed`。
4. 运行：
```bash
@ -232,8 +233,8 @@ x-i18n:
</Accordion>
<Accordion title="我可以把 MiniMax 作为默认值，并将 OpenAI 用于复杂任务吗？">
可以。将 **MiniMax 作为默认值**，并在需要时**按会话**切换模型。
<Accordion title="我可以将 MiniMax 作为默认模型，并将 OpenAI 用于复杂任务吗？">
可以。将 **MiniMax 作为默认模型**，并在需要时**按会话**切换模型。
回退用于**错误**，而不是“困难任务”，因此请使用 `/model` 或单独的智能体。
**选项 A：按会话切换**
@ -270,18 +271,18 @@ x-i18n:
</Accordion>
<Accordion title="opus / sonnet / gpt 是内置快捷方式吗？">
是。OpenClaw 附带了一些默认简写（仅在模型存在于 `agents.defaults.models` 中时应用）：
是。OpenClaw 随附一些默认简写（仅当模型存在于 `agents.defaults.models` 中时应用）：
- `opus` → `anthropic/claude-opus-4-6`
- `sonnet` → `anthropic/claude-sonnet-4-6`
- `gpt` → `openai/gpt-5.5` 用于 API key 设置，或在配置为 Codex OAuth 时指向 `openai-codex/gpt-5.5`
- `gpt` → API key 设置中的 `openai/gpt-5.5`，或配置为 Codex OAuth 时的 `openai-codex/gpt-5.5`
- `gpt-mini` → `openai/gpt-5.4-mini`
- `gpt-nano` → `openai/gpt-5.4-nano`
- `gemini` → `google/gemini-3.1-pro-preview`
- `gemini-flash` → `google/gemini-3-flash-preview`
- `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
如果你用相同名称设置自己的别名，你的值优先。
如果你设置了同名别名，则你的值优先。
</Accordion>
@ -303,12 +304,12 @@ x-i18n:
}
```
然后 `/model sonnet`（或在支持时使用 `/<alias>`）会解析为该模型 ID。
然后 `/model sonnet`（或在支持时使用 `/<alias>`）会解析到该模型 ID。
</Accordion>
<Accordion title="如何添加来自 OpenRouter 或 Z.AI 等其他提供商的模型？">
OpenRouter（按 token 付费；模型很多）：
OpenRouter（按 token 付费；许多模型）：
```json5
{
@ -336,12 +337,11 @@ x-i18n:
}
```
如果你引用某个提供商/模型，但缺少所需的提供商密钥，会收到运行时凭证错误（例如 `No API key found for provider "zai"`）。
如果你引用了某个提供商/模型，但缺少所需的提供商密钥，你会收到运行时认证错误（例如 `No API key found for provider "zai"`）。
**添加新智能体后找不到提供商的 API 密钥**
**添加新智能体后找不到提供商的 API key**
这通常表示**新智能体**的凭证存储为空。凭证按智能体隔离，并
存储在：
这通常表示**新智能体**的认证存储为空。认证按智能体区分，并存储在：
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
@ -349,121 +349,121 @@ x-i18n:
修复选项：
- 运行 `openclaw agents add <id>`，并在向导中配置凭证。
- 或者只把可移植的静态 `api_key` / `token` 配置档案从主智能体的凭证存储复制到新智能体的凭证存储。
- 对于 OAuth 配置档案，当新智能体需要自己的账号时，请从新智能体登录；否则 OpenClaw 可以透传读取默认/主智能体，而无需克隆刷新令牌。
- 运行 `openclaw agents add <id>`，并在向导中配置认证。
- 或者只把可移植的静态 `api_key` / `token` 配置文件从主智能体的认证存储复制到新智能体的认证存储。
- 对于 OAuth 配置文件，在新智能体需要自己的账号时从新智能体登录；否则 OpenClaw 可以读取默认/主智能体，而无需克隆 refresh token。
不要在多个智能体之间复用 `agentDir`；这会导致凭证/会话冲突。
不要在多个智能体之间复用 `agentDir`；这会导致认证/会话冲突。
</Accordion>
</AccordionGroup>
## 模型故障转移和 “All models failed”
## 模型故障转移和“所有模型均失败”
<AccordionGroup>
<Accordion title="故障转移如何工作？">
故障转移分两个阶段发生：
故障转移分两个阶段进行：
1. 同一提供商内的**凭证配置档案轮换**。
1. 同一提供商内的**认证配置文件轮换**。
2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。
冷却会应用于失败的配置档案（指数退避），因此即使某个提供商被限流或暂时失败，OpenClaw 也可以继续响应。
冷却时间会应用到失败的配置文件（指数退避），因此即使某个提供商受到速率限制或暂时失败，OpenClaw 也可以继续响应。
限流桶包含的不只是普通的 `429` 响应。OpenClaw
速率限制分组包含的不只是普通的 `429` 响应。OpenClaw
也会把 `Too many concurrent requests`、
`ThrottlingException`、`concurrency limit reached`、
`workers_ai ... quota limit exceeded`、`resource exhausted`，以及周期性
使用窗口限制（`weekly/monthly limit reached`）等消息视为值得触发故障转移的
限流。
`workers_ai ... quota limit exceeded`、`resource exhausted` 以及周期性
用量窗口限制（`weekly/monthly limit reached`）等消息视为值得故障转移的
速率限制。
有些看起来像计费的响应不是 `402`，而有些 HTTP `402`
响应也会留在这个临时桶中。如果提供商在 `401` 或 `403` 上返回
明确的计费文本，OpenClaw 仍可将其保留在
计费通道中，但提供商专属的文本匹配器仍限定在拥有它们的
提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。如果 `402`
消息反而看起来像可重试的使用窗口限制或
有些看起来像计费问题的响应不是 `402`，而有些 HTTP `402`
响应也会留在这个瞬态分组中。如果提供商在 `401` 或 `403` 上返回
明确的计费文本，OpenClaw 仍可以将其保留在计费通道中，
但提供商特定的文本匹配器会限定在拥有它们的
提供商范围内（例如 OpenRouter `Key limit exceeded`）。如果 `402`
消息看起来更像可重试的用量窗口或
组织/工作区支出限制（`daily limit reached, resets tomorrow`、
`organization spending limit exceeded`），OpenClaw 会将其视为
`rate_limit`，而不是长期计费禁用。
`rate_limit`，而不是长期的计费停用。
上下文溢出错误不同：诸如
`request_too_large`、`input exceeds the maximum number of tokens`、
`input token count exceeds the maximum number of input tokens`、
`input is too long for the model`，或 `ollama error: context length
exceeded` 这样的签名会留在压缩/重试路径上，而不会推进模型
`input is too long for the model` 或 `ollama error: context length
exceeded` 这样的特征会留在压缩/重试路径上，而不是推进模型
回退。
通用服务器错误文本有意比“任何包含
unknown/error 的内容”更窄。OpenClaw 确实会在提供商上下文
匹配时，把提供商范围内的临时形态视为值得触发故障转移的超时/过载信号，
例如 Anthropic 裸 `An unknown error occurred`、OpenRouter 裸
`Provider returned error`、类似 `Unhandled stop reason:
error` 的停止原因错误、带有临时服务器文本
通用服务器错误文本被刻意限定得比“任何包含
unknown/error 的内容”更窄。OpenClaw 确实会把提供商范围内的瞬态形态
视为值得故障转移的超时/过载信号，例如 Anthropic 裸
`An unknown error occurred`、OpenRouter 裸
`Provider returned error`、像 `Unhandled stop reason:
error` 这样的停止原因错误、带瞬态服务器文本
（`internal server error`、`unknown error, 520`、`upstream error`、`backend
error`）的 JSON `api_error` 载荷，以及类似 `ModelNotReadyException` 的
提供商繁忙错误。
类似 `LLM request failed with an unknown
error.` 的通用内部回退文本会保持保守，单独出现时不会触发模型回退。
error`）的 JSON `api_error` 负载，以及像 `ModelNotReadyException` 这样的
提供商繁忙错误，前提是提供商上下文匹配。
像 `LLM request failed with an unknown
error.` 这样的通用内部回退文本会保持保守，单独不会触发模型回退。
</Accordion>
<Accordion title='“No credentials found for profile anthropic:default” 是什么意思？'>
这表示系统尝试使用凭证配置档案 ID `anthropic:default`，但无法在预期的凭证存储中找到它的凭证。
<Accordion title='“No credentials found for profile anthropic:default”是什么意思？'>
这表示系统尝试使用认证配置文件 ID `anthropic:default`，但无法在预期的认证存储中找到它的凭据。
**修复检查清单：**
**修复清单：**
- **确认凭证配置档案的存放位置**（新路径与旧路径）
- **确认认证配置文件存放在哪里**（新路径与旧路径）
- 当前：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- 旧版：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）
- **确认你的环境变量已由 Gateway 网关加载**
- 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承该变量。把它放入 `~/.openclaw/.env`，或启用 `env.shellEnv`。
- **确认你的环境变量已被 Gateway 网关加载**
- 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承该变量。将它放入 `~/.openclaw/.env`，或启用 `env.shellEnv`。
- **确保你正在编辑正确的智能体**
- 多智能体设置意味着可能存在多个 `auth-profiles.json` 文件。
- **对模型/凭证状态做完整性检查**
- 使用 `openclaw models status` 查看已配置的模型以及提供商是否已完成凭证配置。
- **对模型/认证状态做完整性检查**
- 使用 `openclaw models status` 查看已配置的模型以及提供商是否已认证。
**“No credentials found for profile anthropic” 的修复检查清单**
**“No credentials found for profile anthropic”的修复清单**
这表示此次运行被固定到某个 Anthropic 凭证配置档案，但 Gateway 网关
无法在其凭证存储中找到它。
这表示本次运行固定到了某个 Anthropic 认证配置文件，但 Gateway 网关
无法在其认证存储中找到它。
- **使用 Claude CLI**
- 在 Gateway 网关主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。
- **如果你想改用 API 密钥**
- 在 **Gateway 网关主机** 上把 `ANTHROPIC_API_KEY` 放入 `~/.openclaw/.env`。
- 清除任何强制使用缺失配置档案的固定顺序：
- **如果你想改用 API key**
- 在 **Gateway 网关主机**上的 `~/.openclaw/.env` 中放入 `ANTHROPIC_API_KEY`。
- 清除任何强制使用缺失配置文件的固定顺序：
```bash
openclaw models auth order clear --provider anthropic
```
- **确认你正在 Gateway 网关主机上运行命令**
- 在远程模式下，凭证配置档案存在于 Gateway 网关机器上，而不是你的笔记本电脑上。
- **确认你是在 Gateway 网关主机上运行命令**
- 在远程模式下，认证配置文件位于 Gateway 网关机器上，而不是你的笔记本电脑上。
</Accordion>
<Accordion title="为什么它还尝试了 Google Gemini 并失败？">
如果你的模型配置包含 Google Gemini 作为回退项（或你切换到了 Gemini 简写），OpenClaw 会在模型回退期间尝试它。如果你没有配置 Google 凭证，会看到 `No API key found for provider "google"`。
<Accordion title="为什么它还尝试了 Google Gemini 并失败了？">
如果你的模型配置包含 Google Gemini 作为回退（或者你切换到了 Gemini 简写），OpenClaw 会在模型回退期间尝试它。如果你还没有配置 Google 凭据，你会看到 `No API key found for provider "google"`。
修复：提供 Google 凭证，或从 `agents.defaults.model.fallbacks` / 别名中移除/避免 Google 模型，这样回退就不会路由到那里。
修复：提供 Google 认证，或者从 `agents.defaults.model.fallbacks` / aliases 中移除/避免 Google 模型，这样回退就不会路由到那里。
**LLM 请求被拒绝：需要 thinking 签名（Google Antigravity）**
**LLM 请求被拒绝：需要 thinking signature（Google Antigravity）**
原因：会话历史包含**没有签名的 thinking 块**（通常来自
已中止/不完整的流）。Google Antigravity 要求 thinking 块带签名。
原因：会话历史包含**没有签名的 thinking block**（通常来自
已中止/不完整的流）。Google Antigravity 要求 thinking block 带有签名。
修复：OpenClaw 现在会为 Google Antigravity Claude 剥离未签名的 thinking 块。如果它仍然出现，请启动一个**新会话**，或为该智能体设置 `/thinking off`。
修复：OpenClaw 现在会为 Google Antigravity Claude 去除未签名的 thinking block。如果仍然出现，请启动一个**新会话**，或为该智能体设置 `/thinking off`。
</Accordion>
</AccordionGroup>
## 凭证配置档案：它们是什么以及如何管理
## 认证配置文件：它们是什么以及如何管理
相关：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、令牌存储、多账号模式）
相关：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、token 存储、多账号模式）
<AccordionGroup>
<Accordion title="什么是凭证配置档案？">
凭证配置档案是绑定到提供商的命名凭证记录（OAuth 或 API 密钥）。配置档案存放在：
<Accordion title="什么是认证配置文件？">
认证配置文件是绑定到提供商的命名凭据记录（OAuth 或 API key）。配置文件位于：
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
@ -471,25 +471,25 @@ x-i18n:
</Accordion>
<Accordion title="典型的配置档案 ID 有哪些？">
<Accordion title="典型的配置文件 ID 有哪些？">
OpenClaw 使用带提供商前缀的 ID，例如：
- `anthropic:default`（没有电子邮件身份时很常见）
- `anthropic:default`（没有电子邮件身份时常见）
- OAuth 身份使用 `anthropic:<email>`
- 你选择的自定义 ID（例如 `anthropic:work`）
</Accordion>
<Accordion title="我可以控制先尝试哪个凭证配置档案吗？">
可以。配置支持为配置档案提供可选元数据，并为每个提供商设置顺序（`auth.order.<provider>`）。这**不会**存储秘密；它会把 ID 映射到提供商/模式，并设置轮换顺序。
<Accordion title="我可以控制先尝试哪个认证配置文件吗？">
可以。配置支持为配置文件添加可选元数据，并按提供商设置顺序（`auth.order.<provider>`）。这不会存储密钥；它会将 ID 映射到提供商/模式，并设置轮换顺序。
如果某个配置档案处于短暂**冷却**（限流/超时/凭证失败）或较长的**禁用**状态（计费/额度不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。
如果某个配置文件处于短暂**冷却**状态（速率限制/超时/认证失败）或较长的**停用**状态（计费/余额不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。
限流冷却可以按模型限定。某个配置档案如果正在因
一个模型冷却，它仍可能可用于同一提供商上的兄弟模型，
而计费/禁用窗口仍会阻止整个配置档案。
速率限制冷却可以按模型限定。某个配置文件针对一个模型处于冷却中时，
仍可能可用于同一提供商上的相邻模型，
而计费/停用窗口仍会阻止整个配置文件。
你还可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）：
你也可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）：
```bash
# Defaults to the configured default agent (omit --agent)
@ -517,25 +517,25 @@ x-i18n:
openclaw models status --probe
```
如果存储的配置档案被显式顺序省略，probe 会为该配置档案报告
如果某个已存储的配置文件被显式顺序省略，探测会为该配置文件报告
`excluded_by_auth_order`，而不是静默尝试它。
</Accordion>
<Accordion title="OAuth 和 API 密钥有什么区别？">
OpenClaw 两者都支持：
<Accordion title="OAuth 和 API key 有什么区别？">
OpenClaw 同时支持两者：
- **OAuth** 通常会利用订阅访问权限（如适用）。
- **API 密钥** 使用按令牌计费。
- **OAuth** 通常会利用订阅访问权限（适用时）。
- **API keys** 使用按 token 计费。
向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。
向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API keys。
</Accordion>
</AccordionGroup>
## 相关
- [常见问题](/zh-CN/help/faq) — 主常见问题
- [常见问题](/zh-CN/help/faq) — 主要常见问题
- [常见问题 — 快速开始和首次运行设置](/zh-CN/help/faq-first-run)
- [模型选择](/zh-CN/concepts/model-providers)
- [模型故障转移](/zh-CN/concepts/model-failover)

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

@ -1,34 +1,45 @@
---
read_when:
- 你想使用内置的 Codex app-server harness
- 你想使用内置的 Codex app-server 框架
- 你需要 Codex harness 配置示例
- 你希望仅使用 Codex 的部署失败，而不是回退到 PI
summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次
- 你希望仅限 Codex 的部署失败，而不是回退到 PI
summary: 通过内置的 Codex app-server 测试框架运行 OpenClaw 嵌入式智能体轮次
title: Codex harness
x-i18n:
generated_at: "2026-05-01T20:39:45Z"
generated_at: "2026-05-02T02:37:18Z"
model: gpt-5.5
provider: openai
source_hash: 082c3a81eb6ef238477ca4013114a84e6ea7b188e23fb31855297beaaa7fec40
source_hash: 107f9fc0a3e8ad6a4790fc9eb68276c81d299236f11293014d2ab9bf6e235133
source_path: plugins/codex-harness.md
workflow: 16
---
内置的 `codex` 插件让 OpenClaw 可以通过 Codex app-server 运行嵌入式 agent 轮次，而不是使用内置 PI 运行框架。
内置的 `codex` 插件让 OpenClaw 通过 Codex app-server 运行嵌入式智能体轮次，而不是通过内置 PI harness。
当你希望 Codex 接管底层 agent 会话时，请使用它：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体投递，以及可见的转录镜像。
当你希望 Codex 拥有底层智能体会话时使用它：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然拥有聊天渠道、会话文件、模型选择、工具、审批、媒体投递，以及可见的转录镜像。
当源聊天轮次通过 Codex harness 运行时，如果部署没有显式配置 `messages.visibleReplies`，可见回复默认使用 OpenClaw `message` 工具。agent 仍然可以私下完成其 Codex 轮次；只有在调用 `message(action="send")` 时才会发布到渠道。设置 `messages.visibleReplies: "automatic"` 可让直接聊天的最终回复继续走旧版自动投递路径。
当源聊天轮次通过 Codex harness 运行时，如果部署未显式配置 `messages.visibleReplies`，可见回复默认使用 OpenClaw `message` 工具。智能体仍可私下完成其 Codex 轮次；只有在调用 `message(action="send")` 时才会发布到渠道。设置 `messages.visibleReplies: "automatic"` 可让直接聊天的最终回复继续走旧版自动投递路径。
Codex heartbeat 轮次默认也会获得 `heartbeat_respond` 工具，因此 agent 可以记录本次唤醒应保持安静还是发送通知，而不必在最终文本中编码该控制流。
Codex heartbeat 轮次默认也会获得 `heartbeat_respond` 工具，因此智能体可以记录此次唤醒应保持安静还是发出通知，而无需在最终文本中编码该控制流。
如果你正在尝试了解整体情况，请从
如果你正在尝试了解整体方向，请从
[Agent Runtimes](/zh-CN/concepts/agent-runtimes) 开始。简短版本是：
`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、Discord、Slack 或其他渠道仍然是通信界面。
`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、
Discord、Slack 或其他渠道仍是通信界面。
## 快速配置
要将 Codex harness 用于 GPT agent 轮次，请保持模型引用规范为 `openai/gpt-*`，启用内置 `codex` 插件，并设置 `agentRuntime.id: "codex"`：
大多数想要“OpenClaw 中的 Codex”的用户需要这条路线：使用 ChatGPT/Codex 订阅登录，然后通过原生 Codex app-server 运行时运行嵌入式智能体轮次。模型引用仍保持规范形式
`openai/gpt-*`；订阅凭证来自 Codex 账号/配置文件，而不是来自
`openai-codex/*` 模型前缀。
如果尚未登录，请先使用 Codex OAuth 登录：
```bash
openclaw models auth login --provider openai-codex
```
然后启用内置 `codex` 插件并强制使用 Codex 运行时：
```json5
{
@ -66,29 +77,29 @@ Codex heartbeat 轮次默认也会获得 `heartbeat_respond` 工具，因此 age
}
```
不要在此路径中使用 `openai-codex/gpt-*`。除非你另外强制指定运行时，否则那会通过普通 PI runner 选择 Codex OAuth。配置更改会应用于新的或重置后的会话；现有会话会保留其已记录的运行时。
当你指的是原生 Codex 运行时时，不要使用 `openai-codex/gpt-*`。该前缀是显式的“通过 PI 使用 Codex OAuth”路线。配置更改会应用于新的或重置后的会话；现有会话会保留其已记录的运行时。
## 这个插件会改变什么
## 此插件会改变什么
内置 `codex` 插件提供几个独立能力：
内置 `codex` 插件提供多个独立能力：
| 能力 | 使用方式 | 作用 |
| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex app-server 运行 OpenClaw 嵌入式 agent 轮次。 |
| 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 从消息对话中绑定和控制 Codex app-server 线程。 |
| Codex app-server 提供商/目录 | `codex` internals, surfaced through the harness | 让运行时发现并验证 app-server 模型。 |
| Codex 媒体理解路径 | `codex/*` image-model compatibility paths | 为受支持的图像理解模型运行有界 Codex app-server 轮次。 |
| 原生钩子中继 | Plugin hooks around Codex-native events | 让 OpenClaw 观察/阻止受支持的 Codex 原生工具/最终化事件。 |
| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex app-server 运行 OpenClaw 嵌入式智能体轮次。 |
| 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 从消息对话绑定并控制 Codex app-server 线程。 |
| Codex app-server 提供商/目录 | `codex` 内部机制，通过 harness 暴露 | 让运行时发现并验证 app-server 模型。 |
| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 为受支持的图像理解模型运行有界 Codex app-server 轮次。 |
| 原生钩子中继 | 围绕 Codex 原生事件的插件钩子 | 让 OpenClaw 观察/阻止受支持的 Codex 原生工具/最终化事件。 |
启用该插件会让这些能力可用。它**不会**：
- 开始对每个 OpenAI 模型都使用 Codex
- 开始对每个 OpenAI 模型使用 Codex
- 将 `openai-codex/*` 模型引用转换为原生运行时
- 让 ACP/acpx 成为默认 Codex 路径
- 热切换已经记录 PI 运行时的现有会话
- 替换 OpenClaw 渠道投递、会话文件、auth-profile 存储或消息路由
- 替换 OpenClaw 渠道投递、会话文件、凭证配置文件存储或消息路由
同一个插件也拥有原生 `/codex` 聊天控制命令界面。如果该插件已启用，并且用户要求从聊天中绑定、恢复、操控、停止或检查 Codex 线程，agent 应优先使用 `/codex ...` 而不是 ACP。当用户要求 ACP/acpx 或正在测试 ACP Codex 适配器时，ACP 仍然是显式回退。
同一个插件还拥有原生 `/codex` 聊天控制命令界面。如果插件已启用，且用户要求从聊天中绑定、恢复、steer、停止或检查 Codex 线程，智能体应优先使用 `/codex ...` 而不是 ACP。当用户要求 ACP/acpx 或正在测试 ACP Codex 适配器时，ACP 仍是显式回退选项。
原生 Codex 轮次保留 OpenClaw 插件钩子作为公共兼容层。这些是进程内 OpenClaw 钩子，不是 Codex `hooks.json` 命令钩子：
@ -97,97 +108,112 @@ Codex heartbeat 轮次默认也会获得 `heartbeat_respond` 工具，因此 age
- `llm_input`, `llm_output`
- `before_tool_call`, `after_tool_call`
- `before_message_write` 用于镜像转录记录
- `before_agent_finalize` 通过 Codex `Stop` 中继
- 通过 Codex `Stop` 中继的 `before_agent_finalize`
- `agent_end`
插件还可以注册与运行时无关的工具结果中间件，用于在 OpenClaw 执行工具之后、结果返回给 Codex 之前改写 OpenClaw 动态工具结果。这不同于公共 `tool_result_persist` 插件钩子，后者会转换由 OpenClaw 拥有的转录工具结果写入。
插件还可以注册运行时中立的工具结果中间件，以便在 OpenClaw 执行工具之后、结果返回给 Codex 之前改写 OpenClaw 动态工具结果。这独立于公共
`tool_result_persist` 插件钩子，后者转换由 OpenClaw 拥有的转录工具结果写入。
关于插件钩子语义本身，请参阅 [插件钩子](/zh-CN/plugins/hooks)
和 [插件守卫行为](/zh-CN/tools/plugin)。
有关插件钩子语义本身，请参阅[插件钩子](/zh-CN/plugins/hooks)
和[插件保护行为](/zh-CN/tools/plugin)。
harness 默认关闭。新配置应保持 OpenAI 模型引用规范为 `openai/gpt-*`，并在需要原生 app-server 执行时显式强制使用 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。旧版 `codex/*` 模型引用仍会为兼容性自动选择该 harness，但由运行时支持的旧版提供商前缀不会显示为普通模型/提供商选项。
harness 默认关闭。新配置应将 OpenAI 模型引用保持为规范形式
`openai/gpt-*`，并在需要原生 app-server 执行时显式强制设置
`agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。旧版 `codex/*` 模型引用仍会为兼容性自动选择 harness，但由运行时支持的旧版提供商前缀不会显示为普通模型/提供商选项。
如果 `codex` 插件已启用，但主模型仍为 `openai-codex/*`，`openclaw doctor` 会发出警告，而不是更改路由。这是有意设计的：`openai-codex/*` 仍然是 PI Codex OAuth/订阅路径，而原生 app-server 执行仍然是显式运行时选择。
如果 `codex` 插件已启用，但主模型仍是
`openai-codex/*`，`openclaw doctor` 会发出警告，而不是更改路线。这是有意设计的：`openai-codex/*` 仍表示 PI Codex OAuth/订阅路径，而原生 app-server 执行仍是显式运行时选择。
## 路由映射
## 路线图
在更改配置前使用此表：
更改配置前请使用此表：
| 期望行为 | 模型引用 | 运行时配置 | 插件要求 | 预期 Status 标签 |
| ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ |
| 通过普通 OpenClaw runner 使用 OpenAI API | `openai/gpt-*` | 省略或 `runtime: "pi"` | OpenAI provider | `Runtime: OpenClaw Pi Default` |
| 通过 PI 使用 Codex OAuth/订阅 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth 提供商 | `Runtime: OpenClaw Pi Default` |
| 原生 Codex app-server 嵌入式轮次 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` 插件 | `Runtime: OpenAI Codex` |
| 使用保守自动模式的混合提供商 | 提供商特定引用 | `agentRuntime.id: "auto"` | 可选插件运行时 | 取决于选定运行时 |
| 显式 Codex ACP 适配器会话 | 取决于 ACP prompt/model | `sessions_spawn` with `runtime: "acp"` | 健康的 `acpx` 后端 | ACP 任务/会话 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 提供商 | `Runtime: OpenClaw Pi Default` |
| 使用保守自动模式的混合提供商 | 提供商特定引用 | `agentRuntime.id: "auto"` | 按所选提供商 | 取决于所选运行时 |
| 显式 Codex ACP 适配器会话 | 取决于 ACP prompt/模型 | 带 `runtime: "acp"` 的 `sessions_spawn` | ACP 后端凭证 | ACP 任务/会话 Status |
重要区别在于提供商与运行时：
关键区别在于提供商与运行时：
- `openai-codex/*` 回答“PI 应使用哪个提供商/凭证路由？”
- `agentRuntime.id: "codex"` 回答“哪个循环应执行这个嵌入式轮次？”
- `openai-codex/*` 回答“PI 应使用哪条提供商/凭证路线？”
- `agentRuntime.id: "codex"` 回答“哪个 loop 应执行此嵌入式轮次？”
- `/codex ...` 回答“此聊天应绑定或控制哪个原生 Codex 对话？”
- ACP 回答“acpx 应启动哪个外部 harness 进程？”
## 选择正确的模型前缀
OpenAI 系列路由按前缀区分。当你希望通过 PI 使用 Codex OAuth 时，使用 `openai-codex/*`；当你希望直接访问 OpenAI API，或正在强制使用原生 Codex app-server harness 时，使用 `openai/*`：
OpenAI 系列路线按前缀区分。对于常见的订阅加原生 Codex 运行时设置，请使用带 `agentRuntime.id: "codex"` 的 `openai/*`。
仅当你有意希望通过 PI 使用 Codex OAuth 时，才使用 `openai-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 app-server harness | 你希望为嵌入式 agent 轮次使用原生 Codex app-server 执行。 |
| `openai/gpt-5.4` | 通过 OpenClaw/PI 管线使用 OpenAI provider | 你希望使用当前直接 OpenAI Platform API 访问，并带有 `OPENAI_API_KEY`。 |
| `openai-codex/gpt-5.5` | 通过 OpenClaw/PI 使用 OpenAI Codex OAuth | 你希望通过默认 PI runner 使用 ChatGPT/Codex 订阅凭证。 |
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你希望通过原生 Codex 执行使用 ChatGPT/Codex 订阅凭证。 |
GPT-5.5 目前在 OpenClaw 中仅支持订阅/OAuth。对 PI OAuth 使用 `openai-codex/gpt-5.5`，或将 `openai/gpt-5.5` 与 Codex app-server harness 配合使用。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即支持通过 API key 直接访问 `openai/gpt-5.5`。
当你的账号暴露这些路线时，GPT-5.5 可以同时出现在直接 OpenAI API key 和 Codex 订阅路线中。对于原生 Codex 运行时，请将 `openai/gpt-5.5` 与 Codex app-server harness 一起使用；对于 PI OAuth，请使用 `openai-codex/gpt-5.5`；对于直接 API key 流量，请使用不带 Codex 运行时覆盖的 `openai/gpt-5.5`。
旧版 `codex/gpt-*` 引用仍会作为兼容别名被接受。Doctor 兼容性迁移会将旧版主运行时引用改写为规范模型引用，并单独记录运行时策略；而仅作为回退的旧版引用会保持不变，因为运行时是为整个 agent 容器配置的。新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server harness 配置应使用 `openai/gpt-*` 加 `agentRuntime.id: "codex"`。
旧版 `codex/gpt-*` 引用仍作为兼容别名被接受。Doctor 兼容性迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略；而仅作为 fallback 的旧版引用会保持不变，因为运行时是针对整个智能体容器配置的。新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server harness 配置应使用 `openai/gpt-*` 加
`agentRuntime.id: "codex"`。
`agents.defaults.imageModel` 遵循相同的前缀划分。当图像理解应通过 OpenAI Codex OAuth provider 路径运行时，使用 `openai-codex/gpt-*`。当图像理解应通过有界 Codex app-server 轮次运行时，使用 `codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；纯文本 Codex 模型会在媒体轮次开始前失败。
`agents.defaults.imageModel` 遵循相同的前缀区分。当图像理解应通过 OpenAI Codex OAuth 提供商路径运行时，请使用
`openai-codex/gpt-*`。当图像理解应通过有界 Codex app-server 轮次运行时，请使用 `codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；纯文本 Codex 模型会在媒体轮次开始前失败。
使用 `/status` 确认当前会话的有效 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 gateway 的结构化 `agent harness selected` 记录。它包含选定的 harness id、选择原因、运行时/回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。
使用 `/status` 确认当前会话的有效 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含所选 harness id、选择原因、运行时/fallback 策略，以及在 `auto` 模式下每个插件候选项的支持结果。
### Doctor 警告的含义
当以下条件全部为真时，`openclaw doctor` 会警告：
当以下条件全部为真时，`openclaw doctor` 会发出警告：
- 内置 `codex` 插件已启用或允许
- 某个 agent 的主模型是 `openai-codex/*`
- 该 agent 的有效运行时不是 `codex`
- 某个智能体的主模型是 `openai-codex/*`
- 该智能体的有效运行时不是 `codex`
该警告存在的原因是，用户通常期望“Codex 插件已启用”意味着“原生 Codex app-server 运行时”。OpenClaw 不会做出这种跳转。该警告表示：
该警告存在是因为用户经常以为“启用 Codex 插件”意味着“原生 Codex app-server 运行时”。OpenClaw 不会做这样的推断。该警告表示：
- 如果你本来就想通过 PI 使用 ChatGPT/Codex OAuth，**无需更改**。
- 如果你想使用原生 app-server 执行，请将模型改为 `openai/<model>` 并设置
- 如果你想要原生 app-server 执行，请将模型改为 `openai/<model>` 并设置
`agentRuntime.id: "codex"`。
- 运行时更改后，现有会话仍然需要 `/new` 或 `/reset`，因为会话运行时固定是粘性的。
- 运行时更改后，现有会话仍需要 `/new` 或 `/reset`，因为会话运行时 pin 是粘性的。
harness 选择不是实时会话控制。当一个嵌入式轮次运行时，OpenClaw 会在该会话上记录选定的 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来会话使用另一个 harness 时，请更改 `agentRuntime` 配置或 `OPENCLAW_AGENT_RUNTIME`；在 PI 和 Codex 之间切换现有对话前，请使用 `/new` 或 `/reset` 启动一个新会话。这可以避免通过两个不兼容的原生会话系统重放同一份转录。
harness 选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会在该会话上记录所选 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来会话使用另一个 harness 时，请更改 `agentRuntime` 配置或
`OPENCLAW_AGENT_RUNTIME`；在将现有对话从 PI 切换到 Codex 之前，请使用 `/new` 或 `/reset` 启动新会话。这可以避免通过两个不兼容的原生会话系统重放同一份转录。
在 harness 固定机制出现之前创建的旧版会话，只要已有转录历史，就会被视为固定到 PI。更改配置后，使用 `/new` 或 `/reset` 将该对话切换到 Codex。
在 harness pin 出现之前创建的旧版会话，一旦已有转录历史，就会被视为已 pin 到 PI。更改配置后，请使用 `/new` 或 `/reset` 将该对话选择加入 Codex。
`/status` 显示有效模型运行时。默认 PI harness 显示为 `Runtime: OpenClaw Pi Default`，Codex app-server harness 显示为 `Runtime: OpenAI Codex`。
`/status` 会显示生效的模型运行时。默认 PI harness 显示为
`Runtime: OpenClaw Pi Default`，Codex app-server 运行框架显示为
`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`，因此默认不会读取你的个人 `~/.codex` 账号、Skills、插件、配置、线程状态，或原生 `$HOME/.agents/skills`。
- OpenClaw，并且内置的 `codex` 插件可用。
- Codex app-server `0.125.0` 或更新版本。内置插件默认会管理兼容的
Codex app-server 二进制文件，因此 `PATH` 上的本地 `codex` 命令不会影响正常的 harness 启动。
- 应用服务器进程或 OpenClaw 的 Codex 凭证桥接可使用 Codex 凭证。本地 app-server 启动会为每个
agent 使用 OpenClaw 管理的 Codex home，并使用隔离的子进程 `HOME`，因此默认不会读取你的个人
`~/.codex` 账号、Skills、插件、配置、线程状态或原生
`$HOME/.agents/skills`。
该插件会阻止较旧或未带版本的 app-server 握手。这样可让 OpenClaw 保持在已测试过的协议表面上。
该插件会阻止较旧或无版本的 app-server 握手。这样可让 OpenClaw 保持在已经测试过的协议表面上。
对于 live 和 Docker 冒烟测试，凭证通常来自 Codex CLI 账号或 OpenClaw `openai-codex` 凭证配置。本地 stdio app-server 启动也可以在没有账号时回退到 `CODEX_API_KEY` / `OPENAI_API_KEY`。
对于实时和 Docker 冒烟测试，凭证通常来自 Codex CLI 账号或 OpenClaw `openai-codex` 凭证配置文件。本地 stdio app-server 启动在没有账号时也可以回退到 `CODEX_API_KEY` / `OPENAI_API_KEY`。
## 将 Codex 与其他模型一起添加
如果同一个智能体需要在 Codex 和非 Codex 提供商模型之间自由切换，不要全局设置 `agentRuntime.id: "codex"`。强制运行时会应用到该智能体或会话的每个嵌入式轮次。如果在强制使用该运行时时选择 Anthropic 模型，OpenClaw 仍会尝试 Codex harness 并失败关闭，而不是静默地通过 Pi 路由该轮次。
如果同一个 agent 需要在 Codex 和非 Codex 提供商模型之间自由切换，不要全局设置 `agentRuntime.id: "codex"`。强制运行时会应用到该 agent 或会话的每个嵌入式轮次。如果在该运行时被强制时选择 Anthropic 模型，OpenClaw 仍会尝试 Codex harness，并以失败关闭方式结束，而不是静默地将该轮次路由到 PI。
改用以下结构之一：
请改用以下结构之一：
- 将 Codex 放在一个带有 `agentRuntime.id: "codex"` 的专用智能体上。
- 保持默认智能体使用 `agentRuntime.id: "auto"`，并为普通混合提供商使用保留 Pi 回退。
- 仅为兼容性使用旧版 `codex/*` 引用。新配置应优先使用 `openai/*`，并显式设置 Codex 运行时策略。
- 将 Codex 放在一个专用 agent 上，并设置 `agentRuntime.id: "codex"`。
- 将默认 agent 保持为 `agentRuntime.id: "auto"`，并对常规混合提供商使用保留 PI 回退。
- 仅为兼容性使用旧版 `codex/*` 引用。新配置应优先使用
`openai/*` 加显式 Codex 运行时策略。
例如，以下配置会让默认智能体保持正常的自动选择，并添加一个单独的 Codex 智能体：
例如，下面会让默认 agent 保持正常自动选择，并添加一个单独的 Codex agent：
```json5
{
@ -226,31 +252,32 @@ harness 选择不是实时会话控制。当一个嵌入式轮次运行时，Ope
使用这种结构时：
- 默认 `main` 智能体使用正常的提供商路径和 Pi 兼容性回退。
- `codex` 智能体使用 Codex app-server harness。
- 如果 `codex` 智能体缺失 Codex 或不支持 Codex，该轮次会失败，而不是静默使用 Pi。
- 默认 `main` agent 使用常规提供商路径和 PI 兼容性回退。
- `codex` agent 使用 Codex app-server harness。
- 如果 `codex` agent 缺少 Codex 或不支持 Codex，该轮次会失败，而不是悄悄使用 PI。
## 智能体命令路由
## Agent 命令路由
智能体应按意图路由用户请求，而不是仅凭 “Codex” 这个词：
Agents 应按意图路由用户请求，而不是只根据 “Codex” 这个词：
| 用户请求... | 智能体应使用... |
| -------------------------------------------------------- | ------------------------------------------------ |
| “将此聊天绑定到 Codex” | `/codex bind` |
| “在这里恢复 Codex 线程 `<id>`” | `/codex resume <id>` |
| “显示 Codex 线程” | `/codex threads` |
| “为一次糟糕的 Codex 运行提交支持报告” | `/diagnostics [note]` |
| “仅为这个附加线程发送 Codex 反馈” | `/codex diagnostics [note]` |
| “将 Codex 用作此智能体的运行时” | 将配置更改为 `agentRuntime.id` |
| “在普通 OpenClaw 中使用我的 ChatGPT/Codex 订阅” | `openai-codex/*` 模型引用 |
| “通过 ACP/acpx 运行 Codex” | ACP `sessions_spawn({ runtime: "acp", ... })` |
| “在线程中启动 Claude Code/Gemini/OpenCode/Cursor” | ACP/acpx，而不是 `/codex`，也不是原生子智能体 |
| 用户请求... | Agent 应使用... |
| ------------------------------------------------------ | ------------------------------------------------ |
| “将此聊天绑定到 Codex” | `/codex bind` |
| “在这里恢复 Codex 线程 `<id>`” | `/codex resume <id>` |
| “显示 Codex 线程” | `/codex threads` |
| “为一次有问题的 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`，也不是原生子 agent |
OpenClaw 仅在 ACP 已启用、可分发且由已加载的运行时后端支撑时，才会向智能体宣传 ACP spawn 指引。如果 ACP 不可用，系统提示词和插件 Skills 不应教智能体 ACP 路由。
OpenClaw 只有在 ACP 已启用、可分发，并且由已加载的运行时后端支持时，才会向 agents 公布 ACP 生成指引。如果 ACP 不可用，系统提示和插件 Skills 不应教 agent 关于 ACP 路由。
## 仅 Codex 部署
当你需要证明每个嵌入式智能体轮次都使用 Codex 时，强制使用 Codex harness。显式插件运行时默认没有 Pi 回退，因此 `fallback: "none"` 是可选的，但通常可作为有用的文档说明：
当你需要证明每个嵌入式 agent 轮次都使用 Codex 时，请强制使用 Codex harness。显式插件运行时默认没有 PI 回退，因此
`fallback: "none"` 是可选的，但通常很适合作为文档说明：
```json5
{
@ -266,17 +293,18 @@ OpenClaw 仅在 ACP 已启用、可分发且由已加载的运行时后端支撑
}
```
环境变量覆盖：
环境覆盖：
```bash
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 会提前失败。只有在你有意让 PI 处理缺失的 harness 选择时，才设置
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。
## 按智能体配置 Codex
## 按 agent 配置 Codex
你可以让一个智能体仅使用 Codex，同时让默认智能体保持正常的自动选择：
你可以让一个 agent 仅使用 Codex，同时让默认 agent 保持正常自动选择：
```json5
{
@ -307,17 +335,18 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
}
```
使用普通会话命令切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，Codex harness 会按需创建或恢复其 sidecar app-server 线程。`/reset` 会清除此线程的 OpenClaw 会话绑定，并让下一轮再次从当前配置解析 harness。
使用常规会话命令切换 agents 和模型。`/new` 会创建一个全新的
OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar app-server 线程。`/reset` 会清除此线程的 OpenClaw 会话绑定，并让下一轮再次从当前配置解析 harness。
## 模型发现
默认情况下，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
{
@ -337,7 +366,7 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
}
```
当你希望启动时避免探测 Codex 并固定使用回退目录时，禁用设备发现：
当你希望启动时避免探测 Codex 并坚持使用回退目录时，请禁用发现：
```json5
{
@ -364,11 +393,13 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
codex app-server --listen stdio://
```
受管二进制文件随 `codex` 插件包一起发布。这样会将 app-server 版本绑定到内置插件，而不是本地恰好安装的某个单独 Codex CLI。仅当你有意运行不同的可执行文件时，才设置 `appServer.command`。
托管二进制文件随 `codex` 插件包一起提供。这样会让 app-server 版本与内置插件绑定，而不是与本地碰巧安装的任何单独 Codex CLI 绑定。只有在你有意运行其他可执行文件时，才设置 `appServer.command`。
默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话：`approvalPolicy: "never"`、`approvalsReviewer: "user"` 和 `sandbox: "danger-full-access"`。这是用于自主 Heartbeat 的可信本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会因为无人回应的原生审批提示而停止。
默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话：
`approvalPolicy: "never"`、`approvalsReviewer: "user"` 和
`sandbox: "danger-full-access"`。这是用于自主 Heartbeat 的可信本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会停在无人回答的原生批准提示上。
若要选择使用由 Codex guardian 审核的审批，请设置 `appServer.mode:
若要选择使用 Codex guardian 审核的批准，请设置 `appServer.mode:
"guardian"`：
```json5
@ -389,9 +420,12 @@ codex app-server --listen stdio://
}
```
Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求离开沙箱、写入工作区外部，或添加网络访问等权限时，Codex 会将该审批请求路由给原生审核器，而不是人工提示。审核器会应用 Codex 的风险框架，并批准或拒绝该具体请求。当你需要比 YOLO 模式更多的护栏，但仍需要无人值守智能体继续推进时，请使用 Guardian。
Guardian 模式使用 Codex 的原生自动审核批准路径。当 Codex 请求离开沙箱、写入工作区之外，或添加网络访问等权限时，Codex 会将该批准请求路由到原生审核者，而不是人工提示。审核者会应用 Codex 的风险框架，并批准或拒绝该具体请求。当你需要比 YOLO 模式更多的防护栏，但仍需要无人值守的 agents 继续推进时，请使用 Guardian。
`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。单个策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选择混用。较旧的 `guardian_subagent` reviewer 值仍作为兼容别名接受，但新配置应使用 `auto_review`。
`guardian` 预设会展开为 `approvalPolicy: "on-request"`、
`approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。
各个策略字段仍会覆盖 `mode`，因此高级部署可以将预设与显式选择混用。较旧的 `guardian_subagent` 审核者值仍作为兼容别名被接受，但新配置应使用
`auto_review`。
对于已经运行的 app-server，请使用 WebSocket 传输：
@ -415,26 +449,30 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
}
```
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 泄漏进来。
Stdio app-server 启动默认继承 OpenClaw 的进程环境，但 OpenClaw 拥有 Codex app-server 账号桥接，并将 `CODEX_HOME` 和 `HOME` 都设置为该 agent 的 OpenClaw 状态下的按 agent 目录。Codex 自己的 skill loader 会读取 `$CODEX_HOME/skills` 和
`$HOME/.agents/skills`，因此本地 app-server 启动会隔离这两个值。这样可让 Codex 原生 Skills、插件、配置、账号和线程状态限定在 OpenClaw agent 范围内，而不是从操作员的个人 Codex CLI home 泄漏进来。
OpenClaw 插件和 OpenClaw Skills 快照仍会通过 OpenClaw 自己的插件注册表和 Skills 加载器流转。个人 Codex CLI 资产不会。如果你有有用的 Codex CLI Skills 或插件，应显式清点它们，使其成为 OpenClaw 智能体的一部分：
OpenClaw 插件和 OpenClaw skill 快照仍会通过 OpenClaw 自己的插件注册表和 skill loader 流转。个人 Codex CLI 资产不会流转。如果你有应成为 OpenClaw agent 一部分的有用 Codex CLI Skills 或插件，请显式清点它们：
```bash
openclaw migrate codex --dry-run
openclaw migrate apply codex --yes
```
Codex 迁移提供商会将 Skills 复制到当前 OpenClaw 智能体工作区。Codex 原生插件、钩子和配置文件会被报告或归档以供人工审核，而不是自动激活，因为它们可能执行命令、暴露 MCP 服务器，或携带凭证。
Codex 迁移提供商会将 Skills 复制到当前 OpenClaw agent 工作区。Codex 原生插件、钩子和配置文件会被报告或归档以供手动审查，而不会自动激活，因为它们可以执行命令、暴露 MCP 服务器，或携带凭证。
凭证按以下顺序选择：
1. 智能体的显式 OpenClaw Codex 凭证配置。
2. 该智能体 Codex home 中 app-server 的现有账号。
3. 仅对于本地 stdio app-server 启动，当不存在 app-server 账号且仍需要 OpenAI 凭证时，依次使用 `CODEX_API_KEY`、`OPENAI_API_KEY`。
1. 该 agent 的显式 OpenClaw Codex 凭证配置文件。
2. 该 agent 的 Codex home 中 app-server 的现有账号。
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 仍可用于 embeddings 或直接 OpenAI 模型，同时避免原生 Codex app-server 轮次意外通过 API 计费。显式 Codex API-key 配置和本地 stdio 环境键回退使用 app-server 登录，而不是继承的子进程环境。WebSocket app-server 连接不会接收 Gateway 网关环境 API-key 回退；请使用显式凭证配置或远程 app-server 自己的账号。
当 OpenClaw 看到 ChatGPT 订阅式 Codex 凭证配置文件时，会从派生的 Codex 子进程中移除
`CODEX_API_KEY` 和 `OPENAI_API_KEY`。这样可让 Gateway 网关级 API 密钥继续用于 embeddings 或直接 OpenAI 模型，而不会意外让原生 Codex app-server 轮次通过 API 计费。显式 Codex API-key 配置文件和本地 stdio 环境密钥回退使用 app-server 登录，而不是继承的子进程环境。WebSocket app-server 连接不会接收 Gateway 网关环境 API-key 回退；请使用显式凭证配置文件或远程 app-server 自己的账号。
如果部署需要额外的环境隔离，请将这些变量添加到 `appServer.clearEnv`：
如果部署需要额外的环境隔离，请将这些变量添加到
`appServer.clearEnv`：
```json5
{
@ -453,47 +491,48 @@ Codex 迁移提供商会将 Skills 复制到当前 OpenClaw 智能体工作区
}
```
`appServer.clearEnv` 仅影响生成的 Codex app-server 子进程。
`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 应用服务器暴露完整的 OpenClaw 动态工具集。 |
| `codexDynamicToolsExclude` | `[]` | 在 Codex 应用服务器回合中要省略的其他 OpenClaw 动态工具名称。 |
| -------------------------- | ---------------- | ------------------------------------------------------------------------------------- |
| `codexDynamicToolsProfile` | `"native-first"` | 使用 `"openclaw-compat"` 将完整的 OpenClaw 动态工具集暴露给 Codex app-server。 |
| `codexDynamicToolsExclude` | `[]` | 要从 Codex app-server 轮次中省略的其他 OpenClaw 动态工具名称。 |
支持的 `appServer` 字段：
| 字段 | 默认值 | 含义 |
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 |
| `command` | 托管的 Codex 二进制文件 | stdio 传输协议的可执行文件。留空则使用托管二进制文件；仅在需要显式覆盖时设置。 |
| `command` | 托管的 Codex 二进制文件 | stdio 传输协议的可执行文件。保持未设置以使用托管二进制文件；仅在需要显式覆盖时设置。 |
| `args` | `["app-server", "--listen", "stdio://"]` | stdio 传输协议的参数。 |
| `url` | 未设置 | WebSocket 应用服务器 URL。 |
| `authToken` | 未设置 | WebSocket 传输协议的 Bearer token。 |
| `headers` | `{}` | 额外的 WebSocket 请求头。 |
| `clearEnv` | `[]` | OpenClaw 构建继承环境后，从派生的 stdio 应用服务器进程中移除的额外环境变量名称。`CODEX_HOME` 和 `HOME` 保留给 OpenClaw 在本地启动时用于按智能体隔离 Codex。 |
| `requestTimeoutMs` | `60000` | 应用服务器控制平面调用的超时时间。 |
| `mode` | `"yolo"` | YOLO 或 guardian 审查执行的预设。 |
| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/回合的原生 Codex 批准策略。 |
| `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 应用服务器服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 |
| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 让 Codex 审核原生审批提示。`guardian_subagent` 仍是旧版别名。 |
| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 |
OpenClaw 拥有的动态工具调用会独立于
由 OpenClaw 拥有的动态工具调用会独立于
`appServer.requestTimeoutMs` 进行限制：每个 Codex `item/tool/call` 请求都必须在
30 秒内收到 OpenClaw 响应。超时时，OpenClaw 会在支持的地方中止工具
信号，并向 Codex 返回失败的动态工具响应，这样该回合可以继续，而不是让会话停留在
`processing`。
30 秒内收到 OpenClaw 响应。超时时，OpenClaw 会在支持的位置中止工具
信号，并向 Codex 返回失败的动态工具响应，以便
轮次可以继续，而不是让会话停留在 `processing`。
OpenClaw 响应 Codex 回合范围的应用服务器请求后，harness
也期望 Codex 使用 `turn/completed` 完成原生回合。如果
应用服务器在该响应后静默 60 秒，OpenClaw 会尽力
中断 Codex 回合，记录诊断超时，并释放
OpenClaw 会话通道，这样后续聊天消息不会排在过期的
原生回合后面。
在 OpenClaw 响应 Codex 轮次范围的 app-server 请求后，harness
还期望 Codex 使用 `turn/completed` 完成原生轮次。如果
app-server 在该响应后 60 秒内保持静默，OpenClaw 会尽力
中断 Codex 轮次，记录诊断超时，并释放
OpenClaw 会话通道，避免后续聊天消息排在过期的
原生轮次后面。
环境覆盖仍可用于本地测试：
@ -503,29 +542,28 @@ OpenClaw 会话通道，这样后续聊天消息不会排在过期的
- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
当 `appServer.command` 未设置时，`OPENCLAW_CODEX_APP_SERVER_BIN`
会绕过托管二进制文件。
当 `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 设置
相同的已审核文件中。
## Computer Use
## 计算机使用
Computer Use 在自己的设置指南中说明：
[Codex Computer Use](/zh-CN/plugins/codex-computer-use)。
计算机使用在自己的设置指南中说明：
[Codex 计算机使用](/zh-CN/plugins/codex-computer-use)。
简短版本：OpenClaw 不会内置桌面控制应用，也不会自行执行
桌面操作。它会准备 Codex 应用服务器，验证
`computer-use` MCP 服务器可用，然后在 Codex 模式回合期间让 Codex 处理原生
桌面操作。它会准备 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 注册之间的区别。
最小配置：
@ -555,27 +593,28 @@ Codex 拥有的 Computer Use 与直接 MCP 注册之间的区别。
}
```
可以从命令界面检查或安装该设置：
可从命令界面检查或安装该设置：
- `/codex computer-use status`
- `/codex computer-use install`
- `/codex computer-use install --source <marketplace-source>`
- `/codex computer-use install --marketplace-path <path>`
Computer Use 仅适用于 macOS，并且在
Codex MCP 服务器能够控制应用之前，可能需要本地 OS 权限。如果 `computerUse.enabled` 为 true 且 MCP
服务器不可用，Codex 模式回合会在线程启动前失败，而不是在没有原生 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 线程绑定。
`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`
注册标准内置 Codex Desktop marketplace。更改运行时或计算机使用配置后，
请使用 `/new` 或 `/reset`，以免现有会话继续保留旧的
PI 或 Codex 线程绑定。
## 常用配方
## 常见配方
使用默认 stdio 传输协议的本地 Codex：
@ -613,7 +652,7 @@ Codex MCP 服务器能够控制应用之前，可能需要本地 OS 权限。如
}
```
guardian 审查的 Codex 批准：
Guardian 审核的 Codex 审批：
```json5
{
@ -635,7 +674,7 @@ guardian 审查的 Codex 批准：
}
```
带显式请求头的远程应用服务器：
带显式标头的远程 app-server：
```json5
{
@ -658,152 +697,152 @@ guardian 审查的 Codex 批准：
}
```
模型切换仍由 OpenClaw 控制。当 OpenClaw 会话附加到
现有 Codex 线程时，下一个回合会再次向
应用服务器发送当前选择的 OpenAI 模型、提供商、批准策略、沙箱和服务层级。
从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留
线程绑定，但会要求 Codex 使用新选择的模型继续。
模型切换仍由 OpenClaw 控制。当 OpenClaw 会话附加
到现有 Codex 线程时，下一个轮次会再次将当前选择的
OpenAI 模型、提供商、审批策略、沙箱和服务层级发送给
app-server。从 `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 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 compact` 要求 Codex app-server 压缩附加的线程。
- `/codex review` 为附加的线程启动 Codex 原生审核。
- `/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. 将完成后的诊断回复复制到缺陷报告或支持线程中。它包括本地包路径、隐私摘要、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 关联起来。完整的隐私模型和群聊行为请参阅 [Diagnostics export](/zh-CN/gateway/diagnostics)。
仅当你明确想为当前附加的线程上传 Codex 反馈，而不需要完整的 OpenClaw Gateway 网关诊断包时，才使用 `/codex diagnostics [note]`。对大多数支持报告来说，`/diagnostics [note]` 是更好的起点，因为它会在同一条回复中把本地 Gateway 网关状态和 Codex 线程 ID 关联起来。完整的隐私模型和群聊行为请参阅[诊断导出](/zh-CN/gateway/diagnostics)。
OpenClaw 核心也公开了仅所有者可用的 `/diagnostics [note]`，作为通用 Gateway 网关诊断命令。它的批准提示会显示敏感数据前言，链接到 [Diagnostics Export](/zh-CN/gateway/diagnostics)，并且每次都会通过显式 exec 批准请求 `openclaw gateway diagnostics export --json`。不要使用全部允许规则来批准诊断。批准后，OpenClaw 会发送一份可粘贴的报告，其中包含本地包路径和清单摘要。当活跃的 OpenClaw 会话正在使用 Codex harness 时，同一次批准也会授权将相关 Codex 反馈包发送到 OpenAI 服务器。批准提示会说明将发送 Codex 反馈，但不会在批准前列出 Codex 会话或线程 ID。
OpenClaw 核心也提供仅所有者可用的 `/diagnostics [note]`，作为通用的 Gateway 网关诊断命令。它的批准提示会显示敏感数据前置说明，链接到[诊断导出](/zh-CN/gateway/diagnostics)，并且每次都通过显式 exec 批准请求 `openclaw gateway diagnostics export --json`。不要用允许所有操作的规则批准诊断。批准后，OpenClaw 会发送一份可粘贴的报告，其中包含本地包路径和清单摘要。当活动的 OpenClaw 会话正在使用 Codex harness 时，同一次批准也会授权将相关 Codex 反馈包发送到 OpenAI 服务器。批准提示会说明将发送 Codex 反馈，但不会在批准前列出 Codex 会话或线程 ID。
如果所有者在群聊中调用 `/diagnostics`，OpenClaw 会保持共享渠道整洁：群组只会收到一条简短通知，而诊断前言、批准提示以及 Codex 会话/线程 ID 会通过私有批准路径发送给所有者。如果没有私有所有者路径，OpenClaw 会拒绝群组请求，并要求所有者从私信中运行它。
如果所有者在群聊中调用 `/diagnostics`，OpenClaw 会保持共享渠道整洁：群组只会收到一条简短通知，而诊断前置说明、批准提示以及 Codex 会话/线程 ID 会通过私有批准路由发送给所有者。如果没有私有所有者路由，OpenClaw 会拒绝群组请求，并要求所有者从私信中运行它。
已批准的 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 上传会调用 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 用于正常轮次的同一个 sidecar 绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选中的 OpenClaw 模型传入 app-server，并保持扩展历史启用。
`/codex resume` 会写入与 harness 在正常回合中使用的同一份旁车绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选择的 OpenClaw 模型传入 app-server，并保持扩展历史记录启用。
### 从 CLI 检查 Codex 线程
理解一次异常 Codex 运行最快的方法，通常是直接打开原生 Codex 线程：
理解一次异常 Codex 运行的最快方式，通常是直接打开原生 Codex 线程：
```sh
codex resume <thread-id>
```
当你在渠道对话中注意到缺陷，并想检查有问题的 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 app-server 线程的 `/codex threads [filter]` 获取线程 ID，然后在 shell 中运行同一个 `codex resume` 命令。
你也可以通过当前聊天的 `/codex binding` 获取线程 ID，或通过 `/codex threads [filter]` 获取最近的 Codex app-server 线程，然后在你的 shell 中运行同一个 `codex resume` 命令。
该命令表面需要 Codex app-server `0.125.0` 或更新版本。如果未来版本或自定义 app-server 未公开某个 JSON-RPC 方法，各个控制方法会报告为 `unsupported by this Codex app-server`。
该命令界面要求 Codex app-server `0.125.0` 或更新版本。如果未来或自定义 app-server 未公开某个 JSON-RPC 方法，单个控制方法会报告为 `unsupported by this Codex app-server`。
## 钩子边界
Codex harness 有三个钩子层：
| 层级 | 所有者 | 用途 |
| 层 | 所有者 | 用途 |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| OpenClaw 插件钩子 | OpenClaw | 跨 PI 和 Codex harness 的产品/插件兼容性。 |
| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的每轮适配器行为。 |
| Codex 原生钩子 | Codex | 来自 Codex 配置的低层 Codex 生命周期和原生工具策略。 |
| OpenClaw 插件钩子 | OpenClaw | 跨 Pi 和 Codex harness 的产品/插件兼容性。 |
| 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 通过 app-server 或原生钩子回调公开该操作，否则它无法重写原生 Codex 线程。
对于 OpenClaw 动态工具，OpenClaw 会在 Codex 请求调用后执行该工具，因此 OpenClaw 会在 harness 适配器中触发它所拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范工具记录。OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生钩子回调公开该操作，否则它不能重写原生 Codex 线程。
压缩和 LLM 生命周期投影来自 Codex app-server 通知和 OpenClaw 适配器状态，而不是原生 Codex 钩子命令。OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 `llm_output` 事件是适配器层级的观察结果，而不是逐字节捕获的 Codex 内部请求或压缩载荷。
压缩和 LLM 生命周期投影来自 Codex app-server 通知和 OpenClaw 适配器状态，而不是原生 Codex 钩子命令。OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 `llm_output` 事件是适配器级观察结果，不是对 Codex 内部请求或压缩负载的逐字节捕获。
Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会被投影为用于轨迹和调试的 `codex_app_server.hook` 智能体事件。它们不会调用 OpenClaw 插件钩子。
Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会投影为 `codex_app_server.hook` 智能体事件，用于轨迹和调试。它们不会调用 OpenClaw 插件钩子。
## V1 支持合约
Codex 模式不是在底层换了一次模型调用的 PI。Codex 拥有更多原生模型循环，而 OpenClaw 会围绕该边界适配它的插件和会话表面。
Codex 模式并不是底层换了一个模型调用的 Pi。Codex 拥有更多原生模型循环，而 OpenClaw 会围绕该边界适配其插件和会话界面。
Codex 运行时 v1 支持：
| 表面 | 支持情况 | 原因 |
| 界面 | 支持情况 | 原因 |
| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex app-server 拥有 OpenAI 轮次、原生线程恢复和原生工具延续。 |
| OpenClaw 渠道路由和投递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 以及其他渠道仍位于模型运行时之外。 |
| OpenClaw 动态工具 | 支持 | Codex 请求 OpenClaw 执行这些工具，因此 OpenClaw 仍在执行路径中。 |
| 提示词和上下文插件 | 支持 | OpenClaw 会在启动或恢复线程前构建提示词叠加层，并将上下文投影到 Codex 轮次中。 |
| 上下文引擎生命周期 | 支持 | 对于 Codex 轮次，会运行组装、摄取或轮次后维护，以及上下文引擎压缩协调。 |
| 动态工具钩子 | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕 OpenClaw 拥有的动态工具运行。 |
| 生命周期钩子 | 作为适配器观察结果支持 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 会以真实的 Codex 模式载荷触发。 |
| 最终答案修订门控 | 通过原生钩子中继支持 | Codex `Stop` 会中继到 `before_agent_finalize`；`revise` 会要求 Codex 在最终完成前再进行一次模型传递。 |
| 原生 shell、patch 和 MCP 阻止或观察 | 通过原生钩子中继支持 | Codex `PreToolUse` 和 `PostToolUse` 会为已提交的原生工具表面中继，包括 Codex app-server `0.125.0` 或更新版本上的 MCP 载荷。支持阻止；不支持参数重写。 |
| 原生权限策略 | 通过原生钩子中继支持 | 在运行时公开该能力的情况下，Codex `PermissionRequest` 可以通过 OpenClaw 策略路由。如果 OpenClaw 未返回决策，Codex 会继续通过其常规 guardian 或用户批准路径。 |
| App-server 轨迹捕获 | 支持 | OpenClaw 会记录它发送给 app-server 的请求，以及它收到的 app-server 通知。 |
| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex app-server 拥有 OpenAI 回合、原生线程恢复以及原生工具续接。 |
| OpenClaw 渠道路由和投递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 和其他渠道保持在模型运行时之外。 |
| OpenClaw 动态工具 | 支持 | Codex 请求 OpenClaw 执行这些工具，因此 OpenClaw 保持在执行路径中。 |
| Prompt 和上下文插件 | 支持 | OpenClaw 会在启动或恢复线程前构建 prompt 覆盖层，并将上下文投影到 Codex 回合中。 |
| 上下文引擎生命周期 | 支持 | 为 Codex 回合运行组装、摄取或回合后维护，以及上下文引擎压缩协调。 |
| 动态工具钩子 | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕 OpenClaw 所拥有的动态工具运行。 |
| 生命周期钩子 | 作为适配器观察结果支持 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 会使用真实的 Codex 模式负载触发。 |
| 最终答案修订门控 | 通过原生钩子中继支持 | Codex `Stop` 会中继到 `before_agent_finalize`；`revise` 会要求 Codex 在最终确定前再执行一次模型传递。 |
| 原生 shell、patch 和 MCP 阻止或观察 | 通过原生钩子中继支持 | Codex `PreToolUse` 和 `PostToolUse` 会针对已承诺的原生工具界面进行中继，包括 Codex app-server `0.125.0` 或更新版本上的 MCP 负载。支持阻止；不支持参数重写。 |
| 原生权限策略 | 通过原生钩子中继支持 | 当运行时公开该能力时，Codex `PermissionRequest` 可以通过 OpenClaw 策略路由。如果 OpenClaw 未返回决策，Codex 会继续通过其正常 guardian 或用户批准路径。 |
| App-server 轨迹捕获 | 支持 | OpenClaw 会记录它发送给 app-server 的请求以及它收到的 app-server 通知。 |
Codex 运行时 v1 不支持：
| 表面 | V1 边界 | 未来路径 |
| 表面 | V1 边界 | 未来路径 |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 原生工具参数变更 | Codex 原生工具前置钩子可以阻止，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子/模式支持替换工具输入。 |
| 可编辑的 Codex 原生转录历史 | Codex 拥有权威原生线程历史。OpenClaw 拥有镜像并可投射未来上下文，但不应变更不受支持的内部状态。 | 如果需要原生线程手术式修改，请添加显式 Codex 应用服务器 API。 |
| Codex 原生工具记录的 `tool_result_persist` | 该钩子转换 OpenClaw 拥有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但权威重写需要 Codex 支持。 |
| 丰富的原生压缩元数据 | OpenClaw 会观察压缩开始和完成，但不会收到稳定的保留/丢弃列表、令牌增量或摘要负载。 | 需要更丰富的 Codex 压缩事件。 |
| 压缩干预 | 当前 OpenClaw 压缩钩子在 Codex 模式下处于通知级别。 | 如果插件需要否决或重写原生压缩，请添加 Codex 压缩前/后钩子。 |
| 逐字节模型 API 请求捕获 | OpenClaw 可以捕获应用服务器请求和通知，但 Codex 核心会在内部构建最终 OpenAI API 请求。 | 需要 Codex 模型请求跟踪事件或调试 API。 |
| 原生工具参数变更 | Codex 原生工具前钩子可以阻止操作，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子/模式支持替换工具输入。 |
| 可编辑的 Codex 原生转录历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有一个镜像，可以投射未来上下文，但不应变更不受支持的内部机制。 | 如果需要原生线程手术式修改，请添加显式的 Codex app-server API。 |
| Codex 原生工具记录的 `tool_result_persist` | 该钩子会转换 OpenClaw 拥有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范重写需要 Codex 支持。 |
| 丰富的原生压缩元数据 | OpenClaw 会观察压缩开始和完成，但不会收到稳定的保留/丢弃列表、token 差量或摘要载荷。 | 需要更丰富的 Codex 压缩事件。 |
| 压缩干预 | 当前 OpenClaw 压缩钩子在 Codex 模式下处于通知级别。 | 如果插件需要否决或重写原生压缩，请添加 Codex 压缩前/后钩子。 |
| 逐字节模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但 Codex core 会在内部构建最终的 OpenAI API 请求。 | 需要 Codex 模型请求跟踪事件或调试 API。 |
## 工具、媒体和压缩
Codex harness 只更改低级嵌入式智能体执行器。
Codex harness 只更改低层嵌入式智能体执行器。
OpenClaw 仍会构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批和消息工具输出继续通过正常的 OpenClaw 交付路径。
OpenClaw 仍然会构建工具列表，并从 harness 接收动态工具结果。文本、图片、视频、音乐、TTS、审批和消息工具输出会继续通过正常的 OpenClaw 交付路径。
原生钩子中继有意保持通用，但 v1 支持契约仅限于 OpenClaw 测试过的 Codex 原生工具和权限路径。在 Codex 运行时中，这包括 shell、patch 和 MCP `PreToolUse`、`PostToolUse` 与 `PermissionRequest` 负载。在运行时契约命名之前，不要假设每个未来的 Codex 钩子事件都是 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` 提示会发送回发起聊天，下一个排队的跟进消息会响应该原生服务器请求，而不是作为额外上下文进行 steering。其他 MCP 征询请求仍会失败关闭。
主动运行队列引导映射到 Codex 应用服务器 `turn/steer`。使用默认的 `messages.queue.mode: "steer"` 时，OpenClaw 会在配置的静默窗口内批处理排队的聊天消息，并按到达顺序将它们作为一个 `turn/steer` 请求发送。旧版 `queue` 模式会发送单独的 `turn/steer` 请求。Codex review 和手动压缩轮次可能会拒绝同轮引导，在这种情况下，当所选模式允许回退时，OpenClaw 会使用后续队列。请参阅 [Steering queue](/zh-CN/concepts/queue-steering)。
活动运行队列 steering 映射到 Codex app-server `turn/steer`。使用默认的 `messages.queue.mode: "steer"` 时，OpenClaw 会在配置的静默窗口内批处理排队聊天消息，并按到达顺序作为一个 `turn/steer` 请求发送。旧版 `queue` 模式会发送单独的 `turn/steer` 请求。Codex 审查和手动压缩轮次可能会拒绝同轮 steering，此时如果所选模式允许回退，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`。
媒体生成不需要 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，除非你显式设置 `agentRuntime.fallback: "pi"`。一旦选择 Codex app-server，其失败会直接暴露，不需要额外的回退配置。
**应用服务器被拒绝：** 升级 Codex，使应用服务器握手报告版本 `0.125.0` 或更新版本。同版本预发布版或带构建后缀的版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，会被拒绝，因为 OpenClaw 测试的是稳定版 `0.125.0` 协议下限。
**app-server 被拒绝：**升级 Codex，使 app-server 握手报告版本 `0.125.0` 或更新版本。同版本预发布版或带构建后缀的版本（例如 `0.125.0-alpha.2` 或 `0.125.0+custom`）会被拒绝，因为稳定版 `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 后重试。
## 相关
## 相关内容
- [Agent harness plugins](/zh-CN/plugins/sdk-agent-harness)
- [Agent Runtimes](/zh-CN/concepts/agent-runtimes)

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

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

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

@ -6,79 +6,98 @@ read_when:
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
title: OpenAI
x-i18n:
generated_at: "2026-05-01T22:04:13Z"
generated_at: "2026-05-02T02:38:23Z"
model: gpt-5.5
provider: openai
source_hash: bd9a8f05d31800354307c6fd7beb8cd1eed3d234e5c1e939e895cd99658b540b
source_hash: d7e98179f5a7d90289ed6cdad1c4dd03834f42e3fcc747d24c7d29a47e103392
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 系列路由。模型前缀会选择提供商/认证路由；单独的运行时设置会选择由谁执行嵌入式 Agent loop：
OpenClaw 支持三条 OpenAI 系列路线。大多数希望获得 Codex 行为的 ChatGPT/Codex 订阅用户
应使用原生 Codex 应用服务器运行时。
模型前缀选择提供商/模型名称；单独的运行时设置选择
由谁执行嵌入式 Agent loop：
- **API key** — 通过用量计费直接访问 OpenAI Platform（`openai/*` 模型）
- **通过 PI 使用 Codex 订阅** — 使用订阅访问权限进行 ChatGPT/Codex 登录（`openai-codex/*` 模型）
- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型加 `agents.defaults.agentRuntime.id: "codex"`）
- **API key** - 使用按量计费的直接 OpenAI Platform 访问（`openai/*` 模型）
- **带原生 Codex 运行时的 Codex 订阅** - ChatGPT/Codex 登录加 Codex 应用服务器执行（`openai/*` 模型加 `agents.defaults.agentRuntime.id: "codex"`）
- **通过 PI 的 Codex 订阅** - ChatGPT/Codex 登录并使用常规 OpenClaw PI 运行器（`openai-codex/*` 模型）
OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth。
OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。
提供商、模型、运行时和渠道是彼此独立的层。如果这些标签被混在一起，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再更改配置。
提供商、模型、运行时和渠道是不同层。如果这些标签
混在一起，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再
更改配置。
## 快速选择
| 目标 | 使用 | 说明 |
| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| 直接 API key 计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API key 新手引导。 |
| 使用 ChatGPT/Codex 订阅认证的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 PI 路由。订阅设置的首选项。 |
| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 |
| 图像生成或编辑 | `openai/gpt-image-2` | 可使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth。 |
| 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 |
| 目标 | 使用 | 备注 |
| ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- |
| 带原生 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 运行器时使用。 |
| 图像生成或编辑 | `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 运行器使用的 OpenAI Codex OAuth/订阅路由。 |
| `codex` 插件 | 插件 | OpenClaw 内置插件，提供原生 Codex app-server 运行时和 `/codex` 聊天控制。 |
| `agentRuntime.id: codex` | 智能体运行时 | 为嵌入式轮次强制使用原生 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` plugin | 插件 | 内置 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 路由使用。直接 `OPENAI_API_KEY` 流量使用 `openai/gpt-5.5`，通过 PI 的 Codex OAuth 使用 `openai-codex/gpt-5.5`，原生 Codex app-server harness 使用带有 `agentRuntime.id: "codex"` 的 `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 插件。只有在你通过 `agentRuntime.id: "codex"` 显式选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时，OpenClaw 才会启用该插件。
如果内置 `codex` 插件已启用，但 `openai-codex/*` 仍通过 PI 解析，`openclaw doctor` 会发出警告并保持路由不变。
启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会
启用内置 Codex 应用服务器插件。OpenClaw 只会在你显式选择原生 Codex harness，
即使用 `agentRuntime.id: "codex"`，或使用旧版 `codex/*` 模型引用时
启用该插件。
如果内置 `codex` 插件已启用，但 `openai-codex/*` 仍通过
PI 解析，`openclaw doctor` 会发出警告并保持路线不变。
</Note>
## OpenClaw 功能覆盖
| 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` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
| 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 |
| Embeddings | 记忆嵌入提供商 | 是 |
| OpenAI 能力 | OpenClaw 界面 | Status |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
| Codex 订阅模型 | 带 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
| Codex 应用服务器 harness | 带 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
| 服务端网页搜索 | 原生 OpenAI Responses 工具 | 是，在网页搜索已启用且未固定提供商时 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
| 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 |
| 嵌入 | 记忆嵌入提供商 | 是 |
## 记忆嵌入
OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_search` 索引和查询嵌入提供支持：
OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为
`memory_search` 索引和查询嵌入提供支持：
```json5
{
@ -93,15 +112,19 @@ 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）">
**最适合：** 直接 API 访问和按用量计费。
**最适合：** 直接 API 访问和按量计费。
<Steps>
<Step title="获取你的 API key">
@ -112,7 +135,7 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
openclaw onboard --auth-choice openai-api-key
```
或者直接传入 key：
或直接传入 key：
```bash
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
@ -125,16 +148,19 @@ 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: "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 应用服务器 harness | Codex 应用服务器 |
<Note>
`openai/*` 是直接 OpenAI API key 路由，除非你显式强制使用 Codex app-server harness。通过默认 PI 运行器的 Codex OAuth 使用 `openai-codex/*`，或使用带有 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5` 进行原生 Codex app-server 执行。
`openai/*` 是直接 OpenAI API-key 路线，除非你显式强制
使用 Codex 应用服务器 harness。通过默认 PI 运行器使用 Codex OAuth 时请使用 `openai-codex/*`，
或使用带 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`
进行原生 Codex 应用服务器执行。
</Note>
### 配置示例
@ -147,13 +173,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 订阅，而不是单独的 API key。Codex cloud 需要 ChatGPT 登录。
**最适合：** 使用你的 ChatGPT/Codex 订阅并通过原生 Codex 应用服务器执行，而不是使用单独的 API key。Codex 云端需要 ChatGPT 登录。
<Steps>
<Step title="运行 Codex OAuth">
@ -167,71 +193,92 @@ 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
```
</Step>
<Step title="设置默认模型">
<Step title="使用原生 Codex 运行时">
```bash
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
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
```
</Step>
<Step title="验证模型可用">
<Step title="验证 Codex 凭证可用">
```bash
openclaw models list --provider openai-codex
```
Gateway 网关运行后，在聊天中发送 `/codex status` 或 `/codex models`
来验证原生应用服务器运行时。
</Step>
</Steps>
### 路由摘要
### 路线摘要
| 模型引用 | 运行时配置 | 路由 | 认证 |
| 模型引用 | 运行时配置 | 路线 | 凭证 |
|-----------|----------------|-------|------|
| `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"` | 仍然是 PI，除非插件显式声明 `openai-codex` | Codex 登录 |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server 认证 |
| `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"` | 仍是 PI，除非某个插件显式声明 `openai-codex` | Codex 登录 |
<Note>
继续使用 `openai-codex` 提供商 id 来执行认证/配置文件命令。`openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路由。它不会选择或自动启用内置 Codex app-server harness。
继续将 `openai-codex` provider id 用于凭证/profile 命令。
`openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路由。
它不会选择或自动启用内置的 Codex app-server harness。对于常见的订阅加原生运行时设置，请使用
`openai-codex` 登录，但将模型引用保持为 `openai/gpt-5.5`，并设置
`agentRuntime.id: "codex"`。
</Note>
### 配置示例
```json5
{
agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } },
plugins: { entries: { codex: { enabled: true } } },
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" },
agentRuntime: { id: "codex", fallback: "none" },
},
},
}
```
若要改为在普通 PI runner 上保留 Codex OAuth，请使用
`openai-codex/gpt-5.5`，并省略 Codex 运行时覆盖。
<Note>
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备代码流程登录，OpenClaw 会在自己的智能体认证存储中管理生成的凭证。
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备代码流程登录，OpenClaw 会在自己的智能体凭证存储中管理生成的凭证。
</Note>
### Status 指示器
聊天中的 `/status` 会显示当前会话激活的是哪个模型运行时。
默认 Pi harness 显示为 `Runtime: OpenClaw Pi Default`。当选择内置 Codex app-server 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 警告
如果在选择此标签页的 `openai-codex/*` 路由时启用了内置 `codex` 插件，`openclaw doctor` 会警告该模型仍会通过 PI 解析。当这就是预期的订阅凭证路由时，请保持配置不变。只有在你想要原生 Codex app-server 执行时，才切换到 `openai/<model>` 加
`agentRuntime.id: "codex"`。
如果在已启用内置 `codex` 插件的同时选择了 `openai-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
{
@ -251,8 +298,8 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
### 目录恢复
当上游 Codex 目录元数据中存在 `gpt-5.5` 时，OpenClaw 会使用它。如果账号已完成凭证验证，但实时 Codex 发现结果省略了 `openai-codex/gpt-5.5` 这一行，OpenClaw 会合成该 OAuth 模型行，以免 cron、子智能体和已配置默认模型的运行因
`Unknown model` 而失败。
当存在上游 Codex 目录元数据时，OpenClaw 会将其用于 `gpt-5.5`。如果 live Codex 设备发现遗漏了 `openai-codex/gpt-5.5` 行，而账户已通过身份验证，OpenClaw 会合成该 OAuth 模型行，避免 cron、子智能体和配置的默认模型运行因
`Unknown model` 失败。
</Tab>
</Tabs>
@ -260,29 +307,28 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
## 原生 Codex app-server 凭证
原生 Codex app-server harness 使用 `openai/*` 模型引用加
`agentRuntime.id: "codex"`，但其凭证仍基于账号。OpenClaw 会按以下顺序选择凭证：
`agentRuntime.id: "codex"`，但其凭证仍基于账户。OpenClaw 按以下顺序选择凭证：
1. 绑定到该智能体的显式 OpenClaw `openai-codex` 凭证配置。
2. app-server 的现有账号，例如本地 Codex CLI ChatGPT 登录。
3. 仅对于本地 stdio app-server 启动，当 app-server 报告没有账号但仍需要 OpenAI 凭证时，先使用 `CODEX_API_KEY`，再使用
`OPENAI_API_KEY`。
1. 绑定到智能体的显式 OpenClaw `openai-codex` 凭证 profile。
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 app-server 连接。当选择订阅式 Codex 配置时，OpenClaw 还会避免将 `CODEX_API_KEY` 和 `OPENAI_API_KEY` 传入派生出的 stdio app-server 子进程，并会通过 app-server login RPC 发送所选凭证。
这意味着本地 ChatGPT/Codex 订阅登录不会仅因为 Gateway 网关进程也为直接 OpenAI 模型或嵌入提供了 `OPENAI_API_KEY` 就被替换。环境变量 API 密钥回退仅适用于本地 stdio 无账户路径；它不会发送到 WebSocket app-server 连接。选择订阅风格的 Codex profile 时，OpenClaw 还会避免将 `CODEX_API_KEY` 和 `OPENAI_API_KEY` 放入生成的 stdio app-server 子进程，并通过 app-server 登录 RPC 发送所选凭证。
## 图像生成
内置 `openai` 插件通过 `image_generate` 工具注册图像生成。
它通过同一个 `openai/gpt-image-2` 模型引用，同时支持 OpenAI API key 图像生成和 Codex OAuth 图像生成。
它通过同一个 `openai/gpt-image-2` 模型引用同时支持 OpenAI API 密钥图像生成和 Codex OAuth 图像生成。
| 能力 | OpenAI API key | Codex OAuth |
| 能力 | OpenAI API 密钥 | Codex OAuth |
| ------------------------- | ---------------------------------- | ------------------------------------ |
| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` |
| 凭证 | `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
{
@ -295,16 +341,17 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
```
<Note>
参阅[图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。
请参阅 [图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。
</Note>
`gpt-image-2` 是 OpenAI 文本生成图像和图像编辑的默认模型。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为显式模型覆盖使用。请使用 `openai/gpt-image-1.5` 输出透明背景 PNG/WebP；当前 `gpt-image-2` API 会拒绝
`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 兼容端点会保留其已配置的部署/模型名称。
`background: "transparent"`；较旧的 `openai.background` 提供商选项仍会被接受。OpenClaw 还会保护公开 OpenAI 和
OpenAI Codex OAuth 路由，将默认 `openai/gpt-image-2` 透明请求改写为 `gpt-image-1.5`；Azure 和自定义 OpenAI 兼容端点会保留其配置的部署/模型名称。
同一设置也暴露给无头 CLI 运行：
@ -320,10 +367,10 @@ openclaw infer image generate \
从输入文件开始时，请对 `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 profile 时，OpenClaw 会解析该已存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会为该请求静默回退到 API 密钥。当你需要改用直接 OpenAI Images API 路由时，请使用 API 密钥、自定义 base URL 或 Azure 端点显式配置 `models.providers.openai`。
如果该自定义图像端点位于可信 LAN/专用地址上，还需设置
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非存在此选择加入项，否则 OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。
生成：
@ -347,13 +394,13 @@ openclaw infer image generate \
内置 `openai` 插件通过 `video_generate` 工具注册视频生成。
| 能力 | 值 |
| ---------------- | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并发出工具警告 |
| 能力 | 值 |
| ------------ | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文本到视频、图像到视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并显示工具警告 |
```json5
{
@ -366,22 +413,22 @@ openclaw infer image generate \
```
<Note>
参阅[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。
请参阅 [视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。
</Note>
## GPT-5 prompt 贡献
## GPT-5 提示贡献
OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享 GPT-5 prompt 贡献。它按模型 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 app-server developer instructions 使用相同的 GPT-5 行为和 Heartbeat 叠加，因此强制通过 `agentRuntime.id: "codex"` 运行的 `openai/gpt-5.x` 会话，即便 harness prompt 的其余部分由 Codex 拥有，也会保留相同的跟进和主动 Heartbeat 指引。
内置原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 Heartbeat 叠加层，因此强制通过 `agentRuntime.id: "codex"` 运行的 `openai/gpt-5.x` 会话会保留相同的跟进执行和主动 Heartbeat 指引，即使 Codex 拥有 harness 提示的其余部分。
GPT-5 贡献会添加带标签的行为契约，涵盖 persona 持久性、执行安全、工具纪律、输出形态、完成检查和验证。特定渠道的回复和静默消息行为仍保留在共享 OpenClaw 系统 prompt 和出站投递策略中。GPT-5 指引始终会为匹配模型启用。友好交互风格层是独立且可配置的。
GPT-5 贡献会为 persona 持久性、执行安全、工具纪律、输出形态、完成检查和验证添加带标签的行为契约。特定渠道的回复和静默消息行为仍保留在共享 OpenClaw 系统提示和出站投递策略中。匹配模型始终启用 GPT-5 指引。友好的交互风格层是独立且可配置的。
| 值 | 效果 |
| ---------------------- | ----------------------------------------- |
| `"friendly"`（默认） | 启用友好交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
| 值 | 效果 |
| ---------------------- | ---------------------------- |
| `"friendly"`（默认） | 启用友好的交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
<Tabs>
<Tab title="配置">
@ -409,29 +456,29 @@ GPT-5 贡献会添加带标签的行为契约，涵盖 persona 持久性、执
</Tip>
<Note>
当未设置共享 `agents.defaults.promptOverlays.gpt5.personality` 设置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退读取。
当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 设置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退读取。
</Note>
## 语音与语音识别
## 语音和语音识别
<AccordionGroup>
<Accordion title="语音合成（TTS）">
内置 `openai` 插件为 `messages.tts` 表面注册语音合成。
内置 `openai` 插件为 `messages.tts` surface 注册语音合成。
| 设置 | 配置路径 | 默认值 |
| 设置项 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `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`。
`extraBody` 会在 OpenClaw 生成的字段之后合并到 `/audio/speech` 请求 JSON 中，因此可将它用于需要额外键（例如 `lang`）的 OpenAI 兼容端点。原型键会被忽略。
`extraBody` 会在 OpenClaw 生成字段之后合并到 `/audio/speech` 请求 JSON 中，因此可将它用于需要额外键（如 `lang`）的 OpenAI 兼容端点。原型键会被忽略。
```json5
{
@ -452,14 +499,14 @@ GPT-5 贡献会添加带标签的行为契约，涵盖 persona 持久性、执
</Accordion>
<Accordion title="语音转文本">
内置 `openai` 插件通过 OpenClaw 的媒体理解转写表面注册批量语音转文本。
内置 `openai` 插件会通过 OpenClaw 的媒体理解转写表面注册批量语音转文本。
- 默认模型：`gpt-4o-transcribe`
- 端点：OpenAI REST `/v1/audio/transcriptions`
- 输入路径：multipart 音频文件上传
- 只要入站音频转录使用 `tools.media.audio`，OpenClaw 都支持此功能，包括 Discord 语音渠道片段和渠道音频附件
- 在 OpenClaw 中凡是入站音频转写使用 `tools.media.audio` 的地方都受支持，包括 Discord 语音频道片段和渠道音频附件
如需强制对入站音频转录使用 OpenAI：
若要强制入站音频转写使用 OpenAI：
```json5
{
@ -479,14 +526,14 @@ GPT-5 贡献会添加带标签的行为契约，涵盖 persona 持久性、执
}
```
当共享音频媒体配置或每次调用的转录请求提供语言和提示词提示时，它们会被转发给 OpenAI。
当共享音频媒体配置或逐次调用的转写请求提供语言和提示词提示时，它们会转发给 OpenAI。
</Accordion>
<Accordion title="实时转录">
内置的 `openai` 插件会为 Voice Call 插件注册实时转录。
<Accordion title="实时转写">
内置 `openai` 插件会为 Voice Call 插件注册实时转写。
| 设置 | 配置路径 | 默认值 |
| 设置项 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| 语言 | `...openai.language` | （未设置） |
@ -496,15 +543,15 @@ GPT-5 贡献会添加带标签的行为契约，涵盖 persona 持久性、执
| 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 插件注册实时语音。
| 设置 | 配置路径 | 默认值 |
| 设置项 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
| 语音 | `...openai.voice` | `alloy` |
@ -518,7 +565,7 @@ GPT-5 贡献会添加带标签的行为契约，涵盖 persona 持久性、执
</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>
@ -526,21 +573,21 @@ GPT-5 贡献会添加带标签的行为契约，涵盖 persona 持久性、执
## Azure OpenAI 端点
内置的 `openai` provider 可以通过覆盖基准 URL，将图像生成指向 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换为 Azure 的请求形态。
内置 `openai` 提供商可以通过覆盖基础 URL，将图像生成指向 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到 Azure 的请求形态。
<Note>
实时语音使用单独的配置路径（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），不受 `models.providers.openai.baseUrl` 影响。有关其 Azure 设置，请参阅 [语音和语音合成](#voice-and-speech) 下的**实时语音**折叠项。
实时语音使用单独的配置路径（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），不受 `models.providers.openai.baseUrl` 影响。有关它的 Azure 设置，请参阅 [语音与语音处理](#voice-and-speech) 下的 **实时语音** 折叠项。
</Note>
在以下情况下使用 Azure OpenAI：
- 你已经有 Azure OpenAI 订阅、配额或企业协议
- 你需要 Azure 提供的区域数据驻留或合规控制
- 你希望将流量保留在现有 Azure 租户内
- 你希望将流量保留在现有 Azure 租户中
### 配置
如需通过内置 `openai` provider 使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI key（不是 OpenAI Platform key）：
若要通过内置 `openai` 提供商使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI key（而不是 OpenAI Platform key）：
```json5
{
@ -564,67 +611,67 @@ OpenClaw 会为 Azure 图像生成路由识别以下 Azure 主机后缀：
对于识别出的 Azure 主机上的图像生成请求，OpenClaw 会：
- 发送 `api-key` 标头，而不是 `Authorization: Bearer`
- 使用按部署限定的路径（`/openai/deployments/{deployment}/...`）
- 使用 deployment 范围路径（`/openai/deployments/{deployment}/...`）
- 为每个请求追加 `?api-version=...`
- 对 Azure 图像生成调用使用 600 秒的默认请求超时。每次调用的 `timeoutMs` 值仍会覆盖此默认值。
- 对 Azure 图像生成调用使用 600 秒默认请求超时。逐次调用的 `timeoutMs` 值仍会覆盖此默认值。
其他基准 URL（公共 OpenAI、OpenAI 兼容代理）会保留标准 OpenAI 图像请求形态。
其他基础 URL（公共 OpenAI、OpenAI 兼容代理）会保留标准 OpenAI 图像请求形态。
<Note>
`openai` provider 的图像生成路径上的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。更早版本会像处理公共 OpenAI 端点一样处理任何自定义 `openai.baseUrl`，因此会在 Azure 图像部署上失败。
`openai` 提供商图像生成路径的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。更早版本会像处理公共 OpenAI 端点一样处理任何自定义 `openai.baseUrl`，并且会在访问 Azure 图像 deployment 时失败。
</Note>
### API 版本
设置 `AZURE_OPENAI_API_VERSION`，为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
设置 `AZURE_OPENAI_API_VERSION`，为 Azure 图像生成路径固定特定 Azure preview 或 GA 版本：
```bash
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
```
当未设置该变量时，默认值为 `2024-12-01-preview`。
未设置该变量时，默认值为 `2024-12-01-preview`。
### 模型名称就是部署名称
### 模型名称就是 deployment 名称
Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**，而不是公共 OpenAI 模型 ID。
Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是公共 OpenAI 模型 ID。
如果你创建了名为 `gpt-image-2-prod`、用于提供 `gpt-image-2` 服务的部署：
如果你创建了名为 `gpt-image-2-prod` 的 deployment 来提供 `gpt-image-2`：
```
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
```
同样的部署名称规则也适用于通过内置 `openai` provider 路由的图像生成调用。
同样的 deployment 名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
### 区域可用性
Azure 图像生成目前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。创建部署前，请查看 Microsoft 当前的区域列表，并确认你的区域提供了特定模型。
Azure 图像生成目前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。创建 deployment 前请查看 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 门户中检查你的特定 deployment 和 API 版本支持的参数集。
<Note>
Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因标头 — 请参阅 [高级配置](#advanced-configuration) 下的**原生路由与 OpenAI 兼容路由**折叠项。
Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因标头——请参阅 [高级配置](#advanced-configuration) 下的 **原生路由与 OpenAI 兼容路由** 折叠项。
对于 Azure 上的聊天或 Responses 流量（图像生成之外），请使用新手引导流程或专用 Azure provider 配置；仅设置 `openai.baseUrl` 不会启用 Azure API/认证形态。存在单独的 `azure-openai-responses/*` provider；请参阅下方的服务端压缩折叠项。
对于 Azure 上的聊天或 Responses 流量（超出图像生成范围），请使用 新手引导 流程或专用 Azure 提供商配置——仅设置 `openai.baseUrl` 不会启用 Azure API/鉴权形态。存在一个单独的 `azure-openai-responses/*` 提供商；请参阅下面的服务器端压缩折叠项。
</Note>
## 高级配置
<AccordionGroup>
<Accordion title="传输（WebSocket 与 SSE）">
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都优先使用 WebSocket，并以 SSE 作为回退（`"auto"`）。
对 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先，并以 SSE 作为回退（`"auto"`）。
在 `"auto"` 模式下，OpenClaw 会：
在 `"auto"` 模式下，OpenClaw：
- 在回退到 SSE 之前重试一次早期 WebSocket 失败
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话与轮次身份标头
- 为重试和重新连接附加稳定的会话与轮次身份标头
- 在传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
| `"auto"`（默认） | 优先 WebSocket，SSE 回退 |
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
| `"sse"` | 仅强制使用 SSE |
| `"websocket"` | 仅强制使用 WebSocket |
@ -647,12 +694,12 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
相关 OpenAI 文档：
- [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
- [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)
- [Streaming API responses（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
@ -677,7 +724,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 priority processing（`service_tier = "priority"`）。现有 `service_tier` 值会被保留，且快速模式不会重写 `reasoning` 或 `text.verbosity`。
```json5
{
@ -692,13 +739,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
```
<Note>
会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，会话会回到已配置的默认值。
会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖会让会话回到已配置的默认值。
</Note>
</Accordion>
<Accordion title="优先处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 公开优先处理。在 OpenClaw 中按模型设置：
OpenAI 的 API 通过 `service_tier` 公开优先处理。在 OpenClaw 中按模型设置它：
```json5
{
@ -715,22 +762,22 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
支持的值：`auto`、`default`、`flex`、`priority`。
<Warning>
`serviceTier` 只会转发给原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 不变。
`serviceTier` 只会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
</Warning>
</Accordion>
<Accordion title="服务端压缩（Responses API）">
<Accordion title="Server-side compaction (Responses API)">
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi harness 流包装器会自动启用服务端压缩：
- 强制 `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="显式启用">
<Tab title="Enable explicitly">
适用于 Azure OpenAI Responses 等兼容端点：
```json5
@ -747,7 +794,7 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
}
```
</Tab>
<Tab title="自定义阈值">
<Tab title="Custom threshold">
```json5
{
agents: {
@ -765,7 +812,7 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
}
```
</Tab>
<Tab title="禁用">
<Tab title="Disable">
```json5
{
agents: {
@ -783,12 +830,12 @@ 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>
<Accordion title="严格智能体式 GPT 模式">
<Accordion title="Strict-agentic GPT mode">
对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：
```json5
@ -802,10 +849,10 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
```
使用 `strict-agentic` 时，OpenClaw：
- 当工具操作可用时，不再将仅规划的回合视为成功进展
- 使用立即行动的 steer 重试该回合
- 为实质性工作自动启用 `update_plan`
- 如果模型持续规划而不行动，则显示明确的受阻状态
- 当工具操作可用时，不再将仅计划的轮次视为成功进展
- 使用立即行动引导重试该轮次
- 对实质性工作自动启用 `update_plan`
- 如果模型持续规划而不行动，则呈现明确的受阻状态
<Note>
仅限 OpenAI 和 Codex GPT-5 系列运行。其他提供商和较旧的模型系列保持默认行为。
@ -813,41 +860,41 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
</Accordion>
<Accordion title="原生路由与 OpenAI 兼容路由">
OpenClaw 对直连 OpenAI、Codex 和 Azure OpenAI 端点的处理不同于通用 OpenAI 兼容 `/v1` 代理：
<Accordion title="Native vs OpenAI-compatible routes">
OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理不同于通用 OpenAI 兼容 `/v1` 代理：
**原生路由**（`openai/*`、Azure OpenAI）：
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
- 对拒绝 `reasoning.effort: "none"` 的模型或代理省略已禁用的 reasoning
- 对会拒绝 `reasoning.effort: "none"` 的模型或代理省略已禁用的 reasoning
- 默认将工具 schema 设为严格模式
- 仅在已验证的原生主机上附加隐藏归因标头
- 保留仅适用于 OpenAI 的请求整形（`service_tier`、`store`、reasoning 兼容、prompt-cache 提示）
- 保留仅 OpenAI 使用的请求整形（`service_tier`、`store`、reasoning 兼容性、提示缓存提示）
**代理/兼容路由：**
- 使用更宽松的兼容行为
- 从非原生 `openai-completions` payload 中剥离 Completions `store`
- 从非原生 `openai-completions` payload 中移除 Completions `store`
- 接受高级 `params.extra_body`/`params.extraBody` 透传 JSON，用于 OpenAI 兼容的 Completions 代理
- 接受 `params.chat_template_kwargs`，用于 vLLM 等 OpenAI 兼容的 Completions 代理
- 不强制使用严格工具 schema 或仅原生标头
- 不强制使用严格工具 schema 或仅原生使用的标头
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因标头。
</Accordion>
</AccordionGroup>
## 相关内容
## 相关
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
<Card title="Model selection" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
<Card title="Image generation" href="/zh-CN/tools/image-generation" icon="image">
共享图像工具参数和提供商选择。
</Card>
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
<Card title="Video generation" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
</Card>
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
认证详情和凭据复用规则。
<Card title="OAuth and auth" href="/zh-CN/gateway/authentication" icon="key">
认证详情和凭证复用规则。
</Card>
</CardGroup>