diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 5933d0a3b..8e8300c8a 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,27 +1,27 @@ --- read_when: - - 设置 Slack 或调试 Slack 套接字/HTTP 模式 + - 设置 Slack 或调试 Slack socket/HTTP 模式 summary: Slack 设置和运行时行为（Socket 模式 + HTTP 请求 URL） title: Slack x-i18n: - generated_at: "2026-04-28T11:46:08Z" + generated_at: "2026-04-29T03:16:11Z" model: gpt-5.5 provider: openai - source_hash: 22e33ea77f81c7f1f79a26e73fd9341ec2d44f86620e8acf37e41eb70e8b7793 + source_hash: 4cad48c342c4edf0857d79264e5a3213e58b8f5cde6bd04fa11eca1c969a8f1a source_path: channels/slack.md workflow: 16 --- -可通过 Slack 应用集成，用于生产环境中的私信和渠道。默认模式是 Socket Mode；也支持 HTTP 请求 URL。 +可用于通过 Slack app 集成在私信和渠道中投入生产。默认模式为 Socket Mode；也支持 HTTP Request URLs。 - + Slack 私信默认使用配对模式。 - + 原生命令行为和命令目录。 - + 跨渠道诊断和修复手册。 @@ -29,19 +29,19 @@ x-i18n: ## 快速设置 - + - - 在 Slack 应用设置中按下 **[创建新应用](https://api.slack.com/apps/new)** 按钮： + + 在 Slack app 设置中点击 **[Create New App](https://api.slack.com/apps/new)** 按钮： - - 选择 **通过 manifest**，并为你的应用选择一个工作区 - - 粘贴下面的 [示例 manifest](#manifest-and-scope-checklist)，然后继续创建 - - 生成带有 `connections:write` 的 **App-Level Token**（`xapp-...`） - - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） + - 选择 **from a manifest**，并为你的 app 选择一个工作区 + - 粘贴下方的[示例 manifest](#manifest-and-scope-checklist)，然后继续创建 + - 生成具有 `connections:write` 的 **App-Level Token**（`xapp-...`） + - 安装 app，并复制显示的 **Bot Token**（`xoxb-...`） - + ```json5 { @@ -56,7 +56,7 @@ x-i18n: } ``` - 环境变量回退（仅默认账户）： + 环境变量回退（仅默认账号）： ```bash SLACK_APP_TOKEN=xapp-... @@ -65,7 +65,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -76,19 +76,19 @@ openclaw gateway - + - - 在 Slack 应用设置中按下 **[创建新应用](https://api.slack.com/apps/new)** 按钮： + + 在 Slack app 设置中点击 **[Create New App](https://api.slack.com/apps/new)** 按钮： - - 选择 **通过 manifest**，并为你的应用选择一个工作区 - - 粘贴 [示例 manifest](#manifest-and-scope-checklist)，并在创建前更新 URL + - 选择 **from a manifest**，并为你的 app 选择一个工作区 + - 粘贴[示例 manifest](#manifest-and-scope-checklist)，并在创建前更新 URL - 保存用于请求验证的 **Signing Secret** - - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） + - 安装 app，并复制显示的 **Bot Token**（`xoxb-...`） - + ```json5 { @@ -105,14 +105,14 @@ openclaw gateway ``` - 为多账户 HTTP 使用唯一的 webhook 路径 + 为多账号 HTTP 使用唯一的 webhook 路径 - 为每个账户提供不同的 `webhookPath`（默认 `/slack/events`），这样注册就不会冲突。 + 为每个账号提供不同的 `webhookPath`（默认 `/slack/events`），避免注册冲突。 - + ```bash openclaw gateway @@ -126,7 +126,7 @@ openclaw gateway ## Socket Mode 传输调优 -默认情况下，OpenClaw 会将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 秒。仅在需要针对工作区或主机进行特定调优时，才覆盖传输设置： +OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 秒。仅在需要针对工作区或主机进行特定调优时覆盖传输设置： ```json5 { @@ -143,11 +143,11 @@ openclaw gateway } ``` -仅对记录 Slack websocket pong/server-ping 超时，或运行在已知事件循环饥饿主机上的 Socket Mode 工作区使用此设置。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。应用消息和事件仍然是应用状态，而不是传输活跃性信号。 +仅当 Socket Mode 工作区记录 Slack websocket pong/server-ping 超时，或运行在已知存在事件循环饥饿问题的主机上时才使用此设置。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。App 消息和事件仍然是应用状态，而不是传输活性信号。 -## Manifest 和权限范围检查清单 +## Manifest 和 scope 清单 -基础 Slack 应用 manifest 对 Socket Mode 和 HTTP 请求 URL 相同。只有 `settings` 块（以及斜杠命令的 `url`）不同。 +基础 Slack app manifest 对 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 块（以及 slash command 的 `url`）不同。 基础 manifest（Socket Mode 默认）： @@ -221,7 +221,7 @@ openclaw gateway } ``` -对于 **HTTP 请求 URL 模式**，请将 `settings` 替换为 HTTP 变体，并为每个斜杠命令添加 `url`。需要公共 URL： +对于 **HTTP Request URLs 模式**，将 `settings` 替换为 HTTP 变体，并向每个 slash command 添加 `url`。需要公开 URL： ```json { @@ -253,20 +253,20 @@ openclaw gateway ### 其他 manifest 设置 -启用扩展上述默认设置的不同功能。 +呈现扩展上述默认设置的不同功能。 - + - 可以使用多个 [原生斜杠命令](#commands-and-slash-behavior)，而不是单个配置命令，并保留细粒度行为： + 可以使用多个[原生 slash command](#commands-and-slash-behavior) 来替代单个已配置命令，但需要注意细节： - - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令是保留命令。 - - 一次最多只能提供 25 个斜杠命令。 + - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令是保留的。 + - 一次最多只能提供 25 个 slash command。 - 将你现有的 `features.slash_commands` 部分替换为 [可用命令](/zh-CN/tools/slash-commands#command-list) 的子集： + 将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的一个子集： - + ```json "slash_commands": [ @@ -382,8 +382,8 @@ openclaw gateway ``` - - 使用与上方 Socket Mode 相同的 `slash_commands` 列表，并为每个条目添加 `"url": "https://gateway-host.example.com/slack/events"`。示例： + + 使用上方与 Socket Mode 相同的 `slash_commands` 列表，并向每个条目添加 `"url": "https://gateway-host.example.com/slack/events"`。示例： ```json "slash_commands": [ @@ -406,14 +406,14 @@ openclaw gateway - - 如果你想让传出消息使用活跃智能体身份（自定义用户名和图标），而不是默认 Slack 应用身份，请添加 `chat:write.customize` bot 权限范围。 + + 如果你希望传出消息使用活跃智能体身份（自定义用户名和图标），而不是默认 Slack app 身份，请添加 `chat:write.customize` bot scope。 - 如果你使用 emoji 图标，Slack 期望使用 `:emoji_name:` 语法。 + 如果使用 emoji 图标，Slack 需要 `:emoji_name:` 语法。 - - 如果你配置 `channels.slack.userToken`，典型读取权限范围是： + + 如果你配置了 `channels.slack.userToken`，典型的读取 scope 为： - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -426,15 +426,14 @@ openclaw gateway -## 令牌模型 +## Token 模型 - Socket Mode 需要 `botToken` + `appToken`。 - HTTP 模式需要 `botToken` + `signingSecret`。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 - 字符串或 SecretRef 对象。 -- 配置令牌会覆盖环境变量回退。 -- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账户。 -- `userToken`（`xoxp-...`）只能通过配置设置（没有环境变量回退），并默认使用只读行为（`userTokenReadOnly: true`）。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 +- 配置 token 会覆盖环境变量回退。 +- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账号。 +- `userToken`（`xoxp-...`）仅可通过配置设置（没有环境变量回退），并且默认使用只读行为（`userTokenReadOnly: true`）。 Status 快照行为： @@ -445,10 +444,10 @@ Status 快照行为： 或其他非内联密钥来源配置，但当前命令/运行时路径 无法解析实际值。 - 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下， - 必需的配对是 `botTokenStatus` + `appTokenStatus`。 + 必需的组合是 `botTokenStatus` + `appTokenStatus`。 -对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍然优先使用机器人令牌；只有当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。 +对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；仅当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许使用用户令牌写入。 ## 操作和门控 @@ -465,12 +464,12 @@ Slack 操作由 `channels.slack.actions.*` 控制。 | memberInfo | 启用 | | emojiList | 启用 | -当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图片返回图片预览，或为其他文件类型返回本地文件元数据。 +当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图片返回图片预览，为其他文件类型返回本地文件元数据。 ## 访问控制和路由 - + `channels.slack.dmPolicy` 控制私信访问（旧版：`channels.slack.dm.policy`）： - `pairing`（默认） @@ -483,48 +482,48 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `dm.enabled`（默认 true） - `channels.slack.allowFrom`（首选） - `dm.allowFrom`（旧版） - - `dm.groupEnabled`（群组私信默认为 false） + - `dm.groupEnabled`（群组私信默认 false） - `dm.groupChannels`（可选 MPIM 允许列表） 多账户优先级： - - `channels.slack.accounts.default.allowFrom` 只应用于 `default` 账户。 - - 命名账户在其自身的 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。 + - `channels.slack.accounts.default.allowFrom` 仅应用于 `default` 账户。 + - 命名账户在自己的 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。 - 命名账户不会继承 `channels.slack.accounts.default.allowFrom`。 私信中的配对使用 `openclaw pairing approve slack `。 - + `channels.slack.groupPolicy` 控制渠道处理： - `open` - `allowlist` - `disabled` - 渠道允许列表位于 `channels.slack.channels` 下，并且应使用稳定的渠道 ID。 + 渠道允许列表位于 `channels.slack.channels` 下，并应使用稳定的渠道 ID。 - 运行时注意事项：如果完全缺失 `channels.slack`（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使设置了 `channels.defaults.groupPolicy`）。 + 运行时说明：如果完全缺少 `channels.slack`（仅环境配置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使已设置 `channels.defaults.groupPolicy`）。 名称/ID 解析： - - 渠道允许列表条目和私信允许列表条目会在启动时解析，前提是令牌访问权限允许 - - 未解析的渠道名称条目会按配置保留，但默认情况下会被路由忽略 + - 当令牌访问允许时，渠道允许列表条目和私信允许列表条目会在启动时解析 + - 未解析的渠道名称条目会按配置保留，但默认会在路由时被忽略 - 入站授权和渠道路由默认优先使用 ID；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true` - + 渠道消息默认由提及门控。 提及来源： - 显式应用提及（`<@botId>`） - - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 提及正则表达式模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） - 每个渠道控制项（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 使用）： + 按渠道控制（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 使用）： - `requireMention` - `users`（允许列表） @@ -533,7 +532,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `systemPrompt` - `tools`、`toolsBySender` - `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符 - （旧版无前缀键仍然只映射到 `id:`） + （旧版无前缀键仍仅映射到 `id:`） @@ -543,15 +542,15 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。 - 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。 - 渠道会话：`agent::slack:channel:`。 -- 线程回复在适用时可以创建线程会话后缀（`:thread:`）。 -- `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。 -- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时获取多少条现有线程消息（默认 `20`；设置为 `0` 可禁用）。 -- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，抑制隐式线程提及，使机器人在线程内只响应显式 `@bot` 提及，即使机器人已经参与该线程。否则，机器人已参与线程中的回复会绕过 `requireMention` 门控。 +- 适用时，线程回复可以创建线程会话后缀（`:thread:`）。 +- `channels.slack.thread.historyScope` 默认值为 `thread`；`thread.inheritParent` 默认值为 `false`。 +- `channels.slack.thread.initialHistoryLimit` 控制新线程会话开始时获取多少条现有线程消息（默认 `20`；设为 `0` 可禁用）。 +- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，抑制隐式线程提及，因此机器人只会响应线程内显式 `@bot` 提及，即使机器人已参与该线程。没有此设置时，机器人参与过的线程中的回复会绕过 `requireMention` 门控。 -回复线程控制项： +回复线程控制： - `channels.slack.replyToMode`：`off|first|all|batched`（默认 `off`） -- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 设置 +- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` - 直接聊天的旧版回退：`channels.slack.dm.replyToMode` 支持手动回复标签： @@ -560,10 +559,10 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `[[reply_to:]]` -`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同，Telegram 在 `"off"` 模式下仍然会遵循显式标签。Slack 线程会在渠道中隐藏消息，而 Telegram 回复会保持内联可见。 +`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同，后者在 `"off"` 模式下仍会遵循显式标签。Slack 线程会在渠道中隐藏消息，而 Telegram 回复会以内联方式保持可见。 -## 确认反应 +## 确认表情反应 `ackReaction` 会在 OpenClaw 处理入站消息时发送确认表情符号。 @@ -574,10 +573,10 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `messages.ackReaction` - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） -注意事项： +说明： -- Slack 需要短代码（例如 `"eyes"`）。 -- 使用 `""` 可为 Slack 账户或全局禁用该反应。 +- Slack 期望使用短代码（例如 `"eyes"`）。 +- 使用 `""` 可为 Slack 账户或全局禁用该表情反应。 ## 文本流式传输 @@ -586,17 +585,17 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `off`：禁用实时预览流式传输。 - `partial`（默认）：用最新的部分输出替换预览文本。 - `block`：追加分块预览更新。 -- `progress`：生成时显示进度状态文本，然后发送最终文本。 -- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一条已编辑的预览消息中（默认：`true`）。设置为 `false` 可保留单独的工具/进度消息。 +- `progress`：生成时显示进度 Status 文本，然后发送最终文本。 +- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一条已编辑的预览消息（默认：`true`）。设为 `false` 可保留单独的工具/进度消息。 当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。 -- 必须有可用的回复线程，原生文本流式传输和 Slack 助手线程状态才会显示。线程选择仍然遵循 `replyToMode`。 -- 当原生流式传输不可用时，渠道和群聊根消息仍可以使用普通草稿预览。 -- 顶层 Slack 私信默认保持在线程外，因此不会显示线程样式预览；如果你希望在那里显示可见进度，请使用线程回复或 `typingReaction`。 -- 媒体和非文本负载会回退到普通投递。 -- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息只有在可以就地编辑预览时才会刷新。 -- 如果流式传输在回复中途失败，OpenClaw 会对剩余负载回退到普通投递。 +- 必须有可用的回复线程，原生文本流式传输和 Slack 助手线程 Status 才会显示。线程选择仍遵循 `replyToMode`。 +- 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。 +- 顶层 Slack 私信默认不在线程中，因此不会显示线程样式预览；如果你希望在那里显示可见进度，请使用线程回复或 `typingReaction`。 +- 媒体和非文本载荷会回退到普通投递。 +- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在可以原地编辑预览时刷新。 +- 如果流式传输在回复中途失败，OpenClaw 会对剩余载荷回退到普通投递。 使用草稿预览而不是 Slack 原生文本流式传输： @@ -619,54 +618,54 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 - 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。 -## 输入反应回退 +## 输入状态表情反应回退 -`typingReaction` 会在 OpenClaw 处理回复时向入站 Slack 消息添加临时反应，并在运行结束时移除它。这在线程回复之外最有用，因为线程回复会使用默认的 “is typing...” 状态指示器。 +`typingReaction` 会在 OpenClaw 处理回复时向入站 Slack 消息添加一个临时表情反应，并在运行结束时移除它。这在非线程回复中最有用，因为线程回复会使用默认的 “is typing...” Status 指示器。 解析顺序： - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` -注意事项： +说明： -- Slack 需要短代码（例如 `"hourglass_flowing_sand"`）。 -- 该反应是尽力而为的，回复或失败路径完成后会自动尝试清理。 +- Slack 期望使用短代码（例如 `"hourglass_flowing_sand"`）。 +- 表情反应是尽力而为的，并会在回复或失败路径完成后自动尝试清理。 ## 媒体、分块和投递 - - Slack 文件附件会从 Slack 托管的私有 URL 下载（令牌认证请求流），并在抓取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以用 `download-file` 获取原始文件。 + + Slack 文件附件会从 Slack 托管的私有 URL 下载（令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以使用 `download-file` 获取原始文件。 - 下载使用有界空闲超时和总超时。如果 Slack 文件检索卡住或失败，OpenClaw 会继续处理消息，并回退到文件占位符。 + 下载使用有界空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息并回退到文件占位符。 - 运行时入站大小上限默认为 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆盖。 + 除非由 `channels.slack.mediaMaxMb` 覆盖，运行时入站大小上限默认为 `20MB`。 - - - 文本块使用 `channels.slack.textChunkLimit`（默认 4000） - - `channels.slack.chunkMode="newline"` 启用段落优先拆分 - - 文件发送使用 Slack 上传 API，并且可以包含线程回复（`thread_ts`） - - 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则渠道发送会使用媒体管道中的 MIME 类型默认值 + + - 文本分块使用 `channels.slack.textChunkLimit`（默认 4000） + - `channels.slack.chunkMode="newline"` 启用优先按段落拆分 + - 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`） + - 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送会使用媒体管道中的 MIME 类型默认值 - + 首选显式目标： - `user:` 用于私信 - `channel:` 用于渠道 - 发送到用户目标时，会通过 Slack conversation API 打开 Slack 私信。 + 发送到用户目标时，Slack 私信会通过 Slack conversation API 打开。 ## 命令和斜杠行为 -斜杠命令在 Slack 中显示为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： +斜杠命令在 Slack 中会显示为一个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： - `enabled: false` - `name: "openclaw"` @@ -677,17 +676,17 @@ Slack 操作由 `channels.slack.actions.*` 控制。 /openclaw /help ``` -原生命令需要在你的 Slack 应用中配置[额外 manifest 设置](#additional-manifest-settings)，并改用 `channels.slack.commands.native: true` 启用，或在全局配置中使用 `commands.native: true` 启用。 +原生命令需要在你的 Slack 应用中配置[额外清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 启用，或在全局配置中改用 `commands.native: true` 启用。 -- Slack 的原生命令自动模式为**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 +- 对 Slack 而言，原生命令自动模式为**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 ```txt /help ``` -原生参数菜单使用自适应渲染策略，在分派所选选项值前显示确认模态框： +原生参数菜单使用自适应渲染策略，在分派所选选项值之前显示确认模态框： -- 最多 5 个选项：按钮区块 +- 最多 5 个选项：按钮块 - 6-100 个选项：静态选择菜单 - 超过 100 个选项：当交互选项处理器可用时，使用带异步选项过滤的外部选择 - 超出 Slack 限制：编码后的选项值回退为按钮 @@ -734,29 +733,30 @@ Slack 可以渲染智能体编写的交互式回复控件，但此功能默认 } ``` -启用后，智能体可以发出仅 Slack 可用的回复指令： +启用后，智能体可以发出仅适用于 Slack 的回复指令： - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -这些指令会编译为 Slack Block Kit，并通过现有 Slack 交互事件路径路由点击或选择。 +这些指令会编译为 Slack Block Kit，并通过现有 Slack 交互事件路径将点击或选择路由回来。 -注意事项： +说明： -- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令转换为自己的按钮系统。 -- 交互式回调值是 OpenClaw 生成的不透明令牌，而不是原始由智能体编写的值。 +- 这是 Slack 专用 UI。其他渠道不会把 Slack Block Kit 指令转换成自己的按钮系统。 +- 交互式回调值是 OpenClaw 生成的不透明令牌，不是智能体编写的原始值。 - 如果生成的交互式块会超出 Slack Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的 blocks 负载。 -## Slack 中的 Exec 批准 +## Slack 中的执行审批 -Slack 可以作为带有交互式按钮和交互的原生批准客户端，而不是回退到 Web UI 或终端。 +Slack 可以通过交互式按钮和交互作为原生审批客户端，而不是回退到 Web 界面或终端。 -- Exec 批准使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 -- 当请求已经落到 Slack 中且批准 id 类型为 `plugin:` 时，插件批准仍可通过同一个 Slack 原生按钮界面完成。 -- 仍会强制执行批准者授权：只有被识别为批准者的用户才能通过 Slack 批准或拒绝请求。 +- 执行审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 +- 当请求已进入 Slack 且审批 ID 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面完成。 +- 审批者授权仍会强制执行：只有被识别为审批者的用户才能通过 Slack 批准或拒绝请求。 -这使用与其他渠道相同的共享批准按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，批准提示会直接在对话中渲染为 Block Kit 按钮。 -当这些按钮存在时，它们就是主要的批准 UX；只有当工具结果表明聊天批准不可用，或手动批准是唯一路径时，OpenClaw +这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用 `interactivity` 时，审批提示会直接在对话中呈现为 Block Kit 按钮。 +当这些按钮存在时，它们就是主要审批 UX；只有当工具结果说明聊天 +审批不可用，或手动审批是唯一路径时，OpenClaw 才应包含手动 `/approve` 命令。 配置路径： @@ -766,10 +766,11 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 - `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter` -当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个批准者时，Slack 会自动启用原生 exec 批准。设置 `enabled: false` 可明确禁用 Slack 作为原生批准客户端。 -设置 `enabled: true` 可在能解析出批准者时强制启用原生批准。 +当 `enabled` 未设置或为 `"auto"` 且至少解析出一个 +审批者时，Slack 会自动启用原生执行审批。设置 `enabled: false` 可明确禁用 Slack 作为原生审批客户端。 +设置 `enabled: true` 可在解析出审批者时强制启用原生审批。 -没有显式 Slack exec 批准配置时的默认行为： +没有显式 Slack 执行审批配置时的默认行为： ```json5 { @@ -779,7 +780,7 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 } ``` -只有当你想覆盖批准者、添加过滤器，或 +只有当你要覆盖审批者、添加过滤器，或 选择启用来源聊天投递时，才需要显式 Slack 原生配置： ```json5 @@ -796,24 +797,24 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 } ``` -共享 `approvals.exec` 转发是独立的。仅当 exec 批准提示还必须 +共享 `approvals.exec` 转发是独立的。仅当执行审批提示还必须 路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是 -独立的；当这些请求已经落到 Slack 中时，Slack 原生按钮仍可完成插件批准。 +独立的；当这些请求已进入 Slack 时，Slack 原生按钮仍可完成插件审批。 -同聊天 `/approve` 也可在已支持命令的 Slack 渠道和私信中使用。完整批准转发模型请参阅 [Exec 批准](/zh-CN/tools/exec-approvals)。 +同聊天 `/approve` 也可在已支持命令的 Slack 渠道和私信中使用。查看[执行审批](/zh-CN/tools/exec-approvals)了解完整审批转发模型。 -## 事件和运行行为 +## 事件和运维行为 - 消息编辑/删除会映射为系统事件。 -- 线程广播（“Also send to channel” 线程回复）会作为普通用户消息处理。 -- 表情反应添加/移除事件会映射为系统事件。 +- 线程广播（“同时发送到频道”的线程回复）会按普通用户消息处理。 +- 添加/移除回应事件会映射为系统事件。 - 成员加入/离开、渠道创建/重命名，以及置顶添加/移除事件会映射为系统事件。 - 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。 -- 渠道 topic/purpose 元数据会被视为不可信上下文，并且可注入到路由上下文中。 -- 适用时，线程发起消息和初始线程历史上下文种子会按已配置的发送者允许列表过滤。 -- Block actions 和 modal 交互会发出结构化的 `Slack interaction: ...` 系统事件，并带有丰富的负载字段： - - block actions：已选择的值、标签、选择器值和 `workflow_*` 元数据 - - modal `view_submission` 和 `view_closed` 事件，包含已路由渠道元数据和表单输入 +- 渠道主题/用途元数据会被视为不受信任的上下文，并可注入路由上下文。 +- 适用时，线程起始消息和初始线程历史上下文种子会按配置的发送者允许列表过滤。 +- 块操作和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并包含丰富的负载字段： + - 块操作：选定值、标签、选择器值和 `workflow_*` 元数据 + - 模态 `view_submission` 和 `view_closed` 事件，包含路由的渠道元数据和表单输入 ## 配置参考 @@ -821,9 +822,9 @@ Slack 可以作为带有交互式按钮和交互的原生批准客户端，而 -- mode/auth：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` +- 模式/认证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` - 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels` -- 兼容性开关：`dangerouslyAllowNameMatching`（紧急破窗；除非需要，否则保持关闭） +- 兼容性开关：`dangerouslyAllowNameMatching`（应急；除非需要，否则保持关闭） - 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention` - 线程/历史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` - 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress` @@ -857,9 +858,9 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy`（或旧版 `channels.slack.dm.policy`） - - 配对批准 / 允许列表条目 + - 配对审批 / 允许列表条目 - Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志 - 通常表示 Slack 发送了一个已编辑的 Assistant 线程事件，但消息元数据中 + 通常意味着 Slack 发送了一个已编辑的 Assistant 线程事件，但消息元数据中 没有可恢复的人类发送者 ```bash @@ -869,56 +870,120 @@ openclaw pairing list slack - 在 Slack 应用设置中验证 bot + app token 以及 Socket Mode 是否已启用。 + 在 Slack 应用设置中验证 bot + app 令牌以及 Socket Mode 启用状态。 如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或 - `appTokenStatus: "configured_unavailable"`，则 Slack 账号 - 已配置，但当前运行时无法解析由 SecretRef 支持的 - 值。 + `appTokenStatus: "configured_unavailable"`，表示 Slack 账户已配置， + 但当前运行时无法解析由 SecretRef 支持的值。 - + 验证： - - signing secret - - webhook path + - 签名密钥 + - webhook 路径 - Slack Request URLs（Events + Interactivity + Slash Commands） - - 每个 HTTP 账号使用唯一的 `webhookPath` + - 每个 HTTP 账户唯一的 `webhookPath` - 如果账号快照中出现 `signingSecretStatus: "configured_unavailable"`， - 则 HTTP 账号已配置，但当前运行时无法 - 解析由 SecretRef 支持的 signing secret。 + 如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`， + 表示 HTTP 账户已配置，但当前运行时无法 + 解析由 SecretRef 支持的签名密钥。 - - 验证你想要的是： + + 确认你想要的是： - - 原生命令模式（`channels.slack.commands.native: true`），并已在 Slack 中注册匹配的 slash commands - - 或单一 slash command 模式（`channels.slack.slashCommand.enabled: true`） + - 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册了匹配的斜杠命令 + - 或单一斜杠命令模式（`channels.slack.slashCommand.enabled: true`） - 还要检查 `commands.useAccessGroups` 以及渠道/用户允许列表。 + 还要检查 `commands.useAccessGroups` 和渠道/用户允许列表。 -## 相关 +## 附件视觉参考 + +当 Slack 文件下载成功且大小限制允许时，Slack 可以把已下载的媒体附加到智能体轮次。图像文件可以通过媒体理解路径传递，或直接传给支持视觉的回复模型；其他文件会作为可下载文件上下文保留，而不是作为图像输入处理。 + +### 支持的媒体类型 + +| 媒体类型 | 来源 | 当前行为 | 备注 | +| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| JPEG / PNG / GIF / WebP 图像 | Slack 文件 URL | 下载并附加到轮次，以便进行支持视觉的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） | +| PDF 文件 | Slack 文件 URL | 下载并作为文件上下文暴露给 `download-file` 或 `pdf` 等工具 | Slack 入站不会自动把 PDF 转换为图像视觉输入 | +| 其他文件 | Slack 文件 URL | 可行时下载，并作为文件上下文暴露 | 二进制文件不会作为图像输入处理 | +| 线程回复 | 线程起始消息文件 | 当回复没有直接媒体时，根消息文件可作为上下文补充 | 仅文件起始消息使用附件占位符 | +| 多图像消息 | 多个 Slack 文件 | 每个文件都会独立评估 | Slack 处理限制为每条消息最多八个文件 | + +### 入站管线 + +当带有文件附件的 Slack 消息到达时： + +1. OpenClaw 使用 bot 令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。 +2. 成功后，文件会写入媒体存储。 +3. 已下载媒体路径和内容类型会添加到入站上下文。 +4. 支持图像的模型/工具路径可以使用该上下文中的图像附件。 +5. 非图像文件仍可作为文件元数据或媒体引用，供能够处理它们的工具使用。 + +### 线程根附件继承 + +当消息在线程中到达时（有 `thread_ts` 父级）： + +- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以把根文件补充为线程起始上下文。 +- 直接回复附件优先于根消息附件。 +- 只有文件而没有文本的根消息会用附件占位符表示，以便回退仍可包含其文件。 + +### 多附件处理 + +当单条 Slack 消息包含多个文件附件时： + +- 每个附件都会通过媒体管线独立处理。 +- 已下载媒体引用会聚合进消息上下文。 +- 处理顺序遵循事件负载中的 Slack 文件顺序。 +- 一个附件下载失败不会阻塞其他附件。 + +### 大小、下载和模型限制 + +- **大小上限**：默认每个文件 20 MB。可通过 `channels.slack.mediaMaxMb` 配置。 +- **下载失败**：Slack 无法提供的文件、过期 URL、不可访问文件、超大文件，以及 Slack 认证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。 +- **视觉模型**：图像分析会在活动回复模型支持视觉时使用该模型，或使用 `agents.defaults.imageModel` 配置的图像模型。 + +### 已知限制 + +| 场景 | 当前行为 | 解决方法 | +| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | +| 过期的 Slack 文件 URL | 文件被跳过；不显示错误 | 在 Slack 中重新上传文件 | +| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用支持视觉的回复模型 | +| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，增大 `channels.slack.mediaMaxMb` | +| 转发/共享附件 | 文本和 Slack 托管的图像/文件媒体按尽力而为处理 | 直接在 OpenClaw 线程中重新共享 | +| PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉路由 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 | + +### 相关文档 + +- [媒体理解流水线](/zh-CN/nodes/media-understanding) +- [PDF 工具](/zh-CN/tools/pdf) +- 史诗任务：[#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件视觉启用 +- 回归测试：[#51353](https://github.com/openclaw/openclaw/issues/51353) +- 实时验证：[#51354](https://github.com/openclaw/openclaw/issues/51354) + +## 相关内容 - - 将 Slack 用户配对到 Gateway 网关。 + + 将 Slack 用户与 Gateway 网关配对。 - + 渠道和群组私信行为。 - + 将入站消息路由到智能体。 - + 威胁模型和加固。 - + 配置布局和优先级。 diff --git a/docs/zh-CN/web/control-ui.md b/docs/zh-CN/web/control-ui.md index d507b71e8..d29c7a271 100644 --- a/docs/zh-CN/web/control-ui.md +++ b/docs/zh-CN/web/control-ui.md @@ -1,46 +1,46 @@ --- read_when: - - 你想从浏览器操作 Gateway 网关 + - 你想通过浏览器操作 Gateway 网关 - 你希望无需 SSH 隧道即可访问 Tailnet sidebarTitle: Control UI -summary: 用于 Gateway 网关的基于浏览器的控制 UI（聊天、节点、配置） -title: 控制 UI +summary: 基于浏览器的 Gateway 网关控制 UI（聊天、节点、配置） +title: 控制界面 x-i18n: - generated_at: "2026-04-28T12:07:07Z" + generated_at: "2026-04-29T03:16:15Z" model: gpt-5.5 provider: openai - source_hash: 1ebfb9ade82821cfb1fbbb15cea95e23581856d8eafa87bd43883ebf699819c9 + source_hash: 4e8b3d8b346748a6fb1112d7c6e53e8ca7a87d1d974fcd44772997393c395c08 source_path: web/control-ui.md workflow: 16 --- -控制 UI 是一个小型 **Vite + Lit** 单页应用，由 Gateway 网关提供服务： +Control UI 是由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用： -- 默认：`http://:18789/` +- 默认值：`http://:18789/` - 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`） -它在同一端口上**直接与 Gateway 网关 WebSocket** 通信。 +它会在同一端口上**直接与 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`。 +如果页面加载失败，请先启动 Gateway 网关：`openclaw gateway`。 -认证会在 WebSocket 握手期间通过以下方式提供： +凭证会在 WebSocket 握手期间通过以下方式提供： - `connect.params.auth.token` - `connect.params.auth.password` - 当 `gateway.auth.allowTailscale: true` 时的 Tailscale Serve 身份标头 -- 当 `gateway.auth.mode: "trusted-proxy"` 时的 trusted-proxy 身份标头 +- 当 `gateway.auth.mode: "trusted-proxy"` 时的可信代理身份标头 -仪表板设置面板会为当前浏览器标签页会话和选中的 Gateway 网关 URL 保存一个令牌；密码不会被持久化。新手引导通常会在首次连接时为共享密钥认证生成 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，密码认证也可用。 +仪表板设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保留一个令牌；密码不会被持久化。新手引导通常会在首次连接时为共享密钥凭证生成 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，也可以使用密码凭证。 ## 设备配对（首次连接） -当你从新的浏览器或设备连接到控制 UI 时，Gateway 网关通常会要求**一次性配对批准**。这是一项安全措施，用于防止未经授权的访问。 +当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关通常会要求**一次性配对批准**。这是一项安全措施，用于防止未经授权的访问。 **你会看到：**“disconnected (1008): pairing required” @@ -57,94 +57,94 @@ x-i18n: -如果浏览器使用变更后的认证详情（角色/作用域/公钥）重试配对，之前的待处理请求会被取代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。 +如果浏览器使用变更后的凭证详细信息（角色/作用域/公钥）重试配对，之前待处理的请求会被取代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。 -如果浏览器已经配对，而你将它从读取访问改为写入/管理员访问，这会被视为批准升级，而不是静默重新连接。OpenClaw 会保留旧批准处于活动状态，阻止范围更广的重新连接，并要求你明确批准新的作用域集合。 +如果浏览器已经配对，而你将它从读取访问权限改为写入/管理员访问权限，这会被视为批准升级，而不是静默重连。OpenClaw 会保持旧批准有效，阻止权限更大的重连，并要求你明确批准新的作用域集合。 -批准后，设备会被记住，除非你使用 `openclaw devices revoke --device --role ` 撤销它，否则无需重新批准。有关令牌轮换和撤销，请参阅[设备 CLI](/zh-CN/cli/devices)。 +批准后，该设备会被记住，并且不再需要重新批准，除非你使用 `openclaw devices revoke --device --role ` 撤销它。请参阅 [Devices CLI](/zh-CN/cli/devices) 了解令牌轮换和撤销。 - 直接的 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动批准。 -- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过且浏览器出示其设备身份时，Tailscale Serve 可以为控制 UI 操作员会话跳过配对往返。 -- 直接 Tailnet 绑定、LAN 浏览器连接，以及没有设备身份的浏览器配置文件仍然需要明确批准。 +- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过，并且浏览器提供其设备身份时，Tailscale Serve 可以为 Control UI 操作员会话跳过配对往返。 +- 直接的 Tailnet 绑定、LAN 浏览器连接，以及没有设备身份的浏览器配置文件仍然需要显式批准。 - 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据将需要重新配对。 ## 个人身份（浏览器本地） -控制 UI 支持按浏览器设置的个人身份（显示名称和头像），该身份会附加到传出消息上，用于在共享会话中归属发言。它存储在浏览器存储中，作用域限定于当前浏览器配置文件，不会同步到其他设备，也不会在服务端持久化，除了你实际发送的消息上正常的转录作者元数据。清除站点数据或切换浏览器会将其重置为空。 +Control UI 支持按浏览器设置个人身份（显示名称和头像），并将其附加到传出消息，用于在共享会话中标注归属。它存储在浏览器存储中，作用域限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务器端持久化，除了你实际发送的消息上正常的转录作者元数据。清除站点数据或切换浏览器会将其重置为空。 -同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖 Gateway 网关解析出的身份，绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍然可供直接写入该字段的非 UI 客户端使用（例如脚本化 Gateway 网关或自定义仪表板）。 +同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖由 Gateway 网关解析出的身份，并且绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍可供直接写入该字段的非 UI 客户端使用（例如脚本化 Gateway 网关或自定义仪表板）。 ## 运行时配置端点 -控制 UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点与 HTTP 表面的其余部分一样受同一 Gateway 网关认证保护：未经认证的浏览器无法获取它；成功获取需要已有有效的 Gateway 网关令牌/密码、Tailscale Serve 身份，或 trusted-proxy 身份。 +Control UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点受到与其余 HTTP 表面相同的 Gateway 网关凭证保护：未经身份验证的浏览器无法获取它，成功获取需要已有有效的 Gateway 网关令牌/密码、Tailscale Serve 身份，或可信代理身份。 ## 语言支持 -控制 UI 可以在首次加载时根据你的浏览器区域设置进行本地化。若要之后覆盖设置，请打开 **Overview -> Gateway Access -> Language**。区域设置选择器位于 Gateway Access 卡片中，而不是 Appearance 下。 +Control UI 可以在首次加载时根据你的浏览器区域设置进行本地化。若要稍后覆盖它，请打开 **Overview -> Gateway Access -> Language**。区域设置选择器位于 Gateway Access 卡片中，而不是 Appearance 下。 - 支持的区域设置：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`tr`、`uk`、`id`、`pl`、`th` - 非英语翻译会在浏览器中延迟加载。 -- 选中的区域设置会保存在浏览器存储中，并在以后访问时复用。 +- 所选区域设置会保存在浏览器存储中，并在后续访问时复用。 - 缺失的翻译键会回退到英语。 ## 外观主题 -Appearance 面板保留内置的 Claw、Knot 和 Dash 主题，外加一个浏览器本地 tweakcn 导入槽。要导入主题，请打开 [tweakcn 主题](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` 等默认主题名称。 +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` 等默认主题名称。 -导入的主题只会存储在当前浏览器配置文件中。它们不会写入 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 模型。 - - 在聊天中流式传输工具调用和实时工具输出卡片（智能体事件）。 + - 通过浏览器实时会话进行语音对话。OpenAI 使用直接 WebRTC，Google Live 通过 WebSocket 使用受限的一次性浏览器令牌，而仅后端的实时语音插件使用 Gateway 网关中继传输。中继会将提供商凭据保留在 Gateway 网关上，同时浏览器通过 `talk.realtime.relay*` RPC 流式传输麦克风 PCM，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用发回给配置的更大的 OpenClaw 模型。 + - 在 Chat 中流式传输工具调用和实时工具输出卡片（智能体事件）。 - - - 渠道：内置渠道以及内置/外部插件渠道的状态、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。 - - 实例：在线列表 + 刷新（`system-presence`）。 - - 会话：列表 + 按会话设置模型/thinking/fast/verbose/trace/reasoning 覆盖（`sessions.list`、`sessions.patch`）。 - - 梦境：Dreaming 状态、启用/禁用开关，以及 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。 + + - 渠道：内置渠道以及内置/外部插件渠道 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`）。 - - - Cron 作业：列出/添加/编辑/运行/启用/禁用 + 运行历史（`cron.*`）。 - - Skills：状态、启用/禁用、安装、API 密钥更新（`skills.*`）。 - - 节点：列表 + 能力（`node.list`）。 - - 执行批准：编辑 Gateway 网关或节点允许列表 + `exec host=gateway/node` 的询问策略（`exec.approvals.*`）。 + + - Cron 作业：列出/添加/编辑/运行/启用/禁用，以及运行历史（`cron.*`）。 + - Skills：Status、启用/禁用、安装、API 密钥更新（`skills.*`）。 + - 节点：列表和能力（`node.list`）。 + - Exec 批准：编辑 Gateway 网关或节点允许列表，以及 `exec host=gateway/node` 的询问策略（`exec.approvals.*`）。 - 查看/编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。 - - 通过验证应用 + 重启（`config.apply`），并唤醒最后一个活动会话。 - - 写入包含 base-hash 防护，以防覆盖并发编辑。 + - 通过验证应用并重启（`config.apply`），并唤醒上一个活动会话。 + - 写入包含基准哈希保护，防止覆盖并发编辑。 - 写入（`config.set`/`config.apply`/`config.patch`）会对提交的配置载荷中的引用预检活动 SecretRef 解析；未解析的活动提交引用会在写入前被拒绝。 - - Schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；只有当快照可以安全进行原始往返时，Raw JSON 编辑器才可用。 - - 如果快照无法安全地往返原始文本，控制 UI 会强制使用表单模式，并对该快照禁用原始模式。 - - Raw JSON 编辑器的“Reset to saved”会保留原始编写的形态（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此当快照可以安全往返时，外部编辑会在重置后保留下来。 + - Schema 和表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件和渠道 schema）；只有当快照具有安全的原始往返能力时，Raw JSON 编辑器才可用。 + - 如果快照无法安全地往返原始文本，Control UI 会强制使用 Form 模式，并为该快照禁用 Raw 模式。 + - Raw JSON 编辑器中的“Reset to saved”会保留原始编写的形状（格式、注释、`$include` 布局），而不是重新渲染展平的快照，因此当快照可以安全往返时，外部编辑会在重置后保留下来。 - 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，以防意外发生对象到字符串的损坏。 - - 调试：状态/健康/模型快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）。 - - 日志：实时跟踪 Gateway 网关文件日志，支持过滤/导出（`logs.tail`）。 - - 更新：运行包/git 更新 + 重启（`update.run`）并生成重启报告，然后在重新连接后轮询 `update.status`，以验证正在运行的 Gateway 网关版本。 + - 调试：Status/health/models 快照、事件日志和手动 RPC 调用（`status`、`health`、`models.list`）。 + - 日志：带过滤/导出的 Gateway 网关文件日志实时尾随（`logs.tail`）。 + - 更新：运行包/git 更新并重启（`update.run`），生成重启报告，然后在重连后轮询 `update.status`，验证正在运行的 Gateway 网关版本。 - - 对于隔离作业，投递默认会公告摘要。如果你想要仅内部运行，可以切换为无。 - - 选择公告后，会显示渠道/目标字段。 + - 对于隔离作业，交付默认会公告摘要。如果你想要仅内部运行，可以切换为 none。 + - 选择公告时会显示渠道/目标字段。 - Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。 - - 对于主会话作业，webhook 和无投递模式均可用。 - - 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/thinking 覆盖，以及尽力而为投递开关。 - - 表单验证以内联方式显示字段级错误；无效值会禁用保存按钮，直到修复为止。 - - 设置 `cron.webhookToken` 可发送专用 bearer 令牌；如果省略，webhook 会在没有认证标头的情况下发送。 - - 已弃用回退：存储的旧版作业若带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。 + - 对于主会话作业，可以使用 webhook 和 none 交付模式。 + - 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/thinking 覆盖，以及尽力而为交付切换。 + - 表单验证以内联方式显示字段级错误；无效值会禁用保存按钮，直到修复。 + - 设置 `cron.webhookToken` 可发送专用 bearer 令牌；如果省略，webhook 会在不带凭证标头的情况下发送。 + - 已弃用的回退：存储的旧版作业如果带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。 @@ -152,69 +152,69 @@ Appearance 面板保留内置的 Claw、Knot 和 Dash 主题，外加一个浏 ## 聊天行为 - - - `chat.send` 是**非阻塞**的：它会立即以 `{ runId, status: "started" }` 确认，响应通过 `chat` 事件流式传输。 - - 聊天上传接受图片以及非视频文件。图片保留原生图片路径；其他文件会作为托管媒体存储，并在历史中显示为附件链接。 - - 使用相同的 `idempotencyKey` 重新发送时，运行期间返回 `{ status: "in_flight" }`，完成后返回 `{ status: "ok" }`。 + + - `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，响应会通过 `chat` 事件流式传输。 + - 聊天上传接受图片以及非视频文件。图片保留原生图片路径；其他文件会作为托管媒体存储，并在历史记录中显示为附件链接。 + - 使用相同的 `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 更新（无智能体运行，无渠道投递）。 - - 聊天头部的模型和 thinking 选择器会立即通过 `sessions.patch` 修补活跃会话；它们是持久会话覆盖项，而不是仅单轮的发送选项。 - - 聊天模型选择器会请求 Gateway 网关配置的模型视图。如果存在 `agents.defaults.models`，该允许列表会驱动选择器。否则，选择器会先显示显式的 `models.providers.*.models` 条目，然后再为全新安装回退到完整目录。 - - 当新的 Gateway 网关会话用量报告显示上下文压力较高时，聊天输入区域会显示上下文提示；在建议的压缩级别，会显示一个紧凑按钮，用于运行正常的会话压缩路径。过期的令牌快照会被隐藏，直到 Gateway 网关再次报告新的用量。 + - `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 网关再次报告新的使用情况。 - - 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` 不接受调用方提供的指令覆盖。 + + 通话模式使用已注册的实时语音提供商。可以使用 `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 启动时，输入框状态行会显示 `Connecting Talk...`，音频连接后显示 `Talk live`，或在实时工具调用通过 `chat.send` 咨询配置的更大模型时显示 `Asking OpenClaw...`。 + 在聊天输入框中，通话控件是麦克风听写按钮旁边的波形按钮。通话启动后，输入框状态行先显示 `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 受限令牌浏览器 WebSocket 设置，以及带有假麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只打印提供商状态，不记录密钥。 + 维护者实时冒烟测试：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 浏览器 WebRTC SDP 交换、Google Live 受限 token 浏览器 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 网关会将已中止的部分助手文本持久化到转录历史中。 - - 持久化条目包含中止元数据，因此转录消费者可以区分中止部分内容和正常完成输出。 + - 当运行被中止时，部分助手文本仍可显示在 UI 中。 + - 当存在已缓冲输出时，Gateway 网关会将中止的部分助手文本持久化到转录历史中。 + - 持久化条目包含中止元数据，使转录消费者能够区分中止部分内容和正常完成输出。 -## PWA 安装和 Web Push +## PWA 安装与 Web Push -Control UI 随附一个 `manifest.webmanifest` 和一个 service worker，因此现代浏览器可以将其安装为独立 PWA。Web Push 允许 Gateway 网关通过通知唤醒已安装的 PWA，即使标签页或浏览器窗口未打开也是如此。 +控制 UI 随附 `manifest.webmanifest` 和 Service Worker，因此现代浏览器可以将其安装为独立 PWA。Web Push 可让 Gateway 网关通过通知唤醒已安装的 PWA，即使标签页或浏览器窗口未打开也是如此。 | 表面 | 作用 | | ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | PWA 清单。浏览器在可访问后会提供“安装应用”。 | -| `ui/public/sw.js` | 处理 `push` 事件和通知点击的 service worker。 | -| `push/vapid-keys.json`（位于 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于签名 Web Push 载荷。 | +| `ui/public/manifest.webmanifest` | PWA manifest。浏览器在其可访问后会提供“安装应用”。 | +| `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`） -Control UI 使用这些受作用域限制的 Gateway 网关方法来注册和测试浏览器订阅： +控制 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` 方法，后两者面向原生移动端配对。 ## 托管嵌入 @@ -226,10 +226,10 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 禁用托管嵌入内的脚本执行。 - 允许交互式嵌入，同时保持来源隔离；这是默认值，通常足以用于自包含的浏览器游戏/小组件。 + 允许交互式嵌入，同时保持源隔离；这是默认设置，通常足以满足自包含浏览器游戏/小组件。 - 在 `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,12 +265,12 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 - `https:///`（或你配置的 `gateway.controlUi.basePath`） - 默认情况下，当 `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"`。 + 默认情况下，当 `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"`。 - 对于该异步 Serve 身份路径，在写入速率限制之前，同一客户端 IP 和认证作用域的失败认证尝试会被串行化。因此，来自同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配并行竞争。 + 对于该异步 Serve 身份路径，同一客户端 IP 和身份验证作用域的失败认证尝试会在写入速率限制之前被串行化。因此，来自同一浏览器的并发错误重试可能会在第二个请求上显示 `retry later`，而不是两个普通不匹配并行竞争。 - 无令牌 Serve 认证假定网关主机是可信的。如果不可信的本地代码可能在该主机上运行，请要求 token/password 认证。 + 无 token 的 Serve 身份验证假定网关主机可信。如果不受信任的本地代码可能在该主机上运行，请要求 token/密码身份验证。 @@ -290,21 +290,21 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 ## 不安全 HTTP -如果你通过纯 HTTP（`http://` 或 `http://`）打开仪表板，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。 +如果你通过纯 HTTP（`http://` 或 `http://`）打开仪表板，浏览器会在**非安全上下文**中运行并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的控制 UI 连接。 -已记录的例外： +已记录的例外情况： -- 仅限 localhost 的不安全 HTTP 兼容性，使用 `gateway.controlUi.allowInsecureAuth=true` -- 通过 `gateway.auth.mode: "trusted-proxy"` 成功完成的操作者 Control UI 认证 -- 紧急破窗 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- 通过 `gateway.controlUi.allowInsecureAuth=true` 提供仅 localhost 的不安全 HTTP 兼容性 +- 通过 `gateway.auth.mode: "trusted-proxy"` 成功完成的操作者控制 UI 身份验证 +- 应急用 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` -**推荐修复：**使用 HTTPS（Tailscale Serve）或在本地打开 UI： +**推荐修复：** 使用 HTTPS（Tailscale Serve）或在本地打开 UI： - `https:///`（Serve） - `http://127.0.0.1:18789/`（在网关主机上） - + ```json5 { gateway: { @@ -317,12 +317,12 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 `allowInsecureAuth` 只是本地兼容性开关： - - 它允许 localhost Control UI 会话在非安全 HTTP 上下文中无需设备身份继续进行。 + - 它允许 localhost 控制 UI 会话在非安全 HTTP 上下文中无需设备身份即可继续。 - 它不会绕过配对检查。 - 它不会放宽远程（非 localhost）设备身份要求。 - + ```json5 { gateway: { @@ -334,30 +334,30 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 ``` - `dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，是严重的安全降级。紧急使用后请迅速恢复。 + `dangerouslyDisableDeviceAuth` 会禁用控制 UI 设备身份检查，是严重的安全降级。应急使用后请尽快恢复。 - - 成功的可信代理认证可以允许没有设备身份的 **operator** 控制 UI 会话进入。 + - 成功的可信代理认证可以允许没有设备身份的**操作者**控制 UI 会话进入。 - 这**不**适用于节点角色控制 UI 会话。 - - 同主机 loopback 反向代理仍不满足可信代理认证；请参阅[可信代理认证](/zh-CN/gateway/trusted-proxy-auth)。 + - 同主机 loopback 反向代理仍然不满足可信代理认证；请参阅[可信代理认证](/zh-CN/gateway/trusted-proxy-auth)。 -有关 HTTPS 设置指导，请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 +请参阅 [Tailscale](/zh-CN/gateway/tailscale) 获取 HTTPS 设置指南。 ## 内容安全策略 -控制 UI 附带严格的 `img-src` 策略：只允许**同源**资源、`data:` URL 和本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络请求。 +控制 UI 附带严格的 `img-src` 策略：只允许**同源**资源、`data:` URL，以及本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络获取。 这在实践中意味着： - 通过相对路径提供的头像和图片（例如 `/avatars/`）仍会渲染，包括 UI 获取并转换为本地 `blob:` URL 的已认证头像路由。 -- 内联 `data:image/...` URL 仍会渲染（适用于协议内载荷）。 +- 内联 `data:image/...` URL 仍会渲染（对协议内载荷很有用）。 - 控制 UI 创建的本地 `blob:` URL 仍会渲染。 -- 渠道元数据发出的远程头像 URL 会在控制 UI 的头像辅助函数中被剥离，并替换为内置标志/徽章，因此被入侵或恶意的渠道无法强制操作员浏览器发起任意远程图片请求。 +- 渠道元数据发出的远程头像 URL 会在控制 UI 的头像辅助逻辑中被移除，并替换为内置徽标/徽章，因此被攻陷或恶意的渠道无法强制操作者浏览器获取任意远程图片。 你无需更改任何内容即可获得此行为 —— 它始终启用且不可配置。 @@ -365,15 +365,15 @@ Web Push 独立于 iOS APNS 中继路径（有关中继支持的推送，请参 配置 Gateway 网关认证后，控制 UI 头像端点需要与 API 其余部分相同的 Gateway 网关令牌： -- `GET /avatar/` 仅向已认证调用方返回头像图片。`GET /avatar/?meta=1` 在相同规则下返回头像元数据。 -- 对任一路由的未认证请求都会被拒绝（与相邻的助手媒体路由一致）。这可以防止头像路由在其他方面受保护的主机上泄露智能体身份。 -- 控制 UI 自身在获取头像时会以 bearer 头转发 Gateway 网关令牌，并使用已认证的 blob URL，因此图片仍会在仪表盘中渲染。 +- `GET /avatar/` 仅向已认证调用方返回头像图片。`GET /avatar/?meta=1` 按同一规则返回头像元数据。 +- 对任一路由的未认证请求都会被拒绝（与相邻的 assistant-media 路由一致）。这可以防止头像路由在原本受保护的主机上泄露智能体身份。 +- 控制 UI 本身在获取头像时会将 Gateway 网关令牌作为 bearer 标头转发，并使用已认证的 blob URL，因此图片仍会在仪表板中渲染。 -如果你禁用 Gateway 网关认证（不建议在共享主机上这样做），头像路由也会变为未认证状态，与 Gateway 网关的其余部分保持一致。 +如果你禁用 Gateway 网关认证（不建议在共享主机上这样做），头像路由也会与 Gateway 网关的其余部分一样变为未认证。 ## 构建 UI -Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建： +Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建它们： ```bash pnpm ui:build @@ -385,7 +385,7 @@ pnpm ui:build OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build ``` -本地开发（独立开发服务器）： +本地开发（单独的开发服务器）： ```bash pnpm ui:dev @@ -395,7 +395,7 @@ pnpm ui:dev ## 调试/测试：开发服务器 + 远程 Gateway 网关 -控制 UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 源。当你想在本地使用 Vite 开发服务器、但 Gateway 网关在其他位置运行时，这很方便。 +控制 UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 来源。当你想在本地使用 Vite 开发服务器，但 Gateway 网关在其他地方运行时，这很方便。 @@ -405,13 +405,13 @@ pnpm ui:dev ```text - http://localhost:5173/?gatewayUrl=ws://:18789 + http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ``` - 可选的一次性认证（如果需要）： + 可选的一次性认证（如需要）： ```text - http://localhost:5173/?gatewayUrl=wss://:18789#token= + http://localhost:5173/?gatewayUrl=wss%3A%2F%2F%3A18789#token= ``` @@ -419,16 +419,17 @@ pnpm ui:dev - - `gatewayUrl` 会在加载后存储在 localStorage 中，并从 URL 中移除。 - - 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，这可以避免请求日志和 Referer 泄露。旧版 `?token=` 查询参数仍会为了兼容性导入一次，但仅作为回退，并且会在引导后立即剥离。 + - `gatewayUrl` 会在加载后存储到 localStorage，并从 URL 中移除。 + - 如果你通过 `gatewayUrl` 传入完整的 `ws://` 或 `wss://` 端点，请对 `gatewayUrl` 值进行 URL 编码，以便浏览器正确解析查询字符串。 + - 应尽可能通过 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: ["*"]`。它表示允许任何浏览器源，而不是“匹配我正在使用的任何主机”。 - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 头源回退模式，但这是一种危险的安全模式。 + - 设置 `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: ["*"]`。它表示允许任何浏览器来源，而不是“匹配我正在使用的任何主机”。 + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头来源回退模式，但这是危险的安全模式。 @@ -449,7 +450,7 @@ pnpm ui:dev ## 相关内容 -- [仪表盘](/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) — 基于浏览器的聊天界面