From a02caac2d2efa4fcdc3e68a7e4bfb03ca7dac89f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 06:55:27 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/mcp.md | 185 +++--- docs/zh-CN/cli/models.md | 118 ++-- docs/zh-CN/concepts/model-providers.md | 260 ++++---- docs/zh-CN/gateway/cli-backends.md | 185 +++--- docs/zh-CN/gateway/config-tools.md | 182 +++--- docs/zh-CN/gateway/configuration-reference.md | 593 ++++++++++-------- docs/zh-CN/plugins/google-meet.md | 446 ++++++++----- 7 files changed, 1104 insertions(+), 865 deletions(-) diff --git a/docs/zh-CN/cli/mcp.md b/docs/zh-CN/cli/mcp.md index 6cf31330e..98600bd0f 100644 --- a/docs/zh-CN/cli/mcp.md +++ b/docs/zh-CN/cli/mcp.md @@ -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 `：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` 仅包含桥接器连接期间观察到的审批 ## 相关内容 diff --git a/docs/zh-CN/cli/models.md b/docs/zh-CN/cli/models.md index 34da2af7e..1ca5cfc9a 100644 --- a/docs/zh-CN/cli/models.md +++ b/docs/zh-CN/cli/models.md @@ -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 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 ` 可检查某个已配置智能体的模型/认证状态。省略时， -该命令会在设置了 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` 时使用它们，否则使用 -已配置的默认智能体。 -探测行可能来自认证配置文件、环境变量凭证或 `models.json`。 +概览，而 `auth.oauth` 仅是身份验证存储中配置文件健康状态。 +添加 `--probe` 可对每个已配置的提供商配置文件运行实时身份验证探测。 +探测会发出真实请求（可能消耗令牌并触发速率限制）。 +使用 `--agent ` 可检查某个已配置智能体的模型/身份验证状态。省略时， +该命令会在设置了 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` 时使用它们， +否则使用已配置的默认智能体。 +探测行可能来自身份验证配置文件、环境变量凭证或 `models.json`。 说明： - `models set ` 接受 `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 过滤，例如 `moonshot` 或 - `openai-codex`。它不接受交互式提供商选择器中的显示标签，例如 `Moonshot AI`。 + `openai-codex`。它不接受交互式提供商 + 选择器中的显示标签，例如 `Moonshot AI`。 - 模型引用通过按**第一个** `/` 进行拆分来解析。如果模型 ID 包含 `/`（OpenRouter 风格），请包含提供商前缀（例如：`openrouter/moonshotai/kimi-k2`）。 -- 如果你省略了提供商，OpenClaw 会先将输入解析为别名，然后 - 解析为对该精确模型 id 的唯一已配置提供商匹配，最后才会回退到已配置的默认提供商，并显示弃用警告。 - 如果该提供商不再公开已配置的默认模型，OpenClaw - 会回退到第一个已配置的提供商/模型，而不是暴露一个 - 已删除提供商的陈旧默认值。 -- `models status` 可能会在认证输出中显示 `marker()`，用于表示非秘密占位符（例如 `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`），而不是将它们作为秘密值进行掩码。 +- 如果你省略提供商，OpenClaw 会先将输入解析为别名，然后 + 解析为精确匹配该模型 id 的唯一已配置提供商，最后才 + 以弃用警告的方式回退到已配置的默认提供商。 + 如果该提供商不再暴露已配置的默认模型，OpenClaw + 会回退到第一个已配置的提供商/模型，而不是显示一个 + 过时的、已移除提供商默认值。 +- `models status` 可能会在身份验证输出中显示 `marker()`，用于表示非机密占位符（例如 `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 `（探测单个提供商） -- `--probe-profile `（可重复传入或使用逗号分隔的配置文件 id） +- `--probe-profile `（可重复使用，或使用逗号分隔的配置文件 id） - `--probe-timeout ` - `--probe-concurrency ` - `--probe-max-tokens ` -- `--agent `（已配置的智能体 id；会覆盖 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`） +- `--agent `（已配置的智能体 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.` 未包含它，因此探测会报告该排除情况，而不是 +- `excluded_by_auth_order`：存在已存储的配置文件，但显式 + `auth.order.` 省略了它，因此探测会报告该排除，而不是 尝试使用它。 - `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 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 `:manual`，除非你传入 `--profile-id`。 -- `paste-token --expires-in ` 会根据相对时长（例如 `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 ` 会根据相对时长存储一个绝对令牌过期时间，例如 + `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) diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index d0ecf5292..593e8abad 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -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 `。 -- `models.providers.*.models[].contextWindow` 是原生模型元数据；`contextTokens` 是运行时生效的上限。 -- 回退规则、冷却探测和会话覆盖持久化：参见 [模型故障转移](/zh-CN/concepts/model-failover)。 -- OpenAI 系列路由按前缀区分：`openai/` 在 PI 中使用直接的 OpenAI API 密钥提供商，`openai-codex/` 在 PI 中使用 Codex OAuth，而 `openai/` 加上 `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/` 属于 OpenAI 插件，而 Codex 插件则通过 `embeddedHarness.runtime: "codex"` 或旧版 `codex/` 引用启用。 -- 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/` 使用 PI 中基于直接 OpenAI API 密钥的 provider，`openai-codex/` 使用 PI 中的 Codex OAuth，而 `openai/` 加上 `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/` 属于 OpenAI 插件，而 Codex 插件由 `embeddedHarness.runtime: "codex"` 或旧版 `codex/` 引用启用。 +- 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 需要完全自定义的请求执行器，那将属于另一个更深层的扩展接口。 -provider 运行时 `capabilities` 是共享运行器元数据（provider 家族、转录/工具特性、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。 +provider 运行时 `capabilities` 是共享运行器元数据（provider 系列、转录/工具使用特殊行为、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么（文本推理、语音等）。 ## API 密钥轮换 -- 支持所选提供商的通用提供商轮换。 +- 对选定的 provider 支持通用 provider 轮换。 - 可通过以下方式配置多个密钥： - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） - - `_API_KEYS`（逗号或分号分隔列表） + - `_API_KEYS`（逗号或分号分隔的列表） - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_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/"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- 可按模型通过 `agents.defaults.models["openai/"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`） - OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`） - OpenAI 优先级处理可通过 `agents.defaults.models["openai/"].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/"].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/"].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/"].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/"].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/"].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/"].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.` 条目。 +下面许多内置 provider 插件已经发布了默认目录。 +只有当你想覆盖默认 Base URL、请求头或模型列表时，才需要显式使用 +`models.providers.` 条目。 ### 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 分类的设置指南 diff --git a/docs/zh-CN/gateway/cli-backends.md b/docs/zh-CN/gateway/cli-backends.md index dd8634284..1af112618 100644 --- a/docs/zh-CN/gateway/cli-backends.md +++ b/docs/zh-CN/gateway/cli-backends.md @@ -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 会成为你的模型引用左侧部分： ``` / @@ -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 会话。 -内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，再次允许 OpenClaw 风格的 Claude CLI 用法，因此除非 Anthropic 发布新的策略，否则 OpenClaw 会将此集成中的 `claude -p` 用法视为已获认可。 +内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，允许使用 OpenClaw 风格的 Claude CLI，因此除非 Anthropic 发布新的策略，否则 OpenClaw 会将 `claude -p` 的用法视为该集成的受认可方式。 内置的 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.` 中的配置仍会覆盖插件默认值。 -- 后端特定的配置清理仍由插件通过可选的 `normalizeConfig` 钩子负责。 +- 后端的 `id` 会成为模型引用中的提供商前缀。 +- `agents.defaults.cliBackends.` 中的用户配置仍会覆盖插件默认值。 +- 后端特定的配置清理由插件通过可选的 + `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 支持文件路径）。 ## 相关内容 diff --git a/docs/zh-CN/gateway/config-tools.md b/docs/zh-CN/gateway/config-tools.md index 1d68c0775..7c821d582 100644 --- a/docs/zh-CN/gateway/config-tools.md +++ b/docs/zh-CN/gateway/config-tools.md @@ -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` （旧版请求者会话唤醒 / 模型投递路径）。 @@ -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//`，并附带一个 `.manifest.json`。 +- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 +- 文件会被实体化到子工作区的 `.openclaw/attachments//` 中，并带有一个 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会通过严格的字母表 / 填充检查以及解码前大小保护进行验证。 -- 目录和文件权限分别为 `0700` 和 `0600`。 -- 清理由 `cleanup` 策略控制：`delete` 总是会删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 +- Base64 输入会使用严格的字母表 / 填充校验，以及解码前大小保护进行验证。 +- 目录文件权限为 `0700`，文件权限为 `0600`。 +- 清理遵循 `cleanup` 策略：`delete` 总是删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留它们。 ### `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. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge`。除非你传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 + - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --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`。 @@ -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`。 @@ -506,7 +506,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 - 通用端点：`https://api.z.ai/api/paas/v4` - 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` -- 对于通用端点，定义一个自定义提供商并覆盖基础 URL。 +- 对于通用端点，请定义一个覆盖基础 URL 的自定义提供商。 @@ -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 本身来处理这一点。 @@ -571,7 +571,7 @@ OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 - + ```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`。 @@ -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` 或 -参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在较强硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在性能足够强的硬件上，通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 @@ -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) diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index e8276838d..56151e3d4 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -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..enabled: false`：即使某个 Skill 已内置 / 已安装，也会禁用它。 +- `install.preferBrew`：为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 +- `install.nodeManager`：用于 `metadata.openclaw.install` + 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使 Skill 已内置 / 已安装，也会禁用该 Skill。 - `entries..apiKey`：为声明了主环境变量的 Skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 --- @@ -117,44 +155,44 @@ provider / base-URL 设置已移至专用页面——请参阅 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 发现机制接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。 -- **配置变更需要重启 gateway。** -- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（当插件支持时）。 -- `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的 bundle 提供钩子目录。 +- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex 包和 Claude 包，包括无 manifest 的 Claude 默认布局包。 +- **配置更改需要重启 Gateway 网关。** +- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。 +- `plugins.entries..apiKey`：插件级 API 密钥便捷字段（插件支持时可用）。 +- `plugins.entries..env`：插件范围的环境变量映射。 +- `plugins.entries..hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的包提供钩子目录。 - `plugins.entries..hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可以从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始对话内容。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件，使其可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你明确要允许任意模型时才使用 `"*"`。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件可以为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你确实想允许任意模型时才使用 `"*"`。 - `plugins.entries..config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。 -- 渠道插件的账号 / 运行时设置位于 `channels.` 下，应由所属插件的 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.` 下，应由所属插件的 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 设置已移至专用页面——请参阅 } ``` - + -- `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..healthMonitor.enabled`：按渠道禁用健康监控重启，同时保留全局监控启用。 -- `channels..accounts..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..healthMonitor.enabled`：在保持全局监控启用的情况下，按渠道选择退出健康监控重启。 +- `channels..accounts..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 拒绝列表中移除工具名称。 ### 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 `（使用 `~/.openclaw-`）。 -请参阅[多个 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 ` 或 `x-openclaw-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/` → 通过 `hooks.mappings` 解析 - - 通过模板渲染得到的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 + - 经过模板渲染的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 - `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（如果设置了模型目录，则必须被允许）。 ### 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://:/__openclaw__/canvas/` - `http://:/__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 存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持静态凭证模式的值级 ref（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 -- OAuth 模式 profile（`auth.profiles..mode = "oauth"`）不支持基于 SecretRef 的 auth-profile 凭证。 -- 静态运行时凭证来自内存中解析后的快照；发现旧版静态 `auth.json` 条目时会进行清理。 +- 每个智能体的 profile 存储在 `/auth-profiles.json`。 +- `auth-profiles.json` 对静态凭证模式支持值级引用（`api_key` 对应 `keyRef`，`token` 对应 `tokenRef`）。 +- OAuth 模式 profile（`auth.profiles..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` 可以清除未知键）。 - + ```json { @@ -1006,11 +1055,11 @@ SecretRef 是增量支持的：明文值仍然可用。 } ``` -- `sessionRetention`：在从 `sessions.json` 中清理之前，已完成的隔离 cron 运行会话要保留多久。也控制已归档、已删除 cron 转录的清理。默认：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：触发清理前每个运行日志文件（`cron/runs/.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/.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) diff --git a/docs/zh-CN/plugins/google-meet.md b/docs/zh-CN/plugins/google-meet.md index e7ea76fe2..f135a73db 100644 --- a/docs/zh-CN/plugins/google-meet.md +++ b/docs/zh-CN/plugins/google-meet.md @@ -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 --port 18789 --display-name parallels-macos ``` -如果 `` 是局域网 IP，且你未使用 TLS，那么除非你为该受信私有网络显式开启，否则节点会拒绝明文 WebSocket： +如果 `` 是局域网 IP 且你未使用 TLS，除非你为该受信任私有网络显式启用明文 WebSocket，否则节点会拒绝它： ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --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 ``` -确认 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 ` 会挂断委派出去的语音呼叫。 +- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。 +- Gateway 网关重新加载后，CLI 中可用 `voicecall`。 +- 返回的会话包含 `transport: "twilio"` 和 `twilio.voiceCallId`。 +- `googlemeet leave ` 会挂断被委派的语音呼叫。 ## 故障排除 ### 智能体看不到 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 --port 18789 --display-name parallels-macos ``` -在 Gateway 网关主机上，批准该节点并验证命令： +在 Gateway 网关主机上，批准节点并验证命令： ```bash openclaw devices list @@ -712,8 +846,7 @@ openclaw devices approve 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)