diff --git a/docs/zh-CN/channels/discord.md b/docs/zh-CN/channels/discord.md index a45680c4b..be3226be7 100644 --- a/docs/zh-CN/channels/discord.md +++ b/docs/zh-CN/channels/discord.md @@ -1,22 +1,22 @@ --- read_when: - - 正在处理 Discord 渠道功能 + - 正在开发 Discord 渠道功能 summary: Discord 机器人支持状态、能力和配置 title: Discord x-i18n: - generated_at: "2026-04-29T13:26:41Z" + generated_at: "2026-04-29T15:39:28Z" model: gpt-5.5 provider: openai - source_hash: a7ea64c3de512b9e194630c819a8183aa4574f86526c6dd205181fc486df8ac1 + source_hash: a1d3dc0962b6140a727ea8e08f01227e18d2feffa7ce50c3614fb7aa4dd9d044 source_path: channels/discord.md workflow: 16 --- -可通过官方 Discord Gateway 网关用于私信和公会渠道。 +已可通过 Discord 官方网关用于私信和服务器渠道。 - Discord 私信默认使用配对模式。 + Discord 私信默认进入配对模式。 原生命令行为和命令目录。 @@ -28,80 +28,80 @@ x-i18n: ## 快速设置 -你需要创建一个带机器人的新应用，将机器人添加到你的服务器，并将其配对到 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)（选择 **创建我自己的 > 为我和我的朋友**）。 - - 前往 [Discord Developer Portal](https://discord.com/developers/applications) 并点击 **New Application**。将其命名为类似 “OpenClaw” 的名称。 + + 前往 [Discord 开发者门户](https://discord.com/developers/applications) 并点击 **新建应用程序**。将其命名为类似 “OpenClaw” 的名称。 - 点击侧边栏中的 **Bot**。将 **Username** 设置为你的 OpenClaw 智能体名称。 + 点击侧边栏中的 **机器人**。将 **用户名** 设置为你给 OpenClaw 智能体起的名称。 - 仍在 **Bot** 页面上，向下滚动到 **Privileged Gateway Intents** 并启用： + 仍在 **机器人** 页面，向下滚动到 **特权 Gateway 网关意图** 并启用： - - **Message Content Intent**（必需） - - **Server Members Intent**（推荐；角色允许列表和名称到 ID 匹配需要） - - **Presence Intent**（可选；仅当需要状态更新时才需要） + - **消息内容意图**（必需） + - **服务器成员意图**（推荐；角色允许列表和名称到 ID 匹配需要） + - **在线状态意图**（可选；仅在线状态更新需要） - 在 **Bot** 页面上向上滚动并点击 **Reset Token**。 + 回到 **机器人** 页面顶部，点击 **重置令牌**。 - 尽管名称如此，这会生成你的第一个令牌，并没有任何内容被 “重置”。 + 尽管名称如此，这会生成你的第一个令牌；并没有任何内容被“重置”。 - 复制该令牌并保存到某处。这是你的 **Bot Token**，稍后会用到。 + 复制该令牌并保存到某处。这是你的 **机器人令牌**，稍后会用到。 - 点击侧边栏中的 **OAuth2**。你将生成一个带有正确权限的邀请 URL，用于将机器人添加到你的服务器。 + 点击侧边栏中的 **OAuth2**。你将生成一个具备正确权限的邀请 URL，以便将机器人添加到你的服务器。 - 向下滚动到 **OAuth2 URL Generator** 并启用： + 向下滚动到 **OAuth2 URL 生成器** 并启用： - `bot` - `applications.commands` - 下方会出现 **Bot Permissions** 区块。至少启用： + 下方会出现 **机器人权限** 部分。至少启用： - **General Permissions** - - View Channels - **Text Permissions** - - Send Messages - - Read Message History - - Embed Links - - Attach Files - - Add Reactions（可选） + **常规权限** + - 查看渠道 + **文本权限** + - 发送消息 + - 读取消息历史 + - 嵌入链接 + - 附加文件 + - 添加反应（可选） - 这是普通文本渠道的基线权限集。如果你计划在 Discord 话题中发帖，包括创建或继续话题的论坛或媒体渠道工作流，还要启用 **Send Messages in Threads**。 - 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 **Continue** 进行连接。现在你应该可以在 Discord 服务器中看到你的机器人。 + 这是普通文本渠道的基线权限集。如果你计划在 Discord 线程中发帖，包括会创建或继续线程的论坛或媒体渠道工作流，还要启用 **在线程中发送消息**。 + 复制底部生成的 URL，粘贴到浏览器中，选择你的服务器，然后点击 **继续** 以连接。现在你应该能在 Discord 服务器中看到你的机器人。 - 回到 Discord 应用后，你需要启用开发者模式，以便复制内部 ID。 + 回到 Discord 应用，你需要启用开发者模式，才能复制内部 ID。 - 1. 点击 **User Settings**（头像旁边的齿轮图标）→ **Advanced** → 开启 **Developer Mode** - 2. 右键点击侧边栏中的 **server icon** → **Copy Server ID** - 3. 右键点击你自己的 **own avatar** → **Copy User ID** + 1. 点击 **用户设置**（头像旁的齿轮图标） → **高级** → 开启 **开发者模式** + 2. 右键点击侧边栏中的 **服务器图标** → **复制服务器 ID** + 3. 右键点击你自己的 **头像** → **复制用户 ID** - 将你的 **Server ID** 和 **User ID** 与 Bot Token 一起保存；下一步你会将这三项发送给 OpenClaw。 + 将你的 **服务器 ID** 和 **用户 ID** 与机器人令牌一起保存；下一步你会把这三项发送给 OpenClaw。 - 要让配对正常工作，Discord 需要允许你的机器人给你发送私信。右键点击你的 **server icon** → **Privacy Settings** → 开启 **Direct Messages**。 + 要让配对工作，Discord 需要允许你的机器人向你发送私信。右键点击你的 **服务器图标** → **隐私设置** → 开启 **私信**。 - 这允许服务器成员（包括机器人）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持此项启用。如果你只计划使用公会渠道，可以在配对后禁用私信。 + 这允许服务器成员（包括机器人）向你发送私信。如果你想通过 Discord 私信使用 OpenClaw，请保持开启。如果你只计划使用服务器渠道，可以在配对后禁用私信。 - 你的 Discord 机器人令牌是机密信息（类似密码）。在向你的智能体发消息之前，请在运行 OpenClaw 的机器上设置它。 + 你的 Discord 机器人令牌是密钥（类似密码）。在给智能体发消息之前，请在运行 OpenClaw 的机器上设置它。 ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -112,7 +112,7 @@ openclaw gateway ``` 如果 OpenClaw 已作为后台服务运行，请通过 OpenClaw Mac 应用重启它，或停止并重新启动 `openclaw gateway run` 进程。 - 对于托管服务安装，请从存在 `DISCORD_BOT_TOKEN` 的 shell 中运行 `openclaw gateway install`，或将变量存储在 `~/.openclaw/.env` 中，这样服务重启后即可解析环境变量 SecretRef。 + 对于托管服务安装，请在存在 `DISCORD_BOT_TOKEN` 的命令行环境中运行 `openclaw gateway install`，或将变量存储在 `~/.openclaw/.env` 中，这样服务重启后就能解析环境变量 SecretRef。 @@ -120,9 +120,9 @@ openclaw gateway - 在任何现有渠道（例如 Telegram）与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置选项卡。 + 在任何现有渠道（例如 Telegram）中与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置选项卡。 - > “我已经在配置中设置了 Discord 机器人令牌。请使用 User ID `` 和 Server ID `` 完成 Discord 设置。” + > “我已经在配置中设置了我的 Discord 机器人令牌。请使用用户 ID `` 和服务器 ID `` 完成 Discord 设置。” 如果你更喜欢基于文件的配置，请设置： @@ -142,13 +142,13 @@ openclaw gateway } ``` - 默认账户的环境变量回退： + 默认账号的环境变量回退： ```bash DISCORD_BOT_TOKEN=... ``` - 支持明文 `token` 值。`channels.discord.token` 也支持跨 env/file/exec 提供商的 SecretRef 值。参见[密钥管理](/zh-CN/gateway/secrets)。 + 支持明文 `token` 值。也支持在 env/file/exec 提供商中为 `channels.discord.token` 使用 SecretRef 值。请参阅 [密钥管理](/zh-CN/gateway/secrets)。 @@ -156,13 +156,13 @@ DISCORD_BOT_TOKEN=... - 等待 Gateway 网关运行后，在 Discord 中向你的机器人发送私信。它会返回一个配对码。 + 等到 Gateway 网关运行后，在 Discord 中私信你的机器人。它会回复配对码。 - 在你现有的渠道上将配对码发送给你的智能体： + 在你现有的渠道中将配对码发送给你的智能体： - > “批准这个 Discord 配对码：``” + > “批准此 Discord 配对码：``” @@ -176,28 +176,28 @@ openclaw pairing approve discord 配对码会在 1 小时后过期。 - 现在你应该可以通过 Discord 私信与你的智能体聊天。 + 现在你应该可以在 Discord 中通过私信与你的智能体聊天。 -令牌解析支持账户感知。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账户。 -如果两个已启用的 Discord 账户解析到同一个机器人令牌，OpenClaw 只会为该令牌启动一个 Gateway 网关监视器。配置来源的令牌优先于默认环境变量回退；否则第一个启用的账户获胜，重复账户会被报告为已禁用。 -对于高级出站调用（消息工具/渠道操作），显式的逐调用 `token` 会用于该调用。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账户策略/重试设置仍来自活动运行时快照中选定的账户。 +令牌解析会感知账号。配置中的令牌值优先于环境变量回退。`DISCORD_BOT_TOKEN` 仅用于默认账号。 +如果两个已启用的 Discord 账号解析为同一个机器人令牌，OpenClaw 只会为该令牌启动一个 Gateway 网关监视器。配置来源的令牌优先于默认环境变量回退；否则，第一个已启用账号获胜，重复账号会被报告为已禁用。 +对于高级出站调用（`message` 工具/渠道操作），每次调用都会使用显式的调用级 `token`。这适用于发送和读取/探测类操作（例如 read/search/fetch/thread/pins/permissions）。账号策略/重试设置仍来自活动运行时快照中选定的账号。 -## 推荐：设置公会工作区 +## 推荐：设置服务器工作区 -私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个渠道都有自己的智能体会话和自己的上下文。对于只有你和你的机器人的私有服务器，推荐这样做。 +私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个渠道都有自己的智能体会话和上下文。对于只有你和机器人的私有服务器，建议这样做。 - - 这会让你的智能体能够在你服务器上的任何渠道中响应，而不只是私信。 + + 这会让你的智能体可以在服务器上的任何渠道中响应，而不只是私信。 - > “将我的 Discord Server ID `` 添加到公会允许列表” + > “将我的 Discord 服务器 ID `` 添加到服务器允许列表” @@ -222,17 +222,17 @@ openclaw pairing approve discord - - 默认情况下，你的智能体只有在公会渠道中被 @mentioned 时才会响应。对于私有服务器，你可能希望它响应每条消息。 + + 默认情况下，你的智能体只有在服务器渠道中被 @提及时才会响应。对于私有服务器，你可能希望它响应每条消息。 - 在公会渠道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须通过 `message` 工具显式发送，因此智能体默认可以旁观，只在它判断渠道回复有用时才发帖。 + 在服务器渠道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须使用 `message` 工具显式发送，因此智能体默认可以静默观察，并且只有在它判断渠道回复有用时才发帖。 - > “允许我的智能体在这个服务器上无需被 @mentioned 就能响应” + > “允许我的智能体在此服务器上响应，而无需被 @提及” - 在你的公会配置中设置 `requireMention: false`： + 在你的服务器配置中设置 `requireMention: false`： ```json5 { @@ -248,91 +248,93 @@ openclaw pairing approve discord } ``` - 若要恢复群组/渠道房间的旧版自动最终回复，请设置 `messages.groupChat.visibleReplies: "automatic"`。 + 要为群组/渠道房间恢复旧版自动最终回复，请设置 `messages.groupChat.visibleReplies: "automatic"`。 - - 默认情况下，长期记忆（MEMORY.md）仅在私信会话中加载。公会渠道不会自动加载 MEMORY.md。 + + 默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。服务器渠道不会自动加载 MEMORY.md。 > “当我在 Discord 渠道中提问时，如果你需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。” - 如果你需要在每个渠道中共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并按需通过记忆工具访问。 + 如果你需要在每个渠道中共享上下文，请将稳定指令放入 `AGENTS.md` 或 `USER.md`（它们会注入到每个会话中）。将长期笔记保存在 `MEMORY.md` 中，并按需使用记忆工具访问它们。 -现在在你的 Discord 服务器上创建一些渠道并开始聊天。你的智能体可以看到渠道名称，并且每个渠道都有自己的隔离会话，因此你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的渠道。 +现在在你的 Discord 服务器上创建一些渠道并开始聊天。你的智能体可以看到渠道名称，并且每个渠道都有自己的隔离会话，所以你可以设置 `#coding`、`#home`、`#research`，或任何适合你工作流的渠道。 ## 运行时模型 -- Gateway 网关拥有 Discord 连接。 -- 回复路由是确定性的：Discord 入站消息会回复到 Discord。 -- Discord 公会/渠道元数据会作为不受信任的上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型将该封套复制回来，OpenClaw 会从出站回复和后续重放上下文中剥离复制的元数据。 +- Gateway 网关负责 Discord 连接。 +- 回复路由是确定性的：Discord 入站会回复到 Discord。 +- Discord 服务器/渠道元数据会作为不受信任的 + 上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型把该封装复制回去，OpenClaw 会从出站回复和未来重放上下文中剥离复制的元数据。 - 默认情况下（`session.dmScope=main`），直接聊天共享智能体主会话（`agent:main:main`）。 -- 公会渠道使用隔离的会话键（`agent::discord:channel:`）。 +- 服务器渠道使用隔离的会话键（`agent::discord:channel:`）。 - 群组私信默认会被忽略（`channels.discord.dm.groupEnabled=false`）。 -- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 到被路由的对话会话。 -- 仅文本的 cron/heartbeat 公告投递到 Discord 时，会使用一次最终的助手可见答案。当智能体发出多个可投递载荷时，媒体和结构化组件载荷仍会保持多消息。 +- 原生斜杠命令在隔离的命令会话中运行（`agent::discord:slash:`），同时仍携带 `CommandTargetSessionKey` 指向路由后的对话会话。 +- 到 Discord 的纯文本 cron/heartbeat 公告投递只使用一次最终的 + 助手可见答案。媒体和结构化组件负载在智能体发出多个可投递负载时仍保持多消息形式。 ## 论坛渠道 -Discord 论坛和媒体渠道只接受话题帖子。OpenClaw 支持两种方式来创建它们： +Discord 论坛和媒体渠道只接受线程帖子。OpenClaw 支持两种创建方式： -- 向论坛父级（`channel:`）发送消息以自动创建话题。话题标题使用你消息中的第一个非空行。 -- 使用 `openclaw message thread create` 直接创建话题。不要为论坛渠道传递 `--message-id`。 +- 向论坛父渠道（`channel:`）发送消息以自动创建线程。线程标题使用你消息中的第一行非空内容。 +- 使用 `openclaw message thread create` 直接创建线程。对于论坛渠道，不要传递 `--message-id`。 -示例：发送到论坛父级以创建话题 +示例：发送到论坛父渠道以创建线程 ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -示例：显式创建论坛话题 +示例：显式创建论坛线程 ```bash openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -论坛父级不接受 Discord 组件。如果你需要组件，请发送到话题本身（`channel:`）。 +论坛父渠道不接受 Discord 组件。如果你需要组件，请发送到线程本身（`channel:`）。 ## 交互式组件 -OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带有 `components` 载荷的 message 工具。交互结果会作为普通入站消息路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 +OpenClaw 支持 Discord components v2 容器用于智能体消息。请使用带有 `components` 负载的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有的 Discord `replyToMode` 设置。 支持的块： - `text`、`section`、`separator`、`actions`、`media-gallery`、`file` -- Action row 最多允许 5 个按钮或一个选择菜单 +- 操作行最多允许 5 个按钮或单个选择菜单 - 选择类型：`string`、`user`、`role`、`mentionable`、`channel` -默认情况下，components 只能使用一次。设置 `components.reusable=true` 可允许按钮、选择框和表单在过期前被多次使用。 +默认情况下，组件只能使用一次。设置 `components.reusable=true`，允许按钮、选择器和表单在过期前多次使用。 要限制谁可以点击按钮，请在该按钮上设置 `allowedUsers`（Discord 用户 ID、标签或 `*`）。配置后，不匹配的用户会收到一条临时拒绝消息。 -`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型、兼容运行时下拉框以及提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，并且只有调用它的用户可以使用。 +`/model` 和 `/models` 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型、兼容运行时下拉菜单以及提交步骤。`/models add` 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是临时的，并且只有发起调用的用户可以使用。 文件附件： - `file` 块必须指向附件引用（`attachment://`） - 通过 `media`/`path`/`filePath` 提供附件（单个文件）；多个文件请使用 `media-gallery` -- 当上传名称需要匹配附件引用时，使用 `filename` 覆盖上传名称 +- 当上传名称应与附件引用匹配时，使用 `filename` 覆盖上传名称 模态表单： -- 添加最多包含 5 个字段的 `components.modal` +- 添加 `components.modal`，最多包含 5 个字段 - 字段类型：`text`、`checkbox`、`radio`、`select`、`role-select`、`user-select` -- OpenClaw 会自动添加一个触发按钮 +- OpenClaw 会自动添加触发按钮 示例： @@ -391,34 +393,36 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 ## 访问控制和路由 - - `channels.discord.dmPolicy` 控制私信访问（旧版：`channels.discord.dm.policy`）： + + `channels.discord.dmPolicy` 控制私信访问。`channels.discord.allowFrom` 是规范的私信允许列表。 - `pairing`（默认） - `allowlist` - - `open`（要求 `channels.discord.allowFrom` 包含 `"*"`；旧版：`channels.discord.dm.allowFrom`） + - `open`（要求 `channels.discord.allowFrom` 包含 `"*"`） - `disabled` - 如果私信策略不是开放模式，未知用户会被阻止（或在 `pairing` 模式下被提示配对）。 + 如果私信策略不是开放的，未知用户会被阻止（或在 `pairing` 模式下被提示配对）。 多账号优先级： - `channels.discord.accounts.default.allowFrom` 仅适用于 `default` 账号。 - - 对于一个账号，`allowFrom` 优先于旧版 `dm.allowFrom`。 - - 当命名账号自己的 `allowFrom` 和旧版 `dm.allowFrom` 未设置时，会继承 `channels.discord.allowFrom`。 + - 对于一个账号，`allowFrom` 的优先级高于旧版 `dm.allowFrom`。 + - 当命名账号自己的 `allowFrom` 和旧版 `dm.allowFrom` 均未设置时，会继承 `channels.discord.allowFrom`。 - 命名账号不会继承 `channels.discord.accounts.default.allowFrom`。 + 旧版 `channels.discord.dm.policy` 和 `channels.discord.dm.allowFrom` 仍会为了兼容性而读取。`openclaw doctor --fix` 会在不改变访问权限的情况下，将它们迁移到 `dmPolicy` 和 `allowFrom`。 + 用于投递的私信目标格式： - `user:` - `<@id>` 提及 - 当渠道默认值处于活动状态时，裸数字 ID 通常会解析为渠道 ID，但列在账号有效私信 `allowFrom` 中的 ID 会为了兼容性被视为用户私信目标。 + 当渠道默认值处于活动状态时，裸数字 ID 通常会解析为渠道 ID，但在账号有效私信 `allowFrom` 中列出的 ID 会为了兼容性被视为用户私信目标。 - - 服务器处理由 `channels.discord.groupPolicy` 控制： + + Guild 处理由 `channels.discord.groupPolicy` 控制： - `open` - `allowlist` @@ -428,12 +432,12 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 `allowlist` 行为： - - 服务器必须匹配 `channels.discord.guilds`（优先使用 `id`，也接受 slug） - - 可选发送者 allowlist：`users`（推荐稳定 ID）和 `roles`（仅角色 ID）；如果配置了任一项，发送者匹配 `users` 或 `roles` 时即被允许 - - 默认禁用直接名称/标签匹配；仅在应急兼容模式下启用 `channels.discord.dangerouslyAllowNameMatching: true` + - guild 必须匹配 `channels.discord.guilds`（优先使用 `id`，也接受 slug） + - 可选发送者允许列表：`users`（推荐使用稳定 ID）和 `roles`（仅角色 ID）；如果配置了任一项，发送者匹配 `users` 或 `roles` 时即允许 + - 默认禁用直接名称/标签匹配；只有在作为应急兼容模式时才启用 `channels.discord.dangerouslyAllowNameMatching: true` - `users` 支持名称/标签，但 ID 更安全；使用名称/标签条目时，`openclaw security audit` 会发出警告 - - 如果服务器配置了 `channels`，未列出的渠道会被拒绝 - - 如果服务器没有 `channels` 块，则该 allowlist 服务器中的所有渠道都被允许 + - 如果某个 guild 配置了 `channels`，未列出的渠道会被拒绝 + - 如果某个 guild 没有 `channels` 块，则该允许列表 guild 中的所有渠道都允许 示例： @@ -459,33 +463,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`。 - - 服务器消息默认受提及门控。 + + Guild 消息默认受提及门控限制。 提及检测包括： - 显式机器人提及 - - 已配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） - - 受支持情况下的隐式回复机器人行为 + - 配置的提及模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 支持情况下的隐式回复机器人行为 - `requireMention` 按服务器/渠道配置（`channels.discord.guilds...`）。 - `ignoreOtherMentions` 可选丢弃提及另一个用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 + `requireMention` 按 guild/渠道配置（`channels.discord.guilds...`）。 + `ignoreOtherMentions` 可选择丢弃提及其他用户/角色但未提及机器人的消息（不包括 @everyone/@here）。 群组私信： - 默认：忽略（`dm.groupEnabled=false`） - - 可通过 `dm.groupChannels` 配置可选 allowlist（渠道 ID 或 slug） + - 可通过 `dm.groupChannels` 使用可选允许列表（渠道 ID 或 slug） ### 基于角色的智能体路由 -使用 `bindings[].match.roles` 按角色 ID 将 Discord 服务器成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在 peer 或 parent-peer 绑定之后、仅服务器绑定之前求值。如果一个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 +使用 `bindings[].match.roles` 按角色 ID 将 Discord guild 成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在 peer 或 parent-peer 绑定之后、guild-only 绑定之前评估。如果某个绑定还设置了其他匹配字段（例如 `peer` + `guildId` + `roles`），则所有已配置字段都必须匹配。 ```json5 { @@ -511,11 +515,11 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 ## 原生命令和命令授权 -- `commands.native` 默认为 `"auto"`，并为 Discord 启用。 -- 单渠道覆盖：`channels.discord.commands.native`。 -- `commands.native=false` 会显式清除先前注册的 Discord 原生命令。 -- 原生命令授权使用与普通消息处理相同的 Discord allowlist/策略。 -- 对于未授权的用户，命令仍可能在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 授权并返回 “not authorized”。 +- `commands.native` 默认为 `"auto"`，并且为 Discord 启用。 +- 按渠道覆盖：`channels.discord.commands.native`。 +- `commands.native=false` 会显式清除之前注册的 Discord 原生命令。 +- 原生命令授权使用与普通消息处理相同的 Discord 允许列表/策略。 +- 命令对于未授权用户可能仍会显示在 Discord UI 中；执行时仍会强制执行 OpenClaw 授权，并返回“未授权”。 请参阅[斜杠命令](/zh-CN/tools/slash-commands)，了解命令目录和行为。 @@ -526,7 +530,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 ## 功能详情 - + Discord 支持智能体输出中的回复标签： - `[[reply_to_current]]` @@ -539,18 +543,18 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `all` - `batched` - 注意：`off` 会禁用隐式回复串联。显式 `[[reply_to_*]]` 标签仍会生效。 + 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会生效。 `first` 始终将隐式原生回复引用附加到本轮第一条出站 Discord 消息。 - `batched` 仅在入站轮次是由多条消息组成的防抖批次时，才附加 Discord 的隐式原生回复引用。当你希望原生回复主要用于模糊的突发聊天，而不是每个单消息轮次时，这很有用。 + `batched` 仅在入站轮次是多条消息的防抖批次时，才附加 Discord 的隐式原生回复引用。当你主要想为含义不明确的突发聊天提供原生回复，而不是为每个单消息轮次都提供时，这很有用。 - 消息 ID 会在上下文/历史中暴露，以便智能体可以定位特定消息。 + 消息 ID 会在上下文/历史中暴露，因此智能体可以定位特定消息。 - - OpenClaw 可以通过发送临时消息并在文本到达时编辑它来流式传输草稿回复。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。在 Discord 上，`progress` 映射为 `partial`；`streamMode` 是旧版别名，会自动迁移。 + + OpenClaw 可以通过发送临时消息并在文本到达时编辑它来流式传输草稿回复。`channels.discord.streaming` 接受 `off`（默认）| `partial` | `block` | `progress`。`progress` 在 Discord 上映射为 `partial`；`streamMode` 是旧版别名，并会自动迁移。 - 默认保持 `off`，因为多个机器人或 Gateway 网关共享一个账号时，Discord 预览编辑会很快触发速率限制。 + 默认保持为 `off`，因为当多个机器人或 Gateway 网关共享一个账号时，Discord 预览编辑会很快触及速率限制。 ```json5 { @@ -568,20 +572,20 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 ``` - `partial` 会在 token 到达时编辑单条预览消息。 - - `block` 会发送草稿大小的分块（使用 `draftChunk` 调整大小和断点，并被限制在 `textChunkLimit` 内）。 - - 媒体、错误和显式回复的最终消息会取消待处理的预览编辑。 + - `block` 会发出草稿大小的块（使用 `draftChunk` 调整大小和断点，并限制在 `textChunkLimit` 内）。 + - 媒体、错误和显式回复最终消息会取消待处理的预览编辑。 - `streaming.preview.toolProgress`（默认 `true`）控制工具/进度更新是否复用预览消息。 - 预览流式传输仅支持文本；媒体回复会回退到普通投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 + 预览流式传输仅支持文本；媒体回复会回退到正常投递。当显式启用 `block` 流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。 - - 服务器历史上下文： + + Guild 历史上下文： - - `channels.discord.historyLimit` 默认 `20` + - `channels.discord.historyLimit` 默认值为 `20` - 回退：`messages.groupChat.historyLimit` - - `0` 禁用 + - `0` 会禁用 私信历史控制： @@ -591,25 +595,25 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 线程行为： - Discord 线程会作为渠道会话路由，并继承父渠道配置，除非被覆盖。 - - 线程会话会继承父渠道会话级 `/model` 选择，作为仅模型回退；线程本地 `/model` 选择仍优先，并且不会复制父转录历史，除非启用了转录继承。 - - `channels.discord.thread.inheritParent`（默认 `false`）会让新的自动线程从父转录中进行种子填充。单账号覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 - - 消息工具反应可以解析 `user:` 私信目标。 - - 在回复阶段激活回退期间，会保留 `guilds..channels..requireMention: false`。 + - 线程会话继承父渠道的会话级 `/model` 选择作为仅模型回退；线程本地 `/model` 选择仍优先，并且除非启用了 transcript 继承，否则不会复制父 transcript 历史。 + - `channels.discord.thread.inheritParent`（默认 `false`）会让新的自动线程从父 transcript 播种。按账号覆盖位于 `channels.discord.accounts..thread.inheritParent` 下。 + - 消息工具 reactions 可以解析 `user:` 私信目标。 + - `guilds..channels..requireMention: false` 会在回复阶段激活回退期间保留。 - 渠道主题会作为**不受信任的**上下文注入。Allowlist 负责限制谁可以触发智能体，而不是完整的补充上下文删减边界。 + 渠道主题会作为**不可信**上下文注入。允许列表会限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 - - Discord 可以将线程绑定到会话目标，使该线程中的后续消息继续路由到同一会话（包括子智能体会话）。 + + Discord 可以将线程绑定到会话目标，以便该线程中的后续消息继续路由到同一个会话（包括子智能体会话）。 命令： - `/focus ` 将当前/新线程绑定到子智能体/会话目标 - `/unfocus` 移除当前线程绑定 - `/agents` 显示活动运行和绑定状态 - - `/session idle ` 查看/更新聚焦绑定的不活动自动取消聚焦 - - `/session max-age ` 查看/更新聚焦绑定的硬性最大年龄 + - `/session idle ` 检查/更新聚焦绑定的非活动自动取消聚焦 + - `/session max-age ` 检查/更新聚焦绑定的硬性最长时长 配置： @@ -639,20 +643,20 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - `session.threadBindings.*` 设置全局默认值。 - `channels.discord.threadBindings.*` 覆盖 Discord 行为。 - - `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定线程。 - - `spawnAcpSessions` 必须为 true，才能为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定线程。 - - 如果某个账号禁用了线程绑定，`/focus` 和相关线程绑定操作将不可用。 + - `spawnSubagentSessions` 必须为 true，才能为 `sessions_spawn({ thread: true })` 自动创建/绑定话题。 + - `spawnAcpSessions` 必须为 true，才能为 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自动创建/绑定话题。 + - 如果某个账号禁用了话题绑定，则 `/focus` 及相关话题绑定操作不可用。 参见 [子智能体](/zh-CN/tools/subagents)、[ACP 智能体](/zh-CN/tools/acp-agents) 和 [配置参考](/zh-CN/gateway/configuration-reference)。 - - 对于稳定的“一直在线”ACP 工作区，请配置顶层类型化 ACP 绑定，目标为 Discord 对话。 + + 对于稳定的“始终在线”ACP 工作区，请配置面向 Discord 对话的顶层类型化 ACP 绑定。 配置路径： - - `bindings[]`，其中 `type: "acp"` 且 `match.channel: "discord"` + - `bindings[]`，其中包含 `type: "acp"` 和 `match.channel: "discord"` 示例： @@ -704,28 +708,28 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 说明： - - `/acp spawn codex --bind here` 会在当前位置绑定当前渠道或线程，并让后续消息继续使用同一个 ACP 会话。线程消息会继承父渠道绑定。 - - 在已绑定的渠道或线程中，`/new` 和 `/reset` 会在原地重置同一个 ACP 会话。临时线程绑定在生效期间可以覆盖目标解析。 - - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子线程时，才需要 `spawnAcpSessions`。 + - `/acp spawn codex --bind here` 会就地绑定当前频道或话题，并让后续消息继续使用同一个 ACP 会话。话题消息会继承父频道绑定。 + - 在已绑定的频道或话题中，`/new` 和 `/reset` 会就地重置同一个 ACP 会话。临时话题绑定在活跃期间可以覆盖目标解析。 + - 只有当 OpenClaw 需要通过 `--thread auto|here` 创建/绑定子话题时，才需要 `spawnAcpSessions`。 - 有关绑定行为细节，请参见 [ACP 智能体](/zh-CN/tools/acp-agents)。 + 有关绑定行为详情，请参见 [ACP 智能体](/zh-CN/tools/acp-agents)。 - - 每个服务器的反应通知模式： + + 每个服务器的回应通知模式： - `off` - `own`（默认） - `all` - `allowlist`（使用 `guilds..users`） - 反应事件会转换为系统事件，并附加到路由后的 Discord 会话。 + 回应事件会转换为系统事件，并附加到路由后的 Discord 会话。 - - `ackReaction` 会在 OpenClaw 处理传入消息时发送一个确认表情符号。 + + `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 解析顺序： @@ -737,14 +741,14 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 说明： - Discord 接受 Unicode 表情符号或自定义表情符号名称。 - - 使用 `""` 可为某个渠道或账号禁用反应。 + - 使用 `""` 可为某个渠道或账号禁用回应。 - + 默认启用由渠道发起的配置写入。 - 这会影响 `/config set|unset` 流程（当命令功能启用时）。 + 这会影响 `/config set|unset` 流程（当命令功能已启用时）。 禁用： @@ -760,8 +764,8 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - - 通过 HTTP(S) 代理路由 Discord gateway WebSocket 流量和启动时 REST 查询（应用 ID + 允许列表解析），使用 `channels.discord.proxy`。 + + 通过 HTTP(S) 代理使用 `channels.discord.proxy` 路由 Discord gateway WebSocket 流量和启动时 REST 查询（应用 ID + allowlist 解析）。 ```json5 { @@ -773,7 +777,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 每账号覆盖： + 按账号覆盖： ```json5 { @@ -791,7 +795,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - + 启用 PluralKit 解析，将代理消息映射到系统成员身份： ```json5 @@ -809,14 +813,14 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 说明： - - 允许列表可以使用 `pk:` - - 只有当 `channels.discord.dangerouslyAllowNameMatching: true` 时，才会按名称/slug 匹配成员显示名称 - - 查询使用原始消息 ID，并受时间窗口限制 - - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 `allowBots=true` + - allowlist 可以使用 `pk:` + - 仅当 `channels.discord.dangerouslyAllowNameMatching: true` 时，成员显示名称才会按名称/slug 匹配 + - 查询使用原始消息 ID，并受时间窗口约束 + - 如果查询失败，代理消息会被视为机器人消息并丢弃，除非设置了 `allowBots=true` - + 当你设置 Status 或活动字段，或启用自动在线状态时，会应用在线状态更新。 仅 Status 示例： @@ -844,7 +848,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 流式示例： + 流式传输示例： ```json5 { @@ -860,12 +864,12 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 活动类型映射： - - 0: 正在玩 - - 1: 正在直播（需要 `activityUrl`） - - 2: 正在听 - - 3: 正在观看 - - 4: 自定义（使用活动文本作为 Status 状态；表情符号可选） - - 5: 正在竞赛 + - 0：正在玩 + - 1：正在直播（需要 `activityUrl`） + - 2：正在听 + - 3：正在观看 + - 4：自定义（使用活动文本作为 Status 状态；表情符号可选） + - 5：正在竞赛 自动在线状态示例（运行时健康信号）： @@ -884,7 +888,7 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 } ``` - 自动在线状态会将运行时可用性映射到 Discord Status：健康 => 在线，降级或未知 => 空闲，耗尽或不可用 => 请勿打扰。可选文本覆盖： + 自动在线状态会将运行时可用性映射到 Discord Status：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖： - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -892,58 +896,57 @@ OpenClaw 支持用于智能体消息的 Discord components v2 容器。使用带 - - Discord 支持在私信中处理基于按钮的批准，并且可以选择在发起渠道中发布批准提示。 + + Discord 支持在私信中基于按钮处理审批，也可以选择在发起渠道中发布审批提示。 配置路径： - `channels.discord.execApprovals.enabled` - `channels.discord.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`） - - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） + - `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`） - `agentFilter`、`sessionFilter`、`cleanupAfterResolve` - 当 `enabled` 未设置或为 `"auto"`，且可以从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出至少一个批准者时，Discord 会自动启用原生执行批准。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或直接消息 `defaultTo` 推断执行批准者。设置 `enabled: false` 可显式禁用 Discord 作为原生批准客户端。 + 当 `enabled` 未设置或为 `"auto"`，且至少可以从 `execApprovals.approvers` 或 `commands.ownerAllowFrom` 解析出一个审批者时，Discord 会自动启用原生执行审批。Discord 不会从渠道 `allowFrom`、旧版 `dm.allowFrom` 或私信 `defaultTo` 推断执行审批者。设置 `enabled: false` 可明确禁用 Discord 作为原生审批客户端。 - 对于 `/diagnostics` 和 `/export-trajectory` 等敏感的仅所有者群组命令，OpenClaw 会私下发送批准提示和最终结果。当发起调用的所有者有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 + 对于 `/diagnostics` 和 `/export-trajectory` 等敏感的仅限所有者组命令，OpenClaw 会私下发送审批提示和最终结果。当调用命令的所有者拥有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 `commands.ownerAllowFrom` 中第一个可用的所有者路由，例如 Telegram。 - 当 `target` 为 `channel` 或 `both` 时，批准提示会在渠道中可见。只有解析出的批准者可以使用按钮；其他用户会收到临时拒绝。批准提示包含命令文本，因此只应在受信任渠道中启用渠道投递。如果无法从会话键推导出渠道 ID，OpenClaw 会回退到私信投递。 + 当 `target` 为 `channel` 或 `both` 时，审批提示会在频道中可见。只有已解析的审批者可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此仅应在可信频道中启用频道投递。如果无法从会话键推导出频道 ID，OpenClaw 会回退到私信投递。 - Discord 也会渲染其他聊天渠道使用的共享批准按钮。原生 Discord 适配器主要增加批准者私信路由和渠道扇出。 - 当这些按钮存在时，它们是主要批准 UX；只有当工具结果表示 - 聊天批准不可用，或手动批准是唯一路径时，OpenClaw + Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要添加审批者私信路由和频道扇出。 + 当这些按钮存在时，它们是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一路径时，OpenClaw 才应包含手动 `/approve` 命令。 - 如果 Discord 原生批准运行时未激活，OpenClaw 会保持 + 如果 Discord 原生审批运行时未激活，OpenClaw 会保持 本地确定性的 `/approve ` 提示可见。如果 运行时已激活，但原生卡片无法投递到任何目标， - OpenClaw 会在同一聊天中发送回退通知，其中包含待处理批准中的确切 `/approve` + OpenClaw 会在同一聊天中发送回退通知，其中包含待处理审批里的准确 `/approve` 命令。 - Gateway 网关认证和批准解析遵循共享 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。默认情况下，批准会在 30 分钟后过期。 + Gateway 网关认证和审批解析遵循共享 Gateway 网关客户端契约（`plugin:` ID 通过 `plugin.approval.resolve` 解析；其他 ID 通过 `exec.approval.resolve` 解析）。审批默认在 30 分钟后过期。 - 参见 [执行批准](/zh-CN/tools/exec-approvals)。 + 参见 [执行审批](/zh-CN/tools/exec-approvals)。 -## 工具和操作门控 +## 工具和动作门控 -Discord 消息操作包括消息、渠道管理、审核、在线状态和元数据操作。 +Discord 消息动作包括消息、频道管理、审核、在线状态和元数据动作。 核心示例： - 消息：`sendMessage`、`readMessages`、`editMessage`、`deleteMessage`、`threadReply` -- 反应：`react`、`reactions`、`emojiList` +- 回应：`react`、`reactions`、`emojiList` - 审核：`timeout`、`kick`、`ban` - 在线状态：`setPresence` -`event-create` 操作接受可选的 `image` 参数（URL 或本地文件路径），用于设置计划事件封面图片。 +`event-create` 动作接受一个可选的 `image` 参数（URL 或本地文件路径），用于设置计划事件封面图。 -操作门控位于 `channels.discord.actions.*` 下。 +动作门控位于 `channels.discord.actions.*` 下。 默认门控行为： -| 操作组 | 默认值 | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| 动作组 | 默认值 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | | reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | 已启用 | | roles | 已禁用 | | moderation | 已禁用 | @@ -951,11 +954,11 @@ Discord 消息操作包括消息、渠道管理、审核、在线状态和元数 ## Components v2 UI -OpenClaw 使用 Discord components v2 处理执行批准和跨上下文标记。Discord 消息操作也可以接受 `components` 以实现自定义 UI（高级；需要通过 discord 工具构造组件载荷），而旧版 `embeds` 仍然可用，但不推荐。 +OpenClaw 使用 Discord components v2 处理执行审批和跨上下文标记。Discord 消息动作也可以接受 `components` 用于自定义 UI（高级用法；需要通过 discord 工具构造 component payload），而旧版 `embeds` 仍然可用，但不推荐。 -- `channels.discord.ui.components.accentColor` 设置 Discord 组件容器使用的强调色（十六进制）。 +- `channels.discord.ui.components.accentColor` 设置 Discord component containers 使用的强调色（十六进制）。 - 使用 `channels.discord.accounts..ui.components.accentColor` 按账号设置。 -- 当存在 components v2 时，会忽略 `embeds`。 +- 当 components v2 存在时，会忽略 `embeds`。 示例： @@ -975,16 +978,16 @@ OpenClaw 使用 Discord components v2 处理执行批准和跨上下文标记。 ## 语音 -Discord 有两个不同的语音界面：实时 **语音频道**（连续对话）和 **语音消息附件**（波形预览格式）。Gateway 网关同时支持两者。 +Discord 有两个不同的语音表面：实时**语音频道**（连续对话）和**语音消息附件**（波形预览格式）。Gateway 网关支持两者。 ### 语音频道 设置清单： -1. 在 Discord Developer Portal 中启用 Message Content Intent。 -2. 使用角色/用户允许列表时，启用 Server Members Intent。 -3. 使用 `bot` 和 `applications.commands` scopes 邀请机器人。 -4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History 权限。 +1. 在 Discord Developer Portal 中启用消息内容意图。 +2. 使用角色/用户允许列表时，启用服务器成员意图。 +3. 使用 `bot` 和 `applications.commands` 作用域邀请机器人。 +4. 在目标语音频道中授予连接、发言、发送消息和读取消息历史权限。 5. 启用原生命令（`commands.native` 或 `channels.discord.commands.native`）。 6. 配置 `channels.discord.voice`。 @@ -1023,36 +1026,36 @@ Discord 有两个不同的语音界面：实时 **语音频道**（连续对话 } ``` -注意事项： +说明： - `voice.tts` 仅覆盖语音播放的 `messages.tts`。 -- `voice.model` 仅覆盖用于 Discord 语音渠道响应的 LLM。保持未设置可继承路由后的智能体模型。 -- STT 使用 `tools.media.audio`；`voice.model` 不影响转录。 -- 语音转录轮次从 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者说话者无法访问仅限所有者的工具（例如 `gateway` 和 `cron`）。 -- 默认启用语音；设置 `channels.discord.voice.enabled=false` 可禁用语音运行时和 `GuildVoiceStates` Gateway 网关 intent。 -- `channels.discord.intents.voiceStates` 可以显式覆盖语音状态 intent 订阅。保持未设置时，intent 会跟随 `voice.enabled`。 -- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 加入选项。 -- 如果未设置，`@discordjs/voice` 默认值为 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 -- OpenClaw 还会监视接收解密失败，并在短时间窗口内重复失败后通过离开并重新加入语音频道来自动恢复。 -- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 版本线包含来自 discord.js PR #11449 的上游填充修复，该修复关闭了 discord.js issue #11419。 +- `voice.model` 仅覆盖用于 Discord 语音频道响应的 LLM。保留未设置可继承路由后的智能体模型。 +- STT 使用 `tools.media.audio`；`voice.model` 不影响转写。 +- 语音转录轮次会从 Discord `allowFrom`（或 `dm.allowFrom`）派生所有者状态；非所有者说话者无法访问仅限所有者的工具（例如 `gateway` 和 `cron`）。 +- 语音默认启用；设置 `channels.discord.voice.enabled=false` 可禁用语音运行时和 `GuildVoiceStates` Gateway 网关意图。 +- `channels.discord.intents.voiceStates` 可以显式覆盖语音状态意图订阅。保留未设置时，该意图会跟随 `voice.enabled`。 +- `voice.daveEncryption` 和 `voice.decryptionFailureTolerance` 会透传到 `@discordjs/voice` 加入选项。 +- 如果未设置，`@discordjs/voice` 的默认值是 `daveEncryption=true` 和 `decryptionFailureTolerance=24`。 +- OpenClaw 还会监视接收解密失败，并在短时间窗口内重复失败后通过离开/重新加入语音频道自动恢复。 +- 如果更新后接收日志反复显示 `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`，请收集依赖报告和日志。内置的 `@discordjs/voice` 版本线包含来自 discord.js PR #11449 的上游填充修复，该 PR 关闭了 discord.js issue #11419。 语音频道流水线： - Discord PCM 捕获会转换为 WAV 临时文件。 - `tools.media.audio` 处理 STT，例如 `openai/gpt-4o-mini-transcribe`。 -- 转录文本会通过普通 Discord 入口和路由发送。 -- 设置 `voice.model` 时，它仅覆盖此语音频道轮次的响应 LLM。 +- 转录会通过正常的 Discord 入口和路由发送。 +- 设置 `voice.model` 时，它仅覆盖该语音频道轮次的响应 LLM。 - `voice.tts` 会合并覆盖 `messages.tts`；生成的音频会在已加入的频道中播放。 -凭证按组件解析：`voice.model` 使用 LLM 路由凭证，`tools.media.audio` 使用 STT 凭证，`messages.tts`/`voice.tts` 使用 TTS 凭证。 +凭证会按组件解析：`voice.model` 使用 LLM 路由认证，`tools.media.audio` 使用 STT 认证，`messages.tts`/`voice.tts` 使用 TTS 认证。 ### 语音消息 -Discord 语音消息会显示波形预览，并要求使用 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要 Gateway 网关主机上有 `ffmpeg` 和 `ffprobe` 来检查和转换。 +Discord 语音消息会显示波形预览，并需要 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要 Gateway 网关主机上的 `ffmpeg` 和 `ffprobe` 来检查和转换。 -- 提供一个**本地文件路径**（URL 会被拒绝）。 -- 省略文本内容（Discord 会拒绝同一 payload 中同时包含文本和语音消息）。 -- 接受任何音频格式；OpenClaw 会按需转换为 OGG/Opus。 +- 提供**本地文件路径**（URL 会被拒绝）。 +- 省略文本内容（Discord 会拒绝同一载荷中的文本 + 语音消息）。 +- 接受任意音频格式；OpenClaw 会按需转换为 OGG/Opus。 ```bash message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) @@ -1061,22 +1064,22 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## 故障排除 - + - - 启用 Message Content Intent - - 当你依赖用户/成员解析时，启用 Server Members Intent - - 更改 intents 后重启 Gateway 网关 + - 启用消息内容意图 + - 当你依赖用户/成员解析时，启用服务器成员意图 + - 更改意图后重启 Gateway 网关 - + - 验证 `groupPolicy` - - 验证 `channels.discord.guilds` 下的 guild allowlist - - 如果存在 guild `channels` map，则仅允许列出的渠道 - - 验证 `requireMention` 行为和 mention 模式 + - 验证 `channels.discord.guilds` 下的服务器允许列表 + - 如果服务器 `channels` 映射存在，则只允许列出的频道 + - 验证 `requireMention` 行为和提及模式 - 实用检查： + 有用的检查： ```bash openclaw doctor @@ -1086,16 +1089,16 @@ openclaw logs --follow - + 常见原因： - - `groupPolicy="allowlist"` 但没有匹配的 guild/channel allowlist - - `requireMention` 配置在错误位置（必须位于 `channels.discord.guilds` 或 channel 条目下） - - 发送者被 guild/channel `users` allowlist 阻止 + - `groupPolicy="allowlist"` 但没有匹配的服务器/频道允许列表 + - `requireMention` 配置位置错误（必须位于 `channels.discord.guilds` 或频道条目下） + - 发送者被服务器/频道 `users` 允许列表阻止 - + 典型日志： @@ -1106,9 +1109,9 @@ openclaw logs --follow - 单账号：`channels.discord.eventQueue.listenerTimeout` - 多账号：`channels.discord.accounts..eventQueue.listenerTimeout` - - 这只控制 Discord Gateway 网关 listener 工作，不控制智能体轮次生命周期 + - 这只控制 Discord Gateway 网关监听器工作，而不是智能体轮次生命周期 - Discord 不会对排队的智能体轮次应用渠道自有 timeout。Message listener 会立即交接，排队的 Discord 运行会保留每个会话的顺序，直到会话/工具/运行时生命周期完成或中止工作。 + Discord 不会对排队的智能体轮次应用频道拥有的超时。消息监听器会立即移交，排队的 Discord 运行会保留每个会话的顺序，直到会话/工具/运行时生命周期完成或中止工作。 ```json5 { @@ -1128,50 +1131,50 @@ openclaw logs --follow - - OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。瞬时失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中进行限频。 + + OpenClaw 会在连接前获取 Discord `/gateway/bot` 元数据。瞬时失败会回退到 Discord 的默认 Gateway 网关 URL，并在日志中限频记录。 - 元数据 timeout 旋钮： + 元数据超时旋钮： - 单账号：`channels.discord.gatewayInfoTimeoutMs` - 多账号：`channels.discord.accounts..gatewayInfoTimeoutMs` - - 配置未设置时的环境回退：`OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` - - 默认值：`30000`（30 秒），最大值：`120000` + - 配置未设置时的环境变量回退：`OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` + - 默认：`30000`（30 秒），最大：`120000` - - `channels status --probe` 权限检查仅适用于数字渠道 ID。 + + `channels status --probe` 权限检查仅适用于数字频道 ID。 - 如果你使用 slug 键，运行时匹配仍可工作，但 probe 无法完全验证权限。 + 如果你使用 slug 键，运行时匹配仍可工作，但探测无法完整验证权限。 - + - 私信已禁用：`channels.discord.dm.enabled=false` - 私信策略已禁用：`channels.discord.dmPolicy="disabled"`（旧版：`channels.discord.dm.policy`） - - 在 `pairing` 模式下等待配对批准 + - 在 `pairing` 模式中等待配对批准 - - 默认情况下，会忽略由 bot 编写的消息。 + + 默认情况下，机器人撰写的消息会被忽略。 - 如果你设置 `channels.discord.allowBots=true`，请使用严格的 mention 和 allowlist 规则以避免循环行为。 - 建议使用 `channels.discord.allowBots="mentions"`，仅接受 mention 该 bot 的 bot 消息。 + 如果设置 `channels.discord.allowBots=true`，请使用严格的提及和允许列表规则来避免循环行为。 + 优先使用 `channels.discord.allowBots="mentions"`，只接受提及该机器人的机器人消息。 - + - - 保持 OpenClaw 为当前版本（`openclaw update`），以便包含 Discord 语音接收恢复逻辑 - - 确认 `channels.discord.voice.daveEncryption=true`（默认值） - - 从 `channels.discord.voice.decryptionFailureTolerance=24`（上游默认值）开始，仅在需要时调整 - - 观察日志中的： + - 保持 OpenClaw 为当前版本（`openclaw update`），以确保存在 Discord 语音接收恢复逻辑 + - 确认 `channels.discord.voice.daveEncryption=true`（默认） + - 从 `channels.discord.voice.decryptionFailureTolerance=24`（上游默认）开始，只在需要时调优 + - 观察日志中是否出现： - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - 如果自动重新加入后失败仍持续，请收集日志，并与 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) 和 [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) 中的上游 DAVE 接收历史进行对比 + - 如果自动重新加入后故障仍持续，请收集日志，并与 [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) 和 [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) 中的上游 DAVE 接收历史进行比较 @@ -1180,19 +1183,19 @@ openclaw logs --follow 主要参考：[配置参考 - Discord](/zh-CN/gateway/config-channels#discord)。 - + -- 启动/鉴权：`enabled`、`token`、`accounts.*`、`allowBots` +- 启动/认证：`enabled`、`token`、`accounts.*`、`allowBots` - 策略：`groupPolicy`、`dm.*`、`guilds.*`、`guilds.*.channels.*` - 命令：`commands.native`、`commands.useAccessGroups`、`configWrites`、`slashCommand.*` -- 事件队列：`eventQueue.listenerTimeout`（listener 预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` +- 事件队列：`eventQueue.listenerTimeout`（监听器预算）、`eventQueue.maxQueueSize`、`eventQueue.maxConcurrency` - Gateway 网关元数据：`gatewayInfoTimeoutMs` - 回复/历史：`replyToMode`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` -- 递送：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` +- 投递：`textChunkLimit`、`chunkMode`、`maxLinesPerMessage` - 流式传输：`streaming`（旧版别名：`streamMode`）、`streaming.preview.toolProgress`、`draftChunk`、`blockStreaming`、`blockStreamingCoalesce` - 媒体/重试：`mediaMaxMb`（限制出站 Discord 上传，默认 `100MB`）、`retry` - 操作：`actions.*` -- presence：`activity`、`status`、`activityType`、`activityUrl` +- 在线状态：`activity`、`status`、`activityType`、`activityUrl` - UI：`ui.components.accentColor` - 功能：`threadBindings`、顶层 `bindings[]`（`type: "acp"`）、`pluralkit`、`execApprovals`、`intents`、`agentComponents`、`heartbeat`、`responsePrefix` @@ -1200,29 +1203,29 @@ openclaw logs --follow ## 安全和运维 -- 将 bot token 视为密钥（在受监管环境中首选 `DISCORD_BOT_TOKEN`）。 +- 将机器人令牌视为机密（在受监管环境中优先使用 `DISCORD_BOT_TOKEN`）。 - 授予最小权限的 Discord 权限。 -- 如果命令部署/状态已过期，请重启 Gateway 网关，并使用 `openclaw channels status --probe` 重新检查。 +- 如果命令部署/状态过期，请重启 Gateway 网关，并用 `openclaw channels status --probe` 重新检查。 ## 相关内容 - - 将 Discord 用户与 Gateway 网关配对。 + + 将 Discord 用户配对到 Gateway 网关。 - - 群聊和 allowlist 行为。 + + 群聊和允许列表行为。 - + 将入站消息路由到智能体。 - + 威胁模型和加固。 - - 将 guild 和渠道映射到智能体。 + + 将服务器和频道映射到智能体。 - + 原生命令行为。 diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 8e8300c8a..703e3be79 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -4,40 +4,40 @@ read_when: summary: Slack 设置和运行时行为（Socket 模式 + HTTP 请求 URL） title: Slack x-i18n: - generated_at: "2026-04-29T03:16:11Z" + generated_at: "2026-04-29T15:39:31Z" model: gpt-5.5 provider: openai - source_hash: 4cad48c342c4edf0857d79264e5a3213e58b8f5cde6bd04fa11eca1c969a8f1a + source_hash: e888211dc4729da87c2f2d269dca691aec280b5f09ceb3416f5ea16d7930cdd3 source_path: channels/slack.md workflow: 16 --- -可用于通过 Slack app 集成在私信和渠道中投入生产。默认模式为 Socket Mode；也支持 HTTP Request URLs。 +Production-ready for DMs and channels via Slack app integrations. Default mode is Socket Mode; HTTP Request URLs are also supported. - Slack 私信默认使用配对模式。 + Slack DMs default to pairing mode. - 原生命令行为和命令目录。 + Native command behavior and command catalog. - 跨渠道诊断和修复手册。 + Cross-channel diagnostics and repair playbooks. -## 快速设置 +## Quick setup - 在 Slack app 设置中点击 **[Create New App](https://api.slack.com/apps/new)** 按钮： + In Slack app settings press the **[Create New App](https://api.slack.com/apps/new)** button: - - 选择 **from a manifest**，并为你的 app 选择一个工作区 - - 粘贴下方的[示例 manifest](#manifest-and-scope-checklist)，然后继续创建 - - 生成具有 `connections:write` 的 **App-Level Token**（`xapp-...`） - - 安装 app，并复制显示的 **Bot Token**（`xoxb-...`） + - choose **from a manifest** and select a workspace for your app + - paste the [example manifest](#manifest-and-scope-checklist) from below and continue to create + - generate an **App-Level Token** (`xapp-...`) with `connections:write` + - install app and copy the **Bot Token** (`xoxb-...`) shown @@ -56,7 +56,7 @@ x-i18n: } ``` - 环境变量回退（仅默认账号）： + Env fallback (default account only): ```bash SLACK_APP_TOKEN=xapp-... @@ -79,12 +79,12 @@ openclaw gateway - 在 Slack app 设置中点击 **[Create New App](https://api.slack.com/apps/new)** 按钮： + In Slack app settings press the **[Create New App](https://api.slack.com/apps/new)** button: - - 选择 **from a manifest**，并为你的 app 选择一个工作区 - - 粘贴[示例 manifest](#manifest-and-scope-checklist)，并在创建前更新 URL - - 保存用于请求验证的 **Signing Secret** - - 安装 app，并复制显示的 **Bot Token**（`xoxb-...`） + - choose **from a manifest** and select a workspace for your app + - paste the [example manifest](#manifest-and-scope-checklist) and update the URLs before create + - save the **Signing Secret** for request verification + - install app and copy the **Bot Token** (`xoxb-...`) shown @@ -105,9 +105,9 @@ openclaw gateway ``` - 为多账号 HTTP 使用唯一的 webhook 路径 + Use unique webhook paths for multi-account HTTP - 为每个账号提供不同的 `webhookPath`（默认 `/slack/events`），避免注册冲突。 + Give each account a distinct `webhookPath` (default `/slack/events`) so registrations do not collide. @@ -124,9 +124,9 @@ openclaw gateway -## Socket Mode 传输调优 +## Socket Mode transport tuning -OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 秒。仅在需要针对工作区或主机进行特定调优时覆盖传输设置： +OpenClaw sets the Slack SDK client pong timeout to 15 seconds by default for Socket Mode. Override the transport settings only when you need workspace- or host-specific tuning: ```json5 { @@ -143,13 +143,13 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 } ``` -仅当 Socket Mode 工作区记录 Slack websocket pong/server-ping 超时，或运行在已知存在事件循环饥饿问题的主机上时才使用此设置。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。App 消息和事件仍然是应用状态，而不是传输活性信号。 +Use this only for Socket Mode workspaces that log Slack websocket pong/server-ping timeouts or run on hosts with known event-loop starvation. `clientPingTimeout` is the pong wait after the SDK sends a client ping; `serverPingTimeout` is the wait for Slack server pings. App messages and events remain application state, not transport liveness signals. -## Manifest 和 scope 清单 +## Manifest and scope checklist -基础 Slack app manifest 对 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 块（以及 slash command 的 `url`）不同。 +The base Slack app manifest is the same for Socket Mode and HTTP Request URLs. Only the `settings` block (and the slash command `url`) differs. -基础 manifest（Socket Mode 默认）： +Base manifest (Socket Mode default): ```json { @@ -221,7 +221,7 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 } ``` -对于 **HTTP Request URLs 模式**，将 `settings` 替换为 HTTP 变体，并向每个 slash command 添加 `url`。需要公开 URL： +For **HTTP Request URLs mode**, replace `settings` with the HTTP variant and add `url` to each slash command. Public URL required: ```json { @@ -251,19 +251,19 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 } ``` -### 其他 manifest 设置 +### Additional manifest settings -呈现扩展上述默认设置的不同功能。 +Surface different features that extend the above defaults. - 可以使用多个[原生 slash command](#commands-and-slash-behavior) 来替代单个已配置命令，但需要注意细节： + Multiple [native slash commands](#commands-and-slash-behavior) can be used instead of a single configured command with nuance: - - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令是保留的。 - - 一次最多只能提供 25 个 slash command。 + - Use `/agentstatus` instead of `/status` because the `/status` command is reserved. + - No more than 25 slash commands can be made available at once. - 将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的一个子集： + Replace your existing `features.slash_commands` section with a subset of [available commands](/zh-CN/tools/slash-commands#command-list): @@ -383,7 +383,7 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 - 使用上方与 Socket Mode 相同的 `slash_commands` 列表，并向每个条目添加 `"url": "https://gateway-host.example.com/slack/events"`。示例： + Use the same `slash_commands` list as Socket Mode above, and add `"url": "https://gateway-host.example.com/slack/events"` to every entry. Example: ```json "slash_commands": [ @@ -407,13 +407,13 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 - 如果你希望传出消息使用活跃智能体身份（自定义用户名和图标），而不是默认 Slack app 身份，请添加 `chat:write.customize` bot scope。 + Add the `chat:write.customize` bot scope if you want outgoing messages to use the active agent identity (custom username and icon) instead of the default Slack app identity. - 如果使用 emoji 图标，Slack 需要 `:emoji_name:` 语法。 + If you use an emoji icon, Slack expects `:emoji_name:` syntax. - 如果你配置了 `channels.slack.userToken`，典型的读取 scope 为： + If you configure `channels.slack.userToken`, typical read scopes are: - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -421,81 +421,84 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 - `reactions:read` - `pins:read` - `emoji:read` - - `search:read`（如果你依赖 Slack 搜索读取） + - `search:read` (if you depend on Slack search reads) -## Token 模型 +## Token model -- Socket Mode 需要 `botToken` + `appToken`。 -- HTTP 模式需要 `botToken` + `signingSecret`。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 -- 配置 token 会覆盖环境变量回退。 -- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账号。 -- `userToken`（`xoxp-...`）仅可通过配置设置（没有环境变量回退），并且默认使用只读行为（`userTokenReadOnly: true`）。 +- `botToken` + `appToken` are required for Socket Mode. +- HTTP mode requires `botToken` + `signingSecret`. +- `botToken`, `appToken`, `signingSecret`, and `userToken` accept plaintext + strings or SecretRef objects. +- Config tokens override env fallback. +- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env fallback applies only to the default account. +- `userToken` (`xoxp-...`) is config-only (no env fallback) and defaults to read-only behavior (`userTokenReadOnly: true`). -Status 快照行为： +Status snapshot behavior: -- Slack 账户检查会跟踪每个凭据的 `*Source` 和 `*Status` +- Slack 账号检查会跟踪每个凭据的 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 - Status 为 `available`、`configured_unavailable` 或 `missing`。 -- `configured_unavailable` 表示账户通过 SecretRef +- `configured_unavailable` 表示账号通过 SecretRef 或其他非内联密钥来源配置，但当前命令/运行时路径 无法解析实际值。 - 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下， 必需的组合是 `botTokenStatus` + `appTokenStatus`。 -对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；仅当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许使用用户令牌写入。 +对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用 bot 令牌；只有当 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 ## 操作和门控 Slack 操作由 `channels.slack.actions.*` 控制。 -当前 Slack 工具中可用的操作组： +当前 Slack 工具中的可用操作组： | 组 | 默认值 | | ---------- | ------- | -| messages | 启用 | -| reactions | 启用 | -| pins | 启用 | -| memberInfo | 启用 | -| emojiList | 启用 | +| messages | 已启用 | +| reactions | 已启用 | +| pins | 已启用 | +| memberInfo | 已启用 | +| emojiList | 已启用 | -当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图片返回图片预览，为其他文件类型返回本地文件元数据。 +当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图片返回图片预览，或为其他文件类型返回本地文件元数据。 ## 访问控制和路由 - - `channels.slack.dmPolicy` 控制私信访问（旧版：`channels.slack.dm.policy`）： + + `channels.slack.dmPolicy` 控制私信访问。`channels.slack.allowFrom` 是规范的私信允许列表。 - `pairing`（默认） - `allowlist` - - `open`（要求 `channels.slack.allowFrom` 包含 `"*"`；旧版：`channels.slack.dm.allowFrom`） + - `open`（要求 `channels.slack.allowFrom` 包含 `"*"`） - `disabled` 私信标志： - `dm.enabled`（默认 true） - - `channels.slack.allowFrom`（首选） + - `channels.slack.allowFrom` - `dm.allowFrom`（旧版） - `dm.groupEnabled`（群组私信默认 false） - `dm.groupChannels`（可选 MPIM 允许列表） - 多账户优先级： + 多账号优先级： - - `channels.slack.accounts.default.allowFrom` 仅应用于 `default` 账户。 - - 命名账户在自己的 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。 - - 命名账户不会继承 `channels.slack.accounts.default.allowFrom`。 + - `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账号。 + - 命名账号在自身 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。 + - 命名账号不会继承 `channels.slack.accounts.default.allowFrom`。 + + 旧版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的情况下，将它们迁移到 `dmPolicy` 和 `allowFrom`。 私信中的配对使用 `openclaw pairing approve slack `。 - + `channels.slack.groupPolicy` 控制渠道处理： - `open` @@ -504,24 +507,24 @@ Slack 操作由 `channels.slack.actions.*` 控制。 渠道允许列表位于 `channels.slack.channels` 下，并应使用稳定的渠道 ID。 - 运行时说明：如果完全缺少 `channels.slack`（仅环境配置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使已设置 `channels.defaults.groupPolicy`）。 + 运行时注意事项：如果 `channels.slack` 完全缺失（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使已设置 `channels.defaults.groupPolicy`）。 名称/ID 解析： - 当令牌访问允许时，渠道允许列表条目和私信允许列表条目会在启动时解析 - - 未解析的渠道名称条目会按配置保留，但默认会在路由时被忽略 - - 入站授权和渠道路由默认优先使用 ID；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true` + - 未解析的渠道名称条目会按配置保留，但默认会在路由中忽略 + - 入站授权和渠道路由默认以 ID 优先；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true` - - 渠道消息默认由提及门控。 + + 渠道消息默认受提及门控。 提及来源： - 显式应用提及（`<@botId>`） - - 提及正则表达式模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） + - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） + - 隐式回复 bot 线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） 按渠道控制（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 使用）： @@ -542,15 +545,15 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。 - 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。 - 渠道会话：`agent::slack:channel:`。 -- 适用时，线程回复可以创建线程会话后缀（`:thread:`）。 +- 线程回复可在适用时创建线程会话后缀（`: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 已经参与该线程。如果不这样设置，bot 参与过的线程中的回复会绕过 `requireMention` 门控。 回复线程控制： - `channels.slack.replyToMode`：`off|first|all|batched`（默认 `off`） -- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` +- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 设置 - 直接聊天的旧版回退：`channels.slack.dm.replyToMode` 支持手动回复标签： @@ -559,12 +562,12 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `[[reply_to:]]` -`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同，后者在 `"off"` 模式下仍会遵循显式标签。Slack 线程会在渠道中隐藏消息，而 Telegram 回复会以内联方式保持可见。 +`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这不同于 Telegram，后者在 `"off"` 模式下仍会遵循显式标签。Slack 线程会从渠道中隐藏消息，而 Telegram 回复仍以内联方式可见。 -## 确认表情反应 +## 确认响应表情 -`ackReaction` 会在 OpenClaw 处理入站消息时发送确认表情符号。 +`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。 解析顺序： @@ -573,10 +576,10 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `messages.ackReaction` - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"） -说明： +注意事项： -- Slack 期望使用短代码（例如 `"eyes"`）。 -- 使用 `""` 可为 Slack 账户或全局禁用该表情反应。 +- Slack 需要短代码（例如 `"eyes"`）。 +- 使用 `""` 可为 Slack 账号或全局禁用该响应。 ## 文本流式传输 @@ -585,19 +588,19 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - `off`：禁用实时预览流式传输。 - `partial`（默认）：用最新的部分输出替换预览文本。 - `block`：追加分块预览更新。 -- `progress`：生成时显示进度 Status 文本，然后发送最终文本。 -- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一条已编辑的预览消息（默认：`true`）。设为 `false` 可保留单独的工具/进度消息。 +- `progress`：生成期间显示进度状态文本，然后发送最终文本。 +- `streaming.preview.toolProgress`：草稿预览处于活动状态时，将工具/进度更新路由到同一条已编辑的预览消息中（默认：`true`）。设置为 `false` 可保留单独的工具/进度消息。 当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。 -- 必须有可用的回复线程，原生文本流式传输和 Slack 助手线程 Status 才会显示。线程选择仍遵循 `replyToMode`。 +- 必须有可用的回复线程，原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍遵循 `replyToMode`。 - 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。 -- 顶层 Slack 私信默认不在线程中，因此不会显示线程样式预览；如果你希望在那里显示可见进度，请使用线程回复或 `typingReaction`。 +- 顶层 Slack 私信默认保持在线程外，因此不会显示线程样式预览；如果想在那里看到可见进度，请使用线程回复或 `typingReaction`。 - 媒体和非文本载荷会回退到普通投递。 -- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在可以原地编辑预览时刷新。 +- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在能就地编辑预览时才会刷新。 - 如果流式传输在回复中途失败，OpenClaw 会对剩余载荷回退到普通投递。 -使用草稿预览而不是 Slack 原生文本流式传输： +使用草稿预览，而不是 Slack 原生文本流式传输： ```json5 { @@ -618,41 +621,41 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 - 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。 -## 输入状态表情反应回退 +## 输入响应回退 -`typingReaction` 会在 OpenClaw 处理回复时向入站 Slack 消息添加一个临时表情反应，并在运行结束时移除它。这在非线程回复中最有用，因为线程回复会使用默认的 “is typing...” Status 指示器。 +`typingReaction` 会在 OpenClaw 处理回复时向入站 Slack 消息添加临时响应，并在运行完成时将其移除。这在线程回复之外最有用，因为线程回复使用默认的 "is typing..." 状态指示器。 解析顺序： - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` -说明： +注意事项： -- Slack 期望使用短代码（例如 `"hourglass_flowing_sand"`）。 -- 表情反应是尽力而为的，并会在回复或失败路径完成后自动尝试清理。 +- Slack 需要短代码（例如 `"hourglass_flowing_sand"`）。 +- 该响应会尽力执行，并会在回复或失败路径完成后自动尝试清理。 ## 媒体、分块和投递 - - Slack 文件附件会从 Slack 托管的私有 URL 下载（令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以使用 `download-file` 获取原始文件。 + + Slack 文件附件会从 Slack 托管的私有 URL 下载（使用令牌认证请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以使用 `download-file` 获取原始文件。 - 下载使用有界空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息并回退到文件占位符。 + 下载使用有界空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。 - 除非由 `channels.slack.mediaMaxMb` 覆盖，运行时入站大小上限默认为 `20MB`。 + 运行时入站大小上限默认为 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆盖。 - + - 文本分块使用 `channels.slack.textChunkLimit`（默认 4000） - - `channels.slack.chunkMode="newline"` 启用优先按段落拆分 + - `channels.slack.chunkMode="newline"` 启用段落优先拆分 - 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`） - - 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送会使用媒体管道中的 MIME 类型默认值 + - 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送使用媒体管线中的 MIME 类型默认值 - + 首选显式目标： - `user:` 用于私信 @@ -665,7 +668,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。 ## 命令和斜杠行为 -斜杠命令在 Slack 中会显示为一个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： +斜杠命令在 Slack 中显示为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： - `enabled: false` - `name: "openclaw"` @@ -676,9 +679,9 @@ Slack 操作由 `channels.slack.actions.*` 控制。 /openclaw /help ``` -原生命令需要在你的 Slack 应用中配置[额外清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 启用，或在全局配置中改用 `commands.native: true` 启用。 +原生命令需要在你的 Slack 应用中配置[额外清单设置](#additional-manifest-settings)，并改为通过 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 启用。 -- 对 Slack 而言，原生命令自动模式为**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 +- Slack 的原生命令自动模式为**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 ```txt /help @@ -688,14 +691,14 @@ Slack 操作由 `channels.slack.actions.*` 控制。 - 最多 5 个选项：按钮块 - 6-100 个选项：静态选择菜单 -- 超过 100 个选项：当交互选项处理器可用时，使用带异步选项过滤的外部选择 -- 超出 Slack 限制：编码后的选项值回退为按钮 +- 超过 100 个选项：当交互选项处理程序可用时，使用带异步选项过滤的外部选择 +- 超出 Slack 限制：编码后的选项值回退到按钮 ```txt /think ``` -斜杠会话使用类似 `agent::slack:slash:` 的隔离键，并且仍会使用 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。 +斜杠会话使用类似 `agent::slack:slash:` 的隔离键，并仍使用 `CommandTargetSessionKey` 将命令执行路由到目标会话。 ## 交互式回复 @@ -715,7 +718,7 @@ Slack 可以渲染智能体编写的交互式回复控件，但此功能默认 } ``` -或仅为一个 Slack 账户启用： +或仅为一个 Slack 账号启用： ```json5 { @@ -733,44 +736,41 @@ 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 中的执行审批 +## Slack 中的 exec 审批 -Slack 可以通过交互式按钮和交互作为原生审批客户端，而不是回退到 Web 界面或终端。 +Slack 可以作为带有交互式按钮和交互的原生审批客户端，而不是回退到 Web UI 或终端。 -- 执行审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 -- 当请求已进入 Slack 且审批 ID 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面完成。 +- Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 +- 当请求已进入 Slack 且审批 id 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面完成。 - 审批者授权仍会强制执行：只有被识别为审批者的用户才能通过 Slack 批准或拒绝请求。 -这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用 `interactivity` 时，审批提示会直接在对话中呈现为 Block Kit 按钮。 -当这些按钮存在时，它们就是主要审批 UX；只有当工具结果说明聊天 -审批不可用，或手动审批是唯一路径时，OpenClaw -才应包含手动 `/approve` 命令。 +这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用 `interactivity` 时，审批提示会直接在对话中渲染为 Block Kit 按钮。 +当这些按钮存在时，它们是主要审批用户体验；OpenClaw 只有在工具结果表明聊天审批不可用或手动审批是唯一路径时，才应包含手动 `/approve` 命令。 配置路径： - `channels.slack.execApprovals.enabled` - `channels.slack.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`） -- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） +- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`） - `agentFilter`、`sessionFilter` -当 `enabled` 未设置或为 `"auto"` 且至少解析出一个 -审批者时，Slack 会自动启用原生执行审批。设置 `enabled: false` 可明确禁用 Slack 作为原生审批客户端。 -设置 `enabled: true` 可在解析出审批者时强制启用原生审批。 +当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个审批者时，Slack 会自动启用原生 exec 审批。设置 `enabled: false` 可明确禁用 Slack 作为原生审批客户端。 +设置 `enabled: true` 可在审批者可解析时强制开启原生审批。 -没有显式 Slack 执行审批配置时的默认行为： +没有显式 Slack exec 审批配置时的默认行为： ```json5 { @@ -780,8 +780,7 @@ Slack 可以通过交互式按钮和交互作为原生审批客户端，而不 } ``` -只有当你要覆盖审批者、添加过滤器，或 -选择启用来源聊天投递时，才需要显式 Slack 原生配置： +只有在你想覆盖审批者、添加过滤器，或选择启用来源聊天投递时，才需要显式 Slack 原生配置： ```json5 { @@ -797,24 +796,22 @@ Slack 可以通过交互式按钮和交互作为原生审批客户端，而不 } ``` -共享 `approvals.exec` 转发是独立的。仅当执行审批提示还必须 -路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是 -独立的；当这些请求已进入 Slack 时，Slack 原生按钮仍可完成插件审批。 +共享的 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须路由到其他聊天或显式的带外目标时才使用它。共享的 `approvals.plugin` 转发也是独立的；当这些请求已进入 Slack 时，Slack 原生按钮仍可完成插件审批。 -同聊天 `/approve` 也可在已支持命令的 Slack 渠道和私信中使用。查看[执行审批](/zh-CN/tools/exec-approvals)了解完整审批转发模型。 +同一聊天中的 `/approve` 也适用于已支持命令的 Slack 渠道和私信。完整的审批转发模型请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。 -## 事件和运维行为 +## 事件与运维行为 - 消息编辑/删除会映射为系统事件。 -- 线程广播（“同时发送到频道”的线程回复）会按普通用户消息处理。 -- 添加/移除回应事件会映射为系统事件。 -- 成员加入/离开、渠道创建/重命名，以及置顶添加/移除事件会映射为系统事件。 +- 线程广播（“同时发送到渠道”的线程回复）会作为普通用户消息处理。 +- 添加/移除表情回应事件会映射为系统事件。 +- 成员加入/离开、渠道创建/重命名，以及图钉添加/移除事件会映射为系统事件。 - 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。 -- 渠道主题/用途元数据会被视为不受信任的上下文，并可注入路由上下文。 -- 适用时，线程起始消息和初始线程历史上下文种子会按配置的发送者允许列表过滤。 -- 块操作和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并包含丰富的负载字段： - - 块操作：选定值、标签、选择器值和 `workflow_*` 元数据 - - 模态 `view_submission` 和 `view_closed` 事件，包含路由的渠道元数据和表单输入 +- 渠道主题/用途元数据会被视为不可信上下文，并可注入到路由上下文中。 +- 适用时，线程发起消息和初始线程历史上下文种子会按配置的发送者允许列表过滤。 +- Block 操作和模态框交互会发出带有丰富载荷字段的结构化 `Slack interaction: ...` 系统事件： + - block 操作：所选值、标签、选择器值，以及 `workflow_*` 元数据 + - 模态框 `view_submission` 和 `view_closed` 事件，包含路由后的渠道元数据和表单输入 ## 配置参考 @@ -824,7 +821,7 @@ 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` @@ -841,9 +838,9 @@ Slack 可以通过交互式按钮和交互作为原生审批客户端，而不 - `groupPolicy` - 渠道允许列表（`channels.slack.channels`） - `requireMention` - - 每渠道 `users` 允许列表 + - 每个渠道的 `users` 允许列表 - 有用命令： + 有用的命令： ```bash openclaw channels status --probe @@ -859,9 +856,7 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy`（或旧版 `channels.slack.dm.policy`） - 配对审批 / 允许列表条目 - - Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志 - 通常意味着 Slack 发送了一个已编辑的 Assistant 线程事件，但消息元数据中 - 没有可恢复的人类发送者 + - Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志通常表示 Slack 发送了一个编辑过的 Assistant 线程事件，但消息元数据中没有可恢复的人类发送者 ```bash openclaw pairing list slack @@ -873,8 +868,7 @@ openclaw pairing list slack 在 Slack 应用设置中验证 bot + app 令牌以及 Socket Mode 启用状态。 如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或 - `appTokenStatus: "configured_unavailable"`，表示 Slack 账户已配置， - 但当前运行时无法解析由 SecretRef 支持的值。 + `appTokenStatus: "configured_unavailable"`，说明 Slack 账号已配置，但当前运行时无法解析由 SecretRef 支持的值。 @@ -883,110 +877,108 @@ openclaw pairing list slack - 签名密钥 - webhook 路径 - - Slack Request URLs（Events + Interactivity + Slash Commands） - - 每个 HTTP 账户唯一的 `webhookPath` + - Slack Request URL（Events + Interactivity + Slash Commands） + - 每个 HTTP 账号唯一的 `webhookPath` - 如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`， - 表示 HTTP 账户已配置，但当前运行时无法 - 解析由 SecretRef 支持的签名密钥。 + 如果账号快照中出现 `signingSecretStatus: "configured_unavailable"`，说明 HTTP 账号已配置，但当前运行时无法解析由 SecretRef 支持的签名密钥。 - - 确认你想要的是： + + 确认你原本想使用的是： - - 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册了匹配的斜杠命令 - - 或单一斜杠命令模式（`channels.slack.slashCommand.enabled: true`） + - 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册了匹配的 slash 命令 + - 或单一 slash 命令模式（`channels.slack.slashCommand.enabled: true`） - 还要检查 `commands.useAccessGroups` 和渠道/用户允许列表。 + 另请检查 `commands.useAccessGroups` 以及渠道/用户允许列表。 ## 附件视觉参考 -当 Slack 文件下载成功且大小限制允许时，Slack 可以把已下载的媒体附加到智能体轮次。图像文件可以通过媒体理解路径传递，或直接传给支持视觉的回复模型；其他文件会作为可下载文件上下文保留，而不是作为图像输入处理。 +当 Slack 文件下载成功且大小限制允许时，Slack 可以将下载的媒体附加到智能体回合。图像文件可以通过媒体理解路径传递，或直接传递给支持视觉的回复模型；其他文件会保留为可下载文件上下文，而不是作为图像输入处理。 ### 支持的媒体类型 -| 媒体类型 | 来源 | 当前行为 | 备注 | +| 媒体类型 | 来源 | 当前行为 | 备注 | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| JPEG / PNG / GIF / WebP 图像 | Slack 文件 URL | 下载并附加到轮次，以便进行支持视觉的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） | -| PDF 文件 | Slack 文件 URL | 下载并作为文件上下文暴露给 `download-file` 或 `pdf` 等工具 | Slack 入站不会自动把 PDF 转换为图像视觉输入 | -| 其他文件 | Slack 文件 URL | 可行时下载，并作为文件上下文暴露 | 二进制文件不会作为图像输入处理 | -| 线程回复 | 线程起始消息文件 | 当回复没有直接媒体时，根消息文件可作为上下文补充 | 仅文件起始消息使用附件占位符 | -| 多图像消息 | 多个 Slack 文件 | 每个文件都会独立评估 | Slack 处理限制为每条消息最多八个文件 | +| JPEG / PNG / GIF / WebP 图像 | Slack 文件 URL | 下载并附加到该回合，以便支持视觉的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） | +| PDF 文件 | Slack 文件 URL | 下载并作为文件上下文暴露给 `download-file` 或 `pdf` 等工具 | Slack 入站不会自动将 PDF 转换为图像视觉输入 | +| 其他文件 | Slack 文件 URL | 可行时下载并作为文件上下文暴露 | 二进制文件不会作为图像输入处理 | +| 线程回复 | 线程发起消息文件 | 当回复没有直接媒体时，根消息文件可作为上下文水合 | 仅包含文件的发起消息使用附件占位符 | +| 多图像消息 | 多个 Slack 文件 | 每个文件都会独立评估 | Slack 处理限制为每条消息最多八个文件 | -### 入站管线 +### 入站流水线 当带有文件附件的 Slack 消息到达时： 1. OpenClaw 使用 bot 令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。 -2. 成功后，文件会写入媒体存储。 -3. 已下载媒体路径和内容类型会添加到入站上下文。 +2. 下载成功后，文件会写入媒体存储。 +3. 下载的媒体路径和内容类型会添加到入站上下文。 4. 支持图像的模型/工具路径可以使用该上下文中的图像附件。 -5. 非图像文件仍可作为文件元数据或媒体引用，供能够处理它们的工具使用。 +5. 非图像文件仍可作为文件元数据或媒体引用供能处理它们的工具使用。 ### 线程根附件继承 -当消息在线程中到达时（有 `thread_ts` 父级）： +当消息进入线程（有 `thread_ts` 父级）时： -- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以把根文件补充为线程起始上下文。 +- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件水合为线程发起消息上下文。 - 直接回复附件优先于根消息附件。 -- 只有文件而没有文本的根消息会用附件占位符表示，以便回退仍可包含其文件。 +- 只有文件且没有文本的根消息会用附件占位符表示，因此回退仍可包含其文件。 ### 多附件处理 当单条 Slack 消息包含多个文件附件时： -- 每个附件都会通过媒体管线独立处理。 -- 已下载媒体引用会聚合进消息上下文。 -- 处理顺序遵循事件负载中的 Slack 文件顺序。 +- 每个附件都会通过媒体流水线独立处理。 +- 下载的媒体引用会聚合到消息上下文中。 +- 处理顺序遵循事件载荷中的 Slack 文件顺序。 - 一个附件下载失败不会阻塞其他附件。 ### 大小、下载和模型限制 - **大小上限**：默认每个文件 20 MB。可通过 `channels.slack.mediaMaxMb` 配置。 - **下载失败**：Slack 无法提供的文件、过期 URL、不可访问文件、超大文件，以及 Slack 认证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。 -- **视觉模型**：图像分析会在活动回复模型支持视觉时使用该模型，或使用 `agents.defaults.imageModel` 配置的图像模型。 +- **视觉模型**：图像分析会在活动回复模型支持视觉时使用它，否则使用在 `agents.defaults.imageModel` 配置的图像模型。 ### 已知限制 -| 场景 | 当前行为 | 解决方法 | +| 场景 | 当前行为 | 解决方法 | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| 过期的 Slack 文件 URL | 文件被跳过；不显示错误 | 在 Slack 中重新上传文件 | -| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用支持视觉的回复模型 | -| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，增大 `channels.slack.mediaMaxMb` | -| 转发/共享附件 | 文本和 Slack 托管的图像/文件媒体按尽力而为处理 | 直接在 OpenClaw 线程中重新共享 | -| PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉路由 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 | +| Slack 文件 URL 已过期 | 跳过文件；不显示错误 | 在 Slack 中重新上传文件 | +| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用具备视觉能力的回复模型 | +| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，请增大 `channels.slack.mediaMaxMb` | +| 转发/共享的附件 | 文本以及 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新共享 | +| PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉处理 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 | ### 相关文档 - [媒体理解流水线](/zh-CN/nodes/media-understanding) - [PDF 工具](/zh-CN/tools/pdf) -- 史诗任务：[#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件视觉启用 -- 回归测试：[#51353](https://github.com/openclaw/openclaw/issues/51353) -- 实时验证：[#51354](https://github.com/openclaw/openclaw/issues/51354) +- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件视觉能力启用 +- 回归测试: [#51353](https://github.com/openclaw/openclaw/issues/51353) +- 实时验证: [#51354](https://github.com/openclaw/openclaw/issues/51354) -## 相关内容 +## 相关 - + 将 Slack 用户与 Gateway 网关配对。 - + 渠道和群组私信行为。 - + 将入站消息路由到智能体。 - + 威胁模型和加固。 - + 配置布局和优先级。 - + 命令目录和行为。 diff --git a/docs/zh-CN/plugins/sdk-channel-plugins.md b/docs/zh-CN/plugins/sdk-channel-plugins.md index fef7c5d2c..26a2abf88 100644 --- a/docs/zh-CN/plugins/sdk-channel-plugins.md +++ b/docs/zh-CN/plugins/sdk-channel-plugins.md @@ -2,122 +2,95 @@ read_when: - 你正在构建一个新的消息渠道插件 - 你想将 OpenClaw 连接到消息平台 - - 你需要了解 ChannelPlugin 适配器接口 + - 你需要了解 ChannelPlugin 适配器接口。 sidebarTitle: Channel Plugins summary: 构建 OpenClaw 消息渠道插件的分步指南 title: 构建渠道插件 x-i18n: - generated_at: "2026-04-28T11:59:09Z" + generated_at: "2026-04-29T15:39:39Z" model: gpt-5.5 provider: openai - source_hash: 70a3f8fb671c7291a0566f71a56e45232ed51bb43a8fe470e651a03e994e4aa2 + source_hash: 03384057a4316b87c6088d3859d16ed4546c803f7c64639cd12be293f4841258 source_path: plugins/sdk-channel-plugins.md workflow: 16 --- -本指南将介绍如何构建一个将 OpenClaw 连接到 -消息平台的渠道插件。完成后，你将拥有一个可工作的渠道，具备私信安全、 -配对、回复线程和出站消息功能。 +本指南会带你构建一个将 OpenClaw 连接到消息平台的渠道插件。完成后，你将拥有一个可工作的渠道，具备私信安全、配对、回复线程和出站消息发送能力。 - 如果你以前没有构建过任何 OpenClaw 插件，请先阅读 - [入门指南](/zh-CN/plugins/building-plugins)，了解基本包 - 结构和清单设置。 + 如果你之前没有构建过任何 OpenClaw 插件，请先阅读 + [入门指南](/zh-CN/plugins/building-plugins)，了解基本的包结构和清单设置。 ## 渠道插件如何工作 -渠道插件不需要自己的发送/编辑/回应工具。OpenClaw 在核心中保留一个 -共享的 `message` 工具。你的插件负责： +渠道插件不需要自己的发送、编辑或回应工具。OpenClaw 在核心中保留一个共享的 `message` 工具。你的插件负责： - **配置** — 账号解析和设置向导 - **安全** — 私信策略和允许列表 - **配对** — 私信批准流程 -- **会话语法** — 提供商特定的对话 ID 如何映射到基础聊天、线程 ID 和父级回退 +- **会话语法** — 提供商特定的会话 ID 如何映射到基础聊天、线程 ID 和父级回退项 - **出站** — 向平台发送文本、媒体和投票 -- **线程** — 回复如何被线程化 -- **心跳输入状态** — 面向心跳投递目标的可选输入中/忙碌信号 +- **线程** — 回复如何进入线程 +- **心跳输入状态** — 用于心跳投递目标的可选输入中/忙碌信号 -核心负责共享消息工具、提示词接线、外层会话键形状、 -通用 `:thread:` 记账和分发。 +核心负责共享消息工具、提示词接线、外层会话键形状、通用 `:thread:` 记账以及分发。 -如果你的渠道支持入站回复之外的输入指示器，请在渠道插件上公开 -`heartbeat.sendTyping(...)`。核心会在心跳模型运行开始前，使用解析后的 -心跳投递目标调用它，并使用共享的输入状态保活/清理生命周期。当平台需要显式停止信号时， -添加 `heartbeat.clearTyping(...)`。 +如果你的渠道支持入站回复之外的输入状态指示器，请在渠道插件上暴露 `heartbeat.sendTyping(...)`。核心会在心跳模型运行开始前，使用已解析的心跳投递目标调用它，并使用共享的输入状态 keepalive/cleanup 生命周期。当平台需要显式停止信号时，请添加 `heartbeat.clearTyping(...)`。 -如果你的渠道添加了承载媒体来源的消息工具参数，请通过 -`describeMessageTool(...).mediaSourceParams` 公开这些参数名。核心会使用 -该显式列表进行沙箱路径规范化和出站媒体访问策略，因此插件不需要为提供商特定的 -头像、附件或封面图参数添加共享核心特例。 -优先返回按操作键分组的映射，例如 -`{ "set-profile": ["avatarUrl", "avatarPath"] }`，这样无关操作不会 -继承另一个操作的媒体参数。对于有意在每个公开操作之间共享的参数，扁平数组仍然可用。 +如果你的渠道添加了承载媒体来源的消息工具参数，请通过 `describeMessageTool(...).mediaSourceParams` 暴露这些参数名称。核心会使用该显式列表来进行沙箱路径规范化和出站媒体访问策略处理，因此插件不需要为提供商特定的头像、附件或封面图像参数在共享核心中添加特殊情况。 +优先返回按动作键索引的映射，例如 +`{ "set-profile": ["avatarUrl", "avatarPath"] }`，这样无关动作不会继承其他动作的媒体参数。对于有意在每个暴露动作之间共享的参数，扁平数组仍然可用。 -如果你的平台在对话 ID 中存储额外作用域，请在插件内使用 -`messaging.resolveSessionConversation(...)` 保持解析逻辑。这是将 `rawId` -映射到基础对话 ID、可选线程 ID、显式 `baseConversationId`， -以及任何 `parentConversationCandidates` 的规范钩子。 -返回 `parentConversationCandidates` 时，请按从最窄父级到最宽/基础对话的顺序排列。 +如果你的平台在会话 ID 中存储额外作用域，请使用 `messaging.resolveSessionConversation(...)` 将解析逻辑保留在插件中。这是将 `rawId` 映射到基础会话 ID、可选线程 ID、显式 `baseConversationId` 以及任何 `parentConversationCandidates` 的规范钩子。 +当你返回 `parentConversationCandidates` 时，请按从最窄父级到最宽泛/基础会话的顺序排列它们。 -当插件代码需要规范化类似路由的字段、比较子线程与其父路由， -或从 `{ channel, to, accountId, threadId }` 构建稳定的去重键时， -使用 `openclaw/plugin-sdk/channel-route`。该辅助函数会以与核心相同的方式 -规范化数字线程 ID，因此插件应优先使用它，而不是临时的 `String(threadId)` 比较。 -具有提供商特定目标语法的插件可以将其解析器注入 -`resolveChannelRouteTargetWithParser(...)`，并且仍然获得与核心相同的路由目标形状 -和线程回退语义。 +当插件代码需要规范化类似路由的字段、比较子线程与其父路由，或从 `{ channel, to, accountId, threadId }` 构建稳定的去重键时，请使用 `openclaw/plugin-sdk/channel-route`。该辅助函数会以与核心相同的方式规范化数字线程 ID，因此插件应优先使用它，而不是临时的 `String(threadId)` 比较。 +具有提供商特定目标语法的插件可以将自己的解析器注入 `resolveChannelRouteTargetWithParser(...)`，并仍然获得与核心使用的相同路由目标形状和线程回退语义。 -在渠道注册表启动前需要相同解析的内置插件，也可以公开一个顶层 -`session-key-api.ts` 文件，并导出匹配的 -`resolveSessionConversation(...)`。只有当运行时插件注册表尚不可用时， -核心才会使用这个启动安全的接口。 +在渠道注册表启动之前就需要相同解析的内置插件，也可以暴露一个顶层 `session-key-api.ts` 文件，并导出匹配的 `resolveSessionConversation(...)`。核心仅在运行时插件注册表尚不可用时使用这个可安全用于引导阶段的接口。 -当插件只需要在通用/原始 ID 之上添加父级回退时， -`messaging.resolveParentConversationCandidates(...)` 仍作为旧版兼容回退可用。 -如果两个钩子都存在，核心会优先使用 -`resolveSessionConversation(...).parentConversationCandidates`，并且只有当规范钩子 -省略它们时，才回退到 `resolveParentConversationCandidates(...)`。 +当插件只需要在通用/原始 ID 之上提供父级回退项时，`messaging.resolveParentConversationCandidates(...)` 仍可作为旧版兼容回退使用。如果两个钩子都存在，核心会优先使用 `resolveSessionConversation(...).parentConversationCandidates`，并且仅当规范钩子省略它们时才回退到 `resolveParentConversationCandidates(...)`。 -## 批准和渠道能力 +## 审批和渠道能力 -大多数渠道插件不需要批准专用代码。 +大多数渠道插件不需要审批专用代码。 -- 核心负责同聊天 `/approve`、共享批准按钮载荷和通用回退投递。 -- 当渠道需要批准专用行为时，优先在渠道插件上使用一个 `approvalCapability` 对象。 -- `ChannelPlugin.approvals` 已移除。将批准投递/原生/渲染/认证事实放在 `approvalCapability` 上。 -- `plugin.auth` 仅用于登录/登出；核心不再从该对象读取批准认证钩子。 -- `approvalCapability.authorizeActorAction` 和 `approvalCapability.getActionAvailabilityState` 是规范的批准认证接缝。 -- 使用 `approvalCapability.getActionAvailabilityState` 表示同聊天批准认证可用性。 -- 如果你的渠道公开原生执行批准，请在发起界面/原生客户端状态不同于同聊天批准认证时，使用 `approvalCapability.getExecInitiatingSurfaceState`。核心使用这个执行专用钩子区分 `enabled` 与 `disabled`，判断发起渠道是否支持原生执行批准，并将该渠道纳入原生客户端回退指引。`createApproverRestrictedNativeApprovalCapability(...)` 会为常见情况填充这一点。 -- 对渠道特定的载荷生命周期行为使用 `outbound.shouldSuppressLocalPayloadPrompt` 或 `outbound.beforeDeliverPayload`，例如隐藏重复的本地批准提示，或在投递前发送输入指示器。 -- 仅将 `approvalCapability.delivery` 用于原生批准路由或回退抑制。 -- 将 `approvalCapability.nativeRuntime` 用于渠道自有的原生批准事实。用 `createLazyChannelApprovalNativeRuntimeAdapter(...)` 在热渠道入口点保持其惰性，它可以按需导入你的运行时模块，同时仍允许核心组装批准生命周期。 -- 仅当渠道确实需要自定义批准载荷而不是共享渲染器时，才使用 `approvalCapability.render`。 -- 当渠道希望禁用路径回复解释启用原生执行批准所需的确切配置开关时，使用 `approvalCapability.describeExecApprovalSetup`。该钩子接收 `{ channel, channelLabel, accountId }`；具名账号渠道应渲染账号作用域路径，例如 `channels..accounts..execApprovals.*`，而不是顶层默认值。 -- 如果渠道可以从现有配置推断稳定的类似所有者的私信身份，请使用来自 `openclaw/plugin-sdk/approval-runtime` 的 `createResolvedApproverActionAuthAdapter` 来限制同聊天 `/approve`，无需添加批准专用核心逻辑。 -- 如果渠道需要原生批准投递，请让渠道代码聚焦于目标规范化以及传输/呈现事实。使用来自 `openclaw/plugin-sdk/approval-runtime` 的 `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver` 和 `createApproverRestrictedNativeApprovalCapability`。将渠道特定事实放在 `approvalCapability.nativeRuntime` 后面，理想情况下通过 `createChannelApprovalNativeRuntimeAdapter(...)` 或 `createLazyChannelApprovalNativeRuntimeAdapter(...)`，这样核心可以组装处理器，并负责请求过滤、路由、去重、过期、Gateway 网关订阅和已路由到别处的通知。`nativeRuntime` 被拆分为几个更小的接缝： -- `createChannelNativeOriginTargetResolver` 默认对 `{ to, accountId, threadId }` 目标使用共享渠道路由匹配器。仅当渠道具有提供商特定的等价规则时才传入 `targetsMatch`，例如 Slack 时间戳前缀匹配。 -- 当渠道需要在默认路由匹配器或自定义 `targetsMatch` 回调运行前规范化提供商 ID，同时保留原始目标用于投递时，将 `normalizeTargetForMatch` 传给 `createChannelNativeOriginTargetResolver`。仅当解析后的投递目标本身应被规范化时，才使用 `normalizeTarget`。 +- 核心负责同一聊天中的 `/approve`、共享审批按钮载荷以及通用回退投递。 +- 当渠道需要审批特定行为时，优先在渠道插件上使用一个 `approvalCapability` 对象。 +- `ChannelPlugin.approvals` 已被移除。请将审批投递、原生、渲染和鉴权事实放在 `approvalCapability` 上。 +- `plugin.auth` 仅用于登录/登出；核心不再从该对象读取审批鉴权钩子。 +- `approvalCapability.authorizeActorAction` 和 `approvalCapability.getActionAvailabilityState` 是规范的审批鉴权接缝。 +- 使用 `approvalCapability.getActionAvailabilityState` 处理同一聊天审批鉴权可用性。 +- 如果你的渠道暴露原生 exec 审批，请在发起面/原生客户端状态不同于同一聊天审批鉴权时，使用 `approvalCapability.getExecInitiatingSurfaceState`。核心使用这个 exec 专用钩子区分 `enabled` 和 `disabled`，决定发起渠道是否支持原生 exec 审批，并将该渠道包含在原生客户端回退指引中。`createApproverRestrictedNativeApprovalCapability(...)` 会为常见情况填充这一点。 +- 使用 `outbound.shouldSuppressLocalPayloadPrompt` 或 `outbound.beforeDeliverPayload` 处理渠道特定的载荷生命周期行为，例如隐藏重复的本地审批提示，或在投递前发送输入状态指示器。 +- 仅将 `approvalCapability.delivery` 用于原生审批路由或回退抑制。 +- 使用 `approvalCapability.nativeRuntime` 处理渠道拥有的原生审批事实。在热渠道入口点上通过 `createLazyChannelApprovalNativeRuntimeAdapter(...)` 保持懒加载，它可以按需导入你的运行时模块，同时仍允许核心组装审批生命周期。 +- 仅当渠道确实需要自定义审批载荷而非共享渲染器时，才使用 `approvalCapability.render`。 +- 当渠道希望禁用路径回复说明启用原生 exec 审批所需的确切配置旋钮时，请使用 `approvalCapability.describeExecApprovalSetup`。该钩子接收 `{ channel, channelLabel, accountId }`；具名账号渠道应渲染账号作用域路径，例如 `channels..accounts..execApprovals.*`，而不是顶层默认值。 +- 如果渠道可以从现有配置推断稳定的类似所有者的私信身份，请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createResolvedApproverActionAuthAdapter` 来限制同一聊天中的 `/approve`，无需添加审批特定的核心逻辑。 +- 如果渠道需要原生审批投递，请让渠道代码聚焦于目标规范化以及传输/呈现事实。使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver` 和 `createApproverRestrictedNativeApprovalCapability`。将渠道特定事实放在 `approvalCapability.nativeRuntime` 后面，理想情况下通过 `createChannelApprovalNativeRuntimeAdapter(...)` 或 `createLazyChannelApprovalNativeRuntimeAdapter(...)`，这样核心可以组装处理程序，并负责请求过滤、路由、去重、过期、Gateway 网关订阅以及已路由到其他位置的通知。`nativeRuntime` 被拆分为几个更小的接缝： +- `createChannelNativeOriginTargetResolver` 默认使用共享渠道路由匹配器处理 `{ to, accountId, threadId }` 目标。仅当渠道具有提供商特定的等价规则时才传入 `targetsMatch`，例如 Slack 时间戳前缀匹配。 +- 当渠道需要在默认路由匹配器或自定义 `targetsMatch` 回调运行之前规范化提供商 ID，同时保留原始目标用于投递时，请将 `normalizeTargetForMatch` 传给 `createChannelNativeOriginTargetResolver`。仅当已解析的投递目标本身应被规范化时，才使用 `normalizeTarget`。 - `availability` — 账号是否已配置，以及请求是否应被处理 -- `presentation` — 将共享批准视图模型映射为待处理/已解决/已过期的原生载荷或最终操作 -- `transport` — 准备目标，并发送/更新/删除原生批准消息 -- `interactions` — 用于原生按钮或回应的可选绑定/解绑/清除操作钩子 -- `observe` — 可选投递诊断钩子 -- 如果渠道需要运行时自有对象，例如客户端、令牌、Bolt 应用或 webhook 接收器，请通过 `openclaw/plugin-sdk/channel-runtime-context` 注册它们。通用运行时上下文注册表让核心能够从渠道启动状态引导能力驱动的处理器，而无需添加批准专用包装胶水。 -- 仅当能力驱动接缝仍不够表达需求时，才使用更低层的 `createChannelApprovalHandler` 或 `createChannelNativeApprovalRuntime`。 -- 原生批准渠道必须通过这些辅助函数同时路由 `accountId` 和 `approvalKind`。`accountId` 让多账号批准策略限定在正确的机器人账号内，`approvalKind` 让执行与插件批准行为可供渠道使用，而不需要在核心中硬编码分支。 -- 核心现在也负责批准重路由通知。渠道插件不应从 `createChannelNativeApprovalRuntime` 发送自己的“批准已发送到私信 / 另一个渠道”后续消息；而应通过共享批准能力辅助函数公开准确的来源和批准者私信路由，并让核心在向发起聊天发布任何通知前聚合实际投递结果。 -- 端到端保留已投递批准 ID 类型。原生客户端不应 - 从渠道本地状态猜测或重写执行与插件批准路由。 -- 不同批准类型可以有意公开不同的原生界面。 +- `presentation` — 将共享审批视图模型映射为待处理/已解决/已过期的原生载荷或最终动作 +- `transport` — 准备目标，并发送/更新/删除原生审批消息 +- `interactions` — 用于原生按钮或回应的可选绑定/解绑/清除动作钩子 +- `observe` — 可选的投递诊断钩子 +- 如果渠道需要由运行时拥有的对象，例如客户端、令牌、Bolt 应用或 webhook 接收器，请通过 `openclaw/plugin-sdk/channel-runtime-context` 注册它们。通用运行时上下文注册表让核心可以从渠道启动状态引导由能力驱动的处理程序，而无需添加审批特定的包装胶水代码。 +- 仅当能力驱动的接缝表达能力仍不够时，才使用更低层级的 `createChannelApprovalHandler` 或 `createChannelNativeApprovalRuntime`。 +- 原生审批渠道必须通过这些辅助函数路由 `accountId` 和 `approvalKind`。`accountId` 让多账号审批策略限定在正确的机器人账号内，`approvalKind` 则让渠道可用 exec 与插件审批行为，而无需在核心中硬编码分支。 +- 核心现在也负责审批重路由通知。渠道插件不应从 `createChannelNativeApprovalRuntime` 发送自己的“审批已发送到私信/另一个渠道”后续消息；相反，应通过共享审批能力辅助函数暴露准确的来源和审批者私信路由，并让核心在发回任何通知到发起聊天之前汇总实际投递。 +- 端到端保留已投递审批 ID 的类型。原生客户端不应 + 从渠道本地状态猜测或重写 exec 与插件审批路由。 +- 不同审批类型可以有意暴露不同的原生表面。 当前内置示例： - - Slack 对执行和插件 ID 都保持原生批准路由可用。 - - Matrix 对执行和插件批准保持相同的原生私信/渠道路由和回应 UX， - 同时仍允许认证按批准类型不同。 -- `createApproverRestrictedNativeApprovalAdapter` 仍作为兼容包装器存在，但新代码应优先使用能力构建器，并在插件上公开 `approvalCapability`。 + - Slack 让原生审批路由对 exec 和插件 ID 都可用。 + - Matrix 为 exec 和插件审批保留相同的原生私信/渠道路由和回应 UX， + 同时仍允许鉴权按审批类型不同。 +- `createApproverRestrictedNativeApprovalAdapter` 仍作为兼容性包装器存在，但新代码应优先使用能力构建器，并在插件上暴露 `approvalCapability`。 -对于热渠道入口点，如果你只需要该系列的一部分，请优先使用更窄的运行时子路径： +对于热渠道入口点，当你只需要该系列的一部分时，优先使用更窄的运行时子路径： - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -136,47 +109,60 @@ x-i18n: `openclaw/plugin-sdk/reply-reference` 和 `openclaw/plugin-sdk/reply-chunking`。 -特别是对于设置： +专门针对设置： -- `openclaw/plugin-sdk/setup-runtime` 覆盖运行时安全的设置辅助函数： +- `openclaw/plugin-sdk/setup-runtime` 涵盖运行时安全的设置辅助函数： 导入安全的设置补丁适配器（`createPatchedAccountSetupAdapter`、 `createEnvPatchedAccountSetupAdapter`、 - `createSetupInputPresenceValidator`）、查找说明输出、 - `promptResolvedAllowFrom`、`splitSetupEntries`，以及委托式 + `createSetupInputPresenceValidator`）、查找注释输出、 + `promptResolvedAllowFrom`、`splitSetupEntries` 以及委托式 设置代理构建器 -- `openclaw/plugin-sdk/setup-adapter-runtime` 是用于 `createEnvPatchedAccountSetupAdapter` - 的窄环境感知适配器接缝 -- `openclaw/plugin-sdk/channel-setup` 覆盖可选安装设置 - 构建器，以及少量设置安全原语： - `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`， +- `openclaw/plugin-sdk/setup-adapter-runtime` 是面向 `createEnvPatchedAccountSetupAdapter` 的窄环境感知适配器接缝 +- `openclaw/plugin-sdk/channel-setup` 涵盖可选安装设置 + 构建器以及一些设置安全的原语： + `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、 -如果你的渠道支持由环境驱动的设置或认证，并且通用启动/配置 -流程应在运行时加载前知道这些环境变量名，请在 -插件清单中用 `channelEnvVars` 声明它们。渠道运行时 `envVars` 或本地 -常量仅用于面向操作员的文案。 +如果你的渠道支持由环境驱动的设置或鉴权，并且通用启动/配置流程应在运行时加载前知道这些环境名称，请在插件清单中使用 `channelEnvVars` 声明它们。将渠道运行时 `envVars` 或本地常量仅用于面向操作员的文案。 -如果你的渠道会在插件运行时启动前出现在 `status`、`channels list`、`channels status` 或 SecretRef 扫描中，请在 `package.json` 中添加 `openclaw.setupEntry`。该入口点应能在只读命令路径中安全导入，并应返回这些摘要所需的渠道元数据、可安全用于设置的配置适配器、Status 适配器和渠道密钥目标元数据。不要从设置入口启动客户端、监听器或传输运行时。 +如果你的渠道会在插件运行时启动前出现在 `status`、`channels list`、`channels status` 或 +SecretRef 扫描中，请在 `package.json` 中添加 `openclaw.setupEntry`。该入口点应该能够在只读命令 +路径中安全导入，并应返回这些摘要所需的渠道元数据、设置安全的配置适配器、Status +适配器，以及渠道密钥目标元数据。不要从设置入口启动客户端、监听器或传输运行时。 -同时保持主渠道入口导入路径收窄。设备发现可以评估入口和渠道插件模块，以注册能力，而不会激活该渠道。像 `channel-plugin-api.ts` 这样的文件应导出渠道插件对象，而不应导入设置向导、传输客户端、套接字监听器、子进程启动器或服务启动模块。将这些运行时部分放在从 `registerFull(...)`、运行时 setter 或懒加载能力适配器加载的模块中。 +主渠道入口导入路径也要保持精简。设备发现可以评估入口和渠道插件模块，以注册能力，而不会激活 +渠道。`channel-plugin-api.ts` 等文件应导出渠道插件对象，而不应导入设置向导、传输客户端、套接字 +监听器、子进程启动器或服务启动模块。将这些运行时部分放在从 `registerFull(...)`、运行时 setter +或惰性能力适配器加载的模块中。 -`createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled` 和 `splitSetupEntries` +`createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、 +`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled` 和 +`splitSetupEntries` -- 仅当你还需要更重的共享设置/配置辅助工具（例如 `moveSingleAccountChannelSectionToDefaultAccount(...)`）时，才使用更宽的 `openclaw/plugin-sdk/setup` seam +- 仅当你还需要更重的共享设置/配置辅助函数（如 + `moveSingleAccountChannelSectionToDefaultAccount(...)`）时，才使用更宽泛的 + `openclaw/plugin-sdk/setup` 接缝 -如果你的渠道只想在设置界面中提示“先安装此插件”，请优先使用 `createOptionalChannelSetupSurface(...)`。生成的适配器/向导会在配置写入和最终完成时失败关闭，并在验证、最终完成和文档链接文案中复用同一条需要安装的消息。 +如果你的渠道只想在设置界面中提示“先安装此插件”，请优先使用 +`createOptionalChannelSetupSurface(...)`。生成的适配器/向导会在配置写入和最终确认时失败关闭，并且会在验证、最终确认和文档链接文案中复用相同的必需安装消息。 -对于其他热路径渠道，请优先使用较窄的辅助工具，而不是更宽的旧版界面： +对于其他热路径渠道，优先使用精简辅助函数，而不是更宽泛的旧界面： -- `openclaw/plugin-sdk/account-core`、`openclaw/plugin-sdk/account-id`、`openclaw/plugin-sdk/account-resolution` 和 `openclaw/plugin-sdk/account-helpers` 用于多账户配置和默认账户回退 -- `openclaw/plugin-sdk/inbound-envelope` 和 `openclaw/plugin-sdk/inbound-reply-dispatch` 用于入站路由/信封以及记录并分发接线 -- `openclaw/plugin-sdk/messaging-targets` 用于目标解析/匹配 -- `openclaw/plugin-sdk/outbound-media` 和 `openclaw/plugin-sdk/outbound-runtime` 用于媒体加载，以及出站身份/发送委托和载荷规划 -- 当出站路由应保留显式 `replyToId`/`threadId`，或在基础会话键仍然匹配后恢复当前 `:thread:` 会话时，请使用来自 `openclaw/plugin-sdk/channel-core` 的 `buildThreadAwareOutboundSessionRoute(...)`。当平台具有原生线程投递语义时，提供商插件可以覆盖优先级、后缀行为和线程 ID 规范化。 -- `openclaw/plugin-sdk/thread-bindings-runtime` 用于线程绑定生命周期和适配器注册 +- `openclaw/plugin-sdk/account-core`、 + `openclaw/plugin-sdk/account-id`、 + `openclaw/plugin-sdk/account-resolution` 和 + `openclaw/plugin-sdk/account-helpers`，用于多账号配置和默认账号回退 +- `openclaw/plugin-sdk/inbound-envelope` 和 + `openclaw/plugin-sdk/inbound-reply-dispatch`，用于入站路由/信封以及记录并分发接线 +- `openclaw/plugin-sdk/messaging-targets`，用于目标解析/匹配 +- `openclaw/plugin-sdk/outbound-media` 和 + `openclaw/plugin-sdk/outbound-runtime`，用于媒体加载，以及出站身份/发送委托和载荷规划 +- 当出站路由应保留显式 `replyToId`/`threadId`，或在基础会话键仍匹配后恢复当前 `:thread:` 会话时，使用 + `openclaw/plugin-sdk/channel-core` 中的 `buildThreadAwareOutboundSessionRoute(...)`。当提供商插件的平台具有原生线程投递语义时，可以覆盖优先级、后缀行为和线程 ID 规范化。 +- `openclaw/plugin-sdk/thread-bindings-runtime`，用于线程绑定生命周期和适配器注册 - 仅当仍需要旧版智能体/媒体载荷字段布局时，才使用 `openclaw/plugin-sdk/agent-media-payload` -- `openclaw/plugin-sdk/telegram-command-config` 用于 Telegram 自定义命令规范化、重复/冲突验证，以及回退稳定的命令配置契约 +- `openclaw/plugin-sdk/telegram-command-config`，用于 Telegram 自定义命令规范化、重复/冲突验证，以及回退稳定的命令配置契约 -仅认证渠道通常可以停在默认路径：核心会处理审批，插件只需暴露出站/认证能力。Matrix、Slack、Telegram 以及自定义聊天传输等原生审批渠道应使用共享的原生辅助工具，而不是自行实现审批生命周期。 +仅认证渠道通常可以停在默认路径：核心处理批准，插件只暴露出站/认证能力。Matrix、Slack、Telegram 和自定义聊天传输等原生批准渠道应使用共享原生辅助函数，而不是自行实现批准生命周期。 ## 入站提及策略 @@ -185,17 +171,19 @@ x-i18n: - 插件拥有的证据收集 - 共享策略评估 -使用 `openclaw/plugin-sdk/channel-mention-gating` 进行提及策略决策。仅当你需要更宽的入站辅助 barrel 时，才使用 `openclaw/plugin-sdk/channel-inbound`。 +使用 `openclaw/plugin-sdk/channel-mention-gating` 进行提及策略决策。 +仅当你需要更宽泛的入站辅助 barrel 时，才使用 +`openclaw/plugin-sdk/channel-inbound`。 -适合放在插件本地逻辑中的内容： +适合插件本地逻辑的内容： -- 检测是否回复机器人 -- 检测是否引用机器人 +- 回复给机器人的检测 +- 引用机器人的检测 - 线程参与检查 - 服务/系统消息排除 - 证明机器人参与所需的平台原生缓存 -适合放在共享辅助工具中的内容： +适合共享辅助函数的内容： - `requireMention` - 显式提及结果 @@ -203,7 +191,7 @@ x-i18n: - 命令绕过 - 最终跳过决策 -推荐流程： +首选流程： 1. 计算本地提及事实。 2. 将这些事实传入 `resolveInboundMentionDecision({ facts, policy })`。 @@ -246,7 +234,7 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` 为已经依赖运行时注入的内置渠道插件暴露相同的共享提及辅助工具： +`api.runtime.channel.mentions` 为已经依赖运行时注入的内置渠道插件暴露相同的共享提及辅助函数： - `buildMentionRegexes` - `matchesMentionPatterns` @@ -254,16 +242,20 @@ if (decision.shouldSkip) return; - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -如果你只需要 `implicitMentionKindWhen` 和 `resolveInboundMentionDecision`，请从 `openclaw/plugin-sdk/channel-mention-gating` 导入，以避免加载无关的入站运行时辅助工具。 +如果你只需要 `implicitMentionKindWhen` 和 +`resolveInboundMentionDecision`，请从 +`openclaw/plugin-sdk/channel-mention-gating` 导入，以避免加载无关的入站运行时辅助函数。 -较旧的 `resolveMentionGating*` 辅助工具仍保留在 `openclaw/plugin-sdk/channel-inbound` 上，仅作为兼容性导出。新代码应使用 `resolveInboundMentionDecision({ facts, policy })`。 +较旧的 `resolveMentionGating*` 辅助函数仍作为兼容导出保留在 +`openclaw/plugin-sdk/channel-inbound` 上。新代码应使用 +`resolveInboundMentionDecision({ facts, policy })`。 ## 演练 - 创建标准插件文件。`package.json` 中的 `channel` 字段会使其成为渠道插件。有关完整的包元数据界面，请参阅 [插件设置和配置](/zh-CN/plugins/sdk-setup#openclaw-channel)： + 创建标准插件文件。`package.json` 中的 `channel` 字段会让它成为渠道插件。完整的软件包元数据界面请参阅 [插件设置和配置](/zh-CN/plugins/sdk-setup#openclaw-channel)： ```json package.json @@ -320,12 +312,13 @@ if (decision.shouldSkip) return; ``` - `configSchema` 会验证 `plugins.entries.acme-chat.config`。将它用于插件拥有的、不是渠道账户配置的设置。`channelConfigs` 会验证 `channels.acme-chat`，并且是在插件运行时加载前，配置 schema、设置和 UI 界面使用的冷路径来源。 + `configSchema` 验证 `plugins.entries.acme-chat.config`。将它用于插件拥有的设置，而不是渠道账号配置。`channelConfigs` + 验证 `channels.acme-chat`，并且是插件运行时加载前由配置架构、设置和 UI 界面使用的冷路径来源。 - `ChannelPlugin` 接口有许多可选的适配器界面。从最小集合开始，也就是 `id` 和 `setup`，然后按需添加适配器。 + `ChannelPlugin` 接口包含许多可选的适配器界面。先从最小内容开始，即 `id` 和 `setup`，再按需添加适配器。 创建 `src/channel.ts`： @@ -420,24 +413,31 @@ if (decision.shouldSkip) return; }); ``` + 对于同时接受规范顶层私信键和旧版嵌套键的渠道，使用 `plugin-sdk/channel-config-helpers` 中的辅助函数：`resolveChannelDmAccess`、`resolveChannelDmPolicy`、`resolveChannelDmAllowFrom` 和 `normalizeChannelDmPolicy` 会让账号本地值优先于继承的根值。通过 `normalizeLegacyDmAliases` 将同一个解析器与 Doctor 修复配对，这样运行时和迁移会读取相同的契约。 + - 你无需手动实现低层适配器接口，而是传入声明式选项，构建器会将它们组合起来： + 你不需要手动实现低级适配器接口，而是传入声明式选项，构建器会组合它们： | 选项 | 接线内容 | | --- | --- | - | `security.dm` | 来自配置字段的作用域 DM 安全解析器 | - | `pairing.text` | 基于文本的 DM 配对流程，包含代码交换 | - | `threading` | 回复模式解析器（固定、账户作用域或自定义） | + | `security.dm` | 来自配置字段的作用域私信安全解析器 | + | `pairing.text` | 基于文本的私信配对流程，带代码交换 | + | `threading` | 回复到模式解析器（固定、账号作用域或自定义） | | `outbound.attachedResults` | 返回结果元数据（消息 ID）的发送函数 | 如果你需要完全控制，也可以传入原始适配器对象，而不是声明式选项。 - 原始出站适配器可以定义 `chunker(text, limit, ctx)` 函数。可选的 `ctx.formatting` 携带投递时的格式决策，例如 `maxLinesPerMessage`；请在发送前应用它，这样回复线程和分块边界只由共享出站投递解析一次。发送上下文也会在解析出原生回复目标时包含 `replyToIdSource`（`implicit` 或 `explicit`），这样载荷辅助工具可以保留显式回复标签，而不会消耗隐式的一次性回复槽位。 + 原始出站适配器可以定义一个 `chunker(text, limit, ctx)` 函数。 + 可选的 `ctx.formatting` 会携带发送时的格式决策， + 例如 `maxLinesPerMessage`；请在发送前应用它，这样回复串联 + 和分块边界只会由共享出站发送流程解析一次。 + 当原生回复目标已解析时，发送上下文也会包含 `replyToIdSource`（`implicit` 或 `explicit`）， + 因此载荷辅助函数可以保留显式回复标签，而不会消耗隐式的一次性回复槽。 - + 创建 `index.ts`： ```typescript index.ts @@ -474,21 +474,20 @@ if (decision.shouldSkip) return; ``` 将渠道拥有的 CLI 描述符放在 `registerCliMetadata(...)` 中，这样 OpenClaw - 就能在不激活完整渠道运行时的情况下，在根帮助中显示它们， - 同时正常的完整加载仍会获取相同描述符，用于实际命令 + 无需激活完整渠道运行时，就能在根帮助中显示它们； + 同时，正常的完整加载仍会获取相同描述符，用于真正的命令 注册。将 `registerFull(...)` 保留给仅运行时的工作。 如果 `registerFull(...)` 注册 Gateway 网关 RPC 方法，请使用 - 插件专用前缀。核心管理命名空间（`config.*`、 + 插件专属前缀。核心管理命名空间（`config.*`、 `exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并且始终 - 解析为 `operator.admin`。 - `defineChannelPluginEntry` 会自动处理注册模式拆分。请参阅 - [入口点](/zh-CN/plugins/sdk-entrypoints#definechannelpluginentry) 了解所有 - 选项。 + 解析到 `operator.admin`。 + `defineChannelPluginEntry` 会自动处理注册模式拆分。所有 + 选项请参阅[入口点](/zh-CN/plugins/sdk-entrypoints#definechannelpluginentry)。 - - 创建 `setup-entry.ts`，用于在新手引导期间轻量加载： + + 创建 `setup-entry.ts`，用于新手引导期间的轻量加载： ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -497,21 +496,20 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - 当渠道被禁用或尚未配置时，OpenClaw 会加载这个入口，而不是完整入口。 - 这样可以避免在设置流程期间引入沉重的运行时代码。 - 详情请参阅[设置和配置](/zh-CN/plugins/sdk-setup#setup-entry)。 + 当渠道被禁用或未配置时，OpenClaw 会加载它，而不是完整入口。 + 这样可以避免在设置流程中引入沉重的运行时代码。 + 详情请参阅[设置与配置](/zh-CN/plugins/sdk-setup#setup-entry)。 - 将设置安全导出拆分到侧车模块的内置工作区渠道， + 将设置安全导出拆分到 sidecar 模块的内置工作区渠道， 如果还需要显式的设置时运行时 setter，可以使用 - `openclaw/plugin-sdk/channel-entry-contract` 中的 - `defineBundledChannelSetupEntry(...)`。 + `openclaw/plugin-sdk/channel-entry-contract` 中的 `defineBundledChannelSetupEntry(...)`。 - - 你的插件需要从平台接收消息，并将它们转发给 - OpenClaw。典型模式是使用一个 webhook 验证请求，并 - 通过你的渠道入站处理器分发请求： + + 你的插件需要从平台接收消息并将其转发给 + OpenClaw。典型模式是使用 webhook 来验证请求，并 + 通过你的渠道入站处理器分发它： ```typescript registerFull(api) { @@ -535,15 +533,15 @@ if (decision.shouldSkip) return; ``` - 入站消息处理是渠道特定的。每个渠道插件拥有 - 自己的入站流水线。查看内置渠道插件 - （例如 Microsoft Teams 或 Google Chat 插件包）了解真实模式。 + 入站消息处理是渠道特定的。每个渠道插件都拥有 + 自己的入站流水线。请查看内置渠道插件 + （例如 Microsoft Teams 或 Google Chat 插件包）中的真实模式。 - + 在 `src/channel.test.ts` 中编写同目录测试： ```typescript src/channel.test.ts @@ -582,7 +580,7 @@ if (decision.shouldSkip) return; pnpm test -- /acme-chat/ ``` - 如需共享测试辅助工具，请参阅[测试](/zh-CN/plugins/sdk-testing)。 + 如需共享测试辅助函数，请参阅[测试](/zh-CN/plugins/sdk-testing)。 @@ -607,35 +605,35 @@ if (decision.shouldSkip) return; ## 高级主题 - + 固定、账户作用域或自定义回复模式 - - describeMessageTool 和动作发现 + + describeMessageTool 和操作发现 - + inferTargetChatType、looksLikeId、resolveTarget - + TTS、STT、媒体、通过 api.runtime 使用的子智能体 -一些内置辅助接缝仍然存在，用于内置插件维护和 +一些内置辅助接缝仍然存在，用于维护内置插件以及 兼容性。它们不是新渠道插件的推荐模式； -除非你正在直接维护该内置插件系列，否则请优先使用通用 SDK -表面的通用渠道/设置/回复/运行时子路径。 +除非你正在直接维护该内置插件家族，否则请优先使用通用 SDK +表面中的通用 channel/setup/reply/runtime 子路径。 ## 后续步骤 -- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 如果你的插件还提供模型 +- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 如果你的插件也提供模型 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 -- [SDK 测试](/zh-CN/plugins/sdk-testing) — 测试实用工具和契约测试 -- [插件清单](/zh-CN/plugins/manifest) — 完整清单 schema +- [SDK 测试](/zh-CN/plugins/sdk-testing) — 测试工具和契约测试 +- [插件 Manifest](/zh-CN/plugins/manifest) — 完整 manifest schema -## 相关内容 +## 相关 - [插件 SDK 设置](/zh-CN/plugins/sdk-setup) - [构建插件](/zh-CN/plugins/building-plugins) diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 83a53603f..916313a5f 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -2,73 +2,73 @@ read_when: - 你看到 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 警告 - 你看到 OPENCLAW_EXTENSION_API_DEPRECATED 警告 - - 你在 OpenClaw 2026.4.25 之前使用了 api.registerEmbeddedExtensionFactory - - 你正在将一个插件更新到现代插件架构 + - 你在 OpenClaw 2026.4.25 之前使用过 api.registerEmbeddedExtensionFactory + - 你正在将插件更新为现代插件架构 - 你维护一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-29T13:54:45Z" + generated_at: "2026-04-29T15:39:48Z" model: gpt-5.5 provider: openai - source_hash: fbc2569e5116d168151c34b31392df87be2b30f67de7303552c9164205716f07 + source_hash: 00a1f95a33c50d5c69d7b4768858289365bf29ed069abb3f29218e03c597b4c6 source_path: plugins/sdk-migration.md workflow: 16 --- -OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，使用聚焦且有文档说明的导入。如果你的插件是在新架构之前构建的，本指南可帮助你迁移。 +OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，使用聚焦且有文档说明的导入。如果你的插件是在新架构之前构建的，本指南会帮助你迁移。 ## 正在变化的内容 -旧插件系统提供了两个开放范围很大的表面，让插件可以从单个入口点导入所需的任何内容： +旧插件系统提供了两个开放面很广的接口，让插件可以从单个入口点导入所需的任何内容： -- **`openclaw/plugin-sdk/compat`** — 一个单一导入，重新导出了数十个辅助函数。它的引入是为了在新插件架构构建期间，让较旧的基于钩子的插件继续工作。 +- **`openclaw/plugin-sdk/compat`** — 一个单一导入，会重新导出数十个辅助函数。它的引入是为了在新插件架构构建期间，保持旧版基于钩子的插件可用。 - **`openclaw/plugin-sdk/infra-runtime`** — 一个宽泛的运行时辅助 barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助函数、文件辅助函数、审批类型和无关工具。 - **`openclaw/plugin-sdk/config-runtime`** — 一个宽泛的配置兼容 barrel，在迁移窗口期间仍携带已弃用的直接加载/写入辅助函数。 -- **`openclaw/extension-api`** — 一个桥接层，使插件可以直接访问主机端辅助函数，例如嵌入式智能体运行器。 -- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除的 Pi 专用内置插件钩子，可观察嵌入式运行器事件，例如 `tool_result`。 +- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问宿主侧辅助函数，例如内嵌智能体运行器。 +- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除的 Pi 专用内置扩展钩子，可观察内嵌运行器事件，例如 `tool_result`。 -宽泛导入表面现在已**弃用**。它们在运行时仍然可用，但新插件不得使用它们，现有插件也应在下一次主版本发布移除它们之前完成迁移。Pi 专用的嵌入式插件工厂注册 API 已被移除；请改用工具结果中间件。 +这些宽泛导入接口现在已**弃用**。它们在运行时仍可工作，但新插件不得使用它们，现有插件应在下一个 major release 移除它们之前完成迁移。Pi 专用内嵌扩展工厂注册 API 已移除；请改用工具结果中间件。 -OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已有文档说明的插件行为。破坏性契约变更必须先经过兼容适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、清单字段、设置 API、钩子和运行时注册行为。 +OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释有文档说明的插件行为。破坏性契约变更必须先经过兼容适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、manifest 字段、设置 API、钩子和运行时注册行为。 - 向后兼容层将在未来某个主版本发布中移除。届时仍从这些表面导入的插件将会中断。Pi 专用的嵌入式插件工厂注册已经不再加载。 + 向后兼容层将在未来某个 major release 中移除。届时仍从这些接口导入的插件将会中断。Pi 专用内嵌扩展工厂注册已经不再加载。 -## 为什么要进行这项变更 +## 为什么做出此变更 -旧方法造成了一些问题： +旧方法会导致问题： - **启动缓慢** — 导入一个辅助函数会加载数十个无关模块 -- **循环依赖** — 宽泛的重新导出很容易造成导入环 -- **API 表面不清晰** — 无法判断哪些导出是稳定的，哪些是内部的 +- **循环依赖** — 宽泛的重新导出很容易造成导入循环 +- **API 接口不清晰** — 无法判断哪些导出是稳定的，哪些是内部的 -现代插件 SDK 修复了这一点：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有明确用途和文档化契约。 +现代插件 SDK 修复了这一点：每个导入路径（`openclaw/plugin-sdk/\`）都是小型、自包含的模块，具有明确用途和有文档说明的契约。 -针对内置渠道的旧版提供商便利 seam 也已移除。带渠道品牌的辅助 seam 是私有 monorepo 快捷方式，不是稳定的插件契约。请改用窄范围的通用 SDK 子路径。在内置插件工作区内，请将提供商拥有的辅助函数保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +面向内置渠道的旧版提供商便利衔接也已移除。带渠道品牌的辅助衔接是私有 mono-repo 捷径，并非稳定插件契约。请改用窄范围的通用 SDK 子路径。在内置插件工作区内，将提供商拥有的辅助函数保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 当前内置提供商示例： -- Anthropic 将 Claude 专用流辅助函数保留在自己的 `api.ts` / `contract-api.ts` seam 中 +- Anthropic 将 Claude 专用流辅助函数保留在自己的 `api.ts` / `contract-api.ts` 衔接中 - OpenAI 将提供商构建器、默认模型辅助函数和实时提供商构建器保留在自己的 `api.ts` 中 - OpenRouter 将提供商构建器和新手引导/配置辅助函数保留在自己的 `api.ts` 中 -## 兼容策略 +## 兼容性策略 -对于外部插件，兼容工作按以下顺序进行： +对于外部插件，兼容性工作按以下顺序进行： 1. 添加新契约 -2. 通过兼容适配器保持旧行为接线 +2. 保持旧行为通过兼容适配器接线 3. 发出诊断或警告，指明旧路径和替代项 4. 在测试中覆盖两条路径 5. 记录弃用和迁移路径 -6. 仅在已宣布的迁移窗口结束后移除，通常是在主版本发布中 +6. 仅在公告的迁移窗口之后移除，通常在 major release 中进行 -维护者可以使用 `pnpm plugins:boundary-report` 审计当前迁移队列。使用 `pnpm plugins:boundary-report:summary` 查看精简计数，使用 `--owner ` 查看单个插件或兼容所有者，并在 CI gate 需要因到期兼容记录、跨所有者保留 SDK 导入或未使用的保留 SDK 子路径而失败时使用 `pnpm plugins:boundary-report:ci`。该报告会按移除日期对已弃用的兼容记录分组，统计本地代码/文档引用，暴露跨所有者保留 SDK 导入，并汇总私有 memory-host SDK 桥接，让兼容清理保持显式，而不是依赖临时搜索。保留的 SDK 子路径必须有被跟踪的所有者用法；未使用的保留辅助导出应从公共 SDK 中移除。 +维护者可以使用 `pnpm plugins:boundary-report` 审计当前迁移队列。使用 `pnpm plugins:boundary-report:summary` 获取紧凑计数，使用 `--owner ` 查看单个插件或兼容性所有者，并在 CI gate 需要因到期兼容性记录、跨所有者保留 SDK 导入或未使用的保留 SDK 子路径而失败时使用 `pnpm plugins:boundary-report:ci`。报告会按移除日期对已弃用的兼容性记录分组，统计本地代码/文档引用，呈现跨所有者保留 SDK 导入，并汇总私有 memory-host SDK 桥接，让兼容性清理保持显式，而不是依赖临时搜索。保留 SDK 子路径必须有跟踪的所有者用法；未使用的保留辅助导出应从公共 SDK 中移除。 -如果某个清单字段仍被接受，插件作者可以继续使用它，直到文档和诊断另有说明。新代码应优先使用有文档说明的替代项，但现有插件不应在普通次版本发布期间中断。 +如果某个 manifest 字段仍被接受，插件作者可以继续使用，直到文档和诊断另有说明。新代码应优先使用有文档说明的替代项，但现有插件不应在普通 minor release 中中断。 ## 如何迁移 @@ -76,9 +76,9 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 内置插件应停止直接调用 `api.runtime.config.loadConfig()` 和 - `api.runtime.config.writeConfigFile(...)`。优先使用已经传入活动调用路径的配置。需要当前进程快照的长生命周期处理器可以使用 `api.runtime.config.current()`。长生命周期智能体工具应在 `execute` 内使用工具上下文的 `ctx.getRuntimeConfig()`，这样在配置写入前创建的工具仍能看到刷新的运行时配置。 + `api.runtime.config.writeConfigFile(...)`。优先使用已经传入当前调用路径的配置。需要当前进程快照的长生命周期处理器可以使用 `api.runtime.config.current()`。长生命周期智能体工具应在 `execute` 内使用工具上下文的 `ctx.getRuntimeConfig()`，这样在配置写入之前创建的工具仍能看到刷新的运行时配置。 - 配置写入必须通过事务辅助函数，并选择写入后策略： + 配置写入必须通过事务型辅助函数，并选择写入后策略： ```typescript await api.runtime.config.mutateConfigFile({ @@ -89,29 +89,28 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 }); ``` - 当调用方知道变更需要干净重启 Gateway 网关时，使用 `afterWrite: { mode: "restart", reason: "..." }`；只有当调用方拥有后续处理并且有意抑制重载规划器时，才使用 `afterWrite: { mode: "none", reason: "..." }`。变更结果包含用于测试和日志记录的类型化 `followUp` 摘要；Gateway 网关仍负责应用或调度重启。`loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为外部插件的已弃用兼容辅助函数保留，并使用 `runtime-config-load-write` 兼容代码警告一次。内置插件和仓库运行时代码受到 `pnpm check:deprecated-internal-config-api` 和 `pnpm check:no-runtime-action-load-config` 中扫描器护栏保护：新的生产插件用法会直接失败，直接配置写入会失败，Gateway 网关服务器方法必须使用请求运行时快照，运行时渠道发送/action/client 辅助函数必须从其边界接收配置，长生命周期运行时模块允许的环境性 `loadConfig()` 调用数量为零。 + 当调用方知道该变更需要干净重启 Gateway 网关时，使用 `afterWrite: { mode: "restart", reason: "..." }`；仅当调用方拥有后续处理并有意抑制重载规划器时，才使用 `afterWrite: { mode: "none", reason: "..." }`。变更结果包含一个类型化的 `followUp` 摘要，用于测试和日志；Gateway 网关仍负责应用或调度重启。`loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为外部插件的已弃用兼容辅助函数保留，并会使用 `runtime-config-load-write` 兼容代码发出一次警告。内置插件和仓库运行时代码受到 `pnpm check:deprecated-internal-config-api` 与 `pnpm check:no-runtime-action-load-config` 中扫描器防护规则的保护：新的生产插件用法会直接失败，直接配置写入会失败，Gateway 网关服务器方法必须使用请求运行时快照，运行时渠道发送/动作/客户端辅助函数必须从其边界接收配置，并且长生命周期运行时模块允许的环境式 `loadConfig()` 调用数量为零。 - 新插件代码也应避免导入宽泛的 - `openclaw/plugin-sdk/config-runtime` 兼容 barrel。请使用与任务匹配的窄范围 SDK 子路径： + 新插件代码还应避免导入宽泛的 `openclaw/plugin-sdk/config-runtime` 兼容 barrel。请使用与任务匹配的窄范围 SDK 子路径： | 需求 | 导入 | | --- | --- | - | `OpenClawConfig` 等配置类型 | `openclaw/plugin-sdk/config-types` | + | 配置类型，例如 `OpenClawConfig` | `openclaw/plugin-sdk/config-types` | | 已加载配置断言和插件入口配置查找 | `openclaw/plugin-sdk/plugin-config-runtime` | | 当前运行时快照读取 | `openclaw/plugin-sdk/runtime-config-snapshot` | | 配置写入 | `openclaw/plugin-sdk/config-mutation` | | 会话存储辅助函数 | `openclaw/plugin-sdk/session-store-runtime` | | Markdown 表格配置 | `openclaw/plugin-sdk/markdown-table-runtime` | | 组策略运行时辅助函数 | `openclaw/plugin-sdk/runtime-group-policy` | - | Secret 输入解析 | `openclaw/plugin-sdk/secret-input-runtime` | + | 密钥输入解析 | `openclaw/plugin-sdk/secret-input-runtime` | | 模型/会话覆盖 | `openclaw/plugin-sdk/model-session-runtime` | - 内置插件及其测试受到扫描器保护，防止使用宽泛 barrel，使导入和 mock 保持局部于其所需行为。宽泛 barrel 仍为外部兼容性而存在，但新代码不应依赖它。 + 内置插件及其测试有扫描器防护，防止使用宽泛 barrel，因此导入和 mock 会保持局部化，只针对它们需要的行为。宽泛 barrel 仍为外部兼容性存在，但新代码不应依赖它。 - - 内置插件必须将 Pi 专用 + + 内置插件必须将 Pi 专用的 `api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为运行时中立的中间件。 ```typescript @@ -123,7 +122,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 }); ``` - 同时更新插件清单： + 同时更新插件 manifest： ```json { @@ -133,31 +132,29 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 } ``` - 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前重写它。 + 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前改写它。 - 支持审批的渠道插件现在通过 `approvalCapability.nativeRuntime` 加共享运行时上下文注册表暴露原生审批行为。 + 支持审批的渠道插件现在通过 `approvalCapability.nativeRuntime` 加共享运行时上下文注册表来暴露原生审批行为。 关键变更： - - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 - `approvalCapability.nativeRuntime` - - 将审批专用 auth/投递从旧版 `plugin.auth` / - `plugin.approvals` 接线移到 `approvalCapability` - - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；将投递/native/render 字段移到 `approvalCapability` - - `plugin.auth` 仍仅用于渠道登录/登出流程；core 不再读取其中的审批 auth 钩子 - - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道拥有的运行时对象，例如客户端、token 或 Bolt app - - 不要从原生审批处理器发送插件拥有的重路由通知；core 现在根据实际投递结果拥有已路由到其他位置通知 - - 将 `channelRuntime` 传入 `createChannelManager(...)` 时，提供真实的 `createPluginRuntime().channel` 表面。部分 stub 会被拒绝。 + - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 `approvalCapability.nativeRuntime` + - 将审批专用身份验证/投递从旧版 `plugin.auth` / `plugin.approvals` 接线迁移到 `approvalCapability` + - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将投递/原生/渲染字段迁移到 `approvalCapability` + - `plugin.auth` 仅保留用于渠道登录/登出流程；core 不再读取其中的审批身份验证钩子 + - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道拥有的运行时对象，例如客户端、令牌或 Bolt 应用 + - 不要从原生审批处理器发送插件拥有的重路由通知；core 现在根据实际投递结果负责路由到其他位置的通知 + - 将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 会被拒绝。 - 有关当前审批能力布局，请参阅 `/plugins/sdk-channel-plugins`。 + 请参阅 `/plugins/sdk-channel-plugins` 了解当前审批能力布局。 - 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，除非你显式传入 `allowShellFallback: true`，否则未解析的 Windows `.cmd`/`.bat` 包装器现在会失败关闭。 + 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，未解析的 Windows `.cmd`/`.bat` 包装器现在会默认失败关闭，除非你显式传入 `allowShellFallback: true`。 ```typescript // Before @@ -172,12 +169,12 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 }); ``` - 如果你的调用方并未有意依赖 shell 回退，不要设置 `allowShellFallback`，而是处理抛出的错误。 + 如果你的调用方并非有意依赖 shell 回退，请不要设置 `allowShellFallback`，而应处理抛出的错误。 - - 在你的插件中搜索来自任一已弃用表面的导入： + + 搜索你的插件中来自任一已弃用接口的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -189,7 +186,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - 旧表面的每个导出都映射到一个具体的现代导入路径： + 旧接口中的每个导出都映射到一个特定的现代导入路径： ```typescript // Before (deprecated backwards-compatibility layer) @@ -205,7 +202,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - 对于主机端辅助函数，请使用注入的插件运行时，而不是直接导入： + 对于宿主侧辅助函数，请使用注入的插件运行时，而不是直接导入： ```typescript // Before (deprecated extension-api bridge) @@ -216,9 +213,9 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - 同样的模式也适用于其他旧版桥接辅助函数： + 同样的模式也适用于其他旧版桥接助手： - | 旧导入 | 现代等价项 | + | 旧导入 | 现代等效项 | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -226,46 +223,42 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | 会话存储辅助函数 | `api.runtime.agent.session.*` | + | 会话存储助手 | `api.runtime.agent.session.*` | - `openclaw/plugin-sdk/infra-runtime` 仍然存在，用于外部兼容性， - 但新代码应导入它实际需要的聚焦辅助接口： + `openclaw/plugin-sdk/infra-runtime` 仍然保留以兼容外部代码，但新代码应该导入它实际需要的聚焦助手接口： | 需求 | 导入 | | --- | --- | - | 系统事件队列辅助函数 | `openclaw/plugin-sdk/system-event-runtime` | - | 心跳事件和可见性辅助函数 | `openclaw/plugin-sdk/heartbeat-runtime` | - | 待处理投递队列排空 | `openclaw/plugin-sdk/delivery-queue-runtime` | + | 系统事件队列助手 | `openclaw/plugin-sdk/system-event-runtime` | + | 心跳事件和可见性助手 | `openclaw/plugin-sdk/heartbeat-runtime` | + | 待处理投递队列清空 | `openclaw/plugin-sdk/delivery-queue-runtime` | | 渠道活动遥测 | `openclaw/plugin-sdk/channel-activity-runtime` | - | 内存内去重缓存 | `openclaw/plugin-sdk/dedupe-runtime` | - | 安全本地文件/媒体路径辅助函数 | `openclaw/plugin-sdk/file-access-runtime` | + | 内存去重缓存 | `openclaw/plugin-sdk/dedupe-runtime` | + | 安全的本地文件/媒体路径助手 | `openclaw/plugin-sdk/file-access-runtime` | | 感知调度器的 fetch | `openclaw/plugin-sdk/runtime-fetch` | - | 代理和受保护的 fetch 辅助函数 | `openclaw/plugin-sdk/fetch-runtime` | + | 代理和受保护的 fetch 助手 | `openclaw/plugin-sdk/fetch-runtime` | | SSRF 调度器策略类型 | `openclaw/plugin-sdk/ssrf-dispatcher` | - | 审批请求/解决类型 | `openclaw/plugin-sdk/approval-runtime` | - | 审批回复负载和命令辅助函数 | `openclaw/plugin-sdk/approval-reply-runtime` | - | 错误格式化辅助函数 | `openclaw/plugin-sdk/error-runtime` | + | 审批请求/解析类型 | `openclaw/plugin-sdk/approval-runtime` | + | 审批回复载荷和命令助手 | `openclaw/plugin-sdk/approval-reply-runtime` | + | 错误格式化助手 | `openclaw/plugin-sdk/error-runtime` | | 传输就绪等待 | `openclaw/plugin-sdk/transport-ready-runtime` | - | 安全令牌辅助函数 | `openclaw/plugin-sdk/secure-random-runtime` | + | 安全令牌助手 | `openclaw/plugin-sdk/secure-random-runtime` | | 有界异步任务并发 | `openclaw/plugin-sdk/concurrency-runtime` | | 数值强制转换 | `openclaw/plugin-sdk/number-runtime` | | 进程本地异步锁 | `openclaw/plugin-sdk/async-lock-runtime` | | 文件锁 | `openclaw/plugin-sdk/file-lock` | - 内置插件会通过扫描器防止使用 `infra-runtime`，因此仓库代码 - 无法回退到宽泛的 barrel。 + 内置插件会通过扫描器防止使用 `infra-runtime`，因此仓库代码不能回退到宽泛的桶文件。 - - 新的渠道路由代码应使用 `openclaw/plugin-sdk/channel-route`。 - 较旧的 route-key 和 comparable-target 名称会在迁移窗口期间保留为兼容性别名， - 但新插件应使用直接描述行为的路由名称： + + 新的渠道路由代码应该使用 `openclaw/plugin-sdk/channel-route`。旧的 route-key 和 comparable-target 名称在迁移窗口期间仍作为兼容别名保留，但新插件应该使用能直接描述行为的路由名称： - | 旧辅助函数 | 现代辅助函数 | + | 旧助手 | 现代助手 | | --- | --- | | `channelRouteIdentityKey(...)` | `channelRouteDedupeKey(...)` | | `channelRouteKey(...)` | `channelRouteCompactKey(...)` | @@ -275,10 +268,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `comparableChannelTargetsMatch(...)` | `channelRouteTargetsMatchExact(...)` | | `comparableChannelTargetsShareRoute(...)` | `channelRouteTargetsShareConversation(...)` | - 现代路由辅助函数会在原生审批、回复抑制、入站去重、 - cron 投递和会话路由中一致规范化 `{ channel, to, accountId, threadId }`。 - 如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)` - 将该解析器适配到同一路由目标契约中。 + 现代路由助手会在原生审批、回复抑制、入站去重、cron 投递和会话路由之间一致地规范化 `{ channel, to, accountId, threadId }`。如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)` 将该解析器适配到相同的路由目标契约。 @@ -292,208 +282,206 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 ## 导入路径参考 - - | 导入路径 | 用途 | 关键导出 | + + | 导入路径 | 用途 | 主要导出 | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 渠道入口定义/构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | 单提供商入口辅助工具 | `defineSingleProviderPluginEntry` | + | `plugin-sdk/plugin-entry` | 标准插件入口助手 | `definePluginEntry` | + | `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | 根配置架构导出 | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | 单提供商入口助手 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助工具 | 允许列表提示、设置 Status 构建器 | - | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 可安全导入的设置补丁适配器、查找备注辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委派设置代理 | - | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表/配置/操作门控辅助工具 | - | `plugin-sdk/account-id` | 账户 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化 | - | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表/账户操作辅助工具 | - | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | + | `plugin-sdk/setup` | 共享设置向导助手 | 允许列表提示、设置 Status 构建器 | + | `plugin-sdk/setup-runtime` | 设置时运行时助手 | 可安全导入的设置补丁适配器、查找说明助手、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | + | `plugin-sdk/setup-adapter-runtime` | 设置适配器助手 | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | 设置工具助手 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | 多账号助手 | 账号列表/配置/操作门控助手 | + | `plugin-sdk/account-id` | 账号 ID 助手 | `DEFAULT_ACCOUNT_ID`、账号 ID 规范化 | + | `plugin-sdk/account-resolution` | 账号查找助手 | 账号查找 + 默认回退助手 | + | `plugin-sdk/account-helpers` | 窄作用域账号助手 | 账号列表/账号操作助手 | + | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | 回复前缀、正在输入和来源投递接线 | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` | - | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 仅共享渠道配置 schema 原语和通用构建器 | - | `plugin-sdk/bundled-channel-config-schema` | 内置配置 schema | 仅限 OpenClaw 维护的内置插件；新插件必须定义插件本地 schema | - | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置 schema | 仅兼容性别名；对于维护中的内置插件，请使用 `plugin-sdk/bundled-channel-config-schema` | - | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复/冲突验证 | + | `plugin-sdk/channel-reply-pipeline` | 回复前缀、输入状态和来源投递布线 | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` | + | `plugin-sdk/channel-config-helpers` | 配置适配器工厂和私信访问助手 | `createHybridChannelConfigAdapter`, `resolveChannelDmAccess`, `resolveChannelDmAllowFrom`, `resolveChannelDmPolicy`, `normalizeChannelDmPolicy`, `normalizeLegacyDmAliases` | + | `plugin-sdk/channel-config-schema` | 配置架构构建器 | 共享渠道配置架构原语和仅通用构建器 | + | `plugin-sdk/bundled-channel-config-schema` | 内置配置架构 | 仅限 OpenClaw 维护的内置插件；新插件必须定义插件本地架构 | + | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置架构 | 仅兼容性别名；对维护中的内置插件请使用 `plugin-sdk/bundled-channel-config-schema` | + | `plugin-sdk/telegram-command-config` | Telegram 命令配置助手 | 命令名规范化、描述裁剪、重复/冲突验证 | | `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | 账户 Status 和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览最终化辅助工具 | - | `plugin-sdk/inbound-envelope` | 入站信封辅助工具 | 共享路由 + 信封构建器辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 | - | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 | - | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | - | `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 无需导入完整出站运行时的轻量 `resolveOutboundSendDep` 查找 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、身份/发送委托、会话、格式化和载荷规划辅助工具 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助工具 | 用于旧版字段布局的 Agent 媒体载荷构建器 | + | `plugin-sdk/channel-lifecycle` | 账号 Status 和草稿流生命周期助手 | `createAccountStatusSink`、草稿预览最终化助手 | + | `plugin-sdk/inbound-envelope` | 入站信封助手 | 共享路由 + 信封构建器助手 | + | `plugin-sdk/inbound-reply-dispatch` | 入站回复助手 | 共享记录和分发助手 | + | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配助手 | + | `plugin-sdk/outbound-media` | 出站媒体助手 | 共享出站媒体加载 | + | `plugin-sdk/outbound-send-deps` | 出站发送依赖助手 | 不导入完整出站运行时的轻量级 `resolveOutboundSendDep` 查找 | + | `plugin-sdk/outbound-runtime` | 出站运行时助手 | 出站投递、身份/发送委托、会话、格式化和载荷规划助手 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定助手 | 线程绑定生命周期和适配器助手 | + | `plugin-sdk/agent-media-payload` | 旧版媒体载荷助手 | 面向旧版字段布局的 Agent 媒体载荷构建器 | | `plugin-sdk/channel-runtime` | 已弃用的兼容性垫片 | 仅旧版渠道运行时实用工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | 日志记录器/运行时环境、超时、重试和退避辅助工具 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/钩子/http/交互式辅助工具 | - | `plugin-sdk/hook-runtime` | 钩子管线辅助工具 | 共享 webhook/内部钩子管线辅助工具 | - | `plugin-sdk/lazy-runtime` | 懒加载运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 | - | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 | - | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端、事件循环就绪的启动辅助工具，以及渠道 Status 补丁辅助工具 | + | `plugin-sdk/runtime` | 广义运行时助手 | 运行时/日志/备份/插件安装助手 | + | `plugin-sdk/runtime-env` | 窄作用域运行时环境助手 | 日志记录器/运行时环境、超时、重试和退避助手 | + | `plugin-sdk/plugin-runtime` | 共享插件运行时助手 | 插件命令/钩子/http/交互式助手 | + | `plugin-sdk/hook-runtime` | 钩子管线助手 | 共享 webhook/内部钩子管线助手 | + | `plugin-sdk/lazy-runtime` | 懒加载运行时助手 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程助手 | 共享 exec 助手 | + | `plugin-sdk/cli-runtime` | CLI 运行时助手 | 命令格式化、等待、版本助手 | + | `plugin-sdk/gateway-runtime` | Gateway 网关助手 | Gateway 网关客户端、事件循环就绪启动助手和渠道 Status 补丁助手 | | `plugin-sdk/config-runtime` | 已弃用的配置兼容性垫片 | 优先使用 `config-types`、`plugin-config-runtime`、`runtime-config-snapshot` 和 `config-mutation` | - | `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-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 用于热渠道入口点的轻量原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽范围的审批处理器运行时辅助工具；足够时优先使用更窄的适配器/Gateway 网关接缝 | - | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | Exec/插件审批回复载荷辅助工具 | - | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文注册/获取/监听辅助工具 | - | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和密钥收集辅助工具 | - | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机允许列表和专用网络策略辅助工具 | - | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定 dispatcher、受保护的 fetch、SSRF 策略辅助工具 | - | `plugin-sdk/system-event-runtime` | 系统事件辅助工具 | `enqueueSystemEvent`, `peekSystemEventEntries` | - | `plugin-sdk/heartbeat-runtime` | 心跳辅助工具 | 心跳事件和可见性辅助工具 | - | `plugin-sdk/delivery-queue-runtime` | 投递队列辅助工具 | `drainPendingDeliveries` | - | `plugin-sdk/channel-activity-runtime` | 渠道活动辅助工具 | `recordChannelActivity` | - | `plugin-sdk/dedupe-runtime` | 去重辅助工具 | 内存去重缓存 | - | `plugin-sdk/file-access-runtime` | 文件访问辅助工具 | 安全的本地文件/媒体路径辅助工具 | - | `plugin-sdk/transport-ready-runtime` | 传输就绪辅助工具 | `waitForTransportReady` | - | `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`、`isApprovalNotFoundError`、错误图辅助工具 | - | `plugin-sdk/fetch-runtime` | 包装的 fetch/代理辅助工具 | `resolveFetch`、代理辅助工具、EnvHttpProxyAgent 选项辅助工具 | - | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`、`retryAsync`、策略运行器 | + | `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-gateway-runtime` | 审批网关助手 | 共享审批网关解析助手 | + | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器助手 | 用于热渠道入口点的轻量级原生审批适配器加载助手 | + | `plugin-sdk/approval-handler-runtime` | 审批处理器助手 | 更广义的审批处理器运行时助手；当更窄的适配器/网关接缝足够时优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 审批目标助手 | 原生审批目标/账号绑定助手 | + | `plugin-sdk/approval-reply-runtime` | 审批回复助手 | Exec/插件审批回复载荷助手 | + | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文助手 | 通用渠道运行时上下文注册/获取/监听助手 | + | `plugin-sdk/security-runtime` | 安全助手 | 共享信任、私信门控、外部内容和密钥收集助手 | + | `plugin-sdk/ssrf-policy` | SSRF 策略助手 | 主机允许列表和私有网络策略助手 | + | `plugin-sdk/ssrf-runtime` | SSRF 运行时助手 | 固定调度器、受保护 fetch、SSRF 策略助手 | + | `plugin-sdk/system-event-runtime` | 系统事件助手 | `enqueueSystemEvent`, `peekSystemEventEntries` | + | `plugin-sdk/heartbeat-runtime` | 心跳助手 | 心跳事件和可见性助手 | + | `plugin-sdk/delivery-queue-runtime` | 投递队列助手 | `drainPendingDeliveries` | + | `plugin-sdk/channel-activity-runtime` | 渠道活动助手 | `recordChannelActivity` | + | `plugin-sdk/dedupe-runtime` | 去重助手 | 内存内去重缓存 | + | `plugin-sdk/file-access-runtime` | 文件访问助手 | 安全本地文件/媒体路径助手 | + | `plugin-sdk/transport-ready-runtime` | 传输就绪助手 | `waitForTransportReady` | + | `plugin-sdk/collection-runtime` | 有界缓存助手 | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | 诊断门控助手 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | 错误格式化助手 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图助手 | + | `plugin-sdk/fetch-runtime` | 包装的 fetch/代理助手 | `resolveFetch`、代理助手、EnvHttpProxyAgent 选项助手 | + | `plugin-sdk/host-runtime` | 主机规范化助手 | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | 重试助手 | `RetryConfig`, `retryAsync`、策略运行器 | | `plugin-sdk/allow-from` | 允许列表格式化 | `formatAllowFromLowercase` | | `plugin-sdk/allowlist-resolution` | 允许列表输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令门控和命令表面辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具，包括动态参数菜单格式化 | + | `plugin-sdk/command-auth` | 命令门控和命令表面助手 | `resolveControlCommandGate`、发送者授权助手、命令注册表助手，包括动态参数菜单格式化 | | `plugin-sdk/command-status` | 命令 Status/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 | - | `plugin-sdk/webhook-ingress` | Webhook 请求辅助工具 | Webhook 目标实用工具 | - | `plugin-sdk/webhook-request-guards` | Webhook 主体保护辅助工具 | 请求主体读取/限制辅助工具 | + | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入助手 | + | `plugin-sdk/webhook-ingress` | Webhook 请求助手 | Webhook 目标实用工具 | + | `plugin-sdk/webhook-request-guards` | Webhook 正文保护助手 | 请求正文读取/限制助手 | | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | 最终化、提供商分发和对话标签辅助工具 | - | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-dispatch-runtime` | 窄作用域回复分发助手 | 最终化、提供商分发和对话标签助手 | + | `plugin-sdk/reply-history` | 回复历史助手 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/Markdown 分块辅助工具 | - | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 | - | `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 | - | `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`、`buildAgentSessionKey`、`resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 | - | `plugin-sdk/status-helpers` | 渠道 Status 辅助工具 | 渠道/账户 Status 摘要构建器、运行时状态默认值、问题元数据辅助工具 | - | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 | - | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug/字符串规范化辅助工具 | - | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类请求输入中提取字符串 URL | - | `plugin-sdk/run-command` | 定时命令辅助工具 | 带规范化 stdout/stderr 的定时命令运行器 | - | `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 工具载荷提取 | 从工具结果对象中提取规范化载荷 | + | `plugin-sdk/reply-chunking` | 回复分块助手 | 文本/Markdown 分块助手 | + | `plugin-sdk/session-store-runtime` | 会话存储助手 | 存储路径 + 更新时间助手 | + | `plugin-sdk/state-paths` | 状态路径助手 | 状态和 OAuth 目录助手 | + | `plugin-sdk/routing` | 路由/会话键助手 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化助手 | + | `plugin-sdk/status-helpers` | 渠道 Status 助手 | 渠道/账号 Status 摘要构建器、运行时状态默认值、问题元数据助手 | + | `plugin-sdk/target-resolver-runtime` | 目标解析器助手 | 共享目标解析器助手 | + | `plugin-sdk/string-normalization-runtime` | 字符串规范化助手 | Slug/字符串规范化助手 | + | `plugin-sdk/request-url` | 请求 URL 助手 | 从类似请求的输入中提取字符串 URL | + | `plugin-sdk/run-command` | 定时命令助手 | 带规范化 stdout/stderr 的定时命令运行器 | + | `plugin-sdk/param-readers` | 参数读取器 | 常用工具/CLI 参数读取器 | + | `plugin-sdk/tool-payload` | 工具 payload 提取 | 从工具结果对象中提取规范化 payload | | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | - | `plugin-sdk/temp-path` | 临时路径帮助程序 | 共享的临时下载路径帮助程序 | - | `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/provider-auth-runtime` | 提供商运行时凭证帮助程序 | 运行时 API 密钥解析帮助程序 | - | `plugin-sdk/provider-auth-api-key` | 提供商 API 密钥设置帮助程序 | API 密钥新手引导/配置写入帮助程序 | - | `plugin-sdk/provider-auth-result` | 提供商凭证结果帮助程序 | 标准 OAuth 凭证结果构建器 | - | `plugin-sdk/provider-auth-login` | 提供商交互式登录帮助程序 | 共享交互式登录帮助程序 | - | `plugin-sdk/provider-selection-runtime` | 提供商选择帮助程序 | 已配置或自动提供商选择，以及原始提供商配置合并 | - | `plugin-sdk/provider-env-vars` | 提供商环境变量帮助程序 | 提供商凭证环境变量查找帮助程序 | - | `plugin-sdk/provider-model-shared` | 共享提供商模型/重放帮助程序 | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享重放策略构建器、提供商端点帮助程序和模型 ID 规范化帮助程序 | - | `plugin-sdk/provider-catalog-shared` | 共享提供商目录帮助程序 | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`buildManifestModelProviderConfig`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置帮助程序 | - | `plugin-sdk/provider-http` | 提供商 HTTP 帮助程序 | 通用提供商 HTTP/端点能力帮助程序，包括音频转录 multipart 表单帮助程序 | - | `plugin-sdk/provider-web-fetch` | 提供商 Web 抓取帮助程序 | Web 抓取提供商注册/缓存帮助程序 | - | `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 清理 + 诊断，以及 xAI 兼容帮助程序，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | 提供商用量帮助程序 | `fetchClaudeUsage`、`fetchGeminiUsage`、`fetchGithubCopilotUsage` 和其他提供商用量帮助程序 | - | `plugin-sdk/provider-stream` | 提供商流包装器帮助程序 | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器帮助程序 | - | `plugin-sdk/provider-transport-runtime` | 提供商传输帮助程序 | 原生提供商传输帮助程序，例如带保护的 fetch、传输消息转换和可写传输事件流 | + | `plugin-sdk/temp-path` | 临时路径助手 | 共享临时下载路径助手 | + | `plugin-sdk/logging-core` | 日志助手 | 子系统 logger 和脱敏助手 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格助手 | Markdown 表格模式助手 | + | `plugin-sdk/reply-payload` | 消息回复类型 | 回复 payload 类型 | + | `plugin-sdk/provider-setup` | 精选本地/自托管提供商设置助手 | 自托管提供商发现/配置助手 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容自托管提供商设置助手 | 相同的自托管提供商发现/配置助手 | + | `plugin-sdk/provider-auth-runtime` | 提供商运行时认证助手 | 运行时 API 密钥解析助手 | + | `plugin-sdk/provider-auth-api-key` | 提供商 API 密钥设置助手 | API 密钥新手引导/profile 写入助手 | + | `plugin-sdk/provider-auth-result` | 提供商认证结果助手 | 标准 OAuth 认证结果构建器 | + | `plugin-sdk/provider-auth-login` | 提供商交互式登录助手 | 共享交互式登录助手 | + | `plugin-sdk/provider-selection-runtime` | 提供商选择助手 | 已配置或自动提供商选择，以及原始提供商配置合并 | + | `plugin-sdk/provider-env-vars` | 提供商环境变量助手 | 提供商认证环境变量查找助手 | + | `plugin-sdk/provider-model-shared` | 共享提供商模型/replay 助手 | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、提供商端点助手和模型 ID 规范化助手 | + | `plugin-sdk/provider-catalog-shared` | 共享提供商目录助手 | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`buildManifestModelProviderConfig`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置助手 | + | `plugin-sdk/provider-http` | 提供商 HTTP 助手 | 通用提供商 HTTP/端点能力助手，包括音频转写 multipart 表单助手 | + | `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 清理 + 诊断，以及 xAI 兼容助手，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | 提供商用量助手 | `fetchClaudeUsage`、`fetchGeminiUsage`、`fetchGithubCopilotUsage` 和其他提供商用量助手 | + | `plugin-sdk/provider-stream` | 提供商流包装器助手 | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享 Anthropic/Bedrock/DeepSeek V4/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` | 共享媒体帮助程序 | 媒体抓取/转换/存储帮助程序、基于 ffprobe 的视频尺寸探测，以及媒体载荷构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成帮助程序 | 用于图像/视频/音乐生成的共享故障转移帮助程序、候选项选择和缺失模型消息 | - | `plugin-sdk/media-understanding` | 媒体理解帮助程序 | 媒体理解提供商类型，以及面向提供商的图像/音频帮助程序导出 | - | `plugin-sdk/text-runtime` | 共享文本帮助程序 | 对智能体可见文本进行剥离、Markdown 渲染/分块/表格帮助程序、脱敏帮助程序、指令标签帮助程序、安全文本实用工具，以及相关文本/日志帮助程序 | - | `plugin-sdk/text-chunking` | 文本分块帮助程序 | 出站文本分块帮助程序 | - | `plugin-sdk/speech` | 语音帮助程序 | 语音提供商类型，以及面向提供商的指令、注册表、验证帮助程序和 OpenAI 兼容 TTS 构建器 | + | `plugin-sdk/media-runtime` | 共享媒体助手 | 媒体获取/转换/存储助手、由 ffprobe 支持的视频尺寸探测，以及媒体 payload 构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成助手 | 图像/视频/音乐生成的共享故障转移助手、候选选择和缺失模型提示 | + | `plugin-sdk/media-understanding` | 媒体理解助手 | 媒体理解提供商类型，以及面向提供商的图像/音频助手导出 | + | `plugin-sdk/text-runtime` | 共享文本助手 | Assistant 可见文本剥离、Markdown 渲染/分块/表格助手、脱敏助手、指令标签助手、安全文本工具，以及相关文本/日志助手 | + | `plugin-sdk/text-chunking` | 文本分块助手 | 出站文本分块助手 | + | `plugin-sdk/speech` | 语音助手 | 语音提供商类型，以及面向提供商的指令、注册表、验证助手和 OpenAI 兼容 TTS 构建器 | | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转录帮助程序 | 提供商类型、注册表帮助程序和共享 WebSocket 会话帮助程序 | - | `plugin-sdk/realtime-voice` | 实时语音帮助程序 | 提供商类型、注册表/解析帮助程序和桥接会话帮助程序 | - | `plugin-sdk/image-generation` | 图像生成帮助程序 | 图像生成提供商类型，以及图像资产/数据 URL 帮助程序和 OpenAI 兼容图像提供商构建器 | - | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、凭证和注册表帮助程序 | - | `plugin-sdk/music-generation` | 音乐生成帮助程序 | 音乐生成提供商/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移帮助程序、提供商查找和模型引用解析 | - | `plugin-sdk/video-generation` | 视频生成帮助程序 | 视频生成提供商/请求/结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移帮助程序、提供商查找和模型引用解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复帮助程序 | 交互式回复载荷规范化/化简 | - | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄渠道配置 schema 原语 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入帮助程序 | 渠道配置写入授权帮助程序 | + | `plugin-sdk/realtime-transcription` | 实时转写助手 | 提供商类型、注册表助手和共享 WebSocket 会话助手 | + | `plugin-sdk/realtime-voice` | 实时语音助手 | 提供商类型、注册表/解析助手和桥接会话助手 | + | `plugin-sdk/image-generation` | 图像生成助手 | 图像生成提供商类型，以及图像资产/data URL 助手和 OpenAI 兼容图像提供商构建器 | + | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表助手 | + | `plugin-sdk/music-generation` | 音乐生成助手 | 音乐生成提供商/请求/结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移助手、提供商查找和模型引用解析 | + | `plugin-sdk/video-generation` | 视频生成助手 | 视频生成提供商/请求/结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移助手、提供商查找和模型引用解析 | + | `plugin-sdk/interactive-runtime` | 交互式回复助手 | 交互式回复 payload 规范化/化简 | + | `plugin-sdk/channel-config-primitives` | 渠道配置基元 | 窄渠道配置 schema 基元 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入助手 | 渠道配置写入授权助手 | | `plugin-sdk/channel-plugin-common` | 共享渠道前导 | 共享渠道插件前导导出 | - | `plugin-sdk/channel-status` | 渠道 Status 帮助程序 | 共享渠道 Status 快照/摘要帮助程序 | - | `plugin-sdk/allowlist-config-edit` | 允许列表配置帮助程序 | 允许列表配置编辑/读取帮助程序 | - | `plugin-sdk/group-access` | 群组访问帮助程序 | 共享群组访问决策帮助程序 | - | `plugin-sdk/direct-dm` | 直接私信帮助程序 | 共享直接私信凭证/防护帮助程序 | - | `plugin-sdk/extension-shared` | 共享插件帮助程序 | 被动渠道/Status 和环境代理帮助程序原语 | - | `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-host-engine-foundation` | Memory 主机 foundation 引擎 | Memory 主机 foundation 引擎导出 | - | `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 主机密钥帮助程序 | Memory 主机密钥帮助程序 | - | `plugin-sdk/memory-core-host-events` | Memory 主机事件日志帮助程序 | Memory 主机事件日志帮助程序 | - | `plugin-sdk/memory-core-host-status` | Memory 主机 Status 帮助程序 | Memory 主机 Status 帮助程序 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时 | Memory 主机 CLI 运行时帮助程序 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时 | Memory 主机核心运行时帮助程序 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件/运行时帮助程序 | Memory 主机文件/运行时帮助程序 | - | `plugin-sdk/memory-host-core` | Memory 主机核心运行时别名 | 面向供应商中立的 Memory 主机核心运行时帮助程序别名 | - | `plugin-sdk/memory-host-events` | Memory 主机事件日志别名 | 面向供应商中立的 Memory 主机事件日志帮助程序别名 | - | `plugin-sdk/memory-host-files` | Memory 主机文件/运行时别名 | 面向供应商中立的 Memory 主机文件/运行时帮助程序别名 | - | `plugin-sdk/memory-host-markdown` | 托管 Markdown 帮助程序 | 面向 Memory 相邻插件的共享托管 Markdown 帮助程序 | - | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索门面 | 惰性活跃 Memory 搜索管理器运行时门面 | - | `plugin-sdk/memory-host-status` | Memory 主机 Status 别名 | 面向供应商中立的 Memory 主机 Status 帮助程序别名 | - | `plugin-sdk/testing` | 测试实用工具 | 旧版宽兼容 barrel；优先使用聚焦测试子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/channel-target-testing`、`plugin-sdk/test-env` 和 `plugin-sdk/test-fixtures` | + | `plugin-sdk/channel-status` | 渠道 Status 助手 | 共享渠道 Status 快照/摘要助手 | + | `plugin-sdk/allowlist-config-edit` | 允许列表配置助手 | 允许列表配置编辑/读取助手 | + | `plugin-sdk/group-access` | 群组访问助手 | 共享群组访问决策助手 | + | `plugin-sdk/direct-dm` | 直接私信助手 | 共享直接私信认证/保护助手 | + | `plugin-sdk/extension-shared` | 共享扩展助手 | 被动渠道/Status 和环境代理助手基元 | + | `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 引擎运行时 facade | Memory 索引/搜索运行时 facade | + | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation 引擎 | Memory host foundation 引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 引擎 | Memory embedding 契约、注册表访问、本地提供商，以及通用批处理/远程助手；具体远程提供商位于其所属插件中 | + | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD 引擎 | Memory host QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage 引擎 | Memory host storage 引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | Memory host multimodal 助手 | Memory host multimodal 助手 | + | `plugin-sdk/memory-core-host-query` | Memory host query 助手 | Memory host query 助手 | + | `plugin-sdk/memory-core-host-secret` | Memory host secret 助手 | Memory host secret 助手 | + | `plugin-sdk/memory-core-host-events` | Memory host event journal 助手 | Memory host event journal 助手 | + | `plugin-sdk/memory-core-host-status` | Memory host status 助手 | Memory host status 助手 | + | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时 | Memory host CLI 运行时助手 | + | `plugin-sdk/memory-core-host-runtime-core` | Memory host core 运行时 | Memory host core 运行时助手 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时助手 | Memory host 文件/运行时助手 | + | `plugin-sdk/memory-host-core` | Memory host core 运行时别名 | 面向 vendor 中立的 memory host core 运行时助手别名 | + | `plugin-sdk/memory-host-events` | Memory host event journal 别名 | 面向 vendor 中立的 memory host event journal 助手别名 | + | `plugin-sdk/memory-host-files` | Memory host 文件/运行时别名 | 面向 vendor 中立的 memory host 文件/运行时助手别名 | + | `plugin-sdk/memory-host-markdown` | 托管 Markdown 助手 | 面向 memory 相邻插件的共享托管 Markdown 助手 | + | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索 facade | 惰性活跃 Memory 搜索管理器运行时 facade | + | `plugin-sdk/memory-host-status` | Memory host status 别名 | 面向 vendor 中立的 memory host status 助手别名 | + | `plugin-sdk/testing` | 测试工具 | 旧版宽兼容 barrel；优先使用聚焦测试子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/channel-target-testing`、`plugin-sdk/test-env` 和 `plugin-sdk/test-fixtures` | -此表有意只列出常见迁移子集，而不是完整的 SDK -表面。完整的 200+ 入口点列表位于 +此表有意只列出常见迁移子集，而不是完整 SDK +表面。200+ 个入口点的完整列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 -保留的内置插件辅助接缝已从公开 SDK -导出映射中移除，明确记录的兼容性门面除外，例如为已发布的 -`@openclaw/discord@2026.3.13` 包保留的已弃用 -`plugin-sdk/discord` 垫片。所有者专属辅助工具位于对应所有者的 -插件包内；共享宿主行为应通过通用 SDK -契约传递，例如 `plugin-sdk/gateway-runtime`、`plugin-sdk/security-runtime` +预留的内置插件辅助接缝已从公共 SDK +导出映射中移除，只有明确记录的兼容性门面除外，例如保留给已发布 +`@openclaw/discord@2026.3.13` 包使用的已弃用 +`plugin-sdk/discord` 垫片。所有者特定的辅助函数位于其所属 +插件包内部；共享宿主行为应通过通用 SDK +契约迁移，例如 `plugin-sdk/gateway-runtime`、`plugin-sdk/security-runtime` 和 `plugin-sdk/plugin-config-runtime`。 使用与任务匹配的最窄导入。如果找不到某个导出， -请检查 `src/plugin-sdk/` 中的源码，或询问维护者应由哪个通用契约 +请查看 `src/plugin-sdk/` 中的源码，或询问维护者应由哪个通用契约 拥有它。 -## 当前弃用项 +## 活跃弃用项 -适用于插件 SDK、提供商契约、运行时表面和清单的更窄弃用项。 -每一项目前仍可使用，但会在未来的主版本中移除。 -每个条目下方都会把旧 API 映射到其规范替代项。 +适用于插件 SDK、提供商契约、运行时表面和清单的更窄弃用项。每一项目前仍可使用，但会在未来的主版本中移除。每个条目下方都会把旧 API 映射到其规范替代项。 - **旧 (`openclaw/plugin-sdk/command-auth`)**：`buildCommandsMessage`, + **旧（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`。 - **新 (`openclaw/plugin-sdk/command-status`)**：相同签名、相同 + **新（`openclaw/plugin-sdk/command-status`）**：相同签名、相同 导出，只是从更窄的子路径导入。`command-auth` - 会将它们作为兼容存根重新导出。 + 会将它们重新导出为兼容性存根。 ```typescript // Before @@ -505,59 +493,64 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - + **旧**：来自 `openclaw/plugin-sdk/channel-inbound` 或 `openclaw/plugin-sdk/channel-mention-gating` 的 `resolveInboundMentionRequirement({ facts, policy })` 和 `shouldDropInboundForMention(...)`。 - **新**：`resolveInboundMentionDecision({ facts, policy })`，返回一个 - 单一决策对象，而不是两次拆分调用。 + **新**：`resolveInboundMentionDecision({ facts, policy })`，返回单个 + 决策对象，而不是两个分离调用。 - 下游渠道插件（Slack、Discord、Matrix、MS Teams）已经完成切换。 + 下游渠道插件（Slack、Discord、Matrix、MS Teams）已经 + 切换。 - + `openclaw/plugin-sdk/channel-runtime` 是面向旧版 渠道插件的兼容性垫片。不要在新代码中导入它；请使用 - `openclaw/plugin-sdk/channel-runtime-context` 注册运行时 + `openclaw/plugin-sdk/channel-runtime-context` 来注册运行时 对象。 - `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助工具 - 会与原始 “actions” 渠道导出一起弃用。请改为通过语义化的 - `presentation` 表面暴露能力：渠道插件声明它们渲染什么 - （卡片、按钮、选择器），而不是声明它们接受哪些原始动作名称。 + `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助函数会 + 与原始 “actions” 渠道导出一起弃用。请改为通过语义化的 + `presentation` 表面公开能力，渠道插件声明它们会渲染什么 + （卡片、按钮、选择器），而不是声明它们接受哪些原始 + 动作名称。 - + **旧**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` 工厂。 **新**：直接在提供商插件上实现 `createTool(...)`。 - OpenClaw 不再需要 SDK 辅助工具来注册工具包装器。 + OpenClaw 不再需要 SDK 辅助函数来注册工具包装器。 - - **旧**：使用 `formatInboundEnvelope(...)`（以及 - `ChannelMessageForAgent.channelEnvelope`）从入站渠道消息构建一个扁平的明文提示词 + + **旧**：`formatInboundEnvelope(...)`（以及 + `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建扁平的纯文本提示词 信封。 - **新**：`BodyForAgent` 加结构化用户上下文块。渠道插件 - 将路由元数据（线程、主题、回复目标、回应）作为类型化字段附加， - 而不是把它们拼接到提示词字符串中。`formatAgentEnvelope(...)` - 辅助工具仍支持用于合成面向助手的信封，但入站明文信封正在 - 淘汰。 + **新**：`BodyForAgent` 加结构化用户上下文块。渠道 + 插件会把路由元数据（线程、主题、回复对象、反应）作为 + 类型化字段附加，而不是将它们拼接到提示词字符串中。 + `formatAgentEnvelope(...)` 辅助函数仍支持用于合成的 + 面向助手的信封，但入站纯文本信封正在 + 退出。 受影响区域：`inbound_claim`、`message_received`，以及任何后处理 - `channelEnvelope` 文本的自定义渠道插件。 + `channelEnvelope` 文本的自定义 + 渠道插件。 - 四个发现类型别名现在是目录时代类型之上的薄包装： + 四个发现类型别名现在是 + 目录时代类型的薄包装： | 旧别名 | 新类型 | | ------------------------- | ------------------------- | @@ -566,7 +559,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `ProviderDiscoveryResult` | `ProviderCatalogResult` | | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - 另外还有旧版 `ProviderCapabilities` 静态包。提供商插件 + 另外还有旧版 `ProviderCapabilities` 静态集合，提供商插件 应使用显式提供商钩子，例如 `buildReplayPolicy`、 `normalizeToolSchemas` 和 `wrapStreamFn`，而不是静态对象。 @@ -577,22 +570,23 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 `isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)` 和 `resolveDefaultThinkingLevel(ctx)`。 - **新**：单个 `resolveThinkingProfile(ctx)`，返回一个 - `ProviderThinkingProfile`，其中包含规范 `id`、可选 `label` 和 - 排序后的级别列表。OpenClaw 会按配置文件排名自动降级陈旧的已存储值。 + **新**：单个 `resolveThinkingProfile(ctx)`，返回包含规范 `id`、可选 + `label` 和已排序级别列表的 + `ProviderThinkingProfile`。OpenClaw 会按配置档 + 排名自动降级过期的已存储值。 - 实现一个钩子即可，而不是三个。旧版钩子在弃用窗口期间仍可工作， - 但不会与配置文件结果组合。 + 实现一个钩子即可，而不是三个。旧版钩子在 + 弃用窗口期间仍会继续工作，但不会与配置档结果组合。 - **旧**：实现 `resolveExternalOAuthProfiles(...)`，但不在插件清单中 - 声明提供商。 + **旧**：实现 `resolveExternalOAuthProfiles(...)`，但不在 + 插件清单中声明提供商。 **新**：在插件清单中声明 `contracts.externalAuthProviders` - **并且**实现 `resolveExternalAuthProfiles(...)`。旧的“认证 - 回退”路径会在运行时发出警告，并将被移除。 + **并且**实现 `resolveExternalAuthProfiles(...)`。旧的 “auth + fallback” 路径会在运行时发出警告，并将被移除。 ```json { @@ -607,11 +601,13 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 **旧**清单字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 - **新**：在清单中将相同的环境变量查找镜像到 `setup.providers[].envVars`。 - 这会把设置/Status 环境元数据整合到一个位置，并避免仅为回答 - 环境变量查找而启动插件运行时。 + **新**：在清单中把相同的环境变量查找映射到 `setup.providers[].envVars`。 + 这会将设置/Status 环境元数据集中到一个 + 位置，并避免仅为回答环境变量 + 查找而启动插件运行时。 - `providerAuthEnvVars` 会通过兼容适配器继续支持，直到弃用窗口关闭。 + `providerAuthEnvVars` 会通过兼容性适配器继续支持， + 直到弃用窗口关闭。 @@ -621,10 +617,10 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 `api.registerMemoryFlushPlan(...)`、 `api.registerMemoryRuntime(...)`。 - **新**：在内存状态 API 上调用一次： + **新**：在 memory-state API 上进行一次调用： `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。 - 相同槽位，单次注册调用。增量 Memory 辅助工具 + 相同槽位，单次注册调用。增量 Memory 辅助函数 （`registerMemoryPromptSupplement`、`registerMemoryCorpusSupplement`、 `registerMemoryEmbeddingProvider`）不受影响。 @@ -638,17 +634,19 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | - 运行时方法 `readSession` 已弃用，改用 `getSessionMessages`。 - 签名相同；旧方法会调用新方法。 + 运行时方法 `readSession` 已弃用，推荐使用 + `getSessionMessages`。签名相同；旧方法会转调用 + 新方法。 - **旧**：`runtime.tasks.flow`（单数）返回一个实时任务流访问器。 + **旧**：`runtime.tasks.flow`（单数）返回实时任务流访问器。 - **新**：`runtime.tasks.managedFlows` 为需要从流中创建、更新、取消或运行 - 子任务的插件保留托管 TaskFlow 变更运行时。当插件只需要基于 DTO 的读取时， - 请使用 `runtime.tasks.flows`。 + **新**：`runtime.tasks.managedFlows` 为创建、更新、取消或从 + 流运行子任务的插件保留托管 TaskFlow 变更 + 运行时。当插件只需要基于 DTO 的读取时，请使用 + `runtime.tasks.flows`。 ```typescript // Before @@ -659,17 +657,18 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - - 已在上文“如何迁移 → 将 Pi 工具结果扩展迁移到中间件”中介绍。 - 此处为完整性补充：已移除的 Pi 专用 - `api.registerEmbeddedExtensionFactory(...)` 路径替换为 - `api.registerAgentToolResultMiddleware(...)`，并在 - `contracts.agentToolResultMiddleware` 中提供显式运行时列表。 + + 已在上方“如何迁移 → 将 Pi 工具结果插件迁移到 + 中间件”中说明。这里为完整性再次列出：已移除的仅限 Pi 的 + `api.registerEmbeddedExtensionFactory(...)` 路径由 + `api.registerAgentToolResultMiddleware(...)` 替代，并在 + `contracts.agentToolResultMiddleware` 中提供显式运行时 + 列表。 从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` 现在是 - `OpenClawConfig` 的一行别名。请优先使用规范名称。 + `OpenClawConfig` 的单行别名。请优先使用规范名称。 ```typescript // Before @@ -682,20 +681,20 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 -扩展级弃用项（位于 `extensions/` 下的内置渠道/提供商插件中） -会在各自的 `api.ts` 和 `runtime-api.ts` 桶文件内跟踪。 -它们不影响第三方插件契约，因此未在此列出。如果你直接使用某个内置插件的本地桶文件， -请在升级前阅读该桶文件中的弃用注释。 +插件级弃用项（位于 `extensions/` 下的内置渠道/提供商插件内部） +会在各自的 `api.ts` 和 `runtime-api.ts` +桶中跟踪。它们不影响第三方插件契约，因此不在此处列出。如果你直接使用某个内置插件的本地桶，请在升级前阅读该桶中的 +弃用注释。 ## 移除时间线 -| 时间 | 会发生什么 | +| 时间 | 会发生什么 | | ---------------------- | ----------------------------------------------------------------------- | -| **现在** | 已弃用表面会发出运行时警告 | -| **下一个主版本** | 已弃用表面将被移除；仍在使用它们的插件会失败 | +| **现在** | 已弃用表面会发出运行时警告 | +| **下一个主版本** | 已弃用表面将被移除；仍在使用它们的插件将失败 | -所有核心插件都已经迁移。外部插件应在下一个主版本发布前完成迁移。 +所有核心插件都已完成迁移。外部插件应在下一个主版本之前迁移。 ## 临时抑制警告 @@ -706,13 +705,13 @@ OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -这是一个临时逃生口，不是永久解决方案。 +这是临时逃生口，不是永久解决方案。 -## 相关 +## 相关内容 - [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 -- [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析 +- [插件内部机制](/zh-CN/plugins/architecture) — 架构深度解析 - [插件清单](/zh-CN/plugins/manifest) — 清单架构参考 diff --git a/docs/zh-CN/plugins/sdk-subpaths.md b/docs/zh-CN/plugins/sdk-subpaths.md index 4a6f17683..d62f84da9 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -1,199 +1,201 @@ --- read_when: - - 为插件导入选择合适的 plugin-sdk 子路径 - - 审查内置插件子路径和辅助接口 + - 为插件导入选择正确的 plugin-sdk 子路径 + - 审计内置插件子路径和辅助接口 summary: 插件 SDK 子路径目录：哪些导入位于何处，按领域分组 title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-29T13:54:37Z" + generated_at: "2026-04-29T15:39:40Z" model: gpt-5.5 provider: openai - source_hash: 02c86fd840e7f68ea86d7b7710278a942e4f0c69154c17393d449790e5474a4f + source_hash: a2b2cb0880317d4bd3fa7c1803afc119d500b3f8ae3c5d444839c9d4d7633b80 source_path: plugins/sdk-subpaths.md workflow: 16 --- - 插件 SDK 以 `openclaw/plugin-sdk/` 下的一组窄子路径形式公开。 - 本页按用途分组列出常用子路径。生成的 200 多个子路径完整列表位于 `scripts/lib/plugin-sdk-entrypoints.json`； - 保留的内置插件辅助子路径也会出现在其中，但除非某个文档页面明确推广，否则它们属于实现细节。 - 维护者可以使用 `pnpm plugins:boundary-report:summary` 审计活跃的保留辅助子路径； - 未使用的保留辅助导出会让 CI 报告失败，而不是作为休眠兼容性债务留在公共 SDK 中。 + 插件 SDK 以 `openclaw/plugin-sdk/` 下的一组窄子路径形式暴露。 + 本页按用途对常用子路径进行分组编目。生成的 + 200+ 个子路径完整列表位于 `scripts/lib/plugin-sdk-entrypoints.json`； + 保留的内置插件帮助器子路径会出现在其中，但除非某个文档页面明确推荐， + 否则它们属于实现细节。维护者可以使用 `pnpm plugins:boundary-report:summary` + 审计当前活跃的保留帮助器子路径；未使用的保留帮助器导出会使 CI 报告失败， + 而不是作为休眠的兼容性债务留在公共 SDK 中。 插件编写指南见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 - | 子路径 | 主要导出 | + | 子路径 | 关键导出 | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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/testing` | 用于旧版插件测试的宽兼容性桶；新的插件测试应优先使用聚焦的测试子路径 | - | `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小 `OpenClawPluginApi` mock 构建器 | - | `plugin-sdk/agent-runtime-test-contracts` | 用于认证配置文件、投递抑制、回退分类、工具钩子、提示词覆盖层、schema 和转录修复的原生 agent-runtime 适配器契约夹具 | - | `plugin-sdk/channel-test-helpers` | 渠道账号生命周期、目录、发送配置、运行时 mock、钩子、内置渠道入口、信封时间戳、配对回复，以及通用渠道契约测试辅助工具 | - | `plugin-sdk/channel-target-testing` | 共享的渠道目标解析错误用例测试套件 | - | `plugin-sdk/plugin-test-contracts` | 插件注册、包清单、公共产物、运行时 API、导入副作用和直接导入契约辅助工具 | - | `plugin-sdk/plugin-test-runtime` | 用于测试的插件运行时、注册表、提供商注册、设置向导和运行时任务流夹具 | - | `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、设备发现、新手引导、目录、媒体能力、重放策略、实时 STT 现场音频、Web 搜索/抓取，以及向导契约辅助工具 | - | `plugin-sdk/provider-http-test-mocks` | 用于测试 `plugin-sdk/provider-http` 的提供商测试的可选 Vitest HTTP/认证 mock | - | `plugin-sdk/test-env` | 测试环境、fetch/网络、一次性 HTTP 服务器、传入请求、现场测试、临时文件系统和时间控制夹具 | - | `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、skill、智能体消息、系统事件、模块重载、内置插件路径、终端、分块、认证令牌和类型化用例测试夹具 | - | `plugin-sdk/test-node-mocks` | 用于 Vitest `vi.mock("node:*")` 工厂内部的聚焦 Node 内置 mock 辅助工具 | - | `plugin-sdk/migration` | 迁移提供商条目辅助工具，例如 `createMigrationItem`、原因常量、条目 Status 标记、脱敏辅助工具和 `summarizeMigrationItems` | - | `plugin-sdk/migration-runtime` | 运行时迁移辅助工具，例如 `copyMigrationFileItem` 和 `writeMigrationReport` | + | `plugin-sdk/testing` | 面向旧版插件测试的宽兼容性 barrel；新的扩展测试应优先使用聚焦的测试子路径 | + | `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小 `OpenClawPluginApi` mock 构建器 | + | `plugin-sdk/agent-runtime-test-contracts` | 用于鉴权配置、递送抑制、回退分类、工具钩子、提示词覆盖层、schema 和转录修复的原生智能体运行时适配器契约夹具 | + | `plugin-sdk/channel-test-helpers` | 渠道账号生命周期、目录、发送配置、运行时 mock、钩子、内置渠道入口、信封时间戳、配对回复和通用渠道契约测试帮助器 | + | `plugin-sdk/channel-target-testing` | 共享的渠道目标解析错误用例测试套件 | + | `plugin-sdk/plugin-test-contracts` | 插件注册、包清单、公共产物、运行时 API、导入副作用和直接导入契约帮助器 | + | `plugin-sdk/plugin-test-runtime` | 用于测试的插件运行时、注册表、提供商注册、设置向导和运行时任务流夹具 | + | `plugin-sdk/provider-test-contracts` | 提供商运行时、鉴权、设备发现、新手引导、目录、媒体能力、重放策略、实时 STT 实时音频、Web 搜索/抓取和向导契约帮助器 | + | `plugin-sdk/provider-http-test-mocks` | 面向会执行 `plugin-sdk/provider-http` 的提供商测试的可选 Vitest HTTP/鉴权 mock | + | `plugin-sdk/test-env` | 测试环境、fetch/网络、一次性 HTTP 服务器、传入请求、实时测试、临时文件系统和时间控制夹具 | + | `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、skill、智能体消息、系统事件、模块重载、内置插件路径、终端、分块、鉴权令牌和类型化用例测试夹具 | + | `plugin-sdk/test-node-mocks` | 用于 Vitest `vi.mock("node:*")` 工厂内部的聚焦 Node 内置 mock 帮助器 | + | `plugin-sdk/migration` | 迁移提供商条目帮助器，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏帮助器和 `summarizeMigrationItems` | + | `plugin-sdk/migration-runtime` | 运行时迁移帮助器，例如 `copyMigrationFileItem` 和 `writeMigrationReport` | - | 子路径 | 主要导出 | + | 子路径 | 关键导出 | | --- | --- | | `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 提示、设置 Status 构建器 | + | `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` | 多账号配置/操作门控辅助工具、默认账号回退辅助工具 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、账号 ID 规范化辅助工具 | - | `plugin-sdk/account-resolution` | 账号查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄账号列表/账号操作辅助工具 | + | `plugin-sdk/account-core` | 多账号配置/操作门控帮助器、默认账号回退帮助器 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`，账号 ID 规范化帮助器 | + | `plugin-sdk/account-resolution` | 账号查找 + 默认回退帮助器 | + | `plugin-sdk/account-helpers` | 窄账号列表/账号操作帮助器 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` | - | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter`, `resolveChannelDmAccess`, `resolveChannelDmAllowFrom`, `resolveChannelDmPolicy`, `normalizeChannelDmPolicy`, `normalizeLegacyDmAliases` | | `plugin-sdk/channel-config-schema` | 共享渠道配置 schema 原语和通用构建器 | - | `plugin-sdk/bundled-channel-config-schema` | 仅供维护的内置插件使用的内置 OpenClaw 渠道配置 schema | + | `plugin-sdk/bundled-channel-config-schema` | 仅面向受维护内置插件的内置 OpenClaw 渠道配置 schema | | `plugin-sdk/channel-config-schema-legacy` | 内置渠道配置 schema 的已弃用兼容性别名 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/验证辅助工具，带有内置契约回退 | - | `plugin-sdk/command-gating` | 窄命令授权门控辅助工具 | + | `plugin-sdk/telegram-command-config` | 带内置契约回退的 Telegram 自定义命令规范化/验证帮助器 | + | `plugin-sdk/command-gating` | 窄命令授权门控帮助器 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, `createChannelRunQueue`，草稿流生命周期/终结辅助工具 | - | `plugin-sdk/inbound-envelope` | 共享入站路由 + 信封构建器辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 | - | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 | - | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 | - | `plugin-sdk/outbound-send-deps` | 面向渠道适配器的轻量出站发送依赖查找 | - | `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` | 共享渠道 Status 快照/摘要辅助工具 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, `createChannelRunQueue`，草稿流生命周期/完成帮助器 | + | `plugin-sdk/inbound-envelope` | 共享的入站路由 + 信封构建器帮助器 | + | `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录并分发帮助器 | + | `plugin-sdk/messaging-targets` | 目标解析/匹配帮助器 | + | `plugin-sdk/outbound-media` | 共享的出站媒体加载帮助器 | + | `plugin-sdk/outbound-send-deps` | 渠道适配器的轻量出站发送依赖查找 | + | `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` | 共享渠道 Status 快照/摘要帮助器 | | `plugin-sdk/channel-config-primitives` | 窄渠道配置 schema 原语 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入授权帮助器 | | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 | - | `plugin-sdk/allowlist-config-edit` | Allowlist 配置编辑/读取辅助工具 | - | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 共享直接私信认证/保护辅助工具 | - | `plugin-sdk/discord` | 已弃用的 Discord 兼容性门面，用于已发布的 `@openclaw/discord@2026.3.13` 和受跟踪的所有者兼容性；新插件应使用通用渠道 SDK 子路径 | - | `plugin-sdk/telegram-account` | 已弃用的 Telegram 账号解析兼容性门面，用于受跟踪的所有者兼容性；新插件应使用注入的运行时辅助工具或通用渠道 SDK 子路径 | - | `plugin-sdk/interactive-runtime` | 语义消息呈现、投递和旧版交互式回复辅助工具。见 [Message Presentation](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 用于入站防抖、提及匹配、提及策略辅助工具和信封辅助工具的兼容性桶 | - | `plugin-sdk/channel-inbound-debounce` | 窄入站防抖辅助工具 | - | `plugin-sdk/channel-mention-gating` | 窄提及策略、提及标记和提及文本辅助工具，不包含更宽的入站运行时表面 | - | `plugin-sdk/channel-envelope` | 窄入站信封格式化辅助工具 | - | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 | - | `plugin-sdk/channel-logging` | 用于入站丢弃和 typing/ack 失败的渠道日志辅助工具 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取帮助器 | + | `plugin-sdk/group-access` | 共享群组访问决策帮助器 | + | `plugin-sdk/direct-dm` | 共享直接私信鉴权/守卫帮助器 | + | `plugin-sdk/discord` | 面向已发布的 `@openclaw/discord@2026.3.13` 和跟踪所有者兼容性的已弃用 Discord 兼容性 facade；新插件应使用通用渠道 SDK 子路径 | + | `plugin-sdk/telegram-account` | 面向跟踪所有者兼容性的已弃用 Telegram 账号解析兼容性 facade；新插件应使用注入的运行时帮助器或通用渠道 SDK 子路径 | + | `plugin-sdk/interactive-runtime` | 语义消息呈现、递送和旧版交互式回复帮助器。见 [Message Presentation](/zh-CN/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | 入站防抖、提及匹配、提及策略帮助器和信封帮助器的兼容性 barrel | + | `plugin-sdk/channel-inbound-debounce` | 窄入站防抖帮助器 | + | `plugin-sdk/channel-mention-gating` | 不包含更宽入站运行时表面的窄提及策略、提及标记和提及文本帮助器 | + | `plugin-sdk/channel-envelope` | 窄入站信封格式化帮助器 | + | `plugin-sdk/channel-location` | 渠道位置上下文和格式化帮助器 | + | `plugin-sdk/channel-logging` | 入站丢弃和 typing/ack 失败的渠道日志帮助器 | | `plugin-sdk/channel-send-result` | 回复结果类型 | - | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 | - | `plugin-sdk/channel-route` | 共享路由规范化、解析器驱动的目标解析、线程 ID 字符串化、去重/紧凑路由键、已解析目标类型，以及路由/目标比较辅助工具 | - | `plugin-sdk/channel-targets` | 目标解析辅助工具；路由比较调用方应使用 `plugin-sdk/channel-route` | + | `plugin-sdk/channel-actions` | 渠道消息操作帮助器，以及为插件兼容性保留的已弃用原生 schema 帮助器 | + | `plugin-sdk/channel-route` | 共享路由规范化、解析器驱动的目标解析、线程 ID 字符串化、去重/紧凑路由键、已解析目标类型和路由/目标比较帮助器 | + | `plugin-sdk/channel-targets` | 目标解析帮助器；路由比较调用方应使用 `plugin-sdk/channel-route` | | `plugin-sdk/channel-contract` | 渠道契约类型 | | `plugin-sdk/channel-feedback` | 反馈/reaction 接线 | - | `plugin-sdk/channel-secret-runtime` | 窄 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret 目标类型 | + | `plugin-sdk/channel-secret-runtime` | 窄密钥契约帮助器，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` 和密钥目标类型 | | 子路径 | 主要导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | 支持的 LM Studio 提供商门面，用于设置、目录发现和运行时模型准备 | - | `plugin-sdk/lmstudio-runtime` | 支持的 LM Studio 运行时门面，用于本地服务器默认值、模型发现、请求标头和已加载模型辅助工具 | - | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管提供商的设置辅助工具 | - | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API 密钥解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/配置文件写入辅助工具，例如 `upsertApiKeyProfile` | + | `plugin-sdk/lmstudio` | 受支持的 LM Studio 提供商门面，用于设置、目录发现和运行时模型准备 | + | `plugin-sdk/lmstudio-runtime` | 受支持的 LM Studio 运行时门面，用于本地服务器默认值、模型发现、请求标头和已加载模型助手 | + | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置助手 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦于兼容 OpenAI 的自托管提供商设置助手 | + | `plugin-sdk/cli-backend` | CLI 后端默认值 + 看门狗常量 | + | `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API 密钥解析助手 | + | `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/配置文件写入助手，例如 `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | - | `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助工具 | - | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 | + | `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`、共享重放策略构建器、提供商端点辅助工具，以及模型 ID 规范化辅助工具，例如 `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, 共享重放策略构建器、提供商端点助手，以及模型 ID 规范化助手，例如 `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-runtime` | 提供商目录增强运行时钩子，以及用于契约测试的插件提供商注册表接缝 | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `buildManifestModelProviderConfig`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具、提供商 HTTP 错误，以及音频转录 multipart 表单辅助工具 | - | `plugin-sdk/provider-web-fetch-contract` | 精简的 Web 抓取配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Web 抓取提供商注册/缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的精简 Web 搜索配置/凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 精简的 Web 搜索配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及作用域凭证设置器/获取器 | - | `plugin-sdk/provider-web-search` | Web 搜索提供商注册/缓存/运行时辅助工具 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似工具 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | - | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的抓取、传输消息转换和可写传输事件流 | - | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 | - | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 | - | `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助工具 | + | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力助手、提供商 HTTP 错误，以及音频转录 multipart 表单助手 | + | `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 搜索配置/凭证助手 | + | `plugin-sdk/provider-web-search-contract` | 窄作用域的 Web 搜索配置/凭证契约助手，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及限定作用域的凭证设置器/获取器 | + | `plugin-sdk/provider-web-search` | Web 搜索提供商注册/缓存/运行时助手 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容助手，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似项 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, 流包装器类型，以及共享 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器助手 | + | `plugin-sdk/provider-transport-runtime` | 原生提供商传输助手，例如受保护的 fetch、传输消息转换和可写传输事件流 | + | `plugin-sdk/provider-onboard` | 新手引导配置补丁助手 | + | `plugin-sdk/global-singleton` | 进程本地单例/map/缓存助手 | + | `plugin-sdk/group-activation` | 窄作用域的群组激活模式和命令解析助手 | | 子路径 | 主要导出 | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具，包括动态参数菜单格式化、发送者授权辅助工具 | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`，命令注册表助手，包括动态参数菜单格式化、发送者授权助手 | | `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作认证辅助工具 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤器辅助工具 | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天操作认证助手 | + | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤器助手 | | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | - | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 面向热渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；当更精简的适配器/Gateway 网关接缝足够时优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账号绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | Exec/插件审批回复载荷辅助工具 | - | `plugin-sdk/approval-runtime` | Exec/插件审批载荷辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示辅助工具，例如 `formatApprovalDisplayPath` | - | `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助工具 | - | `plugin-sdk/channel-contract-testing` | 不包含宽泛测试 barrel 的精简渠道契约测试辅助工具 | - | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化，以及原生会话目标辅助工具 | - | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | - | `plugin-sdk/command-primitives-runtime` | 用于热渠道路径的轻量级命令文本谓词 | - | `plugin-sdk/command-surface` | 命令正文规范化和命令表面辅助工具 | + | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析助手 | + | `plugin-sdk/approval-handler-adapter-runtime` | 面向热渠道入口点的轻量级原生审批适配器加载助手 | + | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时助手；当更窄的适配器/Gateway 网关接缝足够时，优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定助手 | + | `plugin-sdk/approval-reply-runtime` | Exec/插件审批回复载荷助手 | + | `plugin-sdk/approval-runtime` | Exec/插件审批载荷助手、原生审批路由/运行时助手，以及结构化审批显示助手，例如 `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | 窄作用域的入站回复去重重置助手 | + | `plugin-sdk/channel-contract-testing` | 不含宽泛测试 barrel 的窄作用域渠道契约测试助手 | + | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化，以及原生会话目标助手 | + | `plugin-sdk/command-detection` | 共享命令检测助手 | + | `plugin-sdk/command-primitives-runtime` | 面向热渠道路径的轻量级命令文本谓词 | + | `plugin-sdk/command-surface` | 命令正文规范化和命令表面助手 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 渠道/插件密钥表面的精简密钥契约收集辅助工具 | - | `plugin-sdk/secret-ref-runtime` | 用于密钥契约/配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助工具 | - | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本脱敏、常量时间密钥比较，以及密钥收集辅助工具 | - | `plugin-sdk/ssrf-policy` | 主机允许列表和私有网络 SSRF 策略辅助工具 | - | `plugin-sdk/ssrf-dispatcher` | 不包含宽泛基础设施运行时表面的精简固定 dispatcher 辅助工具 | - | `plugin-sdk/ssrf-runtime` | 固定 dispatcher、SSRF 保护的抓取、SSRF 错误，以及 SSRF 策略辅助工具 | - | `plugin-sdk/secret-input` | 密钥输入解析辅助工具 | - | `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具，以及原始 websocket/body 强制转换 | - | `plugin-sdk/webhook-request-guards` | 请求正文大小/超时辅助工具 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道/插件密钥表面的窄作用域密钥契约收集助手 | + | `plugin-sdk/secret-ref-runtime` | 面向密钥契约/配置解析的窄作用域 `coerceSecretRef` 和 SecretRef 类型助手 | + | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本遮蔽、常量时间密钥比较和密钥收集助手 | + | `plugin-sdk/ssrf-policy` | 主机允许列表和专用网络 SSRF 策略助手 | + | `plugin-sdk/ssrf-dispatcher` | 不含宽泛基础设施运行时表面的窄作用域固定 dispatcher 助手 | + | `plugin-sdk/ssrf-runtime` | 固定 dispatcher、受 SSRF 保护的 fetch、SSRF 错误和 SSRF 策略助手 | + | `plugin-sdk/secret-input` | 密钥输入解析助手 | + | `plugin-sdk/webhook-ingress` | Webhook 请求/目标助手，以及原始 websocket/body 强制转换 | + | `plugin-sdk/webhook-request-guards` | 请求正文大小/超时助手 | - | 子路径 | 主要导出 | + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助函数 | - | `plugin-sdk/runtime-env` | 精简的运行时环境、日志记录器、超时、重试和退避辅助函数 | - | `plugin-sdk/browser-config` | 受支持的浏览器配置门面，用于规范化配置文件/默认值、CDP URL 解析和浏览器控制身份验证辅助函数 | + | `plugin-sdk/runtime` | 宽泛的运行时/日志记录/备份/插件安装辅助函数 | + | `plugin-sdk/runtime-env` | 精简的运行时环境、日志器、超时、重试和退避辅助函数 | + | `plugin-sdk/browser-config` | 支持的浏览器配置门面，用于规范化配置文件/默认值、CDP URL 解析和浏览器控制鉴权辅助函数 | | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助函数 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | | `plugin-sdk/plugin-runtime` | 共享的插件命令/钩子/http/交互式辅助函数 | - | `plugin-sdk/hook-runtime` | 共享的 Webhook/内部钩子管线辅助函数 | + | `plugin-sdk/hook-runtime` | 共享的 webhook/内部钩子流水线辅助函数 | | `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | 进程执行辅助函数 | | `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和惰性命令组辅助函数 | - | `plugin-sdk/gateway-runtime` | Gateway 网关客户端、事件循环就绪客户端启动辅助函数、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道 Status 补丁辅助函数 | - | `plugin-sdk/config-types` | 仅类型的配置接口，用于插件配置形状，例如 `OpenClawConfig` 和渠道/提供商配置类型 | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端、事件循环就绪客户端启动辅助函数、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道状态补丁辅助函数 | + | `plugin-sdk/config-types` | 插件配置形状的仅类型配置表面，例如 `OpenClawConfig` 以及渠道/提供商配置类型 | | `plugin-sdk/plugin-config-runtime` | 运行时插件配置查找辅助函数，例如 `requireRuntimeConfig`、`resolvePluginConfigObject` 和 `resolveLivePluginConfigObject` | | `plugin-sdk/config-mutation` | 事务性配置变更辅助函数，例如 `mutateConfigFile`、`replaceConfigFile` 和 `logConfigUpdated` | | `plugin-sdk/runtime-config-snapshot` | 当前进程配置快照辅助函数，例如 `getRuntimeConfig`、`getRuntimeConfigSnapshot` 和测试快照设置器 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化与重复/冲突检查，即使内置的 Telegram 契约接口不可用也可使用 | - | `plugin-sdk/text-autolink-runtime` | 文件引用自动链接检测，无需广泛的文本运行时桶形导出 | - | `plugin-sdk/approval-runtime` | 执行/插件审批辅助函数、审批能力构建器、身份验证/配置文件辅助函数、原生路由/运行时辅助函数，以及结构化审批显示路径格式化 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 合约表面不可用也可使用 | + | `plugin-sdk/text-autolink-runtime` | 无需宽泛 text-runtime 桶即可进行文件引用自动链接检测 | + | `plugin-sdk/approval-runtime` | 执行/插件审批辅助函数、审批能力构建器、鉴权/配置文件辅助函数、原生路由/运行时辅助函数，以及结构化审批显示路径格式化 | | `plugin-sdk/reply-runtime` | 共享的入站/回复运行时辅助函数、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/完成和会话标签辅助函数 | + | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/完成和对话标签辅助函数 | | `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助函数和标记，例如 `buildHistoryContext`、`HISTORY_CONTEXT_MARKER`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | 精简的文本/Markdown 分块辅助函数 | @@ -201,16 +203,16 @@ x-i18n: | `plugin-sdk/cron-store-runtime` | Cron 存储路径/加载/保存辅助函数 | | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助函数 | | `plugin-sdk/routing` | 路由/会话键/账号绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享的渠道/账号 Status 摘要辅助函数、运行时状态默认值和问题元数据辅助函数 | - | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助函数 | + | `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/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` | 子系统日志记录器和脱敏辅助函数 | + | `plugin-sdk/logging-core` | 子系统日志器和脱敏辅助函数 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助函数 | | `plugin-sdk/model-session-runtime` | 模型/会话覆盖辅助函数，例如 `applyModelOverrideToSessionEntry` 和 `resolveAgentMaxConcurrent` | | `plugin-sdk/talk-config-runtime` | Talk 提供商配置解析辅助函数 | @@ -219,115 +221,115 @@ x-i18n: | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 | | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助函数 | | `plugin-sdk/acp-runtime-backend` | 面向启动时加载插件的轻量级 ACP 后端注册和回复分发辅助函数 | - | `plugin-sdk/acp-binding-resolve-runtime` | 只读 ACP 绑定解析，无需生命周期启动导入 | + | `plugin-sdk/acp-binding-resolve-runtime` | 无生命周期启动导入的只读 ACP 绑定解析 | | `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置架构原语 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 | | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 | | `plugin-sdk/extension-shared` | 共享的被动渠道、Status 和环境代理辅助原语 | | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助函数 | - | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 | + | `plugin-sdk/skill-commands-runtime` | Skill 命令列出辅助函数 | | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助函数 | - | `plugin-sdk/agent-harness` | 面向低层智能体 harness 的实验性受信任插件接口：harness 类型、活动运行 steer/abort 辅助函数、OpenClaw 工具桥接辅助函数、运行时计划工具策略辅助函数、终端结果分类、工具进度格式化/详情辅助函数，以及尝试结果实用工具 | + | `plugin-sdk/agent-harness` | 面向底层智能体 harness 的实验性受信插件表面：harness 类型、活动运行引导/中止辅助函数、OpenClaw 工具桥接辅助函数、运行时计划工具策略辅助函数、终端结果分类、工具进度格式化/详情辅助函数和尝试结果工具函数 | | `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助函数 | | `plugin-sdk/async-lock-runtime` | 用于小型运行时状态文件的进程本地异步锁辅助函数 | | `plugin-sdk/channel-activity-runtime` | 渠道活动遥测辅助函数 | | `plugin-sdk/concurrency-runtime` | 有界异步任务并发辅助函数 | - | `plugin-sdk/dedupe-runtime` | 内存内去重缓存辅助函数 | - | `plugin-sdk/delivery-queue-runtime` | 出站待交付队列排空辅助函数 | + | `plugin-sdk/dedupe-runtime` | 内存中去重缓存辅助函数 | + | `plugin-sdk/delivery-queue-runtime` | 出站待处理投递排空辅助函数 | | `plugin-sdk/file-access-runtime` | 安全本地文件和媒体源路径辅助函数 | | `plugin-sdk/heartbeat-runtime` | 心跳事件和可见性辅助函数 | | `plugin-sdk/number-runtime` | 数值强制转换辅助函数 | | `plugin-sdk/secure-random-runtime` | 安全令牌/UUID 辅助函数 | | `plugin-sdk/system-event-runtime` | 系统事件队列辅助函数 | | `plugin-sdk/transport-ready-runtime` | 传输就绪等待辅助函数 | - | `plugin-sdk/infra-runtime` | 已弃用的兼容性 shim；请使用上方更聚焦的运行时子路径 | + | `plugin-sdk/infra-runtime` | 已弃用的兼容性垫片；请使用上面的聚焦运行时子路径 | | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | | `plugin-sdk/diagnostic-runtime` | 诊断标志、事件和跟踪上下文辅助函数 | | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 包装 fetch、代理、EnvHttpProxyAgent 选项和固定查找辅助函数 | - | `plugin-sdk/runtime-fetch` | 支持 dispatcher 的运行时 fetch，无需代理/受保护 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/日志导入 | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理、EnvHttpProxyAgent 选项和固定查找辅助函数 | + | `plugin-sdk/runtime-fetch` | 支持 Dispatcher 的运行时 fetch，无代理/受保护 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/日志记录导入 | | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 | | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 | | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助函数 | - | `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 | + | `plugin-sdk/directory-runtime` | 配置支持的目录查询/去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - | 子路径 | 关键导出 | + + | 子路径 | 主要导出 | | --- | --- | | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具、由 ffprobe 支持的视频尺寸探测，以及媒体载荷构建器 | - | `plugin-sdk/media-store` | 精简媒体存储辅助工具，例如 `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择，以及缺失模型消息 | + | `plugin-sdk/media-store` | 窄范围媒体存储辅助工具，例如 `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择，以及缺失模型提示消息 | | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如去除智能体可见文本、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具，以及安全文本实用工具 | + | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如剥离智能体可见文本、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具，以及安全文本工具 | | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的指令、注册表、验证、OpenAI 兼容 TTS 构建器和语音辅助导出 | | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、指令、规范化和语音辅助导出 | | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具，以及共享 WebSocket 会话辅助工具 | | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | | `plugin-sdk/image-generation` | 图像生成提供商类型，以及图像资产/data URL 辅助工具和 OpenAI 兼容图像提供商构建器 | - | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助工具 | + | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、身份验证和注册表辅助工具 | | `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和模型引用解析 | + | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找，以及模型引用解析 | | `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找和模型引用解析 | + | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找，以及模型引用解析 | | `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助工具 | | `plugin-sdk/webhook-path` | Webhook 路径规范化辅助工具 | | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助工具 | | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/testing` | 用于旧版插件测试的宽泛兼容性桶形导出。新的插件测试应改为导入聚焦的 SDK 子路径，例如 `plugin-sdk/agent-runtime-test-contracts`、`plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/test-env` 或 `plugin-sdk/test-fixtures` | - | `plugin-sdk/plugin-test-api` | 最小化的 `createTestPluginApi` 辅助工具，用于直接插件注册单元测试，无需导入仓库测试辅助桥接 | - | `plugin-sdk/agent-runtime-test-contracts` | 用于认证、投递、回退、工具钩子、提示词叠加、schema 和 transcript 投影测试的原生智能体运行时适配器契约夹具 | - | `plugin-sdk/channel-test-helpers` | 面向渠道的测试辅助工具，适用于通用动作/设置/Status 契约、目录断言、账号启动生命周期、send-config 线程处理、运行时 mock、Status 问题、出站投递和钩子注册 | - | `plugin-sdk/channel-target-testing` | 用于渠道测试的共享目标解析错误用例套件 | - | `plugin-sdk/plugin-test-contracts` | 插件包、注册、公共制品、直接导入、运行时 API 和导入副作用契约辅助工具 | - | `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、设备发现、新手引导、目录、向导、媒体能力、重放策略、实时 STT 实况音频、Web 搜索/获取和流式传输契约辅助工具 | - | `plugin-sdk/provider-http-test-mocks` | 可选择启用的 Vitest HTTP/认证 mock，适用于测试 `plugin-sdk/provider-http` 的提供商测试 | - | `plugin-sdk/test-fixtures` | 通用 CLI 运行时捕获、沙箱上下文、Skills 写入器、智能体消息、系统事件、模块重载、内置插件路径、终端文本、分块、认证令牌和类型化用例夹具 | + | `plugin-sdk/testing` | 面向旧版插件测试的宽兼容性汇总入口。新的插件测试应改为导入聚焦的 SDK 子路径，例如 `plugin-sdk/agent-runtime-test-contracts`、`plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/test-env` 或 `plugin-sdk/test-fixtures` | + | `plugin-sdk/plugin-test-api` | 最小化的 `createTestPluginApi` 辅助工具，用于不导入仓库测试辅助桥接的直接插件注册单元测试 | + | `plugin-sdk/agent-runtime-test-contracts` | 用于身份验证、投递、回退、工具钩子、提示词覆盖、schema 和转录投影测试的原生智能体运行时适配器契约固件 | + | `plugin-sdk/channel-test-helpers` | 面向渠道的测试辅助工具，用于通用操作/设置/Status 契约、目录断言、账号启动生命周期、发送配置线程化、运行时 mock、Status 问题、出站投递和钩子注册 | + | `plugin-sdk/channel-target-testing` | 用于渠道测试的共享目标解析错误案例套件 | + | `plugin-sdk/plugin-test-contracts` | 插件包、注册、公开构件、直接导入、运行时 API 和导入副作用契约辅助工具 | + | `plugin-sdk/provider-test-contracts` | 提供商运行时、身份验证、设备发现、新手引导、目录、向导、媒体能力、重放策略、实时 STT 现场音频、Web 搜索/获取和流契约辅助工具 | + | `plugin-sdk/provider-http-test-mocks` | 面向测试 `plugin-sdk/provider-http` 的提供商测试的可选 Vitest HTTP/身份验证 mock | + | `plugin-sdk/test-fixtures` | 通用 CLI 运行时捕获、沙箱上下文、skill 写入器、智能体消息、系统事件、模块重新加载、内置插件路径、终端文本、分块、身份验证令牌和类型化用例固件 | | `plugin-sdk/test-node-mocks` | 聚焦的 Node 内置 mock 辅助工具，用于 Vitest `vi.mock("node:*")` 工厂内部 | - - | 子路径 | 关键导出 | + + | 子路径 | 主要导出 | | --- | --- | - | `plugin-sdk/memory-core` | 用于管理器/配置/文件/CLI 辅助工具的内置 memory-core 辅助表面 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时门面 | - | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host 嵌入契约、注册表访问、本地提供商和通用批处理/远程辅助工具 | - | `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 多模态辅助工具 | - | `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 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 事件日志辅助工具的厂商中立别名 | - | `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 Status 辅助工具的厂商中立别名 | + | `plugin-sdk/memory-core` | 面向管理器/配置/文件/CLI 辅助工具的内置 memory-core 辅助表面 | + | `plugin-sdk/memory-core-engine-runtime` | 内存索引/搜索运行时门面 | + | `plugin-sdk/memory-core-host-engine-foundation` | 内存宿主 foundation 引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | 内存宿主嵌入契约、注册表访问、本地提供商，以及通用批处理/远程辅助工具 | + | `plugin-sdk/memory-core-host-engine-qmd` | 内存宿主 QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | 内存宿主存储引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | 内存宿主多模态辅助工具 | + | `plugin-sdk/memory-core-host-query` | 内存宿主查询辅助工具 | + | `plugin-sdk/memory-core-host-secret` | 内存宿主密钥辅助工具 | + | `plugin-sdk/memory-core-host-events` | 内存宿主事件日志辅助工具 | + | `plugin-sdk/memory-core-host-status` | 内存宿主 Status 辅助工具 | + | `plugin-sdk/memory-core-host-runtime-cli` | 内存宿主 CLI 运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-core` | 内存宿主核心运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | 内存宿主文件/运行时辅助工具 | + | `plugin-sdk/memory-host-core` | 内存宿主核心运行时辅助工具的供应商中立别名 | + | `plugin-sdk/memory-host-events` | 内存宿主事件日志辅助工具的供应商中立别名 | + | `plugin-sdk/memory-host-files` | 内存宿主文件/运行时辅助工具的供应商中立别名 | + | `plugin-sdk/memory-host-markdown` | 面向内存相邻插件的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动内存运行时门面 | + | `plugin-sdk/memory-host-status` | 内存宿主 Status 辅助工具的供应商中立别名 | - - 目前没有保留的内置辅助工具 SDK 子路径。所有者专用 - 辅助工具位于所属插件包内，而可复用的 host 契约 + + 目前没有预留的内置辅助工具 SDK 子路径。所有者特定的 + 辅助工具位于所属插件包内，而可复用的宿主契约 使用通用 SDK 子路径，例如 `plugin-sdk/gateway-runtime`、 `plugin-sdk/security-runtime` 和 `plugin-sdk/plugin-config-runtime`。 -## 相关 +## 相关内容 - [插件 SDK 概览](/zh-CN/plugins/sdk-overview) - [插件 SDK 设置](/zh-CN/plugins/sdk-setup)