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-04-25 06:55:27 +00:00
parent e91eff8ae7
commit a02caac2d2
7 changed files with 1104 additions and 865 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
docs/zh-CN/cli/mcp.md
View File

@ -2,90 +2,90 @@
read_when:
- 将 Codex、Claude Code 或其他 MCP 客户端连接到由 OpenClaw 支持的渠道
- 运行 `openclaw mcp serve`
- 管理 OpenClaw 保存的 MCP 服务器定义
- 管理 OpenClaw 已保存的 MCP 服务器定义
summary: 通过 MCP 暴露 OpenClaw 渠道会话，并管理已保存的 MCP 服务器定义
title: MCP
x-i18n:
generated_at: "2026-04-24T03:14:51Z"
generated_at: "2026-04-25T06:52:27Z"
model: gpt-5.4
provider: openai
source_hash: b9df42ebc547f07698f84888d8cd6125340d0f0e02974a965670844589e1fbf8
source_hash: 43505ab290d01a2c3f7dd9ff39b8a074360ba4365b628da71459c6f9a9659dc5
source_path: cli/mcp.md
workflow: 15
---
`openclaw mcp` 有两个职责：
`openclaw mcp` 有两个用途：
- 使用 `openclaw mcp serve` 将 OpenClaw 作为 MCP 服务器运行
- 使用 `list`、`show`、`set` 和 `unset` 管理由 OpenClaw 拥有的出站 MCP 服务器定义
换句话说：
- `serve` 是 OpenClaw 作为 MCP 服务器运行
- `list` / `show` / `set` / `unset` 是 OpenClaw 作为面向其他 MCP 服务器的 MCP 客户端侧注册表运行，供其运行时稍后使用
- `serve` 是 OpenClaw 充当 MCP 服务器
- `list` / `show` / `set` / `unset` 是 OpenClaw 充当其他 MCP 服务器的客户端侧注册表，其运行时稍后可能会使用这些服务器
当 OpenClaw 应该自行托管一个 coding harness 会话并通过 ACP 路由该运行时时，请使用 [`openclaw acp`](/zh-CN/cli/acp)。
当 OpenClaw 应该自行托管一个编码 harness 会话并通过 ACP 路由该运行时时，请使用 [`openclaw acp`](/zh-CN/cli/acp)。
## OpenClaw 作为 MCP 服务器
## 作为 MCP 服务器的 OpenClaw
这就是 `openclaw mcp serve` 这一路径。
这对应 `openclaw mcp serve` 路径。
## 何时使用 `serve`
在以下情况下使用 `openclaw mcp serve`：
- Codex、Claude Code 或其他 MCP 客户端应直接与由 OpenClaw 支持的渠道会话通信
- 你已经拥有一个本地或远程的 OpenClaw Gateway 网关，并且其中有已路由的会话
- 你希望使用一个可跨 OpenClaw 渠道后端工作的 MCP 服务器，而不是为每个渠道分别运行桥接器
- 你已经有一个本地或远程的 OpenClaw Gateway 网关，并且其中已有路由好的会话
- 你希望使用一个可跨 OpenClaw 各渠道后端工作的 MCP 服务器，而不是为每个渠道分别运行独立桥接
当 OpenClaw 应该自行托管 coding 运行时并将智能体会话保留在 OpenClaw 内部时，请改用 [`openclaw acp`](/zh-CN/cli/acp)。
当 OpenClaw 应该自行托管编码运行时并将智能体会话保留在 OpenClaw 内部时，请改用 [`openclaw acp`](/zh-CN/cli/acp)。
## 工作原理
`openclaw mcp serve` 会启动一个 stdio MCP 服务器。该进程由 MCP 客户端拥有。只要客户端保持 stdio 会话打开，桥接器就会通过 WebSocket 连接到本地或远程的 OpenClaw Gateway 网关，并通过 MCP 暴露已路由的渠道会话。
`openclaw mcp serve` 会启动一个 stdio MCP 服务器。该进程由 MCP 客户端拥有。只要客户端保持 stdio 会话处于打开状态，这个桥接器就会通过 WebSocket 连接到本地或远程的 OpenClaw Gateway 网关，并通过 MCP 暴露已路由的渠道会话。
生命周期：
1. MCP 客户端启动 `openclaw mcp serve`
2. 桥接器连接到 Gateway 网关
3. 已路由的会话变为 MCP 会话与 transcript/history 工具
4. 当桥接器保持连接时，实时事件会在内存中排队
5. 如果启用了 Claude 渠道模式，同一会话还可以接收 Claude 专用推送通知
3. 已路由会话变为 MCP 会话以及 transcript/history 工具
4. 只要桥接器保持连接，实时事件就会在内存中排队
5. 如果启用了 Claude 渠道模式，同一个会话还可以接收 Claude 专用推送通知
重要行为：
- 实时队列状态从桥接器连接时开始
- 较早的 transcript 历史通过 `messages_read` 读取
- Claude 推送通知仅在 MCP 会话存活期间存在
- 当客户端断开连接时，桥接器退出，实时队列也随之消失
- 由 OpenClaw 启动的 stdio MCP 服务器（内置或用户配置）会在关闭时按进程树终止，因此服务器启动的子进程不会在父 stdio 客户端退出后继续存活
- 更早的 transcript 历史通过 `messages_read` 读取
- Claude 推送通知仅在 MCP 会话存活时存在
- 当客户端断开连接时，桥接器会退出，实时队列也会消失
- 由 OpenClaw 启动的 stdio MCP 服务器（内置或用户配置）会在关闭时作为进程树被终止，因此该服务器启动的子进程不会在父级 stdio 客户端退出后继续存活
- 删除或重置会话时，会通过共享运行时清理路径释放该会话的 MCP 客户端，因此不会留下与已移除会话绑定的残留 stdio 连接
## 选择客户端模式
同一个桥接器可以通过两种不同方式使用：
同一个桥接器可以用两种不同方式使用：
- 通用 MCP 客户端：仅使用标准 MCP 工具。使用 `conversations_list`、`messages_read`、`events_poll`、`events_wait`、`messages_send` 以及审批工具。
- Claude Code：使用标准 MCP 工具外加 Claude 专用渠道适配器。启用 `--claude-channel-mode on`，或保留默认值 `auto`。
- 通用 MCP 客户端：仅标准 MCP 工具。使用 `conversations_list`、`messages_read`、`events_poll`、`events_wait`、`messages_send` 和审批工具。
- Claude Code：标准 MCP 工具加上 Claude 专用渠道适配器。启用 `--claude-channel-mode on`，或保留默认值 `auto`。
目前，`auto` 的行为与 `on` 相同。当前还没有客户端能力检测。
当前，`auto` 的行为与 `on` 相同。还没有客户端能力检测。
## `serve` 暴露了什么
桥接器使用现有的 Gateway 网关会话路由元数据来暴露由渠道支持的会话。当 OpenClaw 已经拥有带有已知路由的会话状态时，会出现一个会话，例如：
该桥接器使用现有的 Gateway 网关会话路由元数据来暴露由渠道支持的会话。当 OpenClaw 已经拥有带有已知路由的会话状态时，就会出现一个会话，例如：
- `channel`
- recipient 或 destination 元数据
- 收件人或目标元数据
- 可选的 `accountId`
- 可选的 `threadId`
这让 MCP 客户端可以在一个地方：
这让 MCP 客户端可以在一个地方完成以下操作：
- 列出最近已路由的会话
- 读取最近的 transcript 历史
- 等待新的入站事件
- 通过同一路由发送回复
- 查看在桥接器连接期间到达的审批请求
- 通过相同路由发送回复
- 查看桥接器连接期间到达的审批请求
## 用法
@ -122,9 +122,9 @@ openclaw mcp serve --claude-channel-mode off
### `conversations_list`
列出最近那些在 Gateway 网关会话状态中已经具有路由元数据的、由会话支持的会话。
列出最近那些已经在 Gateway 网关会话状态中带有路由元数据的、由会话支持的会话。
有用的过滤器：
常用过滤条件：
- `limit`
- `search`
@ -138,30 +138,30 @@ openclaw mcp serve --claude-channel-mode off
### `messages_read`
读取一个由会话支持的会话中的最近 transcript 消息。
读取一个由会话支持的会话的最近 transcript 消息。
### `attachments_fetch`
从一条 transcript 消息中提取非文本消息内容块。这是针对 transcript 内容的元数据视图，而不是一个独立、持久的附件 blob 存储。
从一条 transcript 消息中提取非文本消息内容块。这是 transcript 内容的元数据视图，不是一个独立的持久化附件 blob 存储。
### `events_poll`
读取自某个数值游标以来排队的实时事件。
从某个数字游标开始读取已排队的实时事件。
### `events_wait`
长轮询，直到下一个匹配的排队事件到达或超时。
当通用 MCP 客户端需要接近实时的投递能力，但又不使用 Claude 专用推送协议时，请使用它。
当通用 MCP 客户端需要接近实时的传递而又不使用 Claude 专用推送协议时，可使用此工具。
### `messages_send`
通过会话中已记录的同一路由发送文本。
通过该会话上已记录的相同路由发回文本。
当前行为：
- 需要现有的会话路由
- 使用会话的 channel、recipient、account id 和 thread id
- 需要已有会话路由
- 使用该会话的渠道、收件人、账号 id 和线程 id
- 仅发送文本
### `permissions_list_open`
@ -170,7 +170,7 @@ openclaw mcp serve --claude-channel-mode off
### `permissions_respond`
使用以下值之一来处理一个待处理的 exec/plugin 审批请求：
用以下值之一处理一个待处理的 exec/plugin 审批请求：
- `allow-once`
- `allow-always`
@ -191,13 +191,13 @@ openclaw mcp serve --claude-channel-mode off
重要限制：
- 该队列仅用于实时事件；它从 MCP 桥接器启动时开始
- `events_poll` 和 `events_wait` 本身不会重放较早的 Gateway 网关历史
- 持久积压消息应使用 `messages_read` 读取
- 队列仅包含实时事件；它从 MCP 桥接启动时开始
- `events_poll` 和 `events_wait` 本身不会重放更早的 Gateway 网关历史
- 持久化积压历史应通过 `messages_read` 读取
## Claude 渠道通知
桥接器还可以暴露 Claude 专用渠道通知。这相当于 OpenClaw 版本的 Claude Code 渠道适配器：标准 MCP 工具仍然可用，但实时入站消息也可以作为 Claude 专用 MCP 通知到达。
桥接器还可以暴露 Claude 专用渠道通知。这相当于 OpenClaw 版的 Claude Code 渠道适配器：标准 MCP 工具仍然可用，但实时入站消息也可以作为 Claude 专用 MCP 通知到达。
标志：
@ -215,9 +215,9 @@ openclaw mcp serve --claude-channel-mode off
- 入站的 `user` transcript 消息会被转发为 `notifications/claude/channel`
- 通过 MCP 接收到的 Claude 权限请求会在内存中跟踪
- 如果关联会话随后发送 `yes abcde` 或 `no abcde`，桥接器会将其转换为 `notifications/claude/channel/permission`
- 这些通知仅在实时会话期间存在；如果 MCP 客户端断开连接，就不再有推送目标
- 这些通知仅在实时会话期间存在；如果 MCP 客户端断开连接，就没有推送目标了
这是有意设计为客户端专用的。通用 MCP 客户端应依赖标准轮询工具。
这特意是面向特定客户端的。通用 MCP 客户端应依赖标准轮询工具。
## MCP 客户端配置
@ -241,7 +241,7 @@ openclaw mcp serve --claude-channel-mode off
}
```
对于大多数通用 MCP 客户端，请先从标准工具接口开始，并忽略 Claude 模式。仅当客户端确实理解 Claude 专用通知方法时，再开启 Claude 模式。
对于大多数通用 MCP 客户端，先从标准工具接口开始，并忽略 Claude 模式。只有在客户端确实理解 Claude 专用通知方法时，才开启 Claude 模式。
## 选项
@ -255,70 +255,70 @@ openclaw mcp serve --claude-channel-mode off
- `--claude-channel-mode <auto|on|off>`：Claude 通知模式
- `-v`, `--verbose`：在 stderr 上输出详细日志
如果可能，优先使用 `--token-file` 或 `--password-file`，而不是内联密钥。
如有可能，优先使用 `--token-file` 或 `--password-file`，而不是内联秘密信息。
## 安全性与信任边界
桥接器不会自行发明路由。它只会暴露 Gateway 网关已经知道如何路由的会话。
桥接器不会发明路由。它只暴露 Gateway 网关已经知道如何路由的会话。
这意味着：
- 发送者 allowlist、配对以及渠道级信任，仍然属于底层 OpenClaw 渠道配置的职责范围
- `messages_send` 只能通过现有的已存储路由进行回复
- 审批状态对于当前桥接会话来说仅是实时/内存中的
- 桥接认证应使用与你会信任给其他任何远程 Gateway 网关客户端相同的 Gateway 网关令牌或密码控制方式
- 发送者 allowlist、配对和渠道级信任，仍然属于底层 OpenClaw 渠道配置
- `messages_send` 只能通过一个已存在的已存储路由进行回复
- 审批状态仅对当前桥接会话实时保存在内存中
- 桥接认证应使用与你信任任何其他远程 Gateway 网关客户端相同的 Gateway 网关令牌或密码控制
如果某个会话没有出现在 `conversations_list` 中，通常原因不是 MCP 配置，而是底层 Gateway 网关会话中缺少路由元数据，或其不完整。
如果某个会话未出现在 `conversations_list` 中，通常原因不是 MCP 配置，而是底层 Gateway 网关会话中缺少或存在不完整的路由元数据。
## 测试
OpenClaw 为这个桥接器提供了一个确定性的 Docker smoke 测试：
OpenClaw 为这个桥接器提供了一个确定性的 Docker 冒烟测试：
```bash
pnpm test:docker:mcp-channels
```
该 smoke 测试会：
该冒烟测试会：
- 启动一个已注入种子数据的 Gateway 网关容器
- 启动一个已预置数据的 Gateway 网关容器
- 启动第二个容器，并在其中启动 `openclaw mcp serve`
- 验证会话发现、transcript 读取、附件元数据读取、实时事件队列行为，以及出站发送路由
- 验证会话发现、transcript 读取、附件元数据读取、实时事件队列行为以及出站发送路由
- 通过真实的 stdio MCP 桥接验证 Claude 风格的渠道通知和权限通知
这是在不把真实 Telegram、Discord 或 iMessage 账户接入测试流程的情况下，证明桥接器可正常工作的最快方式。
这是在不将真实 Telegram、Discord 或 iMessage 账号接入测试运行的情况下，证明桥接器可正常工作的最快方法。
有关更广泛的测试背景，请参见 [测试](/zh-CN/help/testing)。
如需更广泛的测试背景，请参阅 [测试](/zh-CN/help/testing)。
## 故障排除
### 没有返回任何会话
通常意味着 Gateway 网关会话尚不可路由。请确认底层会话已存储 channel/provider、recipient，以及可选的 account/thread 路由元数据。
通常表示 Gateway 网关会话本身还不可路由。请确认底层会话已存储渠道/提供商、收件人，以及可选的账号/线程路由元数据。
### `events_poll` 或 `events_wait` 漏掉了较早的消息
### `events_poll` 或 `events_wait` 漏掉较早的消息
这是预期行为。实时队列从桥接器连接时开始。较早的 transcript 历史请用 `messages_read` 读取。
这是预期行为。实时队列从桥接器连接时开始。请使用 `messages_read` 读取更早的 transcript 历史。
### Claude 通知没有出现
### Claude 通知没有显示
请检查以下所有项目：
请检查以下各项：
- 客户端保持了 stdio MCP 会话处于打开状态
- `--claude-channel-mode` 是 `on` 或 `auto`
- `--claude-channel-mode` 为 `on` 或 `auto`
- 客户端确实理解 Claude 专用通知方法
- 入站消息发生在桥接器连接之后
### 审批缺失
`permissions_list_open` 只显示桥接器连接期间观察到的审批请求。它不是一个持久化的审批历史 API。
`permissions_list_open` 仅显示桥接器连接期间观察到的审批请求。它不是持久化审批历史 API。
## OpenClaw 作为 MCP 客户端注册表
这就是 `openclaw mcp list`、`show`、`set` 和 `unset` 这一路径。
这对应 `openclaw mcp list`、`show`、`set` 和 `unset` 路径。
这些命令不会通过 MCP 暴露 OpenClaw。它们管理的是 OpenClaw 配置中 `mcp.servers` 下由 OpenClaw 拥有的 MCP 服务器定义。
这些命令不会通过 MCP 暴露 OpenClaw。它们用于管理 OpenClaw 配置中 `mcp.servers` 下由 OpenClaw 拥有的 MCP 服务器定义。
这些已保存的定义供 OpenClaw 稍后启动或配置的运行时使用，例如内嵌 Pi 和其他运行时适配器。OpenClaw 将这些定义集中存储，因此这些运行时不需要各自维护重复的 MCP 服务器列表。
这些已保存的定义供 OpenClaw 稍后启动或配置的运行时使用，例如内嵌 Pi 和其他运行时适配器。OpenClaw 会集中存储这些定义，这样这些运行时就不需要各自维护重复的 MCP 服务器列表。
重要行为：
@ -327,10 +327,11 @@ pnpm test:docker:mcp-channels
- 它们不会验证命令、URL 或远程传输当前是否可达
- 运行时适配器会在执行时决定自己实际支持哪些传输形态
- 内嵌 Pi 会在常规 `coding` 和 `messaging` 工具配置文件中暴露已配置的 MCP 工具；`minimal` 仍会隐藏它们，而 `tools.deny: ["bundle-mcp"]` 会显式禁用它们
- 会话范围的内置 MCP 运行时会在空闲 `mcp.sessionIdleTtlMs` 毫秒后被回收（默认 10 分钟；设为 `0` 可禁用），一次性内嵌运行则会在运行结束时清理它们
## 已保存的 MCP 服务器定义
OpenClaw 还会在配置中存储一个轻量级 MCP 服务器注册表，供那些希望使用 OpenClaw 管理的 MCP 定义的界面使用。
OpenClaw 还会在配置中存储一个轻量级 MCP 服务器注册表，供希望使用 OpenClaw 管理的 MCP 定义的界面使用。
命令：
@ -343,7 +344,7 @@ OpenClaw 还会在配置中存储一个轻量级 MCP 服务器注册表，供那
- `list` 会对服务器名称排序。
- 不带名称的 `show` 会打印完整的已配置 MCP 服务器对象。
- `set` 需要在命令行中提供一个 JSON 对象值。
- `set` 需要在命令行中传入一个 JSON 对象值。
- 如果指定名称的服务器不存在，`unset` 会失败。
示例：
@ -387,19 +388,19 @@ openclaw mcp unset context7
#### Stdio 环境变量安全过滤器
OpenClaw 会拒绝那些可能在第一次 RPC 之前改变 stdio MCP 服务器启动方式的解释器启动环境变量键，即使它们出现在服务器的 `env` 块中也是如此。被拦截的键包括 `NODE_OPTIONS`、`PYTHONSTARTUP`、`PYTHONPATH`、`PERL5OPT`、`RUBYOPT`、`SHELLOPTS`、`PS4` 以及类似的运行时控制变量。启动时会以配置错误的形式拒绝这些键，从而防止它们注入隐式前导代码、替换解释器，或为 stdio 进程启用调试器。普通的凭据、代理和服务器专用环境变量（`GITHUB_TOKEN`、`HTTP_PROXY`、自定义 `*_API_KEY` 等）不受影响。
OpenClaw 会拒绝那些可能在第一次 RPC 之前改变 stdio MCP 服务器启动方式的解释器启动环境变量键，即使它们出现在服务器的 `env` 块中也是如此。被阻止的键包括 `NODE_OPTIONS`、`PYTHONSTARTUP`、`PYTHONPATH`、`PERL5OPT`、`RUBYOPT`、`SHELLOPTS`、`PS4` 以及类似的运行时控制变量。对于这些键，启动会以配置错误被拒绝，这样它们就无法注入隐式前导代码、替换解释器，或对 stdio 进程启用调试器。普通凭证、代理和服务器专用环境变量（`GITHUB_TOKEN`、`HTTP_PROXY`、自定义 `*_API_KEY` 等）不受影响。
如果你的 MCP 服务器确实需要某个被拦截的变量，请将其设置在 Gateway 网关宿主进程上，而不是放在 stdio 服务器的 `env` 下。
如果你的 MCP 服务器确实需要其中某个被阻止的变量，请在 Gateway 网关宿主进程上设置它，而不是放在 stdio 服务器的 `env` 下。
### SSE / HTTP 传输
通过 HTTP Server-Sent Events 连接到远程 MCP 服务器。
| Field | Description |
| --------------------- | ---------------------------------------- |
| `url` | 远程服务器的 HTTP 或 HTTPS URL（必需） |
| Field | Description |
| --------------------- | -------------------------------------- |
| `url` | 远程服务器的 HTTP 或 HTTPS URL（必需） |
| `headers` | 可选的 HTTP 标头键值映射（例如认证令牌） |
| `connectionTimeoutMs` | 每个服务器的连接超时（毫秒，可选） |
| `connectionTimeoutMs` | 每个服务器的连接超时时间（毫秒，可选） |
示例：
@ -418,18 +419,18 @@ OpenClaw 会拒绝那些可能在第一次 RPC 之前改变 stdio MCP 服务器
}
```
`url` 中的敏感值（userinfo）和 `headers` 中的敏感值会在日志和状态输出中被打码。
`url` 中的敏感值（userinfo）以及 `headers` 中的敏感值，会在日志和状态输出中被脱敏。
### Streamable HTTP 传输
### 可流式 HTTP 传输
`streamable-http` 是与 `sse` 和 `stdio` 并列的另一种传输选项。它使用 HTTP 流式传输与远程 MCP 服务器进行双向通信。
`streamable-http` 是与 `sse` 和 `stdio` 并列的额外传输选项。它使用 HTTP 流进行双向通信，以连接远程 MCP 服务器。
| Field | Description |
| --------------------- | ------------------------------------------------------------------- |
| `url` | 远程服务器的 HTTP 或 HTTPS URL（必需） |
| `transport` | 设为 `"streamable-http"` 以选择此传输；省略时，OpenClaw 使用 `sse` |
| `headers` | 可选的 HTTP 标头键值映射（例如认证令牌） |
| `connectionTimeoutMs` | 每个服务器的连接超时（毫秒，可选） |
| Field | Description |
| --------------------- | ------------------------------------------------------------------------------ |
| `url` | 远程服务器的 HTTP 或 HTTPS URL（必需） |
| `transport` | 设置为 `"streamable-http"` 以选择此传输方式；若省略，OpenClaw 将使用 `sse` |
| `headers` | 可选的 HTTP 标头键值映射（例如认证令牌） |
| `connectionTimeoutMs` | 每个服务器的连接超时时间（毫秒，可选） |
示例：
@ -450,18 +451,18 @@ OpenClaw 会拒绝那些可能在第一次 RPC 之前改变 stdio MCP 服务器
}
```
这些命令只管理已保存的配置。它们不会启动渠道桥接器、打开实时 MCP 客户端会话，也不能证明目标服务器当前可达。
这些命令只管理已保存的配置。它们不会启动渠道桥接、打开实时 MCP 客户端会话，也不会证明目标服务器当前可达。
## 当前限制
本页记录的是当前已发布的桥接器行为。
本页记录的是当前发布版本中的桥接器行为。
当前限制：
- 会话发现依赖现有 Gateway 网关会话路由元数据
- 除 Claude 专用适配器外，尚无通用推送协议
- 目前还没有消息编辑或 react 工具
- HTTP/SSE/streamable-http 传输会连接到单个远程服务器；目前还不支持多路复用上游
- 会话发现依赖现有的 Gateway 网关会话路由元数据
- 除了 Claude 专用适配器外，尚无通用推送协议
- 还没有消息编辑或表情回应工具
- HTTP/SSE/streamable-http 传输连接到单个远程服务器；尚不支持多路复用上游
- `permissions_list_open` 仅包含桥接器连接期间观察到的审批
## 相关内容

118
docs/zh-CN/cli/models.md
View File

@ -1,27 +1,27 @@
---
read_when:
- 你想更改默认模型或查看提供商认证状态
- 你想扫描可用的模型/提供商，并调试认证配置文件
summary: '`openclaw models` 的 CLI 参考（状态/列表/设置/扫描、别名、回退和认证）'
title: 模型
- 你想更改默认模型或查看提供商身份验证状态。
- 你想扫描可用的模型/提供商并调试身份验证配置文件。
summary: '`openclaw models` 的 CLI 参考（status/list/set/scan、别名、回退机制、身份验证）'
title: Models
x-i18n:
generated_at: "2026-04-24T03:15:02Z"
generated_at: "2026-04-25T06:52:25Z"
model: gpt-5.4
provider: openai
source_hash: 08e04342ef240bf7a1f60c4d4e2667d17c9a97e985c1b170db8538c890dc8119
source_hash: 2755657b334b8722da06e31fa1d69a5dced3d74e5aeadd38d625039f15911d69
source_path: cli/models.md
workflow: 15
---
# `openclaw models`
模型发现、扫描和配置（默认模型、回退和认证配置文件）。
模型发现、扫描和配置（默认模型、回退机制、身份验证配置文件）。
相关内容：
- 提供商 + 模型：[模型](/zh-CN/providers/models)
- 模型选择概念 + `/models` 斜杠命令：[模型概念](/zh-CN/concepts/models)
- 提供商认证设置：[入门指南](/zh-CN/start/getting-started)
- 提供商 + 模型：[Models](/zh-CN/providers/models)
- 模型选择概念 + `/models` 斜杠命令：[Models 概念](/zh-CN/concepts/models)
- 提供商身份验证设置：[入门指南](/zh-CN/start/getting-started)
## 常用命令
@ -32,38 +32,44 @@ openclaw models set <model-or-alias>
openclaw models scan
```
`openclaw models status` 会显示已解析的默认值/回退值以及认证概览。
当提供商使用情况快照可用时，OAuth/API 密钥状态部分会包含提供商使用窗口和配额快照。
当前支持使用窗口的提供商有：Anthropic、GitHub Copilot、Gemini CLI、OpenAI
Codex、MiniMax、Xiaomi 和 z.ai。使用情况认证在可用时来自提供商特定的钩子；
否则，OpenClaw 会回退为从认证配置文件、环境变量或配置中匹配 OAuth/API 密钥
凭证。
`openclaw models status` 会显示已解析的默认值/回退项以及身份验证概览。
当提供商使用情况快照可用时，OAuth/API 密钥状态部分会包含
提供商使用时间窗口和配额快照。
当前支持使用情况时间窗口的提供商有：Anthropic、GitHub Copilot、Gemini CLI、OpenAI
Codex、MiniMax、Xiaomi 和 z.ai。使用情况身份验证在可用时来自提供商特定的钩子；
否则 OpenClaw 会回退为匹配来自身份验证配置文件、环境变量或配置中的
OAuth/API 密钥凭证。
在 `--json` 输出中，`auth.providers` 是感知环境变量/配置/存储的提供商
概览，而 `auth.oauth` 仅表示认证存储中的配置文件健康状态。
添加 `--probe` 可针对每个已配置的提供商配置文件运行实时认证探测。
探测会发出真实请求（可能会消耗令牌并触发速率限制）。
使用 `--agent <id>` 可检查某个已配置智能体的模型/认证状态。省略时，
该命令会在设置了 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` 时使用它们，否则使用
已配置的默认智能体。
探测行可能来自认证配置文件、环境变量凭证或 `models.json`。
概览，而 `auth.oauth` 仅是身份验证存储中配置文件健康状态。
添加 `--probe` 可对每个已配置的提供商配置文件运行实时身份验证探测。
探测会发出真实请求（可能消耗令牌并触发速率限制）。
使用 `--agent <id>` 可检查某个已配置智能体的模型/身份验证状态。省略时，
该命令会在设置了 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` 时使用它们，
否则使用已配置的默认智能体。
探测行可能来自身份验证配置文件、环境变量凭证或 `models.json`。
说明：
- `models set <model-or-alias>` 接受 `provider/model` 或别名。
- `models list` 是只读的：它会读取配置、认证配置文件、现有目录
状态和提供商自有的目录条目，但不会重写
- `models list` 是只读的：它会读取配置、身份验证配置文件、现有目录
状态以及提供商自有的目录行，但不会重写
`models.json`。
- `models list --all` 会包含内置的、由提供商自有的静态目录条目，即使
你尚未使用该提供商完成认证也是如此。这些条目仍会显示为不可用，直到配置好匹配的认证。
- `models list --all` 会包含提供商自带的静态目录行，即使你
还未对此提供商完成身份验证。这些行仍会显示为不可用，直到配置了匹配的身份验证。
- `models list` 会将原生模型元数据和运行时能力上限区分开来。在表格
输出中，如果有效运行时上限与原生上下文窗口不同，`Ctx` 会显示 `contextTokens/contextWindow`；JSON 行会包含 `contextTokens`，
前提是提供商暴露了该上限。
- `models list --provider <id>` 按提供商 id 过滤，例如 `moonshot` 或
`openai-codex`。它不接受交互式提供商选择器中的显示标签，例如 `Moonshot AI`。
`openai-codex`。它不接受交互式提供商
选择器中的显示标签，例如 `Moonshot AI`。
- 模型引用通过按**第一个** `/` 进行拆分来解析。如果模型 ID 包含 `/`（OpenRouter 风格），请包含提供商前缀（例如：`openrouter/moonshotai/kimi-k2`）。
- 如果你省略了提供商，OpenClaw 会先将输入解析为别名，然后
解析为对该精确模型 id 的唯一已配置提供商匹配，最后才会回退到已配置的默认提供商，并显示弃用警告。
如果该提供商不再公开已配置的默认模型，OpenClaw
会回退到第一个已配置的提供商/模型，而不是暴露一个
已删除提供商的陈旧默认值。
- `models status` 可能会在认证输出中显示 `marker(<value>)`，用于表示非秘密占位符（例如 `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`），而不是将它们作为秘密值进行掩码。
- 如果你省略提供商，OpenClaw 会先将输入解析为别名，然后
解析为精确匹配该模型 id 的唯一已配置提供商，最后才
以弃用警告的方式回退到已配置的默认提供商。
如果该提供商不再暴露已配置的默认模型，OpenClaw
会回退到第一个已配置的提供商/模型，而不是显示一个
过时的、已移除提供商默认值。
- `models status` 可能会在身份验证输出中显示 `marker(<value>)`，用于表示非机密占位符（例如 `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`），而不是像机密信息那样进行掩码处理。
### `models status`
@ -72,13 +78,13 @@ Codex、MiniMax、Xiaomi 和 z.ai。使用情况认证在可用时来自提供
- `--json`
- `--plain`
- `--check`（退出码 1=已过期/缺失，2=即将过期）
- `--probe`（对已配置认证配置文件进行实时探测）
- `--probe`（对已配置的身份验证配置文件进行实时探测）
- `--probe-provider <name>`（探测单个提供商）
- `--probe-profile <id>`（可重复传入或使用逗号分隔的配置文件 id）
- `--probe-profile <id>`（可重复使用，或使用逗号分隔的配置文件 id）
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
- `--agent <id>`（已配置的智能体 id；会覆盖 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`）
- `--agent <id>`（已配置的智能体 id；覆盖 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`）
探测状态分组：
@ -91,24 +97,24 @@ Codex、MiniMax、Xiaomi 和 z.ai。使用情况认证在可用时来自提供
- `unknown`
- `no_model`
预期的探测详情/原因代码情况：
可预期的探测详情/原因代码情况：
- `excluded_by_auth_order`：存在已存储的配置文件，但显式的
`auth.order.<provider>` 未包含它，因此探测会报告该排除情况，而不是
- `excluded_by_auth_order`：存在已存储的配置文件，但显式
`auth.order.<provider>` 省略了它，因此探测会报告该排除，而不是
尝试使用它。
- `missing_credential`、`invalid_expires`、`expired`、`unresolved_ref`：
配置文件存在，但不符合条件/无法解析。
- `no_model`：提供商认证存在，但 OpenClaw 无法为该提供商解析出可用于探测的
- `no_model`：提供商身份验证存在，但 OpenClaw 无法为该提供商解析出可用于探测的
模型候选项。
## 别名 + 回退
## 别名 + 回退机制
```bash
openclaw models aliases list
openclaw models fallbacks list
```
## 认证配置文件
## 身份验证配置文件
```bash
openclaw models auth add
@ -117,10 +123,10 @@ openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
```
`models auth add` 是交互式认证辅助工具。它可以启动提供商认证
流程（OAuth/API 密钥），或根据你选择的提供商，引导你手动粘贴令牌。
`models auth add` 是交互式身份验证辅助工具。它可以启动提供商身份验证
流程（OAuth/API 密钥），或根据你选择的提供商引导你手动粘贴令牌。
`models auth login` 会运行提供商插件的认证流程（OAuth/API 密钥）。使用
`models auth login` 会运行提供商插件的身份验证流程（OAuth/API 密钥）。使用
`openclaw plugins list` 可查看已安装了哪些提供商。
示例：
@ -131,18 +137,20 @@ openclaw models auth login --provider openai-codex --set-default
说明：
- `setup-token` 和 `paste-token` 仍然是面向提供令牌认证方法的提供商的通用令牌命令。
- `setup-token` 需要交互式 TTY，并运行该提供商的令牌认证
方法（当该提供商暴露此方法时，默认使用其 `setup-token` 方法）。
- `paste-token` 接受在其他地方生成或由自动化产生的令牌字符串。
- `setup-token` 和 `paste-token` 仍然是面向暴露令牌身份验证方法的提供商的通用
令牌命令。
- `setup-token` 需要交互式 TTY，并运行该提供商的令牌身份验证
方法（当该提供商暴露了 `setup-token` 方法时，默认使用该方法）。
- `paste-token` 接受在其他地方或通过自动化生成的令牌字符串。
- `paste-token` 需要 `--provider`，会提示输入令牌值，并将其写入默认配置文件 id `<provider>:manual`，除非你传入
`--profile-id`。
- `paste-token --expires-in <duration>` 会根据相对时长（例如 `365d` 或 `12h`）存储一个绝对的令牌过期时间。
- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成的获准方式，除非 Anthropic 发布新的政策。
- Anthropic 的 `setup-token` / `paste-token` 仍可作为受支持的 OpenClaw 令牌路径使用，但现在 OpenClaw 在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。
- `paste-token --expires-in <duration>` 会根据相对时长存储一个绝对令牌过期时间，例如
`365d` 或 `12h`。
- Anthropic 说明：Anthropic 工作人员告诉我们，再次允许 OpenClaw 风格的 Claude CLI 使用方式，因此除非 Anthropic 发布新的策略，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的受支持方式。
- Anthropic 的 `setup-token` / `paste-token` 仍然可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在在可用时更推荐使用 Claude CLI 复用和 `claude -p`。
## 相关
## 相关内容
- [CLI 参考](/zh-CN/cli)
- [模型选择](/zh-CN/concepts/model-providers)
- [模型故障切换](/zh-CN/concepts/model-failover)
- [模型故障转移](/zh-CN/concepts/model-failover)

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

@ -1,78 +1,78 @@
---
read_when:
- 你需要一份按提供商分类的模型设置参考资料
- 你想要模型提供商的示例配置或 CLI 新手引导命令
summary: 模型提供商概览，包含示例配置和 CLI 流程
- 你需要一份按提供商逐一说明的模型设置参考文档
- 你想要针对模型提供商的示例配置或 CLI 新手引导命令
summary: 模型提供商概览，包含示例配置 + CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-04-25T05:54:03Z"
generated_at: "2026-04-25T06:52:24Z"
model: gpt-5.4
provider: openai
source_hash: bdab460823e3138377a7e2b183b31caa64bb2eef4c9e77ebd8db0aacc97493bb
source_hash: fe2871809711608b3e1d996084b834978b15f21dfeea1ac767dce4c1299be0aa
source_path: concepts/model-providers.md
workflow: 15
---
**LLM/模型提供商**参考（不是像 WhatsApp/Telegram 这样的聊天渠道）。有关模型选择规则，请参见 [Models](/zh-CN/concepts/models)。
针对 **LLM/模型提供商** 的参考文档（不是像 WhatsApp/Telegram 这样的聊天渠道）。关于模型选择规则，请参阅 [Models](/zh-CN/concepts/models)。
## 快速规则
- 模型引用使用 `provider/model`（例如：`opencode/claude-opus-4-6`）。
- 设置后，`agents.defaults.models` 会作为允许列表。
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
- 设置后，`agents.defaults.models` 会作为允许列表生效。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- `models.providers.*.models[].contextWindow` 是原生模型元数据；`contextTokens` 是运行时生效的上限。
- 回退规则、冷却探测和会话覆盖持久化：参见 [模型故障转移](/zh-CN/concepts/model-failover)。
- OpenAI 系列路由按前缀区分：`openai/<model>` 在 PI 中使用直接的 OpenAI API 密钥提供商，`openai-codex/<model>` 在 PI 中使用 Codex OAuth，而 `openai/<model>` 加上 `agents.defaults.embeddedHarness.runtime: "codex"` 则使用原生 Codex app-server harness。参见 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果你对 provider/运行时的拆分感到困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
- 插件自动启用遵循相同边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件则通过 `embeddedHarness.runtime: "codex"` 或旧版 `codex/<model>` 引用启用。
- CLI 运行时也使用相同拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在你想使用本地 CLI 后端时，将 `agents.defaults.embeddedHarness.runtime` 设为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并将运行时单独记录。
- GPT-5.5 当前通过订阅/OAuth 路由提供：PI 中使用 `openai-codex/gpt-5.5`，或使用带 Codex app-server harness 的 `openai/gpt-5.5`。`openai/gpt-5.5` 的直接 API 密钥路由会在 OpenAI 在公共 API 上启用 GPT-5.5 后受支持；在此之前，请为 `OPENAI_API_KEY` 配置使用已启用 API 的模型，例如 `openai/gpt-5.4`。
- `models.providers.*.models[].contextWindow` 是模型原生元数据；`contextTokens` 是运行时生效的上限。
- 故障切换规则、冷却探测以及会话覆盖持久化：请参阅 [Model failover](/zh-CN/concepts/model-failover)。
- OpenAI 系列路由按前缀区分：`openai/<model>` 使用 PI 中基于直接 OpenAI API 密钥的 provider，`openai-codex/<model>` 使用 PI 中的 Codex OAuth，而 `openai/<model>` 加上 `agents.defaults.embeddedHarness.runtime: "codex"` 则使用原生 Codex app-server harness。请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果 provider/运行时 的划分让你感到困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
- 插件自动启用遵循相同的边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件由 `embeddedHarness.runtime: "codex"` 或旧版 `codex/<model>` 引用启用。
- CLI 运行时 也使用相同的划分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在你想使用本地 CLI 后端时，将 `agents.defaults.embeddedHarness.runtime` 设为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范 provider 引用，并将运行时 单独记录。
- GPT-5.5 可通过 PI 中的 `openai-codex/gpt-5.5`、原生 Codex app-server harness，以及当内置 PI 目录为你的安装暴露 `openai/gpt-5.5` 时通过公共 OpenAI API 使用。
## 由插件拥有的 provider 行为
## 插件拥有的 provider 行为
大多数提供商特定逻辑都位于 provider 插件中（`registerProvider(...)`），而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置文件等。
大多数 provider 特定逻辑都位于 provider 插件（`registerProvider(...)`）中，而 OpenClaw 负责保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障切换分类、OAuth 刷新、使用情况上报、thinking/reasoning 配置等。
完整的 provider SDK 钩子列表和内置插件示例见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，那属于另一个更深层的扩展面。
provider SDK 钩子和内置插件示例的完整列表位于 [Provider plugins](/zh-CN/plugins/sdk-provider-plugins)。如果某个 provider 需要完全自定义的请求执行器，那将属于另一个更深层的扩展接口。
<Note>
provider 运行时 `capabilities` 是共享运行器元数据（provider 家族、转录/工具特性、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。
provider 运行时 `capabilities` 是共享运行器元数据（provider 系列、转录/工具使用特殊行为、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么（文本推理、语音等）。
</Note>
## API 密钥轮换
- 支持所选提供商的通用提供商轮换。
- 对选定的 provider 支持通用 provider 轮换。
- 可通过以下方式配置多个密钥：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号分隔列表）
- `<PROVIDER>_API_KEYS`（逗号或分号分隔的列表）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退选项。
- 密钥选择顺序会保留优先级并去重。
- 只有在收到速率限制响应时，请求才会使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
- 非速率限制失败会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，返回最后一次尝试的最终错误。
- 对于 Google provider，`GOOGLE_API_KEY` 也会作为回退包含在内。
- 密钥选择顺序会保留优先级并对值去重。
- 仅在遇到限流响应时，请求才会使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
- 非限流失败会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，会返回最后一次尝试的最终错误。
## 内置提供商（pi-ai 目录）
## 内置 provider（pi-ai 目录）
OpenClaw 自带 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证信息并选择模型。
OpenClaw 附带 pi‑ai 目录。这些 provider **不需要**
`models.providers` 配置；只需设置认证信息并选择一个模型。
### OpenAI
- Provider：`openai`
- 认证：`OPENAI_API_KEY`
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
- 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-mini`
- 一旦 OpenAI 在 API 上公开 GPT-5.5，这里就已为 GPT-5.5 直接 API 支持做好准备
- 在不使用 Codex app-server 运行时的情况下使用 `openai/gpt-5.5` 前，请先用 `openclaw models list --provider openai` 验证直接 API 可用性
- 示例模型：`openai/gpt-5.5`、`openai/gpt-5.4`、`openai/gpt-5.4-mini`
- GPT-5.5 直接 API 支持取决于你的安装所附带的 PI 目录版本；在不使用 Codex app-server 运行时 的情况下使用 `openai/gpt-5.5` 之前，请先通过 `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"`）
- 可按模型通过 `agents.defaults.models["openai/<model>"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`）
- OpenAI 优先级处理可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用
- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射为 `api.openai.com` 上的 `service_tier=priority`
- 如果你想使用显式分层而不是共享的 `/fast` 开关，请使用 `params.serviceTier`
- 当你想要显式指定层级，而不是使用共享的 `/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 目录也未公开它
- 原生 OpenAI 路由还会保留 Responses `store`、prompt-cache 提示以及 OpenAI reasoning 兼容负载整形；代理路由则不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为实时 OpenAI API 请求会拒绝它，而当前 Codex 目录也未暴露它
```json5
{
@ -87,9 +87,9 @@ OpenClaw 自带 pi‑ai 目录。这些提供商**不需要** `models.providers`
- 可选轮换：`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 密钥和 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 或 `standard_only`）
- Anthropic 说明：Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的已授权方式。
- Anthropic setup-token 仍作为 OpenClaw 支持的令牌路径提供，但 OpenClaw 现在在可用时更倾向于 Claude CLI 复用和 `claude -p`。
- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥认证与 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`）
- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为该集成的许可方式，除非 Anthropic 发布新的策略。
- Anthropic setup-token 仍然是 OpenClaw 支持的令牌路径，但 OpenClaw 现在在可用时优先使用 Claude CLI 复用和 `claude -p`。
```json5
{
@ -102,19 +102,19 @@ OpenClaw 自带 pi‑ai 目录。这些提供商**不需要** `models.providers`
- Provider：`openai-codex`
- 认证：OAuth（ChatGPT）
- PI 模型引用：`openai-codex/gpt-5.5`
- 原生 Codex app-server harness 引用：带 `agents.defaults.embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.5`
- 原生 Codex app-server harness 引用：`openai/gpt-5.5`，配合 `agents.defaults.embeddedHarness.runtime: "codex"`
- 原生 Codex app-server harness 文档：[Codex harness](/zh-CN/plugins/codex-harness)
- 旧版模型引用：`codex/gpt-*`
- 插件边界：`openai-codex/*` 加载 OpenAI 插件；原生 Codex app-server 插件仅通过 Codex harness 运行时或旧版 `codex/*` 引用选择
- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex app-server 插件仅由 Codex harness 运行时 或旧版 `codex/*` 引用选择。
- 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 兼容代理
- 可按 PI 模型通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `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` 保留原生 `contextWindow = 1000000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- `openai-codex/gpt-5.5` 使用 Codex 目录原生 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时 上限
- 策略说明：OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具/工作流。
- 在 OpenAI 于公共 API 上启用 GPT-5.5 之前，当前 GPT-5.5 访问都通过此 OAuth/订阅路由进行。
- 当你想使用 Codex OAuth/订阅路径时，请使用 `openai-codex/gpt-5.5`；当你的 API 密钥设置和本地目录暴露了公共 API 路径时，请使用 `openai/gpt-5.5`。
```json5
{
@ -136,7 +136,7 @@ OpenClaw 自带 pi‑ai 目录。这些提供商**不需要** `models.providers`
### 其他订阅式托管选项
- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud provider 能力面，以及阿里巴巴 DashScope 和 Coding Plan 端点映射
- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud provider 接口，以及 Alibaba DashScope 和 Coding Plan 端点映射
- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问
- [GLM models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点
@ -162,14 +162,16 @@ OpenClaw 自带 pi‑ai 目录。这些提供商**不需要** `models.providers`
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview`
- CLI：`openclaw onboard --auth-choice gemini-api-key`
- Thinking：`/think adaptive` 使用 Google 动态 thinking。Gemini 3/3.1 不包含固定 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。
- 直接 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），以转发 provider 原生 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
- Thinking：`/think adaptive` 使用 Google 动态 thinking。Gemini 3/3.1 不包含固定的 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。
- 直接 Gemini 运行也接受 `agents.defaults.models["google/<model>"].params.cachedContent`
（或旧版 `cached_content`），用于转发 provider 原生的
`cachedContents/...` 句柄；Gemini 缓存命中会以 OpenClaw `cacheRead` 的形式显示
### Google Vertex 和 Gemini CLI
- Providers：`google-vertex`、`google-gemini-cli`
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
- 注意：OpenClaw 中的 Gemini CLI OAuth 属于非官方集成。一些用户报告称，在使用第三方客户端后其 Google 账号受到限制。若你选择继续，请先查看 Google 条款，并使用非关键账号。
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后，Google 账号受到了限制。若你选择继续，请查看 Google 条款并使用非关键账号。
- Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
- 先安装 Gemini CLI：
- `brew install gemini-cli`
@ -177,9 +179,10 @@ OpenClaw 自带 pi‑ai 目录。这些提供商**不需要** `models.providers`
- 启用：`openclaw plugins enable google`
- 登录：`openclaw models auth login --provider google-gemini-cli --set-default`
- 默认模型：`google-gemini-cli/gemini-3-flash-preview`
- 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置文件中。
- 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
- Gemini CLI JSON 回复从 `response` 中解析；用量会回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
- 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关 主机上的认证配置文件中。
- 如果登录后请求失败，请在 Gateway 网关 主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
- Gemini CLI JSON 回复会从 `response` 解析；使用量会回退到
`stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
### Z.AI（GLM）
@ -188,13 +191,14 @@ OpenClaw 自带 pi‑ai 目录。这些提供商**不需要** `models.providers`
- 示例模型：`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
- Provider：`vercel-ai-gateway`
- 认证：`AI_GATEWAY_API_KEY`
- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`、`vercel-ai-gateway/moonshotai/kimi-k2.6`
- 示例模型：`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 网关
@ -204,14 +208,17 @@ OpenClaw 自带 pi‑ai 目录。这些提供商**不需要** `models.providers`
- 示例模型：`kilocode/kilo/auto`
- CLI：`openclaw onboard --auth-choice kilocode-api-key`
- Base 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)。
设置详情请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。
### 其他内置提供商插件
### 其他内置 provider 插件
| 提供商 | Id | 认证环境变量 | 示例模型 |
| Provider | Id | 认证环境变量 | 示例模型 |
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- |
| BytePlus（国际版） | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
@ -239,29 +246,32 @@ OpenClaw 自带 pi‑ai 目录。这些提供商**不需要** `models.providers`
一些值得了解的特殊行为：
- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其应用归因头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用可用于由 OpenRouter 管理的 prompt 缓存 TTL，但不会收到 Anthropic 缓存标记。作为代理风格的 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的整形（`serviceTier`、Responses `store`、prompt-cache 提示、OpenAI reasoning 兼容性）。Gemini 后端引用仅保留代理 Gemini thought-signature 清理。
- **Kilo Gateway 网关** 的 Gemini 后端引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。
- **MiniMax** API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在由插件拥有的 `MiniMax-VL-01` 媒体 provider 上。
- **xAI** 使用 xAI Responses 路径。`/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` 禁用。
- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其应用归因头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 管理的 prompt 缓存 TTL 条件，但不会收到 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅原生 OpenAI 支持的整形（`serviceTier`、Responses `store`、prompt-cache 提示、OpenAI reasoning 兼容性）。以 Gemini 为后端的引用仅保留代理 Gemini thought-signature 清理。
- **Kilo Gateway 网关** 中以 Gemini 为后端的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。
- **MiniMax** API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在插件拥有的 `MiniMax-VL-01` 媒体 provider 上。
- **xAI** 使用 xAI Responses 路径。`/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` 禁用。
- **Cerebras** GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容 Base URL 为 `https://api.cerebras.ai/v1`。
## 通过 `models.providers` 的提供商（自定义/Base URL）
## 通过 `models.providers` 使用 provider（自定义/Base URL）
使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。
使用 `models.providers`（或 `models.json`）添加**自定义** provider 或
OpenAI/Anthropic 兼容代理。
下面许多内置提供商插件已经发布了默认目录。
只有当你想覆盖默认 Base URL、headers 或模型列表时，才需要使用显式的 `models.providers.<id>` 条目。
下面许多内置 provider 插件已经发布了默认目录。
只有当你想覆盖默认 Base URL、请求头或模型列表时，才需要显式使用
`models.providers.<id>` 条目。
### Moonshot AI（Kimi）
Moonshot 作为内置提供商插件提供。默认使用内置 provider，仅当你需要覆盖 Base URL 或模型元数据时，才添加显式 `models.providers.moonshot` 条目：
Moonshot 作为内置 provider 插件提供。默认情况下请使用内置 provider，
只有在你需要覆盖 Base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
- Provider：`moonshot`
- 认证：`MOONSHOT_API_KEY`
- 示例模型：`moonshot/kimi-k2.6`
- CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`
Kimi K2 模型 id：
Kimi K2 模型 ID：
[//]: # "moonshot-kimi-k2-model-refs:start"
@ -309,13 +319,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
}
```
旧版 `kimi/k2p5` 仍然作为兼容模型 id 被接受。
旧版 `kimi/k2p5` 仍然作为兼容模型 ID 被接受。
### Volcano Engine（Doubao）
Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。
- Provider：`volcengine`（编码：`volcengine-plan`）
- Provider：`volcengine`（编程版：`volcengine-plan`）
- 认证：`VOLCANO_ENGINE_API_KEY`
- 示例模型：`volcengine-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
@ -328,9 +338,13 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
}
```
新手引导默认使用编码能力面，但同时也会注册通用 `volcengine/*` 目录。
新手引导默认使用编程接口，但通用 `volcengine/*`
目录也会同时注册。
在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选目录，而不是显示一个空的 provider 作用域选择器。
在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示
`volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，
OpenClaw 会回退到未过滤的目录，而不是显示一个空的
provider 作用域选择器。
可用模型：
@ -340,7 +354,7 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
- `volcengine/glm-4-7-251222`（GLM 4.7）
- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K）
编码模型（`volcengine-plan`）：
编程模型（`volcengine-plan`）：
- `volcengine-plan/ark-code-latest`
- `volcengine-plan/doubao-seed-code`
@ -352,7 +366,7 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。
- Provider：`byteplus`（编码：`byteplus-plan`）
- Provider：`byteplus`（编程版：`byteplus-plan`）
- 认证：`BYTEPLUS_API_KEY`
- 示例模型：`byteplus-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
@ -365,9 +379,13 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力
}
```
新手引导默认使用编码能力面，但同时也会注册通用 `byteplus/*` 目录。
新手引导默认使用编程接口，但通用 `byteplus/*`
目录也会同时注册。
在新手引导/配置模型选择器中，BytePlus（国际版）认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选目录，而不是显示一个空的 provider 作用域选择器。
在新手引导/配置模型选择器中，BytePlus（国际版）认证选项会优先显示
`byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，
OpenClaw 会回退到未过滤的目录，而不是显示一个空的
provider 作用域选择器。
可用模型：
@ -375,7 +393,7 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力
- `byteplus/kimi-k2-5-260127`（Kimi K2.5）
- `byteplus/glm-4-7-251222`（GLM 4.7）
编码模型（`byteplus-plan`）：
编程模型（`byteplus-plan`）：
- `byteplus-plan/ark-code-latest`
- `byteplus-plan/doubao-seed-code`
@ -415,32 +433,35 @@ Synthetic 通过 `synthetic` provider 提供 Anthropic 兼容模型：
MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax OAuth（全球）：`--auth-choice minimax-global-oauth`
- MiniMax OAuth（中国）：`--auth-choice minimax-cn-oauth`
- MiniMax API 密钥（全球）：`--auth-choice minimax-global-api`
- MiniMax API 密钥（中国）：`--auth-choice minimax-cn-api`
- 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
- MiniMax OAuth（Global）：`--auth-choice minimax-global-oauth`
- MiniMax OAuth（CN）：`--auth-choice minimax-cn-oauth`
- MiniMax API 密钥（Global）：`--auth-choice minimax-global-api`
- MiniMax API 密钥（CN）：`--auth-choice minimax-cn-api`
- 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或
`MINIMAX_API_KEY`
设置详情、模型选项和配置片段请参见 [/providers/minimax](/zh-CN/providers/minimax)。
设置详情、模型选项和配置片段请参阅 [/providers/minimax](/zh-CN/providers/minimax)。
在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，否则 OpenClaw 默认禁用 thinking；并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
在 MiniMax 的 Anthropic 兼容流式传输路径上，OpenClaw 默认禁用 thinking，
除非你显式设置它，并且 `/fast on` 会将
`MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
由插件拥有的能力拆分：
插件拥有的能力划分：
- 文本/聊天默认保持为 `minimax/MiniMax-M2.7`
- 文本/聊天默认保留为 `minimax/MiniMax-M2.7`
- 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01`
- 图像理解在两种 MiniMax 认证路径上都使用由插件拥有的 `MiniMax-VL-01`
- Web 搜索保持使用 provider id `minimax`
- 图像理解在两种 MiniMax 认证路径上都使用插件拥有的 `MiniMax-VL-01`
- Web 搜索保留使用 provider id `minimax`
### LM Studio
LM Studio 作为内置提供商插件提供，并使用原生 API：
LM Studio 作为内置 provider 插件提供，并使用原生 API：
- Provider：`lmstudio`
- 认证：`LM_API_TOKEN`
- 默认推理 Base URL：`http://localhost:1234/v1`
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 id）：
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
```json5
{
@ -450,12 +471,13 @@ 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 作为内置 provider 插件提供，并使用 Ollama 的原生 API：
- Provider：`ollama`
- 认证：无需（本地服务器）
@ -463,7 +485,7 @@ Ollama 作为内置提供商插件提供，并使用 Ollama 原生 API：
- 安装：[https://ollama.com/download](https://ollama.com/download)
```bash
# Install Ollama, then pull a model:
# 安装 Ollama，然后拉取一个模型：
ollama pull llama3.3
```
@ -475,23 +497,26 @@ ollama pull llama3.3
}
```
当你通过 `OLLAMA_API_KEY` 显式启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，并且内置 provider 插件会将 Ollama 直接加入 `openclaw onboard` 和模型选择器。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。
当你通过 `OLLAMA_API_KEY` 选择启用时，Ollama 会在本地 `http://127.0.0.1:11434`
被检测到，并且内置 provider 插件会将 Ollama 直接添加到
`openclaw onboard` 和模型选择器中。关于新手引导、云端/本地模式以及自定义配置，请参阅 [/providers/ollama](/zh-CN/providers/ollama)。
### vLLM
vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容服务器：
vLLM 作为内置 provider 插件提供，用于本地/自托管的 OpenAI 兼容
服务器：
- Provider：`vllm`
- 认证：可选（取决于你的服务器）
- 默认 Base URL：`http://127.0.0.1:8000/v1`
若要在本地启用自动发现（如果你的服务器不强制认证，任意值都可）：
要在本地选择启用自动发现（如果你的服务器不强制认证，任意值都可用）：
```bash
export VLLM_API_KEY="vllm-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的某个 id）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -501,23 +526,25 @@ export VLLM_API_KEY="vllm-local"
}
```
详情请参见 [/providers/vllm](/zh-CN/providers/vllm)。
详情请参阅 [/providers/vllm](/zh-CN/providers/vllm)。
### SGLang
SGLang 作为内置提供商插件提供，用于高速自托管的 OpenAI 兼容服务器：
SGLang 作为内置 provider 插件提供，用于快速自托管的
OpenAI 兼容服务器：
- Provider：`sglang`
- 认证：可选（取决于你的服务器）
- 默认 Base URL：`http://127.0.0.1:30000/v1`
若要在本地启用自动发现（如果你的服务器不强制认证，任意值都可）：
要在本地选择启用自动发现（如果你的服务器不强制
认证，任意值都可用）：
```bash
export SGLANG_API_KEY="sglang-local"
```
然后设置一个模型（替换为 `/v1/models` 返回的某个 id）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -527,7 +554,7 @@ export SGLANG_API_KEY="sglang-local"
}
```
详情请参见 [/providers/sglang](/zh-CN/providers/sglang)。
详情请参阅 [/providers/sglang](/zh-CN/providers/sglang)。
### 本地代理（LM Studio、vLLM、LiteLLM 等）
@ -567,18 +594,23 @@ export SGLANG_API_KEY="sglang-local"
说明：
- 对于自定义 provider，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。
若省略，OpenClaw 默认值为：
省略时，OpenClaw 默认值为：
- `reasoning: false`
- `input: ["text"]`
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`
- 建议：设置与你的代理/模型限制相匹配的显式值。
- 对于非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl` 且其主机不是 `api.openai.com`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免 provider 因不支持 `developer` 角色而返回 400 错误。
- 代理风格的 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求整形：不使用 `service_tier`，不使用 Responses `store`，不使用 Completions `store`，不使用 prompt-cache 提示，不使用 OpenAI reasoning 兼容载荷整形，也不添加隐藏的 OpenClaw 归因头。
- 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，可设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求体中。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（会解析为 `api.openai.com`）。
- 为安全起见，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。
- 对于非原生端点上的 `api: "openai-completions"`（任何主机不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免 provider 因不支持 `developer` 角色而返回 400 错误。
- 代理式 OpenAI 兼容路由也会跳过仅原生 OpenAI 支持的请求
整形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有
prompt-cache 提示，没有 OpenAI reasoning 兼容负载整形，也没有隐藏的
OpenClaw 归因头。
- 对于需要厂商特定字段的 OpenAI 兼容 Completions 代理，
请设置 `agents.defaults.models["provider/model"].params.extra_body`（或
`extraBody`），以将额外 JSON 合并到发送请求的正文中。
- 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认 OpenAI 行为（即解析到 `api.openai.com`）。
- 出于安全考虑，即使在非原生 `openai-completions` 端点上显式设置了 `compat.supportsDeveloperRole: true`，也仍会被覆盖。
## CLI 示例
@ -588,11 +620,11 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
另见：[配置](/zh-CN/gateway/configuration)，了解完整配置示例。
另请参阅：[Configuration](/zh-CN/gateway/configuration) 获取完整配置示例。
## 相关内容
- [Models](/zh-CN/concepts/models) — 模型配置和别名
- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链和重试行为
- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键
- [Providers](/zh-CN/providers) — 每个 provider 的设置指南
- [Models](/zh-CN/concepts/models) — 模型配置与别名
- [Model failover](/zh-CN/concepts/model-failover) — 回退链与重试行为
- [Configuration reference](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键
- [Providers](/zh-CN/providers) — 按 provider 分类的设置指南

185
docs/zh-CN/gateway/cli-backends.md
View File

@ -1,31 +1,31 @@
---
read_when:
- 当 API 提供商失败时，你希望有一个可靠的回退方案。
- 你正在运行 Codex CLI 或其他本地 AI CLI，并希望复用它们。
- 你想了解用于 CLI 后端工具访问的 MCP loopback bridge。
summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退方案
- 当 API 提供商失败时，你希望有一个可靠的回退方案
- 你正在运行 Codex CLI 或其他本地 AI CLI，并且想要复用它们
- 你想了解用于 CLI 后端工具访问的 MCP loopback bridge
summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退机制
title: CLI 后端
x-i18n:
generated_at: "2026-04-24T18:08:05Z"
generated_at: "2026-04-25T06:52:28Z"
model: gpt-5.4
provider: openai
source_hash: 81d5f41ebaf16d4171379cf446b4c70b167519cd1f647c0701cccda19f0b3419
source_hash: 09e184bb99a6c354738c3d770460bc2f282a31c41d2cbce4c1e021ae828ba27c
source_path: gateway/cli-backends.md
workflow: 15
---
OpenClaw 可以在 API 提供商不可用、受到速率限制或临时行为异常时，运行**本地 AI CLI** 作为**纯文本回退方案**。这个设计刻意保持保守：
OpenClaw 可以在 API 提供商不可用、被限流或暂时异常时运行**本地 AI CLI** 作为**纯文本回退机制**。这是一种有意保持保守的设计：
- **OpenClaw 工具不会被直接注入**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP bridge 接收 Gateway 网关工具。
- 对支持的 CLI 提供 **JSONL 流式传输**。
- **支持会话**（这样后续轮次可以保持连贯）。
- 如果 CLI 接受图像路径，**图像也可以透传**。
- 对支持它的 CLI 提供 **JSONL 流式传输**。
- **支持会话**（因此后续轮次能保持连贯）。
- 如果 CLI 接受图像路径，**图像可以透传**。
这个功能被设计为一种**安全兜底机制**，而不是主要路径。当你希望获得“不管怎样都能工作”的文本响应，同时又不依赖外部 API 时，可以使用它。
这被设计为一种**安全网**，而不是主要路径。当你想要“不管怎样都能工作”的文本响应，而不依赖外部 API 时，可以使用它。
如果你需要完整的 harness 运行时，包含 ACP 会话控制、后台任务、线程/会话绑定，以及持久化的外部编码会话，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。
如果你想要一个具备 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。
## 面向初学者的快速开始
## 对初学者友好的快速开始
你可以**无需任何配置**使用 Codex CLI（内置的 OpenAI 插件会注册一个默认后端）：
@ -33,7 +33,7 @@ OpenClaw 可以在 API 提供商不可用、受到速率限制或临时行为异
openclaw agent --message "hi" --model codex-cli/gpt-5.5
```
如果你的 Gateway 网关运行在 launchd/systemd 下，且 PATH 很精简，只需添加命令路径：
如果你的 Gateway 网关 运行在 `launchd`/`systemd` 下并且 `PATH` 很精简，只需添加命令路径：
```json5
{
@ -49,13 +49,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
}
```
就这样。不需要密钥，也不需要除 CLI 本身之外的额外认证配置。
就是这样。除了 CLI 本身之外，不需要密钥，也不需要额外的认证配置。
如果你在 Gateway 网关主机上将某个内置 CLI 后端用作**主要消息提供商**，当你的配置在模型引用中或在 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。
如果你在 Gateway 网关 主机上将内置 CLI 后端用作**主消息提供商**，当你的配置在模型引用中或在 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。
## 将它用作回退方案
## 将它用作回退机制
把 CLI 后端添加到你的回退列表中，这样它只会在主模型失败时运行：
将一个 CLI 后端添加到你的回退列表中，这样它只会在主模型失败时运行：
```json5
{
@ -74,10 +74,10 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
}
```
说明：
注意：
- 如果你使用 `agents.defaults.models`（allowlist），你也必须把 CLI 后端模型包含进去。
- 如果主提供商失败（认证、速率限制、超时），OpenClaw 将接着尝试 CLI 后端。
- 如果你使用 `agents.defaults.models`（允许列表），你也必须把你的 CLI 后端模型包含进去。
- 如果主提供商失败（认证、限流、超时），OpenClaw 将接着尝试 CLI 后端。
## 配置概览
@ -87,8 +87,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
agents.defaults.cliBackends
```
每个条目都以一个**提供商 id** 为键（例如 `codex-cli`、`my-cli`）。
这个提供商 id 会成为你的模型引用左侧部分：
每个条目都以一个**provider id** 为键（例如 `codex-cli`、`my-cli`）。
这个 provider id 会成为你的模型引用左侧部分：
```
<provider>/<model>
@ -118,7 +118,7 @@ agents.defaults.cliBackends
sessionMode: "existing",
sessionIdFields: ["session_id", "conversation_id"],
systemPromptArg: "--system",
// 类似 Codex 的 CLI 也可以改为指向提示文件：
// 类似 Codex 的 CLI 也可以改为指向一个提示文件：
// systemPromptFileConfigArg: "-c",
// systemPromptFileConfigKey: "model_instructions_file",
systemPromptWhen: "first",
@ -134,25 +134,29 @@ agents.defaults.cliBackends
## 工作原理
1. 根据提供商前缀（`codex-cli/...`）**选择后端**。
2. 使用相同的 OpenClaw 提示词 + 工作区上下文**构建系统提示词**。
3. 使用会话 id（如果支持）**执行 CLI**，以保持历史一致。
内置的 `claude-cli` 后端会为每个 OpenClaw 会话保持一个 Claude stdio 进程存活，并通过 stream-json stdin 发送后续轮次。
4. **解析输出**（JSON 或纯文本），并返回最终文本。
5. 按后端**持久化会话 id**，以便后续轮次复用相同的 CLI 会话。
1. 根据提供商前缀（`codex-cli/...`）**选择一个后端**。
2. 使用相同的 OpenClaw 提示词和工作区上下文**构建系统提示词**。
3. 如果支持，则使用会话 id **执行 CLI**，以便保持历史一致。
内置的 `claude-cli` 后端会为每个 OpenClaw 会话保持一个 Claude stdio 进程存活，
并通过 stream-json stdin 发送后续轮次。
4. **解析输出**（JSON 或纯文本）并返回最终文本。
5. 按后端**持久化会话 id**，以便后续轮次复用同一个 CLI 会话。
<Note>
内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，再次允许 OpenClaw 风格的 Claude CLI 用法，因此除非 Anthropic 发布新的策略，否则 OpenClaw 会将此集成中的 `claude -p` 用法视为已获认可。
内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，允许使用 OpenClaw 风格的 Claude CLI，因此除非 Anthropic 发布新的策略，否则 OpenClaw 会将 `claude -p` 的用法视为该集成的受认可方式。
</Note>
内置的 OpenAI `codex-cli` 后端会通过 Codex 的 `model_instructions_file` 配置覆盖项（`-c
model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 没有像 Claude 那样的 `--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话将组装好的提示词写入临时文件。
model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 不提供类似 Claude 的
`--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话将组装后的提示词写入临时文件。
内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw Skills 快照：一种是附加系统提示词中的精简版 OpenClaw Skills 目录，另一种是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件仅包含对该智能体/会话符合条件的 Skills，因此 Claude Code 的原生 Skill 解析器看到的过滤结果，与 OpenClaw 原本会在提示词中公布的一致。Skill 的环境变量/API 密钥覆盖仍然由 OpenClaw 应用到本次运行的子进程环境中。
内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw Skills 快照：一种是在追加的系统提示词中包含精简版的 OpenClaw Skills 目录，另一种是通过 `--plugin-dir` 传入一个临时 Claude Code 插件。该插件仅包含对此智能体/会话符合条件的 Skills，因此 Claude Code 的原生技能解析器会看到与 OpenClaw 否则会在提示词中声明的相同过滤结果。对于运行过程，Skill 环境变量/API 密钥覆盖仍然由 OpenClaw 应用于子进程环境。
Claude CLI 也有自己的非交互权限模式。OpenClaw 将其映射到现有的 exec 策略，而不是新增 Claude 专用配置：当生效的请求 exec 策略为 YOLO（`tools.exec.security: "full"` 且 `tools.exec.ask: "off"`）时，OpenClaw 会添加 `--permission-mode bypassPermissions`。每个智能体的 `agents.list[].tools.exec` 设置会覆盖该智能体的全局 `tools.exec`。如果要强制使用不同的 Claude 模式，可在 `agents.defaults.cliBackends.claude-cli.args` 以及对应的 `resumeArgs` 下设置显式原始后端参数，例如 `--permission-mode default` 或 `--permission-mode acceptEdits`。
Claude CLI 也有它自己的非交互权限模式。OpenClaw 会将其映射到现有的 exec 策略，而不是增加 Claude 专用配置：当生效的请求 exec 策略为 YOLO（`tools.exec.security: "full"` 和
`tools.exec.ask: "off"`）时，OpenClaw 会添加 `--permission-mode bypassPermissions`。
对于该智能体，按智能体配置的 `agents.list[].tools.exec` 会覆盖全局 `tools.exec`。如果要强制使用不同的 Claude 模式，请在 `agents.defaults.cliBackends.claude-cli.args` 和匹配的 `resumeArgs` 下设置显式原始后端参数，例如 `--permission-mode default` 或 `--permission-mode acceptEdits`。
在 OpenClaw 能使用内置的 `claude-cli` 后端之前，Claude Code 本身必须已经在同一主机上登录：
在 OpenClaw 可以使用内置的 `claude-cli` 后端之前，Claude Code 本身必须已经在同一台主机上登录：
```bash
claude auth login
@ -160,24 +164,28 @@ claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default
```
仅当 `claude` 二进制文件不在 PATH 中时，才使用 `agents.defaults.cliBackends.claude-cli.command`。
仅当 `claude` 二进制文件不在 `PATH` 中时，才使用 `agents.defaults.cliBackends.claude-cli.command`。
## 会话
- 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或 `sessionArgs`（占位符 `{sessionId}`），用于在多个标志中插入该 id。
- 如果 CLI 使用带有不同标志的**resume 子命令**，请设置 `resumeArgs`（恢复时替换 `args`），必要时还可设置 `resumeOutput`（用于非 JSON 恢复）。
- 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或
`sessionArgs`（占位符 `{sessionId}`），用于需要将该 ID 插入多个标志的情况。
- 如果 CLI 使用**恢复子命令**且标志不同，请设置
`resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput`
（用于非 JSON 恢复）。
- `sessionMode`：
- `always`：始终发送会话 id（如果未存储则生成新的 UUID）。
- `existing`：仅在之前存储过会话 id 时发送。
- `none`：永不发送会话 id。
- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"` 和 `input: "stdin"`，这样后续轮次可以在 Claude 进程仍然活跃时复用该实时进程。现在默认就是 warm stdio，包括省略传输字段的自定义配置在内。如果 Gateway 网关重启，或者空闲进程退出，OpenClaw 会从存储的 Claude 会话 id 恢复。存储的会话 id 会先根据现有可读的项目转录进行校验，再决定是否恢复，因此虚假的绑定会以 `reason=transcript-missing` 被清除，而不是在 `--resume` 下悄悄启动一个新的 Claude CLI 会话。
- 已存储的 CLI 会话属于提供商所有的连续性。隐式的每日会话重置不会切断它们；`/reset` 和显式的 `session.reset` 策略仍然会切断。
- `existing`：仅在之前已存储会话 id 时发送。
- `none`：从不发送会话 id。
- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"`，
以及 `input: "stdin"`，因此只要它处于活动状态，后续轮次就会复用存活的 Claude 进程。现在 warm stdio 已是默认行为，包括省略传输字段的自定义配置也是如此。如果 Gateway 网关 重启或空闲进程退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。恢复前，已存储的会话 id 会针对现有且可读的项目转录记录进行验证，因此虚假的绑定会以 `reason=transcript-missing` 被清除，而不是在 `--resume` 下静默启动一个新的 Claude CLI 会话。
- 已存储的 CLI 会话属于提供商拥有的连续性。隐式的每日会话重置不会切断它们；`/reset` 和显式的 `session.reset` 策略仍会切断。
序列化说明：
- `serialize: true` 会保持同一通道运行按顺序执行。
- 大多数 CLI 会在一个提供商通道上串行化。
- 当所选认证身份发生变化时，OpenClaw 会丢弃已存储 CLI 会话的复用，包括认证配置文件 id 变化、静态 API 密钥变化、静态令牌变化，或在 CLI 暴露了 OAuth 账户身份时该身份发生变化。OAuth 访问令牌和刷新令牌轮换不会切断已存储的 CLI 会话。如果某个 CLI 不暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。
- `serialize: true` 会保持同一通道中的运行按顺序执行。
- 大多数 CLI 会在一个提供商通道上串行执行。
- 当所选认证身份发生变化时，OpenClaw 会丢弃已存储 CLI 会话的复用，包括 auth profile id、静态 API 密钥、静态令牌，或当 CLI 暴露该信息时的 OAuth 账户身份发生变化。OAuth 访问令牌和刷新令牌的轮换不会切断已存储 CLI 会话。如果某个 CLI 不暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。
## 图像（透传）
@ -188,24 +196,26 @@ imageArg: "--image",
imageMode: "repeat"
```
OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传递。如果缺少 `imageArg`，OpenClaw 会将文件路径追加到提示词中（路径注入）；对于那些能从普通路径自动加载本地文件的 CLI，这样就足够了。
OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，这些
路径会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会把文件路径追加到提示词中（路径注入），这对于那些能够从纯路径自动加载本地文件的 CLI 已经足够。
## 输入 / 输出
- `output: "json"`（默认）会尝试解析 JSON，并提取文本 + 会话 id。
- `output: "json"`（默认）会尝试解析 JSON 并提取文本 + 会话 id。
- 对于 Gemini CLI JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。
- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及存在时的会话标识符。
- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及会话
标识符（如果存在）。
- `output: "text"` 会将 stdout 视为最终响应。
输入模式：
- `input: "arg"`（默认）将提示词作为最后一个 CLI 参数传递。
- `input: "stdin"` 通过 stdin 发送提示词。
- 如果提示词非常长且设置了 `maxPromptArgChars`，则会使用 stdin。
- `input: "arg"`（默认）会将提示词作为最后一个 CLI 参数传入。
- `input: "stdin"` 会通过 stdin 发送提示词。
- 如果提示词非常长，并且设置了 `maxPromptArgChars`，则会使用 stdin。
## 默认值（插件所有）
## 默认值（由插件拥有）
内置的 OpenAI 插件也为 `codex-cli` 注册了默认值：
内置的 OpenAI 插件还会为 `codex-cli` 注册一个默认值：
- `command: "codex"`
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
@ -216,7 +226,7 @@ OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，
- `imageArg: "--image"`
- `sessionMode: "existing"`
内置的 Google 插件也为 `google-gemini-cli` 注册了默认值：
内置的 Google 插件还会为 `google-gemini-cli` 注册一个默认值：
- `command: "gemini"`
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
@ -227,7 +237,7 @@ OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，
- `sessionMode: "existing"`
- `sessionIdFields: ["session_id", "sessionId"]`
前提条件：本地 Gemini CLI 必须已安装，并且可通过 PATH 中的
前提条件：本地 Gemini CLI 必须已安装，并且在 `PATH` 中可作为
`gemini` 使用（`brew install gemini-cli` 或
`npm install -g @google/gemini-cli`）。
@ -235,22 +245,23 @@ Gemini CLI JSON 说明：
- 回复文本从 JSON 的 `response` 字段读取。
- 当 `usage` 不存在或为空时，用量会回退到 `stats`。
- `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
- 如果 `stats.input` 缺失，OpenClaw 会从
`stats.input_tokens - stats.cached` 推导输入 token。
- `stats.cached` 会被标准化为 OpenClaw `cacheRead`。
- 如果 `stats.input` 缺失，OpenClaw 会根据
`stats.input_tokens - stats.cached` 推导输入 token 数。
仅在需要时覆盖（常见情况：使用绝对 `command` 路径）。
## 插件所有的默认值
## 由插件拥有的默认值
CLI 后端默认值现在属于插件表面的一部分：
CLI 后端默认值现在是插件表面的一部分：
- 插件使用 `api.registerCliBackend(...)` 注册它们。
- 后端 `id` 会成为模型引用中的提供商前缀。
- 用户在 `agents.defaults.cliBackends.<id>` 中的配置仍会覆盖插件默认值。
- 后端特定的配置清理仍由插件通过可选的 `normalizeConfig` 钩子负责。
- 后端的 `id` 会成为模型引用中的提供商前缀。
- `agents.defaults.cliBackends.<id>` 中的用户配置仍会覆盖插件默认值。
- 后端特定的配置清理由插件通过可选的
`normalizeConfig` 钩子继续拥有。
如果插件需要非常轻量的提示词/消息兼容性适配，而不想替换提供商或 CLI 后端，它们可以声明双向文本变换：
需要极小提示词/消息兼容性垫片的插件，可以声明双向文本转换，而无需替换提供商或 CLI 后端：
```typescript
api.registerTextTransforms({
@ -268,44 +279,52 @@ api.registerTextTransforms({
```
`input` 会重写传递给 CLI 的系统提示词和用户提示词。`output`
会在 OpenClaw 处理自身控制标记和渠道投递之前，重写流式传输的助手增量以及已解析的最终文本。
会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式 assistant 增量内容和已解析的最终文本。
对于会输出与 Claude Code stream-json 兼容的 JSONL 的 CLI，请在该后端配置上设置
对于输出与 Claude Code stream-json 兼容的 JSONL 的 CLI，请在该后端配置上设置
`jsonlDialect: "claude-stream-json"`。
## 内置 MCP 覆盖层
## 捆绑 MCP 覆盖层
CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 选择接收生成的 MCP 配置覆盖层。
CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 来选择加入一个自动生成的 MCP 配置覆盖层。
当前内置行为：
当前的内置行为：
- `claude-cli`：生成严格的 MCP 配置文件
- `codex-cli`：为 `mcp_servers` 生成内联配置覆盖；生成的 OpenClaw loopback server 会标记为 Codex 的按服务器工具批准模式，这样 MCP 调用就不会卡在本地批准提示上
- `google-gemini-cli`：生成 Gemini system settings 文件
- `claude-cli`：生成的严格 MCP 配置文件
- `codex-cli`：针对 `mcp_servers` 的内联配置覆盖；生成的
OpenClaw loopback server 会标记为 Codex 的按服务器工具批准模式，
因此 MCP 调用不会因本地批准提示而卡住
- `google-gemini-cli`：生成的 Gemini 系统设置文件
启用内置 MCP 后，OpenClaw 会：
启用 bundle MCP 后，OpenClaw 会：
- 启动一个 loopback HTTP MCP server，向 CLI 进程暴露 Gateway 网关工具
- 启动一个 loopback HTTP MCP 服务器，将 Gateway 网关工具暴露给 CLI 进程
- 使用按会话生成的令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行认证
- 将工具访问范围限定在当前会话、账户和渠道上下文中
- 为当前工作区加载已启用的内置 MCP 服务器
- 将工具访问范围限定在当前会话、账户和渠道上下文内
- 为当前工作区加载已启用的 bundle-MCP 服务器
- 将它们与任何现有的后端 MCP 配置/设置结构合并
- 使用所属扩展定义的后端集成模式重写启动配置
- 使用所属扩展提供的后端集成模式重写启动配置
如果没有启用任何 MCP 服务器，只要某个后端选择启用内置 MCP，OpenClaw 仍会注入严格配置，以确保后台运行保持隔离。
如果没有启用任何 MCP 服务器，当后端选择加入 bundle MCP 时，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。
按会话范围的内置 MCP 运行时会被缓存，以便在同一会话内复用；在空闲 `mcp.sessionIdleTtlMs` 毫秒后会被回收（默认 10 分钟；设置为 `0` 可禁用）。一次性嵌入式运行（例如认证探测、slug 生成和活动 Memory 召回）会在运行结束时请求清理，因此 stdio 子进程和 Streamable HTTP/SSE 流不会在运行结束后继续存在。
## 限制
- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用直接注入 CLI 后端协议。只有在后端选择启用 `bundleMcp: true` 时，它们才能看到 Gateway 网关工具。
- **流式传输是后端特定的。** 有些后端会流式输出 JSONL；其他后端则会缓冲到退出时再输出。
- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用直接注入
CLI 后端协议。只有在后端选择加入
`bundleMcp: true` 时，后端才能看到 Gateway 网关工具。
- **流式传输是后端特定的。** 有些后端会流式输出 JSONL；另一些则会缓冲
直到退出。
- **结构化输出** 取决于 CLI 的 JSON 格式。
- **Codex CLI 会话** 通过文本输出恢复（不是 JSONL），因此其结构化程度低于初始的 `--json` 运行。不过 OpenClaw 会话本身仍可正常工作。
- **Codex CLI 会话** 通过文本输出恢复（不是 JSONL），其结构化程度低于初始的 `--json` 运行。不过 OpenClaw 会话本身仍会正常工作。
## 故障排除
- **找不到 CLI**：将 `command` 设置为完整路径。
- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。
- **没有会话连续性**：确保已设置 `sessionArg`，并且 `sessionMode` 不是 `none`（Codex CLI 当前无法使用 JSON 输出恢复）。
- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射为 CLI 模型。
- **没有会话连续性**：确保已设置 `sessionArg`，并且 `sessionMode` 不是
`none`（Codex CLI 当前无法使用 JSON 输出恢复）。
- **图像被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。
## 相关内容

182
docs/zh-CN/gateway/config-tools.md
View File

@ -3,18 +3,18 @@ read_when:
- 配置 `tools.*` 策略、允许列表或实验性功能
- 注册自定义提供商或覆盖基础 URL
- 设置与 OpenAI 兼容的自托管端点
summary: 工具配置（策略、实验性开关、提供商支持的工具）和自定义提供商 / 基础 URL 设置
title: 配置——工具和自定义提供商
summary: 工具配置（策略、实验性开关、提供商支持的工具）以及自定义提供商 / 基础 URL 设置
title: 配置 —— 工具和自定义提供商
x-i18n:
generated_at: "2026-04-25T00:40:28Z"
generated_at: "2026-04-25T06:52:28Z"
model: gpt-5.4
provider: openai
source_hash: a3a9ab07a5536196f3ba6c64111eb97206c3b4ff12e497564fe09684193e5c8a
source_hash: d63b080550a6c95d714d3bb42c2b079368040aa09378d88c2e498ccd5ec113c1
source_path: gateway/config-tools.md
workflow: 15
---
`tools.*` 配置键和自定义提供商 / 基础 URL 设置。关于智能体、渠道及其他顶层配置键，请参见
`tools.*` 配置键以及自定义提供商 / 基础 URL 设置。有关智能体、渠道和其他顶层配置键，请参阅
[配置参考](/zh-CN/gateway/configuration-reference)。
## 工具
@ -23,35 +23,35 @@ x-i18n:
`tools.profile` 会在 `tools.allow` / `tools.deny` 之前设置基础允许列表：
当未设置时，本地新手引导默认会将新的本地配置设为 `tools.profile: "coding"`（已有的显式配置档案会被保留）。
本地新手引导会在未设置时，将新的本地配置默认设为 `tools.profile: "coding"`（现有的显式配置档案会被保留）。
| 配置档案 | 包含 |
| 配置档案 | 包含内容 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `minimal` | 仅 `session_status` |
| `minimal` | 仅 `session_status` |
| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` |
| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` |
| `full` | 无限制（与未设置相同） |
| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` |
| `full` | 无限制（与未设置相同） |
### 工具组
### 工具分组
| 组 | 工具 |
| 分组 | 工具 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） |
| `group:fs` | `read`、`write`、`edit`、`apply_patch` |
| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名使用） |
| `group:fs` | `read`、`write`、`edit`、`apply_patch` |
| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` |
| `group:memory` | `memory_search`、`memory_get` |
| `group:web` | `web_search`、`x_search`、`web_fetch` |
| `group:ui` | `browser`、`canvas` |
| `group:automation` | `cron`、`gateway` |
| `group:messaging` | `message` |
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`、`image_generate`、`video_generate`、`tts` |
| `group:openclaw` | 所有内置工具（不包括提供商插件） |
| `group:memory` | `memory_search`、`memory_get` |
| `group:web` | `web_search`、`x_search`、`web_fetch` |
| `group:ui` | `browser`、`canvas` |
| `group:automation` | `cron`、`gateway` |
| `group:messaging` | `message` |
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`、`image_generate`、`video_generate`、`tts` |
| `group:openclaw` | 所有内置工具（不包括提供商插件） |
### `tools.allow` / `tools.deny`
全局工具允许 / 拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭时也会应用。
全局工具允许 / 拒绝策略（`deny` 优先生效）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭，也会应用。
```json5
{
@ -77,7 +77,7 @@ x-i18n:
### `tools.elevated`
控制沙箱外的提升权限 `exec` 访问：
控制沙箱之外的提升权限 `exec` 访问：
```json5
{
@ -93,9 +93,9 @@ x-i18n:
}
```
- 每个智能体的覆盖项（`agents.list[].tools.elevated`）只能进一步收紧限制。
- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅对单条消息生效。
- 提升权限的 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认为 `gateway`，或者当 `exec` 目标为 `node` 时使用 `node`）。
- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。
- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅应用于单条消息。
- 提升权限的 `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，如果 `exec` 目标是 `node`，则使用 `node`）。
### `tools.exec`
@ -142,13 +142,13 @@ x-i18n:
```
- `historySize`：为循环分析保留的最大工具调用历史记录数。
- `warningThreshold`：用于警告的重复无进展模式阈值。
- `warningThreshold`：针对重复且无进展模式发出警告的阈值。
- `criticalThreshold`：用于阻止严重循环的更高重复阈值。
- `globalCircuitBreakerThreshold`：针对任何无进展运行的硬停止阈值。
- `detectors.genericRepeat`：对重复的同工具 / 同参数调用发出警告。
- `globalCircuitBreakerThreshold`：对任何无进展运行进行硬停止的阈值。
- `detectors.genericRepeat`：对重复调用相同工具 / 相同参数发出警告。
- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告 / 阻止。
- `detectors.pingPong`：对交替出现的无进展成对模式发出警告 / 阻止。
- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。
- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，校验将失败。
### `tools.web`
@ -182,7 +182,7 @@ x-i18n:
### `tools.media`
配置传入媒体理解能力（图像 / 音频 / 视频）：
配置传入媒体理解（图像 / 音频 / 视频）：
```json5
{
@ -190,7 +190,7 @@ x-i18n:
media: {
concurrency: 2,
asyncCompletion: {
directSend: false, // 选择启用：将已完成的异步音乐 / 视频直接发送到渠道
directSend: false, // 选择启用：将完成的异步音乐 / 视频直接发送到渠道
},
audio: {
enabled: true,
@ -231,14 +231,14 @@ x-i18n:
- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai` / `anthropic` / `minimax` → 图像，`google` → 图像 + 音频 + 视频，`groq` → 音频。
- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每个条目的覆盖设置。
- 失败时会回退到下一个条目。
- 如果失败，会回退到下一个条目。
提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。
**异步完成字段：**
- `asyncCompletion.directSend`：当为 `true` 时，已完成的异步 `music_generate`
和 `video_generate` 任务会优先尝试直接发送到渠道。默认值：`false`
- `asyncCompletion.directSend`：当设为 `true` 时，已完成的异步 `music_generate`
和 `video_generate` 任务会先尝试直接投递到渠道。默认值：`false`
（旧版请求者会话唤醒 / 模型投递路径）。
</Accordion>
@ -258,7 +258,7 @@ x-i18n:
### `tools.sessions`
控制哪些会话可以被会话工具（`sessions_list`、`sessions_history`、`sessions_send`）作为目标。
控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以定位哪些会话。
默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。
@ -273,12 +273,12 @@ x-i18n:
}
```
注意：
说明：
- `self`：仅当前会话键。
- `tree`：当前会话 + 由当前会话生成的会话（子智能体）。
- `agent`：属于当前智能体 id 的任意会话（如果你在同一个智能体 id 下按发送者运行会话，也可能包含其他用户）。
- `all`：任意会话。跨智能体定向仍然需要 `tools.agentToAgent`。
- `agent`：属于当前智能体 id 的任何会话（如果你在同一个智能体 id 下按发送者运行会话，可能包括其他用户）。
- `all`：任何会话。跨智能体定位仍然需要 `tools.agentToAgent`。
- 沙箱限制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。
### `tools.sessions_spawn`
@ -301,20 +301,20 @@ x-i18n:
}
```
注意：
说明：
- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。
- 文件会被实体化到子工作区中的 `.openclaw/attachments/<uuid>/`，并附带一个 `.manifest.json`。
- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。
- 文件会被实体化到子工作区的 `.openclaw/attachments/<uuid>/` 中，并带有一个 `.manifest.json`。
- 附件内容会自动从转录持久化中脱敏。
- Base64 输入会通过严格的字母表 / 填充检查以及解码前大小保护进行验证。
- 目录和文件权限分别为 `0700` 和 `0600`。
- 清理由 `cleanup` 策略控制：`delete` 总是会删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。
- Base64 输入会使用严格的字母表 / 填充校验，以及解码前大小保护进行验证。
- 目录文件权限为 `0700`，文件权限为 `0600`。
- 清理遵循 `cleanup` 策略：`delete` 总是删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留它们。
<a id="toolsexperimental"></a>
### `tools.experimental`
实验性内置工具标志。默认关闭，除非严格智能体式 GPT-5 自动启用规则适用。
实验性的内置工具标志。默认关闭，除非适用 strict-agentic GPT-5 自动启用规则。
```json5
{
@ -326,11 +326,11 @@ x-i18n:
}
```
注意：
说明：
- `planTool`：为非简单的多步骤工作跟踪启用结构化 `update_plan` 工具。
- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或某个智能体的覆盖设置）被设为 `"strict-agentic"`，且运行的是 OpenAI 或 OpenAI Codex 的 GPT-5 系列。将其设为 `true` 可在该范围之外强制开启该工具，设为 `false` 则即使在严格智能体式 GPT-5 运行中也保持关闭。
- 启用后，系统提示词还会添加使用指导，以便模型仅在重要工作中使用它，并且最多只保留一个 `in_progress` 步骤。
- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或每个智能体的覆盖值）被设置为 `"strict-agentic"`，并且运行的是 OpenAI 或 OpenAI Codex GPT-5 系列。设为 `true` 可在该范围之外强制启用此工具；设为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。
- 启用后，系统提示词还会添加使用指引，以便模型仅在重要工作中使用它，并且最多只保留一个 `in_progress` 步骤。
### `agents.defaults.subagents`
@ -350,8 +350,8 @@ x-i18n:
}
```
- `model`：生成的子智能体的默认模型。如果省略，子智能体会继承调用方的模型。
- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 的目标智能体 id 默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。
- `model`：生成的子智能体默认使用的模型。如果省略，子智能体会继承调用方的模型。
- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 id 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。
- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时时间（秒）。`0` 表示无超时。
- 每个子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。
@ -388,47 +388,47 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
}
```
- 使用 `authHeader: true` + `headers` 来满足自定义认证需求。
- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用 `PI_CODING_AGENT_DIR`，这是旧版环境变量别名）。
- 对于匹配的提供商 ID，合并优先级如下：
- 如需自定义认证，请使用 `authHeader: true` + `headers`。
- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。
- 匹配提供商 ID 的合并优先级：
- 非空的智能体 `models.json` `baseUrl` 值优先。
- 非空的智能体 `apiKey` 值仅在该提供商在当前配置 / 认证档案上下文中不是由 SecretRef 管理时优先。
- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件 / exec 引用使用 `secretref-managed`），而不是持久化已解析的 Secret。
- 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件 / exec 引用使用 `secretref-managed`）。
- 非空的智能体 `apiKey` 值仅在当前配置 / auth-profile 上下文中该提供商不是由 SecretRef 管理时优先。
- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用为 `ENV_VAR_NAME`，文件 / exec 引用为 `secretref-managed`），而不是持久化已解析的密钥。
- 由 SecretRef 管理的提供商头部值会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，文件 / exec 引用为 `secretref-managed`）。
- 空的或缺失的智能体 `apiKey` / `baseUrl` 会回退到配置中的 `models.providers`。
- 匹配模型的 `contextWindow` / `maxTokens` 会在显式配置值和隐式目录值之间取较高值。
- 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；当你想限制有效上下文而不改变模型原生元数据时可使用它。
- 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。
- 标记持久化以源为准：标记从活动源配置快照（解析前）写入，而不是从已解析的运行时 Secret 值写入。
- 匹配模型的 `contextWindow` / `maxTokens` 会在显式配置值与隐式目录值之间采用较高的值。
- 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；当你希望限制生效上下文而不修改模型原生元数据时，请使用它。
- 当你希望配置完全重写 `models.json` 时，请使用 `models.mode: "replace"`。
- 标记持久化以源为准：标记写入自当前活动的源配置快照（解析前），而不是来自解析后的运行时密钥值。
### 提供商字段详情
- `models.mode`：提供商目录行为（`merge` 或 `replace`）。
- `models.providers`：以提供商 id 为键的自定义提供商映射。
- 安全编辑：对增量更新，使用 `openclaw config set models.providers.<id> '<json>' --strict-json --merge` 或 `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge`。除非你传入 `--replace`，否则 `config set` 会拒绝破坏性替换。
- 安全编辑：使用 `openclaw config set models.providers.<id> '<json>' --strict-json --merge` 或 `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` 进行增量更新。`config set` 会拒绝破坏性替换，除非你传入 `--replace`。
- `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。
- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef / 环境变量替换）。
- `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。
- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求中（默认：`true`）。
- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。
- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，向请求中注入 `options.num_ctx`（默认：`true`）。
- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` 头传输凭证。
- `models.providers.*.baseUrl`：上游 API 基础 URL。
- `models.providers.*.headers`：用于代理 / 租户路由的额外静态 header。
- `models.providers.*.headers`：用于代理 / 租户路由的额外静态头部。
- `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖设置。
- `request.headers`：额外 header（与提供商默认值合并）。值支持 SecretRef。
- `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，可选 `prefix`）。
- `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都支持可选的 `tls` 子对象。
- `request.tls`：直接连接的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均支持 SecretRef）、`serverName`、`insecureSkipVerify`。
- `request.allowPrivateNetwork`：当为 `true` 时，如果 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似地址范围，则通过提供商 HTTP 抓取保护允许 HTTPS 访问（这是面向可信自托管 OpenAI 兼容端点的运维人员选择启用项）。WebSocket 使用相同的 `request` 处理 header / TLS，但不使用该抓取 SSRF 防护门。默认 `false`。
- `request.headers`：额外头部（与提供商默认值合并）。值支持 SecretRef。
- `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value` 和可选的 `prefix`）。
- `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。
- `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都支持 SecretRef）、`serverName`、`insecureSkipVerify`。
- `request.allowPrivateNetwork`：当设为 `true` 时，如果 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似网段，则允许通过提供商 HTTP 抓取防护访问 HTTPS `baseUrl`（这是针对受信任、自托管、与 OpenAI 兼容端点的运维人员选择启用项）。WebSocket 也使用相同的 `request` 处理头部 / TLS，但不使用该抓取 SSRF 防护门。默认值为 `false`。
- `models.providers.*.models`：显式提供商模型目录条目。
- `models.providers.*.models.*.contextWindow`：模型原生上下文窗口元数据。
- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它。
- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且存在非空、非原生 `baseUrl`（主机不是 `api.openai.com`）的情况，OpenClaw 会在运行时强制将其设为 `false`。空的 / 省略的 `baseUrl` 会保留默认 OpenAI 行为。
- `models.providers.*.models.*.compat.requiresStringContent`：面向仅支持字符串的 OpenAI 兼容聊天端点的可选兼容性提示。当为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组展平为普通字符串。
- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根节点。
- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用；当两者不同，`openclaw models list` 会同时显示这两个值。
- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且 `baseUrl` 为非空、非原生值（主机不是 `api.openai.com`）的情况，OpenClaw 会在运行时将其强制设为 `false`。空的 / 省略的 `baseUrl` 会保留默认的 OpenAI 行为。
- `models.providers.*.models.*.compat.requiresStringContent`：针对仅支持字符串的 OpenAI 兼容聊天端点的可选兼容性提示。当设为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组展平为纯字符串。
- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。
- `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启 / 关闭隐式发现。
- `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选提供商 id 过滤器。
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新的轮询间隔。
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选 provider-id 过滤器。
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新轮询间隔。
- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。
@ -468,7 +468,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
}
```
对于 Cerebras，使用 `cerebras/zai-glm-4.7`；对于直连 Z.AI，使用 `zai/glm-4.7`。
Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7`。
</Accordion>
@ -485,7 +485,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
}
```
设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录使用 `opencode/...` 引用，Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。
设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录请使用 `opencode/...` 引用，Go 目录请使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。
</Accordion>
@ -506,7 +506,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
- 通用端点：`https://api.z.ai/api/paas/v4`
- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4`
- 对于通用端点，定义一个自定义提供商并覆盖基础 URL。
- 对于通用端点，请定义一个覆盖基础 URL 的自定义提供商。
</Accordion>
@ -548,8 +548,8 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
对于中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。
原生 Moonshot 端点会在共享的
`openai-completions` 传输上宣告流式用量兼容性，而 OpenClaw 会依据端点能力
而不只是内置提供商 id 来处理这一点。
`openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 会依据端点能力
而不只是内置提供商 id 本身来处理这一点。
</Accordion>
@ -571,7 +571,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
</Accordion>
<Accordion title="Synthetic（Anthropic 兼容）">
<Accordion title="Synthetic（与 Anthropic 兼容）">
```json5
{
@ -606,7 +606,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
}
```
基础 URL 不应包含 `/v1`（Anthropic 客户端会自行追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。
基础 URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。
</Accordion>
@ -650,8 +650,8 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
`openclaw onboard --auth-choice minimax-global-api` 或
`openclaw onboard --auth-choice minimax-cn-api`。
模型目录默认仅包含 M2.7。
在 Anthropic 兼容的流式传输路径上，OpenClaw 默认会禁用 MiniMax thinking，
除非你明确自行设置 `thinking`。`/fast on` 或
在与 Anthropic 兼容的流式路径上，OpenClaw 默认会禁用 MiniMax thinking，
除非你自行显式设置 `thinking`。`/fast on` 或
`params.fastMode: true` 会将 `MiniMax-M2.7` 重写为
`MiniMax-M2.7-highspeed`。
@ -659,7 +659,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
<Accordion title="本地模型（LM Studio）">
参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在较强硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。
参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在性能足够强的硬件上，通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。
</Accordion>
@ -667,7 +667,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或
## 相关内容
- [配置参考](/zh-CN/gateway/configuration-reference) — 其他顶层键
- [配置——智能体](/zh-CN/gateway/config-agents)
- [配置——渠道](/zh-CN/gateway/config-channels)
- [配置参考](/zh-CN/gateway/configuration-reference) —— 其他顶层键
- [配置 —— 智能体](/zh-CN/gateway/config-agents)
- [配置 —— 渠道](/zh-CN/gateway/config-channels)
- [工具和插件](/zh-CN/tools)

593
docs/zh-CN/gateway/configuration-reference.md
View File

@ -1,63 +1,100 @@
---
read_when:
- 你需要精确到字段级别的配置语义或默认值
- 你正在验证 channel、model、Gateway 网关或工具配置块
summary: 用于核心 OpenClaw 键、默认值以及指向各专用子系统参考文档链接的 Gateway 网关配置参考
- 你正在验证渠道、模型、Gateway 网关 或工具配置块
summary: Gateway 网关 配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考的链接
title: 配置参考
x-i18n:
generated_at: "2026-04-25T05:54:11Z"
generated_at: "2026-04-25T06:52:24Z"
model: gpt-5.4
provider: openai
source_hash: 6fc32c7387a8ece01020342186b52202d954a44c6db3fa827a5ed4302e995af7
source_hash: f658493b3354d2f5dca8adf8a32d3d1c07691a35923badb2cbd697d69e0f50f9
source_path: gateway/configuration-reference.md
workflow: 15
---
`~/.openclaw/openclaw.json` 的核心配置参考。若要查看面向任务的概览，请参阅[配置](/zh-CN/gateway/configuration)。
`~/.openclaw/openclaw.json` 的核心配置参考。若要查看面向任务的概览，请参见 [配置](/zh-CN/gateway/configuration)。
本文涵盖 OpenClaw 的主要配置面，并在子系统有更深入的专用参考时提供链接。由渠道和插件拥有的命令目录，以及深度 memory / QMD 调节项，都位于各自页面中，而不在本页展开。
涵盖 OpenClaw 的主要配置面，并在某个子系统有更深入的独立参考时提供链接。由渠道和插件拥有的命令目录，以及更深入的内存 / QMD 调节项，位于各自的页面中，而不是本页。
代码事实来源：
- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据
- `config.schema.lookup` 会返回一个按路径范围定位的 schema 节点，供钻取式工具使用
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 面验证配置文档基线哈希
- `config.schema.lookup` 会返回一个按路径范围限定的 schema 节点，用于下钻工具
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希
专用深度参考：
专用深入参考：
- [Memory 配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
- [Slash commands](/zh-CN/tools/slash-commands)，适用于当前内置 + 捆绑命令目录
- 各自所属的渠道 / 插件页面，适用于渠道特定的命令面
- [内存配置参考](/zh-CN/reference/memory-config)，用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
- [斜杠命令](/zh-CN/tools/slash-commands)，用于当前内置 + 打包的命令目录
- 渠道特定命令面的所属渠道 / 插件页面
配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——OpenClaw 在省略时会使用安全默认值。
配置格式为 **JSON5**（允许注释 + 尾随逗号）。所有字段都是可选的 —— OpenClaw 在省略时会使用安全的默认值。
---
## 渠道
每个渠道的配置键已移至专用页面——请参阅
每个渠道的配置键已移至专用页面 —— 请参见
[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`，
其中包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 及其他
内置渠道（认证、访问控制、多账号、提及门控）。
包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他
内置渠道（身份验证、访问控制、多账户、提及门控）。
## 智能体默认值、多智能体、会话和消息
已移至专用页面——请参阅
[配置 — 智能体](/zh-CN/gateway/config-agents)，了解：
已移至专用页面 —— 请参见
[配置 — 智能体](/zh-CN/gateway/config-agents)，内容包括：
- `agents.defaults.*`（工作区、模型、thinking、heartbeat、memory、媒体、Skills、沙箱）
- `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱）
- `multiAgent.*`（多智能体路由和绑定）
- `session.*`（会话生命周期、压缩、清理）
- `messages.*`（消息交付、TTS、Markdown 渲染）
- `messages.*`（消息投递、TTS、Markdown 渲染）
- `talk.*`（Talk 模式）
- `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保留平台默认的停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）
- `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保持平台默认的停顿窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）
## 工具和自定义提供商
工具策略、实验性开关、由 provider 支持的工具配置，以及自定义
provider / base-URL 设置已移至专用页面——请参阅
工具策略、实验性开关、由提供商支持的工具配置，以及自定义
提供商 / base-URL 设置已移至专用页面 —— 请参见
[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。
## MCP
由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，
并由嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、
`show`、`set` 和 `unset` 命令会管理这个配置块，而不会在编辑配置期间连接到
目标服务器。
```json5
{
mcp: {
// Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
sessionIdleTtlMs: 600000,
servers: {
docs: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-fetch"],
},
remote: {
url: "https://example.com/mcp",
transport: "streamable-http", // streamable-http | sse
headers: {
Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
},
},
},
},
}
```
- `mcp.servers`：为暴露已配置 MCP 工具的运行时提供具名的 stdio 或远程 MCP 服务器定义。
- `mcp.sessionIdleTtlMs`：会话范围内内置 MCP 运行时的空闲 TTL。
一次性嵌入式运行会请求在运行结束时清理；这个 TTL 是
长生命周期会话和未来调用方的兜底机制。
运行时行为请参见 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和
[CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。
## Skills
```json5
@ -83,11 +120,12 @@ provider / base-URL 设置已移至专用页面——请参阅
}
```
- `allowBundled`：仅对内置 Skills 生效的可选允许列表（托管 / 工作区 Skills 不受影响）。
- `allowBundled`：仅针对内置 Skills 的可选允许列表（托管 / 工作区 Skills 不受影响）。
- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。
- `install.preferBrew`：为 `true` 时，若 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。
- `install.nodeManager`：`metadata.openclaw.install` 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使某个 Skill 已内置 / 已安装，也会禁用它。
- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。
- `install.nodeManager`：用于 `metadata.openclaw.install`
规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使 Skill 已内置 / 已安装，也会禁用该 Skill。
- `entries.<skillKey>.apiKey`：为声明了主环境变量的 Skills 提供的便捷字段（明文字符串或 SecretRef 对象）。
---
@ -117,44 +155,44 @@ provider / base-URL 设置已移至专用页面——请参阅
```
- 从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 以及 `plugins.load.paths` 加载。
- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。
- **配置变更需要重启 gateway。**
- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。
- `plugins.entries.<id>.apiKey`：插件级 API key 便捷字段（当插件支持时）。
- `plugins.entries.<id>.env`：插件作用域环境变量映射。
- `plugins.entries.<id>.hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的 bundle 提供钩子目录。
- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex 包和 Claude 包，包括无 manifest 的 Claude 默认布局包。
- **配置更改需要重启 Gateway 网关。**
- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。
- `plugins.entries.<id>.apiKey`：插件级 API 密钥便捷字段（插件支持时可用）。
- `plugins.entries.<id>.env`：插件范围的环境变量映射。
- `plugins.entries.<id>.hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的包提供钩子目录。
- `plugins.entries.<id>.hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可以从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始对话内容。
- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任该插件，使其可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。
- `plugins.entries.<id>.subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你明确要允许任意模型时才使用 `"*"`。
- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任此插件可以为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。
- `plugins.entries.<id>.subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你确实想允许任意模型时才使用 `"*"`。
- `plugins.entries.<id>.config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。
- 渠道插件的账号 / 运行时设置位于 `channels.<id>` 下，应由所属插件的 manifest `channelConfigs` 元数据描述，而不是由中心化的 OpenClaw 选项注册表描述。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl Web 抓取 provider 设置。
- `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。
- 渠道插件的账户 / 运行时设置位于 `channels.<id>` 下，应由所属插件的 manifest `channelConfigs` 元数据描述，而不是由中央 OpenClaw 选项注册表描述。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取提供商设置。
- `apiKey`：Firecrawl API 密钥（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。
- `baseUrl`：Firecrawl API 基础 URL（默认：`https://api.firecrawl.dev`）。
- `onlyMainContent`：仅提取页面主体内容（默认：`true`）。
- `maxAgeMs`：最大缓存时长（毫秒，默认：`172800000` / 2 天）。
- `timeoutSeconds`：抓取请求超时秒数（默认：`60`）。
- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok Web 搜索）设置。
- `enabled`：启用 X Search provider。
- `maxAgeMs`：缓存的最大存活时间（毫秒）（默认：`172800000` / 2 天）。
- `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。
- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web search）设置。
- `enabled`：启用 X Search 提供商。
- `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。
- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。有关阶段和阈值，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `enabled`：dreaming 总开关（默认 `false`）。
- `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。
- 阶段策略和阈值属于实现细节（不是面向用户的配置键）。
- 完整的 memory 配置位于 [Memory 配置参考](/zh-CN/reference/memory-config)：
- 完整内存配置位于 [内存配置参考](/zh-CN/reference/memory-config)：
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
- 已启用的 Claude bundle 插件还可以从 `settings.json` 提供内嵌 Pi 默认值；OpenClaw 会将其作为已净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。
- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 禁用 memory 插件。
- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。
- 已启用的 Claude 包插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将它们作为经过净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。
- `plugins.slots.memory`：选择活动内存插件 id，或用 `"none"` 禁用内存插件。
- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认为 `"legacy"`，除非你安装并选择了其他引擎。
- `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。
- 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。
- 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。
- 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。
- 将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令，而不是手动编辑。
请参阅[插件](/zh-CN/tools/plugin)。
请参见 [插件](/zh-CN/tools/plugin)。
---
@ -205,25 +243,25 @@ provider / base-URL 设置已移至专用页面——请参阅
```
- `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。
- `tabCleanup` 会在空闲时间后，或当某个会话超出其标签页上限时，回收已跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 0 可分别禁用这些单独的清理模式。
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此浏览器导航默认保持严格。
- 仅当你明确受信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性 / 发现检查期间也受相同的私有网络阻止策略约束。
- `ssrfPolicy.allowPrivateNetwork` 仍支持作为旧版别名。
- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。
- 远程配置文件为仅附加模式（不支持 start / stop / reset）。
- `tabCleanup` 会在空闲时间后，或当某个会话超过其上限时，回收被跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为 0 可禁用各自对应的清理模式。
- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此浏览器导航默认保持严格模式。
- 仅当你明确愿意信任私有网络浏览器导航时，才将 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` 设为 true。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性 / 设备发现检查期间也会受到相同的私有网络阻止策略约束。
- `ssrfPolicy.allowPrivateNetwork` 仍然作为旧版别名受支持。
- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。
- 远程配置文件仅支持附加模式（禁用 start / stop / reset）。
- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。
当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；
当你的提供商提供直接的 DevTools WebSocket URL 时，请使用 WS(S)。
- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以在所选主机上或通过已连接的浏览器节点进行附加。
当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；当你的提供商直接提供 DevTools WebSocket URL 时，请使用 WS(S)。
- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到所选主机上，或通过已连接的浏览器节点附加。
- `existing-session` 配置文件可以设置 `userDataDir`，以定位特定的基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。
- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：使用 snapshot / ref 驱动的操作，而不是 CSS 选择器定位；单文件上传钩子；不支持对话框超时覆盖；不支持 `wait --load networkidle`；也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。
- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下才显式设置 `cdpUrl`。
- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 `browser.executablePath`。可用它让一个配置文件运行在 Chrome 中，而另一个运行在 Brave 中。
- `existing-session` 配置文件保留当前的 Chrome MCP 路由限制：使用基于 snapshot / ref 的操作，而不是 CSS 选择器定位；单文件上传钩子；不支持对话框超时覆盖；不支持 `wait --load networkidle`；也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。
- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下才需要显式设置 `cdpUrl`。
- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 `browser.executablePath`。可用它让一个配置文件运行在 Chrome 中，另一个运行在 Brave 中。
- 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
- `browser.executablePath` 接受 `~` 作为你的操作系统主目录。
- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。
- `extraArgs` 会向本地 Chromium 启动追加额外的启动标志（例如 `--disable-gpu`、窗口大小设置或调试标志）。
- `browser.executablePath` 接受表示你的操作系统主目录的 `~`。
- 控制服务：仅限 loopback（端口从 `gateway.port` 派生，默认 `18791`）。
- `extraArgs` 会为本地 Chromium 启动追加额外的启动标志（例如
`--disable-gpu`、窗口尺寸设置或调试标志）。
---
@ -241,8 +279,8 @@ provider / base-URL 设置已移至专用页面——请参阅
}
```
- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡色调等）。
- `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。
- `seamColor`：原生应用 UI 外壳的强调色（Talk 模式气泡色调等）。
- `assistant`：Control UI 身份覆盖。会回退到当前活动智能体身份。
---
@ -289,20 +327,20 @@ provider / base-URL 设置已移至专用页面——请参阅
// password: "your-password",
},
trustedProxies: ["10.0.0.1"],
// 可选。默认 false。
// Optional. Default false.
allowRealIpFallback: false,
nodes: {
pairing: {
// 可选。默认未设置 / 禁用。
// Optional. Default unset/disabled.
autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
},
allowCommands: ["canvas.navigate"],
denyCommands: ["system.run"],
},
tools: {
// 额外的 /tools/invoke HTTP deny
// Additional /tools/invoke HTTP denies
deny: ["browser"],
// 从默认 HTTP deny 列表中移除工具
// Remove tools from the default HTTP deny list
allow: ["gateway"],
},
push: {
@ -317,53 +355,59 @@ provider / base-URL 设置已移至专用页面——请参阅
}
```
<Accordion title="Gateway 网关字段详情">
<Accordion title="Gateway 网关 字段详情">
- `mode`：`local`（运行 gateway）或 `remote`（连接到远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。
- `port`：WS + HTTP 复用的单一端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关 会拒绝启动。
- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
- `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。
- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 gateway 无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。
- **Auth**：默认必需。非 loopback bind 需要 gateway auth。实际意味着共享 token / password，或使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成 token。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。若两者都已配置但未设置 mode，启动以及服务安装 / 修复流程都会失败。
- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示不会提供此选项。
- `gateway.auth.mode: "trusted-proxy"`：将 auth 委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求使用**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy auth 要求。
- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可满足 Control UI / WebSocket auth（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头 auth；它们仍遵循 gateway 的常规 HTTP auth 模式。此无 token 流程假定 gateway 主机是受信任的。当 `tailscale.mode = "serve"` 时默认值为 `true`。
- `gateway.auth.rateLimit`：可选的认证失败限制器。按客户端 IP 和 auth 范围生效（共享密钥和 device-token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
- 在异步 Tailscale Serve Control UI 路径中，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限制器，而不是两个请求都竞态通过并仅表现为普通不匹配。
- `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；当你有意也要对 localhost 流量进行速率限制时（例如测试设置或严格代理部署），请设为 `false`。
- 来自浏览器源的 WS auth 尝试始终会启用限流，且关闭 loopback 豁免（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。
- 在 loopback 上，这些来自浏览器源的锁定会按标准化后的 `Origin` 值隔离，因此来自某个 localhost origin 的重复失败不会自动锁定另一个 origin。
- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开，需要 auth）。
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当预期浏览器客户端来自非 loopback origin 时必须设置。
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 标头 origin 策略的部署启用 Host 标头 origin 回退。
- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
- **Docker 注意事项**：默认的 `loopback` bind 会在容器内部监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关 无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以在所有接口上监听。
- **Auth**：默认必须启用。非 loopback 绑定要求 Gateway 网关 身份验证。实际使用中，这意味着共享 token / password，或使用 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。当两者都已配置且未设置 mode 时，启动以及服务安装 / 修复流程都会失败。
- `gateway.auth.mode: "none"`：显式无认证模式。仅用于可信的本地 local loopback 设置；新手引导提示中不会提供此选项，这是有意为之。
- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同一主机上的 loopback 反向代理不满足 trusted-proxy auth 要求。
- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可满足 Control UI / WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头认证；它们仍遵循 Gateway 网关 的常规 HTTP 认证模式。当 `tailscale.mode = "serve"` 时默认值为 `true`。这种无 token 流程假定 Gateway 网关 所在主机可信。
- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥和设备 token 会分别跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
- 在异步 Tailscale Serve Control UI 路径上，相同 `{scope, clientIp}` 的失败尝试会在失败写入前被串行化。因此，同一客户端的并发错误尝试可能会在第二个请求上触发限流，而不是两个请求都作为普通不匹配竞态通过。
- `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你确实希望 localhost 流量也受限流影响（用于测试设置或严格代理部署），请设为 `false`。
- 来自浏览器源的 WS 认证尝试始终会启用限流，且不会豁免 loopback（作为防御纵深措施，以防浏览器对 localhost 进行暴力破解）。
- 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin`
值隔离，因此来自某个 localhost 源的重复失败不会自动
锁定另一个源。
- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开访问，需要认证）。
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时，这是必需的。
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为那些有意依赖 Host 标头来源策略的部署启用基于 Host 标头的来源回退。
- `remote.transport`：`ssh`（默认）或 `direct`（ws / wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量级别的紧急放行覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍然只允许对 loopback 使用明文。没有对应的 `openclaw.json` 配置项，且诸如 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 之类的浏览器私有网络配置不会影响 Gateway 网关 WebSocket 客户端。
- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 gateway auth。
- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方 / TestFlight iOS 构建在向 gateway 发布基于 relay 的注册之后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 匹配。
- `gateway.push.apns.relay.timeoutMs`：gateway 到 relay 的发送超时（毫秒）。默认值为 `10000`。
- 基于 relay 的注册会委托给特定的 gateway 身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将按注册范围限定的发送授权转发给 gateway。其他 gateway 无法复用该已存储的注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发环境的放行开关，允许使用 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。
- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认：`5`。
- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认：`30`。
- `gateway.channelMaxRestartsPerHour`：每个渠道 / 账号在滚动一小时内允许的最大健康监控重启次数。默认：`10`。
- `channels.<provider>.healthMonitor.enabled`：按渠道禁用健康监控重启，同时保留全局监控启用。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号渠道的按账号覆盖。设置后，其优先级高于渠道级覆盖。
- 仅当 `gateway.auth.*` 未设置时，本地 gateway 调用路径才可将 `gateway.remote.*` 作为回退。
- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未解析，则解析会以关闭失败方式处理（不会以远程回退掩盖问题）。
- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对同主机代理 / 本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的资格。
- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时 gateway 接受 `X-Real-IP`。默认为 `false`，以实现失败即关闭的行为。
- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR / IP 允许列表，用于在未请求作用域时自动批准首次节点设备配对。未设置时为禁用状态。它不会自动批准 operator / 浏览器 / Control UI / WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局允许 / 拒绝整形。
- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认 deny 列表）。
- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名称。
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量中的紧急放行覆盖，允许对可信私有网络
IP 使用明文 `ws://`；默认情况下，明文仍然仅限 loopback。没有对应的 `openclaw.json`
配置项，且诸如
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 之类的浏览器私有网络配置不会影响 Gateway 网关
WebSocket 客户端。
- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关 认证。
- `gateway.push.apns.relay.baseUrl`：官方 / TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关 后，供其使用的外部 APNs relay 的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。
- `gateway.push.apns.relay.timeoutMs`：Gateway 网关 到 relay 的发送超时时间（毫秒）。默认值为 `10000`。
- 基于 relay 的注册会委托给某个特定的 Gateway 网关 身份。配对的 iOS 应用会获取 `gateway.identity.get`，将该身份包含在 relay 注册中，并将一个按注册范围划分的发送授权转发给 Gateway 网关。其他 Gateway 网关 无法复用这个已存储的注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发的例外开关，可为 loopback HTTP relay URL 放行。生产环境的 relay URL 应保持为 HTTPS。
- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。
- `gateway.channelStaleEventThresholdMinutes`：陈旧套接字阈值（分钟）。应保持大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
- `gateway.channelMaxRestartsPerHour`：每个渠道 / 账户在滚动一小时内允许的最大健康监控重启次数。默认值：`10`。
- `channels.<provider>.healthMonitor.enabled`：在保持全局监控启用的情况下，按渠道选择退出健康监控重启。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账户渠道的按账户覆盖。设置后，它会优先于渠道级覆盖。
- 本地 Gateway 网关 调用路径仅在 `gateway.auth.*` 未设置时才可将 `gateway.remote.*` 用作回退。
- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 且无法解析，则解析会以关闭方式失败（不会被远程回退掩盖）。
- `trustedProxies`：终止 TLS 或注入转发客户端标头的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理 / 本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**让 loopback 请求有资格使用 `gateway.auth.mode: "trusted-proxy"`。
- `allowRealIpFallback`：为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关 会接受 `X-Real-IP`。默认值为 `false`，以实现失败即关闭的行为。
- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR / IP 允许列表，用于自动批准首次节点设备配对，且该配对没有请求任何作用域。未设置时为禁用状态。它不会自动批准 operator / browser / Control UI / WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在完成配对和允许列表评估之后，对已声明节点命令进行全局允许 / 拒绝整形。
- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。
- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。
</Accordion>
### OpenAI 兼容端点
- Chat Completions：默认禁用。通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。
- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。
- Responses API：`gateway.http.endpoints.responses.enabled`。
- Responses URL 输入加固：
- `gateway.http.endpoints.responses.maxUrlParts`
@ -372,11 +416,11 @@ provider / base-URL 设置已移至专用页面——请参阅
空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false`
和 / 或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。
- 可选的响应加固标头：
- `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origin 设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
- `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
### 多实例隔离
在一台主机上运行多个 gateways 时，请使用唯一的端口和状态目录：
在同一主机上运行多个 Gateway 网关，并使用唯一端口和状态目录：
```bash
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@ -386,7 +430,7 @@ openclaw gateway --port 19001
便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile <name>`（使用 `~/.openclaw-<name>`）。
请参阅[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。
请参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。
### `gateway.tls`
@ -404,10 +448,10 @@ openclaw gateway --port 19001
}
```
- `enabled`：在 gateway 监听器上启用 TLS 终止（HTTPS / WSS）（默认：`false`）。
- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书 / 密钥对；仅用于本地 / 开发环境。
- `enabled`：在 Gateway 网关 监听器处启用 TLS 终止（HTTPS / WSS）（默认值：`false`）。
- `autoGenerate`：在未配置显式文件时自动生成本地自签名 cert / key 对；仅用于本地 / 开发环境。
- `certPath`：TLS 证书文件的文件系统路径。
- `keyPath`：TLS 私钥文件的文件系统路径；请限制文件权限。
- `keyPath`：TLS 私钥文件的文件系统路径；应保持权限受限。
- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。
### `gateway.reload`
@ -424,13 +468,13 @@ openclaw gateway --port 19001
}
```
- `mode`：控制如何在运行时应用配置编辑。
- `mode`：控制配置编辑在运行时如何应用。
- `"off"`：忽略实时编辑；更改需要显式重启。
- `"restart"`：配置变更时始终重启 gateway 进程。
- `"hot"`：在不重启的情况下于进程内应用更改。
- `"hybrid"`（默认）：先尝试热重载；如有需要则回退为重启。
- `debounceMs`：在应用配置更改前的防抖窗口（毫秒，非负整数）。
- `deferralTimeoutMs`：在强制重启前，等待进行中操作完成的最长时间（毫秒，默认：`300000` = 5 分钟）。
- `"restart"`：配置更改时始终重启 Gateway 网关 进程。
- `"hot"`：在进程内应用更改而不重启。
- `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。
- `debounceMs`：应用配置更改前的防抖窗口（毫秒）（非负整数）。
- `deferralTimeoutMs`：在强制重启前等待进行中操作的最长时间（毫秒）（默认值：`300000` = 5 分钟）。
---
@ -468,46 +512,46 @@ openclaw gateway --port 19001
```
认证：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
拒绝使用查询字符串 hook token。
会拒绝查询字符串中的 hook token。
验证与安全说明：
验证和安全说明：
- `hooks.enabled=true` 要求 `hooks.token` 为非空。
- `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。
- `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。
- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
- 如果某个映射或预设使用模板化 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要此显式启用。
- 如果某个映射或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该显式启用。
**端点：**
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求负载中的 `sessionKey`。
- 仅当 `hooks.allowRequestSessionKey=true` 时，才接受请求负载中的 `sessionKey`（默认：`false`）。
- `POST /hooks/<name>` → 通过 `hooks.mappings` 解析
- 通过模板渲染得到的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。
- 经过模板渲染的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。
<Accordion title="映射详情">
- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。
- `match.source` 匹配通用路径的某个负载字段。
- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取。
- `transform` 可以指向一个返回 hook action 的 JS / TS 模块。
- `transform.module` 必须是相对路径，并且必须位于 `hooks.transformsDir` 内部（绝对路径和路径穿越会被拒绝）。
- `agentId` 路由到特定智能体；未知 ID 会回退到默认值。
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。
- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的 hook 智能体运行。
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。
- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或预设使用模板化 `sessionKey` 时，它将成为必需项。
- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。
- `model` 会覆盖此次 hook 运行使用的 LLM（若设置了模型目录，则该模型必须被允许）。
- `transform` 可以指向返回 hook 动作的 JS / TS 模块。
- `transform.module` 必须是相对路径，并且必须位于 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。
- `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 全部允许，`[]` = 全部拒绝）。
- `defaultSessionKey`：可选的固定会话键，用于未显式指定 `sessionKey` 的 hook 智能体运行。
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。
- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或 preset 使用模板化的 `sessionKey` 时，它就成为必需项。
- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。
- `model` 会为这次 hook 运行覆盖 LLM（如果设置了模型目录，则必须被允许）。
</Accordion>
### Gmail 集成
- 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 约束为匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖预设，而不是使用默认的模板化值。
- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 约束为与 Gmail 命名空间匹配，例如 `["hook:", "hook:gmail:"]`。
- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该 preset，而不是使用模板化默认值。
```json5
{
@ -530,8 +574,8 @@ openclaw gateway --port 19001
}
```
- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。
- 不要在 Gateway 网关之外另外运行一个独立的 `gog gmail watch serve`。
- 配置后，Gateway 网关 会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。
- 不要在 Gateway 网关 旁边单独运行另一个 `gog gmail watch serve`。
---
@ -547,18 +591,18 @@ openclaw gateway --port 19001
}
```
- 在 Gateway 网关端口下通过 HTTP 提供可由智能体编辑的 HTML / CSS / JS 和 A2UI：
- 会通过 Gateway 网关 端口下的 HTTP 提供由智能体可编辑的 HTML / CSS / JS 和 A2UI：
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
- 仅本地：保持 `gateway.bind: "loopback"`（默认）。
- 非 loopback bind：canvas 路由需要 Gateway 网关认证（token / password / trusted-proxy），与其他 Gateway 网关 HTTP 面相同。
- 节点 WebView 通常不会发送认证标头；节点配对并连接后，Gateway 网关会为 canvas / A2UI 访问公布节点作用域 capability URL。
- Capability URL 绑定到活动节点 WS 会话，并且过期很快。不使用基于 IP 的回退。
- 会向所提供的 HTML 中注入实时重载客户端。
- 仅限本地：请保持 `gateway.bind: "loopback"`（默认）。
- 非 loopback 绑定：canvas 路由与其他 Gateway 网关 HTTP 面相同，要求 Gateway 网关 认证（token / password / trusted-proxy）。
- 节点 WebView 通常不会发送认证标头；节点完成配对并连接后，Gateway 网关 会为 canvas / A2UI 访问公布节点作用域的能力 URL。
- 能力 URL 绑定到当前活动的节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。
- 会向所提供的 HTML 注入实时重载客户端。
- 为空时会自动创建初始 `index.html`。
- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。
- 更改需要重启 gateway。
- 对于大型目录或出现 `EMFILE` 错误时，请禁用实时重载。
- 更改需要重启 Gateway 网关。
- 对于大型目录或 `EMFILE` 错误，请禁用实时重载。
---
@ -590,7 +634,7 @@ openclaw gateway --port 19001
}
```
会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS 使用。
会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。
设置：`openclaw dns setup --apply`。
@ -615,10 +659,10 @@ openclaw gateway --port 19001
}
```
- 只有当进程环境中缺少该键时，才会应用内联环境变量。
- 只有在进程环境中缺少该键时，才会应用内联环境变量。
- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。
- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。
- 完整优先级请参阅[环境](/zh-CN/help/environment)。
- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。
- 完整优先级请参见 [环境](/zh-CN/help/environment)。
### 环境变量替换
@ -632,20 +676,20 @@ openclaw gateway --port 19001
}
```
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。
- 缺失 / 为空的变量会在加载配置时报错。
- 仅匹配全大写名称：`[A-Z_][A-Z0-9_]*`。
- 缺失 / 为空的变量会在配置加载时抛出错误。
- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。
- 可与 `$include` 配合使用。
- 可与 `$include` 一起使用。
---
## Secrets
SecretRef 是增量支持的：明文值仍然可用。
SecretRef 是增量式的：明文值仍然可用。
### `SecretRef`
使用一种对象形状：
使用如下对象形状：
```json5
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
@ -655,17 +699,17 @@ SecretRef 是增量支持的：明文值仍然可用。
- `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$`
- `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`）
- `source: "file"` 的 id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`）
- `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "exec"` 的 id 不得包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝）
- `source: "exec"` 的 id 不能包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝）
### 支持的凭证面
- 规范矩阵：[SecretRef 凭证面](/zh-CN/reference/secretref-credential-surface)
- `secrets apply` 面向受支持的 `openclaw.json` 凭证路径。
- `auth-profiles.json` 中的 ref 也包含在运行时解析和审计覆盖范围中。
- `auth-profiles.json` 中的引用已纳入运行时解析和审计覆盖范围。
### Secret providers 配置
### Secret 提供商配置
```json5
{
@ -695,18 +739,18 @@ SecretRef 是增量支持的：明文值仍然可用。
说明：
- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 `singleValue` 模式下，`id` 必须为 `"value"`）。
- 当 Windows ACL 验证不可用时，文件和 exec provider 路径会以关闭失败方式处理。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。
- `exec` provider 要求使用绝对 `command` 路径，并通过 stdin / stdout 传输协议负载。
- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍会验证解析后的目标路径。
- 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。
- 默认情况下，`exec` 子进程环境是最小化的；请通过 `passEnv` 显式传递所需变量。
- Secret ref 会在激活时解析为内存快照，之后请求路径只读取该快照。
- 激活期间会应用活动面过滤：启用表面上的未解析 ref 会导致启动 / 重载失败，而非活动表面会被跳过并给出诊断信息。
- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。
- 当无法验证 Windows ACL 时，file 和 exec 提供商路径会以关闭方式失败。仅对无法验证但可信的路径设置 `allowInsecurePath: true`。
- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin / stdout 上的协议负载进行通信。
- 默认情况下，会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证解析后的目标路径。
- 如果配置了 `trustedDirs`，则可信目录检查会应用于解析后的目标路径。
- 默认情况下，`exec` 子进程环境最小化；请通过 `passEnv` 显式传递所需变量。
- Secret 引用会在激活时解析为内存中的快照，之后请求路径只会读取该快照。
- 激活期间会应用活动面过滤：已启用面上的未解析引用会导致启动 / 重载失败，而非活动面则会被跳过并给出诊断信息。
---
## 凭证存储
## Auth 存储
```json5
{
@ -724,13 +768,13 @@ SecretRef 是增量支持的：明文值仍然可用。
}
```
- 按智能体划分的 profile 存储在 `<agentDir>/auth-profiles.json`。
- `auth-profiles.json` 支持静态凭证模式的值级 ref（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
- OAuth 模式 profile（`auth.profiles.<id>.mode = "oauth"`）不支持基于 SecretRef 的 auth-profile 凭证。
- 静态运行时凭证来自内存中解析后的快照；发现旧版静态 `auth.json` 条目时会进行清理。
- 每个智能体的 profile 存储在 `<agentDir>/auth-profiles.json`。
- `auth-profiles.json` 对静态凭证模式支持值级引用（`api_key` 对应 `keyRef`，`token` 对应 `tokenRef`）。
- OAuth 模式 profile（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。
- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会清理掉。
- 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。
- 请参阅 [OAuth](/zh-CN/concepts/oauth)。
- Secrets 运行时行为以及 `audit/configure/apply` 工具：请参阅[Secrets 管理](/zh-CN/gateway/secrets)。
- 请参见 [OAuth](/zh-CN/concepts/oauth)。
- Secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。
### `auth.cooldowns`
@ -752,15 +796,20 @@ SecretRef 是增量支持的：明文值仍然可用。
}
```
- `billingBackoffHours`：当某个 profile 因真实的计费 / 余额不足错误而失败时的基础退避时长（小时，默认：`5`）。即使在 `401` / `403` 响应上，明确的计费文本仍可能归入这里，但 provider 特定的文本匹配器仍只作用于拥有它们的 provider（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或 organization / workspace 支出限制消息，则仍归入 `rate_limit` 路径。
- `billingBackoffHoursByProvider`：可选的按 provider 覆盖的计费退避时长（小时）。
- `billingMaxHours`：计费退避指数增长的上限（小时，默认：`24`）。
- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时长（分钟，默认：`10`）。
- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限（分钟，默认：`60`）。
- `failureWindowHours`：用于退避计数器的滚动窗口（小时，默认：`24`）。
- `overloadedProfileRotations`：对于过载错误，在切换到模型回退之前，同一 provider 内允许的最大 auth-profile 轮换次数（默认：`1`）。诸如 `ModelNotReadyException` 这样的 provider 忙碌形态归入这里。
- `overloadedBackoffMs`：在重试某个过载的 provider / profile 轮换之前的固定延迟（毫秒，默认：`0`）。
- `rateLimitedProfileRotations`：对于速率限制错误，在切换到模型回退之前，同一 provider 内允许的最大 auth-profile 轮换次数（默认：`1`）。该 rate-limit 类别包括 provider 形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
- `billingBackoffHours`：当某个 profile 因真实的
账单 / 余额不足错误而失败时的基础回退时间（小时）（默认：`5`）。即使在 `401` / `403` 响应上，显式的账单文本
也仍可能归入这里，但提供商特定的文本
匹配器仍仅限于拥有它们的提供商（例如 OpenRouter 的
`Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或
organization / workspace 支出上限消息则仍归入 `rate_limit` 路径。
- `billingBackoffHoursByProvider`：账单回退小时数的可选按提供商覆盖。
- `billingMaxHours`：账单回退指数增长的小时上限（默认：`24`）。
- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础回退时间（分钟）（默认：`10`）。
- `authPermanentMaxMinutes`：`auth_permanent` 回退增长的分钟上限（默认：`60`）。
- `failureWindowHours`：用于回退计数器的滚动时间窗口（小时）（默认：`24`）。
- `overloadedProfileRotations`：对于过载错误，在切换到模型回退之前，同一提供商 auth-profile 的最大轮换次数（默认：`1`）。像 `ModelNotReadyException` 这样的提供商忙碌形态会归入这里。
- `overloadedBackoffMs`：在重试过载的提供商 / profile 轮换前的固定延迟（默认：`0`）。
- `rateLimitedProfileRotations`：对于限流错误，在切换到模型回退之前，同一提供商 auth-profile 的最大轮换次数（默认：`1`）。该限流桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
---
@ -781,12 +830,12 @@ SecretRef 是增量支持的：明文值仍然可用。
- 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。
- 设置 `logging.file` 可使用稳定路径。
- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。
- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节，正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。
- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。
- `maxFileBytes`：在抑制写入之前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。
---
## Diagnostics
## 诊断
```json5
{
@ -827,21 +876,21 @@ SecretRef 是增量支持的：明文值仍然可用。
}
```
- `enabled`：instrumentation 输出总开关（默认：`true`）。
- `flags`：启用定向日志输出的标志字符串数组（支持像 `"telegram.*"` 或 `"*"` 这样的通配符）。
- `stuckSessionWarnMs`：当会话仍处于处理中状态时，发出卡住会话警告的时长阈值（毫秒）。
- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。
- `otel.endpoint`：OTel 导出的 collector URL。
- `enabled`：instrumentation 输出的总开关（默认：`true`）。
- `flags`：用于启用定向日志输出的标志字符串数组（支持通配符，如 `"telegram.*"` 或 `"*"`）。
- `stuckSessionWarnMs`：当会话保持在处理中状态时，用于发出卡住会话警告的年龄阈值（毫秒）。
- `otel.enabled`：启用 OpenTelemetry 导出管道（默认：`false`）。
- `otel.endpoint`：用于 OTel 导出的 collector URL。
- `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。
- `otel.headers`：随 OTel 导出请求发送的额外 HTTP / gRPC 元数据标头。
- `otel.serviceName`：资源属性使用的服务名。
- `otel.serviceName`：资源属性的服务名称。
- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。
- `otel.sampleRate`：trace 采样率 `0`–`1`。
- `otel.sampleRate`：`0`–`1` 的 trace 采样率。
- `otel.flushIntervalMs`：定期刷新 telemetry 的间隔（毫秒）。
- `otel.captureContent`：显式启用用于 OTEL span 属性的原始内容捕获。默认关闭。布尔值 `true` 会捕获非 system 的消息 / 工具内容；对象形式则允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `otel.captureContent`：为 OTEL span 属性选择性启用原始内容捕获。默认关闭。布尔值 `true` 会捕获非 system 消息 / 工具内容；对象形式可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认：`false`）。
- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出包含哪些内容（默认全为 `true`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认全部为 `true`）。
---
@ -863,12 +912,12 @@ SecretRef 是增量支持的：明文值仍然可用。
}
```
- `channel`：用于 npm / git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。
- `checkOnStart`：当 gateway 启动时检查 npm 更新（默认：`true`）。
- `channel`：用于 npm / git 安装的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。
- `checkOnStart`：Gateway 网关 启动时检查 npm 更新（默认：`true`）。
- `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。
- `auto.stableDelayHours`：stable 渠道自动应用前的最短延迟（小时，默认：`6`；最大：`168`）。
- `auto.stableJitterHours`：stable 渠道额外的发布扩散窗口（小时，默认：`12`；最大：`168`）。
- `auto.betaCheckIntervalHours`：beta 渠道检查运行的频率（小时，默认：`1`；最大：`24`）。
- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟（小时）（默认：`6`；最大：`168`）。
- `auto.stableJitterHours`：stable 渠道发布扩散窗口的额外小时数（默认：`12`；最大：`168`）。
- `auto.betaCheckIntervalHours`：beta 渠道执行检查的间隔（小时）（默认：`1`；最大：`24`）。
---
@ -901,21 +950,21 @@ SecretRef 是增量支持的：明文值仍然可用。
}
```
- `enabled`：全局 ACP 功能门控（默认：`false`）。
- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可在阻止执行的同时保留 ACP 命令可用。
- `backend`：默认 ACP 运行时 backend id（必须匹配已注册的 ACP 运行时插件）。
- `defaultAgent`：当 spawn 未指定显式目标时，ACP 目标智能体 id 的回退值。
- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；为空表示没有额外限制。
- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。
- `enabled`：全局 ACP 功能开关（默认：`false`）。
- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在阻止执行的同时保留 ACP 命令可用。
- `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。
- `defaultAgent`：当派生运行未指定显式目标时使用的 ACP 目标智能体 id。
- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 列表；空值表示无额外限制。
- `maxConcurrentSessions`：同时活跃的 ACP 会话最大数量。
- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。
- `stream.maxChunkChars`：拆分流式分块投影前允许的最大分块大小。
- `stream.maxChunkChars`：拆分流式分块投影前的最大块大小。
- `stream.repeatSuppression`：每轮抑制重复的状态 / 工具行（默认：`true`）。
- `stream.deliveryMode`：`"live"` 表示增量流式输出；`"final_only"` 表示缓冲到轮次终结事件后再输出。
- `stream.hiddenBoundarySeparator`：在隐藏工具事件之后、可见文本之前使用的分隔符（默认：`"paragraph"`）。
- `stream.maxOutputChars`：每个 ACP 轮次允许投影的最大助手输出字符数。
- `stream.maxSessionUpdateChars`：投影 ACP 状态 / 更新行允许的最大字符数。
- `stream.tagVisibility`：记录 tag 名称到布尔可见性覆盖的映射，用于流式事件。
- `runtime.ttlMinutes`：ACP 会话 worker 在可被清理前的空闲 TTL（分钟）。
- `stream.deliveryMode`：`"live"` 逐步流式输出；`"final_only"` 则缓冲到轮次终止事件时再输出。
- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。
- `stream.maxOutputChars`：每个 ACP 轮次投影的助手输出最大字符数。
- `stream.maxSessionUpdateChars`：投影的 ACP 状态 / 更新行的最大字符数。
- `stream.tagVisibility`：标签名称到布尔可见性覆盖的记录，用于流式事件。
- `runtime.ttlMinutes`：ACP 会话工作进程在可被清理前的空闲 TTL（分钟）。
- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。
---
@ -932,11 +981,11 @@ SecretRef 是增量支持的：明文值仍然可用。
}
```
- `cli.banner.taglineMode` 控制 banner 标语样式：
- `cli.banner.taglineMode` 控制横幅标语样式：
- `"random"`（默认）：轮换的有趣 / 季节性标语。
- `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。
- `"off"`：不显示标语文本（仍显示 banner 标题 / 版本）。
- 若要隐藏整个 banner（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
- `"off"`：不显示标语文本（仍会显示横幅标题 / 版本）。
- 若要隐藏整个横幅（而不仅仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
---
@ -960,15 +1009,15 @@ SecretRef 是增量支持的：明文值仍然可用。
## 身份
请参阅[智能体默认值](/zh-CN/gateway/config-agents#agent-defaults)中的 `agents.list` 身份字段。
请参见 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下 `agents.list` 的身份字段。
---
## Bridge 协议（旧版节点，历史参考）（旧版，已移除）
## Bridge protocol（旧版节点，历史参考）（旧版，已移除）
当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前会导致验证失败；`openclaw doctor --fix` 可以移除未知键）。
当前构建已不再包含 TCP Bridge protocol（旧版节点，历史参考）。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除之前，验证会失败；`openclaw doctor --fix` 可以清除未知键）。
<Accordion title="旧版 bridge 配置（历史参考）">
<Accordion title="旧版 Bridge protocol（旧版节点，历史参考）配置（历史参考）">
```json
{
@ -1006,11 +1055,11 @@ SecretRef 是增量支持的：明文值仍然可用。
}
```
- `sessionRetention`：在从 `sessions.json` 中清理之前，已完成的隔离 cron 运行会话要保留多久。也控制已归档、已删除 cron 转录的清理。默认：`24h`；设为 `false` 可禁用。
- `runLog.maxBytes`：触发清理前每个运行日志文件（`cron/runs/<jobId>.jsonl`）的最大大小。默认：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认：`2000`。
- `webhookToken`：用于 cron webhook `POST` 交付（`delivery.mode = "webhook"`）的 bearer token；若省略则不会发送认证标头。
- `webhook`：已弃用的旧版回退 webhook URL（http / https），仅用于仍保存 `notify: true` 的存储作业。
- `sessionRetention`：在从 `sessions.json` 中清理之前，保留已完成的隔离 cron 运行会话的时长。也控制已归档且已删除的 cron 转录内容的清理。默认值：`24h`；设为 `false` 可禁用。
- `runLog.maxBytes`：每个运行日志文件（`cron/runs/<jobId>.jsonl`）在清理前允许的最大大小。默认值：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认值：`2000`。
- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不会发送 auth 标头。
- `webhook`：已弃用的旧版回退 webhook URL（http / https），仅用于仍带有 `notify: true` 的已存储任务。
### `cron.retry`
@ -1026,11 +1075,11 @@ SecretRef 是增量支持的：明文值仍然可用。
}
```
- `maxAttempts`：一次性作业在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试对应的退避延迟数组（毫秒，默认：`[30000, 60000, 300000]`；1–10 项）。
- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有瞬时类型。
- `maxAttempts`：一次性任务在瞬时错误下允许的最大重试次数（默认：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试的回退延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。
- `retryOn`：会触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则会重试所有瞬时类型。
仅适用于一次性 cron 作业。循环作业使用单独的失败处理机制。
仅适用于一次性 cron 任务。周期性任务使用单独的失败处理机制。
### `cron.failureAlert`
@ -1048,11 +1097,11 @@ SecretRef 是增量支持的：明文值仍然可用。
}
```
- `enabled`：启用 cron 作业失败告警（默认：`false`）。
- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。
- `cooldownMs`：同一作业重复告警之间的最小间隔（毫秒，非负整数）。
- `mode`：交付模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发起 POST。
- `accountId`：用于限定告警交付范围的可选账号或渠道 id。
- `enabled`：为 cron 任务启用失败告警（默认：`false`）。
- `after`：在触发告警前的连续失败次数（正整数，最小值：`1`）。
- `cooldownMs`：同一任务重复告警之间的最小间隔（毫秒）（非负整数）。
- `mode`：投递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 则 POST 到已配置的 webhook。
- `accountId`：用于限定告警投递范围的可选账户或渠道 id。
### `cron.failureDestination`
@ -1069,16 +1118,16 @@ SecretRef 是增量支持的：明文值仍然可用。
}
```
- 所有作业共用的 cron 失败通知默认目标。
- 所有任务共用的 cron 失败通知默认目标。
- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。
- `channel`：用于 announce 交付的渠道覆盖。`"last"` 会复用最后一次已知的交付渠道。
- `to`：显式的 announce 目标或 webhook URL。在 webhook 模式下为必需。
- `accountId`：用于交付的可选账号覆盖。
- 按作业的 `delivery.failureDestination` 会覆盖这个全局默认值。
- 当全局和按作业的失败目标都未设置时，已经通过 `announce` 交付的作业在失败时会回退到该主要 announce 目标。
- `delivery.failureDestination` 仅在 `sessionTarget="isolated"` 的作业中受支持，除非该作业的主要 `delivery.mode` 是 `"webhook"`。
- `channel`：announce 投递的渠道覆盖。`"last"` 会复用最后一次已知的投递渠道。
- `to`：显式 announce 目标或 webhook URL。在 webhook 模式下为必填项。
- `accountId`：投递的可选账户覆盖。
- 每个任务的 `delivery.failureDestination` 会覆盖这个全局默认值。
- 当既未设置全局失败目标，也未设置每任务失败目标时，已通过 `announce` 投递的任务会在失败时回退到其主 announce 目标。
- `delivery.failureDestination` 仅对 `sessionTarget="isolated"` 的任务受支持，除非该任务的主 `delivery.mode` 为 `"webhook"`。
请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。
请参见 [Cron 任务](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。
---
@ -1086,28 +1135,28 @@ SecretRef 是增量支持的：明文值仍然可用。
在 `tools.media.models[].args` 中展开的模板占位符：
| 变量 | 描述 |
| ------------------ | ------------------------------------------------- |
| `{{Body}}` | 完整的入站消息正文 |
| `{{RawBody}}` | 原始正文（无历史记录 / 发送者包装） |
| Variable | 描述 |
| ------------------ | ---- |
| `{{Body}}` | 完整的入站消息正文 |
| `{{RawBody}}` | 原始正文（无历史记录 / 发送者包装） |
| `{{BodyStripped}}` | 去除群组提及后的正文 |
| `{{From}}` | 发送者标识符 |
| `{{To}}` | 目标标识符 |
| `{{MessageSid}}` | 渠道消息 id |
| `{{SessionId}}` | 当前会话 UUID |
| `{{From}}` | 发送者标识符 |
| `{{To}}` | 目标标识符 |
| `{{MessageSid}}` | 渠道消息 id |
| `{{SessionId}}` | 当前会话 UUID |
| `{{IsNewSession}}` | 新建会话时为 `"true"` |
| `{{MediaUrl}}` | 入站媒体伪 URL |
| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（image / audio / document / …） |
| `{{Transcript}}` | 音频转录文本 |
| `{{Prompt}}` | 为 CLI 条目解析后的媒体提示词 |
| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 |
| `{{ChatType}}` | `"direct"` 或 `"group"` |
| `{{MediaUrl}}` | 入站媒体伪 URL |
| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（image / audio / document / …） |
| `{{Transcript}}` | 音频转录文本 |
| `{{Prompt}}` | CLI 条目的已解析媒体提示词 |
| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 |
| `{{ChatType}}` | `"direct"` 或 `"group"` |
| `{{GroupSubject}}` | 群组主题（尽力而为） |
| `{{GroupMembers}}` | 群组成员预览（尽力而为） |
| `{{SenderName}}` | 发送者显示名称（尽力而为） |
| `{{SenderE164}}` | 发送者电话号码（尽力而为） |
| `{{Provider}}` | provider 提示（whatsapp、telegram、discord 等） |
| `{{SenderName}}` | 发送者显示名称（尽力而为） |
| `{{SenderE164}}` | 发送者电话号码（尽力而为） |
| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） |
---
@ -1128,20 +1177,20 @@ SecretRef 是增量支持的：明文值仍然可用。
**合并行为：**
- 单文件：替换所在的包含对象。
- 单个文件：替换所在的包含对象。
- 文件数组：按顺序深度合并（后者覆盖前者）。
- 同级键：在 includes 之后合并（覆盖 include 的值）。
- 嵌套 include：最多支持 10 层。
- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径 / `../` 形式最终仍解析到该边界内时才允许。
- OpenClaw 自有写入在仅修改由单文件 include 支持的某个顶层 section 时，会直写到该 include 文件中。例如，`plugins install` 会将 `plugins: { $include: "./plugins.json5" }` 更新到 `plugins.json5` 中，并保持 `openclaw.json` 不变。
- 根 include、include 数组，以及带同级覆盖的 include，对 OpenClaw 自有写入来说是只读的；这些写入会以关闭失败方式处理，而不是把配置拍平。
- 错误：对于缺失文件、解析错误和循环 include，会给出清晰消息。
- 同级键：在 include 之后合并（覆盖 include 的值）。
- 嵌套 include：最多 10 层深。
- 路径：相对于发起 include 的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。只有在最终仍解析到该边界内时，才允许使用绝对路径 / `../` 形式。
- 当 OpenClaw 自有写入仅更改由单文件 include 支持的某个顶层区段时，这些更改会直写到该 include 文件。例如，`plugins install` 会把 `plugins: { $include: "./plugins.json5" }` 的更新写入 `plugins.json5`，并保持 `openclaw.json` 不变。
- 对于根级 include、include 数组以及带有同级覆盖的 include，OpenClaw 自有写入为只读；这些写入会以关闭方式失败，而不是将配置展平。
- 错误：对缺失文件、解析错误和循环 include 提供清晰的错误消息。
---
_相关内容：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_
## 相关内容
## 相关
- [配置](/zh-CN/gateway/configuration)
- [配置示例](/zh-CN/gateway/configuration-examples)

446
docs/zh-CN/plugins/google-meet.md
View File

@ -1,36 +1,36 @@
---
read_when:
- 你希望一个 OpenClaw 智能体加入 Google Meet 通话
- 你希望一个 OpenClaw 智能体创建新的 Google Meet 通话
- 你想让一个 OpenClaw 智能体加入 Google Meet 通话
- 你想让一个 OpenClaw 智能体创建新的 Google Meet 通话
- 你正在将 Chrome、Chrome 节点或 Twilio 配置为 Google Meet 传输方式
summary: Google Meet 插件：通过 Chrome 或 Twilio 加入明确的 Meet URL，并使用实时语音默认设置
summary: Google Meet 插件：通过 Chrome 或 Twilio 加入明确指定的 Meet URL，并使用实时语音默认设置
title: Google Meet 插件
x-i18n:
generated_at: "2026-04-25T06:39:33Z"
generated_at: "2026-04-25T06:52:33Z"
model: gpt-5.4
provider: openai
source_hash: b4ba4dd272e9951f19f2f2cc17be8e2c30b698137d77b4c589cbe33c34bc6d95
source_hash: d512862fc3fd8da8b3e581bb69f04238ca533de448b90481ff39ac333061d50c
source_path: plugins/google-meet.md
workflow: 15
---
OpenClaw 的 Google Meet 参会支持——该插件在设计上是显式的：
- 它只会加入明确的 `https://meet.google.com/...` URL。
- 它只会加入明确指定的 `https://meet.google.com/...` URL。
- 它可以通过 Google Meet API 创建一个新的 Meet 空间，然后加入返回的 URL。
- `realtime` 语音是默认模式。
- 当需要更深入的推理或工具时，实时语音可以回调到完整的 OpenClaw 智能体。
- 智能体使用 `mode` 选择加入行为：实时收听/回话使用 `realtime`，仅加入/控制浏览器且不启用实时语音桥接则使用 `transcribe`。
- 认证起始方式可以是个人 Google OAuth，或已经登录的 Chrome 配置文件。
- 不会自动播报同意提示。
- 智能体通过 `mode` 选择加入行为：使用 `realtime` 进行实时收听/回话，或使用 `transcribe` 在不启用实时语音桥接的情况下加入/控制浏览器。
- 认证起始方式为个人 Google OAuth 或已登录的 Chrome 配置文件。
- 没有自动的同意提示播报。
- 默认的 Chrome 音频后端是 `BlackHole 2ch`。
- Chrome 可以在本地运行，也可以在已配对的节点主机上运行。
- Twilio 接受拨入号码，以及可选的 PIN 或 DTMF 序列。
- CLI 命令是 `googlemeet`；`meet` 保留给更广义的智能体电话会议工作流。
- Twilio 接受一个拨入号码，以及可选的 PIN 或 DTMF 序列。
- CLI 命令是 `googlemeet`；`meet` 保留给更广泛的智能体电话会议工作流使用。
## 快速开始
安装本地音频依赖，并配置一个后端实时语音提供商。OpenAI 是默认选项；Google Gemini Live 也可用，配置方式是 `realtime.provider: "google"`：
安装本地音频依赖，并配置一个后端实时语音提供商。OpenAI 是默认项；Google Gemini Live 也可与 `realtime.provider: "google"` 一起使用：
```bash
brew install blackhole-2ch sox
@ -39,20 +39,20 @@ export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
```
`blackhole-2ch` 会安装 `BlackHole 2ch` 虚拟音频设备。Homebrew 的安装程序要求重启后 macOS 才会暴露该设备：
`blackhole-2ch` 会安装 `BlackHole 2ch` 虚拟音频设备。Homebrew 的安装程序要求重启，macOS 才会暴露该设备：
```bash
sudo reboot
```
重启后，验证这两部分是否都已就绪：
重启后，验证这两部分都已就绪：
```bash
system_profiler SPAudioDataType | grep -i BlackHole
command -v rec play
```
启用该插件：
启用插件：
```json5
{
@ -73,8 +73,8 @@ command -v rec play
openclaw googlemeet setup
```
设置输出旨在便于智能体读取。它会报告 Chrome 配置文件、音频桥接、节点固定、延迟的实时介绍，以及在配置了 Twilio 委派时，`voice-call` 插件和 Twilio 凭证是否已就绪。
在请求智能体加入之前，应将任何 `ok: false` 的检查视为阻塞项。
设置输出旨在让智能体可读。它会报告 Chrome 配置文件、音频桥接、节点固定、延迟的实时介绍，以及在配置了 Twilio 委派时，`voice-call` 插件和 Twilio 凭证是否就绪。
在要求智能体加入之前，将任何 `ok: false` 的检查都视为阻塞项。
脚本或机器可读输出请使用 `openclaw googlemeet setup --json`。
加入会议：
@ -94,13 +94,13 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij
}
```
创建一个新会议并加入：
创建新会议并加入：
```bash
openclaw googlemeet create --transport chrome-node --mode realtime
```
只创建 URL 而不加入：
仅创建 URL 而不加入：
```bash
openclaw googlemeet create --no-join
@ -108,14 +108,16 @@ openclaw googlemeet create --no-join
`googlemeet create` 有两条路径：
- API 创建：当配置了 Google Meet OAuth 凭证时使用。这是最确定的路径，不依赖浏览器 UI 状态。
- 浏览器回退：当缺少 OAuth 凭证时使用。OpenClaw 会使用固定的 Chrome 节点，打开 `https://meet.google.com/new`，等待 Google 重定向到真实的会议代码 URL，然后返回该 URL。此路径要求节点上的 OpenClaw Chrome 配置文件已经登录 Google。
- API 创建：当 Google Meet OAuth 凭证已配置时使用。这是最可预测的路径，不依赖浏览器 UI 状态。
- 浏览器回退：当 OAuth 凭证缺失时使用。OpenClaw 使用固定的 Chrome 节点，打开 `https://meet.google.com/new`，等待 Google 重定向到真实的会议代码 URL，然后返回该 URL。这条路径要求节点上的 OpenClaw Chrome 配置文件已登录 Google。
浏览器自动化会处理 Meet 自身的首次运行麦克风提示；该提示不会被视为 Google 登录失败。
加入和创建流程还会尝试复用现有的 Meet 标签页，而不是新开一个标签页。匹配时会忽略无害的 URL 查询字符串，如 `authuser`，因此智能体重试时应聚焦到已打开的会议，而不是创建第二个 Chrome 标签页。
加入和创建流程也会在打开新标签页前尝试复用现有的 Meet 标签页。匹配时会忽略无害的 URL 查询字符串，例如 `authuser`，因此智能体的重试应聚焦到已打开的会议，而不是创建第二个 Chrome 标签页。
命令/工具输出包含一个 `source` 字段（`api` 或 `browser`），这样智能体可以说明使用了哪条路径。`create` 默认会加入新会议，并返回 `joined: true` 以及对应的加入会话。若只想生成 URL，请在 CLI 中使用 `create --no-join`，或向工具传入 `"join": false`。
命令/工具输出包含一个 `source` 字段（`api` 或 `browser`），这样智能体可以说明使用了哪条路径。
`create` 默认会加入新会议，并返回 `joined: true` 以及加入会话。若只想生成 URL，请在 CLI 中使用 `create --no-join`，或向工具传入 `"join": false`。
或者告诉智能体：“创建一个 Google Meet，用实时语音加入它，并把链接发给我。” 智能体应调用 `google_meet`，设置 `action: "create"`，然后分享返回的 `meetingUri`。
或者告诉智能体：“创建一个 Google Meet，用实时语音加入，并把链接发给我。”
智能体应使用 `action: "create"` 调用 `google_meet`，然后分享返回的 `meetingUri`。
```json
{
@ -125,21 +127,24 @@ openclaw googlemeet create --no-join
}
```
如果是仅观察/控制浏览器的加入，请设置 `"mode": "transcribe"`。这不会启动双工实时模型桥接，因此它不会在会议中回话。
若要仅观察/控制浏览器地加入，请设置 `"mode": "transcribe"`。这样不会启动双工实时模型桥接，因此它不会在会议中回话。
在实时会话期间，`google_meet` 状态会包含浏览器和音频桥接健康信息，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近输入/输出时间戳、字节计数，以及桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可以处理时自动处理。登录、主持人准入，以及浏览器/操作系统权限提示会作为手动操作上报，并附带原因和消息，供智能体转达。
在实时会话期间，`google_meet` 状态会包含浏览器和音频桥接健康信息，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近输入/输出时间戳、字节计数，以及桥接关闭状态。
如果出现安全的 Meet 页面提示，浏览器自动化会在可处理时自动处理。
登录、主持人准入以及浏览器/操作系统权限提示会作为手动操作报告，并带有原因和消息，供智能体转达。
Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，为 OpenClaw 使用的麦克风/扬声器路径选择 `BlackHole 2ch`。如需干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备足以完成首次冒烟测试，但可能会产生回声。
Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，选择 `BlackHole 2ch` 作为 OpenClaw 使用的麦克风/扬声器路径。为了获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备足以完成首次冒烟测试，但可能会产生回声。
### 本地 Gateway 网关 + Parallels Chrome
你**不**需要在 macOS VM 中运行完整的 OpenClaw Gateway 网关或配置模型 API 密钥，只是为了让 VM 承担 Chrome。你可以在本地运行 Gateway 网关和智能体，然后在 VM 中运行一个节点主机。只需在 VM 中启用一次内置插件，这样节点就会广播 Chrome 命令：
你**不**需要在 macOS VM 中部署完整的 OpenClaw Gateway 网关或模型 API 密钥，只是为了让 VM 承担 Chrome。
你可以在本地运行 Gateway 网关和智能体，然后在 VM 中运行一个节点主机。只需在 VM 中启用一次内置插件，这样节点就会广播 Chrome 命令：
各部分运行位置：
各组件运行位置：
- Gateway 网关主机：OpenClaw Gateway 网关、智能体工作区、模型/API 密钥、实时提供商，以及 Google Meet 插件配置。
- Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及已登录 Google 的 Chrome 配置文件。
- VM 中不需要：Gateway 网关服务、智能体配置、OpenAI/GPT 密钥，或模型提供商设置。
- Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及一个已登录 Google 的 Chrome 配置文件。
- VM 中不需要：Gateway 网关服务、智能体配置、OpenAI/GPT 密钥或模型提供商设置。
安装 VM 依赖：
@ -147,13 +152,13 @@ Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，为 O
brew install blackhole-2ch sox
```
安装 BlackHole 后重启 VM，以便 macOS 暴露 `BlackHole 2ch`：
安装 BlackHole 后重启 VM，macOS 才会暴露 `BlackHole 2ch`：
```bash
sudo reboot
```
重启后，验证 VM 可以看到音频设备和 SoX 命令：
重启后，验证 VM 能看到该音频设备和 SoX 命令：
```bash
system_profiler SPAudioDataType | grep -i BlackHole
@ -172,14 +177,14 @@ openclaw plugins enable google-meet
openclaw node run --host <gateway-host> --port 18789 --display-name parallels-macos
```
如果 `<gateway-host>` 是局域网 IP，且你未使用 TLS，那么除非你为该受信私有网络显式开启，否则节点会拒绝明文 WebSocket：
如果 `<gateway-host>` 是局域网 IP 且你未使用 TLS，除非你为该受信任私有网络显式启用明文 WebSocket，否则节点会拒绝它：
```bash
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
openclaw node run --host <gateway-lan-ip> --port 18789 --display-name parallels-macos
```
将节点安装为 LaunchAgent 时，也要使用同样的环境变量：
将节点安装为 LaunchAgent 时，使用相同的环境变量：
```bash
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
@ -187,8 +192,8 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
openclaw node restart
```
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是进程环境，而不是 `openclaw.json` 设置。
当该环境变量出现在安装命令中时，`openclaw node install` 会将其存储到 LaunchAgent 环境中。
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是进程环境，不是 `openclaw.json` 设置。
当它出现在安装命令中时，`openclaw node install` 会将其存储到 LaunchAgent 环境中。
在 Gateway 网关主机上批准该节点：
@ -197,7 +202,7 @@ openclaw devices list
openclaw devices approve <requestId>
```
确认 Gateway 网关可以看到该节点，并且它同时广播了 `googlemeet.chrome` 和浏览器能力/`browser.proxy`：
确认 Gateway 网关能看到该节点，并且它同时广播了 `googlemeet.chrome` 和浏览器能力/`browser.proxy`：
```bash
openclaw nodes status
@ -233,61 +238,67 @@ openclaw nodes status
}
```
现在即可从 Gateway 网关主机正常加入：
现在就可以从 Gateway 网关主机正常加入：
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij
```
或者让智能体使用 `google_meet` 工具，并设置 `transport: "chrome-node"`。
或者要求智能体使用 `google_meet` 工具并设置 `transport: "chrome-node"`。
如果想进行一条命令的冒烟测试：创建或复用一个会话，说出一段已知短语，并打印会话健康状态：
如需执行一个单命令冒烟测试，以创建或复用会话、说出一段已知短语并打印会话健康状态：
```bash
openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij
```
在加入期间，OpenClaw 浏览器自动化会填写访客名称，点击加入/请求加入，并在出现提示时接受 Meet 首次运行的“使用麦克风”选项。在仅浏览器创建会议期间，如果 Meet 没有暴露使用麦克风按钮，它也可以在不使用麦克风的情况下继续通过同一个提示。
如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要麦克风/摄像头权限，或 Meet 卡在自动化无法解决的提示上，`join`/`test-speech` 结果会报告 `manualActionRequired: true`，并带上 `manualActionReason` 和 `manualActionMessage`。智能体应停止重试加入，报告该精确消息以及当前的 `browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后再重试。
在加入过程中，OpenClaw 浏览器自动化会填写访客名称、点击 Join/Ask to join，并在出现该提示时接受 Meet 首次运行的 “Use microphone” 选项。
在仅通过浏览器创建会议时，如果 Meet 没有暴露使用麦克风按钮，它也可以在不使用麦克风的情况下继续越过同一个提示。
如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要麦克风/摄像头权限，或 Meet 卡在某个自动化无法解决的提示上，加入/`test-speech` 结果会报告 `manualActionRequired: true`，并附带 `manualActionReason` 和 `manualActionMessage`。
智能体应停止重试加入，报告这条原样消息以及当前的 `browserUrl`/`browserTitle`，并且仅在手动浏览器操作完成后才重试。
如果省略 `chromeNode.node`，只有在恰好只有一个已连接节点同时广播 `googlemeet.chrome` 和浏览器控制时，OpenClaw 才会自动选择。
如果省略 `chromeNode.node`，只有在恰好有一个已连接节点同时广播 `googlemeet.chrome` 和浏览器控制能力时，OpenClaw 才会自动选择。
如果连接了多个具备能力的节点，请将 `chromeNode.node` 设置为节点 id、显示名称或远程 IP。
常见故障检查：
- `No connected Google Meet-capable node`：在 VM 中启动 `openclaw node run`，批准配对，并确保已在 VM 中运行 `openclaw plugins enable google-meet` 和 `openclaw plugins enable browser`。同时确认 Gateway 网关主机已通过 `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` 允许这两个节点命令。
- `BlackHole 2ch audio device not found on the node`：在 VM 中安装 `blackhole-2ch`，并重启 VM。
- Chrome 可以打开但无法加入：在 VM 内的浏览器配置文件中登录，或者保持设置 `chrome.guestName` 以便访客加入。访客自动加入通过节点浏览器代理使用 OpenClaw 浏览器自动化；请确保节点浏览器配置指向你想要的配置文件，例如 `browser.defaultProfile: "user"` 或某个命名的现有会话配置文件。
- 重复的 Meet 标签页：保持启用 `chrome.reuseExistingTab: true`。OpenClaw 会先激活相同 Meet URL 的现有标签页，再打开新标签页；浏览器会议创建也会在打开另一个标签页之前复用一个进行中的 `https://meet.google.com/new` 或 Google 账户提示标签页。
- 没有音频：在 Meet 中，将麦克风/扬声器路由到 OpenClaw 使用的虚拟音频设备路径；为了获得干净的双工音频，请使用独立虚拟设备或类似 Loopback 的路由。
- `No connected Google Meet-capable node`：在 VM 中启动 `openclaw node run`，批准配对，并确保已在 VM 中运行 `openclaw plugins enable google-meet` 和 `openclaw plugins enable browser`。还要确认 Gateway 网关主机通过 `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]` 允许这两个节点命令。
- `BlackHole 2ch audio device not found on the node`：在 VM 中安装 `blackhole-2ch` 并重启 VM。
- Chrome 已打开但无法加入：在 VM 中登录浏览器配置文件，或者保留 `chrome.guestName` 以访客身份加入。访客自动加入使用 OpenClaw 通过节点浏览器代理执行的浏览器自动化；请确保节点浏览器配置指向你想使用的配置文件，例如 `browser.defaultProfile: "user"` 或某个已命名的现有会话配置文件。
- 重复的 Meet 标签页：保持启用 `chrome.reuseExistingTab: true`。OpenClaw 会先激活相同 Meet URL 的现有标签页，再打开新标签页；而且浏览器会议创建会复用进行中的 `https://meet.google.com/new` 或 Google 账号提示标签页，而不是再打开一个。
- 没有音频：在 Meet 中，将麦克风/扬声器路由到 OpenClaw 使用的虚拟音频设备路径；使用独立的虚拟设备或类似 Loopback 的路由以获得干净的双工音频。
## 安装说明
Chrome 实时默认设置使用两个外部工具：
- `sox`：命令行音频工具。该插件使用其 `rec` 和 `play` 命令来实现默认的 8 kHz G.711 mu-law 音频桥接。
- `sox`：命令行音频工具。该插件使用它的 `rec` 和 `play` 命令来实现默认的 8 kHz G.711 mu-law 音频桥接。
- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 `BlackHole 2ch` 音频设备，供 Chrome/Meet 路由使用。
OpenClaw 不会捆绑或重新分发这两个软件包。文档要求用户通过 Homebrew 将它们作为主机依赖安装。SoX 采用 `LGPL-2.0-only AND GPL-2.0-only` 许可；BlackHole 采用 GPL-3.0 许可。如果你构建了一个将 BlackHole 与 OpenClaw 一起打包的安装器或设备，请审查 BlackHole 上游许可条款，或从 Existential Audio 获取单独许可。
OpenClaw 不会内置或重新分发这两个软件包。文档要求用户通过 Homebrew 将它们作为主机依赖安装。
SoX 采用 `LGPL-2.0-only AND GPL-2.0-only` 许可；BlackHole 采用 GPL-3.0 许可。
如果你要构建一个将 BlackHole 与 OpenClaw 一起打包的安装程序或设备，请审查 BlackHole 上游的许可条款，或从 Existential Audio 获取单独许可。
## 传输方式
### Chrome
Chrome 传输会在 Google Chrome 中打开 Meet URL，并以已登录的 Chrome 配置文件身份加入。在 macOS 上，插件会在启动前检查是否存在 `BlackHole 2ch`。如果已配置，它还会在打开 Chrome 之前运行音频桥接健康检查命令和启动命令。当 Chrome/音频运行在 Gateway 网关主机上时使用 `chrome`；当 Chrome/音频 运行在已配对节点（例如 Parallels macOS VM）上时使用 `chrome-node`。
Chrome 传输方式会在 Google Chrome 中打开 Meet URL，并以已登录的 Chrome 配置文件身份加入。在 macOS 上，插件会在启动前检查 `BlackHole 2ch`。
如果进行了配置，它还会在打开 Chrome 之前运行音频桥接健康检查命令和启动命令。
当 Chrome/音频位于 Gateway 网关主机上时，请使用 `chrome`；当 Chrome/音频位于已配对节点上（例如 Parallels macOS VM）时，请使用 `chrome-node`。
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome
openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node
```
将 Chrome 麦克风和扬声器音频通过本地 OpenClaw 音频桥接进行路由。如果未安装 `BlackHole 2ch`，加入会以设置错误失败，而不是在没有音频路径的情况下静默加入。
将 Chrome 麦克风和扬声器音频通过本地 OpenClaw 音频桥接进行路由。如果未安装 `BlackHole 2ch`，加入会因设置错误而失败，而不是在没有音频路径的情况下静默加入。
### Twilio
Twilio 传输是一种严格的拨号计划，并委派给 Voice Call 插件。它不会解析 Meet 页面来获取电话号码。
Twilio 传输方式是一种严格的拨号计划，委派给 Voice Call 插件处理。它不会解析 Meet 页面以获取电话号码。
当无法使用 Chrome 参会，或者你想要电话拨入作为回退方案时，请使用此方式。Google Meet 必须为该会议提供电话拨入号码和 PIN；OpenClaw 不会从 Meet 页面中发现这些信息。
当无法使用 Chrome 参会，或者你想要一个电话拨入后备方案时，请使用此方式。Google Meet 必须为该会议提供电话拨入号码和 PIN；OpenClaw 不会从 Meet 页面中发现这些信息。
在 Gateway 网关主机上启用 Voice Call 插件，而不是在 Chrome 节点上：
@ -314,7 +325,7 @@ Twilio 传输是一种严格的拨号计划，并委派给 Voice Call 插件。
}
```
通过环境变量或配置提供 Twilio 凭证。使用环境变量可以避免将密钥放入 `openclaw.json`：
通过环境变量或配置提供 Twilio 凭证。环境变量可将密钥保留在 `openclaw.json` 之外：
```bash
export TWILIO_ACCOUNT_SID=AC...
@ -322,9 +333,9 @@ export TWILIO_AUTH_TOKEN=...
export TWILIO_FROM_NUMBER=+15550001234
```
启用 `voice-call` 后，请重启或重新加载 Gateway 网关；在 Gateway 网关进程重新加载之前，插件配置变更不会出现在已经运行的 Gateway 网关进程中。
启用 `voice-call` 后请重启或重新加载 Gateway 网关；在 Gateway 网关进程重新加载之前，插件配置变更不会出现在已运行的进程中。
然后验证：
然后进行验证：
```bash
openclaw config validate
@ -332,7 +343,7 @@ openclaw plugins list | grep -E 'google-meet|voice-call'
openclaw googlemeet setup
```
当 Twilio 委派已正确连通时，`googlemeet setup` 会包含成功的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查项。
当 Twilio 委派连通后，`googlemeet setup` 会包含成功的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij \
@ -352,29 +363,153 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \
## OAuth 和预检
OAuth 对于创建 Meet 链接是可选的，因为 `googlemeet create` 可以回退到浏览器自动化。当你希望使用官方 API 创建、空间解析，或 Meet Media API 预检时，请配置 OAuth。
OAuth 对于创建 Meet 链接是可选的，因为 `googlemeet create` 可以回退到浏览器自动化。当你需要官方 API 创建、空间解析或 Meet Media API 预检时，请配置 OAuth。
Google Meet API 访问优先使用个人 OAuth 客户端。配置
`oauth.clientId`，并可选配置 `oauth.clientSecret`，然后运行：
Google Meet API 访问使用用户 OAuth：创建一个 Google Cloud OAuth 客户端，请求所需作用域，授权一个 Google 账号，然后将生成的 refresh token 存储在 Google Meet 插件配置中，或提供 `OPENCLAW_GOOGLE_MEET_*` 环境变量。
OAuth 不会替代 Chrome 加入路径。使用浏览器参会时，Chrome 和 `chrome-node` 传输方式仍然通过已登录的 Chrome 配置文件、BlackHole/SoX，以及一个已连接节点来加入。OAuth 仅用于官方 Google Meet API 路径：创建会议空间、解析空间，以及执行 Meet Media API 预检。
### 创建 Google 凭证
在 Google Cloud Console 中：
1. 创建或选择一个 Google Cloud 项目。
2. 为该项目启用 **Google Meet REST API**。
3. 配置 OAuth 同意屏幕。
- 对于 Google Workspace 组织，**Internal** 最简单。
- **External** 适用于个人/测试设置；当应用处于 Testing 状态时，将每个会授权该应用的 Google 账号添加为测试用户。
4. 添加 OpenClaw 请求的作用域：
- `https://www.googleapis.com/auth/meetings.space.created`
- `https://www.googleapis.com/auth/meetings.space.readonly`
- `https://www.googleapis.com/auth/meetings.conference.media.readonly`
5. 创建一个 OAuth client ID。
- 应用类型：**Web application**。
- 已获授权的重定向 URI：
```text
http://localhost:8085/oauth2callback
```
6. 复制 client ID 和 client secret。
Google Meet `spaces.create` 需要 `meetings.space.created`。
`meetings.space.readonly` 允许 OpenClaw 将 Meet URL/代码解析为会议空间。
`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体相关工作；对于实际的 Media API 使用，Google 可能要求加入 Developer Preview。
如果你只需要基于浏览器的 Chrome 加入，可完全跳过 OAuth。
### 生成 refresh token
配置 `oauth.clientId`，并可选配置 `oauth.clientSecret`，或将它们作为环境变量传入，然后运行：
```bash
openclaw googlemeet auth login --json
```
该命令会输出一个带刷新令牌的 `oauth` 配置块。它使用 PKCE、本地回调 `http://localhost:8085/oauth2callback`，以及通过 `--manual` 进行手动复制/粘贴的流程。
该命令会输出一个包含 refresh token 的 `oauth` 配置块。它使用 PKCE、本地回调 `http://localhost:8085/oauth2callback`，以及通过 `--manual` 启用的手动复制/粘贴流程。
OAuth 同意范围包括 Meet 空间创建、Meet 空间读取权限，以及 Meet 会议媒体读取权限。如果你在支持会议创建之前就已完成认证，请重新运行 `openclaw googlemeet auth login --json`，以便刷新令牌具备 `meetings.space.created` scope。
示例：
浏览器回退不需要 OAuth 凭证。在该模式下，Google 认证来自所选节点上的已登录 Chrome 配置文件，而不是来自 OpenClaw 配置。
```bash
OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \
OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \
openclaw googlemeet auth login --json
```
支持以下环境变量作为回退：
当浏览器无法访问本地回调时，请使用手动模式：
```bash
OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \
OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \
openclaw googlemeet auth login --json --manual
```
JSON 输出包含：
```json
{
"oauth": {
"clientId": "your-client-id",
"clientSecret": "your-client-secret",
"refreshToken": "refresh-token",
"accessToken": "access-token",
"expiresAt": 1770000000000
},
"scope": "..."
}
```
将 `oauth` 对象存储到 Google Meet 插件配置下：
```json5
{
plugins: {
entries: {
"google-meet": {
enabled: true,
config: {
oauth: {
clientId: "your-client-id",
clientSecret: "your-client-secret",
refreshToken: "refresh-token",
},
},
},
},
},
}
```
如果你不想将 refresh token 放入配置中，优先使用环境变量。
如果配置和环境变量值同时存在，插件会优先解析配置，然后再回退到环境变量。
OAuth 同意内容包括 Meet 空间创建、Meet 空间读取访问，以及 Meet 会议媒体读取访问。如果你在会议创建支持出现之前就已完成认证，请重新运行 `openclaw googlemeet auth login --json`，以便 refresh token 包含 `meetings.space.created` 作用域。
### 使用 Doctor 验证 OAuth
当你需要快速、无密钥暴露的健康检查时，请运行 OAuth Doctor：
```bash
openclaw googlemeet doctor --oauth --json
```
这不会加载 Chrome 运行时，也不要求连接 Chrome 节点。它会检查 OAuth 配置是否存在，以及 refresh token 是否可以生成 access token。JSON 报告仅包含 `ok`、`configured`、`tokenSource`、`expiresAt` 和检查消息等状态字段；它不会输出 access token、refresh token 或 client secret。
常见结果：
| 检查 | 含义 |
| -------------------- | --------------------------------------------------------------------------------------- |
| `oauth-config` | 存在 `oauth.clientId` 加 `oauth.refreshToken`，或存在已缓存的 access token。 |
| `oauth-token` | 已缓存的 access token 仍然有效，或 refresh token 已生成新的 access token。 |
| `meet-spaces-get` | 可选的 `--meeting` 检查已解析出一个现有 Meet 空间。 |
| `meet-spaces-create` | 可选的 `--create-space` 检查已创建一个新的 Meet 空间。 |
如需一并证明 Google Meet API 已启用以及具备 `spaces.create` 作用域，请运行带副作用的创建检查：
```bash
openclaw googlemeet doctor --oauth --create-space --json
openclaw googlemeet create --no-join --json
```
`--create-space` 会创建一个一次性的 Meet URL。当你需要确认 Google Cloud 项目已启用 Meet API，且已授权账号具备 `meetings.space.created` 作用域时，请使用它。
如需证明对现有会议空间具有读取权限：
```bash
openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json
openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij
```
`doctor --oauth --meeting` 和 `resolve-space` 可证明已授权的 Google 账号对某个现有空间具有读取权限。来自这些检查的 `403` 通常表示 Google Meet REST API 未启用、已同意的 refresh token 缺少所需作用域，或该 Google 账号无权访问该 Meet 空间。若是 refresh token 错误，则表示应重新运行 `openclaw googlemeet auth login --json` 并存储新的 `oauth` 块。
浏览器回退不需要 OAuth 凭证。在该模式下，Google 认证来自所选节点上已登录的 Chrome 配置文件，而不是来自 OpenClaw 配置。
以下环境变量可作为回退值：
- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID`
- `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` 或 `GOOGLE_MEET_CLIENT_SECRET`
- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` 或 `GOOGLE_MEET_REFRESH_TOKEN`
- `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN` 或 `GOOGLE_MEET_ACCESS_TOKEN`
- `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` 或
`GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT`
- `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` 或 `GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT`
- `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` 或 `GOOGLE_MEET_DEFAULT_MEETING`
- `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` 或 `GOOGLE_MEET_PREVIEW_ACK`
@ -390,21 +525,21 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij
openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij
```
在 Meet 创建会议记录后，列出会议产物和出席情况：
在 Meet 创建会议记录后，列出会议工件和出勤情况：
```bash
openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij
openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij
```
如果你已经知道会议记录 id，可以直接指定：
如果你已经知道 conference record id，可以直接使用它：
```bash
openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --json
openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json
```
`artifacts` 会返回会议记录元数据，以及当 Google 为该会议提供时的参会者、录制、转录和智能笔记资源元数据。`attendance` 会将参会者展开为带加入/离开时间戳的参会者会话行。这些命令仅使用 Meet REST API；转录或智能笔记文档正文下载被有意排除在范围之外，因为那需要额外的 Google Docs/Drive 访问权限。
`artifacts` 会在 Google 为该会议暴露这些资源时，返回会议记录元数据，以及参与者、录音、转录、结构化 transcript-entry 和智能笔记资源元数据。对于大型会议，可使用 `--no-transcript-entries` 跳过条目查询。`attendance` 会将参与者展开为 participant-session 行，并附带加入/离开时间戳。这些命令仅使用 Meet REST API；Google Docs/Drive 文档正文下载被明确排除在范围之外，因为那需要单独的 Google Docs/Drive 访问权限。
创建一个新的 Meet 空间：
@ -412,9 +547,9 @@ openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --js
openclaw googlemeet create
```
该命令会输出新的 `meeting uri`、来源和加入会话。有 OAuth 凭证时，它会使用官方 Google Meet API。没有 OAuth 凭证时，它会回退为使用固定的 Chrome 节点上已登录的浏览器配置文件。智能体可以使用 `google_meet` 工具，并设置 `action: "create"`，一步完成创建和加入。若只想创建 URL，请传入 `"join": false`。
该命令会输出新的 `meeting uri`、来源以及加入会话。使用 OAuth 凭证时，它会使用官方 Google Meet API。没有 OAuth 凭证时，它会回退为使用固定的 Chrome 节点上已登录的浏览器配置文件。智能体可以使用 `google_meet` 工具并设置 `action: "create"`，以一步完成创建和加入。若仅创建 URL，请传入 `"join": false`。
来自浏览器回退的 JSON 输出示例：
浏览器回退的 JSON 输出示例：
```json
{
@ -434,7 +569,7 @@ openclaw googlemeet create
}
```
如果浏览器回退在创建 URL 之前遇到 Google 登录或 Meet 权限阻塞，Gateway 网关方法会返回失败响应，`google_meet` 工具也会返回结构化细节，而不是普通字符串：
如果浏览器回退在创建 URL 之前遇到 Google 登录或 Meet 权限阻塞，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化详情，而不是普通字符串：
```json
{
@ -452,9 +587,9 @@ openclaw googlemeet create
}
```
当智能体看到 `manualActionRequired: true` 时，它应报告 `manualActionMessage`，再加上浏览器节点/标签页上下文，并停止继续打开新的 Meet 标签页，直到操作员完成浏览器步骤。
当智能体看到 `manualActionRequired: true` 时，它应报告 `manualActionMessage`，再加上浏览器节点/标签页上下文，并停止打开新的 Meet 标签页，直到操作员完成该浏览器步骤。
来自 API 创建的 JSON 输出示例：
API 创建的 JSON 输出示例：
```json
{
@ -475,13 +610,13 @@ openclaw googlemeet create
}
```
创建 Meet 默认会直接加入。Chrome 或 Chrome-node 传输仍然需要一个已登录 Google 的 Chrome 配置文件，才能通过浏览器加入。如果该配置文件已退出登录，OpenClaw 会报告 `manualActionRequired: true` 或浏览器回退错误，并要求操作员先完成 Google 登录后再重试。
创建 Meet 默认会自动加入。`chrome` 或 `chrome-node` 传输方式仍然需要一个已登录 Google 的 Chrome 配置文件才能通过浏览器加入。如果该配置文件已退出登录，OpenClaw 会报告 `manualActionRequired: true` 或浏览器回退错误，并要求操作员先完成 Google 登录再重试。
只有在确认你的 Cloud 项目、OAuth 主体和会议参与者都已加入 Google Workspace Developer Preview Program for Meet media APIs 之后，才设置 `preview.enrollmentAcknowledged: true`。
仅在确认你的 Cloud 项目、OAuth 主体以及会议参与者都已加入用于 Meet 媒体 API 的 Google Workspace Developer Preview Program 后，才将 `preview.enrollmentAcknowledged: true` 设置为 true。
## 配置
常见的 Chrome 实时路径只需要启用该插件、安装 BlackHole、SoX，以及一个后端实时语音提供商密钥。OpenAI 是默认选项；设置 `realtime.provider: "google"` 可使用 Google Gemini Live：
常见的 Chrome 实时路径只需要启用插件、安装 BlackHole、SoX，以及一个后端实时语音提供商密钥。OpenAI 是默认项；设置 `realtime.provider: "google"` 可使用 Google Gemini Live：
```bash
brew install blackhole-2ch sox
@ -509,18 +644,18 @@ export GEMINI_API_KEY=...
- `defaultTransport: "chrome"`
- `defaultMode: "realtime"`
- `chromeNode.node`：`chrome-node` 的可选节点 id/名称/IP
- `chromeNode.node`：用于 `chrome-node` 的可选节点 id/名称/IP
- `chrome.audioBackend: "blackhole-2ch"`
- `chrome.guestName: "OpenClaw Agent"`：在已退出登录的 Meet 访客页面上使用的名称
- `chrome.autoJoin: true`：通过 OpenClaw 浏览器自动化在 `chrome-node` 上尽力填写访客名并点击立即加入
- `chrome.guestName: "OpenClaw Agent"`：在已退出登录的 Meet 访客界面上使用的名称
- `chrome.autoJoin: true`：通过 OpenClaw 浏览器自动化，在 `chrome-node` 上尽力填写访客名称并点击 Join Now
- `chrome.reuseExistingTab: true`：激活现有 Meet 标签页，而不是打开重复标签页
- `chrome.waitForInCallMs: 20000`：在触发实时介绍之前，等待 Meet 标签页报告已在通话中
- `chrome.audioInputCommand`：SoX `rec` 命令，将 8 kHz G.711 mu-law 音频写入 stdout
- `chrome.audioOutputCommand`：SoX `play` 命令，从 stdin 读取 8 kHz G.711 mu-law 音频
- `chrome.waitForInCallMs: 20000`：等待 Meet 标签页报告已在通话中，然后再触发实时介绍
- `chrome.audioInputCommand`：将 8 kHz G.711 mu-law 音频写入 stdout 的 SoX `rec` 命令
- `chrome.audioOutputCommand`：从 stdin 读取 8 kHz G.711 mu-law 音频的 SoX `play` 命令
- `realtime.provider: "openai"`
- `realtime.toolPolicy: "safe-read-only"`
- `realtime.instructions`：简短口头回复；更深入的回答使用 `openclaw_agent_consult`
- `realtime.introMessage`：实时桥接连接时的简短口头就绪检查；将其设为 `""` 可静默加入
- `realtime.instructions`：简短的语音回复，并在需要更深入回答时使用 `openclaw_agent_consult`
- `realtime.introMessage`：当实时桥接连接时的简短语音就绪检查；将其设为 `""` 可静默加入
可选覆盖项：
@ -566,7 +701,7 @@ export GEMINI_API_KEY=...
}
```
`voiceCall.enabled` 默认值为 `true`；在使用 Twilio 传输时，它会将实际的 PSTN 呼叫和 DTMF 委派给 Voice Call 插件。如果未启用 `voice-call`，Google Meet 仍然可以验证并记录拨号计划，但无法发起 Twilio 呼叫。
`voiceCall.enabled` 默认为 `true`；使用 Twilio 传输方式时，它会将实际的 PSTN 通话和 DTMF 委派给 Voice Call 插件。如果 `voice-call` 未启用，Google Meet 仍然可以验证并记录拨号计划，但无法发起 Twilio 通话。
## 工具
@ -581,17 +716,17 @@ export GEMINI_API_KEY=...
}
```
当 Chrome 运行在 Gateway 网关主机上时，使用 `transport: "chrome"`。当 Chrome 运行在已配对节点（如 Parallels VM）上时，使用 `transport: "chrome-node"`。在这两种情况下，实时模型和 `openclaw_agent_consult` 都运行在 Gateway 网关主机上，因此模型凭证会保留在那里。
当 Chrome 运行在 Gateway 网关主机上时，使用 `transport: "chrome"`。当 Chrome 运行在已配对节点上（例如 Parallels VM）时，使用 `transport: "chrome-node"`。在这两种情况下，实时模型和 `openclaw_agent_consult` 都运行在 Gateway 网关主机上，因此模型凭证保留在那里。
使用 `action: "status"` 可列出活动会话或检查某个会话 ID。使用 `action: "speak"` 并提供 `sessionId` 和 `message`，可让实时智能体立即发言。使用 `action: "test_speech"` 可创建或复用该会话、触发一段已知短语，并在 Chrome 主机能够上报时返回 `inCall` 健康状态。使用 `action: "leave"` 可将某个会话标记为已结束。
使用 `action: "status"` 列出活动会话或检查某个会话 ID。使用 `action: "speak"` 并传入 `sessionId` 和 `message`，让实时智能体立即发声。使用 `action: "test_speech"` 创建或复用会话、触发一段已知短语，并在 Chrome 主机可报告时返回 `inCall` 健康状态。使用 `action: "leave"` 将会话标记为已结束。
`status` 在可用时包含 Chrome 健康状态：
`status` 在可用时包含 Chrome 健康信息：
- `inCall`：Chrome 看起来已经进入 Meet 通话
- `inCall`：Chrome 看起来已进入 Meet 通话
- `micMuted`：尽力检测的 Meet 麦克风状态
- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：在语音功能可用之前，浏览器配置文件需要手动登录、Meet 主持人准入、权限授予，或浏览器控制修复
- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人准入、权限授予，或浏览器控制修复，语音功能才能正常工作
- `providerConnected` / `realtimeReady`：实时语音桥接状态
- `lastInputAt` / `lastOutputAt`：桥接最近一次接收或发送音频的时间
- `lastInputAt` / `lastOutputAt`：桥接最近一次接收/发送音频的时间
```json
{
@ -601,27 +736,27 @@ export GEMINI_API_KEY=...
}
```
## 实时智能体咨询
## 实时智能体 consult
Chrome 实时模式针对实时语音回路进行了优化。实时语音提供商会听取会议音频，并通过已配置的音频桥接发声。当实时模型需要更深入的推理、当前信息或常规 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。
Chrome 实时模式针对实时语音循环进行了优化。实时语音提供商会听取会议音频，并通过已配置的音频桥接发声。当实时模型需要更深入的推理、最新信息或常规 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。
咨询工具会在后台运行常规 OpenClaw 智能体，附带最近的会议转录上下文，并向实时语音会话返回简洁的口头回答。随后语音模型可以将该回答再说回会议中。它使用与 Voice Call 相同的共享实时咨询工具。
consult 工具会在后台运行常规 OpenClaw 智能体，附带最近的会议转录上下文，并向实时语音会话返回简洁的口语化回答。随后语音模型可以将该回答说回会议中。它使用与 Voice Call 相同的共享实时 consult 工具。
`realtime.toolPolicy` 控制咨询运行方式：
`realtime.toolPolicy` 控制 consult 运行方式：
- `safe-read-only`：暴露咨询工具，并将常规智能体限制为只能使用 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。
- `owner`：暴露咨询工具，并让常规智能体使用正常的智能体工具策略。
- `none`：不向实时语音模型暴露咨询工具。
- `safe-read-only`：暴露 consult 工具，并将常规智能体限制为使用 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`
- `owner`：暴露 consult 工具，并允许常规智能体使用正常的智能体工具策略
- `none`：不向实时语音模型暴露 consult 工具
咨询会话键按每个 Meet 会话进行作用域隔离，因此在同一场会议期间，后续咨询调用可以复用之前的咨询上下文。
consult 会话键按每个 Meet 会话进行作用域隔离，因此在同一场会议期间，后续 consult 调用可以复用之前的 consult 上下文。
要在 Chrome 完全加入通话后强制执行一次口头就绪检查：
如需在 Chrome 完全加入通话后强制执行一次语音就绪检查：
```bash
openclaw googlemeet speak meet_... "Say exactly: I'm here and listening."
```
执行完整的加入并发言冒烟测试：
完整的加入并发声冒烟测试：
```bash
openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
@ -629,9 +764,9 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
--message "Say exactly: I'm here and listening."
```
## 实时测试检查清单
## 现场测试检查清单
在将会议交给无人值守的智能体之前，请使用以下顺序：
在将会议交给无人值守的智能体之前，使用以下流程：
```bash
openclaw googlemeet setup
@ -641,15 +776,15 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
--message "Say exactly: Google Meet speech test complete."
```
预期的 Chrome-node 状态：
预期的 `chrome-node` 状态：
- `googlemeet setup` 全部为绿色。
- 当 `chrome-node` 是默认传输方式或已固定某个节点时，`googlemeet setup` 包含 `chrome-node-connected`。
- 当 `chrome-node` 是默认传输方式或节点已固定时，`googlemeet setup` 包含 `chrome-node-connected`。
- `nodes status` 显示所选节点已连接。
- 所选节点同时广播 `googlemeet.chrome` 和 `browser.proxy`。
- Meet 标签页加入通话，且 `test-speech` 返回的 Chrome 健康状态中 `inCall: true`。
- Meet 标签页加入通话，且 `test-speech` 返回带有 `inCall: true` 的 Chrome 健康状态。
对于远程 Chrome 主机，例如 Parallels macOS VM，在更新 Gateway 网关或 VM 之后，最短且安全的检查如下：
对于远程 Chrome 主机（例如 Parallels macOS VM），在更新 Gateway 网关或 VM 后，这是最短且安全的检查方式：
```bash
openclaw googlemeet setup
@ -660,9 +795,9 @@ openclaw nodes invoke \
--params '{"action":"setup"}'
```
这可以证明 Gateway 网关插件已加载、VM 节点已使用当前令牌连接，并且 Meet 音频桥接可用，然后智能体才会打开真实的会议标签页。
这可以证明 Gateway 网关插件已加载、VM 节点已使用当前令牌连接，并且 Meet 音频桥接在智能体打开真实会议标签页之前可用。
对于 Twilio 冒烟测试，请使用一个已暴露电话拨入详情的会议：
对于 Twilio 冒烟测试，请使用一个会暴露电话拨入详情的会议：
```bash
openclaw googlemeet setup
@ -674,24 +809,23 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \
预期的 Twilio 状态：
- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查项。
- Gateway 网关重新加载后，CLI 中可以使用 `voicecall`。
- 返回的会话带有 `transport: "twilio"` 和 `twilio.voiceCallId`。
- `googlemeet leave <sessionId>` 会挂断委派出去的语音呼叫。
- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。
- Gateway 网关重新加载后，CLI 中可用 `voicecall`。
- 返回的会话包含 `transport: "twilio"` 和 `twilio.voiceCallId`。
- `googlemeet leave <sessionId>` 会挂断被委派的语音呼叫。
## 故障排除
### 智能体看不到 Google Meet 工具
确认该插件已在 Gateway 网关配置中启用，并重新加载 Gateway 网关：
确认插件已在 Gateway 网关配置中启用，并重新加载 Gateway 网关：
```bash
openclaw plugins list | grep google-meet
openclaw googlemeet setup
```
如果你刚刚编辑了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。
正在运行的智能体只能看到由当前 Gateway 网关进程注册的插件工具。
如果你刚刚编辑了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。正在运行的智能体只能看到由当前 Gateway 网关进程注册的插件工具。
### 没有已连接的具备 Google Meet 能力的节点
@ -704,7 +838,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
openclaw node run --host <gateway-lan-ip> --port 18789 --display-name parallels-macos
```
在 Gateway 网关主机上，批准该节点并验证命令：
在 Gateway 网关主机上，批准节点并验证命令：
```bash
openclaw devices list
@ -712,8 +846,7 @@ openclaw devices approve <requestId>
openclaw nodes status
```
该节点必须已连接，并列出 `googlemeet.chrome` 和 `browser.proxy`。
Gateway 网关配置必须允许这些节点命令：
该节点必须已连接，并列出 `googlemeet.chrome` 和 `browser.proxy`。Gateway 网关配置必须允许这些节点命令：
```json5
{
@ -725,8 +858,7 @@ Gateway 网关配置必须允许这些节点命令：
}
```
如果 `googlemeet setup` 中的 `chrome-node-connected` 失败，或者 Gateway 网关日志报告
`gateway token mismatch`，请使用当前 Gateway 网关令牌重新安装或重启该节点。对于局域网 Gateway 网关，这通常意味着：
如果 `googlemeet setup` 的 `chrome-node-connected` 检查失败，或者 Gateway 网关日志报告 `gateway token mismatch`，请使用当前 Gateway 网关令牌重新安装或重启节点。对于局域网 Gateway 网关，通常意味着：
```bash
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
@ -737,7 +869,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
--force
```
然后重新加载节点服务，并再次运行：
然后重新加载节点服务并再次运行：
```bash
openclaw googlemeet setup
@ -746,31 +878,30 @@ openclaw nodes status --connected
### 浏览器已打开，但智能体无法加入
运行 `googlemeet test-speech` 并检查返回的 Chrome 健康状态。如果其中报告 `manualActionRequired: true`，请向操作员展示 `manualActionMessage`，并在浏览器操作完成前停止重试。
运行 `googlemeet test-speech` 并检查返回的 Chrome 健康状态。如果它报告 `manualActionRequired: true`，请向操作员展示 `manualActionMessage`，并在浏览器操作完成前停止重试。
常见手动操作：
- 登录 Chrome 配置文件。
- 从 Meet 主持人账户批准访客加入。
- 当 Chrome 原生权限提示出现时，授予 Chrome 麦克风/摄像头权限。
- 从 Meet 主持人账号批准访客加入。
- 当出现 Chrome 原生权限提示时，授予 Chrome 麦克风/摄像头权限。
- 关闭或修复卡住的 Meet 权限对话框。
不要仅仅因为 Meet 显示 “Do you want people to hear you in the meeting?” 就报告“未登录”。这是 Meet 的音频选择中间页；OpenClaw 会在可用时通过浏览器自动化点击 **Use microphone**，并继续等待真正的会议状态。对于仅创建 URL 的浏览器回退，由于创建 URL 不需要实时音频路径，OpenClaw 可能会点击 **Continue without microphone**。
不要仅因为 Meet 显示 “Do you want people to hear you in the meeting?” 就报告“未登录”。那是 Meet 的音频选择过渡界面；在可用时，OpenClaw 会通过浏览器自动化点击 **Use microphone**，并继续等待真实会议状态。对于仅创建 URL 的浏览器回退，OpenClaw 可能会点击 **Continue without microphone**，因为创建 URL 不需要实时音频路径。
### 会议创建失败
当配置了 OAuth 凭证时，`googlemeet create` 会优先使用 Google Meet API 的 `spaces.create` 端点。
没有 OAuth 凭证时，它会回退到固定的 Chrome 节点浏览器。请确认：
当配置了 OAuth 凭证时，`googlemeet create` 会首先使用 Google Meet API 的 `spaces.create` 端点。没有 OAuth 凭证时，它会回退到固定的 Chrome 节点浏览器。请确认：
- 对于 API 创建：已配置 `oauth.clientId` 和 `oauth.refreshToken`，或存在对应的 `OPENCLAW_GOOGLE_MEET_*` 环境变量。
- 对于 API 创建：刷新令牌是在支持创建功能加入之后生成的。较旧的令牌可能缺少 `meetings.space.created` scope；请重新运行 `openclaw googlemeet auth login --json` 并更新插件配置。
- 对于浏览器回退：`defaultTransport: "chrome-node"` 且 `chromeNode.node` 指向一个已连接、同时具备 `browser.proxy` 和 `googlemeet.chrome` 的节点。
- 对于 API 创建：已配置 `oauth.clientId` 和 `oauth.refreshToken`，或存在匹配的 `OPENCLAW_GOOGLE_MEET_*` 环境变量。
- 对于 API 创建：refresh token 是在添加创建支持之后生成的。较旧的令牌可能缺少 `meetings.space.created` 作用域；请重新运行 `openclaw googlemeet auth login --json` 并更新插件配置。
- 对于浏览器回退：`defaultTransport: "chrome-node"` 和 `chromeNode.node` 指向一个已连接节点，该节点具有 `browser.proxy` 和 `googlemeet.chrome`。
- 对于浏览器回退：该节点上的 OpenClaw Chrome 配置文件已登录 Google，并且可以打开 `https://meet.google.com/new`。
- 对于浏览器回退：重试会复用现有的 `https://meet.google.com/new` 或 Google 账户提示标签页，而不是打开新标签页。如果智能体超时，请重试工具调用，而不是手动再打开一个 Meet 标签页。
- 对于浏览器回退：如果工具返回 `manualActionRequired: true`，请使用返回的 `browser.nodeId`、`browser.targetId`、`browserUrl` 和 `manualActionMessage` 来指导操作员。在该操作完成之前，不要循环重试。
- 对于浏览器回退：如果 Meet 显示 “Do you want people to hear you in the meeting?”，请保持该标签页打开。OpenClaw 应通过浏览器自动化点击 **Use microphone**，或者在仅创建 URL 的回退中点击 **Continue without microphone**，并继续等待生成的 Meet URL。如果它做不到，错误应提及 `meet-audio-choice-required`，而不是 `google-login-required`。
- 对于浏览器回退：重试会在打开新标签页之前复用现有的 `https://meet.google.com/new` 或 Google 账号提示标签页。如果智能体超时，请重试工具调用，而不是手动再打开一个 Meet 标签页。
- 对于浏览器回退：如果工具返回 `manualActionRequired: true`，请使用返回的 `browser.nodeId`、`browser.targetId`、`browserUrl` 和 `manualActionMessage` 来引导操作员。在该操作完成之前，不要循环重试。
- 对于浏览器回退：如果 Meet 显示 “Do you want people to hear you in the meeting?”，请保持该标签页打开。OpenClaw 应通过浏览器自动化点击 **Use microphone**，或者在仅创建的回退场景下点击 **Continue without microphone**，然后继续等待生成的 Meet URL。如果无法做到，错误中应提到 `meet-audio-choice-required`，而不是 `google-login-required`。
### 智能体已加入，但不说话
### 智能体已加入但不说话
检查实时路径：
@ -779,33 +910,32 @@ openclaw googlemeet setup
openclaw googlemeet doctor
```
要进行收听/回话，请使用 `mode: "realtime"`。`mode: "transcribe"` 按设计不会启动双工实时语音桥接。
使用 `mode: "realtime"` 进行收听/回话。`mode: "transcribe"` 按设计不会启动双工实时语音桥接。
还要验证：
- Gateway 网关主机上存在实时提供商密钥，例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。
- Chrome 主机上可见 `BlackHole 2ch`。
- Gateway 网关主机上有可用的实时提供商密钥，例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。
- Chrome 主机上可以看到 `BlackHole 2ch`。
- Chrome 主机上存在 `rec` 和 `play`。
- Meet 麦克风和扬声器已通过 OpenClaw 使用的虚拟音频路径进行路由。
- Meet 的麦克风和扬声器已通过 OpenClaw 使用的虚拟音频路径进行路由。
`googlemeet doctor [session-id]` 会输出会话、节点、通话中状态、手动操作原因、实时提供商连接、`realtimeReady`、音频输入/输出活动、最近音频时间戳、字节计数以及浏览器 URL。
当你需要原始 JSON 时，请使用 `googlemeet status [session-id]`。
`googlemeet doctor [session-id]` 会输出会话、节点、通话中状态、手动操作原因、实时提供商连接状态、`realtimeReady`、音频输入/输出活动、最近音频时间戳、字节计数和浏览器 URL。当你需要原始 JSON 时，请使用 `googlemeet status [session-id]`。当你需要在不暴露令牌的情况下验证 Google Meet OAuth 刷新时，请使用 `googlemeet doctor --oauth`；如果还需要 Google Meet API 证明，请添加 `--meeting` 或 `--create-space`。
如果智能体超时，而你能看到一个已经打开的 Meet 标签页，请在不打开另一个标签页的情况下检查该标签页：
如果智能体超时，而你已经看到有 Meet 标签页处于打开状态，请在不再打开另一个标签页的情况下检查该标签页：
```bash
openclaw googlemeet recover-tab
openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij
```
对应的工具动作是 `recover_current_tab`。它会在已配置的 Chrome 节点上聚焦并检查现有 Meet 标签页。它不会打开新标签页，也不会创建新会话；它会报告当前阻塞项，例如登录、准入、权限或音频选择状态。CLI 命令会与已配置的 Gateway 网关通信，因此 Gateway 网关必须正在运行，且 Chrome 节点必须已连接。
等效的工具操作是 `recover_current_tab`。它会聚焦并检查配置的 Chrome 节点上现有的 Meet 标签页。它不会打开新标签页，也不会创建新会话；它会报告当前阻塞项，例如登录、准入、权限或音频选择状态。CLI 命令会与已配置的 Gateway 网关通信，因此 Gateway 网关必须正在运行，且 Chrome 节点必须已连接。
### Twilio 设置检查失败
当 `voice-call` 未被允许或未启用时，`twilio-voice-call-plugin` 会失败。
将其添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，然后重新加载 Gateway 网关。
请将其添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，然后重新加载 Gateway 网关。
当 Twilio 后端缺少 account SID、auth token 或主叫号码时，`twilio-voice-call-credentials` 会失败。请在 Gateway 网关主机上设置这些值：
当 Twilio 后端缺少 account SID、auth token 或 caller number 时，`twilio-voice-call-credentials` 会失败。请在 Gateway 网关主机上设置这些值：
```bash
export TWILIO_ACCOUNT_SID=AC...
@ -821,13 +951,13 @@ openclaw voicecall setup
openclaw voicecall smoke
```
默认情况下，`voicecall smoke` 仅进行就绪性检查。若要对某个具体号码执行 dry-run：
`voicecall smoke` 默认仅进行就绪性检查。若要对某个特定号码进行 dry-run：
```bash
openclaw voicecall smoke --to "+15555550123"
```
只有在你确实想发起真实的外呼通知电话时，才加上 `--yes`：
只有在你明确想发起真实的外呼通知电话时，才添加 `--yes`：
```bash
openclaw voicecall smoke --to "+15555550123" --yes
@ -835,7 +965,7 @@ openclaw voicecall smoke --to "+15555550123" --yes
### Twilio 呼叫已开始，但始终未进入会议
确认 Meet 事件暴露了电话拨入详情。传入准确的拨入号码和 PIN，或自定义 DTMF 序列：
确认 Meet 事件暴露了电话拨入详情。传入精确的拨入号码和 PIN，或自定义 DTMF 序列：
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij \
@ -844,23 +974,23 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \
--dtmf-sequence ww123456#
```
如果提供商在输入 PIN 之前需要暂停，请在 `--dtmf-sequence` 中使用前导 `w` 或逗号。
如果提供商在输入 PIN 前需要暂停，请在 `--dtmf-sequence` 中使用前导 `w` 或逗号。
## 说明
Google Meet 的官方媒体 API 偏向接收，因此向 Meet 通话中发声仍然需要一个参会者路径。该插件将这一边界保持得很清晰：Chrome 负责浏览器参会和本地音频路由；Twilio 负责电话拨入参会。
Google Meet 的官方媒体 API 偏向接收方向，因此向 Meet 通话中发声仍然需要一个参会者路径。该插件将这一边界保持为可见：Chrome 负责浏览器参会和本地音频路由；Twilio 负责电话拨入参会。
Chrome 实时模式需要以下两种之一：
Chrome 实时模式需要以下之一：
- `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 拥有实时模型桥接，并在这些命令与所选实时语音提供商之间传输 8 kHz G.711 mu-law 音频。
- `chrome.audioBridgeCommand`：一个外部桥接命令拥有完整的本地音频路径，并且必须在启动或验证其守护进程后退出。
- `chrome.audioBridgeCommand`：一个外部桥接命令拥有整个本地音频路径，并且必须在启动或验证其守护进程后退出。
为了获得干净的双工音频，请将 Meet 输出和 Meet 麦克风分别路由到独立的虚拟设备，或使用类似 Loopback 的虚拟设备图。单个共享的 BlackHole 设备可能会把其他参会者的声音回传到通话中。
为了获得干净的双工音频，请将 Meet 输出和 Meet 麦克风路由到独立的虚拟设备，或使用类似 Loopback 的虚拟设备图。单个共享的 BlackHole 设备可能会将其他参会者的声音回送进通话。
`googlemeet speak` 会触发 Chrome 会话的活动实时音频桥接。`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委派的 Twilio 会话，`leave` 还会挂断底层语音呼叫。
## 相关内容
- [Voice call plugin](/zh-CN/plugins/voice-call)
- [Talk mode](/zh-CN/nodes/talk)
- [Voice call 插件](/zh-CN/plugins/voice-call)
- [Talk 模式](/zh-CN/nodes/talk)
- [构建插件](/zh-CN/plugins/building-plugins)