diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index 90d319cae..03ff3b5e1 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -4,36 +4,36 @@ read_when: summary: Discord 机器人支持状态、功能和配置 title: Discord x-i18n: - generated_at: "2026-04-21T16:52:56Z" + generated_at: "2026-04-22T01:34:42Z" model: gpt-5.4 provider: openai - source_hash: 1681315a6c246c4b68347f5e22319e132f30ea4e29a19e7d1da9e83dce7b68d0 + source_hash: 613ae39bc4b8c5661cbaab4f70a57af584f296581c3ce54ddaef0feab44e7e42 source_path: channels/discord.md workflow: 15 --- # Discord（Bot API） -状态：已就绪，可通过官方 Discord gateway 用于私信和服务器频道。 +状态：已就绪，可通过官方 Discord gateway 用于私信和服务器渠道。 - Discord 私信默认使用配对模式。 + Discord 私信默认进入配对模式。 原生命令行为和命令目录。 - 跨渠道诊断和修复流程。 + 跨渠道诊断与修复流程。 ## 快速开始 -你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将其与 OpenClaw 配对。我们建议将你的机器人添加到你自己的私人服务器。如果你还没有，请先[创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 +你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将其与 OpenClaw 配对。我们建议你将机器人添加到你自己的私有服务器。如果你还没有，可以先[创建一个](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server)（选择 **Create My Own > For me and my friends**）。 - + 前往 [Discord Developer Portal](https://discord.com/developers/applications)，然后点击 **New Application**。给它起一个类似 “OpenClaw” 的名字。 点击侧边栏中的 **Bot**。将 **Username** 设置为你对 OpenClaw 智能体的称呼。 @@ -44,8 +44,8 @@ x-i18n: 仍然停留在 **Bot** 页面，向下滚动到 **Privileged Gateway Intents** 并启用： - **Message Content Intent**（必需） - - **Server Members Intent**（推荐；角色白名单和名称到 ID 匹配时必需） - - **Presence Intent**（可选；仅在需要在线状态更新时需要） + - **Server Members Intent**（推荐；角色白名单和名称到 ID 匹配需要它） + - **Presence Intent**（可选；仅在需要在线状态更新时才需要） @@ -53,14 +53,14 @@ x-i18n: 回到 **Bot** 页面顶部并点击 **Reset Token**。 - 尽管名字如此，这会生成你的第一个令牌——并没有真的在“重置”任何内容。 + 虽然名字是这样，但这会生成你的第一个令牌——并没有真的在“重置”任何东西。 - 复制该令牌并将其保存到某处。这就是你的 **Bot Token**，你很快就会用到它。 + 复制这个令牌并将其保存到某处。这就是你的 **Bot Token**，你很快就会用到它。 - + 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用于将机器人添加到你的服务器。 向下滚动到 **OAuth2 URL Generator** 并启用： @@ -77,30 +77,30 @@ x-i18n: - Attach Files - Add Reactions（可选） - 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该可以在 Discord 服务器中看到你的机器人了。 + 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 完成连接。现在你应该能在 Discord 服务器中看到你的机器人了。 回到 Discord 应用中，你需要启用开发者模式，这样才能复制内部 ID。 - 1. 点击 **User Settings**（头像旁边的齿轮图标）→ **Advanced** → 打开 **Developer Mode** + 1. 点击 **User Settings**（你头像旁边的齿轮图标）→ **Advanced** → 打开 **Developer Mode** 2. 在侧边栏中右键点击你的**服务器图标** → **Copy Server ID** 3. 右键点击你自己的**头像** → **Copy User ID** - 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存——你会在下一步将这三项都发送给 OpenClaw。 + 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存——下一步你需要把这三个信息都发送给 OpenClaw。 - 为了让配对生效，Discord 需要允许你的机器人向你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 + 为了让配对正常工作，Discord 需要允许你的机器人向你发送私信。右键点击你的**服务器图标** → **Privacy Settings** → 打开 **Direct Messages**。 - 这会允许服务器成员（包括机器人）向你发送私信。如果你想在 OpenClaw 中使用 Discord 私信，请保持启用。如果你只打算使用服务器频道，那么可以在配对完成后关闭私信。 + 这样服务器成员（包括机器人）就可以向你发送私信。如果你想在 OpenClaw 中使用 Discord 私信，请保持此选项开启。如果你只打算使用服务器渠道，那么在配对完成后可以关闭私信。 - 你的 Discord 机器人令牌是一个机密信息（类似密码）。在向你的智能体发送消息之前，请先在运行 OpenClaw 的机器上设置它。 + 你的 Discord 机器人令牌是一个秘密信息（类似密码）。在给你的智能体发消息之前，请先在运行 OpenClaw 的机器上设置它。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -110,19 +110,19 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - 如果 OpenClaw 已经作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。 + 如果 OpenClaw 已经作为后台服务在运行，请通过 OpenClaw Mac 应用重启它，或者停止并重新启动 `openclaw gateway run` 进程。 - + - - 在任何现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天，并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。 + + 在任意现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / config 选项卡。 - > “我已经在配置中设置了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” + > “我已经在配置中设置好了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” - + 如果你更喜欢基于文件的配置，请设置： ```json5 @@ -146,7 +146,7 @@ openclaw gateway DISCORD_BOT_TOKEN=... ``` - 支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商的 SecretRef 值。参见[Secrets Management](/zh-CN/gateway/secrets)。 + 支持明文 `token` 值。`channels.discord.token` 也支持通过 env/file/exec 提供商使用 SecretRef 值。参见 [Secrets Management](/zh-CN/gateway/secrets)。 @@ -154,10 +154,10 @@ DISCORD_BOT_TOKEN=... - 等待 Gateway 网关运行起来，然后在 Discord 中向你的机器人发送私信。它会回复一个配对码。 + 等待 Gateway 网关运行后，在 Discord 中向你的机器人发送私信。它会回复一个配对码。 - + 在你现有的渠道中，将配对码发送给你的智能体： > “批准这个 Discord 配对码：``” @@ -174,27 +174,27 @@ openclaw pairing approve discord 配对码会在 1 小时后过期。 - 现在你应该可以通过 Discord 私信与你的智能体聊天了。 + 现在你应该已经可以通过 Discord 私信与你的智能体聊天了。 -令牌解析具有账户感知能力。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 -对于高级出站调用（消息工具/渠道操作），每次调用都会使用显式的每次调用 `token`。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍然来自活动运行时快照中所选的账户。 +令牌解析支持账户感知。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 +对于高级出站调用（消息工具/渠道操作），该次调用会使用显式的逐次 `token`。这适用于发送以及读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略和重试设置仍然来自活动运行时快照中所选账户。 -## 推荐：设置服务器工作区 +## 推荐：设置一个服务器工作区 -一旦私信可用，你就可以将 Discord 服务器设置为完整工作区，其中每个频道都有自己的智能体会话和各自的上下文。这对于只有你和你的机器人的私人服务器来说是推荐做法。 +当私信可用后，你可以将 Discord 服务器设置为一个完整工作区，其中每个渠道都会拥有各自独立上下文的智能体会话。对于只有你和机器人使用的私有服务器，我们推荐这样做。 - - 这样你的智能体就可以在你的服务器中的任何频道中响应，而不仅仅是私信。 + + 这样你的智能体就可以在你服务器中的任意渠道响应，而不仅仅是私信。 - - > “将我的 Discord Server ID `` 添加到服务器允许列表” + + > “把我的 Discord Server ID `` 添加到服务器白名单” @@ -219,15 +219,15 @@ openclaw pairing approve discord - - 默认情况下，你的智能体只会在被 @ 提及时在服务器频道中响应。对于私人服务器，你大概率会希望它对每条消息都作出响应。 + + 默认情况下，你的智能体只会在被 @ 提及时才会在服务器渠道中回复。对于私有服务器，你大概率希望它对每条消息都进行回复。 - - > “允许我的智能体在这个服务器中无需被 @ 提及也能响应” + + > “允许我的智能体在这个服务器中无需被 @ 提及也能回复” - 在你的服务器配置中将 `requireMention: false` 设置为： + 在你的服务器配置中设置 `requireMention: false`： ```json5 { @@ -248,82 +248,82 @@ openclaw pairing approve discord - - 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。服务器频道不会自动加载 MEMORY.md。 + + 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。服务器渠道不会自动加载 MEMORY.md。 - - > “当我在 Discord 频道中提问时，如果你需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。” + + > “当我在 Discord 渠道里提问时，如果你需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。” - 如果你需要在每个频道中都有共享上下文，请将稳定的说明放在 `AGENTS.md` 或 `USER.md` 中（它们会被注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并按需通过记忆工具访问它们。 + 如果你需要在每个渠道中共享上下文，请将稳定说明放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并按需通过 memory 工具访问。 -现在，在你的 Discord 服务器中创建一些频道并开始聊天。你的智能体可以看到频道名称，并且每个频道都有自己隔离的会话——因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的频道。 +现在，在你的 Discord 服务器中创建一些渠道并开始聊天吧。你的智能体可以看到渠道名称，并且每个渠道都会获得各自独立隔离的会话——因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的渠道。 ## 运行时模型 -- Gateway 网关负责 Discord 连接。 -- 回复路由是确定性的：从 Discord 进入的消息会回复到 Discord。 +- Gateway 网关负责维护 Discord 连接。 +- 回复路由是确定性的：来自 Discord 的入站回复会返回到 Discord。 - 默认情况下（`session.dmScope=main`），私聊共享智能体主会话（`agent:main:main`）。 -- 服务器频道使用隔离的会话键（`agent::discord:channel:`）。 -- 默认忽略群组私信（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 到被路由的对话会话。 +- 服务器渠道使用隔离的会话键（`agent::discord:channel:`）。 +- 群组私信默认会被忽略（`channels.discord.dm.groupEnabled=false`）。 +- 原生斜杠命令运行在隔离的命令会话中（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 指向被路由的对话会话。 -## Forum 频道 +## 论坛渠道 -Discord 的 forum 和 media 频道只接受帖子线程。OpenClaw 支持两种创建方式： +Discord 的 forum 和 media 渠道仅接受帖子线程。OpenClaw 支持两种创建方式： -- 向 forum 父频道（`channel:`）发送消息以自动创建线程。线程标题使用你消息中的第一行非空文本。 -- 使用 `openclaw message thread create` 直接创建线程。对于 forum 频道，不要传递 `--message-id`。 +- 向论坛父级渠道（`channel:`）发送消息，以自动创建线程。线程标题会使用消息中第一行非空内容。 +- 使用 `openclaw message thread create` 直接创建线程。对于 forum 渠道，不要传递 `--message-id`。 -示例：发送到 forum 父频道以创建线程 +示例：向论坛父级渠道发送消息以创建线程 ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -示例：显式创建 forum 线程 +示例：显式创建一个 forum 线程 ```bash openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -Forum 父频道不接受 Discord 组件。如果你需要组件，请发送到线程本身（`channel:`）。 +论坛父级渠道不接受 Discord components。如果你需要 components，请发送到线程本身（`channel:`）。 ## 交互式组件 -OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带有 `components` 负载的消息工具。交互结果会像普通入站消息一样路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 +OpenClaw 支持在智能体消息中使用 Discord components v2 容器。使用消息工具并传入 `components` 负载即可。交互结果会像普通入站消息一样回传给智能体，并遵循现有的 Discord `replyToMode` 设置。 支持的块： - `text`、`section`、`separator`、`actions`、`media-gallery`、`file` -- 操作行最多允许 5 个按钮或单个选择菜单 +- 操作行最多允许 5 个按钮，或 1 个单独的选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，组件是一次性使用的。设置 `components.reusable=true` 可允许按钮、选择器和表单在过期前被多次使用。 +默认情况下，components 为一次性使用。设置 `components.reusable=true` 可让按钮、选择器和表单在过期前可被多次使用。 -要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 +若要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签，或 `*`）。配置后，不匹配的用户将收到一条临时拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商和模型下拉菜单，以及一个 Submit 步骤。选择器回复是临时的，并且只有调用它的用户可以使用。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商和模型下拉框，以及一个提交步骤。选择器回复是临时的，且仅调用它的用户可以使用。 文件附件： -- `file` 块必须指向附件引用（`attachment://`） +- `file` 块必须指向一个附件引用（`attachment://`） - 通过 `media`/`path`/`filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery` -- 当上传名称应与附件引用一致时，使用 `filename` 覆盖上传名称 +- 当上传名称需要与附件引用匹配时，使用 `filename` 覆盖上传名称 模态表单： - 添加 `components.modal`，最多可包含 5 个字段 - 字段类型：`text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` -- OpenClaw 会自动添加一个触发按钮 +- OpenClaw 会自动添加一个触发表单的按钮 示例： @@ -379,7 +379,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` -## 访问控制和路由 +## 访问控制与路由 @@ -395,15 +395,15 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 多账户优先级： - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账户。 - - 已命名账户在其自身 `allowFrom` 未设置时，会继承 `channels.discord.allowFrom`。 + - 已命名账户在自身 `allowFrom` 未设置时，会继承 `channels.discord.allowFrom`。 - 已命名账户不会继承 `channels.discord.accounts.default.allowFrom`。 用于投递的私信目标格式： - `user:` - - `<@id>` 提及 + - `<@id>` mention - 纯数字 ID 存在歧义，除非显式提供 user/channel 目标类型，否则会被拒绝。 + 裸数字 ID 存在歧义，除非显式提供用户/渠道目标类型，否则会被拒绝。 @@ -419,11 +419,11 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 `allowlist` 行为： - 服务器必须匹配 `channels.discord.guilds`（优先使用 `id`，也接受 slug） - - 可选的发送者允许列表：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果任一项已配置，则发送者在匹配 `users` 或 `roles` 时被允许 - - 默认禁用直接名称/标签匹配；仅在紧急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` + - 可选的发送者白名单：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了其中任意一项，则发送者在匹配 `users` 或 `roles` 时被允许 + - 直接名称/标签匹配默认禁用；仅在紧急兼容模式下才启用 `channels.discord.dangerouslyAllowNameMatching: true` - `users` 支持名称/标签，但 ID 更安全；当使用名称/标签条目时，`openclaw security audit` 会发出警告 - - 如果某个服务器配置了 `channels`，则未列出的频道会被拒绝 - - 如果某个服务器没有 `channels` 块，则该允许列表中的服务器内所有频道都被允许 + - 如果某个服务器配置了 `channels`，则未列出的渠道会被拒绝 + - 如果某个服务器没有 `channels` 块，则该已加入白名单的服务器中的所有渠道都被允许 示例： @@ -449,33 +449,33 @@ 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` 也是如此。 - - 默认情况下，服务器消息受提及门控。 + + 默认情况下，服务器消息需要 mention 才会触发。 - 提及检测包括： + mention 检测包括： - 显式提及机器人 - - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） - - 在受支持场景下隐式回复机器人行为 + - 已配置的 mention 模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） + - 在受支持情况下，隐式回复机器人行为 - `requireMention` 按服务器/频道配置（`channels.discord.guilds...`）。 - `ignoreOtherMentions` 可选地丢弃提及了其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 + `requireMention` 按服务器/渠道配置（`channels.discord.guilds...`）。 + `ignoreOtherMentions` 可选择性丢弃那些提及了其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 群组私信： - 默认：忽略（`dm.groupEnabled=false`） - - 可选允许列表：通过 `dm.groupChannels`（频道 ID 或 slug） + - 可选：通过 `dm.groupChannels` 白名单启用（渠道 ID 或 slug） ### 基于角色的智能体路由 -使用 `bindings[].match.roles` 按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并且会在 peer 或 parent-peer 绑定之后、guild-only 绑定之前进行评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 +使用 `bindings[].match.roles` 可按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并且会在 peer 或 parent-peer 绑定之后、guild-only 绑定之前进行评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 ```json5 { @@ -516,16 +516,16 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - Message Content Intent - Server Members Intent（推荐） - Presence intent 是可选的，只有当你想接收在线状态更新时才需要。设置机器人在线状态（`setPresence`）不需要为成员启用在线状态更新。 + Presence intent 为可选项，只有当你希望接收在线状态更新时才需要。设置机器人在线状态（`setPresence`）并不要求为成员启用在线状态更新。 - + OAuth URL 生成器： - scopes：`bot`、`applications.commands` - 典型的基础权限： + 典型的基线权限： - View Channels - Send Messages @@ -542,21 +542,21 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 启用 Discord Developer Mode，然后复制： - 服务器 ID - - 频道 ID + - 渠道 ID - 用户 ID - 在 OpenClaw 配置中优先使用数字 ID，以获得可靠的审计和探测结果。 + 在 OpenClaw 配置中优先使用数字 ID，以获得更可靠的审计和探测结果。 -## 原生命令和命令认证 +## 原生命令与命令鉴权 - `commands.native` 默认为 `"auto"`，并且对 Discord 已启用。 - 按渠道覆盖：`channels.discord.commands.native`。 - `commands.native=false` 会显式清除先前已注册的 Discord 原生命令。 -- 原生命令认证使用与普通消息处理相同的 Discord 允许列表/策略。 -- 即使用户未被授权，命令仍可能在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 认证，并返回“未授权”。 +- 原生命令鉴权使用与普通消息处理相同的 Discord 白名单/策略。 +- 对于未获授权的用户，这些命令在 Discord UI 中仍可能可见；但执行时仍会强制执行 OpenClaw 鉴权，并返回“未授权”。 命令目录和行为请参见[斜杠命令](/zh-CN/tools/slash-commands)。 @@ -567,7 +567,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 ## 功能细节 - + Discord 支持在智能体输出中使用回复标签： - `[[reply_to_current]]` @@ -580,24 +580,25 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `all` - `batched` - 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍然有效。 - `first` 总是会将隐式原生回复引用附加到该轮次的第一条出站 Discord 消息上。 - `batched` 仅在入站轮次是由多条消息去抖后合并成的批次时，才附加 Discord 的隐式原生回复引用。这在你主要希望对模糊的突发聊天使用原生回复，而不是对每个单条消息轮次都使用时很有用。 + 注意：`off` 会禁用隐式回复线程。显式的 `[[reply_to_*]]` 标签仍会被遵循。 + `first` 会始终将隐式原生回复引用附加到该轮的第一条出站 Discord 消息上。 + `batched` 仅在入站轮次是由多条消息去抖后的批处理时，才会附加 Discord 的隐式原生回复引用。这在你主要希望在含糊不清、短时间大量消息的聊天中使用原生回复，而不是对每一个单条消息轮次都使用时很有用。 - 消息 ID 会在上下文/历史中暴露，因此智能体可以定位到特定消息。 + 消息 ID 会在上下文/历史中呈现，因此智能体可以定向回复特定消息。 - OpenClaw 可以通过发送临时消息并在文本到达时编辑它来流式传输草稿回复。 + OpenClaw 可以通过发送一条临时消息并在文本到达时持续编辑它，来流式显示草稿回复。 - `channels.discord.streaming` 控制预览流式传输（`off` | `partial` | `block` | `progress`，默认：`off`）。 - - 默认保持 `off`，因为 Discord 的预览编辑可能很快触发速率限制，尤其是在多个机器人或 Gateway 网关共享同一账户或服务器流量时。 - - `progress` 为了跨渠道一致性而被接受，并在 Discord 上映射为 `partial`。 + - 默认保持为 `off`，因为 Discord 的预览编辑很容易触发速率限制，尤其是在多个机器人或 Gateway 网关共享同一账户或服务器流量时。 + - `progress` 出于跨渠道一致性而被接受，并在 Discord 上映射为 `partial`。 - `channels.discord.streamMode` 是旧版别名，会被自动迁移。 - - `partial` 会在 token 到达时编辑单条预览消息。 + - `partial` 会在 token 到达时编辑同一条预览消息。 - `block` 会输出草稿大小的分块（使用 `draftChunk` 调整大小和断点）。 - - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条草稿预览消息（默认：`true`）。设置为 `false` 可保留单独的工具/进度消息。 + - 媒体、错误和显式回复的最终消息会取消待处理的预览编辑，而不会在正常投递前强制发送一条临时草稿。 + - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条草稿预览消息（默认：`true`）。设置为 `false` 可保留独立的工具/进度消息。 示例： @@ -611,7 +612,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - `block` 模式的默认分块设置（限制在 `channels.discord.textChunkLimit` 范围内）： + `block` 模式的默认分块设置（会被限制在 `channels.discord.textChunkLimit` 范围内）： ```json5 { @@ -628,13 +629,13 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 预览流式传输仅支持文本；媒体回复会回退到普通投递。 + 预览流式传输仅支持文本；媒体回复会回退为正常投递。 - 注意：预览流式传输与分块流式传输是分开的。当为 Discord 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 + 注意：预览流式传输与分块流式传输是分开的。当 Discord 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - + 服务器历史上下文： - `channels.discord.historyLimit` 默认值为 `20` @@ -648,26 +649,26 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 线程行为： - - Discord 线程会作为频道会话进行路由 + - Discord 线程会作为渠道会话进行路由 - 父线程元数据可用于父会话关联 - - 线程配置会继承父频道配置，除非存在线程专用条目 + - 线程配置会继承父渠道配置，除非存在线程专用条目 - 频道主题会作为**不受信任**的上下文注入（而不是作为系统提示词）。 - 回复和引用消息上下文目前保持接收时的原样。 - Discord 允许列表主要用于控制谁可以触发智能体，而不是一个完整的补充上下文脱敏边界。 + 渠道主题会作为**不受信任**的上下文注入（而不是作为系统提示词）。 + 回复和引用消息上下文目前会按接收时的样子保留。 + Discord 白名单主要用于限制谁可以触发智能体，并不是一个完整的补充上下文脱敏边界。 - - Discord 可以将线程绑定到某个会话目标，以便该线程中的后续消息持续路由到同一会话（包括子智能体会话）。 + + Discord 可以将一个线程绑定到某个会话目标，这样该线程中的后续消息会持续路由到同一个会话（包括子智能体会话）。 命令： - - `/focus ` 将当前/新线程绑定到某个子智能体/会话目标 + - `/focus ` 将当前/新线程绑定到子智能体/会话目标 - `/unfocus` 移除当前线程绑定 - - `/agents` 显示活动运行和绑定状态 + - `/agents` 显示活跃运行和绑定状态 - `/session idle ` 查看/更新聚焦绑定的空闲自动取消聚焦设置 - - `/session max-age ` 查看/更新聚焦绑定的硬性最大时长设置 + - `/session max-age ` 查看/更新聚焦绑定的硬性最大存续时间设置 配置： @@ -696,23 +697,23 @@ 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 })`）自动创建/绑定线程。 + - `channels.discord.threadBindings.*` 覆盖 Discord 行为。 + - 若要为 `sessions_spawn({ thread: true })` 自动创建/绑定线程，必须将 `spawnSubagentSessions` 设为 true。 + - 若要为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定线程，必须将 `spawnAcpSessions` 设为 true。 - 如果某个账户禁用了线程绑定，则 `/focus` 和相关线程绑定操作不可用。 - 参见[子智能体](/zh-CN/tools/subagents)、[ACP Agents](/zh-CN/tools/acp-agents) 和[配置参考](/zh-CN/gateway/configuration-reference)。 + 参见[子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents) 和[配置参考](/zh-CN/gateway/configuration-reference)。 - - 对于稳定的“始终在线” ACP 工作区，配置顶层类型化 ACP 绑定，并将其目标指向 Discord 对话。 + + 对于稳定的“始终在线” ACP 工作区，可配置面向 Discord 对话的顶层类型化 ACP 绑定。 配置路径： -- `bindings[]`，其中 `type: "acp"` 且 `match.channel: "discord"` + - `bindings[]`，并设置 `type: "acp"` 和 `match.channel: "discord"` -示例： + 示例： ```json5 { @@ -760,34 +761,34 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` -说明： + 说明： -- `/acp spawn codex --bind here` 会在当前位置绑定当前 Discord 频道或线程，并让后续消息持续路由到同一个 ACP 会话。 -- 这仍然可能意味着“启动一个全新的 Codex ACP 会话”，但它本身不会创建新的 Discord 线程。现有频道仍然是聊天界面。 -- Codex 仍然可能在它自己的 `cwd` 或磁盘上的后端工作区中运行。该工作区是运行时状态，不是 Discord 线程。 -- 线程消息可以继承父频道的 ACP 绑定。 -- 在已绑定的频道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。 -- 临时线程绑定仍然有效，并且在激活期间可以覆盖目标解析。 -- 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子线程时，才需要 `spawnAcpSessions`。对于当前频道中的 `/acp spawn ... --bind here`，不需要它。 + - `/acp spawn codex --bind here` 会就地绑定当前 Discord 渠道或线程，并让后续消息持续路由到同一个 ACP 会话。 + - 这仍然可能意味着“启动一个全新的 Codex ACP 会话”，但它本身不会创建新的 Discord 线程。现有渠道仍然是聊天界面。 + - Codex 仍可能在它自己的 `cwd` 或磁盘上的 backend 工作区中运行。该工作区属于运行时状态，而不是 Discord 线程。 + - 线程消息可以继承父渠道的 ACP 绑定。 + - 在已绑定的渠道或线程中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。 + - 临时线程绑定仍然可用，并且在激活期间可以覆盖目标解析。 + - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子线程时，才需要 `spawnAcpSessions`。在当前渠道中使用 `/acp spawn ... --bind here` 时则不需要。 -绑定行为详情请参见 [ACP Agents](/zh-CN/tools/acp-agents)。 + 绑定行为详情请参见 [ACP 智能体](/zh-CN/tools/acp-agents)。 - - 按服务器配置的表情反应通知模式： + + 按服务器配置的 Reaction 通知模式： - `off` - `own`（默认） - `all` - `allowlist`（使用 `guilds..users`） - 表情反应事件会被转换为系统事件，并附加到已路由的 Discord 会话中。 + Reaction 事件会被转换为系统事件，并附加到路由后的 Discord 会话中。 - - `ackReaction` 会在 OpenClaw 处理入站消息期间发送一个确认表情。 + + `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。 解析顺序： @@ -799,14 +800,14 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 说明： - Discord 接受 unicode emoji 或自定义 emoji 名称。 - - 对渠道或账户使用 `""` 可禁用该表情反应。 + - 使用 `""` 可为某个渠道或账户禁用该 Reaction。 默认启用由渠道发起的配置写入。 - 这会影响 `/config set|unset` 流程（当命令功能已启用时）。 + 这会影响 `/config set|unset` 流程（在启用命令功能时）。 禁用方式： @@ -823,7 +824,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord gateway WebSocket 流量和启动 REST 查询（应用 ID + 允许列表解析）。 + 使用 `channels.discord.proxy` 通过 HTTP(S) 代理路由 Discord gateway WebSocket 流量和启动时的 REST 查询（应用 ID + allowlist 解析）。 ```json5 { @@ -871,15 +872,15 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 说明： - - 允许列表可使用 `pk:` - - 只有在 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名称 - - 查询使用原始消息 ID，并受时间窗口限制 - - 如果查询失败，代理消息会被视为机器人消息并被丢弃，除非设置了 `allowBots=true` + - allowlist 可使用 `pk:` + - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名 + - 查询会使用原始消息 ID，并受到时间窗口限制 + - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非设置了 `allowBots=true` - 当你设置状态或活动字段，或启用自动在线状态时，会应用在线状态更新。 + 当你设置状态或活动字段，或者启用自动在线状态时，会应用在线状态更新。 仅状态示例： @@ -899,7 +900,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 { channels: { discord: { - activity: "专注时间", + activity: "Focus time", activityType: 4, }, }, @@ -912,7 +913,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 { channels: { discord: { - activity: "直播编程", + activity: "Live coding", activityType: 1, activityUrl: "https://twitch.tv/openclaw", }, @@ -946,7 +947,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 自动在线状态将运行时可用性映射到 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： + 自动在线状态会将运行时可用性映射到 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -955,73 +956,73 @@ 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"`，且至少能解析出一个审批人时，Discord 会自动启用原生 exec 审批；该审批人可以来自 `execApprovals.approvers`，也可以来自 `commands.ownerAllowFrom`。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec 审批人。将 `enabled: false` 设置为显式禁用 Discord 作为原生审批客户端。 + 当 `enabled` 未设置或为 `"auto"`，且至少有一个 approver 可被解析时，Discord 会自动启用原生 exec 审批；这些 approver 可以来自 `execApprovals.approvers` 或 `commands.ownerAllowFrom`。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断 exec approver。若要显式禁用 Discord 作为原生审批客户端，请设置 `enabled: false`。 - 当 `target` 为 `channel` 或 `both` 时，审批提示会在频道中可见。只有已解析的审批人可以使用这些按钮；其他用户会收到临时拒绝消息。审批提示包含命令文本，因此仅应在受信任频道中启用频道投递。如果无法从会话键推导出频道 ID，OpenClaw 会回退到私信投递。 + 当 `target` 为 `channel` 或 `both` 时，审批提示会在渠道中可见。只有已解析的 approver 可以使用这些按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此只应在可信渠道中启用渠道投递。如果无法从会话键推导出渠道 ID，OpenClaw 会回退到私信投递。 - Discord 也会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要增加了审批人私信路由和频道扇出。 - 当这些按钮存在时，它们就是主要的审批 UX；只有在工具结果表明聊天审批不可用，或手动审批是唯一可行路径时，OpenClaw 才应包含手动 `/approve` 命令。 + Discord 还会渲染其他聊天渠道共用的审批按钮。原生 Discord 适配器主要增加了 approver 私信路由和渠道扇出。 + 当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，OpenClaw 才应包含手动 `/approve` 命令。 - 此处理器的 Gateway 网关认证使用与其他 Gateway 客户端相同的共享凭证解析契约： + 此处理器的 Gateway 网关鉴权使用与其他 Gateway 网关客户端相同的共享凭证解析契约： - - env 优先的本地认证（`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`，然后是 `gateway.auth.*`） - - 在本地模式下，仅当 `gateway.auth.*` 未设置时，才可使用 `gateway.remote.*` 作为回退；已配置但无法解析的本地 SecretRef 会以失败关闭方式处理 - - 在适用时通过 `gateway.remote.*` 支持远程模式 - - URL 覆盖是覆盖安全的：CLI 覆盖不会复用隐式凭证，环境变量覆盖仅使用环境变量凭证 + - env 优先的本地鉴权（`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`，然后是 `gateway.auth.*`） + - 在本地模式下，仅当 `gateway.auth.*` 未设置时，才可将 `gateway.remote.*` 用作回退；已配置但未解析的本地 SecretRef 会以故障关闭方式处理 + - 在适用时，通过 `gateway.remote.*` 支持远程模式 + - URL 覆盖是覆盖安全的：CLI 覆盖不会复用隐式凭证，而 env 覆盖仅使用 env 凭证 审批解析行为： - 以 `plugin:` 为前缀的 ID 通过 `plugin.approval.resolve` 解析。 - 其他 ID 通过 `exec.approval.resolve` 解析。 - - Discord 不会在这里执行额外的 exec 到 plugin 回退跳转；ID 前缀决定它调用哪个 gateway 方法。 + - Discord 不会在这里做额外的 exec 到 plugin 回退跳转；ID 前缀决定它调用哪个 Gateway 网关方法。 - Exec 审批默认在 30 分钟后过期。如果审批因未知审批 ID 而失败，请检查审批人解析、功能启用情况，以及已投递的审批 ID 类型是否与待处理请求匹配。 + Exec 审批默认在 30 分钟后过期。如果审批因未知审批 ID 而失败，请检查 approver 解析、功能启用状态，以及已投递的审批 ID 类型是否与待处理请求匹配。 - 相关文档：[Exec approvals](/zh-CN/tools/exec-approvals) + 相关文档：[Exec 审批](/zh-CN/tools/exec-approvals) ## 工具和操作门控 -Discord 消息操作包括消息传递、频道管理、审核、在线状态和元数据操作。 +Discord 消息操作包括消息收发、渠道管理、审核、在线状态和元数据操作。 核心示例： -- 消息传递：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` -- 表情反应：`react`、`reactions`、`emojiList` +- 消息：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` +- Reaction：`react`、`reactions`、`emojiList` - 审核：`timeout`、`kick`、`ban` - 在线状态：`setPresence` -`event-create` 操作接受一个可选的 `image` 参数（URL 或本地文件路径），用于设置计划事件封面图像。 +`event-create` 操作接受一个可选的 `image` 参数（URL 或本地文件路径），用于设置计划事件封面图。 操作门控位于 `channels.discord.actions.*` 下。 默认门控行为： -| 操作组 | 默认值 | -| --- | --- | -| reactions、messages、threads、pins、polls、search、memberInfo、roleInfo、channelInfo、channels、voiceStatus、events、stickers、emojiUploads、stickerUploads、permissions | enabled | -| roles | disabled | -| moderation | disabled | -| presence | disabled | +| Action group | Default | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | enabled | +| roles | disabled | +| moderation | disabled | +| presence | disabled | ## Components v2 UI -OpenClaw 对 exec 审批和跨上下文标记使用 Discord components v2。Discord 消息操作也可以接受 `components` 以构建自定义 UI（高级用法；需要通过 discord 工具构造组件负载），而旧版 `embeds` 仍可用，但不推荐。 +OpenClaw 使用 Discord components v2 来实现 exec 审批和跨上下文标记。Discord 消息操作也可以接受 `components` 来构建自定义 UI（高级用法；需要通过 discord 工具构造组件负载），而旧版 `embeds` 仍然可用，但不推荐使用。 -- `channels.discord.ui.components.accentColor` 设置 Discord 组件容器使用的强调色（十六进制）。 +- `channels.discord.ui.components.accentColor` 设置 Discord 组件容器所使用的强调色（hex）。 - 可按账户通过 `channels.discord.accounts..ui.components.accentColor` 设置。 -- 当存在 components v2 时，`embeds` 会被忽略。 +- 当存在 components v2 时，会忽略 `embeds`。 示例： @@ -1039,17 +1040,17 @@ OpenClaw 对 exec 审批和跨上下文标记使用 Discord components v2。Disc } ``` -## 语音频道 +## 语音渠道 -OpenClaw 可以加入 Discord 语音频道，以进行实时、连续的对话。这与语音消息附件是分开的。 +OpenClaw 可以加入 Discord 语音渠道，以进行实时、连续的对话。这与语音消息附件是分开的。 要求： - 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。 - 配置 `channels.discord.voice`。 -- 机器人需要在目标语音频道中拥有 Connect + Speak 权限。 +- 机器人在目标语音渠道中需要 Connect + Speak 权限。 -使用仅限 Discord 的原生命令 `/vc join|leave|status` 来控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的允许列表和服务器策略规则。 +使用仅限 Discord 的原生命令 `/vc join|leave|status` 来控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的 allowlist 和服务器策略规则。 自动加入示例： @@ -1079,23 +1080,23 @@ OpenClaw 可以加入 Discord 语音频道，以进行实时、连续的对话 说明： -- `voice.tts` 仅覆盖用于语音播放的 `messages.tts`。 -- 语音转录轮次会从 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者发言者无法访问仅限所有者的工具（例如 `gateway` 和 `cron`）。 +- `voice.tts` 仅覆盖语音播放中的 `messages.tts`。 +- 语音转录轮次会根据 Discord `allowFrom`（或 `dm.allowFrom`）推导 owner 状态；非 owner 说话者无法访问仅限 owner 的工具（例如 `gateway` 和 `cron`）。 - 语音默认启用；设置 `channels.discord.voice.enabled=false` 可将其禁用。 -- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的加入选项。 -- 如果未设置，`@discordjs/voice` 的默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 -- OpenClaw 还会监测接收解密失败，并在短时间窗口内发生重复失败后，通过离开并重新加入语音频道来自动恢复。 -- 如果接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，这可能是上游 `@discordjs/voice` 的接收问题，见 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)。 +- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 的加入选项。 +- 如果未设置，`@discordjs/voice` 默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 +- OpenClaw 还会监视接收解密失败，并在短时间窗口内重复失败后通过离开/重新加入语音渠道来自动恢复。 +- 如果接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，这可能是上游 `@discordjs/voice` 接收 bug，见 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)。 ## 语音消息 -Discord 语音消息会显示波形预览，并要求使用 OGG/Opus 音频及元数据。OpenClaw 会自动生成波形，但它需要在 Gateway 网关主机上提供 `ffmpeg` 和 `ffprobe`，以检查并转换音频文件。 +Discord 语音消息会显示波形预览，并要求使用 OGG/Opus 音频和元数据。OpenClaw 会自动生成波形，但它需要在 Gateway 网关主机上可用的 `ffmpeg` 和 `ffprobe` 来检查并转换音频文件。 要求和限制： -- 提供**本地文件路径**（URL 会被拒绝）。 -- 省略文本内容（Discord 不允许在同一个负载中同时发送文本和语音消息）。 -- 接受任何音频格式；必要时 OpenClaw 会将其转换为 OGG/Opus。 +- 提供一个**本地文件路径**（不接受 URL）。 +- 省略文本内容（Discord 不允许在同一负载中同时发送文本和语音消息）。 +- 接受任意音频格式；OpenClaw 会在需要时将其转换为 OGG/Opus。 示例： @@ -1109,19 +1110,19 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - 启用 Message Content Intent - - 当你依赖 user/member 解析时，启用 Server Members Intent - - 更改 intents 后重启 Gateway 网关 + - 当你依赖用户/成员解析时，启用 Server Members Intent + - 修改 intents 后重启 Gateway 网关 - 验证 `groupPolicy` - - 验证 `channels.discord.guilds` 下的服务器允许列表 - - 如果存在服务器 `channels` 映射，则只允许列出的频道 - - 验证 `requireMention` 行为和提及模式 + - 验证 `channels.discord.guilds` 下的服务器白名单 + - 如果存在服务器 `channels` 映射，则仅允许已列出的渠道 + - 验证 `requireMention` 行为和 mention 模式 - 有用的检查： + 有用的检查命令： ```bash openclaw doctor @@ -1131,16 +1132,16 @@ openclaw logs --follow - + 常见原因： - - `groupPolicy="allowlist"`，但没有匹配的服务器/频道允许列表 - - `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或频道条目下） - - 发送者被服务器/频道 `users` 允许列表阻止 + - `groupPolicy="allowlist"`，但没有匹配的服务器/渠道白名单 + - `requireMention` 配置在了错误的位置（必须位于 `channels.discord.guilds` 或渠道条目下） + - 发送者被服务器/渠道 `users` allowlist 阻止 - + 典型日志： @@ -1180,14 +1181,14 @@ openclaw logs --follow } ``` - 对于缓慢的监听器设置，使用 `eventQueue.listenerTimeout`；仅当你希望为排队的智能体轮次设置单独的安全阀时，才使用 `inboundWorker.runTimeoutMs`。 + 对于缓慢的监听器初始化，请使用 `eventQueue.listenerTimeout`；仅当你希望为排队中的智能体轮次设置一个单独的安全阀时，才使用 `inboundWorker.runTimeoutMs`。 - `channels status --probe` 的权限检查仅适用于数字频道 ID。 + `channels status --probe` 的权限检查仅适用于数字渠道 ID。 - 如果你使用 slug 键，运行时匹配仍然可以工作，但探测无法完整验证权限。 + 如果你使用 slug 键，运行时匹配仍可能正常工作，但探测无法完整验证权限。 @@ -1199,11 +1200,11 @@ openclaw logs --follow - - 默认情况下，由机器人发送的消息会被忽略。 + + 默认情况下，由机器人创建的消息会被忽略。 - 如果你设置了 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则以避免循环行为。 - 更推荐使用 `channels.discord.allowBots="mentions"`，这样只接受提及该机器人的机器人消息。 + 如果你设置了 `channels.discord.allowBots=true`，请使用严格的 mention 和 allowlist 规则来避免循环行为。 + 建议使用 `channels.discord.allowBots="mentions"`，以仅接受那些提及机器人的机器人消息。 @@ -1211,11 +1212,11 @@ openclaw logs --follow - 保持 OpenClaw 为最新版本（`openclaw update`），以确保包含 Discord 语音接收恢复逻辑 - 确认 `channels.discord.voice.daveEncryption=true`（默认值） - - 从 `channels.discord.voice.decryptionFailureTolerance=24`（上游默认值）开始，仅在需要时再调优 - - 关注日志中的以下内容： + - 从 `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 #11419](https://github.com/discordjs/discord.js/issues/11419) 进行比对 @@ -1228,7 +1229,7 @@ openclaw logs --follow 高信号 Discord 字段： -- 启动/认证：`enabled`、`token`、`accounts.*`、`allowBots` +- 启动/鉴权：`enabled`、`token`、`accounts.*`、`allowBots` - 策略：`groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*` - 命令：`commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*` - 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` @@ -1237,7 +1238,7 @@ openclaw logs --follow - 投递：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` - 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` - 媒体/重试：`mediaMaxMb`、`retry` - - `mediaMaxMb` 限制发往 Discord 的出站上传大小（默认：`100MB`） + - `mediaMaxMb` 限制 Discord 出站上传大小（默认值：`100MB`） - 操作：`actions.*` - 在线状态：`activity`、`status`、`activityType`、`activityUrl` - UI：`ui.components.accentColor` @@ -1245,8 +1246,8 @@ openclaw logs --follow ## 安全与运维 -- 将机器人令牌视为机密（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 -- 授予最小必要的 Discord 权限。 +- 将机器人令牌视为秘密信息（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 +- 授予最小权限的 Discord 权限。 - 如果命令部署/状态已过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。 ## 相关内容 diff --git a/docs/zh-CN/channels/mattermost.md b/docs/zh-CN/channels/mattermost.md index cc15d3b48..4a6208cce 100644 --- a/docs/zh-CN/channels/mattermost.md +++ b/docs/zh-CN/channels/mattermost.md @@ -5,25 +5,25 @@ read_when: summary: Mattermost 机器人设置和 OpenClaw 配置 title: Mattermost x-i18n: - generated_at: "2026-04-21T20:11:32Z" + generated_at: "2026-04-22T01:34:42Z" model: gpt-5.4 provider: openai - source_hash: 76a182ad26199f435de64edc27c888672964b711a7346f3ca539fba666695222 + source_hash: dd3059c5e64f417edc02c3e850ddd066e38decda0cbdcea31e1c57136e6bcb1d source_path: channels/mattermost.md workflow: 15 --- # Mattermost -状态：内置插件（机器人令牌 + WebSocket 事件）。支持渠道、群组和私信。 -Mattermost 是一个可自托管的团队消息平台；产品详情和下载请参见官方网站 +状态：内置插件（bot token + WebSocket 事件）。支持渠道、群组和私信。 +Mattermost 是一个可自托管的团队消息平台；产品详情和下载请参见官方站点 [mattermost.com](https://mattermost.com)。 ## 内置插件 -Mattermost 在当前的 OpenClaw 版本中作为内置插件提供，因此普通的打包构建不需要单独安装。 +Mattermost 在当前的 OpenClaw 版本中作为内置插件提供，因此常规打包构建无需单独安装。 -如果你使用的是较旧版本，或者使用了不包含 Mattermost 的自定义安装， +如果你使用的是较旧版本，或是不包含 Mattermost 的自定义安装， 请手动安装： 通过 CLI 安装（npm 注册表）： @@ -32,7 +32,7 @@ Mattermost 在当前的 OpenClaw 版本中作为内置插件提供，因此普 openclaw plugins install @openclaw/mattermost ``` -本地检出安装（从 git 仓库运行时）： +本地 checkout（从 git 仓库运行时）： ```bash openclaw plugins install ./path/to/local/mattermost-plugin @@ -44,8 +44,8 @@ openclaw plugins install ./path/to/local/mattermost-plugin 1. 确保 Mattermost 插件可用。 - 当前打包发布的 OpenClaw 版本已内置该插件。 - - 较旧版本/自定义安装可使用上面的命令手动添加。 -2. 创建一个 Mattermost 机器人账户并复制 **bot token**。 + - 较旧版本 / 自定义安装可使用上面的命令手动添加。 +2. 创建一个 Mattermost bot 账户，并复制 **bot token**。 3. 复制 Mattermost **base URL**（例如 `https://chat.example.com`）。 4. 配置 OpenClaw 并启动 Gateway 网关。 @@ -77,7 +77,7 @@ Mattermost API 注册 `oc_*` 斜杠命令，并在 Gateway 网关 HTTP 服务器 native: true, nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 当 Mattermost 无法直接访问 Gateway 网关时使用（反向代理/公共 URL）。 + // 当 Mattermost 无法直接访问 Gateway 网关时使用（反向代理 / 公网 URL）。 callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, }, @@ -87,33 +87,32 @@ Mattermost API 注册 `oc_*` 斜杠命令，并在 Gateway 网关 HTTP 服务器 说明： -- `native: "auto"` 在 Mattermost 中默认禁用。设置 `native: true` 以启用。 -- 如果省略 `callbackUrl`，OpenClaw 会根据 Gateway 网关主机/端口 + `callbackPath` 自动推导。 -- 对于多账户设置，`commands` 可以设置在顶层，也可以设置在 +- `native: "auto"` 对 Mattermost 默认为禁用。设置 `native: true` 以启用。 +- 如果省略 `callbackUrl`，OpenClaw 会根据 Gateway 网关 host / port 和 `callbackPath` 自动推导。 +- 对于多账户配置，`commands` 可以设置在顶层，也可以设置在 `channels.mattermost.accounts..commands` 下（账户级值会覆盖顶层字段）。 -- 命令回调会使用 OpenClaw 注册 `oc_*` 命令时 - Mattermost 返回的每个命令专属令牌进行校验。 -- 当注册失败、启动不完整，或 - 回调令牌与任何已注册命令都不匹配时，斜杠命令回调会以失败关闭的方式处理。 +- 命令回调会使用 Mattermost 在 OpenClaw 注册 `oc_*` 命令时返回的每命令 token 进行校验。 +- 当注册失败、启动不完整，或回调 token 与任一已注册命令都不匹配时， + 斜杠命令回调会以失败关闭方式拒绝处理。 - 可达性要求：回调端点必须可从 Mattermost 服务器访问。 - - 除非 Mattermost 与 OpenClaw 运行在同一主机/网络命名空间中，否则不要将 `callbackUrl` 设置为 `localhost`。 - - 除非该 URL 已将 `/api/channels/mattermost/command` 反向代理到 OpenClaw，否则不要将 `callbackUrl` 设置为你的 Mattermost base URL。 - - 一个快速检查方法是执行 `curl https:///api/channels/mattermost/command`；GET 请求应从 OpenClaw 返回 `405 Method Not Allowed`，而不是 `404`。 + - 除非 Mattermost 与 OpenClaw 运行在同一主机 / 网络命名空间中，否则不要将 `callbackUrl` 设置为 `localhost`。 + - 除非该 URL 会将 `/api/channels/mattermost/command` 反向代理到 OpenClaw，否则不要将 `callbackUrl` 设置为你的 Mattermost base URL。 + - 一个快速检查方法是运行 `curl https:///api/channels/mattermost/command`；GET 请求应返回来自 OpenClaw 的 `405 Method Not Allowed`，而不是 `404`。 - Mattermost 出站允许列表要求： - - 如果你的回调目标是私有/tailnet/内部地址，请设置 Mattermost - `ServiceSettings.AllowedUntrustedInternalConnections` 以包含回调主机/域名。 - - 请使用主机/域名条目，而不是完整 URL。 + - 如果你的回调目标是私有地址 / tailnet / 内网地址，请设置 Mattermost + `ServiceSettings.AllowedUntrustedInternalConnections` 以包含回调 host / domain。 + - 使用 host / domain 条目，而不是完整 URL。 - 正确：`gateway.tailnet-name.ts.net` - 错误：`https://gateway.tailnet-name.ts.net` ## 环境变量（默认账户） -如果你更喜欢使用环境变量，请在 Gateway 网关主机上设置这些值： +如果你更倾向于使用环境变量，请在 Gateway 网关主机上设置以下内容： - `MATTERMOST_BOT_TOKEN=...` - `MATTERMOST_URL=https://chat.example.com` -环境变量仅适用于**默认**账户（`default`）。其他账户必须使用配置值。 +环境变量仅适用于 **默认** 账户（`default`）。其他账户必须使用配置值。 ## 聊天模式 @@ -121,7 +120,7 @@ Mattermost 会自动响应私信。渠道行为由 `chatmode` 控制： - `oncall`（默认）：仅在渠道中被 @提及时响应。 - `onmessage`：响应每条渠道消息。 -- `onchar`：当消息以前缀触发符开头时响应。 +- `onchar`：当消息以触发前缀开头时响应。 配置示例： @@ -139,18 +138,17 @@ Mattermost 会自动响应私信。渠道行为由 `chatmode` 控制： 说明： - `onchar` 仍会响应显式的 @提及。 -- `channels.mattermost.requireMention` 会兼容旧配置，但更推荐使用 `chatmode`。 +- `channels.mattermost.requireMention` 仍会兼容旧版配置，但更推荐使用 `chatmode`。 -## 线程和会话 +## 线程与会话 -使用 `channels.mattermost.replyToMode` 控制渠道和群组回复是保留在主渠道中， -还是在触发消息下开启线程。 +使用 `channels.mattermost.replyToMode` 来控制渠道和群组回复是保留在主渠道中， +还是在触发消息下启动一个线程。 -- `off`（默认）：仅当传入消息本身已在线程中时，才在线程中回复。 -- `first`：对于渠道/群组中的顶级消息，在该消息下启动线程，并将 - 对话路由到线程作用域的会话。 -- `all`：在当前 Mattermost 中，行为与 `first` 相同。 -- 私信会忽略此设置，并保持为非线程形式。 +- `off`（默认）：仅当传入消息本身已经在线程中时，才在线程中回复。 +- `first`：对于渠道 / 群组中的顶层消息，在该消息下启动线程，并将对话路由到一个线程作用域的会话。 +- `all`：在当前 Mattermost 中，其行为与 `first` 相同。 +- 私信会忽略该设置，并保持非线程模式。 配置示例： @@ -166,9 +164,9 @@ Mattermost 会自动响应私信。渠道行为由 `chatmode` 控制： 说明： -- 线程作用域会话使用触发消息的 post id 作为线程根。 -- `first` 和 `all` 当前等价，因为一旦 Mattermost 已有线程根， - 后续分块和媒体都会继续发送到同一线程中。 +- 线程作用域会话使用触发消息的 post id 作为线程根节点。 +- `first` 和 `all` 当前等价，因为一旦 Mattermost 已经有线程根节点， + 后续分块和媒体内容都会继续发送到同一线程中。 ## 访问控制（私信） @@ -176,17 +174,17 @@ Mattermost 会自动响应私信。渠道行为由 `chatmode` 控制： - 通过以下命令批准： - `openclaw pairing list mattermost` - `openclaw pairing approve mattermost ` -- 公开私信：`channels.mattermost.dmPolicy="open"` 加上 `channels.mattermost.allowFrom=["*"]`。 +- 公开私信：`channels.mattermost.dmPolicy="open"` 加 `channels.mattermost.allowFrom=["*"]`。 ## 渠道（群组） -- 默认：`channels.mattermost.groupPolicy = "allowlist"`（提及门控）。 +- 默认：`channels.mattermost.groupPolicy = "allowlist"`（受提及门控）。 - 使用 `channels.mattermost.groupAllowFrom` 将发送者加入允许列表（推荐使用用户 ID）。 -- 每个渠道的提及覆盖项位于 `channels.mattermost.groups..requireMention` +- 每渠道提及覆盖项位于 `channels.mattermost.groups..requireMention` 或 `channels.mattermost.groups["*"].requireMention`（作为默认值）。 -- `@username` 匹配是可变的，并且仅在 `channels.mattermost.dangerouslyAllowNameMatching: true` 时启用。 -- 公开渠道：`channels.mattermost.groupPolicy="open"`（提及门控）。 -- 运行时说明：如果 `channels.mattermost` 完全缺失，运行时在群组检查时会回退到 `groupPolicy="allowlist"`（即使已设置 `channels.defaults.groupPolicy`）。 +- `@username` 匹配是可变的，且仅在 `channels.mattermost.dangerouslyAllowNameMatching: true` 时启用。 +- 开放渠道：`channels.mattermost.groupPolicy="open"`（受提及门控）。 +- 运行时说明：如果完全缺少 `channels.mattermost`，运行时在进行群组检查时会回退为 `groupPolicy="allowlist"`（即使已设置 `channels.defaults.groupPolicy` 也是如此）。 示例： @@ -204,31 +202,31 @@ Mattermost 会自动响应私信。渠道行为由 `chatmode` 控制： } ``` -## 出站投递的目标格式 +## 出站投递的 target 格式 -将以下目标格式与 `openclaw message send` 或 cron/webhooks 一起使用： +在 `openclaw message send` 或 cron / webhook 中使用以下 target 格式： - `channel:` 表示渠道 - `user:` 表示私信 - `@username` 表示私信（通过 Mattermost API 解析） -裸的不透明 ID（例如 `64ifufp...`）在 Mattermost 中是**有歧义的** -（用户 ID 与渠道 ID 无法区分）。 +裸的不透明 ID（如 `64ifufp...`）在 Mattermost 中是 **有歧义的** +（可能是用户 ID，也可能是渠道 ID）。 -OpenClaw 会按**优先用户**的顺序解析： +OpenClaw 会按 **用户优先** 进行解析： -- 如果该 ID 作为用户存在（`GET /api/v4/users/` 成功），OpenClaw 会通过 `/api/v4/channels/direct` 解析直连渠道后发送**私信**。 -- 否则，该 ID 会被视为**渠道 ID**。 +- 如果该 ID 作为用户存在（`GET /api/v4/users/` 成功），OpenClaw 会通过 `/api/v4/channels/direct` 解析直连渠道并发送 **私信**。 +- 否则，该 ID 会被视为 **渠道 ID**。 -如果你需要确定性行为，请始终使用显式前缀（`user:` / `channel:`）。 +如果你需要确定性的行为，请始终使用显式前缀（`user:` / `channel:`）。 ## 私信渠道重试 -当 OpenClaw 向 Mattermost 私信目标发送消息且需要先解析直连渠道时， -默认会对临时性的直连渠道创建失败进行重试。 +当 OpenClaw 向 Mattermost 私信 target 发送消息且需要先解析直连渠道时， +默认会对瞬时性的直连渠道创建失败进行重试。 -使用 `channels.mattermost.dmChannelRetry` 为 Mattermost 插件全局调整该行为， -或使用 `channels.mattermost.accounts..dmChannelRetry` 为单个账户调整。 +使用 `channels.mattermost.dmChannelRetry` 可全局调整 Mattermost 插件的此行为， +或使用 `channels.mattermost.accounts..dmChannelRetry` 为某个账户单独设置。 ```json5 { @@ -247,13 +245,13 @@ OpenClaw 会按**优先用户**的顺序解析： 说明： -- 这仅适用于私信渠道创建（`/api/v4/channels/direct`），不适用于每一次 Mattermost API 调用。 -- 重试适用于限流、5xx 响应以及网络或超时错误等瞬时失败。 -- 除 `429` 外的 4xx 客户端错误会被视为永久性错误，不会重试。 +- 这仅适用于私信渠道创建（`/api/v4/channels/direct`），而不是每一次 Mattermost API 调用。 +- 重试适用于限流、5xx 响应，以及网络或超时错误等瞬时性失败。 +- 除 `429` 之外的 4xx 客户端错误会被视为永久性错误，不会重试。 ## 预览流式传输 -Mattermost 会将思考过程、工具活动和部分回复文本流式写入同一个**草稿预览消息**中，当最终答案可以安全发送时，就地完成该消息。预览会在同一个 post id 上更新，而不是用每个分块消息刷屏整个渠道。 +Mattermost 会将思考内容、工具活动和部分回复文本流式写入同一个**草稿预览消息**，当最终答案可以安全发送时，会原地完成定稿。预览会在同一个 post id 上更新，而不会用逐块消息刷屏。媒体 / 错误类最终结果会取消待处理的预览编辑，并改用常规投递，而不是刷新一个临时的预览消息。 通过 `channels.mattermost.streaming` 启用： @@ -269,20 +267,20 @@ Mattermost 会将思考过程、工具活动和部分回复文本流式写入同 说明： -- `partial` 是通常的选择：一个预览消息会随着回复增长不断编辑，然后用完整答案完成。 -- `block` 会在预览消息中使用追加式草稿分块。 -- `progress` 会在生成过程中显示状态预览，并仅在完成时发送最终答案。 +- `partial` 是通常的选择：使用一条预览消息，随着回复增长不断编辑，最后以完整答案定稿。 +- `block` 会在预览消息内使用追加式草稿分块。 +- `progress` 会在生成期间显示状态预览，并仅在完成时发布最终答案。 - `off` 会禁用预览流式传输。 -- 如果流无法就地完成（例如消息在流式过程中被删除），OpenClaw 会回退为发送一个新的最终消息，以确保回复不会丢失。 -- 渠道映射矩阵请参见 [Streaming](/zh-CN/concepts/streaming#preview-streaming-modes)。 +- 如果流无法原地定稿（例如消息在流过程中被删除），OpenClaw 会回退为发送一条新的最终消息，以确保回复不会丢失。 +- 参见 [Streaming](/zh-CN/concepts/streaming#preview-streaming-modes) 了解渠道映射矩阵。 ## Reactions（消息工具） - 使用 `message action=react`，并设置 `channel=mattermost`。 - `messageId` 是 Mattermost 的 post id。 -- `emoji` 接受如 `thumbsup` 或 `:+1:` 这样的名称（冒号可省略）。 -- 设置 `remove=true`（布尔值）以移除一个 reaction。 -- Reaction 添加/移除事件会作为系统事件转发到已路由的智能体会话。 +- `emoji` 接受如 `thumbsup` 或 `:+1:` 这样的名称（冒号可选）。 +- 设置 `remove=true`（布尔值）可移除一个 reaction。 +- Reaction 添加 / 移除事件会作为系统事件转发到已路由的智能体会话。 示例： @@ -293,7 +291,7 @@ message action=react channel=mattermost target=channel: messageId=.actions.reactions`。 ## 交互式按钮（消息工具） @@ -313,7 +311,7 @@ message action=react channel=mattermost target=channel: messageId= buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]] @@ -322,42 +320,40 @@ message action=send channel=mattermost target=channel: buttons=[[{"te 按钮字段： - `text`（必填）：显示标签。 -- `callback_data`（必填）：点击后回传的值（用作 action ID）。 +- `callback_data`（必填）：点击后回传的值（作为 action ID 使用）。 - `style`（可选）：`"default"`、`"primary"` 或 `"danger"`。 当用户点击按钮时： 1. 所有按钮都会被替换为一行确认文本（例如，“✓ **Yes** selected by @user”）。 -2. 智能体会将该选择作为一条入站消息接收，并作出响应。 +2. 智能体会将该选择作为一条传入消息接收，并作出响应。 说明： - 按钮回调使用 HMAC-SHA256 校验（自动完成，无需配置）。 -- Mattermost 会从其 API 响应中剥离 callback data（安全特性），因此点击后所有按钮 - 都会被移除——无法只移除其中一部分。 -- 包含连字符或下划线的 action ID 会自动清理 +- Mattermost 会从其 API 响应中剥离回调数据（安全特性），因此点击后所有按钮 + 都会被移除——无法实现部分移除。 +- 包含连字符或下划线的 action ID 会被自动清理 （Mattermost 路由限制）。 配置： -- `channels.mattermost.capabilities`：能力字符串数组。添加 `"inlineButtons"` 以 - 在智能体系统提示词中启用按钮工具说明。 -- `channels.mattermost.interactions.callbackBaseUrl`：可选的按钮回调外部基础 URL - （例如 `https://gateway.example.com`）。当 Mattermost 无法 - 直接通过 Gateway 网关绑定主机访问它时，请使用此项。 -- 在多账户设置中，你也可以在 - `channels.mattermost.accounts..interactions.callbackBaseUrl` 下设置同一字段。 +- `channels.mattermost.capabilities`：能力字符串数组。添加 `"inlineButtons"` 以在智能体系统提示中启用按钮工具说明。 +- `channels.mattermost.interactions.callbackBaseUrl`：按钮回调的可选外部基础 URL + （例如 `https://gateway.example.com`）。当 Mattermost 无法直接通过 Gateway 网关绑定的 host 访问时，请使用此项。 +- 在多账户配置中，你也可以在 + `channels.mattermost.accounts..interactions.callbackBaseUrl` 下设置相同字段。 - 如果省略 `interactions.callbackBaseUrl`，OpenClaw 会根据 `gateway.customBindHost` + `gateway.port` 推导回调 URL，然后回退到 `http://localhost:`。 - 可达性规则：按钮回调 URL 必须可从 Mattermost 服务器访问。 - `localhost` 仅在 Mattermost 和 OpenClaw 运行于同一主机/网络命名空间时有效。 -- 如果你的回调目标是私有/tailnet/内部地址，请将其主机/域名添加到 Mattermost 的 - `ServiceSettings.AllowedUntrustedInternalConnections` 中。 + `localhost` 仅在 Mattermost 和 OpenClaw 运行在同一主机 / 网络命名空间时有效。 +- 如果你的回调目标是私有地址 / tailnet / 内网地址，请将其 host / domain 添加到 Mattermost 的 + `ServiceSettings.AllowedUntrustedInternalConnections`。 ### 直接 API 集成（外部脚本） 外部脚本和 webhook 可以直接通过 Mattermost REST API 发送按钮， -而不必经过智能体的 `message` 工具。如果可能，请使用扩展中的 `buildButtonAttachments()`；如果发送原始 JSON，请遵循以下规则： +而不必经过智能体的 `message` 工具。尽可能使用扩展中的 `buildButtonAttachments()`；如果发送原始 JSON，请遵循以下规则： **负载结构：** @@ -393,27 +389,27 @@ message action=send channel=mattermost target=channel: buttons=[[{"te **关键规则：** -1. 附件应放在 `props.attachments` 中，而不是顶层的 `attachments`（否则会被静默忽略）。 +1. Attachments 应放在 `props.attachments` 中，而不是顶层 `attachments`（否则会被静默忽略）。 2. 每个 action 都需要 `type: "button"` —— 缺少它时，点击会被静默吞掉。 3. 每个 action 都需要一个 `id` 字段 —— 没有 ID 的 action 会被 Mattermost 忽略。 -4. Action 的 `id` 必须是**纯字母数字**（`[a-zA-Z0-9]`）。连字符和下划线会破坏 +4. Action `id` 必须是**仅字母数字**（`[a-zA-Z0-9]`）。连字符和下划线会破坏 Mattermost 服务端的 action 路由（返回 404）。使用前请将它们移除。 -5. `context.action_id` 必须与按钮的 `id` 匹配，这样确认消息才会显示 - 按钮名称（例如 “Approve”），而不是原始 ID。 -6. `context.action_id` 是必需的 —— 没有它，交互处理器会返回 400。 +5. `context.action_id` 必须与按钮的 `id` 一致，这样确认消息才会显示按钮名称 + （例如 “Approve”），而不是原始 ID。 +6. `context.action_id` 是必填项 —— 没有它，交互处理器会返回 400。 **HMAC token 生成：** Gateway 网关使用 HMAC-SHA256 校验按钮点击。外部脚本必须生成 -与 Gateway 网关校验逻辑匹配的 token： +与 Gateway 网关校验逻辑一致的 token： 1. 从 bot token 派生 secret： `HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)` -2. 构建包含所有字段但**不包括** `_token` 的 context 对象。 -3. 使用**排序后的键**和**无空格**进行序列化（Gateway 网关使用带排序键的 `JSON.stringify`， - 其输出为紧凑格式）。 +2. 构建 context 对象，包含除 `_token` 之外的所有字段。 +3. 使用**排序后的键**和**无空格**进行序列化（Gateway 网关使用 + 带排序键的 `JSON.stringify`，会产生紧凑输出）。 4. 签名：`HMAC-SHA256(key=secret, data=serializedContext)` -5. 将生成的十六进制摘要作为 `_token` 添加到 context 中。 +5. 将得到的十六进制摘要作为 `_token` 加入 context。 Python 示例： @@ -436,20 +432,20 @@ context = {**ctx, "_token": token} - Python 的 `json.dumps` 默认会添加空格（`{"key": "val"}`）。请使用 `separators=(",", ":")` 以匹配 JavaScript 的紧凑输出（`{"key":"val"}`）。 -- 始终对**所有** context 字段（除 `_token` 外）进行签名。Gateway 网关会先移除 `_token`， - 然后对其余所有内容签名。只签名子集会导致静默校验失败。 -- 使用 `sort_keys=True` —— Gateway 网关会在签名前对键排序，而 Mattermost 在存储负载时 - 可能会重排 context 字段顺序。 -- 从 bot token 派生 secret（确定性），而不是使用随机字节。这个 secret - 必须在创建按钮的进程和执行校验的 Gateway 网关之间保持一致。 +- 始终对**所有** context 字段（不含 `_token`）进行签名。Gateway 网关会先移除 `_token`， + 然后对剩余所有内容签名。只签名子集会导致静默校验失败。 +- 使用 `sort_keys=True` —— Gateway 网关在签名前会对键排序，而 Mattermost 在存储负载时 + 可能会重排 context 字段。 +- 从 bot token 派生 secret（确定性），而不是使用随机字节。创建按钮的进程与负责校验的 Gateway 网关 + 必须使用相同的 secret。 ## 目录适配器 -Mattermost 插件包含一个目录适配器，可通过 Mattermost API 解析渠道和用户名称。 -这使得你可以在 -`openclaw message send` 和 cron/webhook 投递中使用 `#channel-name` 和 `@username` 目标。 +Mattermost 插件包含一个目录适配器，可通过 Mattermost API 解析渠道名和用户名。 +这样就能在 `openclaw message send` 和 cron / webhook 投递中使用 +`#channel-name` 和 `@username` 作为 target。 -无需额外配置 —— 该适配器会使用账户配置中的 bot token。 +无需配置 —— 该适配器会使用账户配置中的 bot token。 ## 多账户 @@ -470,34 +466,33 @@ Mattermost 支持在 `channels.mattermost.accounts` 下配置多个账户： ## 故障排除 -- 渠道中没有回复：确认机器人已加入该渠道，并 @提及它（oncall），使用触发前缀（onchar），或设置 `chatmode: "onmessage"`。 +- 渠道中没有回复：确认 bot 已加入该渠道，并提及它（oncall），使用触发前缀（onchar），或设置 `chatmode: "onmessage"`。 - 认证错误：检查 bot token、base URL，以及账户是否已启用。 - 多账户问题：环境变量仅适用于 `default` 账户。 - 原生斜杠命令返回 `Unauthorized: invalid command token.`：OpenClaw - 未接受回调 token。常见原因包括： - - 启动时斜杠命令注册失败，或只完成了部分注册 - - 回调打到了错误的 Gateway 网关/账户 + 未接受该回调 token。常见原因包括： + - 斜杠命令注册在启动时失败，或仅部分完成 + - 回调打到了错误的 Gateway 网关 / 账户 - Mattermost 仍保留指向旧回调目标的旧命令 - Gateway 网关重启后未重新激活斜杠命令 - 如果原生斜杠命令停止工作，请检查日志中是否有 `mattermost: failed to register slash commands` 或 `mattermost: native slash commands enabled but no commands could be registered`。 -- 如果省略 `callbackUrl`，且日志警告回调被解析为 - `http://127.0.0.1:18789/...`，那么该 URL 很可能只有在 - Mattermost 与 OpenClaw 运行于同一主机/网络命名空间时才可达。请改为设置一个 - 显式的、外部可达的 `commands.callbackUrl`。 -- 按钮显示为空白方块：智能体可能发送了格式错误的按钮数据。检查每个按钮是否同时具有 `text` 和 `callback_data` 字段。 -- 按钮能渲染但点击无反应：确认 Mattermost 服务器配置中的 `AllowedUntrustedInternalConnections` 包含 `127.0.0.1 localhost`，并且 ServiceSettings 中的 `EnablePostActionIntegration` 为 `true`。 -- 点击按钮返回 404：按钮的 `id` 很可能包含连字符或下划线。Mattermost 的 action 路由器无法处理非字母数字 ID。请仅使用 `[a-zA-Z0-9]`。 -- Gateway 网关日志显示 `invalid _token`：HMAC 不匹配。请检查你是否对所有 context 字段（而非其中一部分）进行了签名、使用了排序后的键，并使用紧凑 JSON（无空格）。请参见上面的 HMAC 部分。 -- Gateway 网关日志显示 `missing _token in context`：按钮的 context 中没有 `_token` 字段。请确保在构建 integration 负载时包含该字段。 -- 确认消息显示的是原始 ID 而不是按钮名称：`context.action_id` 与按钮的 `id` 不匹配。请将二者设为相同的清理后值。 +- 如果省略了 `callbackUrl`，且日志警告回调被解析为 + `http://127.0.0.1:18789/...`，那么该 URL 很可能仅在 + Mattermost 与 OpenClaw 运行于同一主机 / 网络命名空间时可达。请改为显式设置一个外部可达的 `commands.callbackUrl`。 +- 按钮显示为空白框：智能体可能发送了格式错误的按钮数据。检查每个按钮是否同时包含 `text` 和 `callback_data` 字段。 +- 按钮能渲染但点击无效：确认 Mattermost 服务器配置中的 `AllowedUntrustedInternalConnections` 包含 `127.0.0.1 localhost`，并且 `ServiceSettings` 中的 `EnablePostActionIntegration` 为 `true`。 +- 按钮点击返回 404：按钮的 `id` 很可能包含连字符或下划线。Mattermost 的 action 路由器无法处理非字母数字 ID。仅使用 `[a-zA-Z0-9]`。 +- Gateway 网关日志显示 `invalid _token`：HMAC 不匹配。请检查你是否对所有 context 字段签名（而不是子集）、使用了排序键，并使用紧凑 JSON（无空格）。参见上方 HMAC 部分。 +- Gateway 网关日志显示 `missing _token in context`：按钮的 context 中缺少 `_token` 字段。构建集成负载时请确保包含它。 +- 确认信息显示的是原始 ID 而不是按钮名称：`context.action_id` 与按钮的 `id` 不一致。请将二者设置为相同的清洗后值。 - 智能体不知道按钮功能：在 Mattermost 渠道配置中添加 `capabilities: ["inlineButtons"]`。 ## 相关内容 - [Channels Overview](/zh-CN/channels) — 所有支持的渠道 - [Pairing](/zh-CN/channels/pairing) — 私信认证与配对流程 -- [Groups](/zh-CN/channels/groups) — 群聊行为和提及门控 +- [Groups](/zh-CN/channels/groups) — 群组聊天行为与提及门控 - [Channel Routing](/zh-CN/channels/channel-routing) — 消息的会话路由 - [Security](/zh-CN/gateway/security) — 访问模型与加固 diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 00562fdc6..14073bd8d 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,20 +1,20 @@ --- read_when: - 设置 Slack 或调试 Slack socket/HTTP 模式 -summary: Slack 设置和运行时行为（Socket Mode + HTTP 请求 URL） +summary: Slack 设置和运行时行为（Socket Mode + HTTP Request URLs） title: Slack x-i18n: - generated_at: "2026-04-21T16:52:55Z" + generated_at: "2026-04-22T01:34:40Z" model: gpt-5.4 provider: openai - source_hash: f30b372a3ae10b7b649532181306e42792aca76b41422516e9633eb79f73f009 + source_hash: e80b1ff7dfe3124916f9a4334badc9a742a0d0843b37c77838ede9f830920ff7 source_path: channels/slack.md workflow: 15 --- # Slack -状态：通过 Slack 应用集成支持用于私信和渠道的生产就绪。默认模式为 Socket Mode；也支持 HTTP 请求 URL。 +状态：已可用于生产环境，支持通过 Slack 应用集成实现私信和渠道。默认模式为 Socket Mode；也支持 HTTP Request URLs。 @@ -24,11 +24,11 @@ x-i18n: 原生命令行为和命令目录。 - 跨渠道诊断和修复操作手册。 + 跨渠道诊断与修复操作手册。 -## 快速开始 +## 快速设置 @@ -38,7 +38,7 @@ x-i18n: - 选择 **from a manifest**，并为你的应用选择一个工作区 - 粘贴下面的[示例清单](#manifest-and-scope-checklist)，然后继续创建 - - 生成一个带有 `connections:write` 的 **App-Level Token**（`xapp-...`） + - 生成一个带有 `connections:write` 权限的 **App-Level Token**（`xapp-...`） - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） @@ -57,7 +57,7 @@ x-i18n: } ``` - 环境变量回退（仅默认账户）： + 环境变量回退方案（仅默认账户）： ```bash SLACK_APP_TOKEN=xapp-... @@ -77,14 +77,14 @@ openclaw gateway - + 在 Slack 应用设置中，点击 **[Create New App](https://api.slack.com/apps/new)** 按钮： - 选择 **from a manifest**，并为你的应用选择一个工作区 - - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL - - 保存用于请求验证的 **Signing Secret** + - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新这些 URL + - 保存用于请求校验的 **Signing Secret** - 安装应用并复制显示的 **Bot Token**（`xoxb-...`） @@ -106,7 +106,7 @@ openclaw gateway ``` - 对多账户 HTTP 使用唯一的 webhook 路径 + 为多账户 HTTP 使用唯一的 webhook 路径 为每个账户设置不同的 `webhookPath`（默认是 `/slack/events`），以避免注册冲突。 @@ -125,7 +125,7 @@ openclaw gateway -## 清单和 scope 检查清单 +## 清单和作用域检查清单 @@ -205,7 +205,7 @@ openclaw gateway - + ```json { @@ -291,17 +291,17 @@ openclaw gateway ### 其他清单设置 -展示可扩展上述默认配置的不同功能。 +展示扩展上述默认设置的不同功能。 - + - 可以使用多个[原生斜杠命令](#commands-and-slash-behavior) 来替代单个已配置命令，但有一些细节需要注意： + 可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来替代单个已配置命令，但有一些细节需要注意： - - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令是保留的。 + - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已被保留。 - 同时可用的斜杠命令不能超过 25 个。 - 将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list) 的一个子集： + 用[可用命令](/zh-CN/tools/slash-commands#command-list)中的一个子集替换你现有的 `features.slash_commands` 部分： @@ -310,7 +310,7 @@ openclaw gateway "slash_commands": [ { "command": "/new", - "description": "开始一个新会话", + "description": "开始新会话", "usage_hint": "[model]" }, { @@ -381,7 +381,7 @@ openclaw gateway }, { "command": "/tools", - "description": "显示当前智能体此刻可以使用的内容", + "description": "显示当前智能体此刻可用的内容", "usage_hint": "[compact|verbose]" }, { @@ -390,7 +390,7 @@ openclaw gateway }, { "command": "/tasks", - "description": "列出当前会话的活动/近期后台任务" + "description": "列出当前会话的活跃/最近后台任务" }, { "command": "/context", @@ -403,30 +403,30 @@ openclaw gateway }, { "command": "/skill", - "description": "按名称运行一个 skill", + "description": "按名称运行一个技能", "usage_hint": " [input]" }, { "command": "/btw", - "description": "在不更改会话上下文的情况下提出一个附带问题", + "description": "提出一个不改变会话上下文的旁支问题", "usage_hint": "" }, { "command": "/usage", - "description": "控制 usage 页脚或显示成本摘要", + "description": "控制用量页脚或显示成本摘要", "usage_hint": "off|tokens|full|cost" } ] ``` - + ```json "slash_commands": [ { "command": "/new", - "description": "开始一个新会话", + "description": "开始新会话", "usage_hint": "[model]", "url": "https://gateway-host.example.com/slack/events" }, @@ -512,7 +512,7 @@ openclaw gateway }, { "command": "/tools", - "description": "显示当前智能体此刻可以使用的内容", + "description": "显示当前智能体此刻可用的内容", "usage_hint": "[compact|verbose]", "url": "https://gateway-host.example.com/slack/events" }, @@ -523,7 +523,7 @@ openclaw gateway }, { "command": "/tasks", - "description": "列出当前会话的活动/近期后台任务", + "description": "列出当前会话的活跃/最近后台任务", "url": "https://gateway-host.example.com/slack/events" }, { @@ -539,19 +539,19 @@ openclaw gateway }, { "command": "/skill", - "description": "按名称运行一个 skill", + "description": "按名称运行一个技能", "usage_hint": " [input]", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/btw", - "description": "在不更改会话上下文的情况下提出一个附带问题", + "description": "提出一个不改变会话上下文的旁支问题", "usage_hint": "", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/usage", - "description": "控制 usage 页脚或显示成本摘要", + "description": "控制用量页脚或显示成本摘要", "usage_hint": "off|tokens|full|cost", "url": "https://gateway-host.example.com/slack/events" } @@ -562,17 +562,17 @@ openclaw gateway - - 如果你希望出站消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 + + 如果你希望发出的消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 - 如果你使用表情符号图标，Slack 需要 `:emoji_name:` 语法。 + 如果你使用 emoji 图标，Slack 期望采用 `:emoji_name:` 语法。 - - 如果你配置了 `channels.slack.userToken`，典型的读取 scope 包括： + + 如果你配置了 `channels.slack.userToken`，典型的读取作用域包括： - - `channels:history`, `groups:history`, `im:history`, `mpim:history` - - `channels:read`, `groups:read`, `im:read`, `mpim:read` + - `channels:history`、`groups:history`、`im:history`、`mpim:history` + - `channels:read`、`groups:read`、`im:read`、`mpim:read` - `users:read` - `reactions:read` - `pins:read` @@ -588,26 +588,26 @@ openclaw gateway - HTTP 模式需要 `botToken` + `signingSecret`。 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 字符串或 SecretRef 对象。 -- 配置中的令牌会覆盖环境变量回退。 +- 配置中的令牌会覆盖环境变量回退值。 - `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账户。 -- `userToken`（`xoxp-...`）仅支持通过配置设置（没有环境变量回退），且默认采用只读行为（`userTokenReadOnly: true`）。 +- `userToken`（`xoxp-...`）仅支持通过配置提供（无环境变量回退），并默认采用只读行为（`userTokenReadOnly: true`）。 状态快照行为： -- Slack 账户检查会跟踪每个凭证的 `*Source` 和 `*Status` +- Slack 账户检查会跟踪每个凭证对应的 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 - 状态可以是 `available`、`configured_unavailable` 或 `missing`。 - `configured_unavailable` 表示该账户通过 SecretRef - 或其他非内联密钥来源完成了配置，但当前命令/运行时路径 - 无法解析实际值。 + 或其他非内联密钥来源进行了配置，但当前命令/运行时路径 + 无法解析出实际值。 - 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下， - 所需的配对是 `botTokenStatus` + `appTokenStatus`。 + 所需的字段组合是 `botTokenStatus` + `appTokenStatus`。 -对于 actions/目录读取，如果已配置，可以优先使用用户令牌。对于写入，仍然优先使用 bot 令牌；只有在 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 +对于 actions / 目录读取，配置了用户令牌时可以优先使用它。对于写入操作，仍然优先使用 bot 令牌；只有在 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 -## Actions 和 gates +## Actions 和门控 Slack actions 由 `channels.slack.actions.*` 控制。 @@ -645,10 +645,10 @@ Slack actions 由 `channels.slack.actions.*` 控制。 多账户优先级： - `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账户。 - - 已命名账户在自身 `allowFrom` 未设置时，会继承 `channels.slack.allowFrom`。 - - 已命名账户不会继承 `channels.slack.accounts.default.allowFrom`。 + - 如果命名账户自己的 `allowFrom` 未设置，则会继承 `channels.slack.allowFrom`。 + - 命名账户不会继承 `channels.slack.accounts.default.allowFrom`。 - 在私信中配对使用 `openclaw pairing approve slack `。 + 在私信中进行配对时，使用 `openclaw pairing approve slack `。 @@ -659,28 +659,28 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `allowlist` - `disabled` - 渠道 allowlist 位于 `channels.slack.channels` 下，并且应使用稳定的渠道 ID。 + 渠道 allowlist 位于 `channels.slack.channels` 下，且应使用稳定的渠道 ID。 - 运行时说明：如果 `channels.slack` 完全缺失（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使设置了 `channels.defaults.groupPolicy` 也是如此）。 + 运行时说明：如果 `channels.slack` 完全缺失（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录一条警告（即使已设置 `channels.defaults.groupPolicy` 也是如此）。 名称/ID 解析： - - 渠道 allowlist 条目和私信 allowlist 条目会在启动时解析，前提是令牌访问允许 - - 无法解析的渠道名称条目会按配置保留，但默认会在路由中被忽略 - - 入站授权和渠道路由默认以 ID 优先；直接用户名/slug 匹配需要设置 `channels.slack.dangerouslyAllowNameMatching: true` + - 当令牌访问允许时，渠道 allowlist 条目和私信 allowlist 条目会在启动时解析 + - 无法解析的渠道名称条目会按原样保留，但默认会在路由中被忽略 + - 入站授权和渠道路由默认优先按 ID 处理；直接按用户名/slug 匹配需要设置 `channels.slack.dangerouslyAllowNameMatching: true` - 默认情况下，渠道消息受提及门控。 + 渠道消息默认受提及门控保护。 提及来源： - 显式应用提及（`<@botId>`） - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） + - 隐式机器人线程回复行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） - 每个渠道的控制项（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 支持）： + 每个渠道的控制项（`channels.slack.channels.`；名称仅通过启动时解析或 `dangerouslyAllowNameMatching` 支持）： - `requireMention` - `users`（allowlist） @@ -689,7 +689,7 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `systemPrompt` - `tools`、`toolsBySender` - `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符 - （旧版无前缀键仍然只映射到 `id:`） + （旧版无前缀键仍然只会映射到 `id:`） @@ -697,40 +697,40 @@ Slack actions 由 `channels.slack.actions.*` 控制。 ## 线程、会话和回复标签 - 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。 -- 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。 +- 在默认 `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` 门控。 +- `channels.slack.thread.initialHistoryLimit` 控制新线程会话开始时拉取多少条现有线程消息（默认 `20`；设置为 `0` 可禁用）。 +- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当设为 `true` 时，会抑制隐式线程提及，因此 bot 只会在已参与的线程中对显式 `@bot` 提及做出响应。否则，在 bot 已参与的线程中回复会绕过 `requireMention` 门控。 回复线程控制： - `channels.slack.replyToMode`：`off|first|all|batched`（默认 `off`） - `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 分别设置 -- 私聊的旧版回退：`channels.slack.dm.replyToMode` +- 私信的旧版回退：`channels.slack.dm.replyToMode` 支持手动回复标签： - `[[reply_to_current]]` - `[[reply_to:]]` -注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程功能，包括显式的 `[[reply_to_*]]` 标签。这与 Telegram 不同，在 Telegram 中，显式标签在 `"off"` 模式下仍会生效。这个差异反映了平台线程模型的不同：Slack 线程会将消息隐藏在渠道之外，而 Telegram 回复仍会显示在主聊天流中。 +注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程功能，包括显式的 `[[reply_to_*]]` 标签。这与 Telegram 不同，在 Telegram 中，显式标签在 `"off"` 模式下仍会生效。这种差异反映了平台的线程模型：Slack 线程会将消息隐藏在渠道之外，而 Telegram 回复仍会显示在主聊天流中。 -## Ack reactions +## 确认 reaction -`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 +`ackReaction` 会在 OpenClaw 处理入站消息期间发送一个确认 emoji。 解析顺序： - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 `"👀"`） +- 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 `"👀"`） 说明： -- Slack 需要使用短代码（例如 `"eyes"`）。 +- Slack 期望使用短代码（例如 `"eyes"`）。 - 使用 `""` 可为 Slack 账户或全局禁用该 reaction。 ## 文本流式传输 @@ -739,17 +739,18 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `off`：禁用实时预览流式传输。 - `partial`（默认）：用最新的部分输出替换预览文本。 -- `block`：追加分块预览更新。 +- `block`：追加分块的预览更新。 - `progress`：生成期间显示进度状态文本，然后发送最终文本。 -- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一个被编辑的预览消息中（默认：`true`）。设为 `false` 可保留单独的工具/进度消息。 +- `streaming.preview.toolProgress`：当草稿预览处于启用状态时，将工具/进度更新路由到同一个被编辑的预览消息中（默认：`true`）。设为 `false` 可保留独立的工具/进度消息。 当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。 -- 必须有可用的回复线程，Slack 原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍遵循 `replyToMode`。 +- 必须有一个回复线程可用，Slack 原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍然遵循 `replyToMode`。 - 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。 -- 顶层 Slack 私信默认保持非线程形式，因此不会显示线程式预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。 -- 媒体和非文本负载会回退到普通投递方式。 -- 如果流式传输在回复中途失败，OpenClaw 会对剩余负载回退到普通投递方式。 +- 顶层 Slack 私信默认保持无线程，因此不会显示线程式预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。 +- 媒体和非文本负载会回退到普通投递。 +- 媒体/错误最终消息会取消待处理的预览编辑，而不会刷新临时草稿；符合条件的文本/块最终消息仅会在能够原地编辑预览时刷新。 +- 如果流式传输在回复中途失败，OpenClaw 会对剩余负载回退到普通投递。 使用草稿预览而不是 Slack 原生文本流式传输： @@ -772,9 +773,9 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 - 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。 -## Typing reaction 回退 +## 输入中 reaction 回退 -`typingReaction` 会在 OpenClaw 处理回复期间，向入站 Slack 消息添加一个临时 reaction，并在运行结束时移除它。这在非线程回复场景中特别有用，因为线程回复会使用默认的“is typing...”状态指示器。 +`typingReaction` 会在 OpenClaw 处理回复期间，为入站 Slack 消息添加一个临时 reaction，并在运行结束后将其移除。这在非线程回复场景中最有用，因为线程回复会使用默认的 “is typing...” 状态指示器。 解析顺序： @@ -783,14 +784,14 @@ Slack actions 由 `channels.slack.actions.*` 控制。 说明： -- Slack 需要使用短代码（例如 `"hourglass_flowing_sand"`）。 -- 该 reaction 属于尽力而为行为，在回复完成或失败路径结束后会自动尝试清理。 +- Slack 期望使用短代码（例如 `"hourglass_flowing_sand"`）。 +- 该 reaction 为尽力而为机制，并会在回复完成或失败路径结束后自动尝试清理。 ## 媒体、分块和投递 - Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。 + Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在拉取成功且大小限制允许时写入媒体存储。 运行时入站大小上限默认是 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。 @@ -798,25 +799,25 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - 文本分块使用 `channels.slack.textChunkLimit`（默认 4000） - - `channels.slack.chunkMode="newline"` 启用按段落优先拆分 - - 文件发送使用 Slack 上传 API，并且可以包含线程回复（`thread_ts`） - - 配置了 `channels.slack.mediaMaxMb` 时，出站媒体上限遵循该值；否则渠道发送使用媒体管道中的 MIME 类型默认值 + - `channels.slack.chunkMode="newline"` 启用优先按段落拆分 + - 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`） + - 如果配置了 `channels.slack.mediaMaxMb`，出站媒体上限遵循该设置；否则渠道发送使用媒体管道中的 MIME 类型默认值 - 推荐的显式目标： + 推荐使用的显式目标： - 私信使用 `user:` - 渠道使用 `channel:` - 发送到用户目标时，Slack 私信会通过 Slack 会话 API 打开。 + 向用户目标发送时，Slack 私信会通过 Slack 会话 API 打开。 ## 命令和斜杠行为 -斜杠命令在 Slack 中可以表现为单个已配置命令，或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： +斜杠命令在 Slack 中可表现为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： - `enabled: false` - `name: "openclaw"` @@ -827,30 +828,30 @@ Slack actions 由 `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 原生命令。 +- 对于 Slack，原生命令自动模式默认为**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 ```txt /help ``` -原生参数菜单使用自适应渲染策略，在分发所选选项值之前会先显示确认模态框： +原生参数菜单使用自适应渲染策略，在派发所选选项值前会先显示一个确认模态框： -- 最多 5 个选项：按钮区块 +- 最多 5 个选项：按钮块 - 6-100 个选项：静态选择菜单 -- 超过 100 个选项：如果提供 interactivity 选项处理器，则使用带异步选项过滤的外部选择 +- 超过 100 个选项：当可用 interactivity 选项处理器时，使用带异步选项过滤的外部选择 - 超出 Slack 限制：编码后的选项值会回退为按钮 ```txt /think ``` -斜杠会话使用独立键，例如 `agent::slack:slash:`，同时仍会通过 `CommandTargetSessionKey` 将命令执行路由到目标会话会话。 +斜杠会话使用类似 `agent::slack:slash:` 的隔离键，并仍通过 `CommandTargetSessionKey` 将命令执行路由到目标会话。 ## 交互式回复 -Slack 可以渲染由智能体编写的交互式回复控件，但该功能默认禁用。 +Slack 可以渲染由智能体编写的交互式回复控件，但此功能默认禁用。 全局启用： @@ -866,7 +867,7 @@ Slack 可以渲染由智能体编写的交互式回复控件，但该功能默 } ``` -或仅为一个 Slack 账户启用： +或者仅为某个 Slack 账户启用： ```json5 { @@ -884,30 +885,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 Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 负载。 +- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令翻译成各自的按钮系统。 +- 交互回调值是 OpenClaw 生成的不透明令牌，而不是智能体原始编写的值。 +- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的 blocks 负载。 -## Slack 中的 Exec 审批 +## Slack 中的 exec 审批 Slack 可以充当原生审批客户端，使用交互式按钮和交互，而不是回退到 Web UI 或终端。 - Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 -- 如果请求已落在 Slack 中，且审批 id 类型为 `plugin:`，插件审批仍可通过同一个 Slack 原生按钮界面完成。 -- 审批人授权仍然会被强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。 +- 如果请求已经到达 Slack 且审批 ID 类型为 `plugin:`，插件审批仍可通过同一个 Slack 原生按钮界面处理。 +- 审批人授权仍会被强制执行：只有被识别为审批人的用户，才能通过 Slack 批准或拒绝请求。 -这使用与其他渠道相同的共享审批按钮界面。当你在 Slack 应用设置中启用 `interactivity` 时，审批提示会直接在会话中渲染为 Block Kit 按钮。 +这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，审批提示会直接在会话中渲染为 Block Kit 按钮。 当这些按钮存在时，它们就是主要审批 UX；OpenClaw -仅应在工具结果表明聊天审批不可用，或手动审批是唯一途径时，才包含手动 `/approve` 命令。 +只应在工具结果表明聊天审批不可用，或手动审批是唯一途径时，包含手动 `/approve` 命令。 配置路径： @@ -916,9 +917,9 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 - `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter` -当 `enabled` 未设置或为 `"auto"`，且至少解析出一位 -审批人时，Slack 会自动启用原生 exec 审批。设为 `enabled: false` 可显式禁用 Slack 作为原生审批客户端。 -设为 `enabled: true` 可在审批人可解析时强制启用原生审批。 +当 `enabled` 未设置或为 `"auto"` 且至少解析出一位 +审批人时，Slack 会自动启用原生 exec 审批。将 `enabled: false` 设为显式禁用 Slack 作为原生审批客户端。 +将 `enabled: true` 设为在解析出审批人时强制启用原生审批。 在没有显式 Slack exec 审批配置时的默认行为： @@ -930,8 +931,7 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 } ``` -只有当你想覆盖审批人、添加过滤器，或 -选择加入源聊天投递时，才需要显式的 Slack 原生配置： +只有在你想覆盖审批人、添加过滤器或选择加入来源聊天投递时，才需要显式 Slack 原生配置： ```json5 { @@ -947,22 +947,22 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 } ``` -共享 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须 -路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发同样 -是独立的；当这些请求已经到达 Slack 时，Slack 原生按钮仍然可以处理插件审批。 +共享 `approvals.exec` 转发是独立的。只有当 exec 审批提示也必须 +路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也 +是独立的；当这些请求已经到达 Slack 时，Slack 原生按钮仍可处理插件审批。 -同一聊天中的 `/approve` 在已支持命令的 Slack 渠道和私信中也可使用。完整审批转发模型请参见[Exec 审批](/zh-CN/tools/exec-approvals)。 +同一聊天中的 `/approve` 在已经支持命令的 Slack 渠道和私信中也可使用。完整审批转发模型请参见[Exec 审批](/zh-CN/tools/exec-approvals)。 ## 事件和运行行为 - 消息编辑/删除/线程广播会映射为系统事件。 - reaction 添加/移除事件会映射为系统事件。 -- 成员加入/离开、渠道创建/重命名，以及 pin 添加/移除事件会映射为系统事件。 -- 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。 -- 渠道 topic/purpose 元数据被视为不受信任的上下文，并且可以注入到路由上下文中。 -- 在线程起始消息和初始线程历史上下文播种中，会在适用时按配置的发送者 allowlist 进行过滤。 -- 区块操作和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并带有丰富的负载字段： - - 区块操作：选中值、标签、选择器值，以及 `workflow_*` 元数据 +- 成员加入/离开、渠道创建/重命名以及 pin 添加/移除事件会映射为系统事件。 +- 当启用 `configWrites` 时，`channel_id_changed` 可迁移渠道配置键。 +- 渠道 topic/purpose 元数据被视为不可信上下文，并可注入到路由上下文中。 +- 在线程起始消息和初始线程历史上下文植入时，如适用，会根据已配置的发送者 allowlist 进行过滤。 +- Block actions 和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并附带丰富的负载字段： + - block actions：所选值、标签、选择器值和 `workflow_*` 元数据 - 模态 `view_submission` 和 `view_closed` 事件，包含路由后的渠道元数据和表单输入 ## 配置参考指针 @@ -974,7 +974,7 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 高信号 Slack 字段： - 模式/认证：`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` @@ -989,7 +989,7 @@ Slack 可以充当原生审批客户端，使用交互式按钮和交互，而 - `groupPolicy` - 渠道 allowlist（`channels.slack.channels`） - `requireMention` - - 每个渠道的 `users` allowlist + - 每渠道 `users` allowlist 有用的命令： @@ -1015,36 +1015,36 @@ openclaw pairing list slack - 验证 bot + app 令牌，以及 Slack 应用设置中的 Socket Mode 是否已启用。 + 验证 bot + app 令牌，以及 Slack 应用设置中是否启用了 Socket Mode。 如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或 - `appTokenStatus: "configured_unavailable"`，则说明 Slack 账户 - 已完成配置，但当前运行时无法解析由 SecretRef 支持的 + `appTokenStatus: "configured_unavailable"`，则说明该 Slack 账户已 + 配置，但当前运行时无法解析由 SecretRef 支持的 实际值。 - + 验证： - signing secret - webhook 路径 - - Slack 请求 URL（事件 + 交互 + 斜杠命令） + - Slack Request URLs（Events + Interactivity + Slash Commands） - 每个 HTTP 账户使用唯一的 `webhookPath` 如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`， - 则说明 HTTP 账户已完成配置，但当前运行时无法 - 解析由 SecretRef 支持的 signing secret 实际值。 + 则说明该 HTTP 账户已配置，但当前运行时无法 + 解析由 SecretRef 支持的 signing secret。 - - 确认你打算使用的是： + + 请确认你是否本来想要： - - 原生命令模式（`channels.slack.commands.native: true`），并且在 Slack 中注册了匹配的斜杠命令 - - 或单个斜杠命令模式（`channels.slack.slashCommand.enabled: true`） + - 原生命令模式（`channels.slack.commands.native: true`），并且已在 Slack 中注册匹配的斜杠命令 + - 或单一斜杠命令模式（`channels.slack.slashCommand.enabled: true`） - 同时检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。 + 还要检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。 @@ -1053,7 +1053,7 @@ openclaw pairing list slack - [配对](/zh-CN/channels/pairing) - [群组](/zh-CN/channels/groups) -- [安全](/zh-CN/gateway/security) +- [安全性](/zh-CN/gateway/security) - [渠道路由](/zh-CN/channels/channel-routing) - [故障排除](/zh-CN/channels/troubleshooting) - [配置](/zh-CN/gateway/configuration) diff --git a/docs/zh-CN/concepts/streaming.md b/docs/zh-CN/concepts/streaming.md index e866183c5..cee3aaf69 100644 --- a/docs/zh-CN/concepts/streaming.md +++ b/docs/zh-CN/concepts/streaming.md @@ -1,31 +1,31 @@ --- read_when: - - 说明流式传输或分块处理在渠道中的工作方式 + - 解释渠道上的流式传输或分块处理如何工作 - 更改分块流式传输或渠道分块处理行为 - - 调试重复或过早的分块回复或渠道预览流式传输 + - 调试重复或过早的分块回复，或渠道预览流式传输 summary: 流式传输 + 分块处理行为（分块回复、渠道预览流式传输、模式映射） -title: 流式传输与分块处理 +title: 流式传输和分块处理 x-i18n: - generated_at: "2026-04-21T20:41:40Z" + generated_at: "2026-04-22T01:34:41Z" model: gpt-5.4 provider: openai - source_hash: e550c13ce180bf8f72fced4071926bfe8d24dfb1a419c19c51a64eb9ff216ff1 + source_hash: c6b246025ea1b1be57705bde60c0cdb485ffda727392cf00ea5a165571e37fce source_path: concepts/streaming.md workflow: 15 --- # 流式传输 + 分块处理 -OpenClaw 有两个彼此独立的流式传输层： +OpenClaw 有两个独立的流式传输层： -- **分块流式传输（渠道）：** 在助手写作过程中，随着完整的 **块** 生成而发出。这些是普通的渠道消息（不是 token 增量）。 -- **预览流式传输（Telegram/Discord/Slack）：** 在生成过程中更新一条临时的 **预览消息**。 +- **分块流式传输（渠道）：** 在助手写入时发送已完成的 **块**。这些是普通的渠道消息（不是 token 增量）。 +- **预览流式传输（Telegram/Discord/Slack）：** 在生成过程中更新临时的 **预览消息**。 -目前，渠道消息**不支持真正的 token 增量流式传输**。预览流式传输是基于消息的（发送 + 编辑/追加）。 +当前不会将真正的 token 增量流式传输到渠道消息中。预览流式传输基于消息（发送 + 编辑/追加）。 ## 分块流式传输（渠道消息） -分块流式传输会在助手输出可用时，以较粗粒度的分块发送内容。 +分块流式传输会在助手输出可用时，以较粗粒度的块发送内容。 ``` Model output @@ -39,74 +39,67 @@ Model output 图例： -- `text_delta/events`：模型流事件（对于非流式模型，可能较为稀疏）。 -- `chunker`：应用最小/最大边界 + 断点偏好的 `EmbeddedBlockChunker`。 -- `channel send`：实际发出的出站消息（分块回复）。 +- `text_delta/events`：模型流事件（对于非流式模型可能较稀疏）。 +- `chunker`：应用最小/最大边界和断点偏好的 `EmbeddedBlockChunker`。 +- `channel send`：实际发出的消息（分块回复）。 **控制项：** - `agents.defaults.blockStreamingDefault`：`"on"`/`"off"`（默认关闭）。 -- 渠道覆盖：`*.blockStreaming`（以及每账号变体）可为每个渠道强制设为 `"on"`/`"off"`。 +- 渠道覆盖：`*.blockStreaming`（以及按账户区分的变体），用于按渠道强制设为 `"on"`/`"off"`。 - `agents.defaults.blockStreamingBreak`：`"text_end"` 或 `"message_end"`。 - `agents.defaults.blockStreamingChunk`：`{ minChars, maxChars, breakPreference? }`。 -- `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（发送前合并流式块）。 +- `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（发送前合并已流出的块）。 - 渠道硬上限：`*.textChunkLimit`（例如 `channels.whatsapp.textChunkLimit`）。 - 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 会先按空行即段落边界拆分，再按长度分块）。 -- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17），会拆分过高的回复以避免 UI 裁切。 +- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17），用于拆分过高的回复，避免 UI 裁切。 **边界语义：** -- `text_end`：只要 chunker 发出块就立即流式发送；在每个 `text_end` 时刷新。 +- `text_end`：只要 chunker 产出块就立即流出；每次 `text_end` 时刷新。 - `message_end`：等待助手消息完成后，再刷新缓冲输出。 -即使使用 `message_end`，如果缓冲文本超过 `maxChars`，仍会使用 chunker，因此它可以在结束时发出多个分块。 +`message_end` 在缓冲文本超过 `maxChars` 时仍会使用 chunker，因此它可以在结束时输出多个块。 ## 分块算法（低/高边界） -分块流式传输由 `EmbeddedBlockChunker` 实现： +分块处理由 `EmbeddedBlockChunker` 实现： -- **低边界：** 在缓冲区达到 `minChars` 之前不发出内容（除非被强制）。 -- **高边界：** 优先在 `maxChars` 之前拆分；如果必须强制拆分，则在 `maxChars` 处切分。 -- **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬拆分。 -- **代码围栏：** 绝不在围栏内部拆分；如果必须在 `maxChars` 处强制拆分，会关闭并重新打开围栏以保持 Markdown 有效。 +- **低边界：** 在缓冲区长度达到 `minChars` 之前不输出（除非被强制输出）。 +- **高边界：** 尽量在 `maxChars` 之前切分；如果必须强制切分，则在 `maxChars` 处切开。 +- **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬切分。 +- **代码围栏：** 绝不在围栏内部切分；如果必须在 `maxChars` 处强制切分，会先闭合再重新打开围栏，以保持 Markdown 有效。 -`maxChars` 会被限制到渠道的 `textChunkLimit`，因此你不能超过每个渠道的上限。 +`maxChars` 会被限制到渠道的 `textChunkLimit`，因此不会超过每个渠道的上限。 -## 合并发送（合并流式块） +## 合并（合并已流出的块） -启用分块流式传输时，OpenClaw 可以在发送前**合并连续的分块内容**。 -这样既能提供渐进式输出，又能减少“单行刷屏”。 +启用分块流式传输时，OpenClaw 可以在发送前**合并连续的分块内容**。这样可以减少“单行刷屏”，同时仍然提供渐进式输出。 - 合并会等待**空闲间隔**（`idleMs`）后再刷新。 -- 缓冲区受 `maxChars` 限制，超过时会立即刷新。 -- `minChars` 可防止过小碎片被发送，直到累计了足够文本 - （最终刷新时总会发送剩余文本）。 -- 连接符由 `blockStreamingChunk.breakPreference` - 推导得出（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。 -- 可通过 `*.blockStreamingCoalesce` 提供渠道级覆盖（包括每账号配置）。 -- 对于 Signal/Slack/Discord，默认的合并 `minChars` 会提升到 1500，除非另有覆盖。 +- 缓冲区受 `maxChars` 限制，超出时会立即刷新。 +- `minChars` 会阻止过小的碎片发送，直到累积足够文本（最终刷新总会发送剩余文本）。 +- 连接符由 `blockStreamingChunk.breakPreference` 推导而来（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。 +- 可通过 `*.blockStreamingCoalesce` 进行渠道级覆盖（包括按账户配置）。 +- 对于 Signal/Slack/Discord，默认的合并 `minChars` 会提升到 1500，除非被覆盖。 -## 分块之间更像人类的节奏 +## 块之间更像人类的节奏 -启用分块流式传输时，你可以在 -分块回复之间（首个分块之后）加入**随机暂停**。这会让多气泡回复感觉 -更自然。 +启用分块流式传输时，你可以在分块回复之间加入**随机暂停**（第一块之后）。这样会让多气泡回复感觉更自然。 -- 配置：`agents.defaults.humanDelay`（可通过 `agents.list[].humanDelay` 为每个智能体覆盖）。 +- 配置：`agents.defaults.humanDelay`（可通过 `agents.list[].humanDelay` 按智能体覆盖）。 - 模式：`off`（默认）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。 -- 仅适用于**分块回复**，不适用于最终回复或工具摘要。 +- 仅应用于**分块回复**，不适用于最终回复或工具摘要。 -## “流式发送分块”还是“最后一次性发送” +## “流式发送分块”还是“最后一次性发送全部内容” -它映射为： +这对应到： -- **流式发送分块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发出）。非 Telegram 渠道还需要设置 `*.blockStreaming: true`。 -- **在结尾一次性流式发送全部内容：** `blockStreamingBreak: "message_end"`（只刷新一次；如果内容很长，可能仍会拆成多个分块）。 +- **流式发送分块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边输出）。非 Telegram 渠道还需要设置 `*.blockStreaming: true`。 +- **最后一次性流式发送全部内容：** `blockStreamingBreak: "message_end"`（一次刷新，若内容很长则可能分成多个块）。 - **不启用分块流式传输：** `blockStreamingDefault: "off"`（只发送最终回复）。 -**渠道说明：** 除非 -显式将 `*.blockStreaming` 设为 `true`，否则分块流式传输**默认关闭**。渠道即使没有分块回复，也可以通过 -`channels..streaming` 流式显示实时预览。 +**渠道说明：** 分块流式传输默认是**关闭的**，除非显式将 `*.blockStreaming` 设为 `true`。渠道可以在没有分块回复的情况下启用实时预览流式传输（`channels..streaming`）。 配置位置提醒：`blockStreaming*` 默认项位于 `agents.defaults` 下，而不是根配置。 @@ -118,66 +111,74 @@ Model output - `off`：禁用预览流式传输。 - `partial`：使用单个预览，并用最新文本替换它。 -- `block`：以分块/追加的方式逐步更新预览。 -- `progress`：在生成期间显示进度/状态预览，完成时发送最终答案。 +- `block`：预览以分块/追加的方式逐步更新。 +- `progress`：生成期间显示进度/状态预览，完成后再显示最终答案。 ### 渠道映射 | 渠道 | `off` | `partial` | `block` | `progress` | -| ---------- | ----- | --------- | ------- | ----------------- | -| Telegram | ✅ | ✅ | ✅ | 映射为 `partial` | -| Discord | ✅ | ✅ | ✅ | 映射为 `partial` | -| Slack | ✅ | ✅ | ✅ | ✅ | -| Mattermost | ✅ | ✅ | ✅ | ✅ | +| ---- | ----- | --------- | ------- | ---------- | +| Telegram | ✅ | ✅ | ✅ | 映射到 `partial` | +| Discord | ✅ | ✅ | ✅ | 映射到 `partial` | +| Slack | ✅ | ✅ | ✅ | ✅ | +| Mattermost | ✅ | ✅ | ✅ | ✅ | -仅 Slack： +仅限 Slack： -- `channels.slack.streaming.nativeTransport` 在 `channels.slack.streaming.mode="partial"` 时切换 Slack 原生流式 API 调用（默认：`true`）。 +- `channels.slack.streaming.nativeTransport` 用于在 `channels.slack.streaming.mode="partial"` 时切换 Slack 原生流式 API 调用（默认：`true`）。 - Slack 原生流式传输和 Slack 助手线程状态都需要一个回复线程目标；顶级私信不会显示这种线程式预览。 旧键迁移： -- Telegram：`streamMode` + 布尔型 `streaming` 会自动迁移到 `streaming` 枚举。 -- Discord：`streamMode` + 布尔型 `streaming` 会自动迁移到 `streaming` 枚举。 +- Telegram：`streamMode` 和布尔型 `streaming` 会自动迁移到枚举型 `streaming`。 +- Discord：`streamMode` 和布尔型 `streaming` 会自动迁移到枚举型 `streaming`。 - Slack：`streamMode` 会自动迁移到 `streaming.mode`；布尔型 `streaming` 会自动迁移到 `streaming.mode` 加 `streaming.nativeTransport`；旧版 `nativeStreaming` 会自动迁移到 `streaming.nativeTransport`。 ### 运行时行为 Telegram： -- 在私信和群组/话题中使用 `sendMessage` + `editMessageText` 更新预览。 -- 如果显式启用了 Telegram 分块流式传输，则会跳过预览流式传输（以避免双重流式传输）。 -- `/reasoning stream` 可以将推理内容写入预览。 +- 在私信和群组/话题中，使用 `sendMessage` + `editMessageText` 更新预览。 +- 当 Telegram 分块流式传输被显式启用时，会跳过预览流式传输（以避免双重流式传输）。 +- `/reasoning stream` 可以将 reasoning 写入预览。 Discord： - 使用发送 + 编辑预览消息。 - `block` 模式使用草稿分块（`draftChunk`）。 -- 如果显式启用了 Discord 分块流式传输，则会跳过预览流式传输。 +- 当 Discord 分块流式传输被显式启用时，会跳过预览流式传输。 +- 最终媒体、错误和显式回复负载会取消待处理预览而不刷新新的草稿，然后使用正常投递。 Slack： -- `partial` 在可用时可使用 Slack 原生流式传输（`chat.startStream`/`append`/`stop`）。 +- `partial` 在可用时可以使用 Slack 原生流式传输（`chat.startStream`/`append`/`stop`）。 - `block` 使用追加式草稿预览。 -- `progress` 使用状态预览文本，然后发送最终答案。 +- `progress` 使用状态预览文本，然后显示最终答案。 +- 最终媒体/错误负载和进度最终消息不会创建一次性草稿消息；只有可编辑预览的文本/块最终消息才会刷新待处理草稿文本。 Mattermost： - 将 thinking、工具活动和部分回复文本流式写入单个草稿预览帖子，并在最终答案可安全发送时原地完成。 -- 如果在完成时预览帖子已被删除或因其他原因不可用，则回退为发送一条新的最终帖子。 +- 如果预览帖子在完成时被删除或因其他原因不可用，则回退为发送新的最终帖子。 +- 最终媒体/错误负载会在正常投递前取消待处理预览更新，而不是刷新临时预览帖子。 + +Matrix： + +- 当最终文本可以复用预览事件时，草稿预览会原地完成。 +- 仅媒体、错误和回复目标不匹配的最终消息会在正常投递前取消待处理预览更新；已显示的陈旧预览会被撤回。 ### 工具进度预览更新 -预览流式传输还可以包含**工具进度**更新——例如“正在搜索网络”“正在读取文件”或“正在调用工具”之类的简短状态行——这些内容会在工具运行期间显示在同一条预览消息中，先于最终回复出现。这样，多步骤的工具回合在视觉上会保持活跃，而不是在首次 thinking 预览和最终答案之间显得沉默。 +预览流式传输还可以包含**工具进度**更新——例如“正在搜索网络”“正在读取文件”或“正在调用工具”这样的简短状态行——在工具运行期间，这些内容会出现在同一条预览消息中，并先于最终回复显示。这样可以让多步骤工具调用在视觉上保持活跃，而不是在最初的 thinking 预览和最终答案之间保持沉默。 支持的界面： - **Discord**、**Slack** 和 **Telegram** 会将工具进度流式写入实时预览编辑中。 - **Mattermost** 已经将工具活动整合进其单一草稿预览帖子中（见上文）。 -- 工具进度编辑遵循当前启用的预览流式传输模式；当预览流式传输为 `off`，或当分块流式传输已接管该消息时，会跳过这些更新。 +- 工具进度编辑遵循当前启用的预览流式传输模式；当预览流式传输为 `off` 或消息已被分块流式传输接管时，会跳过这些更新。 ## 相关内容 -- [消息](/zh-CN/concepts/messages) — 消息生命周期与投递 -- [重试](/zh-CN/concepts/retry) — 投递失败时的重试行为 -- [渠道](/zh-CN/channels) — 每个渠道的流式传输支持 +- [消息](/zh-CN/concepts/messages) —— 消息生命周期与投递 +- [重试](/zh-CN/concepts/retry) —— 投递失败时的重试行为 +- [渠道](/zh-CN/channels) —— 各渠道的流式传输支持 diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 85e813e35..a68d02b43 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -3,77 +3,76 @@ read_when: - 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 - 你正在将一个插件更新到现代插件架构 - - 你在维护一个外部 OpenClaw 插件 + - 你维护着一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-21T04:19:35Z" + generated_at: "2026-04-22T01:34:47Z" model: gpt-5.4 provider: openai - source_hash: d3d2ea9a8cc869b943ad774ac0ddb8828b80ce86432ece7b9aeed4f1edb30859 + source_hash: 72c9fc2d77f5feda336a1119fc42ebe088d5037f99c2b3843e9f06efed20386d source_path: plugins/sdk-migration.md workflow: 15 --- # 插件 SDK 迁移 -OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且有文档说明的导入方式。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 +OpenClaw 已经从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且有文档说明的导入路径。如果你的插件构建于新架构推出之前，本指南将帮助你完成迁移。 ## 正在发生什么变化 -旧版插件系统提供了两个宽开放的入口，使插件可以从单个入口点导入所需的任何内容： +旧版插件系统提供了两个开放度很高的接口面，让插件可以通过单一入口导入所需的任何内容： -- **`openclaw/plugin-sdk/compat`** —— 单个导入入口，重新导出了数十个辅助工具。引入它是为了在构建新插件架构期间，保持较旧的基于钩子的插件继续工作。 -- **`openclaw/extension-api`** —— 一个桥接层，使插件可以直接访问宿主侧辅助工具，例如嵌入式 Pi 智能体运行器。 +- **`openclaw/plugin-sdk/compat`** — 一个单一导入入口，会重新导出几十个辅助工具。它的引入是为了在构建新插件架构期间，让旧的基于 hook 的插件继续工作。 +- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问宿主侧辅助工具，例如内嵌的智能体运行器。 -这两个入口现在都已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件应在下一个主版本移除它们之前完成迁移。 +这两个接口面现在都已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 - 向后兼容层将在未来的某个主版本中移除。 - 到那时，仍从这些入口导入的插件将会失效。 + 向后兼容层将在未来的某个主版本中被移除。到那时，仍然从这些接口面导入的插件将会失效。 ## 为什么会有这个变化 -旧方法带来了一些问题： +旧方法带来了这些问题： -- **启动缓慢** —— 导入一个辅助工具会加载数十个无关模块 -- **循环依赖** —— 宽泛的重新导出让创建导入循环变得很容易 -- **API 入口不清晰** —— 无法判断哪些导出是稳定的，哪些是内部实现 +- **启动缓慢** — 导入一个辅助工具会加载几十个无关模块 +- **循环依赖** — 宽泛的重新导出很容易造成导入循环 +- **API 接口面不清晰** — 无法分辨哪些导出是稳定的，哪些是内部实现 现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、独立的模块，具有明确用途和文档化契约。 -面向内置渠道的旧版提供商便捷入口也已移除。诸如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、渠道品牌化辅助入口以及 `openclaw/plugin-sdk/telegram-core` 之类的导入，都是私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，请将提供商拥有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +面向内置渠道的旧版提供商便捷接口也已经移除。像 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口，以及 `openclaw/plugin-sdk/telegram-core` 这类导入，都是私有 monorepo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，请将提供商自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 当前内置提供商示例： -- Anthropic 将 Claude 专属的流式辅助工具保留在其自己的 `api.ts` / `contract-api.ts` 入口中 -- OpenAI 将提供商构建器、默认模型辅助工具和实时提供商构建器保留在其自己的 `api.ts` 中 -- OpenRouter 将提供商构建器以及新手引导/配置辅助工具保留在其自己的 `api.ts` 中 +- Anthropic 将 Claude 专用的流式传输辅助工具保留在它自己的 `api.ts` / `contract-api.ts` 接口中 +- OpenAI 将提供商构建器、默认模型辅助工具和实时提供商构建器保留在它自己的 `api.ts` 中 +- OpenRouter 将提供商构建器以及新手引导 / 配置辅助工具保留在它自己的 `api.ts` 中 ## 如何迁移 - - 具备审批能力的渠道插件现在通过 `approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来暴露原生审批行为。 + + 支持审批的渠道插件现在通过 `approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来暴露原生审批行为。 关键变化： - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 `approvalCapability.nativeRuntime` - - 将审批专用的认证/投递从旧版 `plugin.auth` / `plugin.approvals` 连接迁移到 `approvalCapability` - - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将 delivery/native/render 字段迁移到 `approvalCapability` - - `plugin.auth` 仅保留用于渠道登录/登出流程；其中的审批认证钩子不再被核心读取 - - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道拥有的运行时对象，例如客户端、令牌或 Bolt 应用 - - 不要从原生审批处理程序发送由插件拥有的重路由通知；核心现在会根据实际投递结果负责“已路由到其他位置”的通知 - - 在将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 入口。部分桩实现会被拒绝。 + - 将审批专用的认证 / 投递逻辑从旧版 `plugin.auth` / `plugin.approvals` 接线迁移到 `approvalCapability` + - `ChannelPlugin.approvals` 已从公开的渠道插件契约中移除；请将 delivery / native / render 字段迁移到 `approvalCapability` + - `plugin.auth` 仅保留用于渠道登录 / 登出流程；其中的审批认证 hook 不再被 core 读取 + - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt 应用 + - 不要从原生审批处理器发送插件自有的改道通知；core 现在会根据实际投递结果负责 “已路由到其他位置” 的通知 + - 在将 `channelRuntime` 传给 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 将被拒绝。 当前审批能力布局请参见 `/plugins/sdk-channel-plugins`。 - 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，未解析的 Windows `.cmd`/`.bat` 包装器现在会默认失败关闭，除非你显式传入 `allowShellFallback: true`。 + 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在未解析的 Windows `.cmd` / `.bat` 包装器会默认以失败关闭，除非你显式传入 `allowShellFallback: true`。 ```typescript // Before @@ -82,18 +81,17 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // Only set this for trusted compatibility callers that intentionally - // accept shell-mediated fallback. + // 仅为有意接受 shell 中介回退的受信任兼容性调用方设置此项。 allowShellFallback: true, }); ``` - 如果你的调用方并非有意依赖 shell 回退，请不要设置 `allowShellFallback`，而应改为处理抛出的错误。 + 如果你的调用方并不有意依赖 shell 回退，请不要设置 `allowShellFallback`，而应改为处理抛出的错误。 - 在你的插件中搜索来自这两个已弃用入口的导入： + 在你的插件中搜索来自任一已弃用接口面的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -103,7 +101,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 - 旧入口中的每个导出都映射到一个特定的现代导入路径： + 旧接口面的每个导出都映射到一个特定的现代导入路径： ```typescript // Before (deprecated backwards-compatibility layer) @@ -130,7 +128,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - 相同模式也适用于其他旧版桥接辅助工具： + 其他旧版桥接辅助工具也遵循相同模式： | 旧导入 | 现代等价项 | | --- | --- | @@ -140,7 +138,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | session store helpers | `api.runtime.agent.session.*` | + | 会话存储辅助工具 | `api.runtime.agent.session.*` | @@ -158,214 +156,210 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | | `plugin-sdk/plugin-entry` | 规范的插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版总括式重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/core` | 用于渠道入口定义 / 构建器的旧版聚合重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | | `plugin-sdk/provider-entry` | 单提供商入口辅助工具 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助工具 | allowlist 提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 可安全导入的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | + | `plugin-sdk/setup` | 共享的设置向导辅助工具 | allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 导入安全的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表/配置/操作门控辅助工具 | - | `plugin-sdk/account-id` | 账户 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化 | + | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表 / 配置 / 操作门控辅助工具 | + | `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 | | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表/账户操作辅助工具 | + | `plugin-sdk/account-helpers` | 精简的账户辅助工具 | 账户列表 / 账户操作辅助工具 | | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | 私信配对基础能力 | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入连接 | `createChannelReplyPipeline` | + | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入接线 | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 渠道配置 schema 类型 | - | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复/冲突校验 | - | `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | 账户状态跟踪 | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | 入站信封辅助工具 | 共享路由 + 信封构建器辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 | - | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名称规范化、描述裁剪、重复 / 冲突校验 | + | `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览最终化辅助工具 | + | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope 构建器辅助工具 | + | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录与分发辅助工具 | + | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助工具 | | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份/发送委托和负载规划辅助工具 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份 / 发送委托和载荷规划辅助工具 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧版字段布局的智能体媒体负载构建器 | - | `plugin-sdk/channel-runtime` | 已弃用的兼容性垫片 | 仅旧版渠道运行时工具 | + | `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助工具 | 用于旧字段布局的智能体媒体载荷构建器 | + | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅保留旧版渠道运行时工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | logger/运行时环境、超时、重试和退避辅助工具 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/钩子/http/交互式辅助工具 | - | `plugin-sdk/hook-runtime` | 钩子流水线辅助工具 | 共享 webhook/内部钩子流水线辅助工具 | - | `plugin-sdk/lazy-runtime` | 延迟运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/runtime` | 宽泛的运行时辅助工具 | 运行时 / 日志 / 备份 / 插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 精简的运行时环境辅助工具 | 日志器 / 运行时环境、超时、重试和退避辅助工具 | + | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / hook / http / 交互式辅助工具 | + | `plugin-sdk/hook-runtime` | hook 管道辅助工具 | 共享 webhook / 内部 hook 管道辅助工具 | + | `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 | | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 | | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 | - | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载/写入辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约入口不可用时，提供回退稳定的 Telegram 命令校验辅助工具 | - | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批负载、审批能力/配置文件辅助工具、原生审批路由/运行时辅助工具 | + | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供具备稳定回退能力的 Telegram 命令校验辅助工具 | + | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批载荷、审批能力 / 配置文件辅助工具、原生审批路由 / 运行时辅助工具 | | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同聊天操作认证 | - | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件/过滤辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力/投递适配器 | + | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件 / 过滤器辅助工具 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力 / 投递适配器 | | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向高频渠道入口的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 审批处理程序辅助工具 | 更宽范围的审批处理程序运行时辅助工具；如果更窄的 adapter/gateway 入口已足够，优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复负载辅助工具 | - | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register/get/watch 辅助工具 | - | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和秘密收集辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 用于高频渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽泛的审批处理器运行时辅助工具；若更精简的 adapter / gateway 接口已足够，优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复载荷辅助工具 | + | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register / get / watch 辅助工具 | + | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和敏感信息收集辅助工具 | | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 | - | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定 dispatcher、受保护 fetch、SSRF 策略辅助工具 | + | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | pinned-dispatcher、受保护 fetch、SSRF 策略辅助工具 | | `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` | | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`, 错误图辅助工具 | - | `plugin-sdk/fetch-runtime` | 封装的 fetch/代理辅助工具 | `resolveFetch`、代理辅助工具 | + | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch / 代理辅助工具 | `resolveFetch`、代理辅助工具 | | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`, 策略运行器 | + | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 | | `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` | | `plugin-sdk/allowlist-resolution` | allowlist 输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令门控和命令入口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | - | `plugin-sdk/command-status` | 命令状态/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | secret 输入解析 | secret 输入辅助工具 | - | `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标工具 | - | `plugin-sdk/webhook-request-guards` | webhook 请求体守卫辅助工具 | 请求体读取/限制辅助工具 | - | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | finalize + provider 分发辅助工具 | + | `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | + | `plugin-sdk/command-status` | 命令状态 / 帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | 敏感信息输入解析 | 敏感信息输入辅助工具 | + | `plugin-sdk/webhook-ingress` | Webhook 请求辅助工具 | Webhook 目标工具 | + | `plugin-sdk/webhook-request-guards` | Webhook 请求体保护辅助工具 | 请求体读取 / 限制辅助工具 | + | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、heartbeat、回复规划器、分块 | + | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发辅助工具 | 最终化 + 提供商分发辅助工具 | | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/Markdown 分块辅助工具 | + | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本 / markdown 分块辅助工具 | | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 | | `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 | - | `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 | - | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道/账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | + | `plugin-sdk/routing` | 路由 / session-key 辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、session-key 规范化辅助工具 | + | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道 / 账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 | - | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug/字符串规范化辅助工具 | + | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug / 字符串规范化辅助工具 | | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类请求输入中提取字符串 URL | - | `plugin-sdk/run-command` | 定时命令辅助工具 | 带标准化 stdout/stderr 的定时命令运行器 | - | `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 工具负载提取 | 从工具结果对象中提取标准化负载 | - | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | + | `plugin-sdk/run-command` | 定时命令辅助工具 | 带标准化 stdout / stderr 的定时命令运行器 | + | `plugin-sdk/param-readers` | 参数读取器 | 通用工具 / CLI 参数读取器 | + | `plugin-sdk/tool-payload` | 工具载荷提取 | 从工具结果对象中提取标准化载荷 | + | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范的发送目标字段 | | `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 | - | `plugin-sdk/logging-core` | 日志辅助工具 | 子系统 logger 和脱敏辅助工具 | + | `plugin-sdk/logging-core` | 日志辅助工具 | 子系统日志器和脱敏辅助工具 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 | - | `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 | - | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 | 自托管提供商发现/配置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助工具 | 同一组自托管提供商发现/配置辅助工具 | + | `plugin-sdk/reply-payload` | 消息回复类型 | 回复载荷类型 | + | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助工具 | 自托管提供商发现 / 配置辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助工具 | 同样的自托管提供商发现 / 配置辅助工具 | | `plugin-sdk/provider-auth-runtime` | 提供商运行时认证辅助工具 | 运行时 API key 解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | 提供商 API key 设置辅助工具 | API key 新手引导/配置文件写入辅助工具 | + | `plugin-sdk/provider-auth-api-key` | 提供商 API key 设置辅助工具 | API key 新手引导 / 配置文件写入辅助工具 | | `plugin-sdk/provider-auth-result` | 提供商认证结果辅助工具 | 标准 OAuth 认证结果构建器 | | `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助工具 | 共享交互式登录辅助工具 | | `plugin-sdk/provider-env-vars` | 提供商环境变量辅助工具 | 提供商认证环境变量查找辅助工具 | - | `plugin-sdk/provider-model-shared` | 共享提供商模型/重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、提供商端点辅助工具以及 model-id 规范化辅助工具 | + | `plugin-sdk/provider-model-shared` | 共享提供商模型 / 重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、提供商端点辅助工具以及 model-id 规范化辅助工具 | | `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助工具 | - | `plugin-sdk/provider-http` | 提供商 HTTP 辅助工具 | 通用提供商 HTTP/端点能力辅助工具 | - | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助工具 | web-fetch 提供商注册/缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 提供商 web 搜索配置辅助工具 | 适用于不需要插件启用连接的提供商的窄范围 web 搜索配置/凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 提供商 web 搜索契约辅助工具 | 窄范围 web 搜索配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及带作用域的凭证 setter/getter | - | `plugin-sdk/provider-web-search` | 提供商 web 搜索辅助工具 | web 搜索提供商注册/缓存/运行时辅助工具 | - | `plugin-sdk/provider-tools` | 提供商工具/schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助工具 | + | `plugin-sdk/provider-http` | 提供商 HTTP 辅助工具 | 通用提供商 HTTP / 端点能力辅助工具 | + | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助工具 | web-fetch 提供商注册 / 缓存辅助工具 | + | `plugin-sdk/provider-web-search-config-contract` | 提供商 web-search 配置辅助工具 | 为不需要插件启用接线的提供商提供精简的 web-search 配置 / 凭证辅助工具 | + | `plugin-sdk/provider-web-search-contract` | 提供商 web-search 契约辅助工具 | 精简的 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化的凭证设置器 / 获取器 | + | `plugin-sdk/provider-web-search` | 提供商 web-search 辅助工具 | web-search 提供商注册 / 缓存 / 运行时辅助工具 | + | `plugin-sdk/provider-tools` | 提供商工具 / schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | 提供商用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他提供商用量辅助工具 | - | `plugin-sdk/provider-stream` | 提供商流包装器辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | - | `plugin-sdk/provider-transport-runtime` | 提供商传输辅助工具 | 原生提供商传输辅助工具，例如受保护 fetch、传输消息转换以及可写传输事件流 | + | `plugin-sdk/provider-stream` | 提供商流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助工具 | + | `plugin-sdk/provider-transport-runtime` | 提供商传输辅助工具 | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换和可写的传输事件流 | | `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体 fetch/转换/存储辅助工具，以及媒体负载构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 用于图像/视频/音乐生成的共享故障切换辅助工具、候选项选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解提供商类型，以及面向提供商的图像/音频辅助工具导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本/日志辅助工具 | + | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取 / 转换 / 存储辅助工具，以及媒体载荷构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 用于图像 / 视频 / 音乐生成的共享故障转移辅助工具、候选项选择和缺失模型提示 | + | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助工具导出 | + | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本 / 日志辅助工具 | | `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 | | `plugin-sdk/speech` | 语音辅助工具 | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 | - | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、directives、规范化 | + | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、规范化 | | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | 提供商类型和注册表辅助工具 | | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | 提供商类型和注册表辅助工具 | - | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障切换、认证和注册表辅助工具 | - | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成提供商/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成提供商/请求/结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化/归约 | - | `plugin-sdk/channel-config-primitives` | 渠道配置基础能力 | 窄范围渠道 config-schema 基础能力 | + | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助工具 | + | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成提供商 / 请求 / 结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成提供商 / 请求 / 结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复载荷规范化 / 归约 | + | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 精简的渠道 config-schema 原语 | | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 | | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 | - | `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照/摘要辅助工具 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑/读取辅助工具 | + | `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照 / 摘要辅助工具 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑 / 读取辅助工具 | | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证/守卫辅助工具 | - | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/状态和环境代理辅助工具基础能力 | - | `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和路由安装辅助工具 | - | `plugin-sdk/webhook-path` | webhook 路径辅助工具 | webhook 路径规范化辅助工具 | - | `plugin-sdk/web-media` | 共享 web 媒体辅助工具 | 远程/本地媒体加载辅助工具 | + | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证 / 保护辅助工具 | + | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态和环境代理辅助工具原语 | + | `plugin-sdk/webhook-targets` | Webhook 目标辅助工具 | Webhook 目标注册表和路由安装辅助工具 | + | `plugin-sdk/webhook-path` | Webhook 路径辅助工具 | Webhook 路径规范化辅助工具 | + | `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程 / 本地媒体加载辅助工具 | | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用方重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 管理器/配置/文件/CLI 辅助工具入口 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时门面 | Memory 索引/搜索运行时门面 | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 管理器 / 配置 / 文件 / CLI 辅助工具接口 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时门面 | Memory 索引 / 搜索运行时门面 | | `plugin-sdk/memory-core-host-engine-foundation` | Memory 宿主基础引擎 | Memory 宿主基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地提供商以及通用批处理/远程辅助工具；具体远程提供商位于各自所属插件中 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地提供商和通用批处理 / 远程辅助工具；具体远程提供商位于其所属插件中 | | `plugin-sdk/memory-core-host-engine-qmd` | Memory 宿主 QMD 引擎 | Memory 宿主 QMD 引擎导出 | | `plugin-sdk/memory-core-host-engine-storage` | Memory 宿主存储引擎 | Memory 宿主存储引擎导出 | | `plugin-sdk/memory-core-host-multimodal` | Memory 宿主多模态辅助工具 | Memory 宿主多模态辅助工具 | | `plugin-sdk/memory-core-host-query` | Memory 宿主查询辅助工具 | Memory 宿主查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory 宿主 secret 辅助工具 | Memory 宿主 secret 辅助工具 | + | `plugin-sdk/memory-core-host-secret` | Memory 宿主敏感信息辅助工具 | Memory 宿主敏感信息辅助工具 | | `plugin-sdk/memory-core-host-events` | Memory 宿主事件日志辅助工具 | Memory 宿主事件日志辅助工具 | | `plugin-sdk/memory-core-host-status` | Memory 宿主状态辅助工具 | Memory 宿主状态辅助工具 | | `plugin-sdk/memory-core-host-runtime-cli` | Memory 宿主 CLI 运行时 | Memory 宿主 CLI 运行时辅助工具 | | `plugin-sdk/memory-core-host-runtime-core` | Memory 宿主核心运行时 | Memory 宿主核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件/运行时辅助工具 | Memory 宿主文件/运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件 / 运行时辅助工具 | Memory 宿主文件 / 运行时辅助工具 | | `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向供应商中立的 Memory 宿主核心运行时辅助工具别名 | | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向供应商中立的 Memory 宿主事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | Memory 宿主文件/运行时别名 | 面向供应商中立的 Memory 宿主文件/运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助工具 | 用于 memory 相邻插件的共享托管 Markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索门面 | 延迟加载的活跃 Memory 搜索管理器运行时门面 | + | `plugin-sdk/memory-host-files` | Memory 宿主文件 / 运行时别名 | 面向供应商中立的 Memory 宿主文件 / 运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 受管 markdown 辅助工具 | 面向 memory 邻近插件的共享受管 markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索门面 | 惰性活跃 Memory 搜索管理器运行时门面 | | `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向供应商中立的 Memory 宿主状态辅助工具别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助工具入口 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助工具接口 | | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mock | -此表有意只包含常见迁移子集，而不是完整的 SDK -入口。完整的 200+ 入口列表位于 +这个表格有意只包含常见迁移子集，而不是完整的 SDK 接口面。完整的 200 多个入口点列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 -该列表仍包含一些内置插件辅助入口，例如 +该列表仍然包含一些内置插件辅助接口，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 -`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些入口仍会继续导出， -用于内置插件维护和兼容性，但它们被有意省略出常见迁移表，也不是 -新插件代码的推荐目标。 +`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些导出仍会保留，用于内置插件维护和兼容性，但它们被有意排除在常见迁移表之外，也不是新插件代码的推荐目标。 -相同规则也适用于其他内置辅助工具系列，例如： +同样的规则也适用于其他内置辅助工具族，例如： -- 浏览器支持辅助工具：`plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` +- 浏览器支持辅助工具：`plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix：`plugin-sdk/matrix*` - LINE：`plugin-sdk/line*` - IRC：`plugin-sdk/irc*` -- 内置辅助工具/插件入口，例如 `plugin-sdk/googlechat`、 - `plugin-sdk/zalouser`、`plugin-sdk/bluebubbles*`、 - `plugin-sdk/mattermost*`、`plugin-sdk/msteams`、 - `plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、 - `plugin-sdk/twitch`、 - `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、 - `plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、 +- 内置辅助工具 / 插件接口，例如 `plugin-sdk/googlechat`、 + `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, + `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, + `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, + `plugin-sdk/twitch`, + `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, + `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` 和 `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` 当前暴露了窄范围 token 辅助工具 -入口 `DEFAULT_COPILOT_API_BASE_URL`、 +`plugin-sdk/github-copilot-token` 当前暴露的是精简的令牌辅助工具接口： +`DEFAULT_COPILOT_API_BASE_URL`、 `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 -请使用与你任务最匹配的最窄导入路径。如果你找不到某个导出， -请查看 `src/plugin-sdk/` 下的源码，或在 Discord 中提问。 +请使用与你的任务最匹配的最精简导入。如果你找不到某个导出，请查看 `src/plugin-sdk/` 中的源码，或在 Discord 中提问。 ## 移除时间线 | 时间 | 会发生什么 | | ---------------------- | ----------------------------------------------------------------------- | -| **现在** | 已弃用入口会发出运行时警告 | -| **下一个主版本发布时** | 已弃用入口将被移除；仍在使用它们的插件将会失效 | +| **现在** | 已弃用接口面会发出运行时警告 | +| **下一个主版本发布时** | 已弃用接口面将被移除；仍在使用它们的插件将会失效 | -所有核心插件都已完成迁移。外部插件应在下一个主版本发布前完成迁移。 +所有 core 插件都已完成迁移。外部插件应在下一个主版本发布前完成迁移。 ## 临时抑制警告 -在你进行迁移期间，可设置以下环境变量： +在你进行迁移时，设置这些环境变量： ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -这只是临时的应急方式，不是永久解决方案。 +这只是一个临时逃生舱口，不是永久解决方案。 ## 相关内容 @@ -373,5 +367,5 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 -- [插件内部机制](/zh-CN/plugins/architecture) — 架构深度解析 +- [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析 - [插件清单](/zh-CN/plugins/manifest) — 清单 schema 参考 diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index 253b9e9ac..59bbe6e02 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -1,60 +1,60 @@ --- read_when: - 你需要知道应从哪个 SDK 子路径导入 - - 你想查看 `OpenClawPluginApi` 上所有注册方法的参考说明 + - 你想查看 OpenClawPluginApi 上所有注册方法的参考资料 - 你正在查找某个特定的 SDK 导出项 sidebarTitle: SDK Overview -summary: 导入映射、注册 API 参考和 SDK 架构 +summary: Import map、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-04-21T20:34:46Z" + generated_at: "2026-04-22T01:34:41Z" model: gpt-5.4 provider: openai - source_hash: 16ef34e4ad4550967d06ea6bd94b3400431c0fb536bf267cc4e8a09ec9483695 + source_hash: 8045c11976bbda6afe3303a0aab08caf0d0a86ebcf1aaaf927943b90cc517673 source_path: plugins/sdk-overview.md workflow: 15 --- # 插件 SDK 概览 -插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考。 +插件 SDK 是插件与核心之间的类型化契约。本页是关于**应导入什么**以及**你可以注册什么**的参考资料。 **在找操作指南吗？** - 第一个插件？从 [入门指南](/zh-CN/plugins/building-plugins) 开始 - - 渠道插件？请参阅 [渠道插件](/zh-CN/plugins/sdk-channel-plugins) - - 提供商插件？请参阅 [提供商插件](/zh-CN/plugins/sdk-provider-plugins) + - 渠道插件？参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins) + - 提供商插件？参见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins) ## 导入约定 -始终从特定子路径导入： +始终从特定的子路径导入： ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -每个子路径都是一个小型、独立的模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口点 / 构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总入口表面以及诸如 `buildChannelConfigSchema` 之类的共享辅助函数。 +每个子路径都是一个小型、独立的模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括性表面和共享辅助工具，例如 `buildChannelConfigSchema`。 -不要添加或依赖带有提供商名称的便捷接口，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助接口。内置插件应在它们自己的 `api.ts` 或 `runtime-api.ts` barrel 中组合通用 SDK 子路径，而核心应使用这些插件本地 barrel，或者仅当需求确实跨渠道时，添加一个狭义的通用 SDK 契约。 +不要添加或依赖带有提供商名称的便捷接缝，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助工具接缝。内置插件应在其自身的 `api.ts` 或 `runtime-api.ts` barrel 中组合通用 SDK 子路径，而核心则应使用这些插件本地 barrel，或者在需求确实跨渠道时添加一个狭义的通用 SDK 契约。 -生成的导出映射仍然包含一小组内置插件辅助接口，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 以及 `plugin-sdk/matrix*`。这些子路径仅用于内置插件维护和兼容性；它们被有意省略在下面的常用表格之外，也不是新第三方插件的推荐导入路径。 +生成的导出映射仍然包含一小部分内置插件辅助工具接缝，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅为内置插件维护和兼容性而存在；它们有意未包含在下面的通用表格中，也不是新第三方插件的推荐导入路径。 ## 子路径参考 -最常用的子路径，按用途分组。完整的 200 多个子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 +最常用的子路径，按用途分组。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json` 中。 -保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其作为公共接口推广，否则应将它们视为实现细节 / 兼容性接口。 +保留的内置插件辅助工具子路径仍会出现在该生成列表中。除非某个文档页面明确将其推广为公共接口，否则应将其视为实现细节/兼容性表面。 -### 插件入口点 +### 插件入口 -| 子路径 | 关键导出 | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| 子路径 | 关键导出 | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | @@ -62,286 +62,286 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | - | `plugin-sdk/setup` | 共享设置向导辅助函数、allowlist 提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`、`noteChannelLookupFailure`、`noteChannelLookupSummary`、`promptResolvedAllowFrom`、`splitSetupEntries`、`createAllowlistSetupWizardProxy`、`createDelegatedSetupWizardProxy` | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | `formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户配置 / action-gate 辅助函数、默认账户回退辅助函数 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 | - | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 | - | `plugin-sdk/account-helpers` | 狭义的账户列表 / 账户操作辅助函数 | + | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | 多账户 config/action-gate 辅助工具、默认账户回退辅助工具 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 | + | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 | + | `plugin-sdk/account-helpers` | 狭义的账户列表/账户操作辅助工具 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 验证辅助函数，并带有内置契约回退 | - | `plugin-sdk/command-gating` | 狭义命令授权门控辅助函数 | + | `plugin-sdk/channel-config-schema` | 渠道 config schema 类型 | + | `plugin-sdk/telegram-command-config` | 带有内置契约回退的 Telegram 自定义命令规范化/验证辅助工具 | + | `plugin-sdk/command-gating` | 狭义的命令授权门控辅助工具 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助函数 | - | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助函数 | - | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 | - | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助函数 | - | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助函数 | - | `plugin-sdk/poll-runtime` | 狭义投票规范化辅助函数 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/最终化辅助工具 | + | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建器辅助工具 | + | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录并分发辅助工具 | + | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 | + | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 | + | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助工具 | + | `plugin-sdk/poll-runtime` | 狭义的投票规范化辅助工具 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 | | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 | - | `plugin-sdk/conversation-runtime` | 对话 / 线程绑定、配对和已配置绑定辅助函数 | - | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 | - | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 | - | `plugin-sdk/channel-status` | 共享渠道状态快照 / 摘要辅助函数 | - | `plugin-sdk/channel-config-primitives` | 狭义渠道配置 schema 基元 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 | + | `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助工具 | + | `plugin-sdk/runtime-config-snapshot` | 运行时 config 快照辅助工具 | + | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 | + | `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助工具 | + | `plugin-sdk/channel-config-primitives` | 狭义的渠道 config-schema 原语 | + | `plugin-sdk/channel-config-writes` | 渠道 config 写入授权辅助工具 | | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助函数 | - | `plugin-sdk/group-access` | 共享群组访问决策辅助函数 | - | `plugin-sdk/direct-dm` | 共享直接私信认证 / 守卫辅助函数 | - | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递和旧版交互式回复辅助函数。请参阅 [消息呈现](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 用于入站去抖动、提及匹配、提及策略辅助函数和 envelope 辅助函数的兼容性 barrel | - | `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时表面的狭义提及策略辅助函数 | - | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助函数 | - | `plugin-sdk/channel-logging` | 用于入站丢弃和 typing / ack 失败的渠道日志辅助函数 | + | `plugin-sdk/allowlist-config-edit` | allowlist config 编辑/读取辅助工具 | + | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 | + | `plugin-sdk/direct-dm` | 共享直接私信授权/守卫辅助工具 | + | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递和旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | 用于入站防抖、提及匹配、提及策略辅助工具和 envelope 辅助工具的兼容性 barrel | + | `plugin-sdk/channel-mention-gating` | 不含更广泛入站运行时表面的狭义提及策略辅助工具 | + | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 | + | `plugin-sdk/channel-logging` | 用于入站丢弃和 typing/ack 失败的渠道日志辅助工具 | | `plugin-sdk/channel-send-result` | 回复结果类型 | - | `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为插件兼容性保留的已弃用原生 schema 辅助函数 | - | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 | + | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 | + | `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 | | `plugin-sdk/channel-contract` | 渠道契约类型 | - | `plugin-sdk/channel-feedback` | 反馈 / reaction 接线 | - | `plugin-sdk/channel-secret-runtime` | 狭义 secret 契约辅助函数，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 以及 secret target 类型 | + | `plugin-sdk/channel-feedback` | 反馈/reaction 接线 | + | `plugin-sdk/channel-secret-runtime` | 狭义的密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和 secret target 类型 | | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 | - | `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商设置的聚焦辅助函数 | + | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管提供商的设置辅助工具 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API key 解析辅助函数 | - | `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置文件写入辅助函数，例如 `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | - | `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助函数 | - | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 | - | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`、`ensureApiKeyFromOptionEnvOrPrompt`、`upsertAuthProfile`、`upsertApiKeyProfile`、`writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 | - | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint capability 辅助函数 | - | `plugin-sdk/provider-web-fetch-contract` | 狭义 web-fetch 配置 / 选择契约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助函数 | - | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的狭义 web-search 配置 / 凭证辅助函数 | - | `plugin-sdk/provider-web-search-contract` | 狭义 web-search 配置 / 凭证契约辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及有作用域的凭证 setter / getter | - | `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助函数 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + diagnostics，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助函数 | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似项 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助函数 | - | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助函数，例如 guarded fetch、transport message transforms 和可写 transport event streams | - | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 | - | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助函数 | + | `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助工具 | + | `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile-write 辅助工具，例如 `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 | + | `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助工具 | + | `plugin-sdk/provider-env-vars` | 提供商凭证环境变量查找辅助工具 | + | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 | + | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-http` | 通用提供商 HTTP/endpoint 能力辅助工具 | + | `plugin-sdk/provider-web-fetch-contract` | 狭义的 web-fetch config/selection 契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册/缓存辅助工具 | + | `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用接线的提供商的狭义 web-search config/credential 辅助工具 | + | `plugin-sdk/provider-web-search-contract` | 狭义的 web-search config/credential 契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 和作用域化 credential setter/getter | + | `plugin-sdk/provider-web-search` | web-search 提供商注册/缓存/运行时辅助工具 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + diagnostics，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 等 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | + | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息变换和可写传输事件流 | + | `plugin-sdk/provider-onboard` | 新手引导 config patch 辅助工具 | + | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 | - + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 | - | `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | approver 解析和同聊天 action-auth 辅助函数 | - | `plugin-sdk/approval-client-runtime` | 原生 exec approval 配置文件 / 过滤器辅助函数 | - | `plugin-sdk/approval-delivery-runtime` | 原生 approval capability / delivery 适配器 | - | `plugin-sdk/approval-gateway-runtime` | 共享 approval Gateway 网关解析辅助函数 | - | `plugin-sdk/approval-handler-adapter-runtime` | 面向热渠道入口点的轻量级原生 approval adapter 加载辅助函数 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的 approval handler 运行时辅助函数；如果更狭义的 adapter / gateway 接口已足够，优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 原生 approval target + account-binding 辅助函数 | - | `plugin-sdk/approval-reply-runtime` | exec / plugin approval 回复负载辅助函数 | - | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生 session-target 辅助函数 | - | `plugin-sdk/command-detection` | 共享命令检测辅助函数 | - | `plugin-sdk/command-surface` | 命令体规范化和 command-surface 辅助函数 | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 | + | `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天 action-auth 辅助工具 | + | `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助工具 | + | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | + | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 用于热渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；在适用时优先使用更狭义的 adapter/gateway 接缝 | + | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | + | `plugin-sdk/approval-reply-runtime` | exec/plugin 审批回复负载辅助工具 | + | `plugin-sdk/command-auth-native` | 原生命令凭证 + 原生会话目标辅助工具 | + | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | + | `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助工具 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret surface 的狭义 secret-contract 收集辅助函数 | - | `plugin-sdk/secret-ref-runtime` | 用于 secret-contract / 配置解析的狭义 `coerceSecretRef` 和 SecretRef 类型辅助函数 | - | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助函数 | - | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 | - | `plugin-sdk/ssrf-dispatcher` | 不包含广泛基础设施运行时表面的狭义 pinned-dispatcher 辅助函数 | - | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、SSRF 防护 fetch 和 SSRF 策略辅助函数 | - | `plugin-sdk/secret-input` | secret 输入解析辅助函数 | - | `plugin-sdk/webhook-ingress` | webhook 请求 / target 辅助函数 | - | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 | + | `plugin-sdk/channel-secret-runtime` | 用于渠道/插件密钥表面的狭义 secret-contract 收集辅助工具 | + | `plugin-sdk/secret-ref-runtime` | 用于 secret-contract/config 解析的狭义 `coerceSecretRef` 和 SecretRef 类型辅助工具 | + | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和密钥收集辅助工具 | + | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 | + | `plugin-sdk/ssrf-dispatcher` | 不含广泛基础设施运行时表面的狭义 pinned-dispatcher 辅助工具 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助工具 | + | `plugin-sdk/secret-input` | 密钥输入解析辅助工具 | + | `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具 | + | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 广泛的运行时 / 日志 / 备份 / 插件安装辅助函数 | - | `plugin-sdk/runtime-env` | 狭义运行时 env、logger、timeout、retry 和 backoff 辅助函数 | - | `plugin-sdk/channel-runtime-context` | 通用渠道 runtime-context 注册和查找辅助函数 | + | `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 狭义的运行时 env、logger、timeout、retry 和 backoff 辅助工具 | + | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共享插件命令 / hook / http / interactive 辅助函数 | - | `plugin-sdk/hook-runtime` | 共享 webhook / 内部 hook pipeline 辅助函数 | - | `plugin-sdk/lazy-runtime` | 延迟运行时导入 / 绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程 exec 辅助函数 | - | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助函数 | - | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 | - | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助函数 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化以及重复 / 冲突检查，即使内置 Telegram 契约接口不可用时也可使用 | - | `plugin-sdk/text-autolink-runtime` | 不依赖广泛 `text-runtime` barrel 的文件引用自动链接检测 | - | `plugin-sdk/approval-runtime` | exec / plugin approval 辅助函数、approval-capability 构建器、认证 / 配置文件辅助函数、原生路由 / 运行时辅助函数 | - | `plugin-sdk/reply-runtime` | 共享入站 / 回复运行时辅助函数、chunking、dispatch、heartbeat、reply planner | - | `plugin-sdk/reply-dispatch-runtime` | 狭义回复 dispatch / finalize 辅助函数 | - | `plugin-sdk/reply-history` | 共享短窗口 reply-history 辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/interactive 辅助工具 | + | `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 管道辅助工具 | + | `plugin-sdk/lazy-runtime` | 延迟运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程 exec 辅助工具 | + | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态 patch 辅助工具 | + | `plugin-sdk/config-runtime` | config 加载/写入辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约表面不可用时也可使用 | + | `plugin-sdk/text-autolink-runtime` | 不含广泛 text-runtime barrel 的文件引用自动链接检测 | + | `plugin-sdk/approval-runtime` | exec/plugin 审批辅助工具、审批能力构建器、凭证/profile 辅助工具、原生路由/运行时辅助工具 | + | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、heartbeat、回复规划器 | + | `plugin-sdk/reply-dispatch-runtime` | 狭义的回复分发/最终化辅助工具 | + | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 狭义文本 / Markdown chunking 辅助函数 | - | `plugin-sdk/session-store-runtime` | 会话存储路径 + `updated-at` 辅助函数 | - | `plugin-sdk/state-paths` | state / OAuth 目录路径辅助函数 | - | `plugin-sdk/routing` | 路由 / session-key / account 绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享渠道 / 账户状态摘要辅助函数、运行时状态默认值和 issue 元数据辅助函数 | - | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助函数 | - | `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助函数 | - | `plugin-sdk/request-url` | 从 fetch / request 类输入中提取字符串 URL | - | `plugin-sdk/run-command` | 带计时的命令运行器，输出规范化的 stdout / stderr 结果 | - | `plugin-sdk/param-readers` | 常用工具 / CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化 payload | - | `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 | - | `plugin-sdk/temp-path` | 共享临时下载路径辅助函数 | - | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助函数 | - | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助函数 | - | `plugin-sdk/json-store` | 小型 JSON 状态读取 / 写入辅助函数 | - | `plugin-sdk/file-lock` | 可重入文件锁辅助函数 | - | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 | - | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和 reply-dispatch 辅助函数 | - | `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 | - | `plugin-sdk/agent-config-primitives` | 狭义智能体运行时 config-schema 基元 | + | `plugin-sdk/reply-chunking` | 狭义的文本/Markdown 分块辅助工具 | + | `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 | + | `plugin-sdk/state-paths` | State/OAuth 目录路径辅助工具 | + | `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助工具、运行时状态默认值和问题元数据辅助工具 | + | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 | + | `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助工具 | + | `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL | + | `plugin-sdk/run-command` | 带计时的命令运行器，带规范化的 stdout/stderr 结果 | + | `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 | + | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 | + | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | + | `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 | + | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助工具 | + | `plugin-sdk/json-store` | 小型 JSON state 读写辅助工具 | + | `plugin-sdk/file-lock` | 可重入文件锁辅助工具 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 | + | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 | + | `plugin-sdk/acp-binding-resolve-runtime` | 不含生命周期启动导入的只读 ACP 绑定解析 | + | `plugin-sdk/agent-config-primitives` | 狭义的智能体运行时 config-schema 原语 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | - | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 | - | `plugin-sdk/device-bootstrap` | 设备 bootstrap 和配对 token 辅助函数 | - | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 | - | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 | - | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助函数 | - | `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助函数 | - | `plugin-sdk/agent-harness` | 面向低层智能体 harness 的实验性受信任插件接口：harness 类型、active-run steer / abort 辅助函数、OpenClaw 工具桥接辅助函数和 attempt result 工具 | - | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助函数 | - | `plugin-sdk/infra-runtime` | 系统事件 / heartbeat 辅助函数 | - | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | - | `plugin-sdk/diagnostic-runtime` | diagnostic 标志和事件辅助函数 | - | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装的 fetch、proxy 和 pinned 查找辅助函数 | - | `plugin-sdk/runtime-fetch` | 具备 dispatcher 感知的运行时 fetch，不引入 proxy / guarded-fetch 导入 | - | `plugin-sdk/response-limit-runtime` | 有界响应体读取器，不依赖广泛媒体运行时表面 | - | `plugin-sdk/session-binding-runtime` | 当前对话绑定状态，不包含已配置绑定路由或配对存储 | - | `plugin-sdk/session-store-runtime` | 不引入广泛配置写入 / 维护导入的会话存储读取辅助函数 | - | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不引入广泛配置 / 安全导入 | - | `plugin-sdk/string-coerce-runtime` | 狭义原始记录 / 字符串强制转换和规范化辅助函数，不引入 markdown / logging 导入 | - | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 | - | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 | - | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助函数 | - | `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 | + | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | + | `plugin-sdk/device-bootstrap` | 设备 bootstrap 和配对令牌辅助工具 | + | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助原语 | + | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 | + | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助工具 | + | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 | + | `plugin-sdk/agent-harness` | 面向低级智能体 harness 的实验性可信插件表面：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具和尝试结果实用工具 | + | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助工具 | + | `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助工具 | + | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | + | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 包装的 fetch、代理和 pinned 查找辅助工具 | + | `plugin-sdk/runtime-fetch` | 不含 proxy/guarded-fetch 导入的 dispatcher-aware 运行时 fetch | + | `plugin-sdk/response-limit-runtime` | 不含广泛 media runtime 表面的有界响应体读取器 | + | `plugin-sdk/session-binding-runtime` | 不含已配置绑定路由或配对存储的当前会话绑定状态 | + | `plugin-sdk/session-store-runtime` | 不含广泛 config 写入/维护导入的会话存储读取辅助工具 | + | `plugin-sdk/context-visibility-runtime` | 不含广泛 config/security 导入的上下文可见性解析和补充上下文过滤 | + | `plugin-sdk/string-coerce-runtime` | 不含 Markdown/logging 导入的狭义原始记录/字符串强制转换和规范化辅助工具 | + | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | + | `plugin-sdk/retry-runtime` | 重试 config 和重试运行器辅助工具 | + | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 | + | `plugin-sdk/directory-runtime` | 基于 config 的目录查询/去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/media-runtime` | 共享媒体获取 / 转换 / 存储辅助函数，以及媒体负载构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助函数、候选项选择和缺失模型消息 | - | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本 / Markdown / 日志辅助函数，例如对智能体可见文本剥离、Markdown 渲染 / chunking / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 | - | `plugin-sdk/text-chunking` | 出站文本 chunking 辅助函数 | - | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和验证辅助函数 | - | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助函数 | - | `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助函数 | - | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 | + | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具以及媒体负载构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型消息 | + | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 | + | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | + | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和验证辅助工具 | + | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助工具 | + | `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | | `plugin-sdk/image-generation` | 图像生成提供商类型 | - | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助函数 | - | `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成提供商 / 请求 / 结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | - | `plugin-sdk/webhook-targets` | webhook target 注册表和路由安装辅助函数 | - | `plugin-sdk/webhook-path` | webhook 路径规范化辅助函数 | - | `plugin-sdk/web-media` | 共享远程 / 本地媒体加载辅助函数 | + | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、凭证和注册表辅助工具 | + | `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助工具 | + | `plugin-sdk/webhook-path` | Webhook 路径规范化辅助工具 | + | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助工具 | | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` | + | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | 用于 manager / config / file / CLI 辅助函数的内置 memory-core 辅助接口 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时 facade | - | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地 provider 以及通用 batch / remote 辅助函数 | - | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory host multimodal 辅助函数 | - | `plugin-sdk/memory-core-host-query` | Memory host query 辅助函数 | - | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助函数 | - | `plugin-sdk/memory-core-host-events` | Memory host event journal 辅助函数 | - | `plugin-sdk/memory-core-host-status` | Memory host status 辅助函数 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助函数 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助函数 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助函数 | - | `plugin-sdk/memory-host-core` | memory host 核心运行时辅助函数的供应商中立别名 | - | `plugin-sdk/memory-host-events` | memory host event journal 辅助函数的供应商中立别名 | - | `plugin-sdk/memory-host-files` | memory host 文件 / 运行时辅助函数的供应商中立别名 | - | `plugin-sdk/memory-host-markdown` | 面向 memory 邻近插件的共享 managed-markdown 辅助函数 | - | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的 active Memory 运行时 facade | - | `plugin-sdk/memory-host-status` | memory host status 辅助函数的供应商中立别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 | + | `plugin-sdk/memory-core` | 内置的 memory-core 辅助工具表面，用于 manager/config/file/CLI 辅助工具 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时外观 | + | `plugin-sdk/memory-core-host-engine-foundation` | Memory host 基础引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用 batch/remote 辅助工具 | + | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 | + | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 | + | `plugin-sdk/memory-core-host-secret` | Memory host 密钥辅助工具 | + | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 | + | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 | + | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 | + | `plugin-sdk/memory-host-core` | 面向供应商中立的别名，用于 memory host 核心运行时辅助工具 | + | `plugin-sdk/memory-host-events` | 面向供应商中立的别名，用于 memory host 事件日志辅助工具 | + | `plugin-sdk/memory-host-files` | 面向供应商中立的别名，用于 memory host 文件/运行时辅助工具 | + | `plugin-sdk/memory-host-markdown` | 用于 memory 相邻插件的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 Memory 运行时外观 | + | `plugin-sdk/memory-host-status` | 面向供应商中立的别名，用于 memory host 状态辅助工具 | + | `plugin-sdk/memory-lancedb` | 内置的 memory-lancedb 辅助工具表面 | - + | 系列 | 当前子路径 | 预期用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助函数（`browser-support` 仍是兼容性 barrel） | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助 / 运行时接口 | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助 / 运行时接口 | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 | - | 特定于渠道的辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性 / 辅助接口 | - | 认证 / 特定于插件的辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助工具（`browser-support` 仍是兼容性 barrel） | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助工具/运行时表面 | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助工具/运行时表面 | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助工具表面 | + | 渠道特定辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助工具接缝 | + | 凭证/插件特定辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助工具接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | ## 注册 API -`register(api)` 回调会接收一个带有以下方法的 `OpenClawPluginApi` 对象： +`register(api)` 回调会接收一个 `OpenClawPluginApi` 对象，其中包含这些方法： ### 能力注册 -| 方法 | 注册的内容 | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | 文本推理（LLM） | -| `api.registerAgentHarness(...)` | 实验性的低层智能体执行器 | -| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | -| `api.registerChannel(...)` | 消息渠道 | -| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | -| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 | -| `api.registerRealtimeVoiceProvider(...)` | 双向实时语音会话 | -| `api.registerMediaUnderstandingProvider(...)` | 图像 / 音频 / 视频分析 | -| `api.registerImageGenerationProvider(...)` | 图像生成 | -| `api.registerMusicGenerationProvider(...)` | 音乐生成 | -| `api.registerVideoGenerationProvider(...)` | 视频生成 | -| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 | -| `api.registerWebSearchProvider(...)` | Web 搜索 | +| 方法 | 注册内容 | +| ------------------------------------------------ | ------------------------------- | +| `api.registerProvider(...)` | 文本推理（LLM） | +| `api.registerAgentHarness(...)` | 实验性的低级智能体执行器 | +| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | +| `api.registerChannel(...)` | 消息渠道 | +| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | +| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 | +| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 | +| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | +| `api.registerImageGenerationProvider(...)` | 图像生成 | +| `api.registerMusicGenerationProvider(...)` | 音乐生成 | +| `api.registerVideoGenerationProvider(...)` | 视频生成 | +| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 | +| `api.registerWebSearchProvider(...)` | Web 搜索 | ### 工具和命令 -| 方法 | 注册的内容 | +| 方法 | 注册内容 | | ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） | -| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | +| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） | +| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | ### 基础设施 -| 方法 | 注册的内容 | -| ---------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | 事件 hook | -| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | -| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | -| `api.registerCli(registrar, opts?)` | CLI 子命令 | -| `api.registerService(service)` | 后台服务 | -| `api.registerInteractiveHandler(registration)` | 交互式处理器 | -| `api.registerMemoryPromptSupplement(builder)` | 追加型 memory 邻近提示部分 | -| `api.registerMemoryCorpusSupplement(adapter)` | 追加型 memory 搜索 / 读取语料库 | +| 方法 | 注册内容 | +| ---------------------------------------------- | ------------------------------- | +| `api.registerHook(events, handler, opts?)` | 事件 hook | +| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | +| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | +| `api.registerCli(registrar, opts?)` | CLI 子命令 | +| `api.registerService(service)` | 后台服务 | +| `api.registerInteractiveHandler(registration)` | 交互式处理器 | +| `api.registerMemoryPromptSupplement(builder)` | 附加的 memory 相邻提示部分 | +| `api.registerMemoryCorpusSupplement(adapter)` | 附加的 memory 搜索/读取语料库 | -保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件拥有的方法，优先使用插件特定的前缀。 +保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试为其分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件特定前缀。 ### CLI 注册元数据 @@ -350,7 +350,7 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; - `commands`：由 registrar 拥有的显式命令根 - `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析期命令描述符 -如果你希望插件命令在常规根 CLI 路径中保持延迟加载，请提供覆盖该 registrar 暴露的每个顶层命令根的 `descriptors`。 +如果你希望插件命令在正常的根 CLI 路径中保持延迟加载，请提供 `descriptors`，覆盖该 registrar 暴露的每一个顶层命令根。 ```typescript api.registerCli( @@ -362,7 +362,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "管理 Matrix 账户、验证、设备和配置文件状态", + description: "管理 Matrix 账户、验证、设备和 profile 状态", hasSubcommands: true, }, ], @@ -370,72 +370,72 @@ api.registerCli( ); ``` -仅当你不需要延迟根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会安装由 descriptor 支持的占位符来实现解析期延迟加载。 +仅当你不需要延迟根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍然受支持，但它不会为解析期延迟加载安装基于 descriptor 的占位符。 ### CLI 后端注册 -`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。 +`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认 config。 -- 后端 `id` 会成为模型引用中的 provider 前缀，例如 `codex-cli/gpt-5`。 +- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。 - 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的结构。 -- 用户配置仍然优先生效。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.` 合并到插件默认值之上。 -- 当后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧版 flag 结构）。 +- 用户 config 仍然优先生效。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.` 合并到插件默认值之上。 +- 当后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧的 flag 结构）。 ### 独占槽位 -| 方法 | 注册的内容 | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | 上下文引擎（同一时间仅一个处于活动状态）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎定制提示补充内容。 | -| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 | -| `api.registerMemoryPromptSection(builder)` | Memory 提示部分构建器 | -| `api.registerMemoryFlushPlan(resolver)` | Memory flush plan 解析器 | -| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 | +| 方法 | 注册内容 | +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个活动）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎能够定制提示附加内容。 | +| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 | +| `api.registerMemoryPromptSection(builder)` | Memory 提示部分构建器 | +| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 | +| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 | ### Memory embedding 适配器 -| 方法 | 注册的内容 | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory embedding 适配器 | +| 方法 | 注册内容 | +| ---------------------------------------------- | ---------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory embedding 适配器 | -- `registerMemoryCapability` 是首选的独占 Memory 插件 API。 -- `registerMemoryCapability` 还可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 Memory artifact，而不必深入某个特定 Memory 插件的私有布局。 -- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 Memory 插件 API。 -- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个 embedding adapter id（例如 `openai`、`gemini` 或自定义的插件定义 id）。 -- 用户配置，例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`，会根据这些已注册的 adapter id 进行解析。 +- `registerMemoryCapability` 是首选的独占 memory 插件 API。 +- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 memory 工件，而不是深入特定 memory 插件的私有布局。 +- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 memory 插件 API。 +- `registerMemoryEmbeddingProvider` 允许活动 memory 插件注册一个或多个 embedding 适配器 id（例如 `openai`、`gemini` 或插件自定义 id）。 +- 用户 config（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会针对这些已注册的适配器 id 进行解析。 ### 事件和生命周期 -| 方法 | 作用 | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook | -| `api.onConversationBindingResolved(handler)` | 对话绑定回调 | +| 方法 | 作用 | +| -------------------------------------------- | ----------------------- | +| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook | +| `api.onConversationBindingResolved(handler)` | 会话绑定回调 | ### Hook 决策语义 -- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任何处理器设置了它，就会跳过更低优先级的处理器。 -- `before_tool_call`：返回 `{ block: false }` 会被视为没有作出决策（与省略 `block` 相同），而不是覆盖。 -- `before_install`：返回 `{ block: true }` 是终止性的。一旦任何处理器设置了它，就会跳过更低优先级的处理器。 -- `before_install`：返回 `{ block: false }` 会被视为没有作出决策（与省略 `block` 相同），而不是覆盖。 -- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任何处理器声明已处理分发，就会跳过更低优先级的处理器以及默认的模型分发路径。 -- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任何处理器设置了它，就会跳过更低优先级的处理器。 -- `message_sending`：返回 `{ cancel: false }` 会被视为没有作出决策（与省略 `cancel` 相同），而不是覆盖。 +- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。 +- `before_tool_call`：返回 `{ block: false }` 会被视为未作出决定（与省略 `block` 相同），而不是作为覆盖。 +- `before_install`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。 +- `before_install`：返回 `{ block: false }` 会被视为未作出决定（与省略 `block` 相同），而不是作为覆盖。 +- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任意处理器声明已分发，就会跳过更低优先级的处理器以及默认的模型分发路径。 +- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。 +- `message_sending`：返回 `{ cancel: false }` 会被视为未作出决定（与省略 `cancel` 相同），而不是作为覆盖。 ### API 对象字段 -| 字段 | 类型 | 描述 | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | 插件 id | -| `api.name` | `string` | 显示名称 | -| `api.version` | `string?` | 插件版本（可选） | -| `api.description` | `string?` | 插件描述（可选） | -| `api.source` | `string` | 插件源路径 | -| `api.rootDir` | `string?` | 插件根目录（可选） | -| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存中运行时快照） | -| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件特定配置 | -| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动 / 设置之前的轻量级窗口 | -| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | +| 字段 | 类型 | 描述 | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------ | +| `api.id` | `string` | 插件 id | +| `api.name` | `string` | 显示名称 | +| `api.version` | `string?` | 插件版本（可选） | +| `api.description` | `string?` | 插件描述（可选） | +| `api.source` | `string` | 插件源路径 | +| `api.rootDir` | `string?` | 插件根目录（可选） | +| `api.config` | `OpenClawConfig` | 当前 config 快照（可用时为活动的内存中运行时快照） | +| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件专属 config | +| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | 作用域化 logger（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置之前的轻量级预启动/设置窗口 | +| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | ## 内部模块约定 @@ -443,39 +443,41 @@ api.registerCli( ``` my-plugin/ - api.ts # 供外部使用者使用的公共导出 + api.ts # 面向外部使用者的公共导出 runtime-api.ts # 仅供内部使用的运行时导出 index.ts # 插件入口点 - setup-entry.ts # 仅用于轻量级设置的入口点（可选） + setup-entry.ts # 仅设置用的轻量入口（可选） ``` - 永远不要在生产代码中通过 `openclaw/plugin-sdk/` - 导入你自己的插件。内部导入应通过 `./api.ts` 或 - `./runtime-api.ts`。SDK 路径仅是对外契约。 + 绝不要在生产代码中通过 `openclaw/plugin-sdk/` + 导入你自己的插件。应通过 `./api.ts` 或 + `./runtime-api.ts` 路由内部导入。SDK 路径仅是外部契约。 -采用 facade 加载的内置插件公共接口（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）现在会在 OpenClaw 已经运行时优先使用活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上已解析的配置文件。 +由 facade 加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）现在在 OpenClaw 已经运行时会优先使用活动运行时 config 快照。如果运行时快照尚不存在，它们会回退到磁盘上已解析的 config 文件。 -如果某个辅助函数明确是提供商特定的，并且尚不属于通用 SDK 子路径，提供商插件也可以暴露一个狭义的插件本地契约 barrel。当前的内置示例：Anthropic 提供商将其 Claude 流辅助函数保留在自己的公共 `api.ts` / `contract-api.ts` 接口中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升到通用 `plugin-sdk/*` 契约中。 +当某个辅助工具是有意保持提供商专属、且暂时还不适合放入通用 SDK 子路径时，提供商插件也可以暴露一个狭义的插件本地契约 barrel。当前的内置示例：Anthropic 提供商将其 Claude 流辅助工具保留在自己的公共 `api.ts` / `contract-api.ts` 接缝中，而不是把 Anthropic beta-header 和 `service_tier` 逻辑提升到通用的 `plugin-sdk/*` 契约中。 其他当前的内置示例： -- `@openclaw/openai-provider`：`api.ts` 导出 provider 构建器、默认模型辅助函数和实时 provider 构建器 -- `@openclaw/openrouter-provider`：`api.ts` 导出 provider 构建器以及新手引导 / 配置辅助函数 +- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、 + 默认模型辅助工具，以及实时提供商构建器 +- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及 + 新手引导/config 辅助工具 - 扩展的生产代码也应避免导入 `openclaw/plugin-sdk/`。 - 如果某个辅助函数确实需要共享，请将其提升到中立的 SDK 子路径， - 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他 - 面向能力的接口，而不是将两个插件耦合在一起。 + 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。 + 如果某个辅助工具确实需要共享，应将其提升到一个中立的 SDK 子路径， + 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他 + 面向能力的表面，而不是将两个插件耦合在一起。 ## 相关内容 - [入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` 选项 -- [运行时辅助函数](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考 -- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、manifest、配置 schema +- [运行时辅助工具](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考 +- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、manifest、config schema - [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则 -- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用接口迁移 +- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移 - [插件内部机制](/zh-CN/plugins/architecture) — 深入的架构和能力模型