diff --git a/docs/zh-CN/concepts/models.md b/docs/zh-CN/concepts/models.md index 30f314ad0..08480bb1b 100644 --- a/docs/zh-CN/concepts/models.md +++ b/docs/zh-CN/concepts/models.md @@ -1,23 +1,23 @@ --- read_when: - - 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks） - - 更改模型回退行为或选择体验 - - 更新模型扫描探针（工具/图片） + - 添加或修改 models CLI（models list/set/scan/aliases/fallbacks） + - 更改模型回退行为或选择用户体验 + - 更新模型扫描探针（工具/图像） sidebarTitle: Models CLI -summary: Models CLI：列出、设置、别名、回退、扫描、Status +summary: Models CLI：列出、设置、别名、回退、扫描、状态 title: Models CLI x-i18n: - generated_at: "2026-04-28T22:39:17Z" + generated_at: "2026-04-29T17:09:47Z" model: gpt-5.5 provider: openai - source_hash: 4fde5131ee4bde7d22f2423124420704cc0cd5ab0daa04d7c091baa74f0fcc61 + source_hash: 64b97ddfcc6f804044580dfc9a441d426f737e9e7d007d78b0b045a52068b34f source_path: concepts/models.md workflow: 16 --- - 凭证配置轮换、冷却时间，以及它如何与后备模型交互。 + 凭证配置轮换、冷却时间，以及它如何与回退交互。 快速提供商概览和示例。 @@ -30,9 +30,9 @@ x-i18n: -模型引用会选择提供商和模型。它们通常不会选择底层智能体运行时。例如，`openai/gpt-5.5` 可以通过常规 OpenAI provider 路径运行，也可以通过 Codex 应用服务器运行时运行，具体取决于 `agents.defaults.agentRuntime.id`。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 +模型引用会选择提供商和模型。它们通常不会选择底层智能体运行时。例如，`openai/gpt-5.5` 可以通过常规 OpenAI provider 路径运行，也可以通过 Codex 应用服务器运行时运行，具体取决于 `agents.defaults.agentRuntime.id`。请参阅 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 -## 模型选择的工作方式 +## 模型选择如何工作 OpenClaw 按以下顺序选择模型： @@ -40,43 +40,43 @@ OpenClaw 按以下顺序选择模型： `agents.defaults.model.primary`（或 `agents.defaults.model`）。 - + `agents.defaults.model.fallbacks`（按顺序）。 - 凭证故障转移发生在提供商内部，然后才会切换到下一个模型。 + 凭证故障转移发生在提供商内部，然后才会移到下一个模型。 - - - `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（以及别名）。 - - `agents.defaults.imageModel` **仅在**主模型无法接受图像时使用。 + + - `agents.defaults.models` 是 OpenClaw 可以使用的模型允许列表/目录（以及别名）。 + - `agents.defaults.imageModel` **仅在**主模型无法接受图片时使用。 - `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到已解析的会话/默认模型。 - - `agents.defaults.imageGenerationModel` 由共享的图像生成能力使用。如果省略，`image_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API 密钥。 - - `agents.defaults.musicGenerationModel` 由共享的音乐生成能力使用。如果省略，`music_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API 密钥。 - - `agents.defaults.videoGenerationModel` 由共享的视频生成能力使用。如果省略，`video_generate` 仍可推断一个有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API 密钥。 + - `agents.defaults.imageGenerationModel` 由共享图片生成能力使用。如果省略，`image_generate` 仍然可以推断一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的图片生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。 + - `agents.defaults.musicGenerationModel` 由共享音乐生成能力使用。如果省略，`music_generate` 仍然可以推断一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。 + - `agents.defaults.videoGenerationModel` 由共享视频生成能力使用。如果省略，`video_generate` 仍然可以推断一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按 provider-id 顺序尝试其余已注册的视频生成提供商。如果你设置了特定提供商/模型，也要配置该提供商的凭证/API key。 - 每个智能体的默认值可以通过 `agents.list[].model` 加绑定来覆盖 `agents.defaults.model`（参见[多智能体路由](/zh-CN/concepts/multi-agent)）。 -## 选择来源和后备行为 +## 选择来源和回退行为 -同一个 `provider/model` 可能会根据来源代表不同含义： +同一个 `provider/model` 可能因来源不同而含义不同： -- 已配置的默认值（`agents.defaults.model.primary` 和智能体专属主模型）是常规起点，并使用 `agents.defaults.model.fallbacks`。 -- 自动后备选择是临时恢复状态。它们会以 `modelOverrideSource: "auto"` 存储，这样后续轮次可以继续使用后备链，而无需先探测已知不可用的主模型。 -- 用户会话选择是精确的。`/model`、模型选择器、`session_status(model=...)` 和 `sessions.patch` 会存储 `modelOverrideSource: "user"`；如果所选提供商/模型不可达，OpenClaw 会显式失败，而不是继续落到另一个已配置模型。 -- Cron `--model` / 载荷 `model` 是每个作业的主模型。除非作业提供显式载荷 `fallbacks`，否则它仍会使用已配置的后备模型（使用 `fallbacks: []` 可进行严格 cron 运行）。 +- 配置的默认值（`agents.defaults.model.primary` 和智能体专属主模型）是常规起点，并使用 `agents.defaults.model.fallbacks`。 +- 自动回退选择是临时恢复状态。它们会以 `modelOverrideSource: "auto"` 存储，因此后续轮次可以继续使用回退链，而不必先探测已知不可用的主模型。 +- 用户会话选择是精确的。`/model`、模型选择器、`session_status(model=...)` 和 `sessions.patch` 会存储 `modelOverrideSource: "user"`；如果所选 provider/model 无法访问，OpenClaw 会明确失败，而不是落到另一个已配置模型。 +- Cron `--model` / 载荷 `model` 是每个作业的主模型。它仍会使用已配置的回退，除非作业提供显式载荷 `fallbacks`（严格的 cron 运行请使用 `fallbacks: []`）。 - CLI 默认模型和允许列表选择器会遵循 `models.mode: "replace"`，列出显式的 `models.providers.*.models`，而不是加载完整内置目录。 -- Control UI 模型选择器会向 Gateway 网关请求其已配置的模型视图：存在 `agents.defaults.models` 时使用它，否则使用显式的 `models.providers.*.models`，否则使用完整目录，避免新安装显示为空。 +- Control UI 模型选择器会向 Gateway 网关请求其已配置的模型视图：存在时使用 `agents.defaults.models`，否则使用显式的 `models.providers.*.models` 加上具有可用凭证的提供商。完整内置目录只保留给显式浏览视图，例如带有 `view: "all"` 的 `models.list` 或 `openclaw models list --all`。 ## 快速模型策略 -- 将主模型设置为你可用的最强新一代模型。 -- 对成本/延迟敏感任务和较低风险聊天使用后备模型。 -- 对启用工具的智能体或不受信任输入，避免使用较旧/较弱的模型层级。 +- 将你的主模型设为你可用的最强最新一代模型。 +- 将回退用于对成本/延迟敏感的任务和低风险聊天。 +- 对于启用工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。 ## 新手引导（推荐） @@ -86,7 +86,7 @@ OpenClaw 按以下顺序选择模型： openclaw onboard ``` -它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code (Codex) 订阅**（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。 +它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code (Codex) 订阅**（OAuth）和 **Anthropic**（API key 或 Claude CLI）。 ## 配置键（概览） @@ -113,35 +113,35 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json ``` - - `openclaw config set` 会保护模型/提供商映射，避免意外覆盖。当对 `agents.defaults.models`、`models.providers` 或 `models.providers..models` 的普通对象赋值会移除现有条目时，该操作会被拒绝。使用 `--merge` 进行增量更改；仅当提供的值应成为完整目标值时，才使用 `--replace`。 + + `openclaw config set` 会保护模型/提供商映射，避免意外覆盖。当普通对象赋值给 `agents.defaults.models`、`models.providers` 或 `models.providers..models` 会移除现有条目时，该赋值会被拒绝。增量更改请使用 `--merge`；仅当提供的值应成为完整目标值时才使用 `--replace`。 - 交互式提供商设置和 `openclaw configure --section model` 也会将提供商作用域内的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商不会删除无关模型条目。重新应用提供商凭证时，Configure 会保留现有的 `agents.defaults.model.primary`。显式默认值设置命令，例如 `openclaw models auth login --provider --set-default` 和 `openclaw models set `，仍会替换 `agents.defaults.model.primary`。 + 交互式提供商设置和 `openclaw configure --section model` 也会将提供商范围的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商不会丢弃无关的模型条目。重新应用提供商凭证时，Configure 会保留现有的 `agents.defaults.model.primary`。显式默认值设置命令，例如 `openclaw models auth login --provider --set-default` 和 `openclaw models set `，仍会替换 `agents.defaults.model.primary`。 -## “Model is not allowed”（以及回复为什么停止） +## “Model is not allowed”（以及回复为什么会停止） -如果设置了 `agents.defaults.models`，它会成为 `/model` 和会话覆盖的**允许列表**。当用户选择不在该允许列表中的模型时，OpenClaw 会返回： +如果设置了 `agents.defaults.models`，它会成为 `/model` 和会话覆盖的**允许列表**。当用户选择的模型不在该允许列表中时，OpenClaw 会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` -这发生在生成常规回复**之前**，因此消息可能让人感觉像是“没有响应”。修复方法是： +这发生在生成正常回复**之前**，因此消息可能让人感觉它“没有响应”。修复方法是以下任一项： - 将模型添加到 `agents.defaults.models`，或 -- 清空允许列表（移除 `agents.defaults.models`），或 -- 从 `/model list` 选择一个模型。 +- 清除允许列表（移除 `agents.defaults.models`），或 +- 从 `/model list` 中选择一个模型。 -对于本地/GGUF 模型，请在允许列表中存储完整的带提供商前缀引用， +对于本地/GGUF 模型，请在允许列表中存储带完整提供商前缀的引用， 例如 `ollama/gemma4:26b`、`lmstudio/Gemma4-26b-a4-it-gguf`，或 -`openclaw models list --provider ` 显示的确切提供商/模型。 -允许列表启用时，仅使用本地文件名或显示名称是不够的。 +`openclaw models list --provider ` 显示的精确 provider/model。 +当允许列表处于激活状态时，仅有本地裸文件名或显示名称是不够的。 允许列表示例配置： @@ -159,7 +159,7 @@ Model "provider/model" is not allowed. Use /model to list available models. ## 在聊天中切换模型（`/model`） -你可以在不重启的情况下切换当前会话的模型： +你可以在不重启的情况下为当前会话切换模型： ``` /model @@ -171,28 +171,28 @@ Model "provider/model" is not allowed. Use /model to list available models. - - `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。 - - 在 Discord 上，`/model` 和 `/models` 会打开带有提供商和模型下拉菜单以及提交步骤的交互式选择器。 + - `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型系列 + 可用提供商）。 + - 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单以及提交步骤。 - `/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。 - `/model <#>` 会从该选择器中选择。 - `/model` 会立即持久化新的会话选择。 - - 如果智能体空闲，下一次运行会立即使用新模型。 - - 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在干净的重试点重启到新模型。 - - 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续重试机会或下一轮用户输入。 - - 用户选择的 `/model` 引用对该会话是严格的：如果所选提供商/模型不可达，回复会显式失败，而不是静默地从 `agents.defaults.model.fallbacks` 回答。这不同于已配置默认值和 cron 作业主模型，它们仍可使用后备链。 - - `/model status` 是详细视图（凭证候选项，以及配置后显示的提供商端点 `baseUrl` + `api` 模式）。 + - 如果智能体处于空闲状态，下一次运行会立即使用新模型。 + - 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只在干净的重试点重启进入新模型。 + - 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到之后的重试机会或下一轮用户输入。 + - 用户选择的 `/model` 引用对该会话是严格的：如果所选 provider/model 无法访问，回复会明确失败，而不是静默地从 `agents.defaults.model.fallbacks` 回答。这不同于已配置默认值和 cron 作业主模型，后者仍可使用回退链。 + - `/model status` 是详细视图（凭证候选项，以及配置时的提供商端点 `baseUrl` + `api` 模式）。 - - 模型引用通过按**第一个** `/` 拆分进行解析。输入 `/model ` 时使用 `provider/model`。 + - 模型引用通过在**第一个** `/` 处分割来解析。输入 `/model ` 时请使用 `provider/model`。 - 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。 - 如果省略提供商，OpenClaw 会按以下顺序解析输入： 1. 别名匹配 - 2. 针对该精确无前缀模型 ID 的唯一已配置提供商匹配 - 3. 已弃用的回退到已配置默认提供商 — 如果该提供商不再公开已配置默认模型，OpenClaw 会改为回退到第一个已配置提供商/模型，以避免暴露陈旧的已移除提供商默认值。 + 2. 对该精确无前缀模型 ID 的唯一已配置提供商匹配 + 3. 已弃用的回退到已配置默认提供商——如果该提供商不再公开已配置的默认模型，OpenClaw 会改为回退到第一个已配置 provider/model，以避免暴露过时的已移除提供商默认值。 @@ -225,16 +225,16 @@ openclaw models image-fallbacks clear ### `models list` -默认显示已配置模型。实用标志： +默认显示已配置/凭证可用的模型。实用标志： - 完整目录。包含配置凭证前内置的提供商自有静态目录行，因此仅用于设备发现的视图也可以显示模型；这些模型在添加匹配的提供商凭证前不可用。 + 完整目录。包括在配置凭证之前由内置提供商拥有的静态目录行，因此仅用于设备发现的视图可以显示在添加匹配提供商凭证之前不可用的模型。 仅本地提供商。 - 按提供商 ID 筛选，例如 `moonshot`。不接受交互式选择器中的显示标签。 + 按提供商 ID 过滤，例如 `moonshot`。不接受交互式选择器中的显示标签。 每行一个模型。 @@ -245,21 +245,21 @@ openclaw models image-fallbacks clear ### `models status` -显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会展示在凭证存储中找到的配置文件的 OAuth 过期 Status（默认在 24 小时内发出警告）。`--plain` 只打印已解析的主模型。 +显示解析后的主模型、备用模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 到期 Status（默认在 24 小时内发出警告）。`--plain` 仅打印解析后的主模型。 - - OAuth Status 始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **缺少凭证** 部分。 - - JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效凭证，包括环境变量支持的凭证）。`auth.oauth` 仅表示凭证存储配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。 - - 对自动化使用 `--check`（缺失/过期时退出 `1`，即将过期时退出 `2`）。 - - 使用 `--probe` 进行实时凭证检查；探测行可以来自凭证配置文件、环境变量凭证或 `models.json`。 - - 如果显式的 `auth.order.` 省略了已存储的配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果存在凭证，但无法为该提供商解析出可探测的模型，探测会报告 `status: no_model`。 + - OAuth Status 始终显示（并包含在 `--json` 输出中）。如果配置的提供商没有凭据，`models status` 会打印 **Missing auth** 部分。 + - JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效凭证，包括由环境变量支持的凭据）。`auth.oauth` 仅表示凭证存储配置文件健康状态；仅使用环境变量的提供商不会出现在其中。 + - 使用 `--check` 进行自动化（缺失/已过期时退出 `1`，即将过期时退出 `2`）。 + - 使用 `--probe` 进行实时凭证检查；探测行可以来自凭证配置文件、环境变量凭据或 `models.json`。 + - 如果显式 `auth.order.` 省略了已存储的配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试使用它。如果存在凭证，但无法为该提供商解析可探测的模型，探测会报告 `status: no_model`。 -凭证选择取决于提供商/账号。对于始终在线的 Gateway 网关主机，API 密钥通常最可预测；也支持复用 Claude CLI，以及使用现有 Anthropic OAuth/token 配置文件。 +凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API key 通常最可预测；也支持复用 Claude CLI 以及现有的 Anthropic OAuth/token 配置文件。 示例（Claude CLI）： @@ -271,7 +271,7 @@ openclaw models status ## 扫描（OpenRouter 免费模型） -`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型的工具和图像支持。 +`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并且可以选择探测模型对工具和图像的支持。 跳过实时探测（仅元数据）。 @@ -280,23 +280,23 @@ openclaw models status 最小参数规模（十亿）。 - 跳过较旧的模型。 + 跳过较旧模型。 提供商前缀过滤器。 - 回退列表大小。 + 备用列表大小。 - 将 `agents.defaults.model.primary` 设置为第一个选择。 + 将 `agents.defaults.model.primary` 设为第一个选择。 - 将 `agents.defaults.imageModel.primary` 设置为第一个图像选择。 + 将 `agents.defaults.imageModel.primary` 设为第一个图像选择。 -OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没有密钥的情况下列出免费候选项。探测和推理仍需要 OpenRouter API 密钥（来自凭证配置文件或 `OPENROUTER_API_KEY`）。如果没有可用密钥，`openclaw models scan` 会回退到仅元数据输出，并保持配置不变。使用 `--no-probe` 可显式请求仅元数据模式。 +OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没有密钥的情况下列出免费候选项。探测和推理仍需要 OpenRouter API key（来自凭证配置文件或 `OPENROUTER_API_KEY`）。如果没有可用密钥，`openclaw models scan` 会回退到仅元数据输出，并保持配置不变。使用 `--no-probe` 可以显式请求仅元数据模式。 扫描结果按以下顺序排名： @@ -309,40 +309,40 @@ OpenRouter `/models` 目录是公开的，因此仅元数据扫描可以在没 输入： - OpenRouter `/models` 列表（过滤 `:free`） -- 实时探测需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（见[环境变量](/zh-CN/help/environment)） +- 实时探测需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API key（参见[环境变量](/zh-CN/help/environment)） - 可选过滤器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` - 请求/探测控制：`--timeout`、`--concurrency` -当实时探测在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。仅元数据结果只供参考；`--set-default` 和 `--set-image` 需要实时探测，因此 OpenClaw 不会配置无法使用的无密钥 OpenRouter 模型。 +在 TTY 中运行实时探测时，你可以交互式选择备用模型。在非交互模式下，传入 `--yes` 以接受默认值。仅元数据结果仅供参考；`--set-default` 和 `--set-image` 需要实时探测，这样 OpenClaw 才不会配置无法使用的无密钥 OpenRouter 模型。 -## 模型注册表（`models.json`） +## Models 注册表（`models.json`） -`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.openclaw/agents//agent/models.json`）。除非 `models.mode` 设置为 `replace`，否则默认会合并此文件。 +`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.openclaw/agents//agent/models.json`）。除非 `models.mode` 设为 `replace`，否则默认会合并此文件。 匹配提供商 ID 时的合并模式优先级： - - 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。 - - 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商未由当前配置/凭证配置文件上下文中的 SecretRef 管理时优先。 - - SecretRef 管理的提供商 `apiKey` 值会从来源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/执行引用使用 `secretref-managed`），而不是持久化已解析的机密。 - - SecretRef 管理的提供商标头值会从来源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/执行引用使用 `secretref-managed`）。 - - 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置 `models.providers`。 - - 其他提供商字段会从配置和规范化后的目录数据刷新。 + - 智能体 `models.json` 中已经存在的非空 `baseUrl` 优先。 + - 智能体 `models.json` 中的非空 `apiKey` 仅在当前配置/凭证配置文件上下文中该提供商不是由 SecretRef 管理时优先。 + - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`），而不是持久化解析后的密钥。 + - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`）。 + - 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 + - 其他提供商字段会从配置和规范化目录数据刷新。 -标记持久化以来源为权威：OpenClaw 会从活动来源配置快照（解析前）写入标记，而不是从已解析的运行时机密值写入。只要 OpenClaw 重新生成 `models.json`，包括像 `openclaw agent` 这样的命令驱动路径，都会应用此规则。 +标记持久化以来源为准：OpenClaw 会从活动源配置快照（解析前）写入标记，而不是从解析后的运行时密钥值写入。只要 OpenClaw 重新生成 `models.json`，包括 `openclaw agent` 等命令驱动路径，都会应用此规则。 -## 相关 +## 相关内容 - [Agent Runtimes](/zh-CN/concepts/agent-runtimes) — PI、Codex 和其他 Agent loop 运行时 - [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键 - [图像生成](/zh-CN/tools/image-generation) — 图像模型配置 -- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链 +- [模型故障切换](/zh-CN/concepts/model-failover) — 备用链 - [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由和凭证 - [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置 - [视频生成](/zh-CN/tools/video-generation) — 视频模型配置 diff --git a/docs/zh-CN/tools/slash-commands.md b/docs/zh-CN/tools/slash-commands.md index 96606182b..66c8f0cd6 100644 --- a/docs/zh-CN/tools/slash-commands.md +++ b/docs/zh-CN/tools/slash-commands.md @@ -6,37 +6,37 @@ sidebarTitle: Slash commands summary: 斜杠命令：文本与原生、配置和支持的命令 title: 斜杠命令 x-i18n: - generated_at: "2026-04-28T22:44:27Z" + generated_at: "2026-04-29T17:09:38Z" model: gpt-5.5 provider: openai - source_hash: f9dfa0d86b953fe83989f117a27e5c05ee151ee7bd54c9db3c4190db4418043b + source_hash: bdc4c9e4e2d541c5be089113f144907c150b85cce1922b8a6975fd11a57927aa source_path: tools/slash-commands.md workflow: 16 --- -命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! `（`/bash ` 作为别名）。 +命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! `（`/bash ` 是别名）。 -当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保持本地处理：`/acp ...` 始终到达 OpenClaw ACP 命令处理器；只要该界面启用了命令处理，`/status` 和 `/unfocus` 也会保持本地处理。 +当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍然保持本地处理：`/acp ...` 始终会到达 OpenClaw ACP 命令处理器，并且只要该表面的命令处理已启用，`/status` 加 `/unfocus` 就会保持本地处理。 有两个相关系统： - + 独立的 `/...` 消息。 - + `/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。 - - 指令会在模型看到消息前从消息中剥离。 - - 在普通聊天消息中（不是纯指令），它们会被当作“内联提示”，并且**不会**持久化会话设置。 - - 在纯指令消息中（消息只包含指令），它们会持久化到会话，并回复确认消息。 - - 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被当作纯文本处理。 + - 指令会在模型看到消息前从消息中移除。 + - 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 + - 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话并回复确认。 + - 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对，以及 `commands.useAccessGroups`。未授权发送者的指令会被视为纯文本。 - - 仅限允许列表中/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 + + 仅限允许列表/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - 它们会立即运行，在模型看到消息前被剥离，并且剩余文本会继续进入正常流程。 + 它们会立即运行，在模型看到消息前被移除，剩余文本会继续走正常流程。 @@ -69,28 +69,28 @@ x-i18n: ``` - 启用在聊天消息中解析 `/...`。在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将此项设为 `false`，文本命令仍会工作。 + 启用在聊天消息中解析 `/...`。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将其设置为 `false`，文本命令仍然可用。 注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生命令的提供商忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。 - 在支持时以原生方式注册 **skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 要求为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 + 在支持时原生注册 **Skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 要求为每个 Skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许列表）。 - 控制 bash 在切换到后台模式前等待多久（`0` 表示立即进入后台）。 + 控制 bash 在切换到后台模式前等待多久（`0` 表示立即后台运行）。 启用 `/config`（读取/写入 `openclaw.json`）。 - 启用 `/mcp`（读取/写入 OpenClaw 管理的、位于 `mcp.servers` 下的 MCP 配置）。 + 启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。 - 启用 `/plugins`（插件发现/Status 以及安装 + 启用/禁用控制）。 + 启用 `/plugins`（插件发现/Status，以及安装和启用/停用控制）。 启用 `/debug`（仅运行时覆盖）。 @@ -99,80 +99,80 @@ x-i18n: 启用 `/restart` 以及 Gateway 网关重启工具操作。 - 为仅所有者命令/工具界面设置显式所有者允许列表。这是可批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom`，也独立于私信配对访问。 + 为仅限所有者的命令/工具表面设置显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom`，也独立于私信配对访问。 - 按渠道设置：让仅所有者命令需要**所有者身份**才能在该界面运行。当为 `true` 时，发送者必须匹配某个已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足条件 — 仅所有者命令会在该渠道上默认失败关闭。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令允许列表来门控，请保持此项关闭。 + 按渠道：让仅限所有者的命令在该表面上运行时需要**所有者身份**。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求 —— 仅限所有者的命令会在该渠道上以封闭方式失败。如果你希望仅限所有者的命令只由 `ownerAllowFrom` 和标准命令允许列表约束，请保持此项关闭。 - 控制所有者 ID 在系统提示词中的显示方式。 + 控制所有者 id 在系统提示中的显示方式。 - 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 + 可选地设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 - 用于命令授权的按提供商允许列表。配置后，它就是命令和指令的唯一授权来源（会忽略渠道允许列表/配对以及 `commands.useAccessGroups`）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。 + 用于命令授权的按提供商允许列表。配置后，它是命令和指令的唯一授权来源（渠道允许列表/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。 - 在未设置 `commands.allowFrom` 时，为命令强制执行允许列表/策略。 + 当未设置 `commands.allowFrom` 时，对命令强制执行允许列表/策略。 ## 命令列表 当前事实来源： -- 核心内置项来自 `src/auto-reply/commands-registry.shared.ts` +- 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts` - 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts` - 插件命令来自插件 `registerCommand()` 调用 -- 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道界面，以及已安装/已启用的插件 +- 在你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道表面，以及已安装/已启用的插件 ### 核心内置命令 - + - `/new [model]` 启动新会话；`/reset` 是重置别名。 - - `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 ID，并在原位置重新运行启动/系统提示词加载。 - - `/compact [instructions]` 压缩会话上下文。参见 [压缩](/zh-CN/concepts/compaction)。 + - `/reset soft [message]` 保留当前转录内容，丢弃复用的 CLI 后端会话 id，并在原位重新运行启动/系统提示加载。 + - `/compact [instructions]` 压缩会话上下文。参见[压缩](/zh-CN/concepts/compaction)。 - `/stop` 中止当前运行。 - - `/session idle ` 和 `/session max-age ` 管理线程绑定过期。 + - `/session idle ` 和 `/session max-age ` 管理线程绑定过期时间。 - `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。 - - `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示词、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。 + - `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要某个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。 - - - `/think ` 设置思考级别。选项来自活动模型的提供商配置；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，自定义级别如 `xhigh`、`adaptive`、`max`，或二进制 `on` 仅在支持处可用。别名：`/thinking`、`/t`。 + + - `/think ` 设置思考级别。选项来自活动模型的提供商配置文件；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，自定义级别如 `xhigh`、`adaptive`、`max`，或二进制 `on` 仅在受支持时可用。别名：`/thinking`、`/t`。 - `/verbose on|off|full` 切换详细输出。别名：`/v`。 - - `/trace on|off` 切换当前会话的插件 trace 输出。 + - `/trace on|off` 切换当前会话的插件跟踪输出。 - `/fast [status|on|off]` 显示或设置快速模式。 - `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。 - - `/elevated [on|off|ask|full]` 切换提权模式。别名：`/elev`。 + - `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。 - `/exec host= security= ask= node=` 显示或设置 exec 默认值。 - `/model [name|#|status]` 显示或设置模型。 - - `/models [provider] [page] [limit=|size=|all]` 列出提供商或某个提供商的模型。 - - `/queue ` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`）以及 `debounce:2s cap:25 drop:summarize` 等选项。 + - `/models [provider] [page] [limit=|size=|all]` 列出已配置/可凭证访问的提供商，或列出某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。 + - `/queue ` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及 `debounce:2s cap:25 drop:summarize` 等选项。 - + - `/help` 显示简短帮助摘要。 - `/commands` 显示生成的命令目录。 - `/tools [compact|verbose]` 显示当前智能体现在可以使用什么。 - - `/status` 显示执行/运行时 Status，包括可用时的 `Execution`/`Runtime` 标签以及提供商使用量/配额。 - - `/diagnostics [note]` 是用于 Gateway 网关错误和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 前请求显式 exec 批准；不要用允许全部规则批准 diagnostics。批准后，它会发送一份可粘贴报告，其中包含本地包路径、manifest 摘要、隐私说明和相关会话 ID。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一次批准还会向 OpenAI 服务器发送相关 Codex 反馈，完成后的回复会列出 OpenClaw 会话 ID、Codex 线程 ID 和 `codex resume ` 命令。参见 [Diagnostics 导出](/zh-CN/gateway/diagnostics)。 + - `/status` 显示执行/运行时 Status，包括 `Execution`/`Runtime` 标签，以及可用时的提供商用量/配额。 + - `/diagnostics [note]` 是针对 Gateway 网关 bug 和 Codex harness 运行的仅限所有者支持报告流程。它每次运行 `openclaw gateway diagnostics export --json` 前都会请求显式 exec 批准；不要用 allow-all 规则批准诊断。批准后，它会发送一份可粘贴报告，其中包含本地 bundle 路径、清单摘要、隐私说明和相关会话 id。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一批准还会将相关 Codex 反馈发送到 OpenAI 服务器，完成后的回复会列出 OpenClaw 会话 id、Codex 线程 id 和 `codex resume ` 命令。参见[诊断导出](/zh-CN/gateway/diagnostics)。 - `/crestodian ` 从所有者私信运行 Crestodian 设置和修复助手。 - - `/tasks` 列出当前会话的活动/最近后台任务。 + - `/tasks` 列出当前会话的活动/近期后台任务。 - `/context [list|detail|json]` 解释上下文如何组装。 - - `/whoami` 显示你的发送者 ID。别名：`/id`。 - - `/usage off|tokens|full|cost` 控制每次响应的使用量页脚，或打印本地成本摘要。 + - `/whoami` 显示你的发送者 id。别名：`/id`。 + - `/usage off|tokens|full|cost` 控制每条回复的用量页脚，或打印本地成本摘要。 - - - `/skill [input]` 按名称运行 skill。 + + - `/skill [input]` 按名称运行一个 Skill。 - `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。 - `/approve ` 解决 exec 批准提示。 - - `/btw ` 提出旁支问题，而不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。 + - `/btw ` 提出一个旁路问题，而不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。 - + - `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。 - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。 - `/focus ` 将当前 Discord 线程或 Telegram 话题/对话绑定到会话目标。 @@ -183,53 +183,51 @@ x-i18n: - - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者。需要 `commands.config: true`。 - - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者。需要 `commands.mcp: true`。 - - `/plugins list|inspect|show|get|install|enable|disable` 检查或更改插件状态。`/plugin` 是别名。写入仅限所有者。需要 `commands.plugins: true`。 - - `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅所有者。需要 `commands.debug: true`。 - - `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。 - - `/send on|off|inherit` 设置发送策略。仅所有者。 + - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。 + - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。 + - `/plugins list|inspect|show|get|install|enable|disable` 检查或变更插件状态。`/plugin` 是别名。写入仅限所有者。需要 `commands.plugins: true`。 + - `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限所有者。需要 `commands.debug: true`。 + - `/restart` 在启用时重启 OpenClaw。默认：已启用；设置 `commands.restart: false` 可禁用。 + - `/send on|off|inherit` 设置发送策略。仅限所有者。 - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。参见 [TTS](/zh-CN/tools/tts)。 - `/activation mention|always` 设置群组激活模式。 - - `/bash ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。 - - `!poll [sessionId]` 检查后台 bash 任务。 - - `!stop [sessionId]` 停止后台 bash 任务。 + - `/bash ` 运行宿主 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。 + - `!poll [sessionId]` 检查后台 bash 作业。 + - `!stop [sessionId]` 停止后台 bash 作业。 -### 生成的 dock 命令 +### 生成的停靠命令 -Dock 命令会将当前会话的回复路由切换到另一个已关联的 -渠道。设置、 -示例和故障排除请参见[渠道停靠](/zh-CN/concepts/channel-docking)。 +停靠命令会将当前会话的回复路由切换到另一个已关联的渠道。有关设置、示例和故障排除，请参见 [渠道停靠](/zh-CN/concepts/channel-docking)。 -Dock 命令由支持原生命令的渠道插件生成。当前内置集合： +停靠命令由支持原生命令的渠道插件生成。当前内置集合： - `/dock-discord`（别名：`/dock_discord`） - `/dock-mattermost`（别名：`/dock_mattermost`） - `/dock-slack`（别名：`/dock_slack`） - `/dock-telegram`（别名：`/dock_telegram`） -在直接聊天中使用 dock 命令，将当前会话的回复路由切换到另一个已关联的渠道。智能体会保留同一个会话上下文，但该会话后续回复会发送到所选的渠道对端。 +在直接聊天中使用停靠命令，可将当前会话的回复路由切换到另一个已关联的渠道。智能体会保留相同的会话上下文，但该会话之后的回复会发送给所选渠道对端。 -Dock 命令需要 `session.identityLinks`。源发送者和目标对端必须在同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 ID 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未关联到 Discord 对端，该命令会回复设置提示，而不是落入普通聊天流程。 +停靠命令需要 `session.identityLinks`。源发送者和目标对端必须位于同一个身份组，例如 `["telegram:123", "discord:456"]`。如果 id 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未关联到 Discord 对端，该命令会返回设置提示，而不是落入普通聊天。 -Docking 只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，或将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的 dock 命令可再次切换路由。 +停靠只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，也不会将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或其他生成的停靠命令来再次切换路由。 ### 内置插件命令 -内置插件可以添加更多斜杠命令。此仓库当前的内置命令： +内置插件可以添加更多斜杠命令。此仓库中当前的内置命令： - `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。 -- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见[配对](/zh-CN/channels/pairing)。 +- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [配对](/zh-CN/channels/pairing)。 - `/phone status|arm [duration]|disarm` 临时启用高风险手机节点命令。 - `/voice status|list [limit]|set ` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。 - `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。 -- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查并控制内置 Codex app-server harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。 +- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查和控制内置 Codex app-server harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。 - 仅 QQBot 的命令： - `/bot-ping` - `/bot-version` @@ -237,89 +235,89 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访 - `/bot-upgrade` - `/bot-logs` -### 动态 skill 命令 +### 动态 Skill 命令 -用户可调用的 skills 也会公开为斜杠命令： +用户可调用的 Skills 也会暴露为斜杠命令： - `/skill [input]` 始终作为通用入口点可用。 -- 当 skill/插件注册它们时，skills 也可能显示为 `/prose` 这样的直接命令。 -- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 +- 当 Skill/插件注册时，Skills 也可能显示为类似 `/prose` 的直接命令。 +- 原生 Skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 - - 命令可在命令和参数之间接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 - - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。 - - 如需完整的提供商用量细分，请使用 `openclaw status --usage`。 + - 命令在命令和参数之间接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 + - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。 + - 如需完整的提供商使用情况细分，请使用 `openclaw status --usage`。 - `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。 - - 在多账号渠道中，面向配置的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账号的 `configWrites`。 - - `/usage` 控制每次回复的用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地成本摘要。 - - `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。 + - 在多账号渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账号的 `configWrites`。 + - `/usage` 控制每条回复的用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地费用摘要。 + - `/restart` 默认启用；设置 `commands.restart: false` 可禁用。 - `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包或 `clawhub:`。 - `/plugins enable|disable` 会更新插件配置，并可能提示重启。 - - 仅 Discord 原生命令：`/vc join|leave|status` 控制语音频道（不可作为文本使用）。`join` 需要一个服务器以及选中的语音/舞台频道。需要 `channels.discord.voice` 和原生命令。 + - 仅 Discord 的原生命令：`/vc join|leave|status` 控制语音渠道（不能作为文本使用）。`join` 需要一个 guild 和已选择的语音/舞台渠道。需要 `channels.discord.voice` 和原生命令。 - Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 - ACP 命令参考和运行时行为：[ACP 智能体](/zh-CN/tools/acp-agents)。 - - - `/verbose` 用于调试和提供额外可见性；正常使用时保持**关闭**。 - - `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具杂项输出关闭。 - - `/fast on|off` 会持久化会话覆盖。使用 Sessions UI 的 `inherit` 选项清除它，并回退到配置默认值。 - - `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公开 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 - - 相关时仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。 - - `/reasoning`、`/verbose` 和 `/trace` 在群组设置中有风险：它们可能暴露你不打算公开的内部推理、工具输出或插件诊断。优先保持关闭，尤其是在群聊中。 + + - `/verbose` 用于调试和额外可见性；正常使用时保持**关闭**。 + - `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通详细工具噪声关闭。 + - `/fast on|off` 会持久化会话覆盖。使用 Sessions UI 的 `inherit` 选项可清除它并回退到配置默认值。 + - `/fast` 与提供商相关：OpenAI/OpenAI Codex 在原生 Responses 端点上会将它映射到 `service_tier=priority`，而直接公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将它映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 + - 工具失败摘要在相关时仍会显示，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。 + - `/reasoning`、`/verbose` 和 `/trace` 在群组设置中有风险：它们可能泄露你本不打算暴露的内部 reasoning、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。 - `/model` 会立即持久化新的会话模型。 - - 如果智能体空闲，下一次运行会立即使用它。 - - 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在干净的重试点重启到新模型。 - - 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到稍后的重试机会或下一次用户回合。 - - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这与消息渠道救援模式分开，并且不会授予远程配置权限。 + - 如果智能体处于空闲状态，下一次运行会立即使用它。 + - 如果运行已处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只在干净的重试点重启到新模型。 + - 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到之后的重试机会或下一轮用户输入。 + - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回 Crestodian。这与消息渠道救援模式不同，也不会授予远程配置权限。 - - **快速路径：**来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。 - - **群组提及门控：**来自允许列表发送者的纯命令消息会绕过提及要求。 - - **内联快捷方式（仅允许列表发送者）：**某些命令在嵌入普通消息时也可用，并会在模型看到剩余文本之前被剥离。 - - 示例：`hey /status` 会触发 Status 回复，剩余文本继续走普通流程。 + - **快速路径：** 来自允许列表发送者的纯命令消息会被立即处理（绕过队列 + 模型）。 + - **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。 + - **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入普通消息时也能工作，并且会在模型看到剩余文本之前被剥离。 + - 示例：`hey /status` 会触发 Status 回复，剩余文本会继续走普通流程。 - 当前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - 未授权的纯命令消息会被静默忽略，内联 `/...` 标记会被视为纯文本。 - - **Skill 命令：**`user-invocable` skills 会公开为斜杠命令。名称会清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。 - - `/skill [input]` 按名称运行 skill（当原生命令限制阻止为每个 skill 创建命令时很有用）。 - - 默认情况下，skill 命令会作为普通请求转发给模型。 + - **Skill 命令：** `user-invocable` Skills 会暴露为斜杠命令。名称会被清洗为 `a-z0-9_`（最多 32 个字符）；冲突时会获得数字后缀（例如 `_2`）。 + - `/skill [input]` 按名称运行 Skill（当原生命令限制阻止为每个 Skill 提供命令时很有用）。 + - 默认情况下，Skill 命令会作为普通请求转发给模型。 - Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，无模型）。 - 示例：`/prose`（OpenProse 插件）— 参见 [OpenProse](/zh-CN/prose)。 - - **原生命令参数：**Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。当命令支持选项且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会基于目标会话模型解析，因此 `/think` 级别等模型特定选项会遵循该会话的 `/model` 覆盖。 + - **原生命令参数：** Discord 对动态选项使用自动补全（省略必需参数时使用按钮菜单）。当命令支持选项且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会针对目标会话模型解析，因此模型特定选项（例如 `/think` 级别）会遵循该会话的 `/model` 覆盖。 ## `/tools` -`/tools` 回答的是运行时问题，而不是配置问题：**此智能体现在在这个对话中可以使用什么**。 +`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在在这段对话中可以使用什么**。 -- 默认 `/tools` 紧凑，并针对快速浏览优化。 +- 默认 `/tools` 很紧凑，并针对快速浏览优化。 - `/tools verbose` 添加简短描述。 -- 支持参数的原生命令界面会公开同样的模式切换：`compact|verbose`。 +- 支持参数的原生命令表面会暴露相同的模式开关：`compact|verbose`。 - 结果限定于会话范围，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。 - `/tools` 包含运行时实际可达的工具，包括核心工具、已连接的插件工具和渠道拥有的工具。 -如需编辑 profile 和覆盖，请使用 Control UI Tools 面板或配置/catalog 界面，而不是把 `/tools` 当作静态目录。 +对于配置文件和覆盖编辑，请使用 Control UI Tools 面板或配置/目录表面，而不是把 `/tools` 当作静态目录。 -## 用量界面（哪里显示什么） +## 使用情况表面（哪里显示什么） -- **提供商用量/配额**（示例：“Claude 剩余 80%”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余 %”；对于 MiniMax，仅剩余百分比字段会在显示前反转，`model_remains` 响应会优先使用聊天模型条目以及带模型标签的计划标签。 -- **Token/缓存行**在 `/status` 中可在实时会话快照稀疏时回退到最新转录用量条目。现有非零实时值仍然优先，转录回退也可以恢复活动运行时模型标签，以及当存储总数缺失或较小时恢复更大的面向提示的总数。 -- **执行 vs 运行时：**`/status` 会为有效沙箱路径报告 `Execution`，并为实际运行会话的主体报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。 -- **每次回复 token/成本**由 `/usage off|tokens|full` 控制（附加到普通回复）。 -- `/model status` 关注的是**模型/认证/端点**，不是用量。 +- **提供商使用量/配额**（示例：“Claude 剩余 80%”）会在启用使用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余 %”；对于 MiniMax，仅剩余百分比字段会在显示前反转，并且 `model_remains` 响应优先使用聊天模型条目以及带模型标签的计划标签。 +- **Token/缓存行** 在 `/status` 中可以在实时会话快照稀疏时回退到最新转录用量条目。已有的非零实时值仍然优先，转录回退也可以恢复活动运行时模型标签，以及在存储总量缺失或更小时恢复更大的面向提示词的总量。 +- **执行与运行时：** `/status` 对有效沙箱路径报告 `Execution`，并对实际运行会话的对象报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。 +- **每条回复 token/费用** 由 `/usage off|tokens|full` 控制（追加到普通回复）。 +- `/model status` 关注的是**模型/凭证/端点**，而不是使用量。 ## 模型选择（`/model`） @@ -338,14 +336,14 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访 说明： -- `/model` 和 `/model list` 显示紧凑的编号选择器（模型系列 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开交互式选择器，包含提供商和模型下拉框以及 Submit 步骤。 -- `/model <#>` 从该选择器中选择（并在可能时优先使用当前提供商）。 +- `/model` 和 `/model list` 显示紧凑的编号选择器（模型家族 + 可用提供商）。 +- 在 Discord 上，`/model` 和 `/models` 会打开带有提供商和模型下拉框以及 Submit 步骤的交互式选择器。 +- `/model <#>` 从该选择器中选择（并在可能时优先选择当前提供商）。 - `/model status` 显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`，如果可用）。 ## 调试覆盖 -`/debug` 可让你设置**仅运行时**配置覆盖（内存中，而非磁盘）。仅限所有者使用。默认禁用；使用 `commands.debug: true` 启用。 +`/debug` 允许你设置**仅运行时**的配置覆盖（内存中，不写入磁盘）。仅所有者可用。默认禁用；使用 `commands.debug: true` 启用。 示例： @@ -358,12 +356,12 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访 ``` -覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。 +覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并回到磁盘上的配置。 -## 插件跟踪输出 +## 插件追踪输出 -`/trace` 可让你切换**会话作用域的插件跟踪/调试行**，而无需开启完整详细模式。 +`/trace` 允许你切换**会话范围内的插件追踪/调试行**，而无需开启完整详细模式。 示例： @@ -375,16 +373,16 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访 注意： -- 不带参数的 `/trace` 会显示当前会话的跟踪状态。 -- `/trace on` 会为当前会话启用插件跟踪行。 +- 不带参数的 `/trace` 会显示当前会话的追踪状态。 +- `/trace on` 会为当前会话启用插件追踪行。 - `/trace off` 会再次禁用它们。 -- 插件跟踪行可能出现在 `/status` 中，也可能在普通助手回复后作为后续诊断消息出现。 -- `/trace` 不会取代 `/debug`；`/debug` 仍用于管理仅运行时配置覆盖。 -- `/trace` 不会取代 `/verbose`；普通详细工具/Status 输出仍属于 `/verbose`。 +- 插件追踪行可以出现在 `/status` 中，也可以在正常助手回复之后作为后续诊断消息出现。 +- `/trace` 不会取代 `/debug`；`/debug` 仍然管理仅运行时的配置覆盖。 +- `/trace` 不会取代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。 ## 配置更新 -`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者使用。默认禁用；使用 `commands.config: true` 启用。 +`/config` 会写入你的磁盘配置（`openclaw.json`）。仅所有者可用。默认禁用；使用 `commands.config: true` 启用。 示例： @@ -402,7 +400,7 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访 ## MCP 更新 -`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者使用。默认禁用；使用 `commands.mcp: true` 启用。 +`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅所有者可用。默认禁用；使用 `commands.mcp: true` 启用。 示例： @@ -419,7 +417,7 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访 ## 插件更新 -`/plugins` 可让操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。 +`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。 示例： @@ -432,45 +430,45 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访 ``` -- `/plugins list` 和 `/plugins show` 会基于当前工作区加磁盘配置执行真实的插件发现。 +- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的插件发现。 - `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。 -- 启用/禁用更改后，请重启 Gateway 网关以应用它们。 +- 启用/禁用更改后，重启 Gateway 网关以应用它们。 -## 接入面说明 +## 界面说明 - + - **文本命令**在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。 - **原生命令**使用隔离会话： - Discord：`agent::discord:slash:` - Slack：`agent::slack:slash:`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置） - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位聊天会话） - - **`/stop`** 定位活跃聊天会话，以便它可以中止当前运行。 + - **`/stop`** 定位活动聊天会话，因此它可以中止当前运行。 - - 仍支持 `channels.slack.slashCommand` 用于单个 `/openclaw` 风格命令。如果你启用 `commands.native`，必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式发送。 + + 仍然支持 `channels.slack.slashCommand` 用于单个 `/openclaw` 风格命令。如果启用 `commands.native`，你必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会作为临时 Block Kit 按钮发送。 - Slack 原生例外：注册 `/agentstatus`（不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 仍可在 Slack 消息中使用。 + Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然有效。 -## BTW 附带问题 +## BTW 旁路问题 -`/btw` 是关于当前会话的快速**附带问题**。 +`/btw` 是关于当前会话的快速**旁路问题**。 -不同于普通聊天： +与普通聊天不同： - 它使用当前会话作为背景上下文， -- 它作为单独的**无工具**一次性调用运行， +- 它作为一次独立的**无工具**单次调用运行， - 它不会改变未来的会话上下文， - 它不会写入转录历史， -- 它会作为实时附带结果发送，而不是普通助手消息。 +- 它会作为实时旁路结果发送，而不是普通助手消息。 -当你想在主任务继续进行时临时澄清某个问题，`/btw` 很有用。 +因此，当你希望在主任务继续进行时临时澄清某件事，`/btw` 会很有用。 示例： @@ -478,9 +476,9 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访 /btw what are we doing right now? ``` -请参阅 [BTW 附带问题](/zh-CN/tools/btw)，了解完整行为和客户端 UX 细节。 +请参阅 [BTW 旁路问题](/zh-CN/tools/btw)，了解完整行为和客户端 UX 细节。 -## 相关 +## 相关内容 - [创建 Skills](/zh-CN/tools/creating-skills) - [Skills](/zh-CN/tools/skills) diff --git a/docs/zh-CN/web/control-ui.md b/docs/zh-CN/web/control-ui.md index d29c7a271..14b2603b4 100644 --- a/docs/zh-CN/web/control-ui.md +++ b/docs/zh-CN/web/control-ui.md @@ -1,48 +1,48 @@ --- read_when: - - 你想通过浏览器操作 Gateway 网关 - - 你希望无需 SSH 隧道即可访问 Tailnet + - 你想从浏览器操作 Gateway 网关 + - 你想要无需 SSH 隧道即可访问 Tailnet sidebarTitle: Control UI -summary: 基于浏览器的 Gateway 网关控制 UI（聊天、节点、配置） +summary: Gateway 网关的基于浏览器的控制 UI（聊天、节点、配置） title: 控制界面 x-i18n: - generated_at: "2026-04-29T03:16:15Z" + generated_at: "2026-04-29T17:09:41Z" model: gpt-5.5 provider: openai - source_hash: 4e8b3d8b346748a6fb1112d7c6e53e8ca7a87d1d974fcd44772997393c395c08 + source_hash: d7846eaf1b1e00ab05a3ed22ec021b5dbc33b24c26b76a72823c9b61bfcb64b4 source_path: web/control-ui.md workflow: 16 --- -Control UI 是由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用： +控制 UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用： -- 默认值：`http://:18789/` +- 默认：`http://:18789/` - 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`） 它会在同一端口上**直接与 Gateway 网关 WebSocket 通信**。 ## 快速打开（本地） -如果 Gateway 网关在同一台计算机上运行，请打开： +如果 Gateway 网关在同一台电脑上运行，请打开： - [http://127.0.0.1:18789/](http://127.0.0.1:18789/)（或 [http://localhost:18789/](http://localhost:18789/)） 如果页面加载失败，请先启动 Gateway 网关：`openclaw gateway`。 -凭证会在 WebSocket 握手期间通过以下方式提供： +身份验证会在 WebSocket 握手期间通过以下方式提供： - `connect.params.auth.token` - `connect.params.auth.password` -- 当 `gateway.auth.allowTailscale: true` 时的 Tailscale Serve 身份标头 -- 当 `gateway.auth.mode: "trusted-proxy"` 时的可信代理身份标头 +- 当 `gateway.auth.allowTailscale: true` 时使用 Tailscale Serve 身份标头 +- 当 `gateway.auth.mode: "trusted-proxy"` 时使用可信代理身份标头 -仪表板设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保留一个令牌；密码不会被持久化。新手引导通常会在首次连接时为共享密钥凭证生成 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，也可以使用密码凭证。 +仪表板设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保留令牌；密码不会持久保存。新手引导通常会在首次连接时为共享密钥身份验证生成 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，密码身份验证也可用。 ## 设备配对（首次连接） -当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关通常会要求**一次性配对批准**。这是一项安全措施，用于防止未经授权的访问。 +当你从新的浏览器或设备连接到控制 UI 时，Gateway 网关通常需要**一次性配对批准**。这是一项用于防止未授权访问的安全措施。 -**你会看到：**“disconnected (1008): pairing required” +**你会看到：** “disconnected (1008): pairing required” @@ -57,94 +57,94 @@ Control UI 是由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应 -如果浏览器使用变更后的凭证详细信息（角色/作用域/公钥）重试配对，之前待处理的请求会被取代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。 +如果浏览器在身份验证详情（角色/范围/公钥）变更后重试配对，之前的待处理请求会被取代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。 -如果浏览器已经配对，而你将它从读取访问权限改为写入/管理员访问权限，这会被视为批准升级，而不是静默重连。OpenClaw 会保持旧批准有效，阻止权限更大的重连，并要求你明确批准新的作用域集合。 +如果浏览器已经配对，而你将它从读取访问改为写入/管理员访问，这会被视为一次批准升级，而不是静默重连。OpenClaw 会保持旧批准有效，阻止权限更大的重连，并要求你明确批准新的范围集合。 -批准后，该设备会被记住，并且不再需要重新批准，除非你使用 `openclaw devices revoke --device --role ` 撤销它。请参阅 [Devices CLI](/zh-CN/cli/devices) 了解令牌轮换和撤销。 +批准后，该设备会被记住，除非你使用 `openclaw devices revoke --device --role ` 撤销它，否则不需要重新批准。有关令牌轮换和撤销，请参阅 [设备 CLI](/zh-CN/cli/devices)。 - 直接的 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动批准。 -- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过，并且浏览器提供其设备身份时，Tailscale Serve 可以为 Control UI 操作员会话跳过配对往返。 -- 直接的 Tailnet 绑定、LAN 浏览器连接，以及没有设备身份的浏览器配置文件仍然需要显式批准。 -- 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据将需要重新配对。 +- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过且浏览器提供其设备身份时，Tailscale Serve 可以为控制 UI 操作员会话跳过配对往返。 +- 直接 Tailnet 绑定、LAN 浏览器连接，以及没有设备身份的浏览器配置文件仍需要显式批准。 +- 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据会需要重新配对。 ## 个人身份（浏览器本地） -Control UI 支持按浏览器设置个人身份（显示名称和头像），并将其附加到传出消息，用于在共享会话中标注归属。它存储在浏览器存储中，作用域限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务器端持久化，除了你实际发送的消息上正常的转录作者元数据。清除站点数据或切换浏览器会将其重置为空。 +控制 UI 支持按浏览器设置个人身份（显示名称和头像），并将其附加到外发消息中，用于共享会话中的归属标识。它存放在浏览器存储中，范围限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务端持久保存，除了你实际发送的消息上的正常转录作者元数据。清除站点数据或切换浏览器会将其重置为空。 同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖由 Gateway 网关解析出的身份，并且绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍可供直接写入该字段的非 UI 客户端使用（例如脚本化 Gateway 网关或自定义仪表板）。 ## 运行时配置端点 -Control UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点受到与其余 HTTP 表面相同的 Gateway 网关凭证保护：未经身份验证的浏览器无法获取它，成功获取需要已有有效的 Gateway 网关令牌/密码、Tailscale Serve 身份，或可信代理身份。 +控制 UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点由与其他 HTTP 表面相同的 Gateway 网关身份验证保护：未认证的浏览器无法获取它，成功获取需要已有有效的 Gateway 网关令牌/密码、Tailscale Serve 身份，或可信代理身份。 ## 语言支持 -Control UI 可以在首次加载时根据你的浏览器区域设置进行本地化。若要稍后覆盖它，请打开 **Overview -> Gateway Access -> Language**。区域设置选择器位于 Gateway Access 卡片中，而不是 Appearance 下。 +控制 UI 可以在首次加载时根据你的浏览器区域设置进行本地化。若要稍后覆盖它，请打开 **概览 -> Gateway 网关访问 -> 语言**。区域设置选择器位于 Gateway 网关访问卡片中，而不是外观下。 - 支持的区域设置：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`tr`、`uk`、`id`、`pl`、`th` - 非英语翻译会在浏览器中延迟加载。 -- 所选区域设置会保存在浏览器存储中，并在后续访问时复用。 +- 所选区域设置会保存在浏览器存储中，并在之后访问时复用。 - 缺失的翻译键会回退到英语。 ## 外观主题 -Appearance 面板保留内置的 Claw、Knot 和 Dash 主题，以及一个浏览器本地的 tweakcn 导入槽位。若要导入主题，请打开 [tweakcn themes](https://tweakcn.com/themes)，选择或创建一个主题，点击 **Share**，然后将复制的主题链接粘贴到 Appearance 中。导入器也接受 `https://tweakcn.com/r/themes/` 注册表 URL、类似 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的编辑器 URL、相对 `/themes/` 路径、原始主题 ID，以及 `amethyst-haze` 等默认主题名称。 +外观面板保留内置的 Claw、Knot 和 Dash 主题，外加一个浏览器本地的 tweakcn 导入槽。要导入主题，请打开 [tweakcn 主题](https://tweakcn.com/themes)，选择或创建主题，点击**共享**，然后将复制的主题链接粘贴到外观中。导入器也接受 `https://tweakcn.com/r/themes/` 注册表 URL、类似 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的编辑器 URL、相对 `/themes/` 路径、原始主题 ID，以及 `amethyst-haze` 等默认主题名称。 -导入的主题只存储在当前浏览器配置文件中。它们不会写入 Gateway 网关配置，也不会跨设备同步。替换导入的主题会更新这一个本地槽位；如果当前选择的是导入主题，清除它会将活动主题切回 Claw。 +导入的主题只会存储在当前浏览器配置文件中。它们不会写入 Gateway 网关配置，也不会跨设备同步。替换导入的主题会更新这一个本地槽；如果当前选中了导入的主题，清除它会把活动主题切回 Claw。 -## 它能做什么（当前） +## 它现在能做什么 - 通过 Gateway 网关 WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）。 - - 通过浏览器实时会话进行语音对话。OpenAI 使用直接 WebRTC，Google Live 通过 WebSocket 使用受限的一次性浏览器令牌，而仅后端的实时语音插件使用 Gateway 网关中继传输。中继会将提供商凭据保留在 Gateway 网关上，同时浏览器通过 `talk.realtime.relay*` RPC 流式传输麦克风 PCM，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用发回给配置的更大的 OpenClaw 模型。 - - 在 Chat 中流式传输工具调用和实时工具输出卡片（智能体事件）。 + - 通过浏览器实时会话进行语音对话。OpenAI 使用直接 WebRTC，Google Live 通过 WebSocket 使用受限的一次性浏览器令牌，而仅后端的实时语音插件使用 Gateway 网关中继传输。中继会将提供商凭证保留在 Gateway 网关上，同时浏览器通过 `talk.realtime.relay*` RPC 流式传输麦克风 PCM，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用发回给配置的更大 OpenClaw 模型。 + - 在聊天中流式传输工具调用和实时工具输出卡片（智能体事件）。 - - - 渠道：内置渠道以及内置/外部插件渠道 Status、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。 - - 实例：在线列表和刷新（`system-presence`）。 - - 会话：列表和按会话的模型/thinking/fast/verbose/trace/reasoning 覆盖（`sessions.list`、`sessions.patch`）。 - - Dreams：dreaming Status、启用/禁用切换，以及 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。 + + - 渠道：内置以及捆绑/外部插件渠道的 Status、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。 + - 实例：在线状态列表和刷新（`system-presence`）。 + - 会话：列表以及按会话设置模型/思考/快速/详细/追踪/推理覆盖（`sessions.list`、`sessions.patch`）。 + - 梦境：Dreaming 状态、启用/禁用开关，以及梦境日记阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。 - - - Cron 作业：列出/添加/编辑/运行/启用/禁用，以及运行历史（`cron.*`）。 - - Skills：Status、启用/禁用、安装、API 密钥更新（`skills.*`）。 + + - Cron 作业：列出/添加/编辑/运行/启用/禁用以及运行历史（`cron.*`）。 + - Skills：状态、启用/禁用、安装、API key 更新（`skills.*`）。 - 节点：列表和能力（`node.list`）。 - Exec 批准：编辑 Gateway 网关或节点允许列表，以及 `exec host=gateway/node` 的询问策略（`exec.approvals.*`）。 - 查看/编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。 - - 通过验证应用并重启（`config.apply`），并唤醒上一个活动会话。 - - 写入包含基准哈希保护，防止覆盖并发编辑。 - - 写入（`config.set`/`config.apply`/`config.patch`）会对提交的配置载荷中的引用预检活动 SecretRef 解析；未解析的活动提交引用会在写入前被拒绝。 - - Schema 和表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件和渠道 schema）；只有当快照具有安全的原始往返能力时，Raw JSON 编辑器才可用。 - - 如果快照无法安全地往返原始文本，Control UI 会强制使用 Form 模式，并为该快照禁用 Raw 模式。 - - Raw JSON 编辑器中的“Reset to saved”会保留原始编写的形状（格式、注释、`$include` 布局），而不是重新渲染展平的快照，因此当快照可以安全往返时，外部编辑会在重置后保留下来。 - - 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，以防意外发生对象到字符串的损坏。 + - 应用并通过校验后重启（`config.apply`），并唤醒最后一个活跃会话。 + - 写入包含 base-hash 保护，以防覆盖并发编辑。 + - 写入（`config.set`/`config.apply`/`config.patch`）会对提交的配置载荷中的引用预检活跃 SecretRef 解析；未解析的活跃提交引用会在写入前被拒绝。 + - 架构和表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件和渠道架构）；仅当快照具备安全的原始往返能力时，原始 JSON 编辑器才可用。 + - 如果快照无法安全地往返原始文本，控制 UI 会强制使用表单模式，并为该快照禁用原始模式。 + - 原始 JSON 编辑器的“重置为已保存”会保留原始编写形态（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此当快照可以安全往返时，外部编辑会在重置后保留下来。 + - 结构化 SecretRef 对象值在表单文本输入中以只读方式呈现，以防意外发生对象到字符串的损坏。 - - 调试：Status/health/models 快照、事件日志和手动 RPC 调用（`status`、`health`、`models.list`）。 - - 日志：带过滤/导出的 Gateway 网关文件日志实时尾随（`logs.tail`）。 - - 更新：运行包/git 更新并重启（`update.run`），生成重启报告，然后在重连后轮询 `update.status`，验证正在运行的 Gateway 网关版本。 + - 调试：Status/健康/模型快照、事件日志和手动 RPC 调用（`status`、`health`、`models.list`）。 + - 日志：实时跟踪 Gateway 网关文件日志，支持过滤/导出（`logs.tail`）。 + - 更新：运行 package/git 更新并重启（`update.run`），生成重启报告，然后在重连后轮询 `update.status` 以验证正在运行的 Gateway 网关版本。 - - 对于隔离作业，交付默认会公告摘要。如果你想要仅内部运行，可以切换为 none。 - - 选择公告时会显示渠道/目标字段。 + - 对于隔离作业，交付默认宣布摘要。如果你想要仅内部运行，可以切换为无。 + - 选择宣布时会显示渠道/目标字段。 - Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。 - - 对于主会话作业，可以使用 webhook 和 none 交付模式。 - - 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/thinking 覆盖，以及尽力而为交付切换。 - - 表单验证以内联方式显示字段级错误；无效值会禁用保存按钮，直到修复。 - - 设置 `cron.webhookToken` 可发送专用 bearer 令牌；如果省略，webhook 会在不带凭证标头的情况下发送。 - - 已弃用的回退：存储的旧版作业如果带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。 + - 对于主会话作业，可以使用 webhook 和无交付模式。 + - 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/思考覆盖，以及尽力交付开关。 + - 表单验证以内联方式显示字段级错误；无效值会禁用保存按钮，直到修复为止。 + - 设置 `cron.webhookToken` 可发送专用 bearer token；如果省略，webhook 会在没有 auth 标头的情况下发送。 + - 已弃用的回退：存储的旧版作业若带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。 @@ -153,83 +153,83 @@ Appearance 面板保留内置的 Claw、Knot 和 Dash 主题，以及一个浏 - - `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，响应会通过 `chat` 事件流式传输。 + - `chat.send` 是**非阻塞**的：它会立即以 `{ runId, status: "started" }` 确认，响应通过 `chat` 事件流式传输。 - 聊天上传接受图片以及非视频文件。图片保留原生图片路径；其他文件会作为托管媒体存储，并在历史记录中显示为附件链接。 - - 使用相同的 `idempotencyKey` 重新发送时，运行期间会返回 `{ status: "in_flight" }`，完成后会返回 `{ status: "ok" }`。 - - 出于 UI 安全考虑，`chat.history` 响应有大小限制。当转录条目过大时，Gateway 网关可能会截断长文本字段、省略较重的元数据块，并用占位符（`[chat.history omitted: message too large]`）替换超大的消息。 + - 使用相同的 `idempotencyKey` 重新发送时，运行期间返回 `{ status: "in_flight" }`，完成后返回 `{ status: "ok" }`。 + - 为了 UI 安全，`chat.history` 响应有大小限制。当转录条目过大时，Gateway 网关可能会截断长文本字段、省略较大的元数据块，并用占位符（`[chat.history omitted: message too large]`）替换超大的消息。 - 助手/生成的图片会作为托管媒体引用持久化，并通过经过身份验证的 Gateway 网关媒体 URL 返回，因此重新加载不依赖原始 base64 图片载荷继续保留在聊天历史响应中。 - - `chat.history` 还会从可见助手文本中剥离仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 载荷（包括 `...`、`...`、`...`、`...` 和被截断的工具调用块），以及泄漏的 ASCII/全角模型控制标记，并省略可见文本整体仅为精确静默标记 `NO_REPLY` / `no_reply` 的助手条目。 - - 在一次活跃发送以及最终历史刷新期间，如果 `chat.history` 短暂返回较旧快照，聊天视图会继续显示本地乐观用户/助手消息；当 Gateway 网关历史记录追上后，规范转录会替换这些本地消息。 - - `chat.inject` 会向会话转录追加一条助手备注，并广播一个 `chat` 事件用于仅 UI 更新（不运行智能体，不进行渠道投递）。 - - 聊天标题中的模型和思考选择器会通过 `sessions.patch` 立即修补活跃会话；它们是持久会话覆盖项，而不是仅单轮发送选项。 - - 聊天模型选择器会请求 Gateway 网关配置的模型视图。如果存在 `agents.defaults.models`，该允许列表会驱动选择器。否则，选择器会先显示显式的 `models.providers.*.models` 条目，然后针对全新安装回退到完整目录。 - - 当新的 Gateway 网关会话使用报告显示上下文压力较高时，聊天输入区域会显示上下文提示，并在建议压缩级别显示一个紧凑按钮，用于运行正常的会话压缩路径。陈旧的 token 快照会被隐藏，直到 Gateway 网关再次报告新的使用情况。 + - `chat.history` 还会从可见助手文本中移除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 载荷（包括 `...`、`...`、`...`、`...` 以及被截断的工具调用块）和泄漏的 ASCII/全角模型控制令牌，并省略那些整个可见文本仅为精确静默令牌 `NO_REPLY` / `no_reply` 的助手条目。 + - 在活跃发送期间以及最终历史记录刷新时，如果 `chat.history` 短暂返回较旧的快照，聊天视图会继续显示本地乐观的用户/助手消息；一旦 Gateway 网关历史记录追上，规范转录会替换这些本地消息。 + - `chat.inject` 会向会话转录追加一条助手注释，并广播一个用于仅 UI 更新的 `chat` 事件（不运行智能体，不进行渠道投递）。 + - 聊天标题中的模型和思考选择器会立即通过 `sessions.patch` 修补活跃会话；它们是持久会话覆盖项，不是仅单轮的发送选项。 + - 聊天模型选择器会请求 Gateway 网关的已配置模型视图。如果存在 `agents.defaults.models`，该允许列表会驱动选择器。否则，选择器会显示显式的 `models.providers.*.models` 条目以及具备可用凭证的提供商。完整目录仍可通过调试 `models.list` RPC 使用 `view: "all"` 获取。 + - 当新的 Gateway 网关会话用量报告显示上下文压力较高时，聊天编写区会显示上下文提示，并在建议压缩级别显示一个压缩按钮，用于运行正常的会话压缩路径。过期的令牌快照会被隐藏，直到 Gateway 网关再次报告新的用量。 - - 通话模式使用已注册的实时语音提供商。可以使用 `talk.provider: "openai"` 加 `talk.providers.openai.apiKey` 配置 OpenAI，或使用 `talk.provider: "google"` 加 `talk.providers.google.apiKey` 配置 Google；语音通话实时提供商配置仍可作为回退复用。浏览器永远不会收到标准提供商 API 密钥。OpenAI 会收到用于 WebRTC 的临时 Realtime 客户端密钥。Google Live 会收到用于浏览器 WebSocket 会话的一次性受限 Live API 认证 token，其中指令和工具声明由 Gateway 网关锁定到 token 中。仅公开后端实时桥接的提供商会通过 Gateway 网关中继传输运行，因此凭据和厂商套接字保留在服务端，而浏览器音频通过经过身份验证的 Gateway 网关 RPC 传输。Realtime 会话提示由 Gateway 网关组装；`talk.realtime.session` 不接受调用方提供的指令覆盖项。 + + Talk 模式使用已注册的实时语音提供商。使用 `talk.provider: "openai"` 加上 `talk.providers.openai.apiKey` 配置 OpenAI，或使用 `talk.provider: "google"` 加上 `talk.providers.google.apiKey` 配置 Google；Voice Call 实时提供商配置仍可作为回退复用。浏览器永远不会收到标准提供商 API key。OpenAI 会收到用于 WebRTC 的临时 Realtime 客户端密钥。Google Live 会收到一个用于浏览器 WebSocket 会话的一次性受限 Live API 凭证令牌，并且指令和工具声明会由 Gateway 网关锁定到该令牌中。只公开后端实时桥接的提供商会通过 Gateway 网关中继传输运行，因此凭证和供应商套接字保留在服务器端，而浏览器音频通过经过身份验证的 Gateway 网关 RPC 传输。Realtime 会话提示词由 Gateway 网关组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。 - 在聊天输入框中，通话控件是麦克风听写按钮旁边的波形按钮。通话启动后，输入框状态行先显示 `Connecting Talk...`，音频连接后显示 `Talk live`，或在实时工具调用通过 `chat.send` 咨询已配置的较大模型时显示 `Asking OpenClaw...`。 + 在聊天编写器中，Talk 控件是麦克风听写按钮旁边的波形按钮。Talk 启动后，编写器状态行会显示 `Connecting Talk...`，音频连接后显示 `Talk live`，或者在实时工具调用通过 `chat.send` 咨询已配置的更大模型时显示 `Asking OpenClaw...`。 - 维护者实时冒烟测试：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 浏览器 WebRTC SDP 交换、Google Live 受限 token 浏览器 WebSocket 设置，以及带有伪麦克风媒体的 Gateway 网关中继浏览器适配器。该命令仅打印提供商状态，不记录密钥。 + 维护者实时冒烟测试：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 浏览器 WebRTC SDP 交换、Google Live 受限令牌浏览器 WebSocket 设置，以及带有模拟麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只打印提供商状态，不记录密钥。 - - - 点击 **停止**（调用 `chat.abort`）。 - - 当运行处于活跃状态时，普通后续消息会排队。点击排队消息上的 **引导**，可将该后续消息注入正在运行的轮次。 - - 输入 `/stop`（或独立的中止短语，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）以带外中止。 - - `chat.abort` 支持使用 `{ sessionKey }`（无 `runId`）中止该会话的所有活跃运行。 + + - 点击**停止**（调用 `chat.abort`）。 + - 运行处于活跃状态时，普通后续消息会排队。点击排队消息上的**引导**，可将该后续消息注入正在运行的轮次。 + - 输入 `/stop`（或独立的中止短语，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）可带外中止。 + - `chat.abort` 支持 `{ sessionKey }`（无 `runId`），用于中止该会话的所有活跃运行。 - 当运行被中止时，部分助手文本仍可显示在 UI 中。 - - 当存在已缓冲输出时，Gateway 网关会将中止的部分助手文本持久化到转录历史中。 - - 持久化条目包含中止元数据，使转录消费者能够区分中止部分内容和正常完成输出。 + - 当存在缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到转录历史记录中。 + - 持久化条目包含中止元数据，因此转录消费者可以区分中止部分内容和正常完成输出。 -## PWA 安装与 Web Push +## PWA 安装和 Web Push -控制 UI 随附 `manifest.webmanifest` 和 Service Worker，因此现代浏览器可以将其安装为独立 PWA。Web Push 可让 Gateway 网关通过通知唤醒已安装的 PWA，即使标签页或浏览器窗口未打开也是如此。 +Control UI 附带 `manifest.webmanifest` 和 service worker，因此现代浏览器可以将其安装为独立 PWA。Web Push 允许 Gateway 网关在标签页或浏览器窗口未打开时，通过通知唤醒已安装的 PWA。 | 表面 | 作用 | | ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | PWA manifest。浏览器在其可访问后会提供“安装应用”。 | -| `ui/public/sw.js` | 处理 `push` 事件和通知点击的 Service Worker。 | -| `push/vapid-keys.json`（位于 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于签名 Web Push 载荷。 | +| `ui/public/manifest.webmanifest` | PWA 清单。浏览器在它可访问后会提供“安装应用”。 | +| `ui/public/sw.js` | 处理 `push` 事件和通知点击的 service worker。 | +| `push/vapid-keys.json`（在 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于签名 Web Push 载荷。 | | `push/web-push-subscriptions.json` | 持久化的浏览器订阅端点。 | -如果想固定密钥（用于多主机部署、密钥轮换或测试），请通过 Gateway 网关进程上的环境变量覆盖 VAPID 密钥对： +当你想固定密钥（用于多主机部署、密钥轮换或测试）时，可以在 Gateway 网关进程上通过环境变量覆盖 VAPID 密钥对： - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` - `OPENCLAW_VAPID_SUBJECT`（默认为 `mailto:openclaw@localhost`） -控制 UI 使用这些受作用域限制的 Gateway 网关方法来注册和测试浏览器订阅： +Control UI 使用这些受作用域限制的 Gateway 网关方法来注册和测试浏览器订阅： -- `push.web.vapidPublicKey` — 获取活跃 VAPID 公钥。 +- `push.web.vapidPublicKey` — 获取活跃的 VAPID 公钥。 - `push.web.subscribe` — 注册一个 `endpoint` 以及 `keys.p256dh`/`keys.auth`。 - `push.web.unsubscribe` — 移除已注册的端点。 - `push.web.test` — 向调用方的订阅发送测试通知。 -Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参阅[配置](/zh-CN/gateway/configuration)）以及现有的 `push.test` 方法，后两者面向原生移动端配对。 +Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参阅[配置](/zh-CN/gateway/configuration)）以及现有的 `push.test` 方法，后者面向原生移动配对。 ## 托管嵌入 -助手消息可以使用 `[embed ...]` 短代码以内联方式渲染托管 Web 内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制： +助手消息可以使用 `[embed ...]` 短代码内联渲染托管的网页内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制： - 禁用托管嵌入内的脚本执行。 + 禁用托管嵌入中的脚本执行。 - 允许交互式嵌入，同时保持源隔离；这是默认设置，通常足以满足自包含浏览器游戏/小组件。 + 允许交互式嵌入，同时保持源隔离；这是默认值，通常足够用于自包含的浏览器游戏/小组件。 - 在 `allow-scripts` 基础上为有意需要更强权限的同站点文档添加 `allow-same-origin`。 + 在 `allow-scripts` 之上为有意需要更强权限的同站点文档添加 `allow-same-origin`。 @@ -246,15 +246,15 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 ``` -仅当嵌入文档确实需要同源行为时才使用 `trusted`。对于大多数由智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。 +仅在嵌入文档确实需要同源行为时使用 `trusted`。对于大多数智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。 -绝对外部 `http(s)` 嵌入 URL 默认仍会被阻止。如果你有意希望 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。 +默认情况下，绝对外部 `http(s)` 嵌入 URL 仍会被阻止。如果你确实想让 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。 ## Tailnet 访问（推荐） - + 将 Gateway 网关保留在 loopback 上，并让 Tailscale Serve 通过 HTTPS 代理它： ```bash @@ -265,16 +265,16 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 - `https:///`（或你配置的 `gateway.controlUi.basePath`） - 默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，控制 UI/WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行身份验证。OpenClaw 会通过使用 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与标头匹配来验证身份，并且仅在请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时接受这些身份。对于带有浏览器设备身份的控制 UI 操作者会话，此经过验证的 Serve 路径还会跳过设备配对往返；无设备浏览器和节点角色连接仍会遵循正常设备检查。如果你想即使对 Serve 流量也要求显式共享密钥凭据，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。 + 默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行身份验证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与标头匹配来验证身份，并且只有当请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时才会接受这些身份。对于带有浏览器设备身份的 Control UI 操作员会话，此已验证的 Serve 路径还会跳过设备配对往返；无设备浏览器和节点角色连接仍遵循正常设备检查。如果你想即使对 Serve 流量也要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。 - 对于该异步 Serve 身份路径，同一客户端 IP 和身份验证作用域的失败认证尝试会在写入速率限制之前被串行化。因此，来自同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配并行竞争。 + 对于该异步 Serve 身份路径，同一客户端 IP 和身份验证作用域的失败身份验证尝试会在写入速率限制前被串行化。因此，来自同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配并行竞争。 - 无 token 的 Serve 身份验证假定网关主机可信。如果不受信任的本地代码可能在该主机上运行，请要求 token/密码身份验证。 + 无令牌 Serve 身份验证假定 Gateway 网关主机可信。如果不受信任的本地代码可能在该主机上运行，请要求令牌/密码身份验证。 - + ```bash openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` @@ -290,18 +290,18 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 ## 不安全 HTTP -如果你通过纯 HTTP（`http://` 或 `http://`）打开仪表板，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的控制 UI 连接。 +如果你通过纯 HTTP（`http://` 或 `http://`）打开仪表盘，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。 -已记录的例外情况： +已记录的例外： -- 通过 `gateway.controlUi.allowInsecureAuth=true` 提供仅 localhost 的不安全 HTTP 兼容性 -- 通过 `gateway.auth.mode: "trusted-proxy"` 成功完成的操作者控制 UI 身份验证 -- 应急用 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- 通过 `gateway.controlUi.allowInsecureAuth=true` 提供的仅 localhost 不安全 HTTP 兼容性 +- 通过 `gateway.auth.mode: "trusted-proxy"` 成功进行操作员 Control UI 身份验证 +- 应急 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` -**推荐修复：** 使用 HTTPS（Tailscale Serve）或在本地打开 UI： +**推荐修复：**使用 HTTPS（Tailscale Serve）或在本地打开 UI： - `https:///`（Serve） -- `http://127.0.0.1:18789/`（在网关主机上） +- `http://127.0.0.1:18789/`（在 Gateway 网关主机上） @@ -315,14 +315,14 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 } ``` - `allowInsecureAuth` 只是本地兼容性开关： + `allowInsecureAuth` 只是一个本地兼容性开关： - - 它允许 localhost 控制 UI 会话在非安全 HTTP 上下文中无需设备身份即可继续。 + - 它允许 localhost Control UI 会话在非安全 HTTP 上下文中无需设备身份即可继续。 - 它不会绕过配对检查。 - 它不会放宽远程（非 localhost）设备身份要求。 - + ```json5 { gateway: { @@ -334,46 +334,46 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 ``` - `dangerouslyDisableDeviceAuth` 会禁用控制 UI 设备身份检查，是严重的安全降级。应急使用后请尽快恢复。 + `dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，是严重的安全降级。紧急使用后请尽快恢复。 - - - 成功的可信代理认证可以允许没有设备身份的**操作者**控制 UI 会话进入。 - - 这**不**适用于节点角色控制 UI 会话。 - - 同主机 loopback 反向代理仍然不满足可信代理认证；请参阅[可信代理认证](/zh-CN/gateway/trusted-proxy-auth)。 + + - 成功的受信任代理身份验证可以允许没有设备身份的 **operator** Control UI 会话进入。 + - 这**不会**扩展到 node-role Control UI 会话。 + - 同主机 loopback 反向代理仍然不满足受信任代理身份验证；请参阅[受信任代理身份验证](/zh-CN/gateway/trusted-proxy-auth)。 -请参阅 [Tailscale](/zh-CN/gateway/tailscale) 获取 HTTPS 设置指南。 +有关 HTTPS 设置指南，请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 ## 内容安全策略 -控制 UI 附带严格的 `img-src` 策略：只允许**同源**资源、`data:` URL，以及本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络获取。 +Control UI 附带严格的 `img-src` 策略：只允许**同源**资源、`data:` URL，以及本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络请求。 -这在实践中意味着： +实际含义如下： -- 通过相对路径提供的头像和图片（例如 `/avatars/`）仍会渲染，包括 UI 获取并转换为本地 `blob:` URL 的已认证头像路由。 -- 内联 `data:image/...` URL 仍会渲染（对协议内载荷很有用）。 -- 控制 UI 创建的本地 `blob:` URL 仍会渲染。 -- 渠道元数据发出的远程头像 URL 会在控制 UI 的头像辅助逻辑中被移除，并替换为内置徽标/徽章，因此被攻陷或恶意的渠道无法强制操作者浏览器获取任意远程图片。 +- 通过相对路径提供的头像和图片（例如 `/avatars/`）仍会渲染，包括 UI 获取并转换成本地 `blob:` URL 的已认证头像路由。 +- 内联 `data:image/...` URL 仍会渲染（适用于协议内载荷）。 +- Control UI 创建的本地 `blob:` URL 仍会渲染。 +- 渠道元数据发出的远程头像 URL 会在 Control UI 的头像辅助逻辑中被剥离，并替换为内置 logo/徽章，因此被攻破或恶意的渠道无法强制 operator 浏览器发起任意远程图片请求。 -你无需更改任何内容即可获得此行为 —— 它始终启用且不可配置。 +你不需要更改任何内容即可获得此行为——它始终启用且不可配置。 -## 头像路由认证 +## 头像路由身份验证 -配置 Gateway 网关认证后，控制 UI 头像端点需要与 API 其余部分相同的 Gateway 网关令牌： +配置 Gateway 网关身份验证后，Control UI 头像端点需要与 API 其余部分相同的 Gateway 网关令牌： -- `GET /avatar/` 仅向已认证调用方返回头像图片。`GET /avatar/?meta=1` 按同一规则返回头像元数据。 -- 对任一路由的未认证请求都会被拒绝（与相邻的 assistant-media 路由一致）。这可以防止头像路由在原本受保护的主机上泄露智能体身份。 -- 控制 UI 本身在获取头像时会将 Gateway 网关令牌作为 bearer 标头转发，并使用已认证的 blob URL，因此图片仍会在仪表板中渲染。 +- `GET /avatar/` 仅向已认证调用方返回头像图片。`GET /avatar/?meta=1` 按相同规则返回头像元数据。 +- 对任一路由的未认证请求都会被拒绝（与同级 assistant-media 路由一致）。这可以防止头像路由在其他方面受保护的主机上泄露智能体身份。 +- Control UI 本身在获取头像时会将 Gateway 网关令牌作为 bearer 标头转发，并使用已认证的 blob URL，因此图片仍会在仪表盘中渲染。 -如果你禁用 Gateway 网关认证（不建议在共享主机上这样做），头像路由也会与 Gateway 网关的其余部分一样变为未认证。 +如果你禁用 Gateway 网关身份验证（不建议在共享主机上这样做），头像路由也会变为未认证，这与 Gateway 网关的其余部分一致。 ## 构建 UI -Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建它们： +Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建： ```bash pnpm ui:build @@ -395,7 +395,7 @@ pnpm ui:dev ## 调试/测试：开发服务器 + 远程 Gateway 网关 -控制 UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 来源。当你想在本地使用 Vite 开发服务器，但 Gateway 网关在其他地方运行时，这很方便。 +Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 来源。当你希望在本地使用 Vite 开发服务器，而 Gateway 网关在其他位置运行时，这很方便。 @@ -408,7 +408,7 @@ pnpm ui:dev http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ``` - 可选的一次性认证（如需要）： + 可选的一次性身份验证（如果需要）： ```text http://localhost:5173/?gatewayUrl=wss%3A%2F%2F%3A18789#token= @@ -419,16 +419,16 @@ pnpm ui:dev - - `gatewayUrl` 会在加载后存储到 localStorage，并从 URL 中移除。 + - `gatewayUrl` 会在加载后存储到 localStorage 中，并从 URL 中移除。 - 如果你通过 `gatewayUrl` 传入完整的 `ws://` 或 `wss://` 端点，请对 `gatewayUrl` 值进行 URL 编码，以便浏览器正确解析查询字符串。 - - 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，这可以避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数仍会为了兼容性导入一次，但仅作为回退，并会在引导后立即移除。 + - 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，这可以避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数仍会为了兼容性导入一次，但仅作为备用方案，并会在引导后立即剥离。 - `password` 仅保存在内存中。 - - 设置 `gatewayUrl` 后，UI 不会回退到配置或环境凭据。请显式提供 `token`（或 `password`）。缺少显式凭据是错误。 - - 当 Gateway 网关位于 TLS 后面（Tailscale Serve、HTTPS 代理等）时，请使用 `wss://`。 - - `gatewayUrl` 只在顶层窗口中接受（不接受嵌入式窗口），以防止点击劫持。 - - 非 loopback 控制 UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整来源）。这包括远程开发设置。 - - Gateway 网关启动时可能会根据有效的运行时绑定地址和端口填充本地来源，例如 `http://localhost:` 和 `http://127.0.0.1:`，但远程浏览器来源仍需要显式条目。 - - 除了严格受控的本地测试外，不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任何浏览器来源，而不是“匹配我正在使用的任何主机”。 + - 设置 `gatewayUrl` 时，UI 不会回退到配置或环境凭据。请显式提供 `token`（或 `password`）。缺少显式凭据是错误。 + - 当 Gateway 网关位于 TLS 后面时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。 + - `gatewayUrl` 仅在顶层窗口中被接受（不能嵌入），以防止点击劫持。 + - 非 loopback Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整来源）。这包括远程开发设置。 + - Gateway 网关启动时可能会根据有效的运行时绑定和端口播种本地来源，例如 `http://localhost:` 和 `http://127.0.0.1:`，但远程浏览器来源仍需要显式条目。 + - 除了严格受控的本地测试，不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任何浏览器来源，而不是“匹配我正在使用的任何主机”。 - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头来源回退模式，但这是危险的安全模式。 @@ -448,9 +448,9 @@ pnpm ui:dev 远程访问设置详情：[远程访问](/zh-CN/gateway/remote)。 -## 相关内容 +## 相关 -- [仪表板](/zh-CN/web/dashboard) — Gateway 网关仪表板 +- [仪表盘](/zh-CN/web/dashboard) — Gateway 网关仪表盘 - [健康检查](/zh-CN/gateway/health) — Gateway 网关健康监控 - [TUI](/zh-CN/web/tui) — 终端用户界面 - [WebChat](/zh-CN/web/webchat) — 基于浏览器的聊天界面