From 669c8234885af3f9eb43a0b969773104e864850d Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 01:30:20 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/agents.md | 59 +-- docs/zh-CN/concepts/model-providers.md | 215 ++++---- docs/zh-CN/gateway/config-agents.md | 467 +++++++++--------- docs/zh-CN/help/testing-live.md | 296 +++++------ docs/zh-CN/plugins/google-meet.md | 487 +++++++----------- docs/zh-CN/plugins/manifest.md | 395 +++++++-------- docs/zh-CN/plugins/sdk-agent-harness.md | 190 +++---- docs/zh-CN/plugins/sdk-migration.md | 627 ++++++++++++------------ docs/zh-CN/plugins/sdk-overview.md | 290 +++++------ docs/zh-CN/providers/google.md | 165 +++---- 10 files changed, 1458 insertions(+), 1733 deletions(-) diff --git a/docs/zh-CN/cli/agents.md b/docs/zh-CN/cli/agents.md index 10d55efd8..ef1b6af56 100644 --- a/docs/zh-CN/cli/agents.md +++ b/docs/zh-CN/cli/agents.md @@ -1,24 +1,24 @@ --- read_when: - - 你想要多个彼此隔离的智能体（工作区 + 路由 + 凭证） + - 你想要多个相互隔离的智能体（工作区 + 路由 + 凭证） summary: '`openclaw agents` 的 CLI 参考（list/add/delete/bindings/bind/unbind/set identity）' title: 智能体 x-i18n: - generated_at: "2026-04-24T03:38:07Z" + generated_at: "2026-04-25T01:27:29Z" model: gpt-5.4 provider: openai - source_hash: 04d0ce4f3fb3d0c0ba8ffb3676674cda7d9a60441a012bc94ff24a17105632f1 + source_hash: fcd0698f0821f9444e84cd82fe78ee46071447fb4c3cada6d1a98b5130147691 source_path: cli/agents.md workflow: 15 --- # `openclaw agents` -管理彼此隔离的智能体（工作区 + 凭证 + 路由）。 +管理相互隔离的智能体（工作区 + 凭证 + 路由）。 相关内容： -- 多智能体路由：[Multi-Agent Routing](/zh-CN/concepts/multi-agent) +- 多智能体路由：[多智能体路由](/zh-CN/concepts/multi-agent) - 智能体工作区：[智能体工作区](/zh-CN/concepts/agent-workspace) - Skills 可见性配置：[Skills 配置](/zh-CN/tools/skills-config) @@ -39,10 +39,10 @@ openclaw agents delete work ## 路由绑定 -使用路由绑定将入站渠道流量固定到特定智能体。 +使用路由绑定可将入站渠道流量固定到特定智能体。 -如果你还希望为每个智能体显示不同的 Skills，请在 `openclaw.json` 中配置 -`agents.defaults.skills` 和 `agents.list[].skills`。参见 +如果你还希望每个智能体看到不同的 Skills，请在 `openclaw.json` 中配置 +`agents.defaults.skills` 和 `agents.list[].skills`。请参阅 [Skills 配置](/zh-CN/tools/skills-config) 和 [配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。 @@ -64,23 +64,23 @@ openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a 如果你在 `bind` 或 `unbind` 中省略 `--agent`，OpenClaw 会以当前默认智能体为目标。 -### 绑定范围行为 +### 绑定作用域行为 -- 不带 `accountId` 的绑定仅匹配该渠道的默认账号。 -- `accountId: "*"` 是渠道级回退项（适用于所有账号），其具体程度低于显式账号绑定。 -- 如果同一个智能体已经有一个不带 `accountId` 的匹配渠道绑定，而你之后又使用显式或已解析的 `accountId` 进行绑定，OpenClaw 会原地升级这个现有绑定，而不是添加重复项。 +- 不带 `accountId` 的绑定仅匹配渠道默认账户。 +- `accountId: "*"` 是渠道范围的回退项（所有账户），其具体程度低于显式账户绑定。 +- 如果同一个智能体已经有一个不带 `accountId` 的匹配渠道绑定，而你之后使用显式或已解析的 `accountId` 进行绑定，OpenClaw 会就地升级该现有绑定，而不是添加重复项。 示例： ```bash -# initial channel-only binding +# 初始的仅渠道绑定 openclaw agents bind --agent work --bind telegram -# later upgrade to account-scoped binding +# 之后升级为按账户划分作用域的绑定 openclaw agents bind --agent work --bind telegram:ops ``` -升级后，该绑定的路由范围将限定为 `telegram:ops`。如果你还希望保留默认账号路由，请显式添加（例如 `--bind telegram:default`）。 +升级后，该绑定的路由作用域将限定为 `telegram:ops`。如果你还想要默认账户路由，请显式添加它（例如 `--bind telegram:default`）。 移除绑定： @@ -95,14 +95,14 @@ openclaw agents unbind --agent work --all ### `agents` -运行不带子命令的 `openclaw agents` 等同于 `openclaw agents list`。 +在没有子命令的情况下运行 `openclaw agents`，等同于运行 `openclaw agents list`。 ### `agents list` 选项： - `--json` -- `--bindings`：包含完整路由规则，而不只是按智能体划分的计数/摘要 +- `--bindings`：包含完整路由规则，而不只是每个智能体的计数/摘要 ### `agents add [name]` @@ -117,8 +117,8 @@ openclaw agents unbind --agent work --all 说明： -- 传入任何显式的 add 标志，都会让命令切换到非交互路径。 -- 非交互模式同时要求提供智能体名称和 `--workspace`。 +- 传入任何显式的 add 标志都会将命令切换到非交互路径。 +- 非交互模式要求同时提供智能体名称和 `--workspace`。 - `main` 是保留名称，不能用作新智能体 id。 ### `agents bindings` @@ -132,7 +132,7 @@ openclaw agents unbind --agent work --all 选项： -- `--agent `（默认使用当前默认智能体） +- `--agent `（默认为当前默认智能体） - `--bind `（可重复） - `--json` @@ -140,7 +140,7 @@ openclaw agents unbind --agent work --all 选项： -- `--agent `（默认使用当前默认智能体） +- `--agent `（默认为当前默认智能体） - `--bind `（可重复） - `--all` - `--json` @@ -155,17 +155,20 @@ openclaw agents unbind --agent work --all 说明： - `main` 不能被删除。 -- 没有 `--force` 时，需要交互式确认。 -- 工作区、智能体状态和会话转录目录会被移到回收站，而不是被彻底删除。 +- 如果不带 `--force`，则需要交互式确认。 +- 工作区、智能体状态目录和会话转录目录会被移到废纸篓，而不是被硬删除。 +- 如果另一个智能体的工作区是同一路径、位于此工作区内部，或包含此工作区， + 则该工作区会被保留，且 `--json` 会报告 `workspaceRetained`、 + `workspaceRetainedReason` 和 `workspaceSharedWith`。 ## 身份文件 每个智能体工作区都可以在工作区根目录包含一个 `IDENTITY.md`： - 示例路径：`~/.openclaw/workspace/IDENTITY.md` -- `set-identity --from-identity` 会从工作区根目录读取（或从显式指定的 `--identity-file` 读取） +- `set-identity --from-identity` 会从工作区根目录读取（或从显式的 `--identity-file` 读取） -头像路径会相对于工作区根目录解析。 +头像路径相对于工作区根目录解析。 ## 设置身份 @@ -190,9 +193,9 @@ openclaw agents unbind --agent work --all 说明： -- 可以使用 `--agent` 或 `--workspace` 选择目标智能体。 +- 可使用 `--agent` 或 `--workspace` 选择目标智能体。 - 如果你依赖 `--workspace`，而多个智能体共享该工作区，命令会失败，并要求你传入 `--agent`。 -- 当未提供显式身份字段时，命令会从 `IDENTITY.md` 读取身份数据。 +- 当未提供任何显式身份字段时，命令会从 `IDENTITY.md` 读取身份数据。 从 `IDENTITY.md` 加载： @@ -229,5 +232,5 @@ openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --ava ## 相关内容 - [CLI 参考](/zh-CN/cli) -- [Multi-Agent Routing](/zh-CN/concepts/multi-agent) +- [多智能体路由](/zh-CN/concepts/multi-agent) - [智能体工作区](/zh-CN/concepts/agent-workspace) diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index 4080a6046..830d65330 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,61 +1,61 @@ --- read_when: - - 你需要一份按提供商划分的模型设置参考文档 - - 你想要模型提供商的示例配置或 CLI 新手引导命令 + - 你需要一份按提供商逐项说明的模型设置参考文档 + - 你想要用于模型提供商的示例配置或 CLI 新手引导命令 summary: 模型提供商概览，包含示例配置 + CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-25T00:40:12Z" + generated_at: "2026-04-25T01:27:33Z" model: gpt-5.4 provider: openai - source_hash: 009d57c8e26971357592f6fd57ad03f98f0325c410011649f002531ecb99aa06 + source_hash: 9bc820dafddfb56849cc54216cb9392d0f9e2a980ee12e23382348bdb29233c3 source_path: concepts/model-providers.md workflow: 15 --- 本页介绍的是 **LLM/模型提供商**（不是像 WhatsApp/Telegram 这样的聊天渠道）。 -有关模型选择规则，请参阅 [/concepts/models](/zh-CN/concepts/models)。 +关于模型选择规则，请参阅 [/concepts/models](/zh-CN/concepts/models)。 ## 快速规则 - 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。 -- 设置后，`agents.defaults.models` 会作为允许列表。 +- 设置后，`agents.defaults.models` 会作为允许列表生效。 - CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 -- `models.providers.*.models[].contextWindow` 是模型原生元数据；`contextTokens` 是运行时生效的上限。 +- `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)。 -- 插件自动启用也遵循相同边界：`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`。 +- OpenAI 系列路由按前缀区分：`openai/` 在 PI 中使用直连 OpenAI API 密钥提供商，`openai-codex/` 在 PI 中使用 Codex OAuth，而 `openai/` 加上 `agents.defaults.embeddedHarness.runtime: "codex"` 则使用原生 Codex 应用服务器 harness。参见 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。 +- 插件自动启用遵循相同边界：`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 应用服务器 harness 的 `openai/gpt-5.5`。当 OpenAI 在公共 API 上启用 GPT-5.5 后，`openai/gpt-5.5` 的直连 API 密钥路由才会受支持；在此之前，`OPENAI_API_KEY` 配置请使用已启用 API 的模型，例如 `openai/gpt-5.4`。 ## 插件拥有的提供商行为 -大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具模式清理、故障切换分类、OAuth 刷新、用量报告、思考/推理配置以及更多功能。 +大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 负责保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具模式清理、故障切换分类、OAuth 刷新、用量报告、思考/推理配置等。 -提供商 SDK 钩子的完整列表和内置插件示例位于 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，那将属于另一个更深层的扩展接口。 +提供商 SDK 钩子和内置插件示例的完整列表位于 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，则属于另一个更深层的扩展接口。 -提供商运行时 `capabilities` 是共享的运行器元数据（提供商家族、转录/工具特性差异、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是一个插件注册了什么能力（文本推理、语音等）。 +提供商运行时 `capabilities` 是共享的运行器元数据（提供商家族、转录/工具行为差异、传输/缓存提示）。它不同于[公共能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是一个插件注册了什么（文本推理、语音等）。 ## API 密钥轮换 -- 支持针对选定提供商的通用提供商轮换。 +- 支持为选定提供商进行通用提供商密钥轮换。 - 可通过以下方式配置多个密钥： - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） - `_API_KEYS`（逗号或分号分隔列表） - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） -- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退项包含在内。 +- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。 - 密钥选择顺序会保留优先级并去重。 -- 仅在遇到限流响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 或周期性的使用量限制消息）。 -- 非限流失败会立即失败；不会尝试密钥轮换。 +- 仅在遇到速率限制响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。 +- 非速率限制失败会立即失败；不会尝试密钥轮换。 - 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。 ## 内置提供商（pi-ai 目录） -OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** -`models.providers` 配置；只需设置认证信息并选择模型。 +OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** +`models.providers` 配置；只需设置认证信息并选择一个模型。 ### OpenAI @@ -63,17 +63,17 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** - 认证：`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 支持做好准备 +- 一旦 OpenAI 在 API 上开放 GPT-5.5，这里就已为 GPT-5.5 直连 API 支持做好准备 - CLI：`openclaw onboard --auth-choice openai-api-key` -- 默认传输为 `auto`（优先 WebSocket，回退到 SSE） +- 默认传输为 `auto`（优先 WebSocket，回退 SSE） - 可按模型通过 `agents.defaults.models["openai/"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`） - OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`） - 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先级处理 -- `/fast` 和 `params.fastMode` 会将直连 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority` -- 如果你希望使用显式层级而不是共享的 `/fast` 开关，请使用 `params.serviceTier` -- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）只会应用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理 +- `/fast` 和 `params.fastMode` 会将直连 `openai/*` Responses 请求映射为 `api.openai.com` 上的 `service_tier=priority` +- 当你希望显式指定层级而不是使用共享 `/fast` 开关时，请使用 `params.serviceTier` +- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理 - 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示以及 OpenAI 推理兼容负载整形；代理路由则不会 -- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意隐藏，因为实时 OpenAI API 请求会拒绝它，而当前 Codex 目录也未公开它 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为实际 OpenAI API 请求会拒绝它，而当前 Codex 目录也未公开它 ```json5 { @@ -88,9 +88,9 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** - 可选轮换：`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 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的认可方式。 +- Anthropic setup-token 仍然作为受支持的 OpenClaw token 路径可用，但 OpenClaw 现在在可用时更倾向于 Claude CLI 复用和 `claude -p`。 ```json5 { @@ -103,18 +103,18 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** - 提供商：`openai-codex` - 认证：OAuth（ChatGPT） - PI 模型引用：`openai-codex/gpt-5.5` -- 原生 Codex app-server harness 引用：`openai/gpt-5.5`，配合 `agents.defaults.embeddedHarness.runtime: "codex"` +- 原生 Codex 应用服务器 harness 引用：`openai/gpt-5.5`，并设置 `agents.defaults.embeddedHarness.runtime: "codex"` - 旧版模型引用：`codex/gpt-*` -- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex app-server 插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择。 +- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选中。 - CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex` -- 默认传输为 `auto`（优先 WebSocket，回退到 SSE） +- 默认传输为 `auto`（优先 WebSocket，回退 SSE） - 可按 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 兼容代理 +- `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 OAuth 明确支持 OpenClaw 这样的外部工具/工作流。 -- 当前的 GPT-5.5 访问使用此 OAuth/订阅路由，直到 OpenAI 在公共 API 中启用 GPT-5.5。 +- `openai-codex/gpt-5.5` 保留原生 `contextWindow = 1000000`，默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 +- 策略说明：OpenAI Codex OAuth 被明确支持用于 OpenClaw 这样的外部工具/工作流。 +- 在 OpenAI 于公共 API 上启用 GPT-5.5 之前，当前 GPT-5.5 访问将使用此 OAuth/订阅路由。 ```json5 { @@ -136,7 +136,7 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** ### 其他订阅式托管选项 -- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及阿里巴巴 DashScope 和 Coding Plan 端点映射 +- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 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 端点 @@ -158,19 +158,18 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** - 提供商：`google` - 认证：`GEMINI_API_KEY` -- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） +- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） - 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview` - 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview` - CLI：`openclaw onboard --auth-choice gemini-api-key` -- 直连 Gemini 运行也接受 `agents.defaults.models["google/"].params.cachedContent` - （或旧版 `cached_content`）来透传提供商原生的 - `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` +- 思考：`/think adaptive` 使用 Google 动态思考。Gemini 3/3.1 不包含固定的 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。 +- 直连 Gemini 运行还接受 `agents.defaults.models["google/"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` ### Google Vertex 和 Gemini CLI - 提供商：`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` @@ -178,10 +177,9 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** - 启用：`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 网关主机上的认证配置文件中。 + - 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将 token 存储在 Gateway 网关主机上的认证配置文件中。 - 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。 - - Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 - `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 + - Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 ### Z.AI（GLM） @@ -190,7 +188,7 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** - 示例模型：`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 @@ -207,10 +205,10 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** - 示例模型：`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`；实时 + `https://api.kilo.ai/api/gateway/models` 发现还可以进一步扩展运行时 目录。 -- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 拥有， +- `kilocode/kilo/auto` 背后的具体上游路由由 Kilo Gateway 网关负责， 并非在 OpenClaw 中硬编码。 设置详情请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。 @@ -221,16 +219,16 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** | ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | | BytePlus（国际版） | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | | Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | -| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | +| Cloudflare AI Gateway 网关 | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | | DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | | GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | | Groq | `groq` | `GROQ_API_KEY` | — | | Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | -| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | +| Kilo Gateway 网关 | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | | Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` | | MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | | Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | -| Moonshot AI | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | +| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | | NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | | OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | | Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | @@ -238,40 +236,39 @@ OpenClaw 内置了 pi-ai 目录。这些提供商**不需要** | StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | | Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | | Venice | `venice` | `VENICE_API_KEY` | — | -| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | +| Vercel AI Gateway 网关 | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | | Volcano Engine（Doubao） | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | | xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | | Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -一些值得了解的特殊行为： +一些值得了解的特性： -- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其应用归因请求头和 Anthropic `cache_control` 标记。作为代理风格的 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的负载整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容性）。基于 Gemini 的引用仅保留代理 Gemini 的思维签名清理。 -- **Kilo Gateway** 中基于 Gemini 的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。 -- **MiniMax** API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在由插件拥有的 `MiniMax-VL-01` 媒体提供商上。 -- **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`。 +- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其应用归因请求头和 Anthropic `cache_control` 标记。作为代理式 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的整形处理（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容性）。基于 Gemini 的引用仅保留代理 Gemini 思考签名清理。 +- **Kilo Gateway 网关** 中基于 Gemini 的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。 +- **MiniMax** API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在由插件负责的 `MiniMax-VL-01` 媒体提供商上。 +- **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`（或 `models.json`）来添加**自定义**提供商或 -兼容 OpenAI/Anthropic 的代理。 +OpenAI/Anthropic 兼容代理。 -下面许多内置提供商插件已经发布了默认目录。 -仅当你想覆盖默认 Base URL、请求头或模型列表时，才需要使用显式的 +下方许多内置提供商插件已经发布了默认目录。 +只有当你想覆盖默认 Base URL、请求头或模型列表时，才需要使用显式 `models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件提供。 -默认情况下请使用内置提供商，只有在你 -需要覆盖 base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： +Moonshot 作为内置提供商插件提供。默认情况下请使用内置提供商， +仅当你需要覆盖 Base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： - 提供商：`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" @@ -319,13 +316,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍作为兼容模型 ID 被接受。 +旧版 `kimi/k2p5` 仍然作为兼容模型 Id 被接受。 ### Volcano Engine（Doubao） -Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。 +Volcano Engine（火山引擎）提供对中国区 Doubao 和其他模型的访问。 -- 提供商：`volcengine`（编程：`volcengine-plan`） +- 提供商：`volcengine`（编程方案：`volcengine-plan`） - 认证：`VOLCANO_ENGINE_API_KEY` - 示例模型：`volcengine-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice volcengine-api-key` @@ -343,8 +340,7 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访 在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载， -OpenClaw 会回退到未过滤的目录，而不是显示一个空的 -提供商范围选择器。 +OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商范围筛选的选择器。 可用模型： @@ -364,9 +360,9 @@ OpenClaw 会回退到未过滤的目录，而不是显示一个空的 ### BytePlus（国际版） -BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 +BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。 -- 提供商：`byteplus`（编程：`byteplus-plan`） +- 提供商：`byteplus`（编程方案：`byteplus-plan`） - 认证：`BYTEPLUS_API_KEY` - 示例模型：`byteplus-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice byteplus-api-key` @@ -384,8 +380,7 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 在新手引导/配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载， -OpenClaw 会回退到未过滤的目录，而不是显示一个空的 -提供商范围选择器。 +OpenClaw 会回退到未过滤的目录，而不是显示一个空的按提供商范围筛选的选择器。 可用模型： @@ -403,7 +398,7 @@ OpenClaw 会回退到未过滤的目录，而不是显示一个空的 ### Synthetic -Synthetic 通过 `synthetic` 提供商提供兼容 Anthropic 的模型： +Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型： - 提供商：`synthetic` - 认证：`SYNTHETIC_API_KEY` @@ -433,25 +428,25 @@ Synthetic 通过 `synthetic` 提供商提供兼容 Anthropic 的模型： MiniMax 通过 `models.providers` 配置，因为它使用自定义端点： -- 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 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` 设置详情、模型选项和配置片段请参阅 [/providers/minimax](/zh-CN/providers/minimax)。 -在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认禁用思考， -除非你显式设置它，并且 `/fast on` 会将 +在 MiniMax 的 Anthropic 兼容流式传输路径上，OpenClaw 默认会禁用思考， +除非你显式设置它；而 `/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 搜索保持使用提供商 id `minimax` +- 图像理解在两种 MiniMax 认证路径上都使用由插件负责的 `MiniMax-VL-01` +- Web 搜索仍使用提供商 Id `minimax` ### LM Studio @@ -461,7 +456,7 @@ LM Studio 作为内置提供商插件提供，并使用原生 API： - 认证：`LM_API_TOKEN` - 默认推理 Base URL：`http://localhost:1234/v1` -然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 Id）： ```json5 { @@ -472,7 +467,7 @@ LM Studio 作为内置提供商插件提供，并使用原生 API： ``` OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` -进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。 +进行发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。 设置和故障排除请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 ### Ollama @@ -480,7 +475,7 @@ OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API： - 提供商：`ollama` -- 认证：无需（本地服务器） +- 认证：不需要（本地服务器） - 示例模型：`ollama/llama3.3` - 安装：[https://ollama.com/download](https://ollama.com/download) @@ -497,27 +492,26 @@ ollama pull llama3.3 } ``` -当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 -`http://127.0.0.1:11434` 检测 Ollama，并且内置提供商插件会将 Ollama 直接添加到 -`openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式和自定义配置， -请参阅 [/providers/ollama](/zh-CN/providers/ollama)。 +当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` +检测 Ollama，内置提供商插件也会将 Ollama 直接添加到 +`openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式和自定义配置，请参阅 [/providers/ollama](/zh-CN/providers/ollama)。 ### vLLM -vLLM 作为内置提供商插件提供，适用于本地/自托管的 OpenAI 兼容 +vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容 服务器： - 提供商：`vllm` - 认证：可选（取决于你的服务器） - 默认 Base URL：`http://127.0.0.1:8000/v1` -要在本地启用自动发现（如果你的服务器不强制认证，任意值都可以）： +要在本地选择启用自动发现（如果你的服务器不强制认证，任意值都可以）： ```bash export VLLM_API_KEY="vllm-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 Id）： ```json5 { @@ -531,21 +525,21 @@ export VLLM_API_KEY="vllm-local" ### SGLang -SGLang 作为内置提供商插件提供，适用于快速自托管的 +SGLang 作为内置提供商插件提供，用于快速自托管的 OpenAI 兼容服务器： - 提供商：`sglang` - 认证：可选（取决于你的服务器） - 默认 Base URL：`http://127.0.0.1:30000/v1` -要在本地启用自动发现（如果你的服务器不 +要在本地选择启用自动发现（如果你的服务器不 强制认证，任意值都可以）： ```bash export SGLANG_API_KEY="sglang-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 Id）： ```json5 { @@ -559,7 +553,7 @@ export SGLANG_API_KEY="sglang-local" ### 本地代理（LM Studio、vLLM、LiteLLM 等） -示例（兼容 OpenAI）： +示例（OpenAI 兼容）： ```json5 { @@ -595,20 +589,17 @@ export SGLANG_API_KEY="sglang-local" 说明： - 对于自定义提供商，`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"`（任何 host 不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 -- 代理风格的 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求 - 整形：不使用 `service_tier`、不使用 Responses `store`、不使用提示缓存提示、不进行 - OpenAI 推理兼容负载整形，也不会附加隐藏的 OpenClaw 归因 - 请求头。 -- 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认的 OpenAI 行为（即解析到 `api.openai.com`）。 -- 为安全起见，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 +- 建议：设置与你的代理/模型限制相匹配的显式值。 +- 对于非原生端点上的 `api: "openai-completions"`（任何主机不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设定 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 +- 代理式 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求整形：没有 `service_tier`、没有 Responses `store`、没有提示缓存提示、没有 OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因请求头。 +- 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认 OpenAI 行为（即解析到 `api.openai.com`）。 +- 为了安全起见，在非原生 `openai-completions` 端点上，即使显式设置了 `compat.supportsDeveloperRole: true`，也仍会被覆盖。 ## CLI 示例 @@ -618,11 +609,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -另请参阅：[/gateway/configuration](/zh-CN/gateway/configuration)，获取完整配置示例。 +另请参阅：[/gateway/configuration](/zh-CN/gateway/configuration) 获取完整配置示例。 ## 相关内容 - [模型](/zh-CN/concepts/models) — 模型配置和别名 - [模型故障切换](/zh-CN/concepts/model-failover) — 回退链和重试行为 - [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键 -- [提供商](/zh-CN/providers) — 按提供商划分的设置指南 +- [提供商](/zh-CN/providers) — 按提供商分类的设置指南 diff --git a/docs/zh-CN/gateway/config-agents.md b/docs/zh-CN/gateway/config-agents.md index c38d75fe5..2baaaeae1 100644 --- a/docs/zh-CN/gateway/config-agents.md +++ b/docs/zh-CN/gateway/config-agents.md @@ -1,22 +1,22 @@ --- read_when: - - 调整智能体默认值（模型、思考、工作区、心跳、媒体、Skills） + - 调整智能体默认设置（模型、思考、工作区、心跳、媒体、Skills） - 配置多智能体路由和绑定 - 调整会话、消息传递和通话模式行为 -summary: 智能体默认值、多智能体路由、会话、消息和通话配置 +summary: 智能体默认设置、多智能体路由、会话、消息和通话配置 title: 配置 — 智能体 x-i18n: - generated_at: "2026-04-25T00:40:16Z" + generated_at: "2026-04-25T01:27:31Z" model: gpt-5.4 provider: openai - source_hash: fe9405429df108dd6a745102e03ad1dea29cf9559ad534bba202c767db047a75 + source_hash: 3df297e134f10215ac30bb582180dc06413f81f80c3f673926bf26f8c36a640e source_path: gateway/config-agents.md workflow: 15 --- -`agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下的智能体作用域配置键。对于渠道、工具、Gateway 网关运行时和其他顶层键，请参见[配置参考](/zh-CN/gateway/configuration-reference)。 +`agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下按智能体作用域划分的配置键。关于渠道、工具、Gateway 网关运行时以及其他顶层键，请参见 [配置参考](/zh-CN/gateway/configuration-reference)。 -## 智能体默认值 +## 智能体默认设置 ### `agents.defaults.workspace` @@ -30,7 +30,7 @@ x-i18n: ### `agents.defaults.repoRoot` -显示在系统提示词中 Runtime 行的可选仓库根目录。如果未设置，OpenClaw 会从工作区向上遍历并自动检测。 +可选的仓库根目录，会显示在系统提示中的 Runtime 行里。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。 ```json5 { @@ -56,13 +56,13 @@ x-i18n: ``` - 省略 `agents.defaults.skills` 可使默认 Skills 不受限制。 -- 省略 `agents.list[].skills` 将继承默认值。 -- 设置 `agents.list[].skills: []` 表示不使用任何 Skills。 +- 省略 `agents.list[].skills` 以继承默认值。 +- 设置 `agents.list[].skills: []` 表示没有 Skills。 - 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 +禁用工作区引导文件的自动创建（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -72,9 +72,9 @@ x-i18n: ### `agents.defaults.contextInjection` -控制何时将工作区引导文件注入系统提示词。默认值：`"always"`。 +控制何时将工作区引导文件注入系统提示。默认值：`"always"`。 -- `"continuation-skip"`：安全的续接轮次（在助手完成响应之后）会跳过重新注入工作区引导内容，从而减少提示词大小。Heartbeat 运行和压缩后重试仍会重建上下文。 +- `"continuation-skip"`：安全的续接轮次（在助手完成响应之后）会跳过重新注入工作区引导内容，从而减小提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。 ```json5 { @@ -84,7 +84,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -每个工作区引导文件在截断前允许的最大字符数。默认值：`12000`。 +每个工作区引导文件在被截断前允许的最大字符数。默认值：`12000`。 ```json5 { @@ -94,7 +94,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -所有工作区引导文件合计可注入的最大字符数。默认值：`60000`。 +跨所有工作区引导文件注入的总最大字符数。默认值：`60000`。 ```json5 { @@ -104,12 +104,11 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -控制当引导上下文被截断时，是否向智能体显示警告文本。 -默认值：`"once"`。 +控制在引导上下文被截断时，向智能体显示的警告文本。默认值：`"once"`。 -- `"off"`：绝不将警告文本注入系统提示词。 +- `"off"`：绝不将警告文本注入系统提示。 - `"once"`：每个唯一的截断签名只注入一次警告（推荐）。 -- `"always"`：只要存在截断，每次运行都注入警告。 +- `"always"`：只要存在截断，就在每次运行时注入警告。 ```json5 { @@ -119,7 +118,7 @@ x-i18n: ### 上下文预算归属映射 -OpenClaw 有多个高容量的提示词 / 上下文预算，这些预算会按子系统有意拆分，而不是全部通过一个通用旋钮来控制。 +OpenClaw 有多个高容量提示 / 上下文预算，并且这些预算会按子系统有意拆分，而不是全都通过一个通用开关控制。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： @@ -128,11 +127,11 @@ OpenClaw 有多个高容量的提示词 / 上下文预算，这些预算会按 一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日 `memory/*.md` 文件。 - `skills.limits.*`： - 注入系统提示词中的精简 Skills 列表。 + 注入系统提示中的紧凑 Skills 列表。 - `agents.defaults.contextLimits.*`： - 有界运行时摘录和由运行时拥有的注入内容块。 + 有界的运行时摘录以及注入的运行时自有区块。 - `memory.qmd.limits.*`： - 已索引的内存搜索片段和注入大小控制。 + 已索引的内存搜索片段及其注入大小控制。 仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖项： @@ -141,7 +140,7 @@ OpenClaw 有多个高容量的提示词 / 上下文预算，这些预算会按 #### `agents.defaults.startupContext` -控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 +控制在空白 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 ```json5 { @@ -162,7 +161,7 @@ OpenClaw 有多个高容量的提示词 / 上下文预算，这些预算会按 #### `agents.defaults.contextLimits` -有界运行时上下文表面的共享默认值。 +用于有界运行时上下文表面的共享默认值。 ```json5 { @@ -179,14 +178,14 @@ OpenClaw 有多个高容量的提示词 / 上下文预算，这些预算会按 } ``` -- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接提示之前的默认上限。 +- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接提示前的默认上限。 - `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认行窗口。 - `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 -- `postCompactionMaxChars`：压缩后刷新注入期间使用的 `AGENTS.md` 摘录上限。 +- `postCompactionMaxChars`：压缩后刷新注入期间，`AGENTS.md` 摘录的字符上限。 #### `agents.list[].contextLimits` -共享 `contextLimits` 旋钮的按智能体覆盖项。省略的字段将继承自 `agents.defaults.contextLimits`。 +对共享 `contextLimits` 开关提供按智能体覆盖。省略的字段会继承自 `agents.defaults.contextLimits`。 ```json5 { @@ -212,7 +211,7 @@ OpenClaw 有多个高容量的提示词 / 上下文预算，这些预算会按 #### `skills.limits.maxSkillsPromptChars` -注入系统提示词中的精简 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 +注入系统提示中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -226,7 +225,7 @@ OpenClaw 有多个高容量的提示词 / 上下文预算，这些预算会按 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Skills 提示词预算的按智能体覆盖项。 +Skills 提示预算的按智能体覆盖项。 ```json5 { @@ -245,11 +244,11 @@ Skills 提示词预算的按智能体覆盖项。 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，transcript / 工具图像块中图像最长边的最大像素尺寸。 +在调用提供商之前，transcript / 工具图像区块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量和以截图为主的运行请求负载大小。 -较高的值会保留更多视觉细节。 +较低的值通常会减少视觉 token 使用量以及以截图为主的运行请求负载大小。 +较高的值则会保留更多视觉细节。 ```json5 { @@ -259,7 +258,7 @@ Skills 提示词预算的按智能体覆盖项。 ### `agents.defaults.userTimezone` -用于系统提示词上下文的时区（不影响消息时间戳）。会回退到主机时区。 +用于系统提示上下文的时区（不影响消息时间戳）。会回退到主机时区。 ```json5 { @@ -269,7 +268,7 @@ Skills 提示词预算的按智能体覆盖项。 ### `agents.defaults.timeFormat` -系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 ```json5 { @@ -328,49 +327,49 @@ Skills 提示词预算的按智能体覆盖项。 - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - 字符串形式只设置主模型。 - - 对象形式设置主模型以及按顺序排列的故障转移模型。 + - 对象形式设置主模型以及按顺序排列的故障切换模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 由 `image` 工具路径用作其视觉模型配置。 - - 当选定 / 默认模型无法接受图像输入时，也会用作回退路由。 + - 作为 `image` 工具路径的视觉模型配置使用。 + - 当所选 / 默认模型无法接受图像输入时，也会用作回退路由。 - `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 用于共享的图像生成能力，以及任何未来会生成图像的工具 / 插件表面。 + - 用于共享图像生成能力，以及任何未来会生成图像的工具 / 插件表面。 - 典型值：`google/gemini-3.1-flash-image-preview` 用于原生 Gemini 图像生成，`fal/fal-ai/flux/dev` 用于 fal，或 `openai/gpt-image-2` 用于 OpenAI Images。 - - 如果你直接选择某个 provider / 模型，也要配置匹配的提供商认证（例如：`google/*` 对应 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 对应 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 对应 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出一个已配置认证的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的图像生成提供商。 + - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证（例如，`google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 需要 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 需要 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的图像生成提供商。 - `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 用于共享的音乐生成能力和内置的 `music_generate` 工具。 + - 用于共享音乐生成能力以及内置的 `music_generate` 工具。 - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断出一个已配置认证的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个 provider / 模型，也要同时配置匹配的提供商认证 / API 密钥。 + - 如果省略，`music_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证 / API 密钥。 - `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 用于共享的视频生成能力和内置的 `video_generate` 工具。 + - 用于共享视频生成能力以及内置的 `video_generate` 工具。 - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断出一个已配置认证的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个 provider / 模型，也要同时配置匹配的提供商认证 / API 密钥。 + - 如果省略，`video_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证 / API 密钥。 - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 - `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。 - - 由 `pdf` 工具用于模型路由。 - - 如果省略，PDF 工具会回退到 `imageModel`，再回退到已解析的会话 / 默认模型。 + - 用于 `pdf` 工具的模型路由。 + - 如果省略，PDF 工具会依次回退到 `imageModel`，然后回退到已解析的会话 / 默认模型。 - `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，`pdf` 工具使用的默认 PDF 大小限制。 - `pdfMaxPages`：`pdf` 工具在提取回退模式下默认考虑的最大页数。 - `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 - `elevatedDefault`：智能体的默认增强输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如，`openai/gpt-5.4` 用于 API 密钥访问，或 `openai-codex/gpt-5.5` 用于 Codex OAuth）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试与该确切模型 id 唯一匹配的已配置 provider，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该 provider 不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider / 模型，而不是暴露一个陈旧的已移除 provider 默认值。 -- `models`：`/model` 的已配置模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`）。 - - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换操作。 - - provider 作用域的配置 / 新手引导流程会把选定的 provider 模型合并到此映射中，并保留已经配置的无关 provider。 - - 对于直接的 OpenAI Responses 模型，默认会自动启用服务端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。详见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 -- `params`：应用于所有模型的全局默认提供商参数。在 `agents.defaults.params` 中设置（例如 `{ cacheRetention: "long" }`）。 -- `params` 的合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 id）会按键覆盖。详见[提示词缓存](/zh-CN/reference/prompt-caching)。 -- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。省略 `runtime` 时，默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册的插件 harness 认领受支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动回退到 PI。请将模型引用保持为规范格式 `provider/model`；通过运行时配置而不是旧版运行时 provider 前缀来选择 Codex、Claude CLI、Gemini CLI 和其他执行后端。 -- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退项添加 / 删除命令）会保存为规范对象形式，并尽可能保留现有的回退列表。 +- `model.primary`：格式为 `provider/model`（例如，`openai/gpt-5.4` 用于 API 密钥访问，或 `openai-codex/gpt-5.5` 用于 Codex OAuth）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试与该精确 model id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider / model，而不是显示一个已过期、已移除提供商的默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`）。 + - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝会删除现有允许列表条目的替换操作。 + - 以提供商为作用域的 configure / onboarding 流程会将选定提供商的模型合并到此映射中，并保留已配置的无关提供商。 + - 对于直接使用的 OpenAI Responses 模型，会自动启用服务端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 +- `params`：应用于所有模型的全局默认提供商参数。设置位置为 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配的智能体 id）按键覆盖。详见 [提示缓存](/zh-CN/reference/prompt-caching)。 +- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。省略 runtime 时默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册的插件 harness 接管其支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。请将模型引用保持为标准 `provider/model`；通过运行时配置而不是旧式运行时 provider 前缀来选择 Codex、Claude CLI、Gemini CLI 以及其他执行后端。 +- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及 fallback add / remove 命令）会保存为标准对象形式，并尽可能保留现有的回退列表。 - `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认值：4。 ### `agents.defaults.embeddedHarness` `embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 -大多数部署都应保留默认的 OpenClaw Pi 运行时。 -当受信任的插件提供原生 harness 时可使用它，例如内置的 +大多数部署应保留默认的 OpenClaw Pi 运行时。 +当受信任的插件提供原生 harness 时使用它，例如内置的 Codex app-server harness。 ```json5 @@ -387,35 +386,35 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件注册为 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，省略 `fallback` 时默认值为 `"pi"`，这样旧配置在没有插件 harness 认领运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，省略 `fallback` 时默认值为 `"none"`，这样缺少 harness 时会直接失败，而不是静默使用 PI。运行时覆盖不会继承更广作用域中的 fallback；当你确实想要这种兼容性回退时，请与显式 `runtime` 一起设置 `fallback: "pi"`。所选插件 harness 的失败始终会直接暴露出来。 +- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置 Codex 插件注册的是 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，省略 `fallback` 时默认是 `"pi"`，这样旧配置在没有插件 harness 接管运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，省略 `fallback` 时默认是 `"none"`，这样缺失 harness 时会直接失败，而不是静默使用 PI。运行时覆盖不会继承更广作用域中的 fallback；如果你确实想要这种兼容回退，请在显式 runtime 旁边一起设置 `fallback: "pi"`。所选插件 harness 的失败总是会直接暴露出来。 - 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 会覆盖该进程的 fallback。 -- 对于仅使用 Codex 的部署，请设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。为了可读性，你也可以显式设置 `embeddedHarness.fallback: "none"`；这本就是显式插件运行时的默认值。 -- 第一次嵌入式运行后，harness 选择会按 session id 固定。配置 / 环境变量变更只会影响新的或已重置的会话，不影响现有 transcript。具有 transcript 历史但没有记录固定值的旧会话，会被视为固定到 PI。`/status` 会在 `Fast` 旁显示非 PI 的 harness id，例如 `codex`。 -- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider / 模型设置。 +- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以为了可读性显式设置 `embeddedHarness.fallback: "none"`；对于显式插件运行时，这本来就是默认值。 +- 在第一次嵌入式运行之后，harness 选择会按每个 session id 固定。配置 / 环境变量变更只会影响新的或已重置的会话，不会影响现有 transcript。带有 transcript 历史但没有记录固定值的旧会话会被视为固定到 PI。`/status` 会在 `Fast` 旁显示非 PI 的 harness id，例如 `codex`。 +- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider / model 设置。 -**内置别名简写**（仅在模型位于 `agents.defaults.models` 中时适用）： +**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： -| 别名 | 模型 | +| 别名 | 模型 | | ------------------- | -------------------------------------------------- | -| `opus` | `anthropic/claude-opus-4-6` | -| `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` 或已配置的 Codex OAuth GPT-5.5 | -| `gpt-mini` | `openai/gpt-5.4-mini` | -| `gpt-nano` | `openai/gpt-5.4-nano` | -| `gemini` | `google/gemini-3.1-pro-preview` | -| `gemini-flash` | `google/gemini-3-flash-preview` | -| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | +| `opus` | `anthropic/claude-opus-4-6` | +| `sonnet` | `anthropic/claude-sonnet-4-6` | +| `gpt` | `openai/gpt-5.4` 或已配置 Codex OAuth 的 GPT-5.5 | +| `gpt-mini` | `openai/gpt-5.4-mini` | +| `gpt-nano` | `openai/gpt-5.4-nano` | +| `gemini` | `google/gemini-3.1-pro-preview` | +| `gemini-flash` | `google/gemini-3-flash-preview` | +| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | 你配置的别名始终优先于默认值。 -Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或者自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 +Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 +Z.AI 模型默认启用 `tool_stream` 以支持工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，它可作为备份。 +用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，这可作为备份。 ```json5 { @@ -444,12 +443,12 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - CLI 后端以文本为主；工具始终被禁用。 -- 设置了 `sessionArg` 时支持会话。 +- 当设置了 `sessionArg` 时支持会话。 - 当 `imageArg` 接受文件路径时，支持图像透传。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅包含空白字符的值会被忽略。适用于受控的提示词实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认层级（`agents.defaults.systemPromptOverride`）设置，也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体设置的值优先；空值或仅含空白字符的值会被忽略。这对受控提示实验很有用。 ```json5 { @@ -463,7 +462,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.promptOverlays` -按模型家族应用的、与提供商无关的提示词叠加层。GPT-5 家族模型 id 会在不同提供商之间接收共享的行为契约；`personality` 仅控制友好的交互风格层。 +按模型家族应用的、与提供商无关的提示覆盖层。GPT-5 家族模型 id 会在各提供商之间收到共享的行为契约；`personality` 仅控制友好交互风格这一层。 ```json5 { @@ -479,9 +478,9 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `"friendly"`（默认）和 `"on"` 会启用友好的交互风格层。 -- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍保持启用。 -- 当此共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 +- `"friendly"`（默认）和 `"on"` 会启用友好交互风格层。 +- `"off"` 只会禁用友好层；带标签的 GPT-5 行为契约仍保持启用。 +- 旧版 `plugins.entries.openai.config.personality` 在此共享设置未设置时仍会被读取。 ### `agents.defaults.heartbeat` @@ -495,13 +494,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 every: "30m", // 0m 表示禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // 默认值：true；false 会省略系统提示词中的 Heartbeat 部分 - lightContext: false, // 默认值：false；true 仅保留工作区引导文件中的 HEARTBEAT.md - isolatedSession: false, // 默认值：false；true 会让每次 heartbeat 在全新会话中运行（无会话历史） + includeSystemPromptSection: true, // 默认值：true；false 会从系统提示中省略 Heartbeat 部分 + lightContext: false, // 默认值：false；true 只保留工作区引导文件中的 HEARTBEAT.md + isolatedSession: false, // 默认值：false；true 会在全新会话中运行每次 heartbeat（无对话历史） session: "main", to: "+15555550123", - directPolicy: "allow", // allow（默认） | block - target: "none", // 默认值：none | 可选项：last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow（默认）| block + target: "none", // 默认值：none | 可选值：last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -513,14 +512,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ``` - `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 -- `includeSystemPromptSection`：当为 false 时，会省略系统提示词中的 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：当为 true 时，会在 heartbeat 运行期间抑制工具错误警告负载。 -- `timeoutSeconds`：heartbeat 智能体轮次在被中止之前允许的最长时间（秒）。留空则使用 `agents.defaults.timeoutSeconds`。 -- `directPolicy`：直接 / 私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：当为 true 时，heartbeat 运行会使用轻量级引导上下文，并且仅保留工作区引导文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：当为 true 时，每次 heartbeat 都会在一个没有先前会话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 的隔离模式相同。可将每次 heartbeat 的 token 成本从约 100K 降低到约 2-5K token。 +- `includeSystemPromptSection`：设为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。 +- `suppressToolErrorWarnings`：设为 true 时，会在 heartbeat 运行期间抑制工具错误警告负载。 +- `timeoutSeconds`：在 heartbeat 智能体轮次被中止前允许的最长秒数。若不设置，则使用 `agents.defaults.timeoutSeconds`。 +- `directPolicy`：直接 / 私信投递策略。`allow`（默认）允许直接目标投递。`block` 会阻止直接目标投递，并发出 `reason=dm-blocked`。 +- `lightContext`：设为 true 时，heartbeat 运行会使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：设为 true 时，每次 heartbeat 都会在一个没有任何先前对话历史的全新会话中运行。隔离模式与 cron `sessionTarget: "isolated"` 相同。可将每次 heartbeat 的 token 成本从约 100K 降低到约 2–5K token。 - 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。 -- Heartbeat 会运行完整的智能体轮次——更短的间隔会消耗更多 token。 +- Heartbeat 会运行完整的智能体轮次——间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -537,7 +536,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 model: "openrouter/anthropic/claude-sonnet-4-6", // 仅用于压缩的可选模型覆盖 - notifyUser: true, // 在压缩开始和完成时向用户发送简短通知（默认：false） + notifyUser: true, // 在压缩开始和完成时向用户发送简短通知（默认值：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -550,19 +549,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（对长历史进行分块摘要）。参见[压缩](/zh-CN/concepts/compaction)。 -- `provider`：已注册压缩提供商插件的 id。设置后，将调用该提供商的 `summarize()`，而不是内置的 LLM 摘要。失败时会回退到内置方案。设置 provider 会强制使用 `mode: "safeguard"`。参见[压缩](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 在中止之前允许单次压缩操作运行的最大秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要期间预置内置的不透明标识符保留指引。 +- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [压缩](/zh-CN/concepts/compaction)。 +- `provider`：已注册压缩提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是内置的 LLM 摘要功能。失败时会回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [压缩](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 中止单次压缩操作前允许的最大秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要时预先添加内置的不透明标识符保留指引。 - `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 -- `postCompactionSections`：压缩后重新注入的可选 `AGENTS.md` H2/H3 章节名称。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。当未设置，或显式设置为该默认对时，也接受较旧的 `Every Session` / `Safety` 标题作为旧版回退。 -- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖值。当你希望主会话保留一个模型，但压缩摘要应在另一个模型上运行时使用它；未设置时，压缩会使用会话的主模型。 -- `notifyUser`：当为 `true` 时，在压缩开始和完成时向用户发送简短通知（例如“正在压缩上下文...”和“压缩完成”）。默认禁用，以保持压缩静默。 +- `postCompactionSections`：压缩后重新注入的可选 `AGENTS.md` H2 / H3 节名称。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置或显式设为这对默认值时，也接受旧版的 `Every Session` / `Safety` 标题作为兼容回退。 +- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应继续使用一个模型，而压缩摘要应使用另一个模型时使用此项；未设置时，压缩会使用会话的主模型。 +- `notifyUser`：当为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如，“正在压缩上下文...” 和 “压缩完成”）。默认禁用，以保持压缩静默。 - `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在将内容发送到 LLM 之前，从内存中的上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在将上下文发送给 LLM 之前，从内存中的上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -586,23 +585,23 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 -- `mode: "cache-ttl"` 会启用修剪流程。 -- `ttl` 控制再次运行修剪的频率（在上次缓存触碰之后）。 -- 修剪会先对过大的工具结果进行软修剪，如有需要，再对更旧的工具结果进行硬清除。 +- `mode: "cache-ttl"` 会启用修剪过程。 +- `ttl` 控制再次允许执行修剪的频率（基于上次缓存触碰之后）。 +- 修剪会先对过大的工具结果执行软裁剪，然后在需要时对更旧的工具结果执行硬清除。 -**软修剪**会保留开头和结尾，并在中间插入 `...`。 +**软裁剪**会保留开头和结尾，并在中间插入 `...`。 -**硬清除**会用占位符替换整个工具结果。 +**硬清除**会用占位文本替换整个工具结果。 -注意： +说明： -- 图像块永远不会被修剪 / 清除。 -- 比例是基于字符的（近似值），而不是精确的 token 数。 -- 如果助手消息少于 `keepLastAssistants` 条，则会跳过修剪。 +- 图像区块永远不会被裁剪 / 清除。 +- 比例按字符数计算（近似值），不是精确 token 计数。 +- 如果助手消息少于 `keepLastAssistants` 条，则跳过修剪。 -行为细节请参见[会话修剪](/zh-CN/concepts/session-pruning)。 +行为详情请参见 [会话修剪](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -620,13 +619,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 -- 渠道覆盖项：`channels..blockStreamingCoalesce`（以及按账户的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500 ms。按智能体覆盖项：`agents.list[].humanDelay`。 +- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。 +- 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号的变体）。Signal / Slack / Discord / Google Chat 默认 `minChars: 1500`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节请参见[流式传输](/zh-CN/concepts/streaming)。 +行为和分块详情请参见 [流式传输](/zh-CN/concepts/streaming)。 -### 正在输入指示器 +### 输入状态指示器 ```json5 { @@ -639,16 +638,16 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：直接聊天 / 提及时为 `instant`，未被提及的群聊为 `message`。 -- 按会话覆盖项：`session.typingMode`、`session.typingIntervalSeconds`。 +- 默认值：直接聊天 / 提及时为 `instant`，未被提及的群聊中为 `message`。 +- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -参见[正在输入指示器](/zh-CN/concepts/typing-indicators)。 +参见 [输入状态指示器](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见[沙箱隔离](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -748,7 +747,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **后端：** - `docker`：本地 Docker 运行时（默认） -- `ssh`：通用 SSH 支持的远程运行时 +- `ssh`：通用的基于 SSH 的远程运行时 - `openshell`：OpenShell 运行时 当选择 `backend: "openshell"` 时，运行时特定设置会移动到 @@ -756,31 +755,31 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **SSH 后端配置：** -- `target`：`user@host[:port]` 格式的 SSH 目标 -- `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域工作区的远程绝对根目录 +- `target`：`user@host[:port]` 形式的 SSH 目标 +- `command`：SSH 客户端命令（默认值：`ssh`） +- `workspaceRoot`：用于按作用域划分工作区的远程绝对根路径 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 -- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其物化为临时文件 -- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略控制项 +- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 +- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 **SSH 认证优先级：** - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前激活的 secrets 运行时快照中解析 +- 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前从当前活动的 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后，会先向远程工作区植入一次初始内容 -- 然后保持远程 SSH 工作区为规范副本 +- 在创建或重建后仅为远程工作区执行一次初始化播种 +- 然后保持远程 SSH 工作区为标准副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 -- 不会自动将远程变更同步回主机 +- 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 **工作区访问：** -- `none`：位于 `~/.openclaw/sandboxes` 下、按作用域划分的沙箱工作区 +- `none`：在 `~/.openclaw/sandboxes` 下为每个作用域创建沙箱工作区 - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` @@ -818,30 +817,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在执行前将本地内容植入远程，执行后再同步回本地；本地工作区保持为规范副本 -- `remote`：在创建沙箱时仅向远程植入一次初始内容，之后保持远程工作区为规范副本 +- `mirror`：在执行前从本地向远程播种，执行后再同步回本地；本地工作区保持为标准副本 +- `remote`：在创建沙箱时仅向远程播种一次，之后保持远程工作区为标准副本 -在 `remote` 模式下，种子步骤完成后，在 OpenClaw 外部于主机本地所做的编辑不会自动同步到沙箱中。 +在 `remote` 模式下，在 OpenClaw 之外于主机本地所做的编辑，在播种步骤之后不会自动同步进沙箱。 传输方式是通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 -**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 +**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统以及 root 用户。 -**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -`"host"` 被禁止。默认也禁止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急放行）。 +**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 +默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破玻璃紧急开关）。 -**入站附件** 会被暂存到活动工作区中的 `media/inbound/*`。 +**入站附件** 会暂存到活动工作区中的 `media/inbound/*`。 -**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的挂载会合并。 +**`docker.binds`** 会挂载其他主机目录；全局和按智能体的 binds 会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行的 Chromium + CDP。noVNC URL 会注入系统提示词中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -默认情况下，noVNC 观察者访问使用 VNC 认证，OpenClaw 会发出一个短时效 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示中。无需在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话将目标指向主机浏览器。 -- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确想要全局 bridge 连通性时，才设置为 `bridge`。 -- `cdpSourceRange` 可选，用于在容器边界将 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替代浏览器容器上的 `docker.binds`。 -- 启动默认值定义于 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： +- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 +- `network` 默认是 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时，才设置为 `bridge`。 +- `cdpSourceRange` 可选地将容器边界上的 CDP 入站访问限制到某个 CIDR 范围内（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 只会将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 +- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器宿主机做了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -860,15 +859,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `--metrics-recording-only` - `--disable-extensions`（默认启用） - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用；如果 WebGL / 3D 使用场景需要，可通过 + 默认启用；如果 WebGL / 3D 使用场景需要它们，可通过 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流 - 依赖它们。 + - 如果你的工作流依赖扩展，可通过 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` + 重新启用扩展。 - `--renderer-process-limit=2` 可通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设置为 `0` 可使用 Chromium 的 默认进程限制。 - 以及当启用 `noSandbox` 时附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义 + - 默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义 entrypoint 的自定义浏览器镜像。 @@ -896,11 +895,11 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } thinkingDefault: "high", // 按智能体覆盖 thinking 级别 - reasoningDefault: "on", // 按智能体覆盖推理可见性 - fastModeDefault: false, // 按智能体覆盖快速模式 + reasoningDefault: "on", // 按智能体覆盖 reasoning 可见性 + fastModeDefault: false, // 按智能体覆盖 fast mode embeddedHarness: { runtime: "auto", fallback: "pi" }, params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params - skills: ["docs-search"], // 设置后将替换 agents.defaults.skills + skills: ["docs-search"], // 设置后会替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -932,26 +931,26 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` - `id`：稳定的智能体 id（必填）。 -- `default`：当设置了多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。 -- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局回退）。只覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 -- `params`：按智能体设置的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。用于设置该智能体专属的覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。如果省略，则在已设置时，智能体会继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示不使用任何 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话的覆盖项时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。当未设置按消息或按会话的推理覆盖项时生效。 -- `fastModeDefault`：可选的按智能体默认快速模式（`true | false`）。当未设置按消息或按会话的快速模式覆盖项时生效。 -- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某个智能体仅使用 Codex，而其他智能体仍在 `auto` 模式下保持默认的 PI 回退。 -- `runtime`：可选的按智能体运行时描述符。当该智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 和 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 -- `identity.avatar`：相对工作区路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name` / `emoji`。 -- `subagents.allowAgents`：`sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅相同智能体）。 -- 沙箱继承保护：如果请求方会话已处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。 -- `subagents.requireAgentId`：当为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置档；默认：false）。 +- `default`：当设置了多个时，第一个生效（会记录警告）。如果一个都没设，列表中的第一个条目就是默认值。 +- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局 fallbacks）。只覆盖 `primary` 的 cron 作业仍会继承默认 fallbacks，除非你设置 `fallbacks: []`。 +- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中所选模型条目之上。用于智能体特定覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 +- `skills`：可选的按智能体 Skills 允许列表。如果省略，在设置了 `agents.defaults.skills` 时，该智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。 +- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选 provider / model 配置决定了哪些值有效；对于 Google Gemini，`adaptive` 会保留由提供商管理的动态 thinking（Gemini 3 / 3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。 +- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话的 reasoning 覆盖时生效。 +- `fastModeDefault`：可选的按智能体默认 fast mode（`true | false`）。当未设置按消息或按会话的 fast mode 覆盖时生效。 +- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某一个智能体仅使用 Codex，而其他智能体仍保留默认的 `auto` 模式 PI 回退。 +- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 并配合 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 +- `identity` 会派生默认值：`ackReaction` 取自 `emoji`，`mentionPatterns` 取自 `name` / `emoji`。 +- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅相同智能体）。 +- 沙箱继承保护：如果请求方会话已处于沙箱隔离中，`sessions_spawn` 会拒绝那些本应在非沙箱隔离环境中运行的目标。 +- `subagents.requireAgentId`：设为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关中运行多个相互隔离的智能体。参见[多智能体](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关中运行多个彼此隔离的智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -970,29 +969,29 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认为 route），持久化 ACP 会话绑定使用 `acp`。 +- `type`（可选）：普通路由使用 `route`（缺失时默认是 route），持久 ACP 对话绑定使用 `acp`。 - `match.channel`（必填） -- `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户） +- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；特定于渠道） -- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId`（可选；渠道特定） +- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }` -**确定性匹配顺序：** +**确定性的匹配顺序：** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（精确匹配，无 peer/guild/team） +4. `match.accountId`（精确匹配，无 peer / guild / team） 5. `match.accountId: "*"`（整个渠道范围） 6. 默认智能体 在每个层级内，第一条匹配的 `bindings` 条目胜出。 -对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + account + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。 +对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份解析（`match.channel` + account + `match.peer.id`），不会使用上述 route 绑定层级顺序。 -### 按智能体访问配置档 +### 按智能体划分的访问配置 - + ```json5 { @@ -1085,7 +1084,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 -优先级细节请参见[多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 +关于优先级详情，请参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- @@ -1111,7 +1110,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程分叉（0 表示禁用） + parentForkMaxTokens: 100000, // 高于此 token 数时跳过父线程分叉（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1123,8 +1122,8 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 }, threadBindings: { enabled: true, - idleHours: 24, // 默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用） - maxAgeHours: 0, // 默认按小时计算的硬性最大时长（`0` 表示禁用） + idleHours: 24, // 默认按小时计算的无活动自动取消聚焦时间（`0` 表示禁用） + maxAgeHours: 0, // 默认按小时计算的硬性最大年龄（`0` 表示禁用） }, mainKey: "main", // 旧版字段（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, @@ -1139,34 +1138,34 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在渠道上下文中，每个发送者都有独立的会话。 - - `global`：渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 + - `per-sender`（默认）：在某个渠道上下文中，每个发送者都有独立会话。 + - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在明确需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - `per-peer`：按发送者 id 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - - `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（推荐用于多账户）。 -- **`identityLinks`**：将规范 id 映射到带 provider 前缀的 peer，用于跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。当两者都已配置时，先到期者生效。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍接受为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建分叉线程会话时，允许父会话 `totalTokens` 的最大值（默认 `100000`）。 - - 如果父会话 `totalTokens` 超过该值，OpenClaw 会启动一个新的线程会话，而不是继承父 transcript 历史。 - - 设置为 `0` 可禁用此保护，并始终允许父会话分叉。 -- **`mainKey`**：旧版字段。运行时始终对主直接聊天桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体之间交流时，代理间往返回复的最大轮数（整数，范围：`0`–`5`）。`0` 会禁用乒乓式链式回复。 -- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 仍可作为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 规则优先。 + - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 +- **`identityLinks`**：将标准 id 映射到带提供商前缀的 peer，以便跨渠道共享会话。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都配置时，以先到期者为准。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 也可作为 `direct` 的别名使用。 +- **`parentForkMaxTokens`**：创建分叉线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 + - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父 transcript 历史。 + - 设置为 `0` 可禁用此保护，并始终允许从父会话分叉。 +- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 +- **`agentToAgent.maxPingPongTurns`**：在智能体之间交互时，智能体间来回回复的最大轮次（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式交互。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版别名 `dm` 也可用）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 规则优先。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 只发出警告；`enforce` 会执行清理。 - - `pruneAfter`：陈旧条目的年龄截止时间（默认 `30d`）。 - - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过此大小时进行轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` transcript 存档的保留时间。默认与 `pruneAfter` 相同；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的制品 / 会话。 + - `mode`：`warn` 只发出警告；`enforce` 会实际执行清理。 + - `pruneAfter`：过期条目的年龄截止时间（默认 `30d`）。 + - `maxEntries`：`sessions.json` 中条目的最大数量（默认 `500`）。 + - `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` transcript 归档的保留时长。默认继承 `pruneAfter`；设置为 `false` 可禁用。 + - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的制品 / 会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - - `enabled`：主默认开关（provider 可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用；provider 可覆盖） - - `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 表示禁用；provider 可覆盖） + - `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） + - `idleHours`：默认按小时计算的无活动自动取消聚焦时间（`0` 表示禁用；提供商可以覆盖） + - `maxAgeHours`：默认按小时计算的硬性最大年龄（`0` 表示禁用；提供商可以覆盖） @@ -1204,36 +1203,36 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ### 响应前缀 -按渠道 / 账户覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道 / 账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 -解析顺序（越具体越优先）：账户 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 +解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会推导为 `[{identity.name}]`。 **模板变量：** -| 变量 | 描述 | 示例 | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | 简短模型名 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`, `low`, `off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ----------------- | ------------------ | --------------------------- | +| `{model}` | 简短模型名 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 ### 确认反应 -- 默认使用当前智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。 +- 默认取当前活动智能体的 `identity.emoji`，否则为 `"👀"`。设置 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 -- 解析顺序：账户 → 渠道 → `messages.ackReaction` → identity 回退值。 -- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 -- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。 +- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退值。 +- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上会在回复后移除确认反应。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时，当确认反应处于活动状态时会保持状态反应启用。 - 在 Telegram 上，需要显式将其设为 `true` 才会启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时如果确认反应处于启用状态，则状态反应也保持启用。 + 在 Telegram 上，需要显式将它设为 `true` 才会启用生命周期状态反应。 ### 入站防抖 -将来自同一发送者的快速纯文本消息批处理为一个智能体轮次。媒体 / 附件会立即刷新。控制命令会绕过防抖。 +将来自同一发送者的快速纯文本消息批量合并为一个智能体轮次。媒体 / 附件会立即刷新。控制命令会绕过防抖。 ### TTS（文本转语音） @@ -1276,18 +1275,18 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 -- `summaryModel` 会覆盖自动摘要使用的 `agents.defaults.model.primary`。 -- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。 +- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 +- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 +- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式开启）。 - API 密钥会回退到 `ELEVENLABS_API_KEY` / `XI_API_KEY` 和 `OPENAI_API_KEY`。 - `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 -- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型 / 语音校验。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型 / 语音校验。 --- ## 通话 -通话模式默认值（macOS / iOS / Android）。 +Talk 模式的默认值（macOS / iOS / Android）。 ```json5 { @@ -1311,17 +1310,17 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像 } ``` -- `talk.provider` 在配置了多个通话提供商时，必须与 `talk.providers` 中的某个键匹配。 -- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 -- Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 +- `talk.provider` 在配置了多个 Talk 提供商时必须匹配 `talk.providers` 中的某个键。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 +- Voice id 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 仅当未配置任何通话 API 密钥时，才会应用 `ELEVENLABS_API_KEY` 回退。 -- `providers.*.voiceAliases` 允许通话指令使用友好名称。 -- `silenceTimeoutMs` 控制通话模式在用户静音后等待多久才发送 transcript。未设置时将保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- 仅当未配置 Talk API 密钥时，才会使用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久再发送 transcript。未设置时会保留平台默认的停顿窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。 --- -## 相关 +## 相关内容 - [配置参考](/zh-CN/gateway/configuration-reference) — 所有其他配置键 - [配置](/zh-CN/gateway/configuration) — 常见任务和快速设置 diff --git a/docs/zh-CN/help/testing-live.md b/docs/zh-CN/help/testing-live.md index f48f0cf53..382647316 100644 --- a/docs/zh-CN/help/testing-live.md +++ b/docs/zh-CN/help/testing-live.md @@ -7,15 +7,15 @@ sidebarTitle: Live tests summary: 实时（涉及网络）的测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证 title: 测试：实时测试套件 x-i18n: - generated_at: "2026-04-24T20:30:51Z" + generated_at: "2026-04-25T01:27:29Z" model: gpt-5.4 provider: openai - source_hash: 946a5f0c112cb86c45c690f62e737a8deed99440bedfcad07e8d7aabeda59495 + source_hash: 1befd32c3bd02d29b80d319b45c1e5496741866eba94f6923b20306837610706 source_path: help/testing-live.md workflow: 15 --- -有关快速开始、QA 运行器、单元/集成测试套件以及 Docker 流程，请参阅 +对于快速开始、QA 运行器、单元 / 集成测试套件以及 Docker 流程，请参见 [测试](/zh-CN/help/testing)。本页介绍**实时**（涉及网络）的测试 套件：模型矩阵、CLI 后端、ACP 和媒体提供商实时测试，以及 凭证处理。 @@ -24,88 +24,88 @@ x-i18n: - 测试：`src/gateway/android-node.capabilities.live.test.ts` - 脚本：`pnpm android:test:integration` -- 目标：调用已连接 Android 节点当前**通告的每一条命令**，并断言命令契约行为。 +- 目标：调用已连接 Android 节点**当前公布的每一条命令**，并断言命令契约行为。 - 范围： - - 需预先完成/手动设置（该测试套件不会安装/运行/配对应用）。 - - 针对所选 Android 节点，逐条命令验证 Gateway 网关 `node.invoke`。 -- 所需预先设置： - - Android 应用已连接并与 Gateway 网关完成配对。 + - 带前置条件的 / 手动设置（该测试套件不会安装 / 运行 / 配对应用）。 + - 对所选 Android 节点逐命令执行 Gateway 网关 `node.invoke` 验证。 +- 必需的预先设置： + - Android 应用已连接并已与 Gateway 网关配对。 - 应用保持在前台。 - - 已为你期望通过的能力授予权限/采集同意。 + - 你预期要通过的能力所需的权限 / 捕获授权已授予。 - 可选目标覆盖： - `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。 - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。 -- 完整 Android 设置详情： [Android App](/zh-CN/platforms/android) +- 完整 Android 设置详情：[Android App](/zh-CN/platforms/android) -## 实时：模型冒烟测试（配置档案键） +## 实时：模型冒烟测试（profile keys） -实时测试分为两层，这样我们就能隔离故障： +实时测试分为两层，以便我们隔离故障： -- “直接模型”告诉我们，在给定密钥的情况下，提供商/模型是否至少能够响应。 -- “Gateway 冒烟测试”告诉我们，该模型的完整 Gateway 网关 + 智能体流水线是否正常工作（会话、历史记录、工具、沙箱策略等）。 +- “Direct model” 用于判断在给定密钥下，提供商 / 模型是否至少能够响应。 +- “Gateway smoke” 用于判断该模型的完整 Gateway 网关 + 智能体流水线是否正常工作（会话、历史记录、工具、沙箱策略等）。 -### 第 1 层：直接模型补全（无 Gateway 网关） +### 第 1 层：直接模型补全（无网关） - 测试：`src/agents/models.profiles.live.test.ts` - 目标： - - 枚举发现到的模型 + - 枚举已发现的模型 - 使用 `getApiKeyForModel` 选择你拥有凭证的模型 - 为每个模型运行一个小型补全测试（并在需要时运行定向回归测试） - 启用方式： - `pnpm test:live`（如果直接调用 Vitest，则使用 `OPENCLAW_LIVE_TEST=1`） -- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 `modern` 的别名）后，此测试套件才会实际运行；否则会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 冒烟测试 +- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 `modern` 的别名）才会实际运行此测试套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试 - 选择模型的方式： - - `OPENCLAW_LIVE_MODELS=modern` 运行现代允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4） + - `OPENCLAW_LIVE_MODELS=modern` 运行现代允许列表（Opus / Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4） - `OPENCLAW_LIVE_MODELS=all` 是现代允许列表的别名 - 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."`（逗号分隔的允许列表） - - modern/all 扫描默认使用精心挑选的高信号上限；将 `OPENCLAW_LIVE_MAX_MODELS=0` 设为完整的 modern 扫描，或设为正数以使用更小的上限。 - - 完整扫描对整个直接模型测试超时使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS`。默认值：60 分钟。 + - modern / all 扫描默认使用精心挑选的高信号上限；将 `OPENCLAW_LIVE_MAX_MODELS=0` 设为完整 modern 扫描，或设为正数以使用更小的上限。 + - 完整扫描会对整个直接模型测试超时使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS`。默认值：60 分钟。 - 直接模型探测默认使用 20 路并行；可设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY` 进行覆盖。 - 选择提供商的方式： - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的允许列表） - 密钥来源： - - 默认：配置档案存储和环境变量回退 - - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用配置档案存储** -- 存在此层的原因： + - 默认：profile 存储和环境变量回退 + - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制只使用 **profile store** +- 存在意义： - 将“提供商 API 已损坏 / 密钥无效”与“Gateway 网关智能体流水线已损坏”区分开来 - - 包含小型、隔离的回归测试（例如：OpenAI Responses/Codex Responses 推理回放 + 工具调用流程） + - 包含小型、隔离的回归测试（例如：OpenAI Responses / Codex Responses 推理回放 + 工具调用流程） -### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（也就是 “@openclaw” 实际执行的内容） +### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（即 “@openclaw” 实际做的事） - 测试：`src/gateway/gateway-models.profiles.live.test.ts` - 目标： - - 启动一个进程内 Gateway 网关 - - 创建/修补一个 `agent:dev:*` 会话（每次运行覆盖模型） + - 启动进程内 Gateway 网关 + - 创建 / 修补一个 `agent:dev:*` 会话（每次运行按模型覆盖） - 遍历带密钥的模型并断言： - - “有意义”的响应（无工具） - - 一次真实工具调用可正常工作（读取探测） - - 可选的额外工具探测（exec+read 探测） - - OpenAI 回归路径（仅工具调用 → 后续跟进）保持可用 + - 有“有意义”的响应（无工具） + - 真实工具调用可正常工作（读取探测） + - 可选的额外工具探测（exec + read 探测） + - OpenAI 回归路径（仅工具调用 → 后续跟进）持续正常 - 探测细节（便于你快速解释故障）： - `read` 探测：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件并回显 nonce。 - - `exec+read` 探测：测试要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 读回。 - - 图像探测：测试附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat `。 + - `exec+read` 探测：测试会要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 读回。 + - 图像探测：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat `。 - 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。 - 启用方式： - `pnpm test:live`（如果直接调用 Vitest，则使用 `OPENCLAW_LIVE_TEST=1`） - 选择模型的方式： - - 默认：现代允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4） + - 默认：现代允许列表（Opus / Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4） - `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代允许列表的别名 - 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）来缩小范围 - - modern/all Gateway 网关扫描默认使用精心挑选的高信号上限；将 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 设为完整的 modern 扫描，或设为正数以使用更小的上限。 -- 选择提供商的方式（避免变成 “OpenRouter 全部都测”）： + - modern / all Gateway 网关扫描默认使用精心挑选的高信号上限；将 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 设为完整 modern 扫描，或设为正数以使用更小的上限。 +- 选择提供商的方式（避免“OpenRouter 全量”）： - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔的允许列表） -- 工具 + 图像探测在此实时测试中始终启用： +- 工具和图像探测在此实时测试中始终开启： - `read` 探测 + `exec+read` 探测（工具压力测试） - 当模型声明支持图像输入时，会运行图像探测 - - 流程（高层概述）： + - 流程（高层）： - 测试生成一个带有 “CAT” + 随机代码的小型 PNG（`src/gateway/live-image-probe.ts`） - - 通过 `agent` `attachments: [{ mimeType: "image/png", content: "" }]` 发送它 - - Gateway 网关将附件解析到 `images[]` 中（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） - - 嵌入式智能体将多模态用户消息转发给模型 - - 断言：回复包含 `cat` + 该代码（OCR 容差：允许轻微错误） + - 通过 `agent` `attachments: [{ mimeType: "image/png", content: "" }]` 发送 + - Gateway 网关将附件解析到 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） + - 内嵌智能体将多模态用户消息转发给模型 + - 断言：回复包含 `cat` + 该代码（OCR 容错：允许轻微错误） -提示：要查看你在自己机器上可以测试什么（以及精确的 `provider/model` id），请运行： +提示：要查看你的机器上可以测试什么（以及精确的 `provider/model` id），请运行： ```bash openclaw models list @@ -116,21 +116,21 @@ openclaw models list --json - 测试：`src/gateway/gateway-cli-backend.live.test.ts` - 目标：在不触碰你的默认配置的情况下，使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线。 -- 特定于后端的冒烟测试默认值位于所属扩展的 `cli-backend.ts` 定义中。 +- 各后端的默认冒烟设置位于所属扩展的 `cli-backend.ts` 定义中。 - 启用： - `pnpm test:live`（如果直接调用 Vitest，则使用 `OPENCLAW_LIVE_TEST=1`） - `OPENCLAW_LIVE_CLI_BACKEND=1` - 默认值： - - 默认提供商/模型：`claude-cli/claude-sonnet-4-6` - - 命令/参数/图像行为来自所属 CLI 后端插件元数据。 + - 默认提供商 / 模型：`claude-cli/claude-sonnet-4-6` + - 命令 / 参数 / 图像行为来自所属 CLI 后端插件元数据。 - 覆盖项（可选）： - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会注入到提示中）。 - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 通过 CLI 参数传递图像文件路径，而不是通过提示注入。 - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）在设置 `IMAGE_ARG` 时控制图像参数的传递方式。 - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮并验证恢复流程。 + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 通过 CLI 参数传递图像文件路径，而不是注入提示。 + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）用于在设置了 `IMAGE_ARG` 时控制图像参数的传递方式。 + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮消息并验证恢复流程。 - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` 禁用默认的 Claude Sonnet -> Opus 同会话连续性探测（当所选模型支持切换目标时，设为 `1` 可强制启用）。 示例： @@ -141,13 +141,13 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Docker 用法： +Docker 配方： ```bash pnpm test:docker:live-cli-backend ``` -单提供商 Docker 用法： +单提供商 Docker 配方： ```bash pnpm test:docker:live-cli-backend:claude @@ -159,18 +159,18 @@ pnpm test:docker:live-cli-backend:gemini 说明： - Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。 -- 它在仓库 Docker 镜像内以非 root 的 `node` 用户运行实时 CLI 后端冒烟测试。 -- 它从所属扩展解析 CLI 冒烟测试元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到缓存的可写前缀 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 中（默认值：`~/.cache/openclaw/docker-cli-tools`）。 -- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可移植的 Claude Code 订阅 OAuth，可通过 `~/.claude/.credentials.json` 中的 `claudeAiOauth.subscriptionType` 或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它会先在 Docker 中直接验证 `claude -p`，然后在不保留 Anthropic API 密钥环境变量的情况下运行两轮 Gateway 网关 CLI 后端测试。该订阅通道默认禁用 Claude MCP/工具和图像探测，因为 Claude 当前会将第三方应用使用路由到额外用量计费，而不是普通订阅套餐限额。 -- 实时 CLI 后端冒烟测试现在对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮次、图像分类轮次，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。 -- Claude 的默认冒烟测试还会将会话从 Sonnet 修补到 Opus，并验证恢复后的会话仍然记得较早的备注。 +- 它会在仓库 Docker 镜像中以非 root 的 `node` 用户身份运行实时 CLI 后端冒烟测试。 +- 它会从所属扩展解析 CLI 冒烟元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到可缓存、可写的前缀目录 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 中（默认：`~/.cache/openclaw/docker-cli-tools`）。 +- `pnpm test:docker:live-cli-backend:claude-subscription` 要求通过 `~/.claude/.credentials.json` 中的 `claudeAiOauth.subscriptionType`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN`，提供可移植的 Claude Code 订阅 OAuth。它会先在 Docker 中验证直接 `claude -p`，然后在不保留 Anthropic API 密钥环境变量的情况下运行两轮 Gateway 网关 CLI 后端测试。该订阅测试默认禁用 Claude MCP / 工具和图像探测，因为 Claude 当前会将第三方应用使用量计入额外使用计费，而不是普通订阅计划额度。 +- 该实时 CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮次、图像分类轮次，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。 +- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得先前的备注。 ## 实时：ACP 绑定冒烟测试（`/acp spawn ... --bind here`） - 测试：`src/gateway/gateway-acp-bind.live.test.ts` -- 目标：使用实时 ACP 智能体验证真实的 ACP 会话绑定流程： +- 目标：使用实时 ACP 智能体验证真实 ACP 会话绑定流程： - 发送 `/acp spawn --bind here` - - 就地绑定一个合成的消息渠道会话 + - 原地绑定一个合成的消息渠道会话 - 在同一会话上发送普通后续消息 - 验证后续消息落入已绑定的 ACP 会话记录中 - 启用： @@ -178,7 +178,7 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND=1` - 默认值： - Docker 中的 ACP 智能体：`claude,codex,gemini` - - 直接通过 `pnpm test:live ...` 使用的 ACP 智能体：`claude` + - 用于直接 `pnpm test:live ...` 的 ACP 智能体：`claude` - 合成渠道：Slack 私信风格的会话上下文 - ACP 后端：`acpx` - 覆盖项： @@ -190,8 +190,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.2` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.2` - 说明： - - 此测试通道使用 Gateway 网关 `chat.send` 接口，并带有仅管理员可用的合成 originating-route 字段，这样测试就能附加消息渠道上下文，而无需伪装为外部投递。 - - 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会对所选 ACP harness 智能体使用嵌入式 `acpx` 插件的内置智能体注册表。 + - 该测试路径使用 Gateway 网关 `chat.send` 接口，并带有仅限管理员使用的合成 originating-route 字段，这样测试就可以附加消息渠道上下文，而无需假装进行外部投递。 + - 当 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 未设置时，测试会使用内嵌 `acpx` 插件的内置智能体注册表来获取所选 ACP harness 智能体。 示例： @@ -201,13 +201,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Docker 用法： +Docker 配方： ```bash pnpm test:docker:live-acp-bind ``` -单智能体 Docker 用法： +单智能体 Docker 配方： ```bash pnpm test:docker:live-acp-bind:claude @@ -218,10 +218,10 @@ pnpm test:docker:live-acp-bind:gemini Docker 说明： - Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。 -- 默认情况下，它会依次针对所有受支持的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后是 `gemini`。 -- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 可缩小矩阵范围。 -- 它会加载 `~/.profile`，将匹配的 CLI 身份验证材料暂存到容器中，把 `acpx` 安装到可写 npm 前缀中，然后在缺失时安装所请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。 -- 在 Docker 内部，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，以便 acpx 让来自已加载 profile 的提供商环境变量继续对其子 harness CLI 可用。 +- 默认情况下，它会按顺序针对所有受支持的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后 `gemini`。 +- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 可以缩小矩阵范围。 +- 它会 source `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，在可写 npm 前缀中安装 `acpx`，然后在缺失时安装所请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。 +- 在 Docker 内部，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，以便 acpx 保留 source 后的 profile 中提供商环境变量，并将其提供给子 harness CLI。 ## 实时：Codex app-server harness 冒烟测试 @@ -229,28 +229,27 @@ Docker 说明： `agent` 方法验证插件自有的 Codex harness： - 加载内置的 `codex` 插件 - 选择 `OPENCLAW_AGENT_RUNTIME=codex` - - 向 `openai/gpt-5.2` 发送首个 Gateway 网关智能体轮次，并强制使用 Codex harness - - 向同一个 OpenClaw 会话发送第二个轮次，并验证 app-server + - 在强制使用 Codex harness 的情况下，向 `openai/gpt-5.2` 发送第一轮 Gateway 网关智能体请求 + - 向同一个 OpenClaw 会话发送第二轮请求，并验证 app-server 线程可以恢复 - - 通过同一 Gateway 网关命令 + - 通过相同的 Gateway 网关命令 路径运行 `/codex status` 和 `/codex models` - - 可选运行两个经 Guardian 审核的提权 shell 探测：一个应被批准的 - 无害命令，以及一个应被拒绝的伪造密钥上传操作， - 从而让智能体回问 + - 可选运行两个经 Guardian 审核的提权 shell 探测：一个应被批准的无害 + 命令，以及一个应被拒绝的伪造密钥上传操作， + 以便智能体回头询问 - 测试：`src/gateway/gateway-codex-harness.live.test.ts` - 启用：`OPENCLAW_LIVE_CODEX_HARNESS=1` - 默认模型：`openai/gpt-5.2` - 可选图像探测：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- 可选 MCP/工具探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- 可选 MCP / 工具探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - 可选 Guardian 探测：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，这样损坏的 Codex - harness 就不能通过静默回退到 PI - 而蒙混过关。 +- 该冒烟测试设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，这样损坏的 Codex + harness 就无法通过静默回退到 PI 而蒙混过关。 - 认证：Codex app-server 认证来自本地 Codex 订阅登录。Docker - 冒烟测试在适用时也可以提供 `OPENAI_API_KEY` - 用于非 Codex 探测，并可选复制 `~/.codex/auth.json` 和 `~/.codex/config.toml`。 + 冒烟测试在适用时还可以提供 `OPENAI_API_KEY` 用于非 Codex 探测， + 另外还可选复制 `~/.codex/auth.json` 和 `~/.codex/config.toml`。 -本地用法： +本地配方： ```bash source ~/.profile @@ -262,7 +261,7 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Docker 用法： +Docker 配方： ```bash source ~/.profile @@ -272,50 +271,55 @@ pnpm test:docker:live-codex-harness Docker 说明： - Docker 运行器位于 `scripts/test-live-codex-harness-docker.sh`。 -- 它会加载挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI - 认证文件，将 `@openai/codex` 安装到可写的挂载 npm - 前缀中，暂存源代码树，然后仅运行 Codex-harness 实时测试。 -- Docker 默认启用图像、MCP/工具和 Guardian 探测。需要更窄范围的调试 - 运行时，请设置 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或 +- 它会 source 挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI + 认证文件，将 `@openai/codex` 安装到一个可写、已挂载的 npm + 前缀中，暂存源码树，然后只运行 Codex-harness 实时测试。 +- Docker 默认启用图像、MCP / 工具和 Guardian 探测。需要更窄范围的调试 + 运行时，可设置 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。 - Docker 还会导出 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，与实时 - 测试配置一致，因此旧别名或回退到 PI 都无法掩盖 Codex harness + 测试配置保持一致，这样旧别名或回退到 PI 就无法掩盖 Codex harness 回归问题。 -### 推荐的实时测试用法 +### 推荐的实时测试配方 -范围明确的收窄允许列表速度最快，也最不容易出现不稳定： +范围窄且显式的允许列表速度最快，也最不容易出现不稳定情况： -- 单模型，直接（无 Gateway 网关）： +- 单模型，直接模式（无网关）： - `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts` - 单模型，Gateway 网关冒烟测试： - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- 跨多个提供商的工具调用： +- 多个提供商上的工具调用： - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Google 重点测试（Gemini API 密钥 + Antigravity）： +- Google 聚焦（Gemini API 密钥 + Antigravity）： - Gemini（API 密钥）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Google 自适应思考冒烟测试： + - 如果本地密钥位于 shell profile 中：`source ~/.profile` + - Gemini 3 动态默认值：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000` + - Gemini 2.5 动态预算：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000` + 说明： - `google/...` 使用 Gemini API（API 密钥）。 -- `google-antigravity/...` 使用 Antigravity OAuth 桥接（Cloud Code Assist 风格的智能体端点）。 +- `google-antigravity/...` 使用 Antigravity OAuth 桥（Cloud Code Assist 风格的智能体端点）。 - `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（单独的认证 + 工具行为差异）。 - Gemini API 与 Gemini CLI： - - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / 配置档案认证）；这也是大多数用户所说的 “Gemini”。 - - CLI：OpenClaw 调用本地 `gemini` 二进制程序；它有自己的认证方式，行为也可能不同（流式传输/工具支持/版本偏差）。 + - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / profile 认证）；这也是大多数用户提到 “Gemini” 时的含义。 + - CLI：OpenClaw 会调用本地 `gemini` 二进制；它有自己的认证机制，并且行为可能不同（流式传输 / 工具支持 / 版本偏差）。 -## 实时：模型矩阵（我们覆盖什么） +## 实时：模型矩阵（我们的覆盖范围） -没有固定的 “CI 模型列表”（实时测试是可选启用的），但以下是建议在有密钥的开发机器上定期覆盖的**推荐**模型。 +没有固定的 “CI 模型列表”（实时测试为可选启用），但以下是在带有密钥的开发机器上建议定期覆盖的**推荐**模型。 ### 现代冒烟测试集（工具调用 + 图像） -这是我们预期应持续保持可用的 “常用模型” 运行集： +这是我们期望持续可用的 “常见模型” 运行集合： - OpenAI（非 Codex）：`openai/gpt-5.2` - OpenAI Codex OAuth：`openai-codex/gpt-5.2` @@ -340,51 +344,51 @@ Docker 说明： - Z.AI（GLM）：`zai/glm-4.7` - MiniMax：`minimax/MiniMax-M2.7` -可选的额外覆盖（有更好，没有也可以）： +可选的额外覆盖（有更好，没有也行）： - xAI：`xai/grok-4`（或最新可用版本） -- Mistral：`mistral/`…（选择一个你已启用、支持 “tools” 的模型） +- Mistral：`mistral/`…（选择一个你已启用、支持工具的模型） - Cerebras：`cerebras/`…（如果你有访问权限） - LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式） -### 视觉：图像发送（附件 → 多模态消息） +### Vision：图像发送（附件 → 多模态消息） -在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude/Gemini/支持视觉的 OpenAI 变体等），以覆盖图像探测。 +在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude / Gemini / OpenAI 的支持视觉的变体等），以覆盖图像探测。 ### 聚合器 / 替代 Gateway 网关 -如果你已启用相应密钥，我们也支持通过以下方式测试： +如果你已启用相应密钥，我们也支持通过以下方式进行测试： -- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选模型） +- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选项） - OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证） -你还可以在实时矩阵中加入更多提供商（如果你有凭证/配置）： +你还可以加入实时矩阵的更多提供商（前提是你有凭证 / 配置）： - 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot` -- 通过 `models.providers`（自定义端点）：`minimax`（云/API），以及任何兼容 OpenAI/Anthropic 的代理（LM Studio、vLLM、LiteLLM 等） +- 通过 `models.providers`（自定义端点）：`minimax`（云 / API），以及任何兼容 OpenAI / Anthropic 的代理（LM Studio、vLLM、LiteLLM 等） -提示：不要尝试在文档中硬编码 “所有模型”。权威列表始终是你的机器上 `discoverModels(...)` 返回的内容，以及当前可用的密钥。 +提示：不要试图在文档中硬编码 “所有模型”。权威列表就是你的机器上 `discoverModels(...)` 返回的内容，加上当前可用的密钥。 ## 凭证（切勿提交） -实时测试发现凭证的方式与 CLI 完全相同。实际含义如下： +实时测试以与 CLI 相同的方式发现凭证。实际含义如下： -- 如果 CLI 可用，实时测试也应该能找到相同的密钥。 -- 如果实时测试提示 “no creds”，请像调试 `openclaw models list` / 模型选择那样进行调试。 +- 如果 CLI 能正常工作，实时测试也应能找到相同的密钥。 +- 如果实时测试提示 “no creds”，请用与调试 `openclaw models list` / 模型选择相同的方法进行调试。 -- 每个智能体的认证配置档案：`~/.openclaw/agents//agent/auth-profiles.json`（这就是实时测试中 “profile keys” 的含义） +- 按智能体划分的认证 profile：`~/.openclaw/agents//agent/auth-profiles.json`（这就是实时测试中 “profile keys” 的含义） - 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`） -- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时测试 home 中，但它不是主配置档案密钥存储） -- 本地实时运行默认会将当前活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到临时测试 home 中；暂存的实时测试 home 会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，这样探测就不会落到你的真实主机工作区中。 +- 旧状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时测试 home 中，但这不是主要的 profile-key 存储） +- 本地实时运行默认会将活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到临时测试 home 中；暂存的实时 home 会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，以确保探测不会落到你的真实宿主工作区上。 -如果你希望依赖环境变量密钥（例如在你的 `~/.profile` 中导出的密钥），请在本地测试前运行 `source ~/.profile`，或使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。 +如果你想依赖环境变量密钥（例如导出在你的 `~/.profile` 中），请在本地测试前运行 `source ~/.profile`，或者使用下面的 Docker 运行器（它们可以把 `~/.profile` 挂载到容器中）。 ## Deepgram 实时测试（音频转录） - 测试：`extensions/deepgram/audio.live.test.ts` - 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## BytePlus（国际版）编码计划实时测试 +## BytePlus（国际版） 编码计划实时测试 - 测试：`extensions/byteplus/live.test.ts` - 启用：`BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` @@ -396,8 +400,8 @@ Docker 说明： - 启用：`OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - 范围： - 覆盖内置的 comfy 图像、视频和 `music_generate` 路径 - - 除非已配置 `plugins.entries.comfy.config.`，否则会跳过各项能力 - - 在修改 comfy 工作流提交、轮询、下载或插件注册后非常有用 + - 除非已配置 `plugins.entries.comfy.config.`，否则会跳过对应能力 + - 在修改 comfy 工作流提交、轮询、下载或插件注册后尤其有用 ## 图像生成实时测试 @@ -407,12 +411,12 @@ Docker 说明： - 范围： - 枚举每个已注册的图像生成提供商插件 - 在探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量 - - 默认优先使用实时/环境变量 API 密钥，而不是已存储的认证配置档案，这样 `auth-profiles.json` 中过期的测试密钥就不会掩盖真实 shell 凭证 - - 跳过没有可用认证/配置档案/模型的提供商 + - 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证 profile，这样 `auth-profiles.json` 中过期的测试密钥就不会掩盖真实的 shell 凭证 + - 跳过没有可用认证 / profile / 模型的提供商 - 通过共享图像生成运行时运行每个已配置提供商： - `:generate` - - 当提供商声明支持编辑时运行 `:edit` -- 当前覆盖的内置提供商： + - 当提供商声明支持编辑时，运行 `:edit` +- 当前已覆盖的内置提供商： - `fal` - `google` - `minimax` @@ -425,9 +429,9 @@ Docker 说明： - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"` - 可选认证行为： - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置档案存储认证，并忽略仅环境变量覆盖 + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用 profile store 认证并忽略仅环境变量覆盖 -对于已发布的 CLI 路径，在提供商/运行时实时 +对于已发布的 CLI 路径，在提供商 / 运行时实时 测试通过后，再添加一个 `infer` 冒烟测试： ```bash @@ -440,9 +444,9 @@ openclaw infer image generate \ --json ``` -这覆盖了 CLI 参数解析、配置/默认智能体解析、内置 -插件激活、按需修复内置运行时依赖、 -共享图像生成运行时以及实时提供商请求。 +这涵盖了 CLI 参数解析、配置 / 默认智能体解析、内置 +插件激活、按需修复内置运行时依赖、共享 +图像生成运行时以及实时提供商请求。 ## 音乐生成实时测试 @@ -453,10 +457,10 @@ openclaw infer image generate \ - 覆盖共享的内置音乐生成提供商路径 - 当前覆盖 Google 和 MiniMax - 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量 - - 默认优先使用实时/环境变量 API 密钥，而不是已存储的认证配置档案，这样 `auth-profiles.json` 中过期的测试密钥就不会掩盖真实 shell 凭证 - - 跳过没有可用认证/配置档案/模型的提供商 + - 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证 profile，这样 `auth-profiles.json` 中过期的测试密钥就不会掩盖真实的 shell 凭证 + - 跳过没有可用认证 / profile / 模型的提供商 - 在可用时运行两种已声明的运行时模式： - - `generate`，使用纯提示词输入 + - 使用仅提示词输入的 `generate` - 当提供商声明 `capabilities.edit.enabled` 时运行 `edit` - 当前共享通道覆盖： - `google`：`generate`、`edit` @@ -466,7 +470,7 @@ openclaw infer image generate \ - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - 可选认证行为： - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置档案存储认证，并忽略仅环境变量覆盖 + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用 profile store 认证并忽略仅环境变量覆盖 ## 视频生成实时测试 @@ -475,41 +479,41 @@ openclaw infer image generate \ - Harness：`pnpm test:live:media video` - 范围： - 覆盖共享的内置视频生成提供商路径 - - 默认使用发布安全的冒烟测试路径：非 FAL 提供商、每个提供商一次文生视频请求、一秒龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每提供商操作上限（默认 `180000`） + - 默认使用适合发布的冒烟测试路径：非 FAL 提供商、每个提供商一个文生视频请求、时长一秒的龙虾提示词，以及从 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 读取的每提供商操作上限（默认 `180000`） - 默认跳过 FAL，因为提供商侧队列延迟可能主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它 - 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量 - - 默认优先使用实时/环境变量 API 密钥，而不是已存储的认证配置档案，这样 `auth-profiles.json` 中过期的测试密钥就不会掩盖真实 shell 凭证 - - 跳过没有可用认证/配置档案/模型的提供商 + - 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证 profile，这样 `auth-profiles.json` 中过期的测试密钥就不会掩盖真实的 shell 凭证 + - 跳过没有可用认证 / profile / 模型的提供商 - 默认只运行 `generate` - - 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，在可用时也会运行已声明的转换模式： - - 当提供商声明 `capabilities.imageToVideo.enabled` 且所选提供商/模型在共享扫描中接受基于 buffer 的本地图像输入时，运行 `imageToVideo` - - 当提供商声明 `capabilities.videoToVideo.enabled` 且所选提供商/模型在共享扫描中接受基于 buffer 的本地视频输入时，运行 `videoToVideo` + - 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`，在可用时还会运行已声明的转换模式： + - 当提供商声明 `capabilities.imageToVideo.enabled` 且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地图像输入时，运行 `imageToVideo` + - 当提供商声明 `capabilities.videoToVideo.enabled` 且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地视频输入时，运行 `videoToVideo` - 当前在共享扫描中已声明但被跳过的 `imageToVideo` 提供商： - `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL - 提供商专用的 Vydra 覆盖： - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - 该文件会运行 `veo3` 文生视频，以及一个默认使用远程图像 URL 固件的 `kling` 通道 - - 当前 `videoToVideo` 实时测试覆盖： - - 仅 `runway`，且所选模型为 `runway/gen4_aleph` 时 + - 该文件会运行 `veo3` 文生视频，以及一个默认使用远程图像 URL 固定数据的 `kling` 通道 + - 当前 `videoToVideo` 实时覆盖： + - 仅 `runway`，且所选模型为 `runway/gen4_aleph` - 当前在共享扫描中已声明但被跳过的 `videoToVideo` 提供商： - - `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL - - `google`，因为当前共享 Gemini/Veo 通道使用本地基于 buffer 的输入，而该路径在共享扫描中不被接受 - - `openai`，因为当前共享通道缺少针对特定组织的视频修补/混编访问保证 + - `alibaba`、`qwen`、`xai`，因为这些路径目前需要远程 `http(s)` / MP4 参考 URL + - `google`，因为当前共享 Gemini / Veo 通道使用基于本地 buffer 的输入，而该路径在共享扫描中不被接受 + - `openai`，因为当前共享通道缺乏针对组织的 video inpaint / remix 访问保证 - 可选缩小范围： - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 可在默认扫描中包含所有提供商，包括 FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 可降低每个提供商的操作上限，以进行更激进的冒烟测试 + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 可将每个提供商的操作上限降低，以进行更激进的冒烟测试 - 可选认证行为： - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置档案存储认证，并忽略仅环境变量覆盖 + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用 profile store 认证并忽略仅环境变量覆盖 -## 媒体实时测试 Harness +## 媒体实时测试 harness - 命令：`pnpm test:live:media` - 目的： - 通过一个仓库原生入口点运行共享的图像、音乐和视频实时测试套件 - 自动从 `~/.profile` 加载缺失的提供商环境变量 - - 默认自动将每个测试套件收窄到当前具有可用认证的提供商 + - 默认自动将每个测试套件缩小到当前具有可用认证的提供商 - 复用 `scripts/test-live.mjs`，因此心跳和静默模式行为保持一致 - 示例： - `pnpm test:live:media` diff --git a/docs/zh-CN/plugins/google-meet.md b/docs/zh-CN/plugins/google-meet.md index 4395ae49c..59a458e14 100644 --- a/docs/zh-CN/plugins/google-meet.md +++ b/docs/zh-CN/plugins/google-meet.md @@ -1,63 +1,58 @@ --- read_when: - - 你希望让一个 OpenClaw 智能体加入 Google Meet 通话 - - 你希望让一个 OpenClaw 智能体创建一个新的 Google Meet 通话 - - 你正在将 Chrome、Chrome 节点或 Twilio 配置为 Google Meet 的传输方式 -summary: Google Meet 插件：通过 Chrome 或 Twilio 加入显式的 Meet URL，并使用实时语音默认设置 + - 你希望一个 OpenClaw 智能体加入一个 Google Meet 通话 + - 你希望一个 OpenClaw 智能体创建一个新的 Google Meet 通话 + - 你正在将 Chrome、Chrome 节点或 Twilio 配置为 Google Meet 传输方式 +summary: Google Meet 插件：通过 Chrome 或 Twilio 加入显式的 Meet URL，并使用默认的实时语音设置 title: Google Meet 插件 x-i18n: - generated_at: "2026-04-25T00:42:04Z" + generated_at: "2026-04-25T01:27:31Z" model: gpt-5.4 provider: openai - source_hash: 83256d1c374aeaf18f9b2bdf7ae9cdfa9e053422c65b2db4dcee7013505b555a + source_hash: 61ba617e92bc1e5791844adb2c77455577af55970143b39b38f1cc5bd1038a3a source_path: plugins/google-meet.md workflow: 15 --- -OpenClaw 的 Google Meet 参与者支持——该插件在设计上是显式的： +OpenClaw 的 Google Meet 参会支持 —— 该插件在设计上是显式的： - 它只会加入显式的 `https://meet.google.com/...` URL。 -- 它可以通过 Google Meet API 创建一个新的 Meet 空间，然后加入返回的 - URL。 +- 它可以通过 Google Meet API 创建一个新的 Meet 空间，然后加入返回的 URL。 - `realtime` 语音是默认模式。 -- 当需要更深层的推理或工具时，实时语音可以回调到完整的 OpenClaw 智能体。 -- 智能体通过 `mode` 选择加入行为：实时收听/回话使用 `realtime`，而 `transcribe` - 用于加入/控制浏览器，但不启用实时语音桥接。 -- 认证从个人 Google OAuth 或已登录的 Chrome 配置文件开始。 -- 没有自动同意声明。 +- 当需要更深入的推理或工具时，实时语音可以回调到完整的 OpenClaw 智能体。 +- 智能体通过 `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 export OPENAI_API_KEY=sk-... -# or +# 或者 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 { @@ -78,11 +73,7 @@ command -v rec play openclaw googlemeet setup ``` -该设置输出设计为便于智能体读取。它会报告 Chrome 配置文件、 -音频桥接、节点固定、延迟实时介绍，以及在配置了 Twilio 委派时， -`voice-call` 插件和 Twilio 凭证是否已就绪。 -将任何 `ok: false` 检查都视为在请求智能体加入前的阻塞项。 -脚本或机器可读输出请使用 `openclaw googlemeet setup --json`。 +设置输出旨在便于智能体读取。它会报告 Chrome 配置文件、音频桥接、节点固定、延迟实时介绍，以及在配置了 Twilio 委派时，`voice-call` 插件和 Twilio 凭证是否已就绪。将任何 `ok: false` 检查都视为阻塞项，在要求智能体加入之前先解决。对脚本或机器可读输出，请使用 `openclaw googlemeet setup --json`。 加入会议： @@ -115,22 +106,12 @@ 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。 - 浏览器自动化会处理 Meet 自己的首次运行麦克风提示；该提示不会被视为 Google 登录失败。 +- API 创建：当配置了 Google Meet OAuth 凭证时使用。这是最确定性的路径，不依赖浏览器 UI 状态。 +- 浏览器回退：当缺少 OAuth 凭证时使用。OpenClaw 会使用固定的 Chrome 节点，打开 `https://meet.google.com/new`，等待 Google 重定向到真实的会议代码 URL，然后返回该 URL。这条路径要求节点上的 OpenClaw Chrome 配置文件已经登录 Google。浏览器自动化会处理 Meet 自身的首次运行麦克风提示；该提示不会被视为 Google 登录失败。 -命令/工具输出包含一个 `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，用实时语音加入它，并把 -链接发给我。” 智能体应使用 `action: "create"` 调用 `google_meet`，然后 -分享返回的 `meetingUri`。 +或者告诉智能体：“创建一个 Google Meet，用实时语音加入，并把链接发给我。” 智能体应调用 `google_meet`，并使用 `action: "create"`，然后分享返回的 `meetingUri`。 ```json { @@ -140,29 +121,19 @@ CLI 中使用 `create --no-join`，或向工具传入 `"join": false`。 } ``` -对于仅观察/浏览器控制的加入，请设置 `"mode": "transcribe"`。这不会 -启动双工实时模型桥接，因此它不会在会议中回话。 +如果只想观察/控制浏览器加入，请设置 `"mode": "transcribe"`。这不会启动双工实时模型桥接，因此它不会在会议中回话。 -Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，选择 `BlackHole 2ch` 作为 -OpenClaw 使用的麦克风/扬声器路径。为了获得干净的双工音频，请使用 -独立的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备 -足以完成首次 smoke 测试，但可能会产生回声。 +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 密钥或模型 - 提供商设置。 +- Gateway 网关主机：OpenClaw Gateway 网关、智能体工作区、模型/API 密钥、实时提供商，以及 Google Meet 插件配置。 +- Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及一个已登录 Google 的 Chrome 配置文件。 +- VM 中不需要：Gateway 网关服务、智能体配置、OpenAI/GPT 密钥或模型提供商设置。 安装 VM 依赖： @@ -176,14 +147,14 @@ brew install blackhole-2ch sox sudo reboot ``` -重启后，验证 VM 可以看到音频设备和 SoX 命令： +重启后，验证 VM 能看到该音频设备以及 SoX 命令： ```bash system_profiler SPAudioDataType | grep -i BlackHole command -v rec play ``` -在 VM 中安装或更新 OpenClaw，然后在那里启用内置插件： +在 VM 中安装或更新 OpenClaw，然后在其中启用内置插件： ```bash openclaw plugins enable google-meet @@ -195,15 +166,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 \ @@ -211,9 +181,7 @@ 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 网关主机批准该节点： @@ -222,8 +190,7 @@ openclaw devices list openclaw devices approve ``` -确认 Gateway 网关可以看到该节点，并且它同时通告了 `googlemeet.chrome` -和浏览器能力/`browser.proxy`： +确认 Gateway 网关能看到该节点，并且它同时声明了 `googlemeet.chrome` 和浏览器能力/`browser.proxy`： ```bash openclaw nodes status @@ -259,101 +226,61 @@ openclaw nodes status } ``` -现在从 Gateway 网关主机正常加入： +现在可以像平常一样从 Gateway 网关主机加入： ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -或者让智能体使用带有 `transport: "chrome-node"` 的 `google_meet` 工具。 +或者要求智能体使用 `google_meet` 工具，并设置 `transport: "chrome-node"`。 -如需一个单命令 smoke 测试，用于创建或复用会话、说出一段已知短语并打印 -会话健康状态： +如果你想执行一个单命令冒烟测试，用来创建或复用会话、说出一段已知短语并打印会话健康状态： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -在加入过程中，OpenClaw 浏览器自动化会填写访客名称，点击 Join/Ask -to join，并在 Meet 出现首次运行的 “Use microphone” 提示时接受该选择。 -在仅浏览器的会议创建期间，如果 Meet 没有暴露 use-microphone 按钮， -它也可以在不使用麦克风的情况下继续通过相同提示。 -如果浏览器配置文件未登录、Meet 正在等待主持人 -准入、Chrome 需要麦克风/摄像头权限，或 Meet 卡在某个 -自动化无法解决的提示上，join/test-speech 结果会报告 -`manualActionRequired: true`，并附带 `manualActionReason` 和 -`manualActionMessage`。智能体应停止重试加入，报告这条确切 -消息以及当前的 `browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后再重试。 +在加入过程中，OpenClaw 浏览器自动化会填写访客名称、点击加入/请求加入，并在出现该提示时接受 Meet 首次运行时的“使用麦克风”选项。在仅浏览器创建会议期间，如果 Meet 没有暴露使用麦克风按钮，它也可以绕过相同的提示继续而不使用麦克风。如果浏览器配置文件未登录、Meet 正在等待主持人批准、Chrome 需要麦克风/摄像头权限，或者 Meet 卡在某个自动化无法解决的提示上，那么 join/test-speech 结果会报告 `manualActionRequired: true`，并附带 `manualActionReason` 和 `manualActionMessage`。智能体应停止重试加入，报告这条精确消息以及当前的 `browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后再重试。 -如果省略 `chromeNode.node`，只有在恰好有一个已连接节点 -同时通告 `googlemeet.chrome` 和浏览器控制时，OpenClaw 才会自动选择。 -如果连接了多个有能力的节点，请将 `chromeNode.node` 设置为节点 id、 -显示名称或远程 IP。 +如果省略了 `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"` 或某个已命名的 existing-session 配置文件。 -- 重复的 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 的 realtime 默认值使用两个外部工具： +Chrome 实时默认设置会使用两个外部工具： -- `sox`：命令行音频工具。该插件使用它的 `rec` 和 `play` - 命令作为默认的 8 kHz G.711 mu-law 音频桥接。 -- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 - `BlackHole 2ch` 音频设备，供 Chrome/Meet 路由使用。 +- `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 一起打包的安装程序或 appliance，请审查 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 ``` -通过本地 OpenClaw 音频桥接来路由 Chrome 的麦克风和扬声器音频。 -如果未安装 `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 节点上启用： +在 Gateway 网关主机上启用 Voice Call 插件，而不是在 Chrome 节点上启用： ```json5 { @@ -364,7 +291,7 @@ OpenClaw 不会从 Meet 页面发现这些信息。 enabled: true, config: { defaultTransport: "chrome-node", - // 或将 "twilio" 设为默认值，如果 Twilio 应作为默认传输方式 + // 或者如果应将 Twilio 设为默认值，则设置为 "twilio" }, }, "voice-call": { @@ -378,8 +305,7 @@ OpenClaw 不会从 Meet 页面发现这些信息。 } ``` -通过环境变量或配置提供 Twilio 凭证。使用环境变量可以将 -密钥保留在 `openclaw.json` 之外： +通过环境或配置提供 Twilio 凭证。使用环境变量可以让密钥不进入 `openclaw.json`： ```bash export TWILIO_ACCOUNT_SID=AC... @@ -387,8 +313,7 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -启用 `voice-call` 后，请重启或重新加载 Gateway 网关；插件配置变更 -在 Gateway 网关进程重新加载前，不会出现在已运行的进程中。 +启用 `voice-call` 后，重启或重新加载 Gateway 网关；在 Gateway 网关进程重新加载之前，插件配置更改不会出现在已运行的 Gateway 网关进程中。 然后验证： @@ -398,8 +323,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 \ @@ -417,31 +341,23 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -## OAuth 与预检 +## 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 客户端。配置 `oauth.clientId`，并可选配置 `oauth.clientSecret`，然后运行： ```bash openclaw googlemeet auth login --json ``` -该命令会打印一个包含 refresh token 的 `oauth` 配置块。它使用 PKCE、 -`http://localhost:8085/oauth2callback` 上的 localhost 回调，以及可通过 `--manual` -启用的手动复制/粘贴流程。 +该命令会打印一个包含刷新令牌的 `oauth` 配置块。它使用 PKCE、位于 `http://localhost:8085/oauth2callback` 的 localhost 回调，以及通过 `--manual` 进行的手动复制/粘贴流程。 -OAuth 同意范围包括 Meet 空间创建、Meet 空间读取访问，以及 Meet -会议媒体读取访问。如果你在会议创建支持出现之前就已完成认证， -请重新运行 `openclaw googlemeet auth login --json`，以便 refresh token 拥有 `meetings.space.created` 作用域。 +OAuth 同意范围包括 Meet 空间创建、Meet 空间读取访问，以及 Meet 会议媒体读取访问。如果你在支持会议创建功能出现之前就已完成认证，请重新运行 `openclaw googlemeet auth login --json`，以便刷新令牌具备 `meetings.space.created` scope。 -浏览器回退不需要 OAuth 凭证。在这种模式下，Google -认证来自所选节点上已登录的 Chrome 配置文件，而不是来自 OpenClaw 配置。 +浏览器回退不需要 OAuth 凭证。在该模式下，Google 认证来自所选节点上已登录的 Chrome 配置文件，而不是 OpenClaw 配置。 -以下环境变量可作为回退值使用： +接受以下环境变量作为回退值： - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID` - `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` 或 `GOOGLE_MEET_CLIENT_SECRET` @@ -458,7 +374,7 @@ OAuth 同意范围包括 Meet 空间创建、Meet 空间读取访问，以及 Me openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -在进行媒体工作前运行预检： +在进行媒体相关工作前运行预检： ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij @@ -470,13 +386,9 @@ openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet create ``` -该命令会打印新的 `meeting uri`、来源以及加入会话。有 OAuth -凭证时，它会使用官方 Google Meet API。没有 OAuth 凭证时，它会 -使用固定 Chrome 节点上已登录的浏览器配置文件作为回退。智能体可以 -使用 `action: "create"` 调用 `google_meet` 工具，以一步完成创建和加入。 -如仅创建 URL，请传入 `"join": false`。 +该命令会打印新的 `meeting uri`、source 和加入会话。有 OAuth 凭证时，它会使用官方 Google Meet API。没有 OAuth 凭证时，它会回退为使用固定 Chrome 节点中已登录的浏览器配置文件。智能体可以使用 `google_meet` 工具并设置 `action: "create"`，以一步完成创建并加入。如果只需创建 URL，请传入 `"join": false`。 -浏览器回退的 JSON 输出示例： +来自浏览器回退的 JSON 输出示例： ```json { @@ -496,7 +408,7 @@ openclaw googlemeet create } ``` -API 创建的 JSON 输出示例： +来自 API 创建的 JSON 输出示例： ```json { @@ -517,25 +429,18 @@ API 创建的 JSON 输出示例： } ``` -默认情况下，创建 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` 设为 true。 +仅在确认你的 Cloud 项目、OAuth principal 和会议参与者已加入 Google Workspace Developer Preview Program for Meet media APIs 之后，才设置 `preview.enrollmentAcknowledged: true`。 ## 配置 -常见的 Chrome realtime 路径只需要启用插件、安装 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 export OPENAI_API_KEY=sk-... -# or +# 或者 export GEMINI_API_KEY=... ``` @@ -560,24 +465,18 @@ export GEMINI_API_KEY=... - `defaultMode: "realtime"` - `chromeNode.node`：`chrome-node` 的可选节点 id/名称/IP - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`：在已登出 Meet 访客 - 界面上使用的名称 -- `chrome.autoJoin: true`：在 `chrome-node` 上通过 OpenClaw 浏览器自动化尽力完成访客名称填写并点击 Join Now -- `chrome.reuseExistingTab: true`：激活已有 Meet 标签页，而不是 - 打开重复标签页 -- `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` 命令 +- `chrome.guestName: "OpenClaw Agent"`：在已退出登录的 Meet 访客界面上使用的名称 +- `chrome.autoJoin: true`：通过 OpenClaw 浏览器自动化在 `chrome-node` 上尽力完成访客名填写和点击立即加入 +- `chrome.reuseExistingTab: true`：激活现有 Meet 标签页，而不是打开重复标签页 +- `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`：实时桥接连接时的简短口头就绪检查；将其设为 `""` 可静默加入 -可选覆盖： +可选覆盖项： ```json5 { @@ -595,7 +494,7 @@ export GEMINI_API_KEY=... realtime: { provider: "google", toolPolicy: "owner", - introMessage: "Say exactly: I'm here.", + introMessage: "准确说出：我到了。", providers: { google: { model: "gemini-2.5-flash-native-audio-preview-12-2025", @@ -606,7 +505,7 @@ export GEMINI_API_KEY=... } ``` -仅使用 Twilio 的配置： +仅 Twilio 配置： ```json5 { @@ -621,9 +520,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 呼叫。 ## 工具 @@ -638,94 +535,88 @@ Google Meet 仍然可以验证并记录拨号计划，但无法发起 Twilio 呼 } ``` -当 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。使用 -带有 `sessionId` 和 `message` 的 `action: "speak"`，让实时智能体 -立即发声。使用 `action: "test_speech"` 创建或复用会话， -触发一段已知短语，并在 Chrome 主机可报告时返回 `inCall` -健康状态。使用 `action: "leave"` 将会话标记为结束。 +使用 `action: "status"` 可列出活动会话或检查某个会话 ID。使用 `action: "speak"` 并提供 `sessionId` 和 `message`，可让实时智能体立即发声。使用 `action: "test_speech"` 可创建或复用会话、触发一段已知短语，并在 Chrome 主机可报告时返回 `inCall` 健康状态。使用 `action: "leave"` 将会话标记为已结束。 `status` 在可用时包含 Chrome 健康状态： -- `inCall`：Chrome 看起来已经进入 Meet 通话 -- `micMuted`：尽力判断的 Meet 麦克风状态 -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：该 - 浏览器配置文件需要手动登录、Meet 主持人准入、权限处理，或 - 浏览器控制修复，语音功能才能工作 +- `inCall`：Chrome 看起来已进入 Meet 通话 +- `micMuted`：尽力检测的 Meet 麦克风状态 +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人批准、权限授予或浏览器控制修复，语音功能才能工作 - `providerConnected` / `realtimeReady`：实时语音桥接状态 -- `lastInputAt` / `lastOutputAt`：桥接中最近一次接收到或发送出去的音频时间 +- `lastInputAt` / `lastOutputAt`：最近一次从桥接接收到或发送到桥接的音频时间 ```json { "action": "speak", "sessionId": "meet_...", - "message": "Say exactly: I'm here and listening." + "message": "准确说出：我在这里，正在听。" } ``` ## 实时智能体咨询 -Chrome realtime 模式针对实时语音循环做了优化。实时语音 -提供商会听取会议音频，并通过已配置的音频桥接发声。 -当实时模型需要更深层推理、最新信息或普通 OpenClaw 工具时， -它可以调用 `openclaw_agent_consult`。 +Chrome 实时模式针对实时语音回路进行了优化。实时语音提供商会听取会议音频，并通过配置的音频桥接进行发声。当实时模型需要更深入的推理、当前信息或常规 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。 -咨询工具会在后台运行常规的 OpenClaw 智能体，并带上最近的 -会议转录上下文，然后向实时语音会话返回一条简洁的口头回答。语音模型 -随后可以将这条回答说回会议中。 -它与 Voice Call 共用同一个实时咨询工具。 +该咨询工具会在后台运行常规 OpenClaw 智能体，并结合最近的会议转录上下文，向实时语音会话返回简洁的口头回答。然后语音模型可以将该回答再说回会议中。它与 Voice Call 共用同一个实时咨询工具。 -`realtime.toolPolicy` 控制咨询运行： +`realtime.toolPolicy` 控制咨询运行方式： -- `safe-read-only`：暴露咨询工具，并将常规智能体限制为 - `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 - `memory_get`。 -- `owner`：暴露咨询工具，并允许常规智能体使用正常的 - 智能体工具策略。 +- `safe-read-only`：暴露咨询工具，并将常规智能体限制为使用 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 +- `owner`：暴露咨询工具，并允许常规智能体使用正常的智能体工具策略。 - `none`：不向实时语音模型暴露咨询工具。 -咨询会话键按 Meet 会话作用域划分，因此在同一次会议期间， -后续咨询调用可以复用先前的咨询上下文。 +咨询会话键按每个 Meet 会话进行作用域隔离，因此在同一场会议期间，后续咨询调用可以复用先前的咨询上下文。 若要在 Chrome 完全加入通话后强制执行一次口头就绪检查： ```bash -openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." +openclaw googlemeet speak meet_... "准确说出：我在这里，正在听。" ``` -若要执行完整的加入并发声 smoke 测试： +完整的加入并发声冒烟测试： ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --transport chrome-node \ - --message "Say exactly: I'm here and listening." + --message "准确说出：我在这里，正在听。" ``` -## 实时测试清单 +## 实时测试检查清单 -在将会议交给无人值守的智能体之前，请使用以下流程： +在将会议交给无人值守智能体之前，请使用以下顺序： ```bash openclaw googlemeet setup openclaw nodes status openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --transport chrome-node \ - --message "Say exactly: Google Meet speech test complete." + --message "准确说出：Google Meet 语音测试完成。" ``` -预期的 Chrome-node 状态： +预期的 chrome-node 状态： - `googlemeet setup` 全部为绿色。 +- 当 chrome-node 是默认传输方式或固定了节点时，`googlemeet setup` 会包含 `chrome-node-connected`。 - `nodes status` 显示所选节点已连接。 -- 所选节点同时通告 `googlemeet.chrome` 和 `browser.proxy`。 -- Meet 标签页加入通话，并且 `test-speech` 返回包含 - `inCall: true` 的 Chrome 健康状态。 +- 所选节点同时声明了 `googlemeet.chrome` 和 `browser.proxy`。 +- Meet 标签页已加入通话，且 `test-speech` 返回包含 `inCall: true` 的 Chrome 健康状态。 -对于 Twilio smoke 测试，请使用一个暴露电话拨入详情的会议： +对于远程 Chrome 主机，例如 Parallels macOS VM，在更新 Gateway 网关或 VM 后，这是最短且安全的检查方式： + +```bash +openclaw googlemeet setup +openclaw nodes status --connected +openclaw nodes invoke \ + --node parallels-macos \ + --command googlemeet.chrome \ + --params '{"action":"setup"}' +``` + +这可以证明 Gateway 网关插件已加载、VM 节点使用当前令牌保持连接，并且在智能体打开真实会议标签页之前，Meet 音频桥接已可用。 + +对于 Twilio 冒烟测试，请使用一个会公开电话拨入详情的会议： ```bash openclaw googlemeet setup @@ -737,11 +628,10 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ 预期的 Twilio 状态： -- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和 - `twilio-voice-call-credentials` 检查。 +- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。 - Gateway 网关重新加载后，CLI 中可用 `voicecall`。 -- 返回的会话具有 `transport: "twilio"` 和 `twilio.voiceCallId`。 -- `googlemeet leave ` 会挂断被委派的语音呼叫。 +- 返回的会话具有 `transport: "twilio"` 和一个 `twilio.voiceCallId`。 +- `googlemeet leave ` 会挂断被委派的语音通话。 ## 故障排除 @@ -754,13 +644,11 @@ openclaw plugins list | grep google-meet openclaw googlemeet setup ``` -如果你刚刚编辑了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。 -正在运行的智能体只能看到由当前 Gateway 网关 -进程注册的插件工具。 +如果你刚编辑了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。正在运行的智能体只能看到由当前 Gateway 网关进程注册的插件工具。 -### 没有已连接的 Google Meet 能力节点 +### 没有已连接的 Google Meet 可用节点 -在节点主机上，运行： +在节点主机上运行： ```bash openclaw plugins enable google-meet @@ -777,8 +665,7 @@ openclaw devices approve openclaw nodes status ``` -该节点必须已连接，并列出 `googlemeet.chrome` 以及 `browser.proxy`。 -Gateway 网关配置还必须允许这些节点命令： +该节点必须处于已连接状态，并列出 `googlemeet.chrome` 和 `browser.proxy`。Gateway 网关配置还必须允许这些节点命令： ```json5 { @@ -790,77 +677,71 @@ Gateway 网关配置还必须允许这些节点命令： } ``` +如果 `googlemeet setup` 的 `chrome-node-connected` 检查失败，或者 Gateway 网关日志报告 `gateway token mismatch`，请使用当前的 Gateway 网关令牌重新安装或重启节点。对于一个局域网 Gateway 网关，这通常意味着： + +```bash +OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ + openclaw node install \ + --host \ + --port 18789 \ + --display-name parallels-macos \ + --force +``` + +然后重新加载节点服务，并再次运行： + +```bash +openclaw googlemeet setup +openclaw nodes status --connected +``` + ### 浏览器已打开，但智能体无法加入 -运行 `googlemeet test-speech` 并检查返回的 Chrome 健康状态。如果它 -报告 `manualActionRequired: true`，请将 `manualActionMessage` 展示给操作员， -并在浏览器操作完成前停止重试。 +运行 `googlemeet test-speech` 并检查返回的 Chrome 健康状态。如果它报告 `manualActionRequired: true`，请向操作员显示 `manualActionMessage`，并在浏览器操作完成前停止重试。 常见的手动操作： - 登录 Chrome 配置文件。 -- 由 Meet 主持人账号批准访客加入。 +- 使用 Meet 主持人账号批准访客加入。 - 当 Chrome 的原生权限提示出现时，授予 Chrome 麦克风/摄像头权限。 - 关闭或修复卡住的 Meet 权限对话框。 -如果 Meet 显示 “Do you want people to -hear you in the meeting?”，不要仅因此报告“未登录”。 -这是 Meet 的音频选择过渡页；在可用时，OpenClaw 会通过浏览器自动化点击 **Use microphone**，并继续等待真实的会议状态。对于仅创建的浏览器回退路径，OpenClaw -可能会点击 **Continue without microphone**，因为创建 URL 并不需要 -实时音频路径。 +不要仅仅因为 Meet 显示 “Do you want people to hear you in the meeting?” 就报告“未登录”。这是 Meet 的音频选择过渡页面；OpenClaw 会在可用时通过浏览器自动化点击 **Use microphone**，并继续等待真实的会议状态。对于仅创建的浏览器回退，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 创建：refresh token 是在添加创建支持之后签发的。 - 较旧的 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 标签页。 -- 对于浏览器回退：如果 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`。 +- 对于 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`。 +- 对于浏览器回退：该节点上的 OpenClaw Chrome 配置文件已登录 Google，并且可以打开 `https://meet.google.com/new`。 +- 对于浏览器回退：重试会复用已有的 `https://meet.google.com/new` 或 Google 账号提示标签页，而不是打开新标签页。如果智能体超时，请重试工具调用，而不是手动再打开一个 Meet 标签页。 +- 对于浏览器回退：如果 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`。 -### 智能体已加入，但不说话 +### 智能体已加入但不说话 -检查 realtime 路径： +检查实时路径： ```bash openclaw googlemeet setup openclaw googlemeet status ``` -收听/回话请使用 `mode: "realtime"`。`mode: "transcribe"` 则是有意 -不启动双工实时语音桥接。 +使用 `mode: "realtime"` 实现收听/回话。`mode: "transcribe"` 按设计不会启动双工实时语音桥接。 另外还要验证： -- Gateway 网关主机上有可用的实时提供商密钥，例如 - `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。 -- 在 Chrome 主机上可以看到 `BlackHole 2ch`。 -- 在 Chrome 主机上存在 `rec` 和 `play`。 -- Meet 的麦克风和扬声器通过 OpenClaw 使用的虚拟音频路径进行路由。 +- Gateway 网关主机上有可用的实时提供商密钥，例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。 +- Chrome 主机上可见 `BlackHole 2ch`。 +- Chrome 主机上存在 `rec` 和 `play`。 +- Meet 的麦克风和扬声器已通过 OpenClaw 使用的虚拟音频路径进行路由。 ### Twilio 设置检查失败 -当 `voice-call` 未被允许或未启用时，`twilio-voice-call-plugin` 会失败。 -请将其添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，然后重新加载 -Gateway 网关。 +当 `voice-call` 不被允许或未启用时，`twilio-voice-call-plugin` 会失败。将其添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，并重新加载 Gateway 网关。 -当 Twilio 后端缺少 account -SID、auth token 或 caller number 时，`twilio-voice-call-credentials` 会失败。在 Gateway 网关主机上设置这些值： +当 Twilio 后端缺少 account SID、auth token 或 caller number 时，`twilio-voice-call-credentials` 会失败。在 Gateway 网关主机上设置这些值： ```bash export TWILIO_ACCOUNT_SID=AC... @@ -874,10 +755,9 @@ export TWILIO_FROM_NUMBER=+15550001234 openclaw googlemeet setup ``` -### Twilio 呼叫已开始，但始终未进入会议 +### Twilio 通话已开始但始终未进入会议 -确认该 Meet 事件暴露了电话拨入详情。传入精确的拨入 -号码和 PIN，或自定义 DTMF 序列： +确认 Meet 事件公开了电话拨入详情。传入准确的拨入号码和 PIN，或者自定义 DTMF 序列： ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -886,32 +766,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 realtime 模式需要以下其一： +Chrome 实时模式需要以下其中之一： -- `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 负责 - 实时模型桥接，并在这些 - 命令与所选实时语音提供商之间传输 8 kHz G.711 mu-law 音频。 -- `chrome.audioBridgeCommand`：一个外部桥接命令负责整个本地 - 音频路径，并且必须在启动或验证其守护进程后退出。 +- `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 自主管理实时模型桥接，并在这些命令与所选实时语音提供商之间传输 8 kHz G.711 mu-law 音频。 +- `chrome.audioBridgeCommand`：一个外部桥接命令拥有整个本地音频路径，并且必须在启动或验证其守护进程后退出。 -为了获得干净的双工音频，请将 Meet 输出和 Meet 麦克风路由到独立的 -虚拟设备，或使用类似 Loopback 的虚拟设备图。 -单个共享的 BlackHole 设备可能会将其他参与者的声音回送到通话中。 +为了获得干净的双工音频，请将 Meet 输出和 Meet 麦克风通过独立的虚拟设备或类似 Loopback 的虚拟设备图进行路由。单个共享的 BlackHole 设备可能会将其他参与者的声音回送到通话中。 -`googlemeet speak` 会触发 Chrome -会话的活动实时音频桥接。`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委派的 Twilio 会话，`leave` 还会挂断底层语音呼叫。 +`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) diff --git a/docs/zh-CN/plugins/manifest.md b/docs/zh-CN/plugins/manifest.md index 813de5ef3..3b35975ea 100644 --- a/docs/zh-CN/plugins/manifest.md +++ b/docs/zh-CN/plugins/manifest.md @@ -1,21 +1,21 @@ --- read_when: - 你正在构建一个 OpenClaw 插件 - - 你需要交付插件配置 schema，或调试插件验证错误 -summary: 插件清单 + JSON schema 要求（严格配置验证） + - 你需要提供一个插件配置 schema，或调试插件校验错误 +summary: 插件清单 + JSON schema 要求（严格配置校验） title: 插件清单 x-i18n: - generated_at: "2026-04-25T00:42:08Z" + generated_at: "2026-04-25T01:27:30Z" model: gpt-5.4 provider: openai - source_hash: ada68754e06044810bb38c890e1aa6cb2b62fe70103306417486fc6504a57c38 + source_hash: e200037fa22dd5bcc5c14638d3d473dd5af631270dedf18f151798ae15a4b951 source_path: plugins/manifest.md workflow: 15 --- -本页仅适用于**原生 OpenClaw 插件清单**。 +此页面仅适用于**原生 OpenClaw 插件清单**。 -有关兼容的 bundle 布局，请参见 [Plugin bundles](/zh-CN/plugins/bundles)。 +关于兼容的 bundle 布局，请参阅 [插件 bundle](/zh-CN/plugins/bundles)。 兼容的 bundle 格式使用不同的清单文件： @@ -23,31 +23,31 @@ x-i18n: - Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件布局 - Cursor bundle：`.cursor-plugin/plugin.json` -OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 `openclaw.plugin.json` schema 对其进行验证。 +OpenClaw 也会自动检测这些 bundle 布局，但不会根据这里描述的 `openclaw.plugin.json` schema 对它们进行校验。 对于兼容 bundle，当布局符合 OpenClaw 运行时预期时，OpenClaw 当前会读取 bundle 元数据、声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、Claude bundle 的 LSP 默认值，以及受支持的 hook pack。 -每个原生 OpenClaw 插件**都必须**在**插件根目录**提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用这个清单在**不执行插件代码**的情况下验证配置。缺失或无效的清单会被视为插件错误，并阻止配置验证。 +每个原生 OpenClaw 插件**必须**在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用这个清单在**不执行插件代码的情况下**校验配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。 -参见完整的插件系统指南：[Plugins](/zh-CN/tools/plugin)。 -有关原生能力模型和当前外部兼容性指导，请参见： -[Capability model](/zh-CN/plugins/architecture#public-capability-model)。 +请参阅完整的插件系统指南：[插件](/zh-CN/tools/plugin)。 +关于原生能力模型和当前的外部兼容性指导，请参阅： +[能力模型](/zh-CN/plugins/architecture#public-capability-model)。 ## 此文件的作用 -`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。以下所有内容都必须足够轻量，以便在不启动插件运行时的情况下进行检查。 +`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。下面的所有内容都必须足够轻量，能够在不启动插件运行时的情况下进行检查。 **用于：** -- 插件标识、配置验证和配置 UI 提示 -- 凭证、新手引导和设置元数据（别名、自动启用、提供商环境变量、凭证选项） +- 插件标识、配置校验，以及配置 UI 提示 +- 认证、新手引导和设置元数据（别名、自动启用、提供商环境变量、认证选项） - 控制平面界面的激活提示 - 简写的模型家族归属 - 静态能力归属快照（`contracts`） -- 共享 `openclaw qa` 主机可检查的 QA 运行器元数据 -- 合并到目录和验证界面的渠道专用配置元数据 +- 供共享 `openclaw qa` 主机检查的 QA 运行器元数据 +- 合并到目录和校验界面中的渠道专属配置元数据 -**不要用于：** 注册运行时行为、声明代码入口点或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。 +**不要用于：**注册运行时行为、声明代码入口点，或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。 ## 最小示例 @@ -127,67 +127,67 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 ## 顶层字段参考 -| 字段 | 必需 | 类型 | 含义 | +| 字段 | 必填 | 类型 | 含义 | | ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | 是 | `string` | 规范插件 ID。这是在 `plugins.entries.` 中使用的 ID。 | +| `id` | 是 | `string` | 规范插件 id。这是 `plugins.entries.` 中使用的 id。 | | `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 | -| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略此字段，或将其设置为任何非 `true` 的值，则插件默认保持禁用。 | -| `legacyPluginIds` | 否 | `string[]` | 会规范化为此标准插件 ID 的旧版 ID。 | -| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当凭证、配置或模型引用提到这些提供商 ID 时，应自动启用此插件。 | -| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的排他性插件类型。 | -| `channels` | 否 | `string[]` | 由此插件拥有的渠道 ID。用于发现和配置验证。 | -| `providers` | 否 | `string[]` | 由此插件拥有的提供商 ID。 | -| `providerDiscoveryEntry` | 否 | `string` | 轻量级提供商发现模块路径，相对于插件根目录，用于范围限定在清单内的提供商目录元数据，这些元数据可以在不激活完整插件运行时的情况下加载。 | +| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略它，或设置为任何非 `true` 的值，则该插件默认保持禁用。 | +| `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 | +| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 | +| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的互斥插件种类。 | +| `channels` | 否 | `string[]` | 此插件拥有的渠道 id。用于设备发现和配置校验。 | +| `providers` | 否 | `string[]` | 此插件拥有的提供商 id。 | +| `providerDiscoveryEntry` | 否 | `string` | 轻量级提供商发现模块路径，相对于插件根目录，用于可在不激活完整插件运行时的情况下加载的、清单作用域内的提供商目录元数据。 | | `modelSupport` | 否 | `object` | 由清单拥有的简写模型家族元数据，用于在运行时之前自动加载插件。 | -| `providerEndpoints` | 否 | `object[]` | 由清单拥有的 endpoint 主机 / `baseUrl` 元数据，用于核心在提供商运行时加载之前必须分类的提供商路由。 | -| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 ID。用于根据显式配置引用在启动时自动激活。 | -| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载之前的冷模型发现期间，应探测其插件自有 synthetic auth hook 的提供商或 CLI 后端引用。 | -| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API key 值，表示非密钥的本地、OAuth 或环境凭证状态。 | -| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，应在运行时加载前生成具备插件感知能力的配置和 CLI 诊断信息。 | -| `providerAuthEnvVars` | 否 | `Record` | 用于提供商鉴权 / 状态查找的已弃用兼容环境变量元数据。新插件优先使用 `setup.providers[].envVars`；在弃用窗口期内，OpenClaw 仍会读取此字段。 | -| `providerAuthAliases` | 否 | `Record` | 应复用另一个提供商 ID 进行鉴权查找的提供商 ID，例如与基础提供商共享 API key 和 auth profiles 的 coding 提供商。 | -| `channelEnvVars` | 否 | `Record` | OpenClaw 可以在不加载插件代码的情况下检查的轻量级渠道环境变量元数据。对于通用启动 / 配置帮助器需要感知的环境变量驱动渠道设置或鉴权界面，请使用此字段。 | -| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的轻量级鉴权选项元数据。 | -| `activation` | 否 | `object` | 用于基于提供商、命令、渠道、路由和能力触发加载的轻量级激活规划器元数据。仅为元数据；实际行为仍由插件运行时负责。 | -| `setup` | 否 | `object` | 供设备发现和设置界面在不加载插件运行时的情况下检查的轻量级设置 / 新手引导描述符。 | -| `qaRunners` | 否 | `object[]` | 在插件运行时加载之前，由共享 `openclaw qa` 主机使用的轻量级 QA 运行器描述符。 | -| `contracts` | 否 | `object` | 针对外部鉴权 hook、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、web-fetch、Web 搜索和工具归属的静态内置能力快照。 | -| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 ID 提供的轻量级媒体理解默认值。 | -| `channelConfigs` | 否 | `Record` | 由清单拥有的渠道配置元数据，在运行时加载之前合并到设备发现和验证界面中。 | -| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | +| `providerEndpoints` | 否 | `object[]` | 由清单拥有的端点 host/baseUrl 元数据，用于核心在提供商运行时加载之前必须分类的提供商路由。 | +| `cliBackends` | 否 | `string[]` | 此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 | +| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载之前，冷启动模型发现期间应探测其插件自有 synthetic auth hook 的提供商或 CLI 后端引用。 | +| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API key 值，表示非机密的本地、OAuth 或环境凭证状态。 | +| `commandAliases` | 否 | `object[]` | 此插件拥有的命令名称，应在运行时加载之前生成具备插件感知能力的配置和 CLI 诊断信息。 | +| `providerAuthEnvVars` | 否 | `Record` | 已弃用的兼容性提供商认证环境变量元数据，用于提供商认证/状态查找。新插件请优先使用 `setup.providers[].envVars`；在弃用窗口期间，OpenClaw 仍会读取此项。 | +| `providerAuthAliases` | 否 | `Record` | 应复用另一个提供商 id 进行认证查找的提供商 id，例如共享基础提供商 API key 和认证配置文件的 coding 提供商。 | +| `channelEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量渠道环境变量元数据。将其用于通用启动/配置辅助工具应能识别的、由环境变量驱动的渠道设置或认证界面。 | +| `providerAuthChoices` | 否 | `object[]` | 轻量认证选项元数据，用于新手引导选择器、首选提供商解析和简单的 CLI flag 绑定。 | +| `activation` | 否 | `object` | 轻量激活规划器元数据，用于由提供商、命令、渠道、路由和能力触发的加载。仅为元数据；实际行为仍由插件运行时负责。 | +| `setup` | 否 | `object` | 轻量设置/新手引导描述符，供设备发现和设置界面在不加载插件运行时的情况下检查。 | +| `qaRunners` | 否 | `object[]` | 供共享 `openclaw qa` 主机在插件运行时加载之前使用的轻量 QA 运行器描述符。 | +| `contracts` | 否 | `object` | 外部认证 hook、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、web-fetch、Ollama Web 搜索和工具归属的静态内置能力快照。 | +| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的轻量媒体理解默认元数据。 | +| `channelConfigs` | 否 | `Record` | 由清单拥有的渠道配置元数据，在运行时加载之前合并到设备发现和校验界面中。 | +| `skills` | 否 | `string[]` | 要加载的 Skill 目录，相对于插件根目录。 | | `name` | 否 | `string` | 人类可读的插件名称。 | | `description` | 否 | `string` | 在插件界面中显示的简短摘要。 | -| `version` | 否 | `string` | 信息性插件版本。 | +| `version` | 否 | `string` | 仅供参考的插件版本。 | | `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | ## `providerAuthChoices` 参考 -每个 `providerAuthChoices` 条目描述一个新手引导或鉴权选项。 +每个 `providerAuthChoices` 条目描述一个新手引导或认证选项。 OpenClaw 会在提供商运行时加载之前读取它。 -提供商设置流程会优先使用这些清单选项，然后为了兼容性回退到运行时向导元数据和安装目录选项。 +提供商设置流程会优先使用这些清单中的选项，然后为了兼容性回退到运行时向导元数据和安装目录中的选项。 -| 字段 | 必需 | 类型 | 含义 | +| 字段 | 必填 | 类型 | 含义 | | --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | 是 | `string` | 此选项所属的提供商 ID。 | -| `method` | 是 | `string` | 要分派到的鉴权方法 ID。 | -| `choiceId` | 是 | `string` | 由新手引导和 CLI 流程使用的稳定鉴权选项 ID。 | -| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 | -| `choiceHint` | 否 | `string` | 选择器的简短帮助文本。 | +| `provider` | 是 | `string` | 此选项所属的提供商 id。 | +| `method` | 是 | `string` | 要分派到的认证方法 id。 | +| `choiceId` | 是 | `string` | 供新手引导和 CLI 流程使用的稳定认证选项 id。 | +| `choiceLabel` | 否 | `string` | 面向用户的标签。如省略，OpenClaw 会回退到 `choiceId`。 | +| `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 | | `assistantPriority` | 否 | `number` | 在由智能体驱动的交互式选择器中，值越小排序越靠前。 | -| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在智能体选择器中隐藏该选项，但仍允许手动 CLI 选择。 | -| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 ID。 | -| `groupId` | 否 | `string` | 用于分组相关选项的可选分组 ID。 | -| `groupLabel` | 否 | `string` | 该分组的面向用户标签。 | -| `groupHint` | 否 | `string` | 该分组的简短帮助文本。 | -| `optionKey` | 否 | `string` | 用于简单单标志鉴权流程的内部选项键。 | -| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 | -| `cliOption` | 否 | `string` | 完整 CLI 选项形式，例如 `--openrouter-api-key `。 | -| `cliDescription` | 否 | `string` | CLI 帮助中使用的描述。 | -| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应显示在哪些新手引导界面中。如果省略，默认值为 `["text-inference"]`。 | +| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在智能体选择器中隐藏该选项，同时仍允许手动 CLI 选择。 | +| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 | +| `groupId` | 否 | `string` | 用于对相关选项分组的可选分组 id。 | +| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 | +| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 | +| `optionKey` | 否 | `string` | 用于简单单 flag 认证流程的内部选项键。 | +| `cliFlag` | 否 | `string` | CLI flag 名称，例如 `--openrouter-api-key`。 | +| `cliOption` | 否 | `string` | 完整的 CLI 选项形式，例如 `--openrouter-api-key `。 | +| `cliDescription` | 否 | `string` | 在 CLI 帮助中使用的描述。 | +| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些新手引导界面中。如省略，默认值为 `["text-inference"]`。 | ## `commandAliases` 参考 -当某个插件拥有一个运行时命令名称，而用户可能会错误地将其放入 `plugins.allow`，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据在不导入插件运行时代码的情况下生成诊断信息。 +当插件拥有一个运行时命令名称，而用户可能会误将其放入 `plugins.allow` 或尝试将其作为根级 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据在不导入插件运行时代码的情况下提供诊断信息。 ```json { @@ -201,21 +201,21 @@ OpenClaw 会在提供商运行时加载之前读取它。 } ``` -| 字段 | 必需 | 类型 | 含义 | +| 字段 | 必填 | 类型 | 含义 | | ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | | `name` | 是 | `string` | 属于此插件的命令名称。 | -| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根 CLI 命令。 | -| `cliCommand` | 否 | `string` | 若存在，可建议用于 CLI 操作的相关根 CLI 命令。 | +| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天 slash 命令，而不是根级 CLI 命令。 | +| `cliCommand` | 否 | `string` | 若存在，用于建议 CLI 操作的相关根级 CLI 命令。 | ## `activation` 参考 -当插件可以低成本声明哪些控制平面事件应将其纳入激活 / 加载计划时，请使用 `activation`。 +当插件能够以低成本声明哪些控制平面事件应将其纳入激活/加载计划时，请使用 `activation`。 -该块是规划器元数据，而不是生命周期 API。它不会注册运行时行为，不会替代 `register(...)`，也不保证插件代码已经执行。激活规划器使用这些字段来缩小候选插件范围，然后才回退到现有的清单归属元数据，例如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和 hooks。 +此块是规划器元数据，不是生命周期 API。它不会注册运行时行为，不会替代 `register(...)`，也不保证插件代码已经执行。激活规划器使用这些字段在回退到现有清单归属元数据（如 `providers`、`channels`、`commandAliases`、`setup.providers`、`contracts.tools` 和 hooks）之前缩小候选插件范围。 -优先使用已经能描述归属关系的最窄元数据。如果这些字段已经表达该关系，请使用 `providers`、`channels`、`commandAliases`、设置描述符或 `contracts`。对于那些无法由这些归属字段表示的额外规划器提示，再使用 `activation`。 +优先使用已能准确描述归属关系的最窄元数据。如果 `providers`、`channels`、`commandAliases`、设置描述符或 `contracts` 已经能表达这种关系，就使用这些字段。仅在这些归属字段无法表示额外规划提示时，才使用 `activation`。 -该块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。当前使用方会在更广泛的插件加载之前将其作为缩小范围的提示，因此缺失激活元数据通常只会带来性能成本；在旧版清单归属回退仍存在时，它不应改变正确性。 +此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时/插件入口点。当前使用方会在更广泛的插件加载之前将其作为缩小范围的提示，因此缺失激活元数据通常只会带来性能成本；在旧版清单归属回退仍存在时，它不应影响正确性。 ```json { @@ -229,29 +229,29 @@ OpenClaw 会在提供商运行时加载之前读取它。 } ``` -| 字段 | 必需 | 类型 | 含义 | +| 字段 | 必填 | 类型 | 含义 | | ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `onProviders` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的提供商 ID。 | -| `onCommands` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的命令 ID。 | -| `onChannels` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的渠道 ID。 | -| `onRoutes` | 否 | `string[]` | 应将此插件纳入激活 / 加载计划的路由类型。 | -| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 供控制平面激活规划使用的宽泛能力提示。尽可能优先使用更窄的字段。 | +| `onProviders` | 否 | `string[]` | 应将此插件纳入激活/加载计划的提供商 id。 | +| `onCommands` | 否 | `string[]` | 应将此插件纳入激活/加载计划的命令 id。 | +| `onChannels` | 否 | `string[]` | 应将此插件纳入激活/加载计划的渠道 id。 | +| `onRoutes` | 否 | `string[]` | 应将此插件纳入激活/加载计划的路由种类。 | +| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。若可能，优先使用更窄的字段。 | 当前在线使用方： -- 由命令触发的 CLI 规划会回退到旧版 +- 由命令触发的 CLI 规划会回退到旧版的 `commandAliases[].cliCommand` 或 `commandAliases[].name` -- 由渠道触发的设置 / 渠道规划在缺少显式渠道激活元数据时，会回退到旧版 `channels[]` +- 由渠道触发的设置/渠道规划在缺少显式渠道激活元数据时，会回退到旧版 `channels[]` 归属 -- 由提供商触发的设置 / 运行时规划在缺少显式提供商 +- 由提供商触发的设置/运行时规划在缺少显式提供商 激活元数据时，会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 归属 -规划器诊断可以区分显式激活提示和清单归属回退。例如，`activation-command-hint` 表示匹配了 `activation.onCommands`，而 `manifest-command-alias` 表示规划器改用了 `commandAliases` 归属。这些原因标签用于宿主诊断和测试；插件作者应继续声明最能描述归属关系的元数据。 +规划器诊断可以区分显式激活提示和清单归属回退。例如，`activation-command-hint` 表示匹配了 `activation.onCommands`，而 `manifest-command-alias` 表示规划器改用了 `commandAliases` 归属。这些原因标签用于主机诊断和测试；插件作者应继续声明最能描述归属关系的元数据。 ## `qaRunners` 参考 -当插件在共享 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 `qaRunners`。保持这些元数据轻量且静态；实际 CLI 注册仍由插件运行时通过导出 `qaRunnerCliRegistrations` 的轻量级 `runtime-api.ts` 界面负责。 +当插件在共享 `openclaw qa` 根命令下提供一个或多个传输运行器时，请使用 `qaRunners`。保持此元数据轻量且静态；实际 CLI 注册仍由插件运行时通过导出 `qaRunnerCliRegistrations` 的轻量 `runtime-api.ts` 界面负责。 ```json { @@ -264,14 +264,14 @@ OpenClaw 会在提供商运行时加载之前读取它。 } ``` -| 字段 | 必需 | 类型 | 含义 | +| 字段 | 必填 | 类型 | 含义 | | ------------- | -------- | -------- | ------------------------------------------------------------------ | | `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 | -| `description` | 否 | `string` | 当共享宿主需要一个存根命令时使用的回退帮助文本。 | +| `description` | 否 | `string` | 当共享主机需要一个 stub 命令时使用的后备帮助文本。 | ## `setup` 参考 -当设置和新手引导界面需要在运行时加载之前获取廉价的插件自有元数据时，请使用 `setup`。 +当设置和新手引导界面需要在运行时加载之前获得由插件拥有的轻量元数据时，请使用 `setup`。 ```json { @@ -290,35 +290,35 @@ OpenClaw 会在提供商运行时加载之前读取它。 } ``` -顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是面向控制平面 / 设置流程、应保持为纯元数据的设置专用描述符界面。 +顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是面向控制平面/设置流程的、应保持为纯元数据的设置专用描述符界面。 -当存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现时优先使用的、以描述符为先的查找界面。如果描述符只能缩小候选插件范围，而设置仍需要更丰富的设置时运行时 hooks，请设置 `requiresRuntime: true`，并将 `setup-api` 保留为回退执行路径。 +存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现时首选的“描述符优先”查找界面。如果描述符只能缩小候选插件范围，而设置仍需要更丰富的设置时运行时 hook，请将 `requiresRuntime` 设为 `true`，并保留 `setup-api` 作为后备执行路径。 -OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.providers[].envVars`。`providerAuthEnvVars` 在弃用窗口期内仍通过兼容适配器受支持，但仍使用它的非内置插件会收到清单诊断。新插件应将设置 / 状态环境变量元数据放在 `setup.providers[].envVars` 上。 +OpenClaw 还会将 `setup.providers[].envVars` 纳入通用提供商认证和环境变量查找。`providerAuthEnvVars` 在弃用窗口期间仍通过兼容适配器受支持，但仍在使用它的非内置插件会收到清单诊断。新插件应将设置/状态环境变量元数据放在 `setup.providers[].envVars` 上。 -当没有可用的设置入口时，或者 `setup.requiresRuntime: false` 声明设置运行时不是必需时，OpenClaw 还可以从 `setup.providers[].authMethods` 派生简单的设置选项。对于自定义标签、CLI 标志、新手引导范围和智能体元数据，显式的 `providerAuthChoices` 条目仍然是首选。 +当没有可用的设置入口，或 `setup.requiresRuntime: false` 声明设置运行时并非必需时，OpenClaw 也可以从 `setup.providers[].authMethods` 派生简单的设置选项。对于自定义标签、CLI flag、新手引导范围和智能体元数据，显式的 `providerAuthChoices` 条目仍然是首选。 -仅当这些描述符已足以满足设置界面时，才将 `requiresRuntime` 设为 `false`。OpenClaw 会将显式的 `false` 视为纯描述符契约，并且不会为设置查找执行 `setup-api` 或 `openclaw.setupEntry`。如果一个纯描述符插件仍然提供了这些设置运行时入口之一，OpenClaw 会报告附加诊断并继续忽略它。省略 `requiresRuntime` 会保留旧版回退行为，这样那些在未设置该标志的情况下添加了描述符的现有插件不会出错。 +仅当这些描述符足以满足设置界面时，才将 `requiresRuntime: false`。OpenClaw 将显式的 `false` 视为纯描述符契约，并且不会为设置查找执行 `setup-api` 或 `openclaw.setupEntry`。如果一个纯描述符插件仍然提供了其中之一的设置运行时入口，OpenClaw 会报告一个附加诊断并继续忽略它。省略 `requiresRuntime` 会保留旧版回退行为，这样已添加描述符但未设置该标志的现有插件不会出错。 -由于设置查找可能会执行插件自有的 `setup-api` 代码，因此规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值在已发现插件之间必须保持唯一。归属不明确时会以封闭失败的方式处理，而不是根据发现顺序选出“赢家”。 +由于设置查找可能会执行插件自有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值在已发现插件之间必须保持唯一。归属不明确时会采用失败即关闭，而不是根据发现顺序选一个“赢家”。 -当设置运行时确实执行时，如果 `setup-api` 注册了清单描述符未声明的提供商或 CLI 后端，或者某个描述符没有匹配的运行时注册，则设置注册表诊断会报告描述符漂移。这些诊断是附加性的，不会拒绝旧版插件。 +当设置运行时确实执行时，如果 `setup-api` 注册了清单描述符未声明的提供商或 CLI 后端，或者某个描述符没有对应的运行时注册，设置注册表诊断会报告描述符漂移。这些诊断是附加性的，不会拒绝旧版插件。 ### `setup.providers` 参考 -| 字段 | 必需 | 类型 | 含义 | +| 字段 | 必填 | 类型 | 含义 | | ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ | -| `id` | 是 | `string` | 在设置或新手引导期间公开的提供商 ID。保持规范化 ID 在全局唯一。 | -| `authMethods` | 否 | `string[]` | 此提供商在不加载完整运行时的情况下支持的设置 / 鉴权方法 ID。 | -| `envVars` | 否 | `string[]` | 通用设置 / 状态界面可在插件运行时加载前检查的环境变量。 | +| `id` | 是 | `string` | 在设置或新手引导期间暴露的提供商 id。请保持规范化 id 在全局范围内唯一。 | +| `authMethods` | 否 | `string[]` | 此提供商在不加载完整运行时的情况下支持的设置/认证方法 id。 | +| `envVars` | 否 | `string[]` | 通用设置/状态界面可在插件运行时加载之前检查的环境变量。 | ### `setup` 字段 -| 字段 | 必需 | 类型 | 含义 | +| 字段 | 必填 | 类型 | 含义 | | ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | -| `providers` | 否 | `object[]` | 在设置和新手引导期间公开的提供商设置描述符。 | -| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置时后端 ID。保持规范化 ID 在全局唯一。 | -| `configMigrations` | 否 | `string[]` | 属于此插件设置界面的配置迁移 ID。 | +| `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的提供商设置描述符。 | +| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置时后端 id。请保持规范化 id 在全局范围内唯一。 | +| `configMigrations` | 否 | `string[]` | 属于此插件设置界面的配置迁移 id。 | | `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 | ## `uiHints` 参考 @@ -338,20 +338,20 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro } ``` -每个字段提示可以包含： +每个字段提示可包含： | 字段 | 类型 | 含义 | | ------------- | ---------- | --------------------------------------- | | `label` | `string` | 面向用户的字段标签。 | -| `help` | `string` | 简短帮助文本。 | -| `tags` | `string[]` | 可选的 UI 标签。 | -| `advanced` | `boolean` | 将该字段标记为高级字段。 | -| `sensitive` | `boolean` | 将该字段标记为密钥或敏感字段。 | +| `help` | `string` | 简短辅助文本。 | +| `tags` | `string[]` | 可选 UI 标签。 | +| `advanced` | `boolean` | 将该字段标记为高级项。 | +| `sensitive` | `boolean` | 将该字段标记为机密或敏感项。 | | `placeholder` | `string` | 表单输入的占位文本。 | ## `contracts` 参考 -仅当 OpenClaw 可以在不导入插件运行时的情况下读取静态能力归属元数据时，才使用 `contracts`。 +仅在 OpenClaw 可在不导入插件运行时的情况下读取静态能力归属元数据时使用 `contracts`。 ```json { @@ -376,30 +376,29 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro | 字段 | 类型 | 含义 | | -------------------------------- | ---------- | --------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | 已弃用的内嵌扩展工厂 ID。 | -| `agentToolResultMiddleware` | `string[]` | 内置插件可为其注册工具结果中间件的运行时 ID。 | -| `externalAuthProviders` | `string[]` | 其外部凭证 profile hook 由此插件拥有的提供商 ID。 | -| `speechProviders` | `string[]` | 由此插件拥有的语音提供商 ID。 | -| `realtimeTranscriptionProviders` | `string[]` | 由此插件拥有的实时转录提供商 ID。 | -| `realtimeVoiceProviders` | `string[]` | 由此插件拥有的实时语音提供商 ID。 | -| `memoryEmbeddingProviders` | `string[]` | 由此插件拥有的记忆嵌入提供商 ID。 | -| `mediaUnderstandingProviders` | `string[]` | 由此插件拥有的媒体理解提供商 ID。 | -| `imageGenerationProviders` | `string[]` | 由此插件拥有的图像生成提供商 ID。 | -| `videoGenerationProviders` | `string[]` | 由此插件拥有的视频生成提供商 ID。 | -| `webFetchProviders` | `string[]` | 由此插件拥有的 web-fetch 提供商 ID。 | -| `webSearchProviders` | `string[]` | 由此插件拥有的 Web 搜索提供商 ID。 | -| `tools` | `string[]` | 为内置契约检查而由此插件拥有的智能体工具名称。 | +| `embeddedExtensionFactories` | `string[]` | Codex app-server 扩展工厂 id，目前为 `codex-app-server`。 | +| `agentToolResultMiddleware` | `string[]` | 内置插件可为其注册工具结果中间件的运行时 id。 | +| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证配置文件 hook 的提供商 id。 | +| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 | +| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录提供商 id。 | +| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 | +| `memoryEmbeddingProviders` | `string[]` | 此插件拥有的 Memory 嵌入提供商 id。 | +| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 | +| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 | +| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 | +| `webFetchProviders` | `string[]` | 此插件拥有的 web-fetch 提供商 id。 | +| `webSearchProviders` | `string[]` | 此插件拥有的 Ollama Web 搜索提供商 id。 | +| `tools` | `string[]` | 用于内置契约检查的智能体工具名称，归此插件所有。 | -`contracts.embeddedExtensionFactories` 被保留用于仍需要直接 Pi 内嵌运行器事件的内置兼容代码。新的内置工具结果转换应声明 `contracts.agentToolResultMiddleware`，并改为使用 `api.registerAgentToolResultMiddleware(...)` 注册。 -外部插件无法注册工具结果中间件，因为该接口可以在模型看到之前重写高信任度工具输出。 +`contracts.embeddedExtensionFactories` 被保留用于内置的仅 Codex app-server 扩展工厂。内置工具结果转换应声明 `contracts.agentToolResultMiddleware`，并改为使用 `api.registerAgentToolResultMiddleware(...)` 注册。外部插件不能注册工具结果中间件，因为该接口能够在模型看到高信任度工具输出之前重写它。 -实现 `resolveExternalAuthProfiles` 的提供商插件应声明 `contracts.externalAuthProviders`。未声明该字段的插件仍会通过已弃用的兼容回退运行，但该回退更慢，并将在迁移窗口结束后移除。 +实现 `resolveExternalAuthProfiles` 的提供商插件应声明 `contracts.externalAuthProviders`。未声明该项的插件仍可通过已弃用的兼容性回退运行，但这种回退更慢，并将在迁移窗口结束后移除。 -内置记忆嵌入提供商应为其公开的每个适配器 ID 声明 `contracts.memoryEmbeddingProviders`，包括诸如 `local` 之类的内建适配器。独立 CLI 路径会使用此清单契约，仅在完整 Gateway 网关运行时注册提供商之前加载其所属插件。 +内置 Memory 嵌入提供商应为其暴露的每个适配器 id 声明 `contracts.memoryEmbeddingProviders`，包括诸如 `local` 这样的内置适配器。独立 CLI 路径使用此清单契约，在完整 Gateway 网关运行时注册提供商之前，仅加载所属插件。 ## `mediaUnderstandingProviderMetadata` 参考 -当媒体理解提供商具有默认模型、自动凭证回退优先级，或通用核心帮助器在运行时加载之前所需的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键还必须在 `contracts.mediaUnderstandingProviders` 中声明。 +当媒体理解提供商具有默认模型、自动认证回退优先级，或通用核心辅助工具在运行时加载之前需要的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键也必须在 `contracts.mediaUnderstandingProviders` 中声明。 ```json { @@ -422,25 +421,25 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro } ``` -每个提供商条目可以包含： +每个提供商条目可包含： | 字段 | 类型 | 含义 | | ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商公开的媒体能力。 | -| `defaultModels` | `Record` | 当配置未指定模型时使用的“能力到模型”默认值。 | -| `autoPriority` | `Record` | 对于基于凭证的自动提供商回退，数字越小排序越靠前。 | -| `nativeDocumentInputs` | `"pdf"[]` | 该提供商支持的原生文档输入。 | +| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商暴露的媒体能力。 | +| `defaultModels` | `Record` | 当配置未指定模型时使用的能力到模型默认值映射。 | +| `autoPriority` | `Record` | 用于基于凭证的自动提供商回退时，值越小排序越靠前。 | +| `nativeDocumentInputs` | `"pdf"[]` | 提供商支持的原生文档输入。 | ## `channelConfigs` 参考 -当渠道插件在运行时加载之前需要廉价的配置元数据时，请使用 `channelConfigs`。对于已配置的外部渠道，如果没有可用设置入口，或者 `setup.requiresRuntime: false` 声明设置运行时不是必需，则只读渠道设置 / 状态发现可直接使用这些元数据。 +当渠道插件在运行时加载之前需要轻量配置元数据时，请使用 `channelConfigs`。对于已配置的外部渠道，如果没有可用的设置入口，或 `setup.requiresRuntime: false` 声明设置运行时并非必需，只读渠道设置/状态发现可以直接使用此元数据。 对于渠道插件，`configSchema` 和 `channelConfigs` 描述的是不同路径： -- `configSchema` 验证 `plugins.entries..config` -- `channelConfigs..schema` 验证 `channels.` +- `configSchema` 校验 `plugins.entries..config` +- `channelConfigs..schema` 校验 `channels.` -声明了 `channels[]` 的非内置插件也应声明对应的 `channelConfigs` 条目。若未声明，OpenClaw 仍可加载该插件，但冷路径配置 schema、设置和 Control UI 界面在插件运行时执行之前无法知道该渠道自有选项的结构。 +声明了 `channels[]` 的非内置插件也应声明匹配的 `channelConfigs` 条目。否则，OpenClaw 仍然可以加载该插件，但冷路径配置 schema、设置和 Control UI 界面在插件运行时执行之前无法知道该渠道拥有的选项结构。 ```json { @@ -467,19 +466,19 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro } ``` -每个渠道条目可以包含： +每个渠道条目可包含： | 字段 | 类型 | 含义 | | ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | -| `schema` | `object` | `channels.` 的 JSON Schema。每个声明的渠道配置条目都必须提供。 | -| `uiHints` | `Record` | 该渠道配置段的可选 UI 标签 / 占位符 / 敏感性提示。 | +| `schema` | `object` | `channels.` 的 JSON Schema。每个已声明渠道配置条目都必须提供。 | +| `uiHints` | `Record` | 该渠道配置部分的可选 UI 标签 / 占位符 / 敏感性提示。 | | `label` | `string` | 当运行时元数据尚未准备好时，合并到选择器和检查界面中的渠道标签。 | | `description` | `string` | 用于检查和目录界面的简短渠道描述。 | -| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于的旧版或低优先级插件 ID。 | +| `preferOver` | `string[]` | 在选择界面中，该渠道应优先于的旧版或较低优先级插件 id。 | ## `modelSupport` 参考 -当 OpenClaw 应在插件运行时加载之前，通过诸如 `gpt-5.5` 或 `claude-sonnet-4.6` 之类的简写模型 ID 推断你的提供商插件时，请使用 `modelSupport`。 +当 OpenClaw 需要在插件运行时加载之前，从像 `gpt-5.5` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断你的提供商插件时，请使用 `modelSupport`。 ```json { @@ -490,70 +489,70 @@ OpenClaw 还会在通用提供商凭证和环境变量查找中包含 `setup.pro } ``` -OpenClaw 采用以下优先级： +OpenClaw 应用以下优先级： -- 显式 `provider/model` 引用使用其所属的 `providers` 清单元数据 +- 显式的 `provider/model` 引用使用所属 `providers` 清单元数据 - `modelPatterns` 优先于 `modelPrefixes` -- 如果一个非内置插件和一个内置插件同时匹配，则非内置插件胜出 -- 剩余歧义会被忽略，直到用户或配置明确指定提供商 +- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出 +- 其余歧义会被忽略，直到用户或配置指定提供商 字段： | 字段 | 类型 | 含义 | | --------------- | ---------- | ------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | 针对简写模型 ID 使用 `startsWith` 进行匹配的前缀。 | -| `modelPatterns` | `string[]` | 在移除 profile 后缀后，针对简写模型 ID 进行匹配的正则表达式源码。 | +| `modelPrefixes` | `string[]` | 使用 `startsWith` 与简写模型 id 进行匹配的前缀。 | +| `modelPatterns` | `string[]` | 在移除 profile 后缀后，与简写模型 id 进行匹配的正则表达式源码。 | -旧版顶层能力键已弃用。请使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；普通清单加载不再将这些顶层字段视为能力归属。 +旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；普通清单加载不再将这些顶层字段视为能力归属。 -## 清单与 `package.json` +## 清单与 package.json 的区别 这两个文件承担不同的职责： | 文件 | 用途 | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | 设备发现、配置验证、鉴权选项元数据，以及必须在插件代码运行前存在的 UI 提示 | +| `openclaw.plugin.json` | 设备发现、配置校验、认证选项元数据，以及在插件代码运行前必须存在的 UI 提示 | | `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 块 | -如果你不确定某条元数据应放在哪里，请使用以下规则： +如果你不确定某段元数据该放在哪里，请使用这条规则： -- 如果 OpenClaw 必须在加载插件代码之前知道它，请将其放入 `openclaw.plugin.json` -- 如果它与打包、入口文件或 npm 安装行为有关，请将其放入 `package.json` +- 如果 OpenClaw 必须在加载插件代码之前知道它，就放在 `openclaw.plugin.json` +- 如果它与打包、入口文件或 npm 安装行为有关，就放在 `package.json` ### 会影响设备发现的 `package.json` 字段 -一些运行时之前的插件元数据有意放在 `package.json` 的 `openclaw` 块下，而不是放在 `openclaw.plugin.json` 中。 +某些运行时之前的插件元数据有意放在 `package.json` 的 `openclaw` 块下，而不是 `openclaw.plugin.json` 中。 重要示例： | 字段 | 含义 | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | 声明原生插件入口点。必须保留在插件包目录内。 | -| `openclaw.runtimeExtensions` | 为已安装包声明已构建的 JavaScript 运行时入口点。必须保留在插件包目录内。 | -| `openclaw.setupEntry` | 轻量级、仅用于设置的入口点，用于新手引导、延迟渠道启动以及只读渠道状态 / SecretRef 发现。必须保留在插件包目录内。 | -| `openclaw.runtimeSetupEntry` | 为已安装包声明已构建的 JavaScript 设置入口点。必须保留在插件包目录内。 | -| `openclaw.channel` | 轻量级渠道目录元数据，例如标签、文档路径、别名和选择文案。 | -| `openclaw.channel.configuredState` | 轻量级已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已经存在仅环境变量的设置？”。 | -| `openclaw.channel.persistedAuthState` | 轻量级持久化凭证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何已登录状态？”。 | +| `openclaw.extensions` | 声明原生插件入口点。必须保留在插件包目录内部。 | +| `openclaw.runtimeExtensions` | 为已安装包声明构建后的 JavaScript 运行时入口点。必须保留在插件包目录内部。 | +| `openclaw.setupEntry` | 在新手引导、延迟渠道启动和只读渠道状态 / SecretRef 发现期间使用的轻量级仅设置入口点。必须保留在插件包目录内部。 | +| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保留在插件包目录内部。 | +| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择文案。 | +| `openclaw.channel.configuredState` | 轻量已配置状态检查器元数据，可以在不加载完整渠道运行时的情况下回答“是否已经存在仅环境变量配置的设置？”。 | +| `openclaw.channel.persistedAuthState` | 轻量持久化认证状态检查器元数据，可以在不加载完整渠道运行时的情况下回答“是否已经有任何内容登录了？”。 | | `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置和外部发布插件的安装 / 更新提示。 | -| `openclaw.install.defaultChoice` | 当存在多个安装来源时的首选安装路径。 | -| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 宿主版本，使用类似 `>=2026.3.22` 的 semver 下限。 | -| `openclaw.install.expectedIntegrity` | 预期的 npm dist 完整性字符串，例如 `sha512-...`；安装和更新流程会据此验证获取到的制品。 | -| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个范围狭窄的内置插件重新安装恢复路径。 | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许仅设置用的渠道界面在启动期间先于完整渠道插件加载。 | +| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 | +| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 | +| `openclaw.install.expectedIntegrity` | 预期的 npm dist 完整性字符串，例如 `sha512-...`；安装和更新流程会据此验证获取到的工件。 | +| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一条范围很窄的内置插件重装恢复路径。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许启动期间先加载仅设置的渠道界面，再加载完整渠道插件。 | -清单元数据决定了在运行时加载之前，新手引导中会出现哪些提供商 / 渠道 / 设置选项。`package.json#openclaw.install` 则告诉新手引导：当用户选择这些选项之一时，应如何获取或启用该插件。不要将安装提示移入 `openclaw.plugin.json`。 +清单元数据决定了在运行时加载之前，新手引导中会出现哪些提供商 / 渠道 / 设置选项。`package.json#openclaw.install` 则告诉新手引导：当用户选择其中某个选项时，应如何获取或启用该插件。不要将安装提示移入 `openclaw.plugin.json`。 -`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新的但有效的值会让旧宿主跳过该插件。 +`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新的但有效的值会让旧主机跳过该插件。 -精确的 npm 版本固定已经存在于 `npmSpec` 中，例如 -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。官方外部目录条目应将精确规格与 `expectedIntegrity` 配对使用，这样如果获取到的 npm 制品不再匹配固定发布版本，更新流程就会以封闭失败的方式中止。出于兼容性考虑，交互式新手引导仍会提供受信任注册表的 npm 规格，包括裸包名和 dist-tag。目录诊断可以区分精确、浮动、带完整性固定、缺少完整性、包名不匹配和无效默认选项来源。它们还会在存在 `expectedIntegrity` 但没有可用于固定的有效 npm 来源时发出警告。当存在 `expectedIntegrity` 时，安装 / 更新流程会强制执行它；当其被省略时，注册表解析结果会被记录，但不会带有完整性固定。 +精确的 npm 版本固定已经通过 `npmSpec` 提供，例如 +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。官方外部目录条目应将精确 spec 与 `expectedIntegrity` 搭配使用，这样如果获取到的 npm 工件不再匹配固定版本，更新流程就会失败即关闭。出于兼容性考虑，交互式新手引导仍会提供受信任注册表的 npm spec，包括裸包名和 dist-tag。目录诊断可以区分精确、浮动、带完整性固定、缺少完整性、包名不匹配和无效默认选项来源。它们还会在存在 `expectedIntegrity` 但没有可用于固定的有效 npm 来源时发出警告。当存在 `expectedIntegrity` 时，安装 / 更新流程会强制执行它；当省略它时，注册表解析结果会被记录，但不带完整性固定。 -当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账户时，渠道插件应提供 `openclaw.setupEntry`。该设置入口应公开渠道元数据以及适用于设置场景的配置、状态和密钥适配器；将网络客户端、Gateway 网关监听器和传输运行时保留在主扩展入口点中。 +当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账户时，渠道插件应提供 `openclaw.setupEntry`。该设置入口应暴露渠道元数据，以及对设置安全的配置、状态和 secrets 适配器；网络客户端、Gateway 网关监听器和传输运行时应保留在主扩展入口点中。 -运行时入口点字段不会覆盖源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能使一个越界的 `openclaw.extensions` 路径变为可加载。 +运行时入口点字段不会覆盖源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越界的 `openclaw.extensions` 路径变得可加载。 -`openclaw.install.allowInvalidConfigRecovery` 的范围是有意保持狭窄的。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的旧内置插件升级故障中恢复，例如缺失的内置插件路径，或属于同一内置插件的陈旧 `channels.` 条目。无关的配置错误仍会阻止安装，并将运维人员引导至 `openclaw doctor --fix`。 +`openclaw.install.allowInvalidConfigRecovery` 的范围是有意保持很窄的。它不会让任意损坏配置都变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件对应的陈旧 `channels.` 条目。无关的配置错误仍会阻止安装，并将操作人员引导至 `openclaw doctor --fix`。 `openclaw.channel.persistedAuthState` 是一个微型检查器模块的包元数据： @@ -571,9 +570,9 @@ OpenClaw 采用以下优先级： } ``` -当设置、doctor 或已配置状态流程需要在完整渠道插件加载之前进行廉价的“是 / 否”凭证探测时，请使用它。目标导出应是一个仅仅读取持久化状态的小函数；不要通过完整渠道运行时 barrel 来路由它。 +当设置、Doctor 或已配置状态流程需要在完整渠道插件加载之前进行一个低成本的认证“是 / 否”探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 暴露它。 -`openclaw.channel.configuredState` 对于廉价的仅环境变量已配置检查采用相同结构： +`openclaw.channel.configuredState` 对低成本的仅环境变量已配置检查采用相同结构： ```json { @@ -589,51 +588,55 @@ OpenClaw 采用以下优先级： } ``` -当某个渠道可以基于环境变量或其他微小的非运行时输入来回答已配置状态时，请使用它。如果该检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。 +当一个渠道可以根据环境变量或其他微小的非运行时输入回答已配置状态时，请使用它。如果检查需要完整配置解析或真实渠道运行时，则应将该逻辑保留在插件 `config.hasConfiguredState` hook 中。 -## 设备发现优先级（重复插件 ID） +## 设备发现优先级（重复的插件 id） -OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区、显式由配置选择的路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；较低优先级的重复项会被丢弃，而不会与其并行加载。 +OpenClaw 会从多个根位置发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两个发现结果共享相同的 `id`，则只保留**最高优先级**的清单；较低优先级的重复项会被丢弃，而不是与其并行加载。 优先级从高到低如下： -1. **配置选定** — 在 `plugins.entries.` 中显式固定的路径 -2. **内置** — 随 OpenClaw 一起发布的插件 -3. **全局安装** — 安装到全局 OpenClaw 插件根目录中的插件 -4. **工作区** — 相对于当前工作区发现的插件 +1. **配置选择** —— 在 `plugins.entries.` 中显式固定的路径 +2. **内置** —— 随 OpenClaw 一起发布的插件 +3. **全局安装** —— 安装到全局 OpenClaw 插件根目录的插件 +4. **工作区** —— 相对于当前工作区发现的插件 影响： -- 工作区中某个内置插件的 fork 或过期副本不会覆盖内置构建。 -- 如果你确实想用本地插件覆盖内置插件，请通过 `plugins.entries.` 固定它，使其凭借优先级获胜，而不是依赖工作区发现。 -- 被丢弃的重复项会被记录到日志中，以便 Doctor 和启动诊断可以指出被舍弃的副本。 +- 工作区中存在的内置插件分叉版或陈旧副本，不会遮蔽内置构建版本。 +- 若要真正用本地插件覆盖内置插件，请通过 `plugins.entries.` 固定它，使其通过优先级胜出，而不要依赖工作区发现。 +- 被丢弃的重复项会被记录日志，这样 Doctor 和启动诊断就可以指向被舍弃的副本。 ## JSON Schema 要求 - **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。 - 可以接受空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。 -- Schema 会在配置读取 / 写入时验证，而不是在运行时验证。 +- Schema 会在配置读取 / 写入时校验，而不是在运行时校验。 -## 验证行为 +## 校验行为 -- 未知的 `channels.*` 键是**错误**，除非该渠道 ID 由某个插件清单声明。 -- `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现**的插件 ID。未知 ID 是**错误**。 -- 如果插件已安装，但清单或 schema 缺失或损坏，则验证会失败，Doctor 会报告该插件错误。 -- 如果插件配置存在，但插件已**禁用**，则配置会被保留，并在 Doctor + 日志中显示**警告**。 +- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 是由 + 某个插件清单声明的。 +- `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` + 必须引用**可发现**的插件 id。未知 id 会被视为**错误**。 +- 如果插件已安装，但其清单或 schema 损坏或缺失， + 校验会失败，Doctor 会报告该插件错误。 +- 如果插件配置存在，但插件处于**禁用**状态，则配置会被保留，并且 + Doctor + 日志中会显示**警告**。 -完整 `plugins.*` schema 请参见 [Configuration reference](/zh-CN/gateway/configuration)。 +完整的 `plugins.*` schema 请参阅[配置参考](/zh-CN/gateway/configuration)。 ## 说明 -- 对于**原生 OpenClaw 插件**，包括本地文件系统加载，清单都是**必需的**。运行时仍会单独加载插件模块；清单仅用于设备发现 + 验证。 -- 原生清单使用 JSON5 解析，因此只要最终值仍是一个对象，就接受注释、尾随逗号和未加引号的键。 -- 清单加载器只会读取文档中说明的清单字段。避免使用自定义顶层键。 -- 当插件不需要它们时，`channels`、`providers`、`cliBackends` 和 `skills` 都可以省略。 -- `providerDiscoveryEntry` 必须保持轻量，不应导入宽泛的运行时代码；应将其用于静态提供商目录元数据或狭义发现描述符，而不是请求时执行。 -- 排他性插件类型通过 `plugins.slots.*` 进行选择：`kind: "memory"` 通过 `plugins.slots.memory` 选择，`kind: "context-engine"` 通过 `plugins.slots.contextEngine` 选择（默认值 `legacy`）。 -- 环境变量元数据（`setup.providers[].envVars`、已弃用的 `providerAuthEnvVars` 和 `channelEnvVars`）仅是声明式的。状态、审计、cron 投递验证和其他只读界面在将某个环境变量视为已配置之前，仍会应用插件信任和有效激活策略。 -- 对于需要提供商代码的运行时向导元数据，请参见 [Provider runtime hooks](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 -- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器 allowlist 要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 +- **原生 OpenClaw 插件必须提供清单**，包括本地文件系统加载。运行时仍会单独加载插件模块；清单仅用于设备发现 + 校验。 +- 原生清单使用 JSON5 解析，因此支持注释、尾随逗号和未加引号的键，只要最终值仍然是一个对象即可。 +- 清单加载器只会读取已记录的清单字段。避免使用自定义顶层键。 +- 当插件不需要时，可以省略 `channels`、`providers`、`cliBackends` 和 `skills`。 +- `providerDiscoveryEntry` 必须保持轻量，不应导入大范围运行时代码；应将其用于静态提供商目录元数据或狭义设备发现描述符，而不是请求时执行。 +- 互斥插件种类通过 `plugins.slots.*` 选择：`kind: "memory"` 通过 `plugins.slots.memory` 选择，`kind: "context-engine"` 通过 `plugins.slots.contextEngine` 选择（默认值为 `legacy`）。 +- 环境变量元数据（`setup.providers[].envVars`、已弃用的 `providerAuthEnvVars` 和 `channelEnvVars`）仅是声明式信息。在将某个环境变量视为已配置之前，状态、审计、cron 投递校验和其他只读界面仍会应用插件信任和有效激活策略。 +- 对于需要提供商代码的运行时向导元数据，请参阅[提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。 +- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 ## 相关内容 diff --git a/docs/zh-CN/plugins/sdk-agent-harness.md b/docs/zh-CN/plugins/sdk-agent-harness.md index 1bac15a38..a73879068 100644 --- a/docs/zh-CN/plugins/sdk-agent-harness.md +++ b/docs/zh-CN/plugins/sdk-agent-harness.md @@ -1,55 +1,49 @@ --- read_when: - - 你正在更改嵌入式智能体运行时或 Harness 注册表 - - 你正在从内置或受信任插件注册一个智能体 Harness + - 你正在更改内嵌智能体运行时或 Harness 注册表 + - 你正在从内置或受信任的插件注册一个智能体 Harness - 你需要了解 Codex 插件与模型提供商之间的关系 sidebarTitle: Agent Harness -summary: 面向替换底层嵌入式智能体执行器的插件实验性 SDK 接口 +summary: 供替换底层内嵌智能体执行器的插件使用的实验性 SDK 接口 title: 智能体 Harness 插件 x-i18n: - generated_at: "2026-04-25T00:42:27Z" + generated_at: "2026-04-25T01:27:31Z" model: gpt-5.4 provider: openai - source_hash: 350dcfa9492ab30d14913a1f275747a5074f5d8651a96309f6002cdf9b8b2803 + source_hash: 6a451995a18bce70b02eea88e2ac52561e21208c40cf93b88fc921aad49dffec source_path: plugins/sdk-agent-harness.md workflow: 15 --- -**智能体 Harness** 是一个已准备好的 OpenClaw 智能体 -轮次的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。 +**智能体 Harness** 是为单个已准备好的 OpenClaw 智能体轮次提供的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。 -仅对内置或受信任的原生插件使用这一接口。该契约 -仍是实验性的，因为参数类型有意映射当前的嵌入式运行器。 +仅将此接口用于内置或受信任的原生插件。该契约仍然是实验性的，因为参数类型有意映射当前的内嵌运行器。 ## 何时使用 Harness -当某个模型家族拥有自己的原生会话 -运行时，而常规 OpenClaw 提供商传输并不是合适抽象时，请注册智能体 Harness。 +当某个模型家族拥有自己的原生会话运行时，而常规的 OpenClaw 提供商传输层并不是合适抽象时，请注册一个智能体 Harness。 示例： - 拥有线程和压缩能力的原生编码智能体服务器 - 必须流式传输原生计划 / 推理 / 工具事件的本地 CLI 或守护进程 -- 除了 OpenClaw - 会话转录外还需要自身恢复 id 的模型运行时 +- 除 OpenClaw 会话转录记录之外，还需要自己的恢复 id 的模型运行时 -不要仅仅为了添加新的 LLM API 就注册 Harness。对于普通 HTTP 或 -WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 +**不要** 只是为了添加一个新的 LLM API 就注册 Harness。对于普通的 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 ## 核心仍然负责的内容 -在选择 Harness 之前，OpenClaw 已经解析好了： +在选择 Harness 之前，OpenClaw 已经解析了： - 提供商和模型 -- 运行时认证状态 -- thinking 级别和上下文预算 -- OpenClaw 转录 / 会话文件 +- 运行时凭证状态 +- 思考级别和上下文预算 +- OpenClaw 转录记录 / 会话文件 - 工作区、沙箱和工具策略 -- 渠道回复回调和流式回调 +- 渠道回复回调和流式传输回调 - 模型回退和实时模型切换策略 -这种划分是有意为之。Harness 运行的是一个已准备好的尝试；它不会选择 -提供商、替换渠道投递，也不会静默切换模型。 +这种划分是有意设计的。Harness 运行的是一个已准备好的尝试；它不会选择提供商、替换渠道投递，或静默切换模型。 ## 注册 Harness @@ -89,111 +83,58 @@ export default definePluginEntry({ ## 选择策略 -OpenClaw 会在提供商 / 模型解析之后选择 Harness： +OpenClaw 会在提供商 / 模型解析完成后选择一个 Harness： -1. 现有会话中记录的 Harness id 优先，因此配置 / 环境变化不会 - 将该转录热切换到另一个运行时。 -2. `OPENCLAW_AGENT_RUNTIME=` 会为 - 尚未固定的会话强制使用具有该 id 的已注册 Harness。 -3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置 PI Harness。 -4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册的 Harness，它们是否支持已解析的 - 提供商 / 模型。 -5. 如果没有匹配的已注册 Harness，OpenClaw 会使用 PI，除非禁用了 PI 回退。 +1. 现有会话中记录的 Harness id 优先，因此配置 / 环境变量变更不会将该转录记录热切换到另一个运行时。 +2. `OPENCLAW_AGENT_RUNTIME=` 会为尚未固定的会话强制使用具有该 id 的已注册 Harness。 +3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI Harness。 +4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册的 Harness 是否支持已解析的提供商 / 模型。 +5. 如果没有匹配的已注册 Harness，除非 PI 回退已被禁用，否则 OpenClaw 会使用 PI。 -插件 Harness 失败会作为运行失败显示出来。在 `auto` 模式下，仅当没有已注册的插件 Harness 支持已解析的 -提供商 / 模型时，才会使用 PI 回退。一旦某个插件 Harness 已经接管了一次运行，OpenClaw 不会 -再通过 PI 重放同一轮次，因为这可能改变认证 / 运行时语义 -或导致副作用重复发生。 +插件 Harness 失败会表现为运行失败。在 `auto` 模式下，仅当没有任何已注册的插件 Harness 支持已解析的提供商 / 模型时，才会使用 PI 回退。一旦某个插件 Harness 已接管一次运行，OpenClaw 不会再通过 PI 重放同一个轮次，因为那可能改变凭证 / 运行时语义或导致副作用重复。 -所选的 Harness id 会在一次嵌入式运行后与会话 id 一起持久化。 -在 Harness 固定机制出现之前创建的旧会话，一旦有转录历史，就会被视为已固定到 PI。 -在 PI 和原生插件 Harness 之间切换时，请使用新的 / 重置后的会话。 -`/status` 会在 `Fast` 旁显示非默认 Harness id，例如 `codex`； -PI 会保持隐藏，因为它是默认兼容路径。 -如果选中的 Harness 出乎你的意料，请启用 `agents/harness` 调试日志，并 -检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含 -选中的 Harness id、选择原因、运行时 / 回退策略，以及在 -`auto` 模式下每个插件候选项的支持结果。 +选中的 Harness id 会在一次内嵌运行后与会话 id 一起持久化。在 Harness 固定机制出现之前创建的旧会话，只要已有转录历史，就会被视为已固定到 PI。在 PI 与原生插件 Harness 之间切换时，请使用新的 / 重置后的会话。`/status` 会在 `Fast` 旁显示诸如 `codex` 之类的非默认 Harness id；PI 因为是默认兼容路径而保持隐藏。如果选中的 Harness 出乎你的预期，请启用 `agents/harness` 调试日志，并检查 Gateway 网关的结构化 `agent harness selected` 记录。它包含选中的 Harness id、选择原因、运行时 / 回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。 -内置 Codex 插件将 `codex` 注册为其 Harness id。核心将其视为 -普通的插件 Harness id；Codex 专属别名应放在插件 -或运维人员配置中，而不是共享运行时选择器中。 +内置的 Codex 插件将 `codex` 注册为它的 Harness id。核心将其视为普通的插件 Harness id；Codex 专用别名应放在插件或操作员配置中，而不是共享运行时选择器中。 ## 提供商与 Harness 配对 -大多数 Harness 也应同时注册一个提供商。提供商会让模型引用、 -认证状态、模型元数据和 `/model` 选择对 OpenClaw 其余部分可见。 -然后 Harness 在 `supports(...)` 中接管该提供商。 +大多数 Harness 也应注册一个提供商。提供商会让模型引用、凭证状态、模型元数据和 `/model` 选择对 OpenClaw 的其余部分可见。然后 Harness 在 `supports(...)` 中声明该提供商。 -内置 Codex 插件遵循这一模式： +内置的 Codex 插件遵循这一模式： -- 提供商 id：`codex` -- 用户模型引用：`openai/gpt-5.5` 加 `embeddedHarness.runtime: "codex"`； - 旧版 `codex/gpt-*` 引用仍被接受以保持兼容 -- Harness id：`codex` -- 认证：合成提供商可用性，因为 Codex Harness 负责 - 原生 Codex 登录 / 会话 -- app-server 请求：OpenClaw 将裸模型 id 发送给 Codex，并让 - Harness 与原生 app-server 协议通信 +- provider id：`codex` +- 用户模型引用：`openai/gpt-5.5` 加上 `embeddedHarness.runtime: "codex"`；旧版 `codex/gpt-*` 引用仍然出于兼容性而被接受 +- harness id：`codex` +- auth：合成的提供商可用性，因为 Codex Harness 拥有原生 Codex 登录 / 会话 +- app-server 请求：OpenClaw 将裸模型 id 发送给 Codex，并让 Harness 与原生 app-server 协议通信 -Codex 插件是增量式的。普通 `openai/gpt-*` 引用仍会使用常规 -OpenClaw 提供商路径，除非你通过 -`embeddedHarness.runtime: "codex"` 强制使用 Codex Harness。较旧的 `codex/gpt-*` 引用 -仍会为兼容性选择 Codex 提供商和 Harness。 +Codex 插件是增量式的。普通的 `openai/gpt-*` 引用会继续使用常规 OpenClaw 提供商路径，除非你通过 `embeddedHarness.runtime: "codex"` 强制使用 Codex Harness。较旧的 `codex/gpt-*` 引用仍会出于兼容性而选择 Codex 提供商和 Harness。 -关于运维设置、模型前缀示例和仅限 Codex 的配置，请参见 -[Codex Harness](/zh-CN/plugins/codex-harness)。 +关于操作员设置、模型前缀示例和仅限 Codex 的配置，请参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 -OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会检查 -app-server 初始化握手，并阻止较旧版本或无版本服务器，以确保 -OpenClaw 只运行在其已测试过的协议接口上。 +OpenClaw 要求 Codex app-server 为 `0.118.0` 或更高版本。Codex 插件会检查 app-server 初始化握手，并阻止更旧或未带版本号的服务器，以确保 OpenClaw 仅在它已测试过的协议接口上运行。 ### 工具结果中间件 -当清单在 `contracts.agentToolResultMiddleware` 中声明了目标 -运行时 id 时，内置插件可以通过 -`api.registerAgentToolResultMiddleware(...)` 挂接运行时无关的工具结果中间件。这个受信任 -扩展点用于那些必须在 PI 或 Codex 将 -工具输出回送给模型之前运行的异步工具结果转换。 +当内置插件的清单在 `contracts.agentToolResultMiddleware` 中声明了目标运行时 id 时，它们可以通过 `api.registerAgentToolResultMiddleware(...)` 附加运行时无关的工具结果中间件。这个受信任接口用于异步工具结果转换，这些转换必须在 PI 或 Codex 将工具输出反馈给模型之前运行。 -旧版内置插件仍然可以使用 -`api.registerCodexAppServerExtensionFactory(...)` 进行仅限 Codex app-server 的 -中间件处理，但新的结果转换应使用运行时无关 API。 -仅限 Pi 的 `api.registerEmbeddedExtensionFactory(...)` 钩子 -对于工具结果转换已弃用；仅应保留给仍然需要直接 Pi 嵌入式运行器事件的 -内置兼容代码。 +旧版内置插件仍可使用 `api.registerCodexAppServerExtensionFactory(...)` 来实现仅适用于 Codex app-server 的中间件，但新的结果转换应使用运行时无关 API。 +仅限 Pi 的 `api.registerEmbeddedExtensionFactory(...)` 钩子已被移除；Pi 工具结果转换必须使用运行时无关中间件。 ### 原生 Codex Harness 模式 -内置的 `codex` Harness 是嵌入式 OpenClaw -智能体轮次的原生 Codex 模式。请先启用内置 `codex` 插件， -如果你的配置使用限制性允许列表，还需将 `codex` 加入 -`plugins.allow`。原生 app-server 配置应使用带有 -`embeddedHarness.runtime: "codex"` 的 `openai/gpt-*`。 -若要通过 PI 使用 Codex OAuth，请改用 `openai-codex/*`。旧版 `codex/*` -模型引用仍保留为原生 Harness 的兼容别名。 +内置的 `codex` Harness 是内嵌 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置的 `codex` 插件；如果你的配置使用了限制性 allowlist，还需要在 `plugins.allow` 中包含 `codex`。原生 app-server 配置应使用 `openai/gpt-*` 并设置 `embeddedHarness.runtime: "codex"`。若要通过 PI 使用 Codex OAuth，请改用 `openai-codex/*`。旧版 `codex/*` 模型引用仍保留为原生 Harness 的兼容别名。 -在此模式运行时，Codex 负责原生线程 id、恢复行为、 -压缩和 app-server 执行。OpenClaw 仍然负责聊天渠道、 -可见转录镜像、工具策略、审批、媒体投递和会话 -选择。当你需要证明只有 Codex -app-server 路径可以接管该次运行时，请使用 -`embeddedHarness.runtime: "codex"` 和 -`embeddedHarness.fallback: "none"`。该配置仅是一个选择保护： -Codex app-server 失败本来就会直接失败，而不会再通过 PI 重试。 +当该模式运行时，Codex 负责原生线程 id、恢复行为、压缩和 app-server 执行。OpenClaw 仍然负责聊天渠道、可见转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径可以接管运行时，请使用 `embeddedHarness.runtime: "codex"` 并配合 `embeddedHarness.fallback: "none"`。该配置只是一个选择保护措施：Codex app-server 失败本来就会直接失败，而不是通过 PI 重试。 ## 禁用 PI 回退 -默认情况下，OpenClaw 会以 -`agents.defaults.embeddedHarness` -设置为 `{ runtime: "auto", fallback: "pi" }` 来运行嵌入式智能体。在 `auto` 模式下，已注册的插件 -Harness 可以接管某个提供商 / 模型组合。如果没有匹配项，OpenClaw 会回退到 PI。 +默认情况下，OpenClaw 运行内嵌智能体时，`agents.defaults.embeddedHarness` 设置为 `{ runtime: "auto", fallback: "pi" }`。在 `auto` 模式下，已注册的插件 Harness 可以接管某个提供商 / 模型对。如果没有匹配项，OpenClaw 会回退到 PI。 -当你需要在未选中插件 Harness 时直接失败，而不是使用 PI 时， -请设置 `fallback: "none"`。已选中的插件 Harness 失败本来就会硬失败。 -这不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。 +当你需要在缺少插件 Harness 选择时直接失败，而不是使用 PI 时，请设置 `fallback: "none"`。已选中的插件 Harness 失败本来就会硬失败。这不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。 -对于仅限 Codex 的嵌入式运行： +对于仅限 Codex 的内嵌运行： ```json { @@ -209,7 +150,7 @@ Harness 可以接管某个提供商 / 模型组合。如果没有匹配项，Ope } ``` -如果你希望任何已注册的插件 Harness 都可以接管匹配的模型，但永远不想让 OpenClaw 静默回退到 PI，请保留 `runtime: "auto"` 并禁用回退： +如果你希望任何已注册的插件 Harness 都可以接管匹配的模型，但绝不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退： ```json { @@ -224,7 +165,7 @@ Harness 可以接管某个提供商 / 模型组合。如果没有匹配项，Ope } ``` -每个智能体的覆盖项使用相同结构： +按智能体覆盖使用相同的结构： ```json { @@ -249,9 +190,7 @@ Harness 可以接管某个提供商 / 模型组合。如果没有匹配项，Ope } ``` -`OPENCLAW_AGENT_RUNTIME` 仍会覆盖已配置的运行时。使用 -`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可从 -环境变量中禁用 PI 回退。 +`OPENCLAW_AGENT_RUNTIME` 仍会覆盖已配置的运行时。使用 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可通过环境变量禁用 PI 回退。 ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -259,45 +198,34 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -禁用回退后，如果请求的 Harness 未注册、 -不支持已解析的提供商 / 模型，或在产生轮次副作用之前失败， -会话就会提前失败。这是 Codex 专用部署以及必须证明确实使用了 Codex -app-server 路径的实时测试所期望的行为。 +在禁用回退的情况下，如果请求的 Harness 未注册、不支持已解析的提供商 / 模型，或在产生轮次副作用之前失败，会话会尽早失败。这是 Codex 专用部署以及必须证明 Codex app-server 路径确实在使用中的实时测试所期望的行为。 -此设置只控制嵌入式智能体 Harness。它不会禁用 -图像、视频、音乐、TTS、PDF 或其他提供商专属模型路由。 +此设置仅控制内嵌智能体 Harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他特定提供商的模型路由。 ## 原生会话与转录镜像 -Harness 可以保留原生会话 id、线程 id 或守护进程侧恢复令牌。 -请将这种绑定明确关联到 OpenClaw 会话，并持续将用户可见的助手 / 工具输出镜像到 OpenClaw 转录中。 +Harness 可以保留原生会话 id、线程 id 或守护进程侧恢复令牌。请将这种绑定显式地与 OpenClaw 会话关联，并持续将用户可见的助手 / 工具输出镜像到 OpenClaw 转录记录中。 -OpenClaw 转录仍然是以下能力的兼容层： +OpenClaw 转录记录仍然是以下内容的兼容层： - 渠道可见的会话历史 -- 转录搜索和索引 -- 在后续轮次切回内置 PI Harness -- 通用 `/new`、`/reset` 和会话删除行为 +- 转录记录搜索与索引 +- 在后续轮次切换回内置 PI Harness +- 通用的 `/new`、`/reset` 和会话删除行为 -如果你的 Harness 存储了 sidecar 绑定，请实现 `reset(...)`，以便 OpenClaw 能在所属 OpenClaw 会话被重置时 -清除它。 +如果你的 Harness 存储了一个 sidecar 绑定，请实现 `reset(...)`，以便 OpenClaw 在所属 OpenClaw 会话被重置时清除它。 ## 工具和媒体结果 -核心会构建 OpenClaw 工具列表并将其传入已准备好的尝试中。 -当 Harness 执行动态工具调用时，请通过 -Harness 结果结构返回工具结果，而不是自行发送渠道媒体。 +核心会构造 OpenClaw 工具列表并将其传入已准备好的尝试中。当 Harness 执行动态工具调用时，请通过 Harness 结果结构返回工具结果，而不是自行发送渠道媒体。 -这样可以让文本、图像、视频、音乐、TTS、审批和消息工具输出 -与基于 PI 的运行共用同一投递路径。 +这样可以让文本、图像、视频、音乐、TTS、审批以及消息工具输出与基于 PI 的运行共享同一条投递路径。 ## 当前限制 -- 公共导入路径是通用的，但一些尝试 / 结果类型别名 - 为了兼容仍带有 `Pi` 名称。 -- 第三方 Harness 安装仍属实验性。除非你确实需要原生会话运行时， - 否则优先选择提供商插件。 -- 支持跨轮次切换 Harness。不要在某一轮次中途，在原生工具、审批、助手文本或消息发送已经开始之后再切换 Harness。 +- 公共导入路径是通用的，但某些 attempt / result 类型别名仍然保留 `Pi` 命名以维持兼容性。 +- 第三方 Harness 安装仍是实验性的。在你确实需要原生会话运行时之前，请优先使用提供商插件。 +- 支持跨轮次切换 Harness。不要在一个轮次中途、在原生工具、审批、助手文本或消息发送已经开始后切换 Harness。 ## 相关内容 diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 7f8ca1843..c82548956 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -1,93 +1,83 @@ --- read_when: - - 你看到了 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 警告 - - 你看到了 OPENCLAW_EXTENSION_API_DEPRECATED 警告 - - 你使用 `api.registerEmbeddedExtensionFactory` - - 你正在将插件更新到现代插件架构 + - 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 + - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 + - 你在 OpenClaw 2026.4.24 之前使用了 `api.registerEmbeddedExtensionFactory` + - 你正在将插件更新为现代插件架构 - 你维护一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-25T00:43:05Z" + generated_at: "2026-04-25T01:27:32Z" model: gpt-5.4 provider: openai - source_hash: b7848b0f92414fbd39d8e102b1e6e465dc08214588ba1970d194dde1258e1779 + source_hash: 109261bd1358dab30dc521b5103201e6f8b06800650497bcb86bb4e423694eff source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw 已从宽泛的向后兼容层迁移到具有聚焦、文档化导入路径的现代插件架构。如果你的插件构建于新架构之前，本指南可帮助你完成迁移。 +OpenClaw 已经从宽泛的向后兼容层迁移到现代插件架构，采用聚焦、文档化的导入方式。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 ## 正在发生什么变化 -旧插件系统提供了两个开放范围很大的表面，让插件可以从单一入口点导入所需的任何内容： +旧版插件系统提供了两个开放范围很大的接口，使插件可以从单一入口点导入所需的任何内容： -- **`openclaw/plugin-sdk/compat`** —— 一个单一导入路径，会重新导出数十个辅助工具。它的引入是为了在新插件架构构建期间，让较旧的基于钩子的插件继续工作。 -- **`openclaw/extension-api`** —— 一个桥接层，为插件提供对宿主侧辅助工具的直接访问，例如嵌入式智能体运行器。 -- **`api.registerEmbeddedExtensionFactory(...)`** —— 一个仅限 Pi 的内置插件钩子，可观察嵌入式运行器事件，例如 `tool_result`。 +- **`openclaw/plugin-sdk/compat`** — 一个会重新导出几十个辅助函数的单一导入入口。它的引入是为了在构建新插件架构期间，让较旧的基于钩子的插件继续正常工作。 +- **`openclaw/extension-api`** — 一个桥接层，让插件能够直接访问宿主端的辅助功能，例如嵌入式智能体运行器。 +- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除的、仅限 Pi 的内置扩展钩子，可以观察诸如 `tool_result` 之类的嵌入式运行器事件。 -这些表面现已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 +这些宽泛的导入接口现已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。 -OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解释已文档化的插件行为。破坏性合约变更必须先经过兼容适配器、诊断、文档和弃用窗口。这个原则适用于 SDK 导入、manifest 字段、设置 API、钩子和运行时注册行为。 +OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已文档化的插件行为。破坏契约的变更必须先经过兼容适配器、诊断、文档以及弃用窗口。这一规则适用于 SDK 导入、清单字段、设置 API、钩子以及运行时注册行为。 - 向后兼容层将在未来的主版本中移除。 - 届时，仍从这些表面导入的插件将会失效。 + 向后兼容层将在未来的主要版本中移除。 + 到那时，仍从这些接口导入的插件将会中断。 + 仅限 Pi 的嵌入式扩展工厂注册已经不再加载。 ## 为什么会有这个变化 -旧方法带来了一些问题： +旧方法会导致一些问题： -- **启动缓慢** —— 导入一个辅助工具会加载数十个无关模块 -- **循环依赖** —— 宽泛的重新导出使得创建导入环变得很容易 -- **API 表面不清晰** —— 无法区分哪些导出是稳定的，哪些是内部实现 +- **启动缓慢** — 导入一个辅助函数会加载几十个无关模块 +- **循环依赖** — 宽泛的重新导出使创建导入循环变得很容易 +- **API 接口不清晰** — 无法分辨哪些导出是稳定的，哪些是内部实现 -现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有清晰的用途和文档化的合约。 +现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含模块，具有明确用途和文档化契约。 -面向内置渠道的旧版 provider 便捷接缝也已移除。诸如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接缝以及 -`openclaw/plugin-sdk/telegram-core` 之类的导入，都是私有 mono-repo 快捷方式，而不是稳定的插件合约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，请将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +面向内置渠道的旧版提供商便捷接口也已经移除。诸如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口以及 `openclaw/plugin-sdk/telegram-core` 之类的导入，都是私有单体仓库快捷方式，而不是稳定的插件契约。请改用更窄的通用 SDK 子路径。在内置插件工作区内部，请将提供商自有辅助函数保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 -当前内置 provider 示例： +当前内置提供商示例： -- Anthropic 将 Claude 专属的流式辅助工具保留在其自己的 `api.ts` / - `contract-api.ts` 接缝中 -- OpenAI 将 provider 构建器、默认模型辅助工具和实时 provider - 构建器保留在其自己的 `api.ts` 中 -- OpenRouter 将 provider 构建器和新手引导 / 配置辅助工具保留在其自己的 - `api.ts` 中 +- Anthropic 将 Claude 专用的流式辅助函数保留在其自己的 `api.ts` / `contract-api.ts` 接口中 +- OpenAI 将提供商构建器、默认模型辅助函数以及实时提供商构建器保留在其自己的 `api.ts` 中 +- OpenRouter 将提供商构建器以及新手引导 / 配置辅助函数保留在其自己的 `api.ts` 中 ## 兼容性策略 对于外部插件，兼容性工作遵循以下顺序： -1. 添加新合约 +1. 添加新契约 2. 通过兼容适配器保持旧行为继续接通 3. 发出诊断或警告，明确指出旧路径及其替代方案 4. 在测试中覆盖两条路径 -5. 记录弃用和迁移路径 -6. 仅在已公告的迁移窗口之后移除，通常是在主版本中 +5. 记录弃用信息和迁移路径 +6. 仅在宣布的迁移窗口结束后移除，通常是在主要版本中 -如果某个 manifest 字段仍然被接受，插件作者就可以继续使用它，直到文档和诊断另有说明。新代码应优先使用文档化的替代方案，但现有插件不应在常规次版本发布中被破坏。 +如果某个清单字段仍被接受，插件作者就可以继续使用它，直到文档和诊断另有说明。新代码应优先使用文档化的替代方案，但现有插件不应在普通的小版本发布中被破坏。 ## 如何迁移 - - 内置插件应将仅限 Pi 的 + + 内置插件必须将仅限 Pi 的 `api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为 - 运行时无关的中间件。 + 与运行时无关的中间件。 ```typescript - // Before: Pi-only compatibility hook - api.registerEmbeddedExtensionFactory((pi) => { - pi.on("tool_result", async (event) => { - return compactToolResult(event); - }); - }); - - // After: Pi and Codex runtime dynamic tools + // Pi and Codex runtime dynamic tools api.registerAgentToolResultMiddleware(async (event) => { return compactToolResult(event); }, { @@ -95,7 +85,7 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 }); ``` - 同时更新插件 manifest： + 同时更新插件清单： ```json { @@ -105,14 +95,13 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 } ``` - 仅对仍需直接访问 Pi 嵌入式运行器事件的内置兼容代码保留 `contracts.embeddedExtensionFactories`。 - 外部插件不能注册工具结果中间件，因为它会在模型看到高信任工具输出之前重写这些输出。 + 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任度工具输出之前重写这些输出。 具备审批能力的渠道插件现在通过 - `approvalCapability.nativeRuntime` 加上共享的运行时上下文注册表来暴露原生审批行为。 + `approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来公开原生审批行为。 关键变化： @@ -120,26 +109,26 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 `approvalCapability.nativeRuntime` - 将审批专用的认证 / 投递逻辑从旧版 `plugin.auth` / `plugin.approvals` 接线迁移到 `approvalCapability` - - `ChannelPlugin.approvals` 已从公共渠道插件 - 合约中移除；请将 delivery/native/render 字段迁移到 `approvalCapability` - - `plugin.auth` 仅保留给渠道登录 / 登出流程；其中的审批认证 - 钩子不再被 core 读取 + - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除； + 请将 delivery / native / render 字段迁移到 `approvalCapability` + - `plugin.auth` 仅保留给渠道登录 / 登出流程使用；其中的审批认证 + 钩子不再被核心读取 - 通过 `openclaw/plugin-sdk/channel-runtime-context` - 注册渠道自有的运行时对象，例如客户端、token 或 Bolt + 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt 应用 - - 不要从原生审批处理器发送插件自有的重路由通知； - core 现在根据实际投递结果负责 routed-elsewhere 通知 - - 当把 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 - `createPluginRuntime().channel` 表面。部分 stub 会被拒绝。 + - 不要从原生审批处理器发送插件自有的改道路由通知； + 核心现在会根据实际投递结果统一负责“已路由到其他位置”的通知 + - 当把 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供一个 + 真实的 `createPluginRuntime().channel` 接口。部分桩实现将被拒绝。 - 当前审批能力布局请参见 `/plugins/sdk-channel-plugins`。 + 请参阅 `/plugins/sdk-channel-plugins`，了解当前的审批能力布局。 - + 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`， - 那么无法解析的 Windows `.cmd`/`.bat` wrapper 现在会默认失败关闭，除非你显式传入 - `allowShellFallback: true`。 + 那么未解析的 Windows `.cmd`/`.bat` 包装器现在会默认失败关闭， + 除非你显式传入 `allowShellFallback: true`。 ```typescript // Before @@ -148,8 +137,8 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // 仅对受信任的兼容调用方设置此项，这些调用方有意 - // 接受经 shell 中介的回退。 + // Only set this for trusted compatibility callers that intentionally + // accept shell-mediated fallback. allowShellFallback: true, }); ``` @@ -159,8 +148,8 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 - - 在你的插件中搜索来自任一已弃用表面的导入： + + 在你的插件中搜索来自以下任一已弃用接口的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -170,7 +159,7 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 - 旧表面中的每个导出都映射到一个特定的现代导入路径： + 旧接口中的每个导出都映射到一个特定的现代导入路径： ```typescript // Before (deprecated backwards-compatibility layer) @@ -186,7 +175,7 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - 对于宿主侧辅助工具，请使用注入的插件运行时，而不是直接导入： + 对于宿主端辅助函数，请使用注入的插件运行时，而不是直接导入： ```typescript // Before (deprecated extension-api bridge) @@ -197,9 +186,9 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - 其他旧版桥接辅助工具也适用相同模式： + 同样的模式也适用于其他旧版桥接辅助函数： - | 旧导入 | 现代等价项 | + | 旧导入 | 现代等价方式 | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -207,7 +196,7 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | session store helpers | `api.runtime.agent.session.*` | + | 会话存储辅助函数 | `api.runtime.agent.session.*` | @@ -224,210 +213,209 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 面向渠道入口定义 / 构建器的旧版伞式重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | 规范插件入口辅助函数 | `definePluginEntry` | + | `plugin-sdk/core` | 用于渠道入口定义 / 构建器的旧版伞式重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | 单一 provider 入口辅助工具 | `defineSingleProviderPluginEntry` | + | `plugin-sdk/provider-entry` | 单提供商入口辅助函数 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助工具 | 允许列表提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 可安全导入的设置补丁适配器、查找备注辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | - | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表 / 配置 / 操作门控辅助工具 | - | `plugin-sdk/account-id` | 账户 id 辅助工具 | `DEFAULT_ACCOUNT_ID`、账户 id 规范化 | - | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表 / 账户操作辅助工具 | - | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | - | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 输入中状态接线 | `createChannelReplyPipeline` | + | `plugin-sdk/setup` | 共享设置向导辅助函数 | Allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup-runtime` | 设置时运行时辅助函数 | 导入安全的设置补丁适配器、lookup-note 辅助函数、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | + | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助函数 | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | 设置工具辅助函数 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | 多账户辅助函数 | 账户列表 / 配置 / action-gate 辅助函数 | + | `plugin-sdk/account-id` | account-id 辅助函数 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 | + | `plugin-sdk/account-resolution` | 账户查找辅助函数 | 账户查找 + 默认回退辅助函数 | + | `plugin-sdk/account-helpers` | 窄范围账户辅助函数 | 账户列表 / 账户操作辅助函数 | + | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/channel-pairing` | 私信 配对原语 | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入接线 | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语；以内置渠道命名的 schema 导出仅用于旧版兼容 | - | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复 / 冲突校验 | - | `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览最终化辅助工具 | - | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope 构建器辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并派发辅助工具 | - | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助工具 | - | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站 identity / send 委托和负载规划辅助工具 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 用于旧版字段布局的智能体媒体负载构建器 | - | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时工具 | + | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语；带内置渠道名称的 schema 导出仅用于旧版兼容性 | + | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助函数 | 命令名称规范化、描述裁剪、重复 / 冲突校验 | + | `plugin-sdk/channel-policy` | 群组 / 私信 策略解析 | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助函数 | `createAccountStatusSink`、草稿预览完成辅助函数 | + | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助函数 | 共享 route + envelope 构建辅助函数 | + | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助函数 | 共享 record-and-dispatch 辅助函数 | + | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助函数 | + | `plugin-sdk/outbound-media` | 出站媒体辅助函数 | 共享出站媒体加载 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助函数 | 出站身份 / 发送委托和负载规划辅助函数 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助函数 | 线程绑定生命周期和适配器辅助函数 | + | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助函数 | 用于旧版字段布局的智能体媒体负载构建器 | + | `plugin-sdk/channel-runtime` | 已弃用的兼容性垫片 | 仅限旧版渠道运行时工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时 / 日志 / 备份 / 插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | Logger / 运行时环境、超时、重试和退避辅助工具 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / 钩子 / HTTP / 交互式辅助工具 | - | `plugin-sdk/hook-runtime` | 钩子管线辅助工具 | 共享 webhook / 内部钩子管线辅助工具 | - | `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 | - | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 | - | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 | - | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 合约表面不可用时，提供稳定回退的 Telegram 命令校验辅助工具 | - | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批负载、审批能力 / 配置档辅助工具、原生审批路由 / 运行时辅助工具 | - | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | approver 解析、同一聊天中的操作认证 | - | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置档 / 过滤辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力 / 投递适配器 | - | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向热渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 范围更广的审批处理器运行时辅助工具；如果较窄的 adapter / gateway 接缝已足够，优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复负载辅助工具 | - | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register / get / watch 辅助工具 | - | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享 trust、私信门控、外部内容和秘密收集辅助工具 | - | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机允许列表和私有网络策略辅助工具 | - | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | pinned-dispatcher、受保护 fetch、SSRF 策略辅助工具 | - | `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 | - | `plugin-sdk/fetch-runtime` | 包装后的 fetch / proxy 辅助工具 | `resolveFetch`、proxy 辅助工具 | - | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 | - | `plugin-sdk/allow-from` | 允许列表格式化 | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | 允许列表输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令门控和命令表面辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | + | `plugin-sdk/runtime` | 宽范围运行时辅助函数 | 运行时 / 日志 / 备份 / 插件安装辅助函数 | + | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助函数 | Logger / 运行时环境、超时、重试和退避辅助函数 | + | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助函数 | 插件命令 / 钩子 / http / 交互式辅助函数 | + | `plugin-sdk/hook-runtime` | 钩子流水线辅助函数 | 共享 webhook / 内部钩子流水线辅助函数 | + | `plugin-sdk/lazy-runtime` | 惰性运行时辅助函数 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程辅助函数 | 共享 exec 辅助函数 | + | `plugin-sdk/cli-runtime` | CLI 运行时辅助函数 | 命令格式化、等待、版本辅助函数 | + | `plugin-sdk/gateway-runtime` | Gateway 网关辅助函数 | Gateway 网关客户端和渠道状态补丁辅助函数 | + | `plugin-sdk/config-runtime` | 配置辅助函数 | 配置加载 / 写入辅助函数 | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助函数 | 当内置 Telegram 契约接口不可用时，提供回退稳定的 Telegram 命令校验辅助函数 | + | `plugin-sdk/approval-runtime` | 审批提示辅助函数 | exec / 插件审批负载、approval capability / profile 辅助函数、原生审批路由 / 运行时辅助函数 | + | `plugin-sdk/approval-auth-runtime` | 审批认证辅助函数 | approver 解析、同聊天操作认证 | + | `plugin-sdk/approval-client-runtime` | 审批客户端辅助函数 | 原生 exec 审批 profile / filter 辅助函数 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助函数 | 原生 approval capability / delivery 适配器 | + | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助函数 | 共享审批 Gateway 网关解析辅助函数 | + | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助函数 | 用于热渠道入口点的轻量级原生审批适配器加载辅助函数 | + | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助函数 | 范围更广的审批处理器运行时辅助函数；如果更窄的 adapter / gateway 接口已足够，优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 审批目标辅助函数 | 原生审批目标 / 账户绑定辅助函数 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助函数 | exec / 插件审批回复负载辅助函数 | + | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助函数 | 通用渠道运行时上下文 register / get / watch 辅助函数 | + | `plugin-sdk/security-runtime` | 安全辅助函数 | 共享信任、私信 门控、外部内容和密钥收集辅助函数 | + | `plugin-sdk/ssrf-policy` | SSRF 策略辅助函数 | 主机 allowlist 和私有网络策略辅助函数 | + | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助函数 | pinned-dispatcher、guarded fetch、SSRF 策略辅助函数 | + | `plugin-sdk/collection-runtime` | 有界缓存辅助函数 | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助函数 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | 错误格式化辅助函数 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助函数 | + | `plugin-sdk/fetch-runtime` | 封装 fetch / proxy 辅助函数 | `resolveFetch`、proxy 辅助函数 | + | `plugin-sdk/host-runtime` | 主机规范化辅助函数 | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | 重试辅助函数 | `RetryConfig`, `retryAsync`、策略运行器 | + | `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | allowlist 输入映射 | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | 命令门控和命令接口辅助函数 | `resolveControlCommandGate`、发送方授权辅助函数、命令注册表辅助函数 | | `plugin-sdk/command-status` | 命令状态 / 帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | Secret 输入解析 | Secret 输入辅助工具 | - | `plugin-sdk/webhook-ingress` | Webhook 请求辅助工具 | Webhook 目标工具 | - | `plugin-sdk/webhook-request-guards` | Webhook 请求体保护辅助工具 | 请求体读取 / 限制辅助工具 | - | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站派发、Heartbeat、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复派发辅助工具 | 最终化、provider 派发和会话标签辅助工具 | - | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助函数 | + | `plugin-sdk/webhook-ingress` | webhook 请求辅助函数 | webhook 目标工具 | + | `plugin-sdk/webhook-request-guards` | webhook 请求体守卫辅助函数 | 请求体读取 / 限制辅助函数 | + | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | + | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助函数 | 完成、提供商分发和会话标签辅助函数 | + | `plugin-sdk/reply-history` | 回复历史辅助函数 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本 / Markdown 分块辅助工具 | - | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 | - | `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 | - | `plugin-sdk/routing` | 路由 / 会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 | - | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道 / 账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | - | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 | - | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug / 字符串规范化辅助工具 | - | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类似请求的输入中提取字符串 URL | - | `plugin-sdk/run-command` | 定时命令辅助工具 | 带标准化 stdout / stderr 的定时命令运行器 | - | `plugin-sdk/param-readers` | 参数读取器 | 常用工具 / CLI 参数读取器 | + | `plugin-sdk/reply-chunking` | 回复分块辅助函数 | 文本 / markdown 分块辅助函数 | + | `plugin-sdk/session-store-runtime` | 会话存储辅助函数 | 存储路径 + updated-at 辅助函数 | + | `plugin-sdk/state-paths` | 状态路径辅助函数 | 状态和 OAuth 目录辅助函数 | + | `plugin-sdk/routing` | 路由 / session-key 辅助函数 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、session-key 规范化辅助函数 | + | `plugin-sdk/status-helpers` | 渠道状态辅助函数 | 渠道 / 账户状态摘要构建器、运行时状态默认值、问题元数据辅助函数 | + | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助函数 | 共享目标解析器辅助函数 | + | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助函数 | slug / 字符串规范化辅助函数 | + | `plugin-sdk/request-url` | 请求 URL 辅助函数 | 从类请求输入中提取字符串 URL | + | `plugin-sdk/run-command` | 定时命令辅助函数 | 带标准化 stdout / stderr 的定时命令运行器 | + | `plugin-sdk/param-readers` | 参数读取器 | 通用工具 / CLI 参数读取器 | | `plugin-sdk/tool-payload` | 工具负载提取 | 从工具结果对象中提取标准化负载 | | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | - | `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 | - | `plugin-sdk/logging-core` | 日志辅助工具 | 子系统 logger 和脱敏辅助工具 | - | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 | + | `plugin-sdk/temp-path` | 临时路径辅助函数 | 共享临时下载路径辅助函数 | + | `plugin-sdk/logging-core` | 日志辅助函数 | 子系统 logger 和脱敏辅助函数 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助函数 | Markdown 表格模式辅助函数 | | `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 | - | `plugin-sdk/provider-setup` | 经过整理的本地 / 自托管 provider 设置辅助工具 | 自托管 provider 发现 / 配置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管 provider 设置辅助工具 | 同样的自托管 provider 发现 / 配置辅助工具 | - | `plugin-sdk/provider-auth-runtime` | provider 运行时认证辅助工具 | 运行时 API 密钥解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | provider API 密钥设置辅助工具 | API 密钥新手引导 / 配置档写入辅助工具 | - | `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result 构建器 | - | `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 | - | `plugin-sdk/provider-selection-runtime` | provider 选择辅助工具 | “已配置或自动” provider 选择和原始 provider 配置合并 | - | `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider 认证环境变量查找辅助工具 | - | `plugin-sdk/provider-model-shared` | 共享 provider 模型 / 重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、provider 端点辅助工具和模型 id 规范化辅助工具 | - | `plugin-sdk/provider-catalog-shared` | 共享 provider 目录辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 | - | `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP / 端点能力辅助工具，包括音频转录 multipart form 辅助工具 | - | `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | Web-fetch provider 注册 / 缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | provider Web 搜索配置辅助工具 | 面向不需要插件启用接线的 provider 的窄范围 Web 搜索配置 / 凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | provider Web 搜索合约辅助工具 | 窄范围 Web 搜索配置 / 凭证合约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及有作用域的凭证 setter / getter | - | `plugin-sdk/provider-web-search` | provider Web 搜索辅助工具 | Web 搜索 provider 注册 / 缓存 / 运行时辅助工具 | - | `plugin-sdk/provider-tools` | provider 工具 / schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | provider 用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他 provider 用量辅助工具 | - | `plugin-sdk/provider-stream` | provider 流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助工具 | - | `plugin-sdk/provider-transport-runtime` | provider 传输辅助工具 | 原生 provider 传输辅助工具，例如受保护的 fetch、传输消息转换和可写传输事件流 | + | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 | 自托管提供商发现 / 配置辅助函数 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助函数 | 相同的自托管提供商发现 / 配置辅助函数 | + | `plugin-sdk/provider-auth-runtime` | 提供商运行时认证辅助函数 | 运行时 API key 解析辅助函数 | + | `plugin-sdk/provider-auth-api-key` | 提供商 API key 设置辅助函数 | API key 新手引导 / profile 写入辅助函数 | + | `plugin-sdk/provider-auth-result` | 提供商 auth-result 辅助函数 | 标准 OAuth auth-result 构建器 | + | `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助函数 | 共享交互式登录辅助函数 | + | `plugin-sdk/provider-selection-runtime` | 提供商选择辅助函数 | 已配置或自动提供商选择，以及原始提供商配置合并 | + | `plugin-sdk/provider-env-vars` | 提供商环境变量辅助函数 | 提供商认证环境变量查找辅助函数 | + | `plugin-sdk/provider-model-shared` | 共享提供商模型 / 重放辅助函数 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数以及 model-id 规范化辅助函数 | + | `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助函数 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助函数 | + | `plugin-sdk/provider-http` | 提供商 HTTP 辅助函数 | 通用提供商 HTTP / endpoint capability 辅助函数，包括音频转录 multipart form 辅助函数 | + | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助函数 | web-fetch 提供商注册 / 缓存辅助函数 | + | `plugin-sdk/provider-web-search-config-contract` | 提供商 web-search 配置辅助函数 | 面向不需要插件启用接线的提供商的窄范围 web-search 配置 / 凭证辅助函数 | + | `plugin-sdk/provider-web-search-contract` | 提供商 web-search 契约辅助函数 | 窄范围 web-search 配置 / 凭证契约辅助函数，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` 以及作用域凭证 setter / getter | + | `plugin-sdk/provider-web-search` | 提供商 web-search 辅助函数 | web-search 提供商注册 / 缓存 / 运行时辅助函数 | + | `plugin-sdk/provider-tools` | 提供商工具 / schema 兼容性辅助函数 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | 提供商用量辅助函数 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他提供商用量辅助函数 | + | `plugin-sdk/provider-stream` | 提供商流包装辅助函数 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装类型，以及共享 Anthropic / Bedrock / Google / Kilocode / Moonshot AI / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助函数 | + | `plugin-sdk/provider-transport-runtime` | 提供商传输辅助函数 | 原生提供商传输辅助函数，例如 guarded fetch、传输消息转换以及可写传输事件流 | | `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取 / 转换 / 存储辅助工具，以及媒体负载构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像 / 视频 / 音乐生成的共享故障转移辅助工具、候选选择和缺失模型消息 | - | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像 / 音频辅助工具导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、Markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、指令标签辅助工具、安全文本工具，以及相关文本 / 日志辅助工具 | - | `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的指令、注册表和校验辅助工具 | - | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、指令、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表 / 解析辅助工具，以及桥接会话辅助工具 | - | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助工具 | - | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider / 请求 / 结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider / 请求 / 结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化 / 归约 | - | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道配置 schema 原语 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 | - | `plugin-sdk/channel-plugin-common` | 共享渠道前导 | 共享渠道插件前导导出 | - | `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照 / 摘要辅助工具 | - | `plugin-sdk/allowlist-config-edit` | 允许列表配置辅助工具 | 允许列表配置编辑 / 读取辅助工具 | - | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证 / 保护辅助工具 | - | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态和环境代理辅助原语 | - | `plugin-sdk/webhook-targets` | Webhook 目标辅助工具 | Webhook 目标注册表和路由安装辅助工具 | - | `plugin-sdk/webhook-path` | Webhook 路径辅助工具 | Webhook 路径规范化辅助工具 | - | `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程 / 本地媒体加载辅助工具 | - | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 核心管理器 / 配置 / 文件 / CLI 辅助表面 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时门面 | Memory 索引 / 搜索运行时门面 | + | `plugin-sdk/media-runtime` | 共享媒体辅助函数 | 媒体获取 / 转换 / 存储辅助函数，以及媒体负载构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助函数 | 图像 / 视频 / 音乐生成的共享故障转移辅助函数、候选项选择以及缺失模型消息 | + | `plugin-sdk/media-understanding` | 媒体理解辅助函数 | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享文本辅助函数 | 对助手可见文本的剥离、markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数、安全文本工具以及相关文本 / 日志辅助函数 | + | `plugin-sdk/text-chunking` | 文本分块辅助函数 | 出站文本分块辅助函数 | + | `plugin-sdk/speech` | 语音辅助函数 | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助函数 | + | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、directives、规范化 | + | `plugin-sdk/realtime-transcription` | 实时转录辅助函数 | 提供商类型、注册表辅助函数以及共享 WebSocket 会话辅助函数 | + | `plugin-sdk/realtime-voice` | 实时语音辅助函数 | 提供商类型、注册表 / 解析辅助函数以及桥接会话辅助函数 | + | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助函数 | + | `plugin-sdk/music-generation` | 音乐生成辅助函数 | 音乐生成提供商 / 请求 / 结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成辅助函数 | 视频生成提供商 / 请求 / 结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/interactive-runtime` | 交互式回复辅助函数 | 交互式回复负载规范化 / 归约 | + | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道 config-schema 原语 | + | `plugin-sdk/channel-config-writes` | 渠道 config-write 辅助函数 | 渠道 config-write 授权辅助函数 | + | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 | + | `plugin-sdk/channel-status` | 渠道状态辅助函数 | 共享渠道状态快照 / 摘要辅助函数 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助函数 | allowlist 配置编辑 / 读取辅助函数 | + | `plugin-sdk/group-access` | 群组访问辅助函数 | 共享群组访问决策辅助函数 | + | `plugin-sdk/direct-dm` | 直接私信辅助函数 | 共享直接私信 认证 / 守卫辅助函数 | + | `plugin-sdk/extension-shared` | 共享扩展辅助函数 | 被动渠道 / 状态和环境代理辅助原语 | + | `plugin-sdk/webhook-targets` | webhook 目标辅助函数 | webhook 目标注册表和 route-install 辅助函数 | + | `plugin-sdk/webhook-path` | webhook 路径辅助函数 | webhook 路径规范化辅助函数 | + | `plugin-sdk/web-media` | 共享 Web 媒体辅助函数 | 远程 / 本地媒体加载辅助函数 | + | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用方重新导出的 `zod` | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助函数 | Memory 核心管理器 / 配置 / 文件 / CLI 辅助接口 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时外观 | Memory 索引 / 搜索运行时外观 | | `plugin-sdk/memory-core-host-engine-foundation` | Memory 宿主基础引擎 | Memory 宿主基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入合约、注册表访问、本地 provider 和通用批处理 / 远程辅助工具；具体远程 provider 位于其所属插件中 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地提供商以及通用批处理 / 远程辅助函数；具体远程提供商位于其所属插件中 | | `plugin-sdk/memory-core-host-engine-qmd` | Memory 宿主 QMD 引擎 | Memory 宿主 QMD 引擎导出 | | `plugin-sdk/memory-core-host-engine-storage` | Memory 宿主存储引擎 | Memory 宿主存储引擎导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory 宿主多模态辅助工具 | Memory 宿主多模态辅助工具 | - | `plugin-sdk/memory-core-host-query` | Memory 宿主查询辅助工具 | Memory 宿主查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory 宿主 secret 辅助工具 | Memory 宿主 secret 辅助工具 | - | `plugin-sdk/memory-core-host-events` | Memory 宿主事件日志辅助工具 | Memory 宿主事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | Memory 宿主状态辅助工具 | Memory 宿主状态辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory 宿主 CLI 运行时 | Memory 宿主 CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory 宿主核心运行时 | Memory 宿主核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件 / 运行时辅助工具 | Memory 宿主文件 / 运行时辅助工具 | - | `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向供应商中立的 Memory 宿主核心运行时辅助工具别名 | - | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向供应商中立的 Memory 宿主事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | Memory 宿主文件 / 运行时别名 | 面向供应商中立的 Memory 宿主文件 / 运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助工具 | 面向邻近 Memory 的插件的共享托管 Markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索门面 | 惰性活跃 Memory 搜索管理器运行时门面 | - | `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向供应商中立的 Memory 宿主状态辅助工具别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助表面 | - | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mock | + | `plugin-sdk/memory-core-host-multimodal` | Memory 宿主多模态辅助函数 | Memory 宿主多模态辅助函数 | + | `plugin-sdk/memory-core-host-query` | Memory 宿主查询辅助函数 | Memory 宿主查询辅助函数 | + | `plugin-sdk/memory-core-host-secret` | Memory 宿主密钥辅助函数 | Memory 宿主密钥辅助函数 | + | `plugin-sdk/memory-core-host-events` | Memory 宿主事件日志辅助函数 | Memory 宿主事件日志辅助函数 | + | `plugin-sdk/memory-core-host-status` | Memory 宿主状态辅助函数 | Memory 宿主状态辅助函数 | + | `plugin-sdk/memory-core-host-runtime-cli` | Memory 宿主 CLI 运行时 | Memory 宿主 CLI 运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-core` | Memory 宿主核心运行时 | Memory 宿主核心运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件 / 运行时辅助函数 | Memory 宿主文件 / 运行时辅助函数 | + | `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向供应商中立的 Memory 宿主核心运行时辅助函数别名 | + | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向供应商中立的 Memory 宿主事件日志辅助函数别名 | + | `plugin-sdk/memory-host-files` | Memory 宿主文件 / 运行时别名 | 面向供应商中立的 Memory 宿主文件 / 运行时辅助函数别名 | + | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助函数 | 面向与 Memory 邻接插件的共享托管 markdown 辅助函数 | + | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索外观 | 惰性活跃 Memory search-manager 运行时外观 | + | `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向供应商中立的 Memory 宿主状态辅助函数别名 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助函数 | Memory-lancedb 辅助接口 | + | `plugin-sdk/testing` | 测试工具 | 测试辅助函数和 mocks | -此表有意只包含常见迁移子集，而不是完整的 SDK -表面。完整的 200+ 入口点列表位于 +这个表刻意只包含常见迁移子集，而不是完整的 SDK +接口。完整的 200+ 个入口点列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 -该列表仍包含一些内置插件辅助接缝，例如 -`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 -`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些导出仍然保留，用于 -内置插件维护和兼容性，但它们被有意从常见迁移表中省略，并且不是 -新插件代码的推荐目标。 +该列表仍然包含一些内置插件辅助接口，例如 +`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, +`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些接口仍会继续导出， +用于内置插件维护和兼容性，但它们被有意省略在常见迁移表之外，也不是 +新插件代码推荐使用的目标。 -同样的规则也适用于其他内置辅助工具家族，例如： +同样的规则也适用于其他内置辅助函数家族，例如： -- 浏览器支持辅助工具：`plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` +- 浏览器支持辅助函数：`plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix：`plugin-sdk/matrix*` - LINE：`plugin-sdk/line*` - IRC：`plugin-sdk/irc*` -- 内置辅助工具 / 插件表面，例如 `plugin-sdk/googlechat`、 - `plugin-sdk/zalouser`、`plugin-sdk/bluebubbles*`、 - `plugin-sdk/mattermost*`、`plugin-sdk/msteams`、 - `plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、 - `plugin-sdk/twitch`、 - `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、 - `plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、 +- 内置辅助函数 / 插件接口，例如 `plugin-sdk/googlechat`, + `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, + `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, + `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, + `plugin-sdk/twitch`, + `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, + `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` 和 `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` 目前暴露的窄范围 token 辅助表面包括 -`DEFAULT_COPILOT_API_BASE_URL`、 +`plugin-sdk/github-copilot-token` 当前暴露了窄范围的令牌辅助接口 +`DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 请使用与任务最匹配的最窄导入路径。如果你找不到某个导出， -请检查 `src/plugin-sdk/` 下的源码，或在 Discord 中提问。 +请检查 `src/plugin-sdk/` 中的源码，或在 Discord 中提问。 -## 活跃弃用项 +## 当前弃用项 -适用于整个插件 SDK、provider 合约、 -运行时表面和 manifest 的更窄范围弃用项。它们目前仍然可用，但将在未来的主版本中移除。每一项下方的条目都将旧 API 映射到其规范替代方案。 +以下是横跨插件 SDK、提供商契约、运行时接口和清单的更窄范围弃用项。它们目前仍然可用，但将在未来的主要版本中移除。每个条目下方都给出了旧 API 到其规范替代方案的映射。 - - **旧版（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`、 - `buildCommandsMessagePaginated`、`buildHelpMessage`。 + + **旧版（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`, + `buildCommandsMessagePaginated`, `buildHelpMessage`。 - **新版（`openclaw/plugin-sdk/command-status`）**：相同签名、相同 - 导出——只是改为从更窄的子路径导入。`command-auth` - 将它们作为兼容 stub 重新导出。 + **新版（`openclaw/plugin-sdk/command-status`）**：签名相同，导出相同—— + 只是从更窄的子路径导入。`command-auth` + 将它们重新导出为兼容性桩。 ```typescript // Before @@ -439,59 +427,61 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 - + **旧版**：`resolveInboundMentionRequirement({ facts, policy })` 和 `shouldDropInboundForMention(...)`，来自 `openclaw/plugin-sdk/channel-inbound` 或 `openclaw/plugin-sdk/channel-mention-gating`。 - **新版**：`resolveInboundMentionDecision({ facts, policy })`——返回的是 - 单一决策对象，而不是拆分成两个调用。 + **新版**：`resolveInboundMentionDecision({ facts, policy })` —— 返回一个 + 单一决策对象，而不是拆分为两个调用。 - 下游渠道插件（Slack、Discord、Matrix、Microsoft Teams）都已完成切换。 + 下游渠道插件（Slack、Discord、Matrix、Microsoft Teams）已经完成切换。 - - `openclaw/plugin-sdk/channel-runtime` 是面向旧版 - 渠道插件的兼容性 shim。不要在新代码中导入它；请使用 + + `openclaw/plugin-sdk/channel-runtime` 是为较旧 + 渠道插件提供的兼容性垫片。新代码不要导入它；请使用 `openclaw/plugin-sdk/channel-runtime-context` 来注册运行时 对象。 - `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助工具 - 已与原始 “actions” 渠道导出一同弃用。请改为通过语义化的 `presentation` - 表面暴露能力——渠道插件声明自己能渲染什么（卡片、按钮、选择器）， - 而不是声明自己接受哪些原始 action 名称。 + `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助函数 + 已与原始 “actions” 渠道导出一起弃用。请改为通过语义化的 + `presentation` 接口暴露能力——渠道插件声明它们能渲染什么 + （cards、buttons、selects），而不是声明它们接受哪些原始 + action 名称。 - - **旧版**：`openclaw/plugin-sdk/provider-web-search` 中的 `tool()` 工厂。 + + **旧版**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` + 工厂。 - **新版**：直接在 provider 插件上实现 `createTool(...)`。 - OpenClaw 不再需要 SDK 辅助工具来注册工具包装器。 + **新版**：直接在提供商插件上实现 `createTool(...)`。 + OpenClaw 不再需要 SDK 辅助函数来注册工具包装器。 - + **旧版**：`formatInboundEnvelope(...)`（以及 - `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建扁平的纯文本提示词 - envelope。 + `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建 + 扁平纯文本提示 envelope。 **新版**：`BodyForAgent` 加结构化用户上下文块。渠道 - 插件会将路由元数据（线程、主题、回复目标、反应）作为 - 类型化字段附加，而不是将它们拼接到一个提示词字符串中。 - `formatAgentEnvelope(...)` 辅助工具对于合成的 - 面向助手的 envelope 仍然受支持，但入站纯文本 envelope 正在 - 逐步退出。 + 插件会将路由元数据（thread、topic、reply-to、reactions）作为 + 类型化字段附加，而不是把它们拼接进提示字符串中。 + `formatAgentEnvelope(...)` 辅助函数仍然支持用于合成的、 + 面向助手的 envelope，但入站纯文本 envelope 正在被逐步淘汰。 受影响区域：`inbound_claim`、`message_received`，以及任何对 - `channelEnvelope` 文本进行后处理的自定义渠道插件。 + `channelEnvelope` 文本做后处理的自定义渠道插件。 - - 四个发现类型别名现在都只是目录时代类型的薄包装： + + 四个 discovery 类型别名现在只是对 + catalog 时代类型的轻量封装： | 旧别名 | 新类型 | | ------------------------- | ------------------------- | @@ -500,33 +490,32 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 | `ProviderDiscoveryResult` | `ProviderCatalogResult` | | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - 以及旧版 `ProviderCapabilities` 静态集合——provider 插件 - 应通过 provider 运行时合约附加能力事实， - 而不是使用静态对象。 + 以及旧版的 `ProviderCapabilities` 静态集合——提供商插件 + 应通过提供商运行时契约附加能力事实，而不是使用静态对象。 - - **旧版**（`ProviderThinkingPolicy` 上的三个独立钩子）： + + **旧版**（`ProviderThinkingPolicy` 上三个独立钩子）： `isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)` 和 `resolveDefaultThinkingLevel(ctx)`。 - **新版**：单一的 `resolveThinkingProfile(ctx)`，它返回一个 - `ProviderThinkingProfile`，其中包含规范 `id`、可选的 `label` 和 - 排序后的级别列表。OpenClaw 会按配置档等级自动降级陈旧的已存储值。 + **新版**：单个 `resolveThinkingProfile(ctx)`，返回一个 + `ProviderThinkingProfile`，包含规范 `id`、可选 `label` 以及 + 按级别排序的列表。OpenClaw 会按 profile 排名自动降级过期的已存储值。 - 现在实现一个钩子即可，不再需要三个。旧版钩子在 - 弃用窗口期间仍可使用，但不会与配置档结果组合。 + 只需实现一个钩子，而不是三个。旧版钩子在弃用窗口期间仍可使用， + 但不会与 profile 结果进行组合。 - - **旧版**：实现 `resolveExternalOAuthProfiles(...)`， - 却不在插件 manifest 中声明该 provider。 + + **旧版**：在插件清单中未声明提供商的情况下，实现 + `resolveExternalOAuthProfiles(...)`。 - **新版**：在插件 manifest 中声明 `contracts.externalAuthProviders` - **并且**实现 `resolveExternalAuthProfiles(...)`。旧版 “auth - fallback” 路径会在运行时发出警告，并将在之后被移除。 + **新版**：在插件清单中声明 `contracts.externalAuthProviders` + **并且**实现 `resolveExternalAuthProfiles(...)`。旧的 “auth + fallback” 路径会在运行时发出警告，并将在后续移除。 ```json { @@ -538,35 +527,35 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 - - **旧版** manifest 字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 + + **旧版**清单字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 - **新版**：将相同的环境变量查找镜像到 manifest 中的 `setup.providers[].envVars`。 - 这样可将设置 / 状态环境变量元数据集中到一个位置， - 并避免仅为了回答环境变量查找而启动插件运行时。 + **新版**：将相同的环境变量查找镜像到清单中的 `setup.providers[].envVars` + 中。这样可以把设置 / 状态环境变量元数据整合到一个位置， + 并避免仅仅为了回答环境变量查找而启动插件运行时。 - `providerAuthEnvVars` 会继续通过兼容适配器受支持， + `providerAuthEnvVars` 仍然通过兼容适配器支持， 直到弃用窗口结束。 - + **旧版**：三个独立调用—— `api.registerMemoryPromptSection(...)`、 `api.registerMemoryFlushPlan(...)`、 `api.registerMemoryRuntime(...)`。 - **新版**：在 memory-state API 上进行一次调用—— + **新版**：在 memory-state API 上使用一个调用—— `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。 - 相同的插槽，单一注册调用。增量式 Memory 辅助工具 - （`registerMemoryPromptSupplement`、`registerMemoryCorpusSupplement`、 + 相同插槽，单次注册调用。附加型 Memory 辅助函数 + （`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, `registerMemoryEmbeddingProvider`）不受影响。 - - 仍然从 `src/plugins/runtime/types.ts` 导出的两个旧版类型别名： + + 仍从 `src/plugins/runtime/types.ts` 导出的两个旧版类型别名： | 旧版 | 新版 | | ----------------------------- | ------------------------------- | @@ -574,16 +563,16 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | 运行时方法 `readSession` 已弃用，改用 - `getSessionMessages`。 - 签名相同；旧方法会转调到新方法。 + `getSessionMessages`。签名相同；旧方法会直接调用 + 新方法。 - **旧版**：`runtime.tasks.flow`（单数）返回实时任务流访问器。 + **旧版**：`runtime.tasks.flow`（单数）返回一个实时 task-flow 访问器。 **新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问， - 这样导入更安全，也不需要加载完整任务运行时。 + 它具备导入安全性，且不需要加载完整任务运行时。 ```typescript // Before @@ -594,18 +583,18 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 - - 已在上文“如何迁移 → 将 Pi 工具结果插件迁移到 - 中间件”中说明。此处为完整性再次列出：仅限 Pi 的 - `api.registerEmbeddedExtensionFactory(...)` 路径已弃用，取而代之的是 - `api.registerAgentToolResultMiddleware(...)`，并在 `contracts.agentToolResultMiddleware` - 中显式声明运行时列表。 + + 上文“如何迁移 → 将 Pi 工具结果扩展迁移到中间件”中已涵盖。这里列出 + 仅为完整性考虑：已移除的、仅限 Pi 的 + `api.registerEmbeddedExtensionFactory(...)` 路径现由 + `api.registerAgentToolResultMiddleware(...)` 替代，并在 + `contracts.agentToolResultMiddleware` 中提供显式运行时 + 列表。 - - 从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` - 现在只是 `OpenClawConfig` 的 - 一行别名。请优先使用规范名称。 + + 从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` 现在是 + `OpenClawConfig` 的一行别名。请优先使用规范名称。 ```typescript // Before @@ -618,10 +607,10 @@ OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解 -扩展级别弃用项（位于 `extensions/` 下内置渠道 / provider 插件内部） +扩展级弃用项（位于 `extensions/` 下的内置渠道 / 提供商插件内部） 会在它们各自的 `api.ts` 和 `runtime-api.ts` -barrel 中跟踪。它们不会影响第三方插件合约，因此不在此列出。 -如果你直接使用某个内置插件的本地 barrel，请在升级前阅读该 +barrel 中跟踪。它们不会影响第三方插件契约，因此未在此列出。如果你直接 +使用某个内置插件的本地 barrel，请在升级前先阅读该 barrel 中的弃用注释。 @@ -629,27 +618,27 @@ barrel 中的弃用注释。 | 时间 | 会发生什么 | | ---------------------- | ----------------------------------------------------------------------- | -| **现在** | 已弃用表面会发出运行时警告 | -| **下一个主版本** | 已弃用表面将被移除；仍在使用它们的插件将会失效 | +| **现在** | 已弃用接口会发出运行时警告 | +| **下一个主要版本** | 已弃用接口将被移除；仍在使用它们的插件将会失败 | -所有 core 插件都已完成迁移。外部插件应在下一个主版本之前完成迁移。 +所有核心插件都已经完成迁移。外部插件应在下一个主要版本之前完成迁移。 ## 临时抑制警告 -在你处理迁移期间，可设置以下环境变量： +在你进行迁移期间，设置这些环境变量： ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -这只是临时逃生口，不是永久解决方案。 +这只是临时逃生舱口，不是永久解决方案。 -## 相关 +## 相关内容 - [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 - [插件内部机制](/zh-CN/plugins/architecture) — 架构深度解析 -- [插件 Manifest](/zh-CN/plugins/manifest) — manifest schema 参考 +- [插件清单](/zh-CN/plugins/manifest) — 清单 schema 参考 diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index 807dc60a7..e18068f0e 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -1,22 +1,21 @@ --- read_when: - 你需要知道应从哪个 SDK 子路径导入 - - 你想查看 OpenClawPluginApi 上所有注册方法的参考文档 - - 你正在查找某个特定的 SDK 导出 + - 你想要一份 OpenClawPluginApi 上所有注册方法的参考文档 + - 你正在查找某个特定的 SDK 导出项 sidebarTitle: SDK overview summary: 导入映射、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-04-25T00:43:09Z" + generated_at: "2026-04-25T01:27:55Z" model: gpt-5.4 provider: openai - source_hash: 4aedd09b7a02aeced8265c119d7d800f45d41780e5bf099826abee9a3c74c868 + source_hash: 825efe8d9b2283734730348f9803e40cabaaa6399993648f4bb5822b20e588ee source_path: plugins/sdk-overview.md workflow: 15 --- -插件 SDK 是插件与核心之间的类型化契约。本页是 -**该导入什么** 以及 **你可以注册什么** 的参考文档。 +插件 SDK 是插件与核心之间的类型化契约。本页是关于**该导入什么**以及**你可以注册什么**的参考。 在找操作指南而不是参考文档？ @@ -36,118 +35,91 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -每个子路径都是一个小型、独立的模块。这可以保持启动快速，并 -防止循环依赖问题。对于渠道专属入口 / 构建辅助工具， -优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给 -更广义的总入口接口和共享辅助工具，例如 -`buildChannelConfigSchema`。 +每个子路径都是一个小型、自包含模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口点/构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括性接口和共享辅助函数，例如 `buildChannelConfigSchema`。 -对于渠道配置，请通过 -`openclaw.plugin.json#channelConfigs` 发布渠道自有的 JSON Schema。 -`plugin-sdk/channel-config-schema` -子路径用于共享 schema 原语和通用构建器。该子路径上任何 -以内置渠道命名的 schema 导出都属于旧版兼容导出， -不是新插件应遵循的模式。 +对于渠道配置，请通过 `openclaw.plugin.json#channelConfigs` 发布渠道拥有的 JSON Schema。`plugin-sdk/channel-config-schema` 子路径用于共享的 schema 原语和通用构建器。该子路径上任何以内置渠道命名的 schema 导出都属于旧版兼容性导出，并不是新插件应采用的模式。 - 不要导入带有提供商或渠道品牌的便捷接口（例如 + 不要导入带有提供商或渠道品牌的便捷接口层（例如 `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。 内置插件会在它们自己的 `api.ts` / - `runtime-api.ts` barrel 中组合通用 SDK 子路径；核心使用方要么使用这些插件本地 - barrel，要么在确实存在跨渠道需求时添加一个狭窄的通用 SDK 契约。 + `runtime-api.ts` barrel 中组合通用 SDK 子路径；核心使用方应改用这些插件本地的 + barrel，或者在需求确实跨渠道时，新增一个窄而通用的 SDK 契约。 -一小部分内置插件辅助接口（`plugin-sdk/feishu`、 -`plugin-sdk/zalo`、`plugin-sdk/matrix*` 及类似项）仍会出现在 -生成的导出映射中。它们仅用于内置插件维护， -不建议新第三方插件导入。 +生成的导出映射中仍会出现一小部分内置插件辅助接口层（`plugin-sdk/feishu`、 +`plugin-sdk/zalo`、`plugin-sdk/matrix*` 以及类似项）。它们仅用于维护内置插件， +不推荐作为新的第三方插件导入路径。 ## 子路径参考 -插件 SDK 以一组按领域划分的狭窄子路径公开（插件 -入口点、渠道、提供商、认证、运行时、能力、内存，以及为内置插件保留的 -辅助工具）。完整目录 —— 按组分类并附链接 —— 请参见 +插件 SDK 以一组按领域分组的窄子路径形式公开（插件入口点、渠道、提供商、凭证、运行时、能力、内存，以及保留的内置插件辅助函数）。完整目录（按组分类并附带链接）请参见 [插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。 -200+ 子路径的生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 +这份包含 200 多个子路径的生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 ## 注册 API -`register(api)` 回调会接收一个 `OpenClawPluginApi` 对象，包含以下 -方法： +`register(api)` 回调会接收一个带有以下方法的 `OpenClawPluginApi` 对象： ### 能力注册 -| 方法 | 注册内容 | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | 文本推理（LLM） | -| `api.registerAgentHarness(...)` | 实验性的底层智能体执行器 | -| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | -| `api.registerChannel(...)` | 消息渠道 | -| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | -| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 | -| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 | -| `api.registerMediaUnderstandingProvider(...)` | 图像 / 音频 / 视频分析 | -| `api.registerImageGenerationProvider(...)` | 图像生成 | -| `api.registerMusicGenerationProvider(...)` | 音乐生成 | -| `api.registerVideoGenerationProvider(...)` | 视频生成 | -| `api.registerWebFetchProvider(...)` | 网页抓取 / 爬取提供商 | -| `api.registerWebSearchProvider(...)` | 网页搜索 | +| 方法 | 注册内容 | +| ------------------------------------------------ | -------------------------- | +| `api.registerProvider(...)` | 文本推理（LLM） | +| `api.registerAgentHarness(...)` | 实验性的底层智能体执行器 | +| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | +| `api.registerChannel(...)` | 消息渠道 | +| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | +| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 | +| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 | +| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | +| `api.registerImageGenerationProvider(...)` | 图像生成 | +| `api.registerMusicGenerationProvider(...)` | 音乐生成 | +| `api.registerVideoGenerationProvider(...)` | 视频生成 | +| `api.registerWebFetchProvider(...)` | Web 抓取 / 爬取提供商 | +| `api.registerWebSearchProvider(...)` | Web 搜索 | ### 工具和命令 -| 方法 | 注册内容 | +| 方法 | 注册内容 | | ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） | -| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | +| `api.registerTool(tool, opts?)` | 智能体工具（必需，或 `{ optional: true }`） | +| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | ### 基础设施 -| 方法 | 注册内容 | -| ----------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | 事件钩子 | -| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | -| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | -| `api.registerGatewayDiscoveryService(service)` | 本地 Gateway 网关发现广播器 | -| `api.registerCli(registrar, opts?)` | CLI 子命令 | -| `api.registerService(service)` | 后台服务 | -| `api.registerInteractiveHandler(registration)` | 交互处理器 | -| `api.registerAgentToolResultMiddleware(...)` | 运行时工具结果中间件 | -| `api.registerEmbeddedExtensionFactory(factory)` | 已弃用的 PI 扩展工厂 | -| `api.registerMemoryPromptSupplement(builder)` | 追加型、邻接内存的提示词部分 | -| `api.registerMemoryCorpusSupplement(adapter)` | 追加型内存搜索 / 读取语料库 | +| 方法 | 注册内容 | +| ---------------------------------------------- | --------------------------------- | +| `api.registerHook(events, handler, opts?)` | 事件钩子 | +| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | +| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | +| `api.registerGatewayDiscoveryService(service)` | 本地 Gateway 网关发现广播器 | +| `api.registerCli(registrar, opts?)` | CLI 子命令 | +| `api.registerService(service)` | 后台服务 | +| `api.registerInteractiveHandler(registration)` | 交互处理器 | +| `api.registerAgentToolResultMiddleware(...)` | 运行时工具结果中间件 | +| `api.registerMemoryPromptSupplement(builder)` | 追加式内存相邻提示词区段 | +| `api.registerMemoryCorpusSupplement(adapter)` | 追加式内存搜索/读取语料库 | 保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、 - `update.*`）始终保持为 `operator.admin`，即使插件试图分配更窄的 - Gateway 网关方法作用域也是如此。对于插件自有方法，请优先使用插件专属前缀。 + `update.*`）始终保持为 `operator.admin`，即使插件尝试为其分配更窄的 + Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件特定前缀。 - 当内置插件需要在工具执行之后、运行时 - 将该结果回送给模型之前重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。这是一个受信任的、运行时无关的 - 扩展点，用于诸如 tokenjuice 这类异步输出缩减器。 + 当内置插件需要在工具执行后、运行时将结果回传给模型前重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。 + 这是用于异步输出归约器（例如 tokenjuice）的受信任、运行时中立接口层。 -内置插件必须为每个目标 -运行时声明 `contracts.agentToolResultMiddleware`，例如 `["pi", "codex"]`。外部插件 -不能注册此中间件；对于不需要模型前工具结果时机的工作， -请继续使用常规 OpenClaw 插件钩子。 - - - - `api.registerEmbeddedExtensionFactory(...)` 已弃用。它仍然是一个 - 兼容性扩展点，用于仍需要直接 Pi - 嵌入式运行器事件的内置插件。新的工具结果转换应改用 - `api.registerAgentToolResultMiddleware(...)`。 +内置插件必须为每个目标运行时声明 `contracts.agentToolResultMiddleware`，例如 + `["pi", "codex"]`。外部插件 + 不能注册此中间件；对于不需要模型前工具结果时机的工作，请继续使用常规的 OpenClaw 插件钩子。旧的仅限 Pi 的嵌入式扩展工厂注册路径已被移除。 ### Gateway 网关发现注册 -`api.registerGatewayDiscoveryService(...)` 允许插件在本地发现传输层 -（如 mDNS / Bonjour）上广播活动中的 -Gateway 网关。OpenClaw 会在启用本地发现时于 Gateway 网关启动期间调用该 -服务，传入当前 Gateway 网关端口和非 Secret TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 -`stop` 处理器。 +`api.registerGatewayDiscoveryService(...)` 允许插件通过本地发现传输协议（例如 mDNS/Bonjour）广播活动中的 Gateway 网关。启用本地发现时，OpenClaw 会在 Gateway 网关启动期间调用该服务，传入当前 Gateway 网关端口和非敏感的 TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 `stop` 处理器。 ```typescript api.registerGatewayDiscoveryService({ @@ -163,19 +135,16 @@ api.registerGatewayDiscoveryService({ }); ``` -Gateway 网关发现插件不得将已广播的 TXT 值视为 Secret 或 -认证信息。设备发现只是路由提示；信任仍由 Gateway 网关认证和 TLS pinning 负责。 +Gateway 网关发现插件不得将广播的 TXT 值视为密钥或认证信息。设备发现只是路由提示；信任仍由 Gateway 网关凭证和 TLS 固定负责。 ### CLI 注册元数据 `api.registerCli(registrar, opts?)` 接受两类顶层元数据： - `commands`：由注册器拥有的显式命令根 -- `descriptors`：用于根 CLI 帮助、 - 路由和惰性插件 CLI 注册的解析时命令描述符 +- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析时命令描述符 -如果你希望插件命令在常规根 CLI 路径中保持惰性加载， -请提供 `descriptors`，覆盖该注册器暴露的每个顶层命令根。 +如果你希望插件命令在常规根 CLI 路径中保持延迟加载，请提供 `descriptors`，覆盖该注册器公开的每个顶层命令根。 ```typescript api.registerCli( @@ -187,7 +156,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "管理 Matrix 账号、验证、设备和配置档案状态", + description: "管理 Matrix 账户、验证、设备和资料状态", hasSubcommands: true, }, ], @@ -195,90 +164,81 @@ api.registerCli( ); ``` -仅在你不需要惰性根 CLI 注册时才单独使用 `commands`。 -这种急切兼容路径仍受支持，但它不会安装 -用于解析时惰性加载的 descriptor 支持占位符。 +仅在你不需要延迟根 CLI 注册时单独使用 `commands`。这种急切兼容路径仍受支持，但它不会安装基于描述符的占位符来实现解析时的延迟加载。 ### CLI 后端注册 -`api.registerCliBackend(...)` 允许插件为本地 -AI CLI 后端（如 `codex-cli`）提供默认配置。 +`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。 - 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。 - 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的结构。 -- 用户配置仍然优先。运行 CLI 前，OpenClaw 会将 `agents.defaults.cliBackends.` 合并到 - 插件默认值之上。 -- 当某个后端在合并后需要兼容性重写时，请使用 `normalizeConfig` - （例如规范化旧的 flag 结构）。 +- 用户配置仍然优先。OpenClaw 会在运行 CLI 前，将 `agents.defaults.cliBackends.` 合并覆盖到插件默认值之上。 +- 当后端在合并后需要兼容性重写时，请使用 `normalizeConfig`（例如规范化旧的标志形式）。 ### 独占槽位 -| 方法 | 注册内容 | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个活动项）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎定制提示词附加内容。 | -| `api.registerMemoryCapability(capability)` | 统一内存能力 | -| `api.registerMemoryPromptSection(builder)` | 内存提示词部分构建器 | -| `api.registerMemoryFlushPlan(resolver)` | 内存刷新计划解析器 | -| `api.registerMemoryRuntime(runtime)` | 内存运行时适配器 | +| 方法 | 注册内容 | +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只能激活一个）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎定制提示词附加内容。 | +| `api.registerMemoryCapability(capability)` | 统一内存能力 | +| `api.registerMemoryPromptSection(builder)` | 内存提示词区段构建器 | +| `api.registerMemoryFlushPlan(resolver)` | 内存刷新计划解析器 | +| `api.registerMemoryRuntime(runtime)` | 内存运行时适配器 | ### 内存嵌入适配器 -| 方法 | 注册内容 | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的内存嵌入适配器 | +| 方法 | 注册内容 | +| ---------------------------------------------- | ---------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | 当前插件的内存嵌入适配器 | -- `registerMemoryCapability` 是首选的独占内存插件 API。 -- `registerMemoryCapability` 还可以暴露 `publicArtifacts.listArtifacts(...)`， - 以便配套插件通过 - `openclaw/plugin-sdk/memory-host-core` 使用导出的内存工件，而不是深入某个特定 - 内存插件的私有布局。 +- `registerMemoryCapability` 是首选的独占式内存插件 API。 +- `registerMemoryCapability` 还可以公开 `publicArtifacts.listArtifacts(...)`， + 以便配套插件可通过 + `openclaw/plugin-sdk/memory-host-core` 使用导出的内存产物，而无需深入访问特定内存插件的私有布局。 - `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 - `registerMemoryRuntime` 是兼容旧版的独占内存插件 API。 -- `registerMemoryEmbeddingProvider` 允许活动内存插件注册一个 - 或多个嵌入适配器 id（例如 `openai`、`gemini`，或某个自定义 - 插件定义的 id）。 -- 用户配置（如 `agents.defaults.memorySearch.provider` 和 - `agents.defaults.memorySearch.fallback`）会根据这些已注册的 - 适配器 id 进行解析。 + `registerMemoryRuntime` 是兼容旧版的独占式内存插件 API。 +- `registerMemoryEmbeddingProvider` 允许活动中的内存插件注册一个或多个嵌入适配器 id（例如 `openai`、`gemini`，或插件自定义 id）。 +- 用户配置（例如 `agents.defaults.memorySearch.provider` 和 + `agents.defaults.memorySearch.fallback`）会针对这些已注册的适配器 id 进行解析。 ### 事件和生命周期 -| 方法 | 作用 | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | 类型化生命周期钩子 | -| `api.onConversationBindingResolved(handler)` | 会话绑定回调 | +| 方法 | 作用 | +| -------------------------------------------- | ------------------------ | +| `api.on(hookName, handler, opts?)` | 类型化生命周期钩子 | +| `api.onConversationBindingResolved(handler)` | 会话绑定回调 | -示例、常见钩子名称和保护语义请参见 [插件钩子](/zh-CN/plugins/hooks)。 +示例、常见钩子名称和 guard 语义，请参见 [插件钩子](/zh-CN/plugins/hooks)。 ### 钩子决策语义 -- `before_tool_call`：返回 `{ block: true }` 是终止性结果。一旦任意处理器设置它，就会跳过较低优先级处理器。 -- `before_tool_call`：返回 `{ block: false }` 会被视为未作出决定（与省略 `block` 相同），而不是覆盖。 -- `before_install`：返回 `{ block: true }` 是终止性结果。一旦任意处理器设置它，就会跳过较低优先级处理器。 -- `before_install`：返回 `{ block: false }` 会被视为未作出决定（与省略 `block` 相同），而不是覆盖。 -- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性结果。一旦任意处理器接管分发，就会跳过较低优先级处理器和默认模型分发路径。 -- `message_sending`：返回 `{ cancel: true }` 是终止性结果。一旦任意处理器设置它，就会跳过较低优先级处理器。 -- `message_sending`：返回 `{ cancel: false }` 会被视为未作出决定（与省略 `cancel` 相同），而不是覆盖。 -- `message_received`：当你需要入站线程 / 话题路由时，请使用类型化的 `threadId` 字段。`metadata` 保留给渠道专属附加信息。 -- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到渠道专属 `metadata`。 -- `gateway_start`：对于 Gateway 网关自有的启动状态，请使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，而不是依赖内部 `gateway:startup` 钩子。 +- `before_tool_call`：返回 `{ block: true }` 是终止性决定。一旦任一处理器设置该值，就会跳过优先级更低的处理器。 +- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 +- `before_install`：返回 `{ block: true }` 是终止性决定。一旦任一处理器设置该值，就会跳过优先级更低的处理器。 +- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 +- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性决定。一旦任一处理器声明已处理分发，就会跳过优先级更低的处理器以及默认的模型分发路径。 +- `message_sending`：返回 `{ cancel: true }` 是终止性决定。一旦任一处理器设置该值，就会跳过优先级更低的处理器。 +- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。 +- `message_received`：当你需要入站线程/话题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的额外信息。 +- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到渠道特定的 `metadata`。 +- `gateway_start`：对于 Gateway 网关自有的启动状态，请使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，不要依赖内部的 `gateway:startup` 钩子。 ### API 对象字段 -| 字段 | 类型 | 描述 | +| 字段 | 类型 | 说明 | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | 插件 id | -| `api.name` | `string` | 显示名称 | -| `api.version` | `string?` | 插件版本（可选） | -| `api.description` | `string?` | 插件描述（可选） | -| `api.source` | `string` | 插件源路径 | -| `api.rootDir` | `string?` | 插件根目录（可选） | -| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存运行时快照） | -| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件专属配置 | -| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动 / 设置前的轻量窗口 | -| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | +| `api.id` | `string` | 插件 id | +| `api.name` | `string` | 显示名称 | +| `api.version` | `string?` | 插件版本（可选） | +| `api.description` | `string?` | 插件说明（可选） | +| `api.source` | `string` | 插件源路径 | +| `api.rootDir` | `string?` | 插件根目录（可选） | +| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动中的内存运行时快照） | +| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件专属配置 | +| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量预启动/设置窗口 | +| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | ## 内部模块约定 @@ -287,36 +247,30 @@ AI CLI 后端（如 `codex-cli`）提供默认配置。 ``` my-plugin/ api.ts # 面向外部使用方的公共导出 - runtime-api.ts # 仅内部运行时导出 + runtime-api.ts # 仅供内部使用的运行时导出 index.ts # 插件入口点 - setup-entry.ts # 仅设置阶段的轻量入口点（可选） + setup-entry.ts # 仅设置用的轻量入口（可选） ``` - 在生产代码中，绝不要通过 `openclaw/plugin-sdk/` + 不要在生产代码中通过 `openclaw/plugin-sdk/` 导入你自己的插件。内部导入应通过 `./api.ts` 或 - `./runtime-api.ts` 进行。SDK 路径仅是对外契约。 + `./runtime-api.ts`。SDK 路径仅是对外契约。 -由 facade 加载的内置插件公共接口（`api.ts`、`runtime-api.ts`、 -`index.ts`、`setup-entry.ts` 及类似公共入口文件）在 -OpenClaw 已经运行时会优先使用活动运行时配置快照。如果尚不存在运行时 -快照，它们会回退到磁盘上的已解析配置文件。 +通过 facade 加载的内置插件公共接口（`api.ts`、`runtime-api.ts`、 +`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）会在 OpenClaw 已运行时优先使用活动中的运行时配置快照。如果运行时快照尚不存在，则回退到磁盘上已解析的配置文件。 -当某个辅助工具有意是提供商专属、且尚不属于某个通用 SDK -子路径时，提供商插件可以暴露一个狭窄的插件本地契约 barrel。内置示例： +提供商插件可以公开一个窄范围的插件本地契约 barrel，用于那些明确属于提供商专属、尚不适合放入通用 SDK 子路径的辅助函数。内置示例： -- **Anthropic**：公共 `api.ts` / `contract-api.ts` 接口，用于 Claude - beta header 和 `service_tier` 流式辅助工具。 -- **`@openclaw/openai-provider`**：`api.ts` 导出提供商构建器、 - 默认模型辅助工具和实时提供商构建器。 -- **`@openclaw/openrouter-provider`**：`api.ts` 导出提供商构建器 - 以及新手引导 / 配置辅助工具。 +- **Anthropic**：公共 `api.ts` / `contract-api.ts` 接口层，用于 Claude 的 beta-header 和 `service_tier` 流式辅助函数。 +- **`@openclaw/openai-provider`**：`api.ts` 导出提供商构建器、默认模型辅助函数以及实时提供商构建器。 +- **`@openclaw/openrouter-provider`**：`api.ts` 导出提供商构建器以及新手引导/配置辅助函数。 - 扩展的生产代码也应避免导入 `openclaw/plugin-sdk/`。 - 如果某个辅助工具确实是共享的，请将其提升到一个中立的 SDK 子路径， - 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他 + 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。 + 如果某个辅助函数确实应被共享，请将它提升到中立的 SDK 子路径， + 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他 面向能力的接口，而不是将两个插件耦合在一起。 @@ -326,7 +280,7 @@ OpenClaw 已经运行时会优先使用活动运行时配置快照。如果尚 `definePluginEntry` 和 `defineChannelPluginEntry` 选项。 - + 完整的 `api.runtime` 命名空间参考。 diff --git a/docs/zh-CN/providers/google.md b/docs/zh-CN/providers/google.md index b0dc8be9c..8252862d5 100644 --- a/docs/zh-CN/providers/google.md +++ b/docs/zh-CN/providers/google.md @@ -1,35 +1,41 @@ --- read_when: - 你想在 OpenClaw 中使用 Google Gemini 模型 - - 你需要 API key 或 OAuth 认证流程 -summary: Google Gemini 设置（API key + OAuth、图像生成、媒体理解、TTS、web 搜索） + - 你需要 API 密钥或 OAuth 凭证流程 +summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、Web 搜索） title: Google（Gemini） x-i18n: - generated_at: "2026-04-25T00:43:31Z" + generated_at: "2026-04-25T01:28:12Z" model: gpt-5.4 provider: openai - source_hash: 6a3e8531d2cf58ac0f0c003d369be837576b4c2ff7d38e53cfb3f86ab8b44347 + source_hash: b8644a578180600ba65275c28e45cc31eb131173d0f0abdd29dcee908d625642 source_path: providers/google.md workflow: 15 --- -Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支持 -图像生成、媒体理解（图像 / 音频 / 视频）、文本转语音，以及通过 -Gemini Grounding 提供的 web 搜索。 +Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、Web 搜索） + +Google（Gemini） + +你想在 OpenClaw 中使用 Google Gemini 模型 + +你需要 API 密钥或 OAuth 凭证流程 + +Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支持通过 Gemini Grounding 实现图像生成、媒体理解（图像 / 音频 / 视频）、文本转语音和 Web 搜索。 - 提供商：`google` -- 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` +- 凭证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` - API：Google Gemini API - 运行时选项：`agents.defaults.embeddedHarness.runtime: "google-gemini-cli"` - 会复用 Gemini CLI OAuth，同时保持模型引用的规范形式为 `google/*`。 + 会复用 Gemini CLI OAuth，同时保持模型引用规范形式为 `google/*`。 ## 入门指南 -选择你偏好的认证方式，并按照设置步骤进行操作。 +选择你偏好的凭证方式，并按照设置步骤操作。 - - **最适合：** 通过 Google AI Studio 进行标准的 Gemini API 访问。 + + **最适合：** 通过 Google AI Studio 进行标准 Gemini API 访问。 @@ -37,7 +43,7 @@ Gemini Grounding 提供的 web 搜索。 openclaw onboard --auth-choice gemini-api-key ``` - 或直接传入 key： + 或直接传入密钥： ```bash openclaw onboard --non-interactive \ @@ -57,7 +63,7 @@ Gemini Grounding 提供的 web 搜索。 } ``` - + ```bash openclaw models list --provider google ``` @@ -65,17 +71,16 @@ Gemini Grounding 提供的 web 搜索。 - 环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可以使用。使用你已经配置好的那个即可。 + 环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可接受。使用你已经配置好的那个即可。 - - **最适合：** 复用现有的 Gemini CLI 登录，通过 PKCE OAuth 进行认证，而不是单独使用 API key。 + + **最适合：** 复用现有的 Gemini CLI 登录，通过 PKCE OAuth，而不是使用单独的 API 密钥。 - `google-gemini-cli` 提供商是非官方集成。有些用户 - 报告说，以这种方式使用 OAuth 时账号会受到限制。请自行承担风险。 + `google-gemini-cli` 提供商属于非官方集成。一些用户报告称，以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。 @@ -90,15 +95,14 @@ Gemini Grounding 提供的 web 搜索。 npm install -g @google/gemini-cli ``` - OpenClaw 同时支持 Homebrew 安装和全局 npm 安装，包括 - 常见的 Windows / npm 布局。 + OpenClaw 同时支持 Homebrew 安装和全局 npm 安装，包括常见的 Windows / npm 布局。 ```bash openclaw models auth login --provider google-gemini-cli --set-default ``` - + ```bash openclaw models list --provider google ``` @@ -117,27 +121,23 @@ Gemini Grounding 提供的 web 搜索。 （或使用 `GEMINI_CLI_*` 变体。） - 如果在登录后 Gemini CLI OAuth 请求失败，请在 gateway 主机上设置 `GOOGLE_CLOUD_PROJECT` 或 - `GOOGLE_CLOUD_PROJECT_ID`，然后重试。 + 如果 Gemini CLI OAuth 在登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`，然后重试。 - 如果在浏览器流程开始之前登录就失败，请确认本地 `gemini` - 命令已安装并且位于 `PATH` 中。 + 如果在浏览器流程开始之前登录就失败，请确保本地 `gemini` 命令已安装并且位于 `PATH` 中。 - `google-gemini-cli/*` 模型引用是旧版兼容别名。新的 - 配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时使用 `google-gemini-cli` - 运行时。 + `google-gemini-cli/*` 模型引用是旧版兼容别名。新配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时配合 `google-gemini-cli` 运行时。 ## 功能 -| 能力 | 支持情况 | +| 功能 | 支持情况 | | ---------------------- | ----------------------------- | -| Chat completions | 是 | +| 聊天补全 | 是 | | 图像生成 | 是 | | 音乐生成 | 是 | | 文本转语音 | 是 | @@ -145,20 +145,16 @@ Gemini Grounding 提供的 web 搜索。 | 图像理解 | 是 | | 音频转录 | 是 | | 视频理解 | 是 | -| web 搜索（Grounding） | 是 | +| Web 搜索（Grounding） | 是 | | 思考 / 推理 | 是（Gemini 2.5+ / Gemini 3+） | | Gemma 4 模型 | 是 | -Gemini 3 模型使用 `thinkingLevel`，而不是 `thinkingBudget`。OpenClaw 会将 -Gemini 3、Gemini 3.1 和 `gemini-*-latest` 别名的推理控制映射为 -`thinkingLevel`，这样默认 / 低延迟运行就不会发送被禁用的 -`thinkingBudget` 值。 +Gemini 3 模型使用 `thinkingLevel`，而不是 `thinkingBudget`。OpenClaw 会将 Gemini 3、Gemini 3.1 以及 `gemini-*-latest` 别名的推理控制映射到 `thinkingLevel`，这样默认 / 低延迟运行就不会发送被禁用的 `thinkingBudget` 值。 -Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw -会将 `thinkingBudget` 重写为 Google 支持的 `thinkingLevel`，用于 Gemma 4。 -将 thinking 设置为 `off` 时，会保持禁用思考，而不是映射为 -`MINIMAL`。 +`/think adaptive` 会保留 Google 的动态思考语义，而不是选择一个固定的 OpenClaw 级别。Gemini 3 和 Gemini 3.1 会省略固定的 `thinkingLevel`，让 Google 自行选择级别；Gemini 2.5 则会发送 Google 的动态哨兵值 `thinkingBudget: -1`。 + +Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会将 `thinkingBudget` 重写为 Gemma 4 支持的 Google `thinkingLevel`。将 thinking 设置为 `off` 时，会保持禁用思考，而不会映射为 `MINIMAL`。 ## 图像生成 @@ -166,12 +162,12 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 内置的 `google` 图像生成提供商默认使用 `google/gemini-3.1-flash-image-preview`。 -- 也支持 `google/gemini-3-pro-image-preview` -- 生成：每次请求最多 4 张图像 -- 编辑模式：已启用，最多支持 5 张输入图像 +- 还支持 `google/gemini-3-pro-image-preview` +- 生成：每次请求最多 4 张图片 +- 编辑模式：已启用，最多支持 5 张输入图片 - 几何控制：`size`、`aspectRatio` 和 `resolution` -如需将 Google 用作默认图像提供商： +要将 Google 用作默认图像提供商： ```json5 { @@ -186,20 +182,20 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw ``` -共享工具参数、提供商选择和故障转移行为，请参见 [图像生成](/zh-CN/tools/image-generation)。 +有关共享工具参数、提供商选择和故障切换行为，请参见 [图像生成](/zh-CN/tools/image-generation)。 ## 视频生成 -内置的 `google` 插件也通过共享 -`video_generate` 工具注册视频生成功能。 +内置的 `google` 插件还通过共享的 +`video_generate` 工具注册了视频生成。 - 默认视频模型：`google/veo-3.1-fast-generate-preview` -- 模式：text-to-video、image-to-video 和单视频参考流程 +- 模式：文生视频、图生视频和单视频参考流程 - 支持 `aspectRatio`、`resolution` 和 `audio` - 当前时长限制：**4 到 8 秒** -如需将 Google 用作默认视频提供商： +要将 Google 用作默认视频提供商： ```json5 { @@ -214,22 +210,22 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw ``` -共享工具参数、提供商选择和故障转移行为，请参见 [视频生成](/zh-CN/tools/video-generation)。 +有关共享工具参数、提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。 ## 音乐生成 -内置的 `google` 插件也通过共享 -`music_generate` 工具注册音乐生成功能。 +内置的 `google` 插件还通过共享的 +`music_generate` 工具注册了音乐生成。 - 默认音乐模型：`google/lyria-3-clip-preview` -- 也支持 `google/lyria-3-pro-preview` +- 还支持 `google/lyria-3-pro-preview` - 提示词控制：`lyrics` 和 `instrumental` -- 输出格式：默认 `mp3`，以及在 `google/lyria-3-pro-preview` 上支持 `wav` -- 参考输入：最多 10 张图像 -- 基于 session 的运行会通过共享任务 / 状态流程分离，包括 `action: "status"` +- 输出格式：默认 `mp3`，此外 `google/lyria-3-pro-preview` 还支持 `wav` +- 参考输入：最多 10 张图片 +- 基于会话的运行会通过共享任务 / 状态流程分离执行，包括 `action: "status"` -如需将 Google 用作默认音乐提供商： +要将 Google 用作默认音乐提供商： ```json5 { @@ -244,20 +240,20 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw ``` -共享工具参数、提供商选择和故障转移行为，请参见 [音乐生成](/zh-CN/tools/music-generation)。 +有关共享工具参数、提供商选择和故障切换行为，请参见 [音乐生成](/zh-CN/tools/music-generation)。 ## 文本转语音 -内置的 `google` speech 提供商通过 -`gemini-3.1-flash-tts-preview` 使用 Gemini API 的 TTS 路径。 +内置的 `google` 语音提供商通过 +`gemini-3.1-flash-tts-preview` 使用 Gemini API TTS 路径。 - 默认语音：`Kore` -- 认证：`messages.tts.providers.google.apiKey`、`models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` +- 凭证：`messages.tts.providers.google.apiKey`、`models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` - 输出：常规 TTS 附件为 WAV，Talk / 电话场景为 PCM -- 原生语音便笺输出：此 Gemini API 路径不支持，因为 API 返回的是 PCM 而不是 Opus +- 原生语音便笺输出：该 Gemini API 路径不支持，因为 API 返回的是 PCM 而不是 Opus -如需将 Google 用作默认 TTS 提供商： +要将 Google 用作默认 TTS 提供商： ```json5 { @@ -276,9 +272,8 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw } ``` -Gemini API TTS 接受文本中的方括号表现型音频标签，例如 -`[whispers]` 或 `[laughs]`。如果你想在将这些标签发送给 TTS 的同时， -不让它们出现在可见聊天回复中，请将其放入 `[[tts:text]]...[[/tts:text]]` 块中： +Gemini API TTS 支持在文本中使用富表现力的方括号音频标签，例如 +`[whispers]` 或 `[laughs]`。如果你希望这些标签不显示在聊天回复中，但仍发送给 TTS，请将它们放在 `[[tts:text]]...[[/tts:text]]` 块内： ```text Here is the clean reply text. @@ -287,14 +282,13 @@ Here is the clean reply text. ``` -限制为 Gemini API 的 Google Cloud Console API key 也可用于此 -提供商。这不是单独的 Cloud Text-to-Speech API 路径。 +一个限制为 Gemini API 的 Google Cloud Console API 密钥可用于此提供商。这不是单独的 Cloud Text-to-Speech API 路径。 ## 实时语音 内置的 `google` 插件注册了一个由 -Gemini Live API 支持的实时语音提供商，适用于 Voice Call 和 Google Meet 等后端音频桥接。 +Gemini Live API 支持的实时语音提供商，适用于 Voice Call 和 Google Meet 等后端音频桥接场景。 | 设置 | 配置路径 | 默认值 | | --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | @@ -304,9 +298,9 @@ Gemini Live API 支持的实时语音提供商，适用于 Voice Call 和 Google | VAD 开始灵敏度 | `...google.startSensitivity` | （未设置） | | VAD 结束灵敏度 | `...google.endSensitivity` | （未设置） | | 静音时长 | `...google.silenceDurationMs` | （未设置） | -| API key | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | +| API 密钥 | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | -Voice Call 实时配置示例： +示例 Voice Call 实时配置： ```json5 { @@ -333,34 +327,23 @@ Voice Call 实时配置示例： ``` -Google Live API 通过 WebSocket 使用双向音频和函数调用。 -OpenClaw 会将电话 / Meet 桥接音频适配到 Gemini 的 PCM Live API 流中， -并在共享的实时语音契约上保留工具调用。除非你需要调整采样，否则请保持 `temperature` -未设置；因为对于 `temperature: 0`，Google Live 可能返回只有转录而没有音频的结果， -所以 OpenClaw 会省略非正值。 -Gemini API 转录会在不设置 `languageCodes` 的情况下启用；当前 Google -SDK 会在此 API 路径上拒绝语言代码提示。 +Google Live API 使用 WebSocket 上的双向音频和函数调用。OpenClaw 会将电话 / Meet 桥接音频适配到 Gemini 的 PCM Live API 流，并让工具调用保持在共享的实时语音契约上。除非你需要调整采样行为，否则请不要设置 `temperature`；OpenClaw 会省略非正值，因为当 `temperature: 0` 时，Google Live 可能返回只有转录文本而没有音频的结果。Gemini API 转录会在不使用 `languageCodes` 的情况下启用；当前的 Google SDK 会在此 API 路径上拒绝语言代码提示。 -Control UI Talk 浏览器会话仍然需要一个带有 -浏览器 WebRTC 会话实现的实时语音提供商。目前这条路径是 OpenAI Realtime；而 -Google 提供商用于后端实时桥接。 +Control UI Talk 浏览器会话仍然需要一个具有浏览器 WebRTC 会话实现的实时语音提供商。目前该路径是 OpenAI Realtime；Google 提供商用于后端实时桥接。 ## 高级配置 - 对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw - 会将已配置的 `cachedContent` 句柄透传给 Gemini 请求。 + 对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw 会将已配置的 `cachedContent` 句柄透传给 Gemini 请求。 - - 可通过 `cachedContent` 或旧版 - `cached_content` 配置每模型或全局参数 - - 如果两者都存在，则 `cachedContent` 优先生效 + - 可使用 `cachedContent` 或旧版 `cached_content` 配置按模型或全局参数 + - 如果两者同时存在，则 `cachedContent` 优先 - 示例值：`cachedContents/prebuilt-context` - - Gemini 缓存命中用量会从上游的 `cachedContentTokenCount` - 规范化为 OpenClaw `cacheRead` + - Gemini 缓存命中用量会从上游的 `cachedContentTokenCount` 规范化为 OpenClaw 的 `cacheRead` ```json5 { @@ -386,14 +369,14 @@ Google 提供商用于后端实时桥接。 - 回复文本来自 CLI JSON 的 `response` 字段。 - 当 CLI 将 `usage` 留空时，用量会回退到 `stats`。 - - `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 + - `stats.cached` 会被规范化为 OpenClaw 的 `cacheRead`。 - 如果缺少 `stats.input`，OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token。 - 如果 Gateway 网关以守护进程方式运行（launchd / systemd），请确保 `GEMINI_API_KEY` + 如果 Gateway 网关作为守护进程运行（launchd / systemd），请确保 `GEMINI_API_KEY` 对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。 @@ -403,7 +386,7 @@ Google 提供商用于后端实时桥接。 - 选择提供商、模型引用和故障转移行为。 + 选择提供商、模型引用和故障切换行为。 共享图像工具参数和提供商选择。