diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index be3226be7..9994bd845 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -1,22 +1,22 @@ --- read_when: - - 正在开发 Discord 渠道功能 + - 开发 Discord 渠道功能 summary: Discord 机器人支持状态、能力和配置 title: Discord x-i18n: - generated_at: "2026-04-29T15:39:28Z" + generated_at: "2026-04-29T21:05:39Z" model: gpt-5.5 provider: openai - source_hash: a1d3dc0962b6140a727ea8e08f01227e18d2feffa7ce50c3614fb7aa4dd9d044 + source_hash: 2d374742a097682f33529f93709978f21b63a94cd4da803ff78ff8dfcb1f9b81 source_path: channels/discord.md workflow: 16 --- -已可通过 Discord 官方网关用于私信和服务器渠道。 +已可通过官方 Discord 网关用于私信和服务器渠道。 - Discord 私信默认进入配对模式。 + Discord 私信默认使用配对模式。 原生命令行为和命令目录。 @@ -28,91 +28,100 @@ x-i18n: ## 快速设置 -你需要创建一个带机器人的新应用程序，将机器人添加到你的服务器，并将它与 OpenClaw 配对。我们建议将你的机器人添加到你自己的私有服务器。如果你还没有服务器，请[先创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **创建我自己的 > 为我和我的朋友**）。 +你需要创建一个带有 bot 的新应用，将 bot 添加到你的服务器，并将它与 OpenClaw 配对。我们建议将你的 bot 添加到你自己的私有服务器。如果你还没有服务器，请[先创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 - - 前往 [Discord 开发者门户](https://discord.com/developers/applications) 并点击 **新建应用程序**。将其命名为类似 “OpenClaw” 的名称。 + + 前往 [Discord Developer Portal](https://discord.com/developers/applications)，然后点击 **New Application**。将其命名为类似 “OpenClaw” 的名称。 - 点击侧边栏中的 **机器人**。将 **用户名** 设置为你给 OpenClaw 智能体起的名称。 + 点击侧边栏中的 **Bot**。将 **Username** 设置为你给 OpenClaw 智能体起的名字。 - - 仍在 **机器人** 页面，向下滚动到 **特权 Gateway 网关意图** 并启用： + + 仍在 **Bot** 页面上，向下滚动到 **Privileged Gateway Intents** 并启用： - - **消息内容意图**（必需） - - **服务器成员意图**（推荐；角色允许列表和名称到 ID 匹配需要） - - **在线状态意图**（可选；仅在线状态更新需要） + - **Message Content Intent**（必需） + - **Server Members Intent**（推荐；角色允许列表和名称到 ID 匹配需要） + - **Presence Intent**（可选；仅在需要在线状态更新时使用） - - 回到 **机器人** 页面顶部，点击 **重置令牌**。 + + 在 **Bot** 页面上滚回顶部并点击 **Reset Token**。 - 尽管名称如此，这会生成你的第一个令牌；并没有任何内容被“重置”。 + 尽管名称如此，这会生成你的第一个 token，并没有“重置”任何内容。 - 复制该令牌并保存到某处。这是你的 **机器人令牌**，稍后会用到。 + 复制 token 并保存到某处。这是你的 **Bot Token**，你很快就会用到它。 - - 点击侧边栏中的 **OAuth2**。你将生成一个具备正确权限的邀请 URL，以便将机器人添加到你的服务器。 + + 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，以便将 bot 添加到你的服务器。 - 向下滚动到 **OAuth2 URL 生成器** 并启用： + 向下滚动到 **OAuth2 URL Generator** 并启用： - `bot` - `applications.commands` - 下方会出现 **机器人权限** 部分。至少启用： + 下方会出现 **Bot Permissions** 部分。至少启用： - **常规权限** - - 查看渠道 - **文本权限** - - 发送消息 - - 读取消息历史 - - 嵌入链接 - - 附加文件 - - 添加反应（可选） + **General Permissions** + - View Channels + **Text Permissions** + - Send Messages + - Read Message History + - Embed Links + - Attach Files + - Add Reactions（可选） - 这是普通文本渠道的基线权限集。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体渠道工作流，还要启用 **在线程中发送消息**。 - 复制底部生成的 URL，粘贴到浏览器中，选择你的服务器，然后点击 **继续** 以连接。现在你应该能在 Discord 服务器中看到你的机器人。 + 这是普通文本渠道的基线权限集合。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体渠道工作流，也要启用 **Send Messages in Threads**。 + 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该能在 Discord 服务器中看到你的 bot。 - - 回到 Discord 应用，你需要启用开发者模式，才能复制内部 ID。 + + 回到 Discord 应用中，你需要启用 Developer Mode，这样才能复制内部 ID。 - 1. 点击 **用户设置**（头像旁的齿轮图标） → **高级** → 开启 **开发者模式** - 2. 右键点击侧边栏中的 **服务器图标** → **复制服务器 ID** - 3. 右键点击你自己的 **头像** → **复制用户 ID** + 1. 点击 **User Settings**（头像旁边的齿轮图标）→ **Advanced** → 打开 **Developer Mode** + 2. 在侧边栏中右键点击你的 **server icon** → **Copy Server ID** + 3. 右键点击你自己的 **avatar** → **Copy User ID** - 将你的 **服务器 ID** 和 **用户 ID** 与机器人令牌一起保存；下一步你会把这三项发送给 OpenClaw。 + 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存，你会在下一步把这三项都发送给 OpenClaw。 - 要让配对工作，Discord 需要允许你的机器人向你发送私信。右键点击你的 **服务器图标** → **隐私设置** → 开启 **私信**。 + 要让配对正常工作，Discord 需要允许你的 bot 给你发送私信。右键点击你的 **server icon** → **Privacy Settings** → 打开 **Direct Messages**。 - 这允许服务器成员（包括机器人）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持开启。如果你只计划使用服务器渠道，可以在配对后禁用私信。 + 这会允许服务器成员（包括 bot）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持此项启用。如果你只计划使用服务器渠道，可以在配对后禁用私信。 - - 你的 Discord 机器人令牌是密钥（类似密码）。在给智能体发消息之前，请在运行 OpenClaw 的机器上设置它。 + + 你的 Discord bot token 是密钥（类似密码）。在给智能体发消息之前，先在运行 OpenClaw 的机器上设置它。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" -openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run -openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN -openclaw config set channels.discord.enabled true --strict-json +cat > discord.patch.json5 <<'JSON5' +{ + channels: { + discord: { + enabled: true, + token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" }, + }, + }, +} +JSON5 +openclaw config patch --file ./discord.patch.json5 --dry-run +openclaw config patch --file ./discord.patch.json5 openclaw gateway ``` - 如果 OpenClaw 已作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。 - 对于托管服务安装，请在存在 `DISCORD_BOT_TOKEN` 的命令行环境中运行 `openclaw gateway install`，或将变量存储在 `~/.openclaw/.env` 中，这样服务重启后就能解析环境变量 SecretRef。 + 如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重启 `openclaw gateway run` 进程。 + 对于托管服务安装，请从存在 `DISCORD_BOT_TOKEN` 的 shell 运行 `openclaw gateway install`，或将该变量存储在 `~/.openclaw/.env` 中，这样服务在重启后就能解析 env SecretRef。 @@ -120,9 +129,9 @@ openclaw gateway - 在任何现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置选项卡。 + 在任何现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。 - > “我已经在配置中设置了我的 Discord 机器人令牌。请使用用户 ID `` 和服务器 ID `` 完成 Discord 设置。” + > “我已经在配置中设置了 Discord bot token。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” 如果你更喜欢基于文件的配置，请设置： @@ -142,13 +151,13 @@ openclaw gateway } ``` - 默认账号的环境变量回退： + 默认账号的 env 回退： ```bash DISCORD_BOT_TOKEN=... ``` - 支持明文 `token` 值。也支持在 env/file/exec 提供商中为 `channels.discord.token` 使用 SecretRef 值。请参阅 [密钥管理](/zh-CN/gateway/secrets)。 + 对于脚本化或远程设置，请使用 `openclaw config patch --file ./discord.patch.json5 --dry-run` 写入同一个 JSON5 块，然后去掉 `--dry-run` 重新运行。支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商使用 SecretRef 值。请参阅[密钥管理](/zh-CN/gateway/secrets)。 @@ -156,13 +165,13 @@ DISCORD_BOT_TOKEN=... - 等到 Gateway 网关运行后，在 Discord 中私信你的机器人。它会回复配对码。 + 等到网关运行后，在 Discord 中给你的 bot 发送私信。它会返回一个配对码。 - 在你现有的渠道中将配对码发送给你的智能体： + 通过你的现有渠道将配对码发送给你的智能体： - > “批准此 Discord 配对码：``” + > “批准这个 Discord 配对码：``” @@ -176,28 +185,28 @@ openclaw pairing approve discord 配对码会在 1 小时后过期。 - 现在你应该可以在 Discord 中通过私信与你的智能体聊天。 + 现在你应该可以通过私信在 Discord 中与你的智能体聊天。 -令牌解析会感知账号。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账号。 -如果两个已启用的 Discord 账号解析为同一个机器人令牌，OpenClaw 只会为该令牌启动一个 Gateway 网关监视器。配置来源的令牌优先于默认环境变量回退；否则，第一个已启用账号获胜，重复账号会被报告为已禁用。 -对于高级出站调用（`message` 工具/渠道操作），每次调用都会使用显式的调用级 `token`。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账号策略/重试设置仍来自活动运行时快照中选定的账号。 +Token 解析会感知账号。配置 token 值优先于 env 回退。`DISCORD_BOT_TOKEN` 仅用于默认账号。 +如果两个已启用的 Discord 账号解析到同一个 bot token，OpenClaw 只会为该 token 启动一个网关监视器。来自配置的 token 优先于默认 env 回退；否则第一个已启用账号会胜出，重复账号会被报告为已禁用。 +对于高级出站调用（消息工具/渠道操作），显式的按调用 `token` 会用于该调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账号策略/重试设置仍来自活跃运行时快照中选定的账号。 ## 推荐：设置服务器工作区 -私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个渠道都有自己的智能体会话和上下文。对于只有你和机器人的私有服务器，建议这样做。 +私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个渠道都有自己的智能体会话和上下文。对于只有你和你的 bot 的私有服务器，建议这样做。 - 这会让你的智能体可以在服务器上的任何渠道中响应，而不只是私信。 + 这会让你的智能体能在服务器上的任何渠道中响应，而不只是私信。 - > “将我的 Discord 服务器 ID `` 添加到服务器允许列表” + > “将我的 Discord Server ID `` 添加到服务器允许列表” @@ -222,14 +231,14 @@ openclaw pairing approve discord - - 默认情况下，你的智能体只有在服务器渠道中被 @提及时才会响应。对于私有服务器，你可能希望它响应每条消息。 + + 默认情况下，你的智能体只有在服务器渠道中被 @mentioned 时才会响应。对于私有服务器，你可能希望它响应每条消息。 - 在服务器渠道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须使用 `message` 工具显式发送，因此智能体默认可以静默观察，并且只有在它判断渠道回复有用时才发帖。 + 在服务器渠道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须通过 `message` 工具显式发送，因此智能体默认可以旁观，只在判断渠道回复有用时才发帖。 - > “允许我的智能体在此服务器上响应，而无需被 @提及” + > “允许我的智能体在这个服务器上响应，不需要被 @mentioned” 在你的服务器配置中设置 `requireMention: false`： @@ -255,7 +264,7 @@ openclaw pairing approve discord - + 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。服务器渠道不会自动加载 MEMORY.md。 @@ -263,36 +272,34 @@ openclaw pairing approve discord > “当我在 Discord 渠道中提问时，如果你需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。” - 如果你需要在每个渠道中共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并按需使用记忆工具访问它们。 + 如果你需要在每个渠道中共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并按需通过记忆工具访问。 -现在在你的 Discord 服务器上创建一些渠道并开始聊天。你的智能体可以看到渠道名称，并且每个渠道都有自己的隔离会话，所以你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的渠道。 +现在在你的 Discord 服务器上创建一些渠道并开始聊天。你的智能体可以看到渠道名称，而且每个渠道都有自己隔离的会话，因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的内容。 ## 运行时模型 -- Gateway 网关负责 Discord 连接。 -- 回复路由是确定性的：Discord 入站会回复到 Discord。 -- Discord 服务器/渠道元数据会作为不受信任的 - 上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型把该封装复制回去，OpenClaw 会从出站回复和未来重放上下文中剥离复制的元数据。 +- Gateway 网关拥有 Discord 连接。 +- 回复路由是确定性的：Discord 入站回复会回到 Discord。 +- Discord 服务器/渠道元数据会作为不受信任的上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型把该信封复制回来，OpenClaw 会从出站回复和未来重放上下文中剥离被复制的元数据。 - 默认情况下（`session.dmScope=main`），直接聊天共享智能体主会话（`agent:main:main`）。 - 服务器渠道使用隔离的会话键（`agent::discord:channel:`）。 - 群组私信默认会被忽略（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 指向路由后的对话会话。 -- 到 Discord 的纯文本 cron/heartbeat 公告投递只使用一次最终的 - 助手可见答案。媒体和结构化组件负载在智能体发出多个可投递负载时仍保持多消息形式。 +- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 指向已路由的对话会话。 +- 仅文本 cron/heartbeat 向 Discord 宣告交付时，会使用一次最终的助手可见答案。媒体和结构化组件载荷在智能体发出多个可交付载荷时仍保持多消息形式。 ## 论坛渠道 Discord 论坛和媒体渠道只接受线程帖子。OpenClaw 支持两种创建方式： -- 向论坛父渠道（`channel:`）发送消息以自动创建线程。线程标题使用你消息中的第一行非空内容。 -- 使用 `openclaw message thread create` 直接创建线程。对于论坛渠道，不要传递 `--message-id`。 +- 向论坛父级（`channel:`）发送消息以自动创建线程。线程标题使用消息的第一行非空内容。 +- 使用 `openclaw message thread create` 直接创建线程。不要为论坛渠道传递 `--message-id`。 -示例：发送到论坛父渠道以创建线程 +示例：发送到论坛父级以创建线程 ```bash openclaw message send --channel discord --target channel: \ @@ -306,23 +313,23 @@ openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -论坛父渠道不接受 Discord 组件。如果你需要组件，请发送到线程本身（`channel:`）。 +论坛父级不接受 Discord 组件。如果需要组件，请发送到线程本身（`channel:`）。 ## 交互式组件 -OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带有 `components` 负载的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 +OpenClaw 支持用于智能体消息的 Discord components v2 容器。请使用带有 `components` 载荷的 message 工具。交互结果会作为普通入站消息路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 支持的块： - `text`、`section`、`separator`、`actions`、`media-gallery`、`file` -- 操作行最多允许 5 个按钮或单个选择菜单 +- 操作行最多允许 5 个按钮或一个选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，组件只能使用一次。设置 `components.reusable=true`，允许按钮、选择器和表单在过期前多次使用。 +默认情况下，组件只能使用一次。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前多次使用。 要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型、兼容运行时下拉菜单以及提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，并且只有发起调用的用户可以使用。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及一个提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，只有发起调用的用户可以使用。 文件附件： @@ -332,9 +339,9 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 模态表单： -- 添加 `components.modal`，最多包含 5 个字段 +- 添加最多包含 5 个字段的 `components.modal` - 字段类型：`text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` -- OpenClaw 会自动添加触发按钮 +- OpenClaw 会自动添加一个触发按钮 示例： @@ -393,7 +400,7 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 ## 访问控制和路由 - + `channels.discord.dmPolicy` 控制私信访问。`channels.discord.allowFrom` 是规范的私信允许列表。 - `pairing`（默认） @@ -401,28 +408,28 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 - `open`（要求 `channels.discord.allowFrom` 包含 `"*"`） - `disabled` - 如果私信策略不是开放的，未知用户会被阻止（或在 `pairing` 模式下被提示配对）。 + 如果私信策略不是开放的，未知用户会被阻止（或在 `pairing` 模式下提示配对）。 - 多账号优先级： + 多账户优先级： - - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账号。 - - 对于一个账号，`allowFrom` 的优先级高于旧版 `dm.allowFrom`。 - - 当命名账号自己的 `allowFrom` 和旧版 `dm.allowFrom` 均未设置时，会继承 `channels.discord.allowFrom`。 - - 命名账号不会继承 `channels.discord.accounts.default.allowFrom`。 + - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账户。 + - 对于单个账户，`allowFrom` 优先于旧版 `dm.allowFrom`。 + - 当具名账户自身的 `allowFrom` 和旧版 `dm.allowFrom` 未设置时，会继承 `channels.discord.allowFrom`。 + - 具名账户不会继承 `channels.discord.accounts.default.allowFrom`。 - 旧版 `channels.discord.dm.policy` 和 `channels.discord.dm.allowFrom` 仍会为了兼容性而读取。`openclaw doctor --fix` 会在不改变访问权限的情况下，将它们迁移到 `dmPolicy` 和 `allowFrom`。 + 旧版 `channels.discord.dm.policy` 和 `channels.discord.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的情况下，将它们迁移到 `dmPolicy` 和 `allowFrom`。 用于投递的私信目标格式： - `user:` - `<@id>` 提及 - 当渠道默认值处于活动状态时，裸数字 ID 通常会解析为渠道 ID，但在账号有效私信 `allowFrom` 中列出的 ID 会为了兼容性被视为用户私信目标。 + 当渠道默认值处于活动状态时，裸数字 ID 通常会解析为渠道 ID，但为保持兼容，账户有效私信 `allowFrom` 中列出的 ID 会被视为用户私信目标。 - - Guild 处理由 `channels.discord.groupPolicy` 控制： + + 服务器处理由 `channels.discord.groupPolicy` 控制： - `open` - `allowlist` @@ -432,12 +439,12 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 `allowlist` 行为： - - guild 必须匹配 `channels.discord.guilds`（优先使用 `id`，也接受 slug） - - 可选发送者允许列表：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了任一项，发送者匹配 `users` 或 `roles` 时即允许 - - 默认禁用直接名称/标签匹配；只有在作为应急兼容模式时才启用 `channels.discord.dangerouslyAllowNameMatching: true` + - 服务器必须匹配 `channels.discord.guilds`（首选 `id`，也接受 slug） + - 可选发送者允许列表：`users`（推荐稳定 ID）和 `roles`（仅角色 ID）；如果配置了任一项，发送者匹配 `users` 或 `roles` 时即被允许 + - 默认禁用直接名称/标签匹配；仅在应急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` - `users` 支持名称/标签，但 ID 更安全；使用名称/标签条目时，`openclaw security audit` 会发出警告 - - 如果某个 guild 配置了 `channels`，未列出的渠道会被拒绝 - - 如果某个 guild 没有 `channels` 块，则该允许列表 guild 中的所有渠道都允许 + - 如果服务器配置了 `channels`，未列出的渠道会被拒绝 + - 如果服务器没有 `channels` 块，则该允许列表服务器中的所有渠道都被允许 示例： @@ -463,20 +470,20 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 } ``` - 如果你只设置了 `DISCORD_BOT_TOKEN`，并且没有创建 `channels.discord` 块，则运行时回退为 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open`。 + 如果你只设置 `DISCORD_BOT_TOKEN`，但没有创建 `channels.discord` 块，运行时回退值会是 `groupPolicy="allowlist"`（日志中会有警告），即使 `channels.defaults.groupPolicy` 是 `open`。 - - Guild 消息默认受提及门控限制。 + + 服务器消息默认受提及门控。 提及检测包括： - 显式机器人提及 - - 配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） - - 支持情况下的隐式回复机器人行为 + - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） + - 支持场景中的隐式回复机器人行为 - `requireMention` 按 guild/渠道配置（`channels.discord.guilds...`）。 + `requireMention` 按服务器/渠道配置（`channels.discord.guilds...`）。 `ignoreOtherMentions` 可选择丢弃提及其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 群组私信： @@ -489,7 +496,7 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 ### 基于角色的智能体路由 -使用 `bindings[].match.roles` 按角色 ID 将 Discord guild 成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在 peer 或 parent-peer 绑定之后、guild-only 绑定之前评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 +使用 `bindings[].match.roles` 按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在对等或父对等绑定之后、仅服务器绑定之前评估。如果一个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有配置的字段都必须匹配。 ```json5 { @@ -513,15 +520,15 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 } ``` -## 原生命令和命令授权 +## 原生命令和命令认证 -- `commands.native` 默认为 `"auto"`，并且为 Discord 启用。 +- `commands.native` 默认为 `"auto"`，并为 Discord 启用。 - 按渠道覆盖：`channels.discord.commands.native`。 - `commands.native=false` 会显式清除之前注册的 Discord 原生命令。 -- 原生命令授权使用与普通消息处理相同的 Discord 允许列表/策略。 -- 命令对于未授权用户可能仍会显示在 Discord UI 中；执行时仍会强制执行 OpenClaw 授权，并返回“未授权”。 +- 原生命令认证使用与普通消息处理相同的 Discord 允许列表/策略。 +- 对未授权用户，命令可能仍会在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 认证，并返回 “not authorized”。 -请参阅[斜杠命令](/zh-CN/tools/slash-commands)，了解命令目录和行为。 +请参阅[斜杠命令](/zh-CN/tools/slash-commands)了解命令目录和行为。 默认斜杠命令设置： @@ -530,7 +537,7 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 ## 功能详情 - + Discord 支持智能体输出中的回复标签： - `[[reply_to_current]]` @@ -543,18 +550,18 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 - `all` - `batched` - 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会生效。 - `first` 始终将隐式原生回复引用附加到本轮第一条出站 Discord 消息。 - `batched` 仅在入站轮次是多条消息的防抖批次时，才附加 Discord 的隐式原生回复引用。当你主要想为含义不明确的突发聊天提供原生回复，而不是为每个单消息轮次都提供时，这很有用。 + 注意：`off` 会禁用隐式回复串联。显式 `[[reply_to_*]]` 标签仍会生效。 + `first` 始终会将隐式原生回复引用附加到本轮第一条出站 Discord 消息。 + `batched` 仅在入站轮次是多条消息的防抖批次时，才附加 Discord 的隐式原生回复引用。当你主要希望在模糊的突发聊天中使用原生回复，而不是每个单消息轮次都使用时，这很有用。 消息 ID 会在上下文/历史中暴露，因此智能体可以定位特定消息。 - - OpenClaw 可以通过发送临时消息并在文本到达时编辑它来流式传输草稿回复。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。`progress` 在 Discord 上映射为 `partial`；`streamMode` 是旧版别名，并会自动迁移。 + + OpenClaw 可以通过发送临时消息并在文本到达时编辑该消息来流式传输草稿回复。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。在 Discord 上，`progress` 映射到 `partial`；`streamMode` 是旧版别名，会自动迁移。 - 默认保持为 `off`，因为当多个机器人或 Gateway 网关共享一个账号时，Discord 预览编辑会很快触及速率限制。 + 默认保持 `off`，因为当多个机器人或 Gateway 网关共享一个账户时，Discord 预览编辑会很快触及速率限制。 ```json5 { @@ -572,20 +579,20 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 ``` - `partial` 会在 token 到达时编辑单条预览消息。 - - `block` 会发出草稿大小的块（使用 `draftChunk` 调整大小和断点，并限制在 `textChunkLimit` 内）。 - - 媒体、错误和显式回复最终消息会取消待处理的预览编辑。 + - `block` 会发出草稿大小的块（使用 `draftChunk` 调整大小和断点，并被限制到 `textChunkLimit`）。 + - 媒体、错误和显式回复的最终消息会取消待处理的预览编辑。 - `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用预览消息。 - 预览流式传输仅支持文本；媒体回复会回退到正常投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 + 预览流式传输仅支持文本；媒体回复会回退到普通投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - - Guild 历史上下文： + + 服务器历史上下文： - - `channels.discord.historyLimit` 默认值为 `20` + - `channels.discord.historyLimit` 默认 `20` - 回退：`messages.groupChat.historyLimit` - - `0` 会禁用 + - `0` 禁用 私信历史控制： @@ -594,26 +601,26 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 线程行为： - - Discord 线程会作为渠道会话路由，并继承父渠道配置，除非被覆盖。 - - 线程会话继承父渠道的会话级 `/model` 选择作为仅模型回退；线程本地 `/model` 选择仍优先，并且除非启用了 transcript 继承，否则不会复制父 transcript 历史。 - - `channels.discord.thread.inheritParent`（默认 `false`）会让新的自动线程从父 transcript 播种。按账号覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 - - 消息工具 reactions 可以解析 `user:` 私信目标。 + - Discord 线程作为渠道会话路由，并继承父渠道配置，除非被覆盖。 + - 线程会话会继承父渠道的会话级 `/model` 选择，作为仅模型回退；线程本地 `/model` 选择仍然优先，除非启用转录继承，否则不会复制父转录历史。 + - `channels.discord.thread.inheritParent`（默认 `false`）让新的自动线程选择从父转录中播种。按账户覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 + - 消息工具反应可以解析 `user:` 私信目标。 - `guilds..channels..requireMention: false` 会在回复阶段激活回退期间保留。 - 渠道主题会作为**不可信**上下文注入。允许列表会限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 + 渠道主题会作为**不可信**上下文注入。允许列表限制谁可以触发智能体，但不是完整的补充上下文脱敏边界。 - - Discord 可以将线程绑定到会话目标，以便该线程中的后续消息继续路由到同一个会话（包括子智能体会话）。 + + Discord 可以将线程绑定到会话目标，使该线程中的后续消息继续路由到同一会话（包括子智能体会话）。 命令： - `/focus ` 将当前/新线程绑定到子智能体/会话目标 - `/unfocus` 移除当前线程绑定 - `/agents` 显示活动运行和绑定状态 - - `/session idle ` 检查/更新聚焦绑定的非活动自动取消聚焦 - - `/session max-age ` 检查/更新聚焦绑定的硬性最长时长 + - `/session idle ` 查看/更新聚焦绑定的不活动自动取消聚焦时间 + - `/session max-age ` 查看/更新聚焦绑定的硬性最大存在时间 配置： @@ -643,16 +650,16 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 - `session.threadBindings.*` 设置全局默认值。 - `channels.discord.threadBindings.*` 覆盖 Discord 行为。 - - `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定话题。 - - `spawnAcpSessions` 必须为 true，才能为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定话题。 - - 如果某个账号禁用了话题绑定，则 `/focus` 及相关话题绑定操作不可用。 + - `spawnSubagentSessions` 必须为 true，才会为 `sessions_spawn({ thread: true })` 自动创建/绑定帖子串。 + - `spawnAcpSessions` 必须为 true，才会为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定帖子串。 + - 如果某个账号禁用了帖子串绑定，`/focus` 和相关帖子串绑定操作将不可用。 - 参见 [子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents) 和 [配置参考](/zh-CN/gateway/configuration-reference)。 + 参见 [Sub-agents](/zh-CN/tools/subagents)、[ACP Agents](/zh-CN/tools/acp-agents) 和 [配置参考](/zh-CN/gateway/configuration-reference)。 - - 对于稳定的“始终在线”ACP 工作区，请配置面向 Discord 对话的顶层类型化 ACP 绑定。 + + 对于稳定的“始终在线”ACP 工作区，配置面向 Discord 对话的顶层类型化 ACP 绑定。 配置路径： @@ -708,15 +715,15 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 说明： - - `/acp spawn codex --bind here` 会就地绑定当前频道或话题，并让后续消息继续使用同一个 ACP 会话。话题消息会继承父频道绑定。 - - 在已绑定的频道或话题中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时话题绑定在活跃期间可以覆盖目标解析。 - - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子话题时，才需要 `spawnAcpSessions`。 + - `/acp spawn codex --bind here` 会在当前位置绑定当前频道或帖子串，并让后续消息继续使用同一个 ACP 会话。帖子串消息会继承父频道绑定。 + - 在已绑定的频道或帖子串中，`/new` 和 `/reset` 会在当前位置重置同一个 ACP 会话。临时帖子串绑定在活跃时可以覆盖目标解析。 + - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子帖子串时，才需要 `spawnAcpSessions`。 - 有关绑定行为详情，请参见 [ACP 智能体](/zh-CN/tools/acp-agents)。 + 绑定行为详情见 [ACP Agents](/zh-CN/tools/acp-agents)。 - + 每个服务器的回应通知模式： - `off` @@ -728,8 +735,8 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 - - `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 + + `ackReaction` 会在 OpenClaw 处理传入消息时发送一个确认表情符号。 解析顺序： @@ -745,7 +752,7 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 - + 默认启用由渠道发起的配置写入。 这会影响 `/config set|unset` 流程（当命令功能已启用时）。 @@ -764,8 +771,8 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 - - 通过 HTTP(S) 代理使用 `channels.discord.proxy` 路由 Discord gateway WebSocket 流量和启动时 REST 查询（应用 ID + allowlist 解析）。 + + 通过 `channels.discord.proxy` 使用 HTTP(S) 代理路由 Discord gateway WebSocket 流量和启动时 REST 查询（应用 ID + 允许列表解析）。 ```json5 { @@ -777,7 +784,7 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 } ``` - 按账号覆盖： + 每账号覆盖： ```json5 { @@ -795,7 +802,7 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 - + 启用 PluralKit 解析，将代理消息映射到系统成员身份： ```json5 @@ -813,15 +820,15 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 说明： - - allowlist 可以使用 `pk:` - - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，成员显示名称才会按名称/slug 匹配 - - 查询使用原始消息 ID，并受时间窗口约束 - - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非设置了 `allowBots=true` + - 允许列表可以使用 `pk:` + - 只有当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名称 + - 查询使用原始消息 ID，并受时间窗口限制 + - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true` - - 当你设置 Status 或活动字段，或启用自动在线状态时，会应用在线状态更新。 + + 当你设置 Status 或活动字段，或者启用自动在线状态时，会应用在线状态更新。 仅 Status 示例： @@ -865,7 +872,7 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 活动类型映射： - 0：正在玩 - - 1：正在直播（需要 `activityUrl`） + - 1：流式传输（需要 `activityUrl`） - 2：正在听 - 3：正在观看 - 4：自定义（使用活动文本作为 Status 状态；表情符号可选） @@ -888,7 +895,7 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 } ``` - 自动在线状态会将运行时可用性映射到 Discord Status：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： + 自动在线状态会将运行时可用性映射到 Discord Status：健康 => 在线，降级或未知 => 空闲，耗尽或不可用 => 请勿打扰。可选文本覆盖： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -896,68 +903,69 @@ OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带 - - Discord 支持在私信中基于按钮处理审批，也可以选择在发起渠道中发布审批提示。 + + Discord 支持在私信中基于按钮处理审批，并且可以选择在发起渠道中发布审批提示。 配置路径： - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`） + - `channels.discord.execApprovals.approvers`（可选；可用时回退到 `commands.ownerAllowFrom`） - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"`，且至少可以从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个审批者时，Discord 会自动启用原生执行审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断执行审批者。设置 `enabled: false` 可明确禁用 Discord 作为原生审批客户端。 + 当 `enabled` 未设置或为 `"auto"`，并且至少可以从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个审批人时，Discord 会自动启用原生执行审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断执行审批人。设置 `enabled: false` 可明确禁用 Discord 作为原生审批客户端。 - 对于 `/diagnostics` 和 `/export-trajectory` 等敏感的仅限所有者组命令，OpenClaw 会私下发送审批提示和最终结果。当调用命令的所有者拥有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 + 对于敏感的仅所有者群组命令，例如 `/diagnostics` 和 `/export-trajectory`，OpenClaw 会私下发送审批提示和最终结果。当调用的所有者有 Discord 所有者路由时，它会优先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 - 当 `target` 为 `channel` 或 `both` 时，审批提示会在频道中可见。只有已解析的审批者可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此仅应在可信频道中启用频道投递。如果无法从会话键推导出频道 ID，OpenClaw 会回退到私信投递。 + 当 `target` 为 `channel` 或 `both` 时，审批提示会在频道中可见。只有已解析的审批人可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此只应在受信任频道中启用渠道投递。如果无法从会话键派生频道 ID，OpenClaw 会回退到私信投递。 - Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要添加审批者私信路由和频道扇出。 - 当这些按钮存在时，它们是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一路径时，OpenClaw - 才应包含手动 `/approve` 命令。 + Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加审批人私信路由和频道扇出。 + 当这些按钮存在时，它们是主要审批 UX；OpenClaw + 只应在工具结果表示聊天审批不可用或手动审批是唯一路径时， + 才包含手动 `/approve` 命令。 如果 Discord 原生审批运行时未激活，OpenClaw 会保持 本地确定性的 `/approve ` 提示可见。如果 运行时已激活，但原生卡片无法投递到任何目标， - OpenClaw 会在同一聊天中发送回退通知，其中包含待处理审批里的准确 `/approve` + OpenClaw 会在同一聊天中发送回退通知，其中包含待处理审批中的精确 `/approve` 命令。 - Gateway 网关认证和审批解析遵循共享 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。审批默认在 30 分钟后过期。 + Gateway 网关认证和审批解析遵循共享 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。默认情况下，审批会在 30 分钟后过期。 参见 [执行审批](/zh-CN/tools/exec-approvals)。 -## 工具和动作门控 +## 工具和操作门控 -Discord 消息动作包括消息、频道管理、审核、在线状态和元数据动作。 +Discord 消息操作包括消息发送、频道管理、内容管理、在线状态和元数据操作。 核心示例： - 消息：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` - 回应：`react`、`reactions`、`emojiList` -- 审核：`timeout`、`kick`、`ban` +- 内容管理：`timeout`、`kick`、`ban` - 在线状态：`setPresence` -`event-create` 动作接受一个可选的 `image` 参数（URL 或本地文件路径），用于设置计划事件封面图。 +`event-create` 操作接受可选的 `image` 参数（URL 或本地文件路径），用于设置已计划事件的封面图像。 -动作门控位于 `channels.discord.actions.*` 下。 +操作门控位于 `channels.discord.actions.*` 下。 默认门控行为： -| 动作组 | 默认值 | +| 操作组 | 默认值 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 已启用 | +| 回应、消息、帖子串、置顶、投票、搜索、memberInfo、roleInfo、channelInfo、channels、voiceStatus、events、stickers、emojiUploads、stickerUploads、permissions | 已启用 | | roles | 已禁用 | -| moderation | 已禁用 | -| presence | 已禁用 | +| 内容管理 | 已禁用 | +| 在线状态 | 已禁用 | ## Components v2 UI -OpenClaw 使用 Discord components v2 处理执行审批和跨上下文标记。Discord 消息动作也可以接受 `components` 用于自定义 UI（高级用法；需要通过 discord 工具构造 component payload），而旧版 `embeds` 仍然可用，但不推荐。 +OpenClaw 使用 Discord components v2 处理执行审批和跨上下文标记。Discord 消息操作也可以接受 `components` 来构建自定义 UI（高级；需要通过 discord 工具构造组件载荷），而旧版 `embeds` 仍然可用，但不推荐使用。 -- `channels.discord.ui.components.accentColor` 设置 Discord component containers 使用的强调色（十六进制）。 -- 使用 `channels.discord.accounts..ui.components.accentColor` 按账号设置。 +- `channels.discord.ui.components.accentColor` 设置 Discord 组件容器使用的强调色（十六进制）。 +- 使用 `channels.discord.accounts..ui.components.accentColor` 为每个账号设置。 - 当 components v2 存在时，会忽略 `embeds`。 示例： @@ -978,16 +986,16 @@ OpenClaw 使用 Discord components v2 处理执行审批和跨上下文标记。 ## 语音 -Discord 有两个不同的语音表面：实时**语音频道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关支持两者。 +Discord 有两个不同的语音表面：实时**语音频道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。 ### 语音频道 -设置清单： +设置检查清单： -1. 在 Discord Developer Portal 中启用消息内容意图。 +1. 在 Discord 开发者门户中启用消息内容意图。 2. 使用角色/用户允许列表时，启用服务器成员意图。 -3. 使用 `bot` 和 `applications.commands` 作用域邀请机器人。 -4. 在目标语音频道中授予连接、发言、发送消息和读取消息历史权限。 +3. 使用 `bot` 和 `applications.commands` scope 邀请机器人。 +4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History 权限。 5. 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。 6. 配置 `channels.discord.voice`。 @@ -1028,34 +1036,34 @@ Discord 有两个不同的语音表面：实时**语音频道**（连续对话 说明： -- `voice.tts` 仅覆盖语音播放的 `messages.tts`。 -- `voice.model` 仅覆盖用于 Discord 语音频道响应的 LLM。保留未设置可继承路由后的智能体模型。 -- STT 使用 `tools.media.audio`；`voice.model` 不影响转写。 +- `voice.tts` 仅会覆盖语音播放的 `messages.tts`。 +- `voice.model` 仅会覆盖用于 Discord 语音频道响应的 LLM。留空则继承路由到的智能体模型。 +- STT 使用 `tools.media.audio`；`voice.model` 不影响转录。 - 语音转录轮次会从 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者说话者无法访问仅限所有者的工具（例如 `gateway` 和 `cron`）。 - 语音默认启用；设置 `channels.discord.voice.enabled=false` 可禁用语音运行时和 `GuildVoiceStates` Gateway 网关意图。 -- `channels.discord.intents.voiceStates` 可以显式覆盖语音状态意图订阅。保留未设置时，该意图会跟随 `voice.enabled`。 +- `channels.discord.intents.voiceStates` 可以显式覆盖语音状态意图订阅。留空则让该意图跟随 `voice.enabled`。 - `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 加入选项。 -- 如果未设置，`@discordjs/voice` 的默认值是 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 -- OpenClaw 还会监视接收解密失败，并在短时间窗口内重复失败后通过离开/重新加入语音频道自动恢复。 -- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 版本线包含来自 discord.js PR #11449 的上游填充修复，该 PR 关闭了 discord.js issue #11419。 +- 如果未设置，`@discordjs/voice` 默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 +- OpenClaw 还会监视接收解密失败，并在短时间窗口内反复失败后通过离开并重新加入语音频道自动恢复。 +- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 版本线包含来自 discord.js PR #11449 的上游 padding 修复，该修复关闭了 discord.js issue #11419。 语音频道流水线： - Discord PCM 捕获会转换为 WAV 临时文件。 - `tools.media.audio` 处理 STT，例如 `openai/gpt-4o-mini-transcribe`。 -- 转录会通过正常的 Discord 入口和路由发送。 -- 设置 `voice.model` 时，它仅覆盖该语音频道轮次的响应 LLM。 +- 转录文本会通过正常的 Discord 入口和路由发送。 +- 设置 `voice.model` 时，它只会覆盖此语音频道轮次的响应 LLM。 - `voice.tts` 会合并覆盖 `messages.tts`；生成的音频会在已加入的频道中播放。 凭证会按组件解析：`voice.model` 使用 LLM 路由认证，`tools.media.audio` 使用 STT 认证，`messages.tts`/`voice.tts` 使用 TTS 认证。 ### 语音消息 -Discord 语音消息会显示波形预览，并需要 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要 Gateway 网关主机上的 `ffmpeg` 和 `ffprobe` 来检查和转换。 +Discord 语音消息会显示波形预览，并要求使用 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要 Gateway 网关主机上有 `ffmpeg` 和 `ffprobe` 来检查和转换。 -- 提供**本地文件路径**（URL 会被拒绝）。 -- 省略文本内容（Discord 会拒绝同一载荷中的文本 + 语音消息）。 -- 接受任意音频格式；OpenClaw 会按需转换为 OGG/Opus。 +- 提供一个**本地文件路径**（URL 会被拒绝）。 +- 省略文本内容（Discord 会拒绝在同一个载荷中同时包含文本和语音消息）。 +- 接受任何音频格式；OpenClaw 会按需转换为 OGG/Opus。 ```bash message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) @@ -1064,19 +1072,19 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - 启用消息内容意图 - - 当你依赖用户/成员解析时，启用服务器成员意图 + - 依赖用户/成员解析时启用服务器成员意图 - 更改意图后重启 Gateway 网关 - + - 验证 `groupPolicy` - - 验证 `channels.discord.guilds` 下的服务器允许列表 - - 如果服务器 `channels` 映射存在，则只允许列出的频道 + - 验证 `channels.discord.guilds` 下的公会允许列表 + - 如果存在公会 `channels` 映射，则只允许列出的频道 - 验证 `requireMention` 行为和提及模式 有用的检查： @@ -1089,12 +1097,12 @@ openclaw logs --follow - + 常见原因： - - `groupPolicy="allowlist"` 但没有匹配的服务器/频道允许列表 - - `requireMention` 配置位置错误（必须位于 `channels.discord.guilds` 或频道条目下） - - 发送者被服务器/频道 `users` 允许列表阻止 + - `groupPolicy="allowlist"` 但没有匹配的公会/频道允许列表 + - `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或频道条目下） + - 发送者被公会/频道 `users` 允许列表阻止 @@ -1105,13 +1113,13 @@ openclaw logs --follow - `Slow listener detected ...` - `stuck session: sessionKey=agent:...:discord:... state=processing ...` - Discord Gateway 网关队列旋钮： + Discord Gateway 网关队列调节项： - 单账号：`channels.discord.eventQueue.listenerTimeout` - 多账号：`channels.discord.accounts..eventQueue.listenerTimeout` - - 这只控制 Discord Gateway 网关监听器工作，而不是智能体轮次生命周期 + - 这只控制 Discord Gateway 网关监听器工作，不控制智能体轮次生命周期 - Discord 不会对排队的智能体轮次应用频道拥有的超时。消息监听器会立即移交，排队的 Discord 运行会保留每个会话的顺序，直到会话/工具/运行时生命周期完成或中止工作。 + Discord 不会对已排队的智能体轮次应用频道拥有的超时。消息监听器会立即交接，已排队的 Discord 运行会保留每个会话的顺序，直到会话/工具/运行时生命周期完成或中止该工作。 ```json5 { @@ -1132,9 +1140,9 @@ openclaw logs --follow - OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。瞬时失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中限频记录。 + OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。瞬时失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中限速记录。 - 元数据超时旋钮： + 元数据超时调节项： - 单账号：`channels.discord.gatewayInfoTimeoutMs` - 多账号：`channels.discord.accounts..gatewayInfoTimeoutMs` @@ -1144,9 +1152,9 @@ openclaw logs --follow - `channels status --probe` 权限检查仅适用于数字频道 ID。 + `channels status --probe` 权限检查只适用于数字频道 ID。 - 如果你使用 slug 键，运行时匹配仍可工作，但探测无法完整验证权限。 + 如果你使用 slug 键，运行时匹配仍可能工作，但 probe 无法完整验证权限。 @@ -1158,23 +1166,23 @@ openclaw logs --follow - - 默认情况下，机器人撰写的消息会被忽略。 + + 默认会忽略机器人发送的消息。 - 如果设置 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则来避免循环行为。 + 如果你设置 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则来避免循环行为。 优先使用 `channels.discord.allowBots="mentions"`，只接受提及该机器人的机器人消息。 - - 保持 OpenClaw 为当前版本（`openclaw update`），以确保存在 Discord 语音接收恢复逻辑 - - 确认 `channels.discord.voice.daveEncryption=true`（默认） - - 从 `channels.discord.voice.decryptionFailureTolerance=24`（上游默认）开始，只在需要时调优 - - 观察日志中是否出现： + - 保持 OpenClaw 为当前版本（`openclaw update`），以确保 Discord 语音接收恢复逻辑可用 + - 确认 `channels.discord.voice.daveEncryption=true`（默认值） + - 从 `channels.discord.voice.decryptionFailureTolerance=24`（上游默认值）开始，只在需要时调整 + - 关注日志中的： - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - 如果自动重新加入后故障仍持续，请收集日志，并与 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) 和 [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) 中的上游 DAVE 接收历史进行比较 + - 如果自动重新加入后失败仍继续，请收集日志，并与 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) 和 [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) 中的上游 DAVE 接收历史进行比较 @@ -1185,33 +1193,33 @@ openclaw logs --follow -- 启动/认证：`enabled`、`token`、`accounts.*`、`allowBots` -- 策略：`groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*` -- 命令：`commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*` -- 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` +- 启动/认证：`enabled`, `token`, `accounts.*`, `allowBots` +- 策略：`groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` +- 命令：`commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` +- 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` - Gateway 网关元数据：`gatewayInfoTimeoutMs` -- 回复/历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` -- 投递：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` -- 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` +- 回复/历史：`replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- 投递：`textChunkLimit`, `chunkMode`, `maxLinesPerMessage` +- 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` - 媒体/重试：`mediaMaxMb`（限制出站 Discord 上传，默认 `100MB`）、`retry` - 操作：`actions.*` -- 在线状态：`activity`、`status`、`activityType`、`activityUrl` +- 在线状态：`activity`, `status`, `activityType`, `activityUrl` - UI：`ui.components.accentColor` -- 功能：`threadBindings`、顶层 `bindings[]`（`type: "acp"`）、`pluralkit`、`execApprovals`、`intents`、`agentComponents`、`heartbeat`、`responsePrefix` +- 功能：`threadBindings`、顶层 `bindings[]`（`type: "acp"`）、`pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` ## 安全和运维 -- 将机器人令牌视为机密（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 +- 将机器人 token 视为密钥（受监管环境中首选 `DISCORD_BOT_TOKEN`）。 - 授予最小权限的 Discord 权限。 -- 如果命令部署/状态过期，请重启 Gateway 网关，并用 `openclaw channels status --probe` 重新检查。 +- 如果命令部署/状态过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。 -## 相关内容 +## 相关 - 将 Discord 用户配对到 Gateway 网关。 + 将 Discord 用户与 Gateway 网关配对。 群聊和允许列表行为。 @@ -1223,7 +1231,7 @@ openclaw logs --follow 威胁模型和加固。 - 将服务器和频道映射到智能体。 + 将公会和频道映射到智能体。 原生命令行为。 diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 703e3be79..7dd0d1cca 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,62 +1,70 @@ --- read_when: - 设置 Slack 或调试 Slack socket/HTTP 模式 -summary: Slack 设置和运行时行为（Socket 模式 + HTTP 请求 URL） +summary: Slack 设置和运行时行为（套接字模式 + HTTP 请求 URL） title: Slack x-i18n: - generated_at: "2026-04-29T15:39:31Z" + generated_at: "2026-04-29T21:05:41Z" model: gpt-5.5 provider: openai - source_hash: e888211dc4729da87c2f2d269dca691aec280b5f09ceb3416f5ea16d7930cdd3 + source_hash: f4a991fccb938c133303624c8151bd15094cd4254ee9c9bd71649f1430aaa57c source_path: channels/slack.md workflow: 16 --- -Production-ready for DMs and channels via Slack app integrations. Default mode is Socket Mode; HTTP Request URLs are also supported. +可通过 Slack 应用集成用于生产环境中的私信和渠道。默认模式是 Socket Mode；也支持 HTTP Request URLs。 - - Slack DMs default to pairing mode. + + Slack 私信默认使用配对模式。 - - Native command behavior and command catalog. + + 原生命令行为和命令目录。 - - Cross-channel diagnostics and repair playbooks. + + 跨渠道诊断和修复手册。 -## Quick setup +## 快速设置 - + - - In Slack app settings press the **[Create New App](https://api.slack.com/apps/new)** button: + + 在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮： - - choose **from a manifest** and select a workspace for your app - - paste the [example manifest](#manifest-and-scope-checklist) from below and continue to create - - generate an **App-Level Token** (`xapp-...`) with `connections:write` - - install app and copy the **Bot Token** (`xoxb-...`) shown + - 选择 **from a manifest**，并为你的应用选择一个工作区 + - 粘贴下面的[示例清单](#manifest-and-scope-checklist)，然后继续创建 + - 生成一个具有 `connections:write` 的 **App-Level Token**（`xapp-...`） + - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） - + -```json5 + 推荐的 SecretRef 设置： + +```bash +export SLACK_APP_TOKEN=xapp-... +export SLACK_BOT_TOKEN=xoxb-... +cat > slack.socket.patch.json5 <<'JSON5' { channels: { slack: { enabled: true, mode: "socket", - appToken: "xapp-...", - botToken: "xoxb-...", + appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" }, + botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" }, }, }, } +JSON5 +openclaw config patch --file ./slack.socket.patch.json5 --dry-run +openclaw config patch --file ./slack.socket.patch.json5 ``` - Env fallback (default account only): + 环境变量回退（仅默认账户）： ```bash SLACK_APP_TOKEN=xapp-... @@ -65,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -78,41 +86,49 @@ openclaw gateway - - In Slack app settings press the **[Create New App](https://api.slack.com/apps/new)** button: + + 在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮： - - choose **from a manifest** and select a workspace for your app - - paste the [example manifest](#manifest-and-scope-checklist) and update the URLs before create - - save the **Signing Secret** for request verification - - install app and copy the **Bot Token** (`xoxb-...`) shown + - 选择 **from a manifest**，并为你的应用选择一个工作区 + - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL + - 保存用于请求验证的 **Signing Secret** + - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） - + -```json5 + 推荐的 SecretRef 设置： + +```bash +export SLACK_BOT_TOKEN=xoxb-... +export SLACK_SIGNING_SECRET=... +cat > slack.http.patch.json5 <<'JSON5' { channels: { slack: { enabled: true, mode: "http", - botToken: "xoxb-...", - signingSecret: "your-signing-secret", + botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" }, + signingSecret: { source: "env", provider: "default", id: "SLACK_SIGNING_SECRET" }, webhookPath: "/slack/events", }, }, } +JSON5 +openclaw config patch --file ./slack.http.patch.json5 --dry-run +openclaw config patch --file ./slack.http.patch.json5 ``` - Use unique webhook paths for multi-account HTTP + 为多账户 HTTP 使用唯一的 webhook 路径 - Give each account a distinct `webhookPath` (default `/slack/events`) so registrations do not collide. + 为每个账户提供不同的 `webhookPath`（默认 `/slack/events`），以免注册发生冲突。 - + ```bash openclaw gateway @@ -124,9 +140,9 @@ openclaw gateway -## Socket Mode transport tuning +## Socket Mode 传输调优 -OpenClaw sets the Slack SDK client pong timeout to 15 seconds by default for Socket Mode. Override the transport settings only when you need workspace- or host-specific tuning: +OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 秒。仅当你需要针对工作区或主机进行特定调优时，才覆盖传输设置： ```json5 { @@ -143,13 +159,13 @@ OpenClaw sets the Slack SDK client pong timeout to 15 seconds by default for Soc } ``` -Use this only for Socket Mode workspaces that log Slack websocket pong/server-ping timeouts or run on hosts with known event-loop starvation. `clientPingTimeout` is the pong wait after the SDK sends a client ping; `serverPingTimeout` is the wait for Slack server pings. App messages and events remain application state, not transport liveness signals. +仅对记录 Slack websocket pong/服务器 ping 超时，或运行在已知存在事件循环饥饿问题的主机上的 Socket Mode 工作区使用此设置。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。应用消息和事件仍然是应用状态，而不是传输活性信号。 -## Manifest and scope checklist +## 清单和 scope 检查清单 -The base Slack app manifest is the same for Socket Mode and HTTP Request URLs. Only the `settings` block (and the slash command `url`) differs. +基础 Slack 应用清单对于 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 块（以及 slash 命令的 `url`）不同。 -Base manifest (Socket Mode default): +基础清单（Socket Mode 默认）： ```json { @@ -221,7 +237,7 @@ Base manifest (Socket Mode default): } ``` -For **HTTP Request URLs mode**, replace `settings` with the HTTP variant and add `url` to each slash command. Public URL required: +对于 **HTTP Request URLs 模式**，将 `settings` 替换为 HTTP 变体，并为每个 slash 命令添加 `url`。需要公网 URL： ```json { @@ -251,22 +267,22 @@ For **HTTP Request URLs mode**, replace `settings` with the HTTP variant and add } ``` -### Additional manifest settings +### 其他清单设置 -Surface different features that extend the above defaults. +启用在上述默认设置之外的不同功能。 - + - Multiple [native slash commands](#commands-and-slash-behavior) can be used instead of a single configured command with nuance: + 可以使用多个[原生 slash 命令](#commands-and-slash-behavior)，而不是单个已配置命令，并提供更细的差异化行为： - - Use `/agentstatus` instead of `/status` because the `/status` command is reserved. - - No more than 25 slash commands can be made available at once. + - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已保留。 + - 一次最多可以提供 25 个 slash 命令。 - Replace your existing `features.slash_commands` section with a subset of [available commands](/zh-CN/tools/slash-commands#command-list): + 将现有 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的子集： - + ```json "slash_commands": [ @@ -383,7 +399,7 @@ Surface different features that extend the above defaults. - Use the same `slash_commands` list as Socket Mode above, and add `"url": "https://gateway-host.example.com/slack/events"` to every entry. Example: + 使用与上面 Socket Mode 相同的 `slash_commands` 列表，并为每一项添加 `"url": "https://gateway-host.example.com/slack/events"`。示例： ```json "slash_commands": [ @@ -406,14 +422,14 @@ Surface different features that extend the above defaults. - - Add the `chat:write.customize` bot scope if you want outgoing messages to use the active agent identity (custom username and icon) instead of the default Slack app identity. + + 如果你希望传出消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 - If you use an emoji icon, Slack expects `:emoji_name:` syntax. + 如果你使用 emoji 图标，Slack 需要 `:emoji_name:` 语法。 - - If you configure `channels.slack.userToken`, typical read scopes are: + + 如果你配置了 `channels.slack.userToken`，典型的读取 scope 包括： - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -421,41 +437,41 @@ Surface different features that extend the above defaults. - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (if you depend on Slack search reads) + - `search:read`（如果你依赖 Slack 搜索读取） -## Token model +## Token 模型 -- `botToken` + `appToken` are required for Socket Mode. -- HTTP mode requires `botToken` + `signingSecret`. -- `botToken`, `appToken`, `signingSecret`, and `userToken` accept plaintext - strings or SecretRef objects. -- Config tokens override env fallback. -- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env fallback applies only to the default account. -- `userToken` (`xoxp-...`) is config-only (no env fallback) and defaults to read-only behavior (`userTokenReadOnly: true`). +- Socket Mode 需要 `botToken` + `appToken`。 +- HTTP 模式需要 `botToken` + `signingSecret`。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 + 字符串或 SecretRef 对象。 +- 配置令牌会覆盖环境变量回退。 +- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账号。 +- `userToken`（`xoxp-...`）仅能通过配置提供（无环境变量回退），并默认采用只读行为（`userTokenReadOnly: true`）。 -Status snapshot behavior: +Status 快照行为： -- Slack 账号检查会跟踪每个凭据的 `*Source` 和 `*Status` +- Slack 账号检查会按凭证跟踪 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 - Status 为 `available`、`configured_unavailable` 或 `missing`。 - `configured_unavailable` 表示账号通过 SecretRef - 或其他非内联密钥来源配置，但当前命令/运行时路径 + 或其他非内联密钥来源进行了配置，但当前命令/运行时路径 无法解析实际值。 -- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下， +- 在 HTTP 模式下会包含 `signingSecretStatus`；在 Socket Mode 下， 必需的组合是 `botTokenStatus` + `appTokenStatus`。 -对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用 bot 令牌；只有当 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 +对于操作/目录读取，配置了用户令牌时可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；仅当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。 ## 操作和门控 Slack 操作由 `channels.slack.actions.*` 控制。 -当前 Slack 工具中的可用操作组： +当前 Slack 工具中可用的操作组： | 组 | 默认值 | | ---------- | ------- | @@ -465,7 +481,7 @@ 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，并对图片返回图片预览，或对其他文件类型返回本地文件元数据。 ## 访问控制和路由 @@ -483,16 +499,16 @@ 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`。 + - 具名账号在自身 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。 + - 具名账号不会继承 `channels.slack.accounts.default.allowFrom`。 - 旧版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的情况下，将它们迁移到 `dmPolicy` 和 `allowFrom`。 + 旧版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的情况下，尽可能将它们迁移到 `dmPolicy` 和 `allowFrom`。 私信中的配对使用 `openclaw pairing approve slack `。 @@ -505,28 +521,28 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `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` + - 入站授权和渠道路由默认优先使用 ID；直接用户名/短名匹配要求设置 `channels.slack.dangerouslyAllowNameMatching: true` - 渠道消息默认受提及门控。 + 渠道消息默认受提及门控限制。 提及来源： - 显式应用提及（`<@botId>`） - - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式回复 bot 线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） + - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） - 按渠道控制（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 使用）： + 按渠道控制（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching`）： - `requireMention` - `users`（允许列表） @@ -545,10 +561,10 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。 - 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。 - 渠道会话：`agent::slack:channel:`。 -- 线程回复可在适用时创建线程会话后缀（`:thread:`）。 -- `channels.slack.thread.historyScope` 默认值为 `thread`；`thread.inheritParent` 默认值为 `false`。 +- 线程回复在适用时可以创建线程会话后缀（`:thread:`）。 +- `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。 - `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时获取多少条现有线程消息（默认 `20`；设置为 `0` 可禁用）。 -- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，会抑制隐式线程提及，因此 bot 只会响应线程内显式 `@bot` 提及，即使 bot 已经参与该线程。如果不这样设置，bot 参与过的线程中的回复会绕过 `requireMention` 门控。 +- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，会抑制隐式线程提及，使机器人在线程内只响应显式 `@bot` 提及，即使机器人已经参与了该线程。否则，在机器人参与过的线程中，回复会绕过 `requireMention` 门控。 回复线程控制： @@ -562,10 +578,10 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `[[reply_to:]]` -`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这不同于 Telegram，后者在 `"off"` 模式下仍会遵循显式标签。Slack 线程会从渠道中隐藏消息，而 Telegram 回复仍以内联方式可见。 +`replyToMode="off"` 会在 Slack 中禁用**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这不同于 Telegram，后者在 `"off"` 模式下仍会遵循显式标签。Slack 线程会把消息从渠道中隐藏，而 Telegram 回复会继续以内联方式可见。 -## 确认响应表情 +## 确认回应表情 `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 @@ -578,8 +594,8 @@ Slack 操作由 `channels.slack.actions.*` 控制。 注意事项： -- Slack 需要短代码（例如 `"eyes"`）。 -- 使用 `""` 可为 Slack 账号或全局禁用该响应。 +- Slack 期望短代码（例如 `"eyes"`）。 +- 使用 `""` 可为 Slack 账号或全局禁用该回应。 ## 文本流式传输 @@ -589,18 +605,18 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `partial`（默认）：用最新的部分输出替换预览文本。 - `block`：追加分块预览更新。 - `progress`：生成期间显示进度状态文本，然后发送最终文本。 -- `streaming.preview.toolProgress`：草稿预览处于活动状态时，将工具/进度更新路由到同一条已编辑的预览消息中（默认：`true`）。设置为 `false` 可保留单独的工具/进度消息。 +- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一条经过编辑的预览消息中（默认：`true`）。设置为 `false` 可保留单独的工具/进度消息。 当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。 -- 必须有可用的回复线程，原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍遵循 `replyToMode`。 +- 必须存在回复线程，原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍遵循 `replyToMode`。 - 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。 -- 顶层 Slack 私信默认保持在线程外，因此不会显示线程样式预览；如果想在那里看到可见进度，请使用线程回复或 `typingReaction`。 +- 顶层 Slack 私信默认不进入线程，因此不会显示线程样式预览；如果你希望在那里显示可见进度，请使用线程回复或 `typingReaction`。 - 媒体和非文本载荷会回退到普通投递。 -- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在能就地编辑预览时才会刷新。 +- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在可以就地编辑预览时刷新。 - 如果流式传输在回复中途失败，OpenClaw 会对剩余载荷回退到普通投递。 -使用草稿预览，而不是 Slack 原生文本流式传输： +使用草稿预览而不是 Slack 原生文本流式传输： ```json5 { @@ -621,9 +637,9 @@ 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 消息添加一个临时回应，并在运行结束时移除它。这在线程回复之外最有用，因为线程回复会使用默认的“正在输入...”状态指示器。 解析顺序： @@ -632,18 +648,18 @@ Slack 操作由 `channels.slack.actions.*` 控制。 注意事项： -- Slack 需要短代码（例如 `"hourglass_flowing_sand"`）。 -- 该响应会尽力执行，并会在回复或失败路径完成后自动尝试清理。 +- Slack 期望短代码（例如 `"hourglass_flowing_sand"`）。 +- 该回应为尽力而为，并会在回复或失败路径完成后自动尝试清理。 ## 媒体、分块和投递 - Slack 文件附件会从 Slack 托管的私有 URL 下载（使用令牌认证请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以使用 `download-file` 获取原始文件。 + Slack 文件附件会从 Slack 托管的私有 URL 下载（经令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，以便智能体可以用 `download-file` 获取原始文件。 下载使用有界空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。 - 运行时入站大小上限默认为 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆盖。 + 运行时入站大小上限默认为 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。 @@ -651,7 +667,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 文本分块使用 `channels.slack.textChunkLimit`（默认 4000） - `channels.slack.chunkMode="newline"` 启用段落优先拆分 - 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`） - - 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送使用媒体管线中的 MIME 类型默认值 + - 配置时，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送使用媒体流水线中的 MIME 类型默认值 @@ -661,7 +677,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `user:` 用于私信 - `channel:` 用于渠道 - 发送到用户目标时，Slack 私信会通过 Slack conversation API 打开。 + 发送到用户目标时，Slack 私信会通过 Slack 会话 API 打开。 @@ -679,7 +695,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。 /openclaw /help ``` -原生命令需要在你的 Slack 应用中配置[额外清单设置](#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 原生命令。 @@ -687,7 +703,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。 /help ``` -原生参数菜单使用自适应渲染策略，在分派所选选项值之前显示确认模态框： +原生参数菜单使用自适应渲染策略，会在分派所选选项值之前显示确认模态框： - 最多 5 个选项：按钮块 - 6-100 个选项：静态选择菜单 @@ -698,11 +714,11 @@ Slack 操作由 `channels.slack.actions.*` 控制。 /think ``` -斜杠会话使用类似 `agent::slack:slash:` 的隔离键，并仍使用 `CommandTargetSessionKey` 将命令执行路由到目标会话。 +斜杠会话使用类似 `agent::slack:slash:` 的隔离键，并仍会使用 `CommandTargetSessionKey` 将命令执行路由到目标会话。 ## 交互式回复 -Slack 可以渲染智能体编写的交互式回复控件，但此功能默认禁用。 +Slack 可以渲染智能体创作的交互式回复控件，但此功能默认禁用。 全局启用： @@ -718,7 +734,7 @@ Slack 可以渲染智能体编写的交互式回复控件，但此功能默认 } ``` -或仅为一个 Slack 账号启用： +或仅为一个 Slack 账号启用它： ```json5 { @@ -736,41 +752,42 @@ 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 Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的 blocks 载荷。 +- 这是 Slack 专属 UI。其他渠道不会把 Slack Block Kit 指令转换为自己的按钮系统。 +- 交互回调值是 OpenClaw 生成的不透明令牌，而不是智能体编写的原始值。 +- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的 blocks 载荷。 -## Slack 中的 exec 审批 +## Slack 中的执行审批 -Slack 可以作为带有交互式按钮和交互的原生审批客户端，而不是回退到 Web UI 或终端。 +Slack 可以作为带有交互按钮和交互事件的原生审批客户端，而不是回退到 Web UI 或终端。 -- Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 -- 当请求已进入 Slack 且审批 id 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面完成。 -- 审批者授权仍会强制执行：只有被识别为审批者的用户才能通过 Slack 批准或拒绝请求。 +- 执行审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 +- 当请求已经到达 Slack 且审批 ID 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面解析。 +- 仍会强制执行审批人授权：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。 这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用 `interactivity` 时，审批提示会直接在对话中渲染为 Block Kit 按钮。 -当这些按钮存在时，它们是主要审批用户体验；OpenClaw 只有在工具结果表明聊天审批不可用或手动审批是唯一路径时，才应包含手动 `/approve` 命令。 +当这些按钮存在时，它们就是主要审批 UX；OpenClaw +仅应在工具结果表示聊天审批不可用或手动审批是唯一路径时，才包含手动 `/approve` 命令。 配置路径： - `channels.slack.execApprovals.enabled` - `channels.slack.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`） -- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`） +- `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 { @@ -780,7 +797,7 @@ Slack 可以作为带有交互式按钮和交互的原生审批客户端，而 } ``` -只有在你想覆盖审批者、添加过滤器，或选择启用来源聊天投递时，才需要显式 Slack 原生配置： +只有在你想覆盖审批人、添加筛选器或选择启用来源聊天投递时，才需要显式 Slack 原生配置： ```json5 { @@ -796,22 +813,24 @@ Slack 可以作为带有交互式按钮和交互的原生审批客户端，而 } ``` -共享的 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须路由到其他聊天或显式的带外目标时才使用它。共享的 `approvals.plugin` 转发也是独立的；当这些请求已进入 Slack 时，Slack 原生按钮仍可完成插件审批。 +共享 `approvals.exec` 转发是独立的。仅当执行审批提示还必须 +路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是 +独立的；当这些请求已经到达 Slack 时，Slack 原生按钮仍可解析插件审批。 -同一聊天中的 `/approve` 也适用于已支持命令的 Slack 渠道和私信。完整的审批转发模型请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。 +同聊天 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整审批转发模型见[执行审批](/zh-CN/tools/exec-approvals)。 -## 事件与运维行为 +## 事件和运维行为 - 消息编辑/删除会映射为系统事件。 -- 线程广播（“同时发送到渠道”的线程回复）会作为普通用户消息处理。 -- 添加/移除表情回应事件会映射为系统事件。 -- 成员加入/离开、渠道创建/重命名，以及图钉添加/移除事件会映射为系统事件。 -- 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。 -- 渠道主题/用途元数据会被视为不可信上下文，并可注入到路由上下文中。 -- 适用时，线程发起消息和初始线程历史上下文种子会按配置的发送者允许列表过滤。 -- Block 操作和模态框交互会发出带有丰富载荷字段的结构化 `Slack interaction: ...` 系统事件： - - block 操作：所选值、标签、选择器值，以及 `workflow_*` 元数据 - - 模态框 `view_submission` 和 `view_closed` 事件，包含路由后的渠道元数据和表单输入 +- 线程广播（“同时发送到渠道”的线程回复）会按普通用户消息处理。 +- 表情回应添加/移除事件会映射为系统事件。 +- 成员加入/离开、渠道创建/重命名，以及置顶添加/移除事件会映射为系统事件。 +- 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键名。 +- 渠道主题/用途元数据会被视为不可信上下文，并可注入路由上下文。 +- 适用时，线程发起消息和初始线程历史上下文种子会按配置的发送者允许列表筛选。 +- 块操作和模态交互会发出带有丰富载荷字段的结构化 `Slack interaction: ...` 系统事件： + - 块操作：所选值、标签、选择器值和 `workflow_*` 元数据 + - 模态 `view_submission` 和 `view_closed` 事件，带有路由后的渠道元数据和表单输入 ## 配置参考 @@ -819,9 +838,9 @@ Slack 可以作为带有交互式按钮和交互的原生审批客户端，而 -- 模式/认证：`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` @@ -838,7 +857,7 @@ Slack 可以作为带有交互式按钮和交互的原生审批客户端，而 - `groupPolicy` - 渠道允许列表（`channels.slack.channels`） - `requireMention` - - 每个渠道的 `users` 允许列表 + - 每渠道 `users` 允许列表 有用的命令： @@ -856,7 +875,9 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy`（或旧版 `channels.slack.dm.policy`） - 配对审批 / 允许列表条目 - - Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志通常表示 Slack 发送了一个编辑过的 Assistant 线程事件，但消息元数据中没有可恢复的人类发送者 + - Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志 + 通常表示 Slack 发送了一个已编辑的 Assistant 线程事件，但消息元数据中 + 没有可恢复的人类发送者 ```bash openclaw pairing list slack @@ -865,55 +886,59 @@ openclaw pairing list slack - 在 Slack 应用设置中验证 bot + app 令牌以及 Socket Mode 启用状态。 + 验证 Slack 应用设置中的机器人 + 应用令牌以及 Socket Mode 启用状态。 如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或 - `appTokenStatus: "configured_unavailable"`，说明 Slack 账号已配置，但当前运行时无法解析由 SecretRef 支持的值。 + `appTokenStatus: "configured_unavailable"`，则表示 Slack 账号已 + 配置，但当前运行时无法解析由 SecretRef 支持的 + 值。 - + 验证： - 签名密钥 - webhook 路径 - - Slack Request URL（Events + Interactivity + Slash Commands） - - 每个 HTTP 账号唯一的 `webhookPath` + - Slack Request URLs（Events + Interactivity + Slash Commands） + - 每个 HTTP 账号使用唯一的 `webhookPath` - 如果账号快照中出现 `signingSecretStatus: "configured_unavailable"`，说明 HTTP 账号已配置，但当前运行时无法解析由 SecretRef 支持的签名密钥。 + 如果账号快照中出现 `signingSecretStatus: "configured_unavailable"`， + 则表示 HTTP 账号已配置，但当前运行时无法 + 解析由 SecretRef 支持的签名密钥。 - - 确认你原本想使用的是： + + 验证你的预期是： - - 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册了匹配的 slash 命令 - - 或单一 slash 命令模式（`channels.slack.slashCommand.enabled: true`） + - 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册了匹配的斜杠命令 + - 或单斜杠命令模式（`channels.slack.slashCommand.enabled: true`） - 另请检查 `commands.useAccessGroups` 以及渠道/用户允许列表。 + 同时检查 `commands.useAccessGroups` 和渠道/用户允许列表。 ## 附件视觉参考 -当 Slack 文件下载成功且大小限制允许时，Slack 可以将下载的媒体附加到智能体回合。图像文件可以通过媒体理解路径传递，或直接传递给支持视觉的回复模型；其他文件会保留为可下载文件上下文，而不是作为图像输入处理。 +当 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 处理限制为每条消息最多八个文件 | +| 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 下载文件。 +1. OpenClaw 使用机器人令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。 2. 下载成功后，文件会写入媒体存储。 3. 下载的媒体路径和内容类型会添加到入站上下文。 4. 支持图像的模型/工具路径可以使用该上下文中的图像附件。 @@ -921,17 +946,17 @@ openclaw pairing list slack ### 线程根附件继承 -当消息进入线程（有 `thread_ts` 父级）时： +当消息到达线程中（有 `thread_ts` 父级）时： -- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件水合为线程发起消息上下文。 +- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以把根文件补充为线程发起消息上下文。 - 直接回复附件优先于根消息附件。 -- 只有文件且没有文本的根消息会用附件占位符表示，因此回退仍可包含其文件。 +- 只有文件而没有文本的根消息会用附件占位符表示，以便回退仍可包含其文件。 ### 多附件处理 当单条 Slack 消息包含多个文件附件时： -- 每个附件都会通过媒体流水线独立处理。 +- 每个附件都会通过媒体管线独立处理。 - 下载的媒体引用会聚合到消息上下文中。 - 处理顺序遵循事件载荷中的 Slack 文件顺序。 - 一个附件下载失败不会阻塞其他附件。 @@ -939,46 +964,46 @@ openclaw pairing list slack ### 大小、下载和模型限制 - **大小上限**：默认每个文件 20 MB。可通过 `channels.slack.mediaMaxMb` 配置。 -- **下载失败**：Slack 无法提供的文件、过期 URL、不可访问文件、超大文件，以及 Slack 认证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。 -- **视觉模型**：图像分析会在活动回复模型支持视觉时使用它，否则使用在 `agents.defaults.imageModel` 配置的图像模型。 +- **下载失败**：Slack 无法提供的文件、过期 URL、不可访问文件、超大文件，以及 Slack 凭证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。 +- **视觉模型**：当活动回复模型支持视觉时，图像分析使用该模型；否则使用 `agents.defaults.imageModel` 配置的图像模型。 ### 已知限制 | 场景 | 当前行为 | 解决方法 | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| Slack 文件 URL 已过期 | 跳过文件；不显示错误 | 在 Slack 中重新上传文件 | -| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用具备视觉能力的回复模型 | -| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，请增大 `channels.slack.mediaMaxMb` | -| 转发/共享的附件 | 文本以及 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新共享 | +| 已过期的 Slack 文件 URL | 跳过文件；不显示错误 | 在 Slack 中重新上传文件 | +| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用支持视觉的回复模型 | +| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，增大 `channels.slack.mediaMaxMb` | +| 转发/共享的附件 | 文本和 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新共享 | | PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉处理 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 | ### 相关文档 -- [媒体理解流水线](/zh-CN/nodes/media-understanding) +- [媒体理解管线](/zh-CN/nodes/media-understanding) - [PDF 工具](/zh-CN/tools/pdf) -- Epic: [#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) +- 史诗任务：[#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 网关配对。 - + 渠道和群组私信行为。 - + 将入站消息路由到智能体。 - + 威胁模型和加固。 - + 配置布局和优先级。 - + 命令目录和行为。 diff --git a/docs/zh-CN/cli/config.md b/docs/zh-CN/cli/config.md index 2edff0c5a..75bbb7e97 100644 --- a/docs/zh-CN/cli/config.md +++ b/docs/zh-CN/cli/config.md @@ -2,23 +2,23 @@ read_when: - 你想以非交互方式读取或编辑配置 sidebarTitle: Config -summary: 用于 `openclaw config` 的 CLI 参考（get/set/unset/file/schema/validate） +summary: 用于 `openclaw config` 的 CLI 参考（get/set/patch/unset/file/schema/validate） title: 配置 x-i18n: - generated_at: "2026-04-28T11:47:13Z" + generated_at: "2026-04-29T21:05:38Z" model: gpt-5.5 provider: openai - source_hash: 3e90f979a102a6c54f8458f8a2c7f36bec5b1e82ea4bdd30e9c3a4b1d903cf11 + source_hash: f1f55c4b932d469cb9112d9f55b66f0ff88dbe066250651df7a0a753060a223d source_path: cli/config.md workflow: 16 --- -`openclaw.json` 中用于非交互式编辑的配置助手：按路径获取/设置/取消设置/输出文件/输出 schema/验证值，并打印当前生效的配置文件。不带子命令运行时会打开配置向导（等同于 `openclaw configure`）。 +配置辅助工具用于在 `openclaw.json` 中进行非交互式编辑：按路径 get/set/patch/unset/file/schema/validate 值，并打印当前活动的配置文件。不带子命令运行会打开配置向导（等同于 `openclaw configure`）。 ## 根选项 - 不带子命令运行 `openclaw config` 时，可重复使用的引导式设置分区过滤器。 + 当你不带子命令运行 `openclaw config` 时，可重复使用的引导式设置分区过滤器。 支持的引导式分区：`workspace`、`model`、`web`、`gateway`、`daemon`、`channels`、`plugins`、`skills`、`health`。 @@ -38,6 +38,7 @@ openclaw config set agents.list[0].tools.exec.node "node-id-or-name" openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json +openclaw config patch --file ./openclaw.patch.json5 --dry-run openclaw config unset plugins.entries.brave.config.webSearch.apiKey openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run openclaw config validate @@ -49,17 +50,17 @@ openclaw config validate --json 将为 `openclaw.json` 生成的 JSON schema 以 JSON 形式打印到 stdout。 - - - 当前根配置 schema，以及用于编辑器工具的根 `$schema` 字符串字段。 + + - 当前根配置 schema，加上用于编辑器工具的根 `$schema` 字符串字段。 - Control UI 使用的字段 `title` 和 `description` 文档元数据。 - - 嵌套对象、通配符（`*`）和数组项（`[]`）节点在存在匹配字段文档时，会继承相同的 `title` / `description` 元数据。 - - `anyOf` / `oneOf` / `allOf` 分支在存在匹配字段文档时，也会继承相同的文档元数据。 - - 运行时清单可加载时，尽力提供实时插件 + 渠道 schema 元数据。 + - 当存在匹配的字段文档时，嵌套对象、通配符（`*`）和数组项（`[]`）节点会继承相同的 `title` / `description` 元数据。 + - 当存在匹配的字段文档时，`anyOf` / `oneOf` / `allOf` 分支也会继承相同的文档元数据。 + - 当可以加载运行时 manifest 时，尽力提供实时插件 + 渠道 schema 元数据。 - 即使当前配置无效，也会提供干净的回退 schema。 - - `config.schema.lookup` 会返回一个规范化的配置路径，包含浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据，以及直接子项摘要。可用于 Control UI 或自定义客户端中的路径级下钻。 + + `config.schema.lookup` 返回一个规范化配置路径，包含一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据，以及直接子项摘要。可在 Control UI 或自定义客户端中用于按路径深入查看。 @@ -67,7 +68,7 @@ openclaw config validate --json openclaw config schema ``` -如果要用其他工具检查或验证它，可以将其通过管道写入文件： +当你想用其他工具检查或验证它时，可以通过管道写入文件： ```bash openclaw config schema > openclaw.schema.json @@ -75,7 +76,7 @@ openclaw config schema > openclaw.schema.json ### 路径 -路径使用点号或方括号表示法： +路径使用点号或括号表示法： ```bash openclaw config get agents.defaults.workspace @@ -91,7 +92,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name" ## 值 -值会在可能时按 JSON5 解析；否则按字符串处理。使用 `--strict-json` 要求必须按 JSON5 解析。`--json` 仍作为旧版别名受支持。 +值会尽可能按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 要求必须按 JSON5 解析。`--json` 仍作为旧版别名受支持。 ```bash openclaw config set agents.defaults.heartbeat.every "0m" @@ -99,32 +100,32 @@ openclaw config set gateway.port 19001 --strict-json openclaw config set channels.whatsapp.groups '["*"]' --strict-json ``` -`config get --json` 会以 JSON 打印原始值，而不是终端格式化文本。 +`config get --json` 会将原始值以 JSON 打印，而不是打印终端格式化文本。 -对象赋值默认会替换目标路径。受保护的 map/list 路径通常保存用户添加的条目，例如 `agents.defaults.models`、`models.providers`、`models.providers..models`、`plugins.entries` 和 `auth.profiles`，除非传入 `--replace`，否则会拒绝移除现有条目的替换操作。 +默认情况下，对象赋值会替换目标路径。常用于保存用户新增条目的受保护 map/list 路径，例如 `agents.defaults.models`、`models.providers`、`models.providers..models`、`plugins.entries` 和 `auth.profiles`，会拒绝可能移除现有条目的替换，除非你传入 `--replace`。 -向这些 map 添加条目时使用 `--merge`： +向这些映射添加条目时使用 `--merge`： ```bash openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge ``` -仅当你确实希望提供的值成为完整目标值时，才使用 `--replace`。 +只有当你明确希望提供的值成为完整目标值时，才使用 `--replace`。 ## `config set` 模式 -`openclaw config set` 支持四种赋值样式： +`openclaw config set` 支持四种赋值方式： - + ```bash openclaw config set ``` - + ```bash openclaw config set channels.discord.token \ --ref-provider default \ @@ -132,8 +133,8 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll --ref-id DISCORD_BOT_TOKEN ``` - - 提供商构建器模式仅针对 `secrets.providers.` 路径： + + 提供商构建器模式仅面向 `secrets.providers.` 路径： ```bash openclaw config set secrets.providers.vault \ @@ -145,7 +146,7 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll ``` - + ```bash openclaw config set --batch-json '[ { @@ -167,12 +168,68 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll -SecretRef 赋值会在不受支持的运行时可变 surface 上被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook 令牌，以及 WhatsApp 凭证 JSON）。参阅 [SecretRef 凭证 Surface](/zh-CN/reference/secretref-credential-surface)。 +SecretRef 赋值会在不支持运行时可变的表面上被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook 令牌，以及 WhatsApp 凭证 JSON）。参见 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。 -批处理解析始终使用批处理负载（`--batch-json`/`--batch-file`）作为事实来源。`--strict-json` / `--json` 不会改变批处理解析行为。 +批量解析始终使用批量载荷（`--batch-json`/`--batch-file`）作为事实来源。`--strict-json` / `--json` 不会改变批量解析行为。 -JSON 路径/值模式仍同时支持 SecretRefs 和提供商： +## `config patch` + +当你想粘贴或通过管道传入一个配置形状的补丁，而不是运行许多基于路径的 `config set` 命令时，使用 `config patch`。输入是一个 JSON5 对象。对象会递归合并，数组和标量值会替换目标值，`null` 会删除目标路径。 + +```bash +openclaw config patch --file ./openclaw.patch.json5 --dry-run +openclaw config patch --file ./openclaw.patch.json5 +``` + +你也可以通过 stdin 传入补丁，这对远程设置脚本很有用： + +```bash +ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5 +ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5 +``` + +示例补丁： + +```json5 +{ + channels: { + slack: { + enabled: true, + mode: "socket", + botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" }, + appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" }, + groupPolicy: "open", + requireMention: false, + }, + discord: { + enabled: true, + token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" }, + dmPolicy: "disabled", + dm: { enabled: false }, + groupPolicy: "allowlist", + }, + }, + agents: { + defaults: { + model: { primary: "openai/gpt-5.5" }, + models: { + "openai/gpt-5.5": { params: { fastMode: true } }, + }, + }, + }, +} +``` + +当某个对象或数组必须精确变为提供的值，而不是被递归补丁处理时，使用 `--replace-path `： + +```bash +openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels' +``` + +`--dry-run` 会在不写入的情况下运行 schema 和 SecretRef 可解析性检查。默认情况下，dry-run 期间会跳过基于 exec 的 SecretRefs；当你明确希望 dry-run 执行提供商命令时，添加 `--allow-exec`。 + +JSON 路径/值模式仍然同时支持 SecretRefs 和提供商： ```bash openclaw config set channels.discord.token \ @@ -189,23 +246,23 @@ openclaw config set secrets.providers.vaultfile \ 提供商构建器目标必须使用 `secrets.providers.` 作为路径。 - + - `--provider-source ` - `--provider-timeout-ms `（`file`、`exec`） - + - `--provider-allowlist `（可重复） - + - `--provider-path `（必需） - `--provider-mode ` - `--provider-max-bytes ` - `--provider-allow-insecure-path` - + - `--provider-command `（必需） - `--provider-arg `（可重复） - `--provider-no-output-timeout-ms ` @@ -234,9 +291,9 @@ openclaw config set secrets.providers.vault \ --provider-timeout-ms 5000 ``` -## 空运行 +## Dry run -使用 `--dry-run` 验证变更而不写入 `openclaw.json`。 +使用 `--dry-run` 在不写入 `openclaw.json` 的情况下验证更改。 ```bash openclaw config set channels.discord.token \ @@ -261,26 +318,26 @@ openclaw config set channels.discord.token \ ``` - - - 构建器模式：对已变更的 refs/提供商运行 SecretRef 可解析性检查。 - - JSON 模式（`--strict-json`、`--json` 或批处理模式）：运行 schema 验证和 SecretRef 可解析性检查。 - - 对已知不受支持的 SecretRef 目标 surface，也会运行策略验证。 - - 策略检查会评估完整的变更后配置，因此父对象写入（例如将 `hooks` 设置为对象）无法绕过不受支持 surface 的验证。 - - 为避免命令副作用，空运行期间默认跳过 Exec SecretRef 检查。 - - 将 `--allow-exec` 与 `--dry-run` 一起使用，可选择启用 exec SecretRef 检查（这可能会执行提供商命令）。 - - `--allow-exec` 仅用于空运行；如果不带 `--dry-run` 使用则会报错。 + + - 构建器模式：对已更改的 refs/providers 运行 SecretRef 可解析性检查。 + - JSON 模式（`--strict-json`、`--json` 或批量模式）：运行 schema 验证以及 SecretRef 可解析性检查。 + - 策略验证也会针对已知不支持的 SecretRef 目标表面运行。 + - 策略检查会评估完整的更改后配置，因此父对象写入（例如将 `hooks` 设置为对象）无法绕过不支持表面的验证。 + - dry-run 期间默认跳过 exec SecretRef 检查，以避免命令副作用。 + - 将 `--allow-exec` 与 `--dry-run` 一起使用可选择启用 exec SecretRef 检查（这可能会执行提供商命令）。 + - `--allow-exec` 仅用于 dry-run；如果不与 `--dry-run` 一起使用会报错。 - + `--dry-run --json` 会打印机器可读报告： - - `ok`：空运行是否通过 + - `ok`：dry-run 是否通过 - `operations`：已评估的赋值数量 - `checks`：是否运行了 schema/可解析性检查 - `checks.resolvabilityComplete`：可解析性检查是否运行完成（跳过 exec refs 时为 false） - - `refsChecked`：空运行期间实际解析的 refs 数量 - - `skippedExecRefs`：因未设置 `--allow-exec` 而跳过的 exec refs 数量 - - `errors`：`ok=false` 时的结构化 schema/可解析性失败 + - `refsChecked`：dry-run 期间实际解析的 refs 数量 + - `skippedExecRefs`：由于未设置 `--allow-exec` 而跳过的 exec refs 数量 + - `errors`：当 `ok=false` 时的结构化 schema/可解析性失败信息 @@ -356,10 +413,10 @@ openclaw config set channels.discord.token \ - - `config schema validation failed`：你的变更后配置形状无效；修复路径/值或提供商/ref 对象形状。 - - `Config policy validation failed: unsupported SecretRef usage`：将该凭据移回明文/字符串输入，并仅在支持的表面上保留 SecretRefs。 - - `SecretRef assignment(s) could not be resolved`：当前无法解析引用的提供商/ref（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/源不匹配）。 - - `Dry run note: skipped exec SecretRef resolvability check(s)`：dry-run 跳过了 exec refs；如果你需要 exec 可解析性验证，请使用 `--allow-exec` 重新运行。 + - `config schema validation failed`：变更后的配置结构无效；修正路径/值或提供商/ref 对象结构。 + - `Config policy validation failed: unsupported SecretRef usage`：将该凭证移回明文/字符串输入，并仅在受支持的表面使用 SecretRefs。 + - `SecretRef assignment(s) could not be resolved`：当前无法解析引用的提供商/ref（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/来源不匹配）。 + - `Dry run note: skipped exec SecretRef resolvability check(s)`：dry-run 跳过了 exec 引用；如果你需要 exec 可解析性验证，请使用 `--allow-exec` 重新运行。 - 对于批处理模式，请修复失败条目，并在写入前重新运行 `--dry-run`。 @@ -367,13 +424,13 @@ openclaw config set channels.discord.token \ ## 写入安全 -`openclaw config set` 和其他 OpenClaw 拥有的配置写入器会在提交到磁盘前验证完整的变更后配置。如果新的载荷未通过 schema 验证，或看起来像破坏性覆盖，活动配置会保持不变，被拒绝的载荷会作为 `openclaw.json.rejected.*` 保存到旁边。 +`openclaw config set` 和其他 OpenClaw 拥有的配置写入器会在提交到磁盘前验证完整的变更后配置。如果新载荷未通过 schema 验证，或看起来像破坏性覆盖，活动配置会保持不变，被拒绝的载荷会作为 `openclaw.json.rejected.*` 保存在旁边。 -活动配置路径必须是常规文件。不支持通过符号链接布局的 `openclaw.json` 进行写入；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 +活动配置路径必须是普通文件。写入不支持符号链接的 `openclaw.json` 布局；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 -小改动优先使用 CLI 写入： +小幅编辑优先使用 CLI 写入： ```bash openclaw config set gateway.reload.mode hybrid --dry-run @@ -381,7 +438,7 @@ openclaw config set gateway.reload.mode hybrid openclaw config validate ``` -如果写入被拒绝，请检查保存的载荷并修复完整的配置形状： +如果写入被拒绝，请检查保存的载荷并修复完整配置结构： ```bash CONFIG="$(openclaw config file)" @@ -389,13 +446,13 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head openclaw config validate ``` -仍然允许直接用编辑器写入，但运行中的 Gateway 网关会在它们通过验证前将其视为不受信任。无效的直接编辑可以在启动或热重载期间从上次已知良好备份恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。 +仍然允许直接用编辑器写入，但运行中的 Gateway 网关会在它们通过验证前将其视为不可信。无效的直接编辑可能会在启动或热重载期间从最后已知良好的备份恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。 -整文件恢复仅用于全局损坏的配置，例如解析错误、根级 schema 失败、旧版迁移失败，或插件与根配置混合失败。如果验证只在 `plugins.entries....` 下失败，OpenClaw 会保留当前的 `openclaw.json`，并报告插件本地问题，而不是恢复 `.last-good`。这可以防止插件 schema 变更或 `minHostVersion` 偏差回滚无关的用户设置，例如模型、提供商、auth profiles、渠道、Gateway 网关暴露、工具、memory、browser 或 cron 配置。 +整文件恢复仅用于全局损坏的配置，例如解析错误、根级 schema 失败、旧版迁移失败，或插件与根配置同时失败。如果验证仅在 `plugins.entries....` 下失败，OpenClaw 会保留活动的 `openclaw.json`，并报告插件本地问题，而不是恢复 `.last-good`。这可以防止插件 schema 变更或 `minHostVersion` 偏差回滚无关的用户设置，例如模型、提供商、认证配置文件、渠道、Gateway 网关暴露、工具、内存、浏览器或 cron 配置。 ## 子命令 -- `config file`：打印活动配置文件路径（由 `OPENCLAW_CONFIG_PATH` 或默认位置解析）。该路径应指向常规文件，而不是符号链接。 +- `config file`：打印活动配置文件路径（从 `OPENCLAW_CONFIG_PATH` 或默认位置解析）。该路径应指向普通文件，而不是符号链接。 编辑后重启 Gateway 网关。 @@ -408,7 +465,7 @@ openclaw config validate openclaw config validate --json ``` -`openclaw config validate` 通过后，你可以使用本地 TUI，让嵌入式智能体在你从同一终端验证每项变更时，将活动配置与文档进行比较： +`openclaw config validate` 通过后，你可以使用本地 TUI，让嵌入式智能体在同一个终端中验证每项变更时，对照文档比较活动配置： 如果验证已经失败，请从 `openclaw configure` 或 `openclaw doctor --fix` 开始。`openclaw chat` 不会绕过无效配置保护。 @@ -418,7 +475,7 @@ openclaw config validate --json openclaw chat ``` -然后在 TUI 内： +然后在 TUI 中： ```text !openclaw config file @@ -440,11 +497,11 @@ openclaw chat 每次变更后重新运行 `openclaw config validate`。 - 如果验证通过但运行时仍然不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 来获取迁移和修复帮助。 + 如果验证通过但运行时仍不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 获取迁移与修复帮助。 -## 相关内容 +## 相关 - [CLI 参考](/zh-CN/cli) - [配置](/zh-CN/gateway/configuration) diff --git a/docs/zh-CN/install/exe-dev.md b/docs/zh-CN/install/exe-dev.md index d80c603fa..b3e4fb139 100644 --- a/docs/zh-CN/install/exe-dev.md +++ b/docs/zh-CN/install/exe-dev.md @@ -1,38 +1,38 @@ --- read_when: - - 你希望为 Gateway 网关使用一台低成本、始终在线的 Linux 主机 - - 你希望获得远程 Control UI 访问能力，而无需自行运行 VPS -summary: 在 exe.dev 上运行 OpenClaw Gateway 网关（VM + HTTPS 代理）以实现远程访问 + - 你想要一台用于 Gateway 网关的低成本、始终在线的 Linux 主机 + - 你想在不运行自己的 VPS 的情况下远程访问控制界面 +summary: 在 exe.dev 上运行 OpenClaw Gateway 网关（VM + HTTPS 代理）以进行远程访问 title: exe.dev x-i18n: - generated_at: "2026-04-27T07:11:38Z" - model: gpt-5.4 + generated_at: "2026-04-29T21:05:47Z" + model: gpt-5.5 provider: openai - source_hash: 98bc90ff26ce1773bd0e05f975fcc3427039e90ce50eca21bb2e8232f7ac730f + source_hash: b571f9b29bb2cca0f311db4188c922b2f70ee91cb48b233cf9922e57a7f05340 source_path: install/exe-dev.md - workflow: 15 + workflow: 16 --- -目标：让 OpenClaw Gateway 网关运行在 exe.dev VM 上，并可通过你的笔记本访问：`https://.exe.xyz` +目标：OpenClaw Gateway 网关在 exe.dev VM 上运行，并可从你的笔记本电脑通过以下地址访问：`https://.exe.xyz` -本页假设你使用的是 exe.dev 默认的 **exeuntu** 镜像。如果你选择了其他发行版，请相应调整软件包。 +本页假设使用 exe.dev 默认的 **exeuntu** 镜像。如果你选择了其他发行版，请相应映射软件包。 -## 面向初学者的快速路径 +## 初学者快速路径 1. [https://exe.new/openclaw](https://exe.new/openclaw) -2. 根据需要填写你的认证密钥 / 令牌 -3. 点击你 VM 旁边的 “Agent”，然后等待 Shelley 完成配置 -4. 打开 `https://.exe.xyz/`，并使用已配置的共享密钥进行身份验证（本指南默认使用令牌认证，但如果你切换 `gateway.auth.mode`，密码认证也可以使用） +2. 按需填写你的认证密钥/token +3. 点击 VM 旁边的“智能体”，并等待 Shelley 完成预配 +4. 打开 `https://.exe.xyz/`，并使用配置的共享密钥进行认证（本指南默认使用 token 认证，但如果你切换 `gateway.auth.mode`，密码认证也可用） 5. 使用 `openclaw devices approve ` 批准任何待处理的设备配对请求 -## 你需要准备的内容 +## 你需要准备 - exe.dev 账户 - 对 [exe.dev](https://exe.dev) 虚拟机的 `ssh exe.dev` 访问权限（可选） ## 使用 Shelley 自动安装 -Shelley 是 [exe.dev](https://exe.dev) 的智能体，可以通过我们的提示词立即安装 OpenClaw。使用的提示词如下： +Shelley 是 [exe.dev](https://exe.dev) 的智能体，可以使用我们的提示词即时安装 OpenClaw。使用的提示词如下： ``` Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-interactive and accept-risk flags for openclaw onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "openclaw devices list" and "openclaw devices approve ". Make sure the dashboard shows that OpenClaw's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be .exe.xyz, without port specification. @@ -40,9 +40,9 @@ Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-inter ## 手动安装 -## 1）创建 VM +## 1) 创建 VM -在你的设备上执行： +从你的设备运行： ```bash ssh exe.dev new @@ -55,17 +55,17 @@ ssh .exe.xyz ``` -请保持此 VM 为**有状态**。OpenClaw 会将 `openclaw.json`、每个智能体的 `auth-profiles.json`、会话以及渠道 / 提供商状态存储在 `~/.openclaw/` 下，并将工作区存储在 `~/.openclaw/workspace/` 下。 +保持这个 VM **有状态**。OpenClaw 会将 `openclaw.json`、每个智能体的 `auth-profiles.json`、会话以及渠道/提供商状态存储在 `~/.openclaw/` 下，并将工作区存储在 `~/.openclaw/workspace/` 下。 -## 2）安装前置依赖（在 VM 上） +## 2) 安装前置依赖（在 VM 上） ```bash sudo apt-get update sudo apt-get install -y git curl jq ca-certificates openssl ``` -## 3）安装 OpenClaw +## 3) 安装 OpenClaw 运行 OpenClaw 安装脚本： @@ -73,9 +73,9 @@ sudo apt-get install -y git curl jq ca-certificates openssl curl -fsSL https://openclaw.ai/install.sh | bash ``` -## 4）设置 nginx，将 OpenClaw 代理到端口 8000 +## 4) 设置 nginx，将 OpenClaw 代理到端口 8000 -编辑 `/etc/nginx/sites-enabled/default`，内容如下： +使用以下内容编辑 `/etc/nginx/sites-enabled/default` ``` server { @@ -107,15 +107,84 @@ server { } ``` -请覆盖转发头，而不是保留客户端提供的链式值。OpenClaw 只信任来自明确配置代理的转发 IP 元数据，而追加式的 `X-Forwarded-For` 链会被视为一种加固风险。 +覆盖转发标头，而不是保留客户端提供的链。 +OpenClaw 只信任来自显式配置代理的转发 IP 元数据， +而追加式 `X-Forwarded-For` 链会被视为强化安全风险。 -## 5）访问 OpenClaw 并授予权限 +## 5) 访问 OpenClaw 并授予权限 -访问 `https://.exe.xyz/`（参见新手引导期间的 Control UI 输出）。如果提示认证，请粘贴来自 VM 的已配置共享密钥。本指南使用令牌认证，因此可通过 `openclaw config get gateway.auth.token` 获取 `gateway.auth.token`（或使用 `openclaw doctor --generate-gateway-token` 生成一个）。如果你已将 Gateway 网关改为密码认证，请改用 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`。使用 `openclaw devices list` 和 `openclaw devices approve ` 批准设备。不确定时，可以直接在浏览器中使用 Shelley！ +访问 `https://.exe.xyz/`（参见新手引导中的 Control UI 输出）。如果它提示认证，请粘贴来自 VM 的已配置共享密钥。本指南使用 token 认证，因此使用 `openclaw config get gateway.auth.token` 获取 `gateway.auth.token`（或使用 `openclaw doctor --generate-gateway-token` 生成一个）。 +如果你已将 Gateway 网关改为密码认证，请改用 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`。 +使用 `openclaw devices list` 和 `openclaw devices approve ` 批准设备。不确定时，就从浏览器使用 Shelley！ + +## 远程渠道设置 + +对于远程主机，优先使用一次 `config patch` 调用，而不是多次 SSH 调用 `config set`。将真实 token 保存在 VM 环境或 `~/.openclaw/.env` 中，并且只在 `openclaw.json` 中放置 SecretRefs。 + +在 VM 上，让服务环境包含它所需的机密： + +```bash +cat >> ~/.openclaw/.env <<'EOF' +SLACK_BOT_TOKEN=xoxb-... +SLACK_APP_TOKEN=xapp-... +DISCORD_BOT_TOKEN=... +OPENAI_API_KEY=sk-... +EOF +``` + +从你的本地机器创建补丁文件，并将其通过管道传给 VM： + +```json5 +// openclaw.remote.patch.json5 +{ + secrets: { + providers: { + default: { source: "env" }, + }, + }, + channels: { + slack: { + enabled: true, + mode: "socket", + botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" }, + appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" }, + groupPolicy: "open", + requireMention: false, + }, + discord: { + enabled: true, + token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" }, + dmPolicy: "disabled", + dm: { enabled: false }, + groupPolicy: "allowlist", + }, + }, + agents: { + defaults: { + model: { primary: "openai/gpt-5.5" }, + models: { + "openai/gpt-5.5": { params: { fastMode: true } }, + }, + }, + }, +} +``` + +```bash +ssh .exe.xyz 'openclaw config patch --stdin --dry-run' < ./openclaw.remote.patch.json5 +ssh .exe.xyz 'openclaw config patch --stdin' < ./openclaw.remote.patch.json5 +ssh .exe.xyz 'openclaw gateway restart && openclaw health' +``` + +当嵌套允许列表应当精确变为补丁值时，使用 `--replace-path`，例如替换 Discord 渠道允许列表时： + +```bash +ssh .exe.xyz 'openclaw config patch --stdin --replace-path "channels.discord.guilds[\"123\"].channels"' < ./discord.patch.json5 +``` ## 远程访问 -远程访问由 [exe.dev](https://exe.dev) 的认证机制处理。默认情况下，来自端口 8000 的 HTTP 流量会转发到 `https://.exe.xyz`，并使用邮箱认证。 +远程访问由 [exe.dev](https://exe.dev) 的认证处理。默认情况下，来自端口 8000 的 HTTP 流量会通过电子邮件认证转发到 `https://.exe.xyz`。 ## 更新