chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
6a89d950a1
commit
6af68ebbf3
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- 修改群聊行为或提及门控时
|
||||
summary: 跨界面群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo）
|
||||
- 更改群聊行为或提及门控时
|
||||
summary: 跨表面的群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo）
|
||||
title: 群组
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T15:28:01Z"
|
||||
generated_at: "2026-04-07T06:53:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 83d20f2958ed6ad3354f0078553b3c6a38643ea8ef38573c40e89ebef2fa8421
|
||||
source_hash: f5045badbba30587c8f1bf27f6b940c7c471a95c57093c9adb142374413ac81e
|
||||
source_path: channels/groups.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 群组
|
||||
|
||||
OpenClaw 会在各个界面上一致地处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。
|
||||
OpenClaw 会在各个表面上一致地处理群聊：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。
|
||||
|
||||
## 新手简介（2 分钟）
|
||||
## 新手介绍（2 分钟）
|
||||
|
||||
OpenClaw “运行”在你自己的消息账号上。它不是一个单独的 WhatsApp 机器人用户。
|
||||
如果**你**在某个群里，OpenClaw 就可以看到那个群并在那里回复。
|
||||
OpenClaw “运行”在你自己的消息账号上。没有单独的 WhatsApp 机器人用户。
|
||||
如果**你**在某个群组中，OpenClaw 就能看到该群组并在那里回复。
|
||||
|
||||
默认行为：
|
||||
|
||||
- 群组是受限的（`groupPolicy: "allowlist"`）。
|
||||
- 群组受限（`groupPolicy: "allowlist"`）。
|
||||
- 回复需要提及，除非你明确禁用提及门控。
|
||||
|
||||
换句话说：在允许列表中的发送者可以通过提及 OpenClaw 来触发它。
|
||||
也就是说：在允许列表中的发送者可以通过提及 OpenClaw 来触发它。
|
||||
|
||||
> 简而言之
|
||||
> TL;DR
|
||||
>
|
||||
> - **私信访问**由 `*.allowFrom` 控制。
|
||||
> - **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。
|
||||
> - **回复触发**由提及门控（`requireMention`、`/activation`）控制。
|
||||
> - **私信访问权限**由 `*.allowFrom` 控制。
|
||||
> - **群组访问权限**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。
|
||||
> - **回复触发**由提及门控控制（`requireMention`、`/activation`）。
|
||||
|
||||
快速流程（群消息会发生什么）：
|
||||
快速流程（群组消息会发生什么）：
|
||||
|
||||
```
|
||||
groupPolicy? disabled -> drop
|
||||
@ -47,58 +47,58 @@ otherwise -> reply
|
||||
|
||||
群组安全涉及两种不同的控制：
|
||||
|
||||
- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道特定允许列表）。
|
||||
- **上下文可见性**：哪些补充上下文会注入到模型中（回复文本、引用、线程历史、转发元数据）。
|
||||
- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、特定渠道的允许列表）。
|
||||
- **上下文可见性**：哪些补充上下文会被注入到模型中（回复文本、引用、线程历史、转发元数据）。
|
||||
|
||||
默认情况下，OpenClaw 优先保持正常聊天行为，并尽量按接收到的原样保留上下文。这意味着允许列表主要决定谁可以触发操作，而不是对每一段引用或历史片段都进行统一脱敏的边界。
|
||||
默认情况下，OpenClaw 优先保证正常聊天行为，并尽量按接收到的原样保留上下文。这意味着允许列表主要决定谁可以触发操作，而不是对每一段引用或历史片段都实行统一脱敏边界。
|
||||
|
||||
当前行为因渠道而异：
|
||||
|
||||
- 某些渠道已经在特定路径上对补充上下文应用基于发送者的过滤（例如 Slack 线程预载、Matrix 回复/线程查询）。
|
||||
- 某些渠道已经在特定路径上对补充上下文应用基于发送者的过滤（例如 Slack 线程种子数据、Matrix 回复/线程查询）。
|
||||
- 其他渠道仍然会按接收到的原样传递引用/回复/转发上下文。
|
||||
|
||||
加固方向（计划中）：
|
||||
|
||||
- `contextVisibility: "all"`（默认）保持当前“按接收原样处理”的行为。
|
||||
- `contextVisibility: "allowlist"` 会将补充上下文过滤为仅限允许列表中的发送者。
|
||||
- `contextVisibility: "allowlist_quote"` 等于 `allowlist`，再加上一条显式的引用/回复例外规则。
|
||||
- `contextVisibility: "all"`（默认）保持当前按接收原样处理的行为。
|
||||
- `contextVisibility: "allowlist"` 会将补充上下文过滤为仅来自允许列表发送者。
|
||||
- `contextVisibility: "allowlist_quote"` 等同于 `allowlist`，并额外允许一个显式的引用/回复例外。
|
||||
|
||||
在这一加固模型尚未在所有渠道中一致实现之前，不同界面的行为仍会有所差异。
|
||||
在这个加固模型尚未在各渠道中一致实现之前，不同表面之间的行为差异是预期内的。
|
||||
|
||||
|
||||
|
||||
|
||||
如果你想要……
|
||||
|
||||
| 目标 | 需要设置什么 |
|
||||
| 目标 | 应设置内容 |
|
||||
| -------------------------------------------- | ---------------------------------------------------------- |
|
||||
| 允许所有群组，但只在 @提及时回复 | `groups: { "*": { requireMention: true } }` |
|
||||
| 允许所有群组，但只在 @ 提及时回复 | `groups: { "*": { requireMention: true } }` |
|
||||
| 禁用所有群组回复 | `groupPolicy: "disabled"` |
|
||||
| 只允许特定群组 | `groups: { "<group-id>": { ... } }`（不使用 `"*"` 键） |
|
||||
| 只有你可以在群组中触发 OpenClaw | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
|
||||
| 仅限特定群组 | `groups: { "<group-id>": { ... } }`（不使用 `"*"` 键） |
|
||||
| 只有你可以在群组中触发 | `groupPolicy: "allowlist"`，`groupAllowFrom: ["+1555..."]` |
|
||||
|
||||
## 会话键
|
||||
|
||||
- 群组会话使用 `agent:<agentId>:<channel>:group:<id>` 会话键（房间/频道使用 `agent:<agentId>:<channel>:channel:<id>`）。
|
||||
- Telegram 论坛主题会在群组 id 后附加 `:topic:<threadId>`，因此每个主题都有自己的会话。
|
||||
- 私聊使用主会话（或在已配置时按发送者分开）。
|
||||
- Telegram 论坛话题会在群组 id 后附加 `:topic:<threadId>`，因此每个话题都有自己的会话。
|
||||
- 私聊使用主会话（或按配置使用每发送者单独会话）。
|
||||
- 群组会话会跳过心跳。
|
||||
|
||||
<a id="pattern-personal-dms-public-groups-single-agent"></a>
|
||||
|
||||
## 模式：个人私信 + 公开群组（单智能体）
|
||||
## 模式：个人私信 + 公开群组（单个智能体）
|
||||
|
||||
可以——如果你的“个人”流量是**私信**，而“公开”流量是**群组**，这个模式效果很好。
|
||||
可以——如果你的“个人”流量是**私信**，而“公开”流量是**群组**，这种方式效果很好。
|
||||
|
||||
原因是：在单智能体模式下，私信通常会进入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main:<channel>:group:<id>`）。如果你启用沙箱隔离并设置 `mode: "non-main"`，这些群组会话就会在 Docker 中运行，而你的主私信会话仍然留在主机上运行。
|
||||
原因：在单智能体模式下，私信通常会进入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main:<channel>:group:<id>`）。如果你启用 `mode: "non-main"` 的沙箱隔离，这些群组会话会在 Docker 中运行，而你的主私信会话则保留在主机上运行。
|
||||
|
||||
这样你就拥有一个智能体“脑”（共享工作区 + 记忆），但两种执行姿态：
|
||||
这样你就能拥有一个智能体“大脑”（共享工作区 + 记忆），但有两种执行姿态：
|
||||
|
||||
- **私信**：完整工具（主机）
|
||||
- **群组**：沙箱 + 受限工具（Docker）
|
||||
|
||||
> 如果你需要真正独立的工作区/角色（“个人”和“公开”绝不能混在一起），请使用第二个智能体 + 绑定。参见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。
|
||||
> 如果你需要真正独立的工作区/人格（“个人”和“公开”绝不能混用），请使用第二个智能体 + 绑定。参见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。
|
||||
|
||||
示例（私信在主机上，群组使用沙箱隔离且仅允许消息类工具）：
|
||||
示例（私信在主机上运行，群组在沙箱中运行 + 仅消息工具）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -123,7 +123,7 @@ otherwise -> reply
|
||||
}
|
||||
```
|
||||
|
||||
想要实现“群组只能看到文件夹 X”而不是“完全不能访问主机”？保留 `workspaceAccess: "none"`，然后只把允许列表中的路径挂载进沙箱：
|
||||
如果你想要的是“群组只能看到文件夹 X”，而不是“完全不能访问主机”，请保持 `workspaceAccess: "none"`，并仅将允许列表中的路径挂载到沙箱中：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -147,9 +147,9 @@ otherwise -> reply
|
||||
|
||||
相关内容：
|
||||
|
||||
- 配置键与默认值：[Gateway 配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)
|
||||
- 调试为什么某个工具被阻止：[沙箱隔离 vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)
|
||||
- 绑定挂载详情：[沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts)
|
||||
- 配置键和默认值：[Gateway configuration](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)
|
||||
- 调试为什么某个工具被阻止：[Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)
|
||||
- 绑定挂载详情：[Sandboxing](/zh-CN/gateway/sandboxing#custom-bind-mounts)
|
||||
|
||||
## 显示标签
|
||||
|
||||
@ -158,7 +158,7 @@ otherwise -> reply
|
||||
|
||||
## 群组策略
|
||||
|
||||
按渠道控制如何处理群组/房间消息：
|
||||
控制每个渠道如何处理群组/房间消息：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -207,34 +207,36 @@ otherwise -> reply
|
||||
|
||||
| 策略 | 行为 |
|
||||
| ------------- | ------------------------------------------------------------ |
|
||||
| `"open"` | 群组会绕过允许列表；但提及门控仍然生效。 |
|
||||
| `"open"` | 群组绕过允许列表；提及门控仍然适用。 |
|
||||
| `"disabled"` | 完全阻止所有群组消息。 |
|
||||
| `"allowlist"` | 仅允许与已配置允许列表匹配的群组/房间。 |
|
||||
| `"allowlist"` | 仅允许与配置的允许列表匹配的群组/房间。 |
|
||||
|
||||
说明：
|
||||
|
||||
- `groupPolicy` 与提及门控是分开的（提及门控要求 @提及）。
|
||||
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（回退：显式 `allowFrom`）。
|
||||
- 私信配对审批（`*-allowFrom` 存储项）只适用于私信访问；群组发送者授权仍需要在群组允许列表中显式配置。
|
||||
- `groupPolicy` 与提及门控是分开的（后者要求 @ 提及）。
|
||||
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（回退为显式 `allowFrom`）。
|
||||
- 私信配对批准（`*-allowFrom` 存储条目）只适用于私信访问；群组发送者授权仍需通过群组允许列表显式配置。
|
||||
- Discord：允许列表使用 `channels.discord.guilds.<id>.channels`。
|
||||
- Slack：允许列表使用 `channels.slack.channels`。
|
||||
- Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查询是尽力而为，运行时无法解析的名称会被忽略。使用 `channels.matrix.groupAllowFrom` 来限制发送者；也支持按房间配置的 `users` 允许列表。
|
||||
- Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查询仅尽力而为，运行时无法解析的名称会被忽略。使用 `channels.matrix.groupAllowFrom` 来限制发送者；也支持按房间配置的 `users` 允许列表。
|
||||
- 群组私信单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。
|
||||
- Telegram 允许列表可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀大小写不敏感。
|
||||
- 默认值是 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息会被阻止。
|
||||
- 运行时安全：当某个提供商配置块完全缺失（`channels.<provider>` 不存在）时，群组策略会回退到故障关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。
|
||||
- Telegram 允许列表可匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀大小写不敏感。
|
||||
- 默认值是 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，则群组消息会被阻止。
|
||||
- 运行时安全：当某个提供商配置块完全缺失时（`channels.<provider>` 不存在），群组策略会回退到失效关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。
|
||||
|
||||
快速心智模型（群组消息的评估顺序）：
|
||||
|
||||
1. `groupPolicy`（open/disabled/allowlist）
|
||||
2. 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道特定允许列表）
|
||||
2. 群组允许列表（`*.groups`、`*.groupAllowFrom`、特定渠道允许列表）
|
||||
3. 提及门控（`requireMention`、`/activation`）
|
||||
|
||||
## 提及门控（默认）
|
||||
|
||||
群组消息默认需要提及，除非按群组覆盖。默认值按子系统存放在 `*.groups."*"` 下。
|
||||
除非按群组覆盖，否则群组消息需要提及。默认值按各子系统存放在 `*.groups."*"` 下。
|
||||
|
||||
回复机器人消息会被视为隐式提及（当渠道支持回复元数据时）。这适用于 Telegram、WhatsApp、Slack、Discord 和 Microsoft Teams。
|
||||
回复机器人消息会被视为隐式提及，前提是该渠道支持回复元数据。
|
||||
引用机器人消息也可能被视为隐式提及，前提是该渠道公开引用元数据。
|
||||
当前内置支持的渠道包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -275,28 +277,28 @@ otherwise -> reply
|
||||
说明：
|
||||
|
||||
- `mentionPatterns` 是大小写不敏感的安全正则模式；无效模式和不安全的嵌套重复形式会被忽略。
|
||||
- 提供显式提及的界面仍然会通过；这些模式只是回退方案。
|
||||
- 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时很有用）。
|
||||
- 只有在能够检测提及时，才会强制执行提及门控（原生提及或已配置 `mentionPatterns`）。
|
||||
- Discord 默认值位于 `channels.discord.guilds."*"`（可按 guild/channel 覆盖）。
|
||||
- 群组历史上下文会在各个渠道中统一包装，并且仅包含**待处理消息**（即因提及门控而跳过的消息）；全局默认值使用 `messages.groupChat.historyLimit`，覆盖项使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）。设为 `0` 可禁用。
|
||||
- 提供显式提及的表面仍然会通过；这些模式只是回退方案。
|
||||
- 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（多个智能体共享同一群组时很有用）。
|
||||
- 只有在可以进行提及检测时，才会强制执行提及门控（原生提及，或已配置 `mentionPatterns`）。
|
||||
- Discord 默认值位于 `channels.discord.guilds."*"`（可按 guild/频道覆盖）。
|
||||
- 群组历史上下文在各渠道间会被统一包装，并且仅包含**待处理消息**（因提及门控而被跳过的消息）；使用 `messages.groupChat.historyLimit` 作为全局默认值，使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）进行覆盖。设为 `0` 可禁用。
|
||||
|
||||
## 群组/频道工具限制（可选）
|
||||
|
||||
某些渠道配置支持限制**特定群组/房间/频道内**可用的工具。
|
||||
|
||||
- `tools`：为整个群组允许/拒绝工具。
|
||||
- `tools`：对整个群组允许/拒绝工具。
|
||||
- `toolsBySender`：群组内按发送者覆盖。
|
||||
使用显式键前缀：
|
||||
`id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>` 和 `"*"` 通配符。
|
||||
旧版无前缀键仍然被接受，但只会按 `id:` 匹配。
|
||||
旧版无前缀键仍然接受，但只会按 `id:` 匹配。
|
||||
|
||||
解析顺序（越具体优先级越高）：
|
||||
解析顺序（越具体越优先）：
|
||||
|
||||
1. 群组/频道 `toolsBySender` 匹配
|
||||
2. 群组/频道 `tools`
|
||||
3. 默认（`"*"`）`toolsBySender` 匹配
|
||||
4. 默认（`"*"`）`tools`
|
||||
3. 默认值（`"*"`）`toolsBySender` 匹配
|
||||
4. 默认值（`"*"`）`tools`
|
||||
|
||||
示例（Telegram）：
|
||||
|
||||
@ -320,15 +322,15 @@ otherwise -> reply
|
||||
|
||||
说明：
|
||||
|
||||
- 群组/频道工具限制是在全局/智能体工具策略之外额外应用的（deny 仍然优先）。
|
||||
- 群组/频道工具限制会与全局/智能体工具策略一同应用（拒绝仍然优先）。
|
||||
- 某些渠道对房间/频道使用不同的嵌套结构（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
|
||||
|
||||
## 群组允许列表
|
||||
|
||||
当配置了 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会充当群组允许列表。使用 `"*"` 可允许所有群组，同时仍然设置默认提及行为。
|
||||
配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会作为群组允许列表。使用 `"*"` 可以允许所有群组，同时仍然设置默认提及行为。
|
||||
|
||||
常见困惑：私信配对审批并不等同于群组授权。
|
||||
对于支持私信配对的渠道，配对存储只会解锁私信。群组命令仍然需要通过配置允许列表显式授权群组发送者，例如 `groupAllowFrom` 或该渠道文档说明的回退配置。
|
||||
常见混淆：私信配对批准并不等于群组授权。
|
||||
对于支持私信配对的渠道，配对存储只会解锁私信。群组命令仍然需要通过配置允许列表显式授权群组发送者，例如 `groupAllowFrom` 或该渠道文档中说明的配置回退项。
|
||||
|
||||
常见意图（可直接复制粘贴）：
|
||||
|
||||
@ -383,12 +385,12 @@ otherwise -> reply
|
||||
|
||||
## 激活（仅所有者）
|
||||
|
||||
群组所有者可以按群组切换激活模式：
|
||||
群组所有者可以切换每个群组的激活状态：
|
||||
|
||||
- `/activation mention`
|
||||
- `/activation always`
|
||||
|
||||
所有者由 `channels.whatsapp.allowFrom` 决定（如果未设置，则使用机器人自身的 E.164）。请将命令作为单独一条消息发送。其他界面当前会忽略 `/activation`。
|
||||
所有者由 `channels.whatsapp.allowFrom` 决定（未设置时则使用机器人自身的 E.164）。请将命令作为独立消息发送。其他表面当前会忽略 `/activation`。
|
||||
|
||||
## 上下文字段
|
||||
|
||||
@ -398,20 +400,20 @@ otherwise -> reply
|
||||
- `GroupSubject`（如果已知）
|
||||
- `GroupMembers`（如果已知）
|
||||
- `WasMentioned`（提及门控结果）
|
||||
- Telegram 论坛主题还会包含 `MessageThreadId` 和 `IsForum`。
|
||||
- Telegram 论坛话题还会包含 `MessageThreadId` 和 `IsForum`
|
||||
|
||||
渠道特定说明：
|
||||
特定渠道说明：
|
||||
|
||||
- BlueBubbles 可以在填充 `GroupMembers` 之前，选择性地从本地 Contacts 数据库中补充未命名的 macOS 群组参与者信息。此功能默认关闭，并且只会在常规群组门控通过后运行。
|
||||
- BlueBubbles 可以选择在填充 `GroupMembers` 之前，先从本地联系人数据库中补全未命名的 macOS 群组参与者信息。此功能默认关闭，且只会在正常群组门控通过后运行。
|
||||
|
||||
智能体系统提示会在新群组会话的第一轮加入群组说明。它会提醒模型像人类一样回复、避免使用 Markdown 表格、尽量减少空行、遵循正常聊天间距，并避免输入字面量 `\n` 序列。
|
||||
在新群组会话的第一轮中，智能体系统提示词会包含群组介绍。它会提醒模型像人类一样回复、避免使用 Markdown 表格、尽量减少空行、遵循正常聊天间距，并避免输入字面量 `\n` 序列。
|
||||
|
||||
## iMessage 细节
|
||||
|
||||
- 在路由或允许列表中优先使用 `chat_id:<id>`。
|
||||
- 在路由或允许列表中，优先使用 `chat_id:<id>`。
|
||||
- 列出聊天：`imsg chats --limit 20`。
|
||||
- 群组回复始终会发回相同的 `chat_id`。
|
||||
- 群组回复始终返回到同一个 `chat_id`。
|
||||
|
||||
## WhatsApp 细节
|
||||
|
||||
有关 WhatsApp 专属行为（历史注入、提及处理细节），请参见 [群消息](/zh-CN/channels/group-messages)。
|
||||
参见 [Group messages](/zh-CN/channels/group-messages) 了解仅适用于 WhatsApp 的行为（历史注入、提及处理细节）。
|
||||
|
||||
@ -1,45 +1,45 @@
|
||||
---
|
||||
read_when:
|
||||
- 为 OpenClaw 设置 Zalo Personal
|
||||
- 调试 Zalo Personal 登录或消息流
|
||||
summary: 通过原生 `zca-js`（二维码登录）提供 Zalo 个人账号支持，以及相关能力和配置
|
||||
title: Zalo Personal
|
||||
- 为 OpenClaw 设置 Zalo 个人版
|
||||
- 调试 Zalo 个人版登录或消息流程
|
||||
summary: 通过原生 `zca-js`（二维码登录）提供 Zalo 个人账号支持、能力和配置
|
||||
title: Zalo 个人版
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T08:18:17Z"
|
||||
generated_at: "2026-04-07T06:53:05Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 331b95041463185472d242cb0a944972f0a8e99df8120bda6350eca86ad5963f
|
||||
source_hash: 08f50edb2f4c6fe24972efe5e321f5fd0572c7d29af5c1db808151c7c943dc66
|
||||
source_path: channels/zalouser.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Zalo Personal（非官方）
|
||||
# Zalo 个人版（非官方）
|
||||
|
||||
状态：实验性。此集成通过 OpenClaw 内部的原生 `zca-js` 自动化一个 **Zalo 个人账号**。
|
||||
|
||||
> **警告：** 这是一个非官方集成，可能会导致账号被暂停或封禁。请自行承担使用风险。
|
||||
> **警告：** 这是一个非官方集成，可能会导致账号被暂停或封禁。使用风险由你自行承担。
|
||||
|
||||
## 内置插件
|
||||
|
||||
Zalo Personal 作为当前 OpenClaw 版本中的内置插件提供，因此普通打包构建无需单独安装。
|
||||
Zalo 个人版作为当前 OpenClaw 版本中的内置插件提供，因此常规打包构建无需单独安装。
|
||||
|
||||
如果你使用的是较旧版本，或是不包含 Zalo Personal 的自定义安装，请手动安装：
|
||||
如果你使用的是较旧版本，或排除了 Zalo 个人版的自定义安装，请手动安装：
|
||||
|
||||
- 通过 CLI 安装：`openclaw plugins install @openclaw/zalouser`
|
||||
- 或从源码检出安装：`openclaw plugins install ./path/to/local/zalouser-plugin`
|
||||
- 详情：[插件](/tools/plugin)
|
||||
- 详情：[插件](/zh-CN/tools/plugin)
|
||||
|
||||
不需要额外的 `zca`/`openzca` CLI 二进制文件。
|
||||
不需要外部 `zca`/`openzca` CLI 二进制文件。
|
||||
|
||||
## 快速设置（新手）
|
||||
|
||||
1. 确保 Zalo Personal 插件可用。
|
||||
1. 确保 Zalo 个人版插件可用。
|
||||
- 当前打包的 OpenClaw 版本已内置该插件。
|
||||
- 较旧版本或自定义安装可使用上面的命令手动添加。
|
||||
- 较旧版本或自定义安装可使用上述命令手动添加。
|
||||
2. 登录（二维码，在 Gateway 网关机器上）：
|
||||
- `openclaw channels login --channel zalouser`
|
||||
- 使用 Zalo 移动应用扫描二维码。
|
||||
3. 启用渠道：
|
||||
3. 启用该渠道：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -57,14 +57,14 @@ Zalo Personal 作为当前 OpenClaw 版本中的内置插件提供，因此普
|
||||
|
||||
## 它是什么
|
||||
|
||||
- 通过 `zca-js` 完全在进程内运行。
|
||||
- 完全通过 `zca-js` 在进程内运行。
|
||||
- 使用原生事件监听器接收入站消息。
|
||||
- 通过 JS API 直接发送回复（文本/媒体/链接）。
|
||||
- 面向无法使用 Zalo Bot API 的“个人账号”使用场景而设计。
|
||||
- 适用于无法使用 Zalo Bot API 的“个人账号”场景。
|
||||
|
||||
## 命名
|
||||
|
||||
渠道 id 为 `zalouser`，以明确表示这是在自动化一个 **Zalo 个人用户账号**（非官方）。我们保留 `zalo`，用于未来可能推出的官方 Zalo API 集成。
|
||||
渠道 ID 为 `zalouser`，以明确表示这是对 **Zalo 个人用户账号** 的自动化（非官方）。我们保留 `zalo`，供未来可能推出的官方 Zalo API 集成使用。
|
||||
|
||||
## 查找 ID（目录）
|
||||
|
||||
@ -78,34 +78,34 @@ openclaw directory groups list --channel zalouser --query "work"
|
||||
|
||||
## 限制
|
||||
|
||||
- 出站文本会被分块到约 2000 个字符（Zalo 客户端限制）。
|
||||
- 出站文本会被分块为约 2000 个字符（Zalo 客户端限制）。
|
||||
- 默认阻止流式传输。
|
||||
|
||||
## 访问控制（私信）
|
||||
|
||||
`channels.zalouser.dmPolicy` 支持：`pairing | allowlist | open | disabled`（默认：`pairing`）。
|
||||
|
||||
`channels.zalouser.allowFrom` 接受用户 ID 或名称。在设置期间，会使用插件的进程内联系人查询将名称解析为 ID。
|
||||
`channels.zalouser.allowFrom` 接受用户 ID 或名称。设置期间，名称会通过插件的进程内联系人查找解析为 ID。
|
||||
|
||||
通过以下命令批准：
|
||||
可通过以下命令批准：
|
||||
|
||||
- `openclaw pairing list zalouser`
|
||||
- `openclaw pairing approve zalouser <code>`
|
||||
|
||||
## 群组访问（可选）
|
||||
|
||||
- 默认：`channels.zalouser.groupPolicy = "open"`（允许群组）。未设置时，可使用 `channels.defaults.groupPolicy` 覆盖默认值。
|
||||
- 默认：`channels.zalouser.groupPolicy = "open"`（允许群组）。当未设置时，使用 `channels.defaults.groupPolicy` 覆盖默认值。
|
||||
- 使用以下配置限制为允许列表：
|
||||
- `channels.zalouser.groupPolicy = "allowlist"`
|
||||
- `channels.zalouser.groups`（键应为稳定的群组 ID；如果可能，启动时会将名称解析为 ID）
|
||||
- `channels.zalouser.groupAllowFrom`（控制允许群组中哪些发送者可以触发机器人）
|
||||
- `channels.zalouser.groups`（键应为稳定的群组 ID；如有可能，名称会在启动时解析为 ID）
|
||||
- `channels.zalouser.groupAllowFrom`（控制允许的群组中哪些发送者可以触发机器人）
|
||||
- 阻止所有群组：`channels.zalouser.groupPolicy = "disabled"`。
|
||||
- 配置向导可以提示你设置群组允许列表。
|
||||
- 启动时，OpenClaw 会将允许列表中的群组/用户名称解析为 ID，并记录映射。
|
||||
- 默认情况下，群组允许列表匹配仅基于 ID。除非启用 `channels.zalouser.dangerouslyAllowNameMatching: true`，否则无法解析的名称会在鉴权时被忽略。
|
||||
- `channels.zalouser.dangerouslyAllowNameMatching: true` 是一种紧急兼容模式，会重新启用可变群组名称匹配。
|
||||
- 如果未设置 `groupAllowFrom`，运行时会回退到 `allowFrom` 进行群组发送者检查。
|
||||
- 发送者检查同时适用于普通群组消息和控制命令（例如 `/new`、`/reset`）。
|
||||
- 配置向导可以提示输入群组允许列表。
|
||||
- 启动时，OpenClaw 会将允许列表中的群组/用户名称解析为 ID，并记录映射关系。
|
||||
- 默认情况下，群组允许列表匹配仅基于 ID。未解析的名称会在鉴权时被忽略，除非启用 `channels.zalouser.dangerouslyAllowNameMatching: true`。
|
||||
- `channels.zalouser.dangerouslyAllowNameMatching: true` 是一种破玻璃兼容模式，会重新启用可变的群组名称匹配。
|
||||
- 如果未设置 `groupAllowFrom`，运行时会回退到 `allowFrom` 用于群组发送者检查。
|
||||
- 发送者检查同时适用于普通群消息和控制命令（例如 `/new`、`/reset`）。
|
||||
|
||||
示例：
|
||||
|
||||
@ -126,12 +126,13 @@ openclaw directory groups list --channel zalouser --query "work"
|
||||
|
||||
### 群组提及门控
|
||||
|
||||
- `channels.zalouser.groups.<group>.requireMention` 控制群组回复是否需要提及。
|
||||
- 解析顺序：精确群组 id/名称 -> 标准化群组 slug -> `*` -> 默认值（`true`）。
|
||||
- 这同时适用于允许列表中的群组和开放群组模式。
|
||||
- `channels.zalouser.groups.<group>.requireMention` 控制群组回复是否必须被提及。
|
||||
- 解析顺序：精确群组 id/名称 -> 规范化群组 slug -> `*` -> 默认值（`true`）。
|
||||
- 这同时适用于允许列表群组和开放群组模式。
|
||||
- 引用一条机器人消息会被视为用于激活群组的隐式提及。
|
||||
- 已授权的控制命令（例如 `/new`）可以绕过提及门控。
|
||||
- 当群组消息因需要提及而被跳过时，OpenClaw 会将其存储为待处理的群组历史，并在下一条被处理的群组消息中包含这些内容。
|
||||
- 群组历史上限默认使用 `messages.groupChat.historyLimit`（回退值为 `50`）。你可以通过 `channels.zalouser.historyLimit` 为每个账号覆盖此设置。
|
||||
- 当群消息因需要提及而被跳过时，OpenClaw 会将其存储为待处理的群组历史，并在下一条被处理的群消息中包含它。
|
||||
- 群组历史记录限制默认使用 `messages.groupChat.historyLimit`（回退值为 `50`）。你可以通过 `channels.zalouser.historyLimit` 为每个账号单独覆盖。
|
||||
|
||||
示例：
|
||||
|
||||
@ -167,13 +168,13 @@ openclaw directory groups list --channel zalouser --query "work"
|
||||
}
|
||||
```
|
||||
|
||||
## 正在输入、反应和送达确认
|
||||
## 正在输入、表情回应和送达确认
|
||||
|
||||
- OpenClaw 会在发送回复前发送“正在输入”事件（尽力而为）。
|
||||
- 渠道操作中，`zalouser` 支持消息反应动作 `react`。
|
||||
- 使用 `remove: true` 可从消息中移除指定的反应表情。
|
||||
- 反应语义：[反应](/tools/reactions)
|
||||
- 对于包含事件元数据的入站消息，OpenClaw 会发送已送达 + 已查看确认（尽力而为）。
|
||||
- OpenClaw 会在分发回复前发送一个正在输入事件（尽力而为）。
|
||||
- 消息表情回应动作 `react` 在渠道动作中受 `zalouser` 支持。
|
||||
- 使用 `remove: true` 从消息中移除特定的表情回应 emoji。
|
||||
- 表情回应语义：[表情回应](/zh-CN/tools/reactions)
|
||||
- 对于包含事件元数据的入站消息，OpenClaw 会发送送达 + 已读确认（尽力而为）。
|
||||
|
||||
## 故障排除
|
||||
|
||||
@ -188,13 +189,13 @@ openclaw directory groups list --channel zalouser --query "work"
|
||||
|
||||
**从旧版基于 CLI 的设置升级：**
|
||||
|
||||
- 删除任何关于旧外部 `zca` 进程的假设。
|
||||
- 移除任何关于旧外部 `zca` 进程的假设。
|
||||
- 该渠道现在完全在 OpenClaw 内运行，无需外部 CLI 二进制文件。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [渠道概览](/channels) — 所有支持的渠道
|
||||
- [配对](/channels/pairing) — 私信身份验证和配对流程
|
||||
- [群组](/channels/groups) — 群聊行为和提及门控
|
||||
- [渠道路由](/channels/channel-routing) — 消息的会话路由
|
||||
- [安全](/gateway/security) — 访问模型和加固
|
||||
- [渠道概览](/zh-CN/channels) — 所有受支持的渠道
|
||||
- [配对](/zh-CN/channels/pairing) — 私信身份验证和配对流程
|
||||
- [群组](/zh-CN/channels/groups) — 群聊行为和提及门控
|
||||
- [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由
|
||||
- [安全性](/zh-CN/gateway/security) — 访问模型和加固
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,23 +1,23 @@
|
||||
---
|
||||
read_when:
|
||||
- 你正在构建一个新的消息渠道插件
|
||||
- 你想将 OpenClaw 连接到一个消息平台
|
||||
- 你需要了解 ChannelPlugin 适配器接口
|
||||
- 你想要将 OpenClaw 连接到一个消息平台
|
||||
- 你需要理解 ChannelPlugin 适配器表面
|
||||
sidebarTitle: Channel Plugins
|
||||
summary: 构建 OpenClaw 消息渠道插件的分步指南
|
||||
title: 构建渠道插件
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T18:55:42Z"
|
||||
generated_at: "2026-04-07T06:53:58Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 25ac0591d9b0ba401925b29ae4b9572f18b2cbffc2b6ca6ed5252740e7cf97e9
|
||||
source_hash: 0aab6cc835b292c62e33c52ad0c35f989fb1a5b225511e8bdc2972feb3c64f09
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 构建渠道插件
|
||||
|
||||
本指南将带你构建一个把 OpenClaw 连接到消息平台的渠道插件。完成后，你将拥有一个可用的渠道，具备私信安全、配对、回复线程处理以及出站消息发送能力。
|
||||
本指南将带你完成一个渠道插件的构建过程，用于将 OpenClaw 连接到消息平台。完成后，你将拥有一个可用的渠道，支持私信安全、配对、回复线程和出站消息。
|
||||
|
||||
<Info>
|
||||
如果你之前还没有构建过任何 OpenClaw 插件，请先阅读
|
||||
@ -26,47 +26,47 @@ x-i18n:
|
||||
|
||||
## 渠道插件如何工作
|
||||
|
||||
渠道插件不需要自带发送/编辑/回应工具。OpenClaw 在核心中保留了一个共享的 `message` 工具。你的插件负责：
|
||||
渠道插件不需要它们自己的发送/编辑/响应工具。OpenClaw 在核心中保留了一个共享的 `message` 工具。你的插件负责：
|
||||
|
||||
- **配置** — 账户解析和设置向导
|
||||
- **安全** — 私信策略和允许列表
|
||||
- **配对** — 私信批准流程
|
||||
- **会话语法** — 提供商特定的会话 ID 如何映射到底层聊天、线程 ID 和父级回退
|
||||
- **会话语法** — 提供商特定的会话 id 如何映射到基础聊天、线程 id 和父级回退
|
||||
- **出站** — 向平台发送文本、媒体和投票
|
||||
- **线程处理** — 回复如何在线程中传递
|
||||
- **线程处理** — 回复如何形成线程
|
||||
|
||||
核心负责共享消息工具、提示词接线、外层会话键形状、通用 `:thread:` 记录以及分发。
|
||||
核心负责共享的消息工具、提示词接线、外层会话键形状、通用的 `:thread:` 记录以及分发。
|
||||
|
||||
如果你的平台在会话 ID 中存储了额外作用域，请将该解析逻辑保留在插件中，并使用 `messaging.resolveSessionConversation(...)`。这是将 `rawId` 映射为基础会话 ID、可选线程 ID、显式 `baseConversationId` 以及任意 `parentConversationCandidates` 的规范钩子。
|
||||
当你返回 `parentConversationCandidates` 时，请按从最窄父级到最宽泛/基础会话的顺序排列。
|
||||
如果你的平台在会话 id 中存储了额外作用域，请将该解析逻辑保留在插件中，并使用 `messaging.resolveSessionConversation(...)`。这是将 `rawId` 映射到基础会话 id、可选线程 id、显式 `baseConversationId` 以及任何 `parentConversationCandidates` 的规范钩子。
|
||||
当你返回 `parentConversationCandidates` 时，请保持它们按从最窄父级到最宽/基础会话的顺序排列。
|
||||
|
||||
需要在渠道注册表启动前执行相同解析的内置插件，也可以暴露一个顶层 `session-key-api.ts` 文件，并提供匹配的 `resolveSessionConversation(...)` 导出。只有当运行时插件注册表尚不可用时，核心才会使用这个可安全用于启动流程的接口。
|
||||
需要在渠道注册表启动前进行相同解析的内置插件，也可以公开一个顶层 `session-key-api.ts` 文件，并导出匹配的 `resolveSessionConversation(...)`。只有在运行时插件注册表尚不可用时，核心才会使用这个可安全引导的表面。
|
||||
|
||||
当插件只需要在通用/raw ID 之上增加父级回退时，`messaging.resolveParentConversationCandidates(...)` 仍可作为旧版兼容回退方案使用。如果两个钩子都存在，核心会优先使用 `resolveSessionConversation(...).parentConversationCandidates`，仅在该规范钩子省略它们时，才回退到 `resolveParentConversationCandidates(...)`。
|
||||
当插件只需要在通用/raw id 之上提供父级回退时，`messaging.resolveParentConversationCandidates(...)` 仍可作为旧版兼容回退使用。如果两个钩子都存在，核心会优先使用 `resolveSessionConversation(...).parentConversationCandidates`，只有在该规范钩子省略它们时，才会回退到 `resolveParentConversationCandidates(...)`。
|
||||
|
||||
## 批准和渠道能力
|
||||
|
||||
大多数渠道插件不需要专门的批准代码。
|
||||
大多数渠道插件不需要特定于批准的代码。
|
||||
|
||||
- 核心负责同一聊天中的 `/approve`、共享批准按钮负载以及通用回退投递。
|
||||
- 当渠道需要批准专用行为时，优先在渠道插件上使用一个 `approvalCapability` 对象。
|
||||
- `approvalCapability.authorizeActorAction` 和 `approvalCapability.getActionAvailabilityState` 是规范的批准鉴权接口。
|
||||
- 如果你的渠道暴露原生 exec 批准，即使原生传输完全位于 `approvalCapability.native` 下，也要实现 `approvalCapability.getActionAvailabilityState`。核心使用该可用性钩子来区分 `enabled` 与 `disabled`，判断发起渠道是否支持原生批准，并在原生客户端回退指引中包含该渠道。
|
||||
- 当渠道需要特定于批准的行为时，优先在渠道插件上使用一个 `approvalCapability` 对象。
|
||||
- `approvalCapability.authorizeActorAction` 和 `approvalCapability.getActionAvailabilityState` 是规范的批准鉴权接缝。
|
||||
- 如果你的渠道公开原生 exec 批准，请实现 `approvalCapability.getActionAvailabilityState`，即使原生传输完全位于 `approvalCapability.native` 下也是如此。核心使用该可用性钩子来区分 `enabled` 与 `disabled`、判断发起渠道是否支持原生批准，并在原生客户端回退指引中包含该渠道。
|
||||
- 对于渠道特定的负载生命周期行为，例如隐藏重复的本地批准提示或在投递前发送输入中指示器，请使用 `outbound.shouldSuppressLocalPayloadPrompt` 或 `outbound.beforeDeliverPayload`。
|
||||
- 仅在进行原生批准路由或抑制回退时使用 `approvalCapability.delivery`。
|
||||
- 仅当某个渠道确实需要自定义批准负载而不是共享渲染器时，才使用 `approvalCapability.render`。
|
||||
- 当渠道希望在禁用路径回复中说明启用原生 exec 批准所需的确切配置项时，使用 `approvalCapability.describeExecApprovalSetup`。该钩子接收 `{ channel, channelLabel, accountId }`；具名账户渠道应渲染带账户作用域的路径，例如 `channels.<channel>.accounts.<id>.execApprovals.*`，而不是顶层默认值。
|
||||
- 如果一个渠道可以从现有配置中推断出稳定的、类似所有者的私信身份，请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createResolvedApproverActionAuthAdapter` 来限制同一聊天中的 `/approve`，而无需添加批准专用的核心逻辑。
|
||||
- 如果一个渠道需要原生批准投递，请让渠道代码专注于目标规范化和传输钩子。使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability` 和 `createChannelNativeApprovalRuntime`，这样核心就能负责请求过滤、路由、去重、过期和 Gateway 网关订阅。
|
||||
- 原生批准渠道必须通过这些辅助工具同时传递 `accountId` 和 `approvalKind`。`accountId` 可将多账户批准策略限定到正确的机器人账户，`approvalKind` 则让 exec 与插件批准行为在渠道中可用，而无需在核心中写死分支。
|
||||
- 端到端保留已投递的批准 ID 类型。原生客户端不应根据渠道本地状态去猜测或重写 exec 与插件批准路由。
|
||||
- 不同的批准类型可以有意暴露不同的原生接口。
|
||||
- 仅将 `approvalCapability.delivery` 用于原生批准路由或回退抑制。
|
||||
- 仅当渠道确实需要自定义批准负载而不是共享渲染器时，才使用 `approvalCapability.render`。
|
||||
- 当渠道希望禁用路径回复解释启用原生 exec 批准所需的确切配置项时，请使用 `approvalCapability.describeExecApprovalSetup`。该钩子接收 `{ channel, channelLabel, accountId }`；具名账户渠道应渲染账户作用域路径，例如 `channels.<channel>.accounts.<id>.execApprovals.*`，而不是顶层默认值。
|
||||
- 如果渠道可以从现有配置推断出稳定的类似所有者的私信身份，请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createResolvedApproverActionAuthAdapter` 来限制同一聊天中的 `/approve`，而无需添加特定于批准的核心逻辑。
|
||||
- 如果渠道需要原生批准投递，请让渠道代码专注于目标规范化和传输钩子。使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver`、`createApproverRestrictedNativeApprovalCapability` 和 `createChannelNativeApprovalRuntime`，这样核心就可以负责请求过滤、路由、去重、过期和 Gateway 网关订阅。
|
||||
- 原生批准渠道必须通过这些辅助函数同时路由 `accountId` 和 `approvalKind`。`accountId` 让多账户批准策略限定在正确的机器人账户范围内，而 `approvalKind` 让 exec 与插件批准行为在渠道中可用，而无需在核心中写死分支。
|
||||
- 在端到端过程中保留已投递的批准 id 类型。原生客户端不应根据渠道本地状态猜测或重写 exec 与插件批准路由。
|
||||
- 不同的批准类型可以有意公开不同的原生表面。
|
||||
当前内置示例：
|
||||
- Slack 对 exec 和插件 ID 都保留原生批准路由能力。
|
||||
- Matrix 仅为 exec 批准保留原生私信/渠道路由，而将插件批准保留在共享的同一聊天 `/approve` 路径上。
|
||||
- `createApproverRestrictedNativeApprovalAdapter` 仍作为兼容封装存在，但新代码应优先使用 capability 构建器，并在插件上暴露 `approvalCapability`。
|
||||
- Slack 为 exec 和插件 id 都保留原生批准路由。
|
||||
- Matrix 仅为 exec 批准保留原生私信/渠道路由，并将插件批准保留在共享的同一聊天 `/approve` 路径上。
|
||||
- `createApproverRestrictedNativeApprovalAdapter` 仍然作为兼容包装器存在，但新代码应优先使用能力构建器，并在插件上公开 `approvalCapability`。
|
||||
|
||||
对于高频渠道入口点，当你只需要这一系列中的某一部分时，优先使用更窄的运行时子路径：
|
||||
对于高频渠道入口点，如果你只需要该系列中的某一部分，请优先使用更窄的运行时子路径：
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
@ -74,60 +74,130 @@ x-i18n:
|
||||
- `openclaw/plugin-sdk/approval-native-runtime`
|
||||
- `openclaw/plugin-sdk/approval-reply-runtime`
|
||||
|
||||
同样地，当你不需要更宽泛的总入口接口时，优先使用 `openclaw/plugin-sdk/setup-runtime`、
|
||||
`openclaw/plugin-sdk/setup-adapter-runtime`、
|
||||
`openclaw/plugin-sdk/reply-runtime`、
|
||||
`openclaw/plugin-sdk/reply-dispatch-runtime`、
|
||||
`openclaw/plugin-sdk/reply-reference` 和
|
||||
`openclaw/plugin-sdk/reply-chunking`。
|
||||
同样地，当你不需要更宽泛的总括表面时，请优先使用 `openclaw/plugin-sdk/setup-runtime`、`openclaw/plugin-sdk/setup-adapter-runtime`、`openclaw/plugin-sdk/reply-runtime`、`openclaw/plugin-sdk/reply-dispatch-runtime`、`openclaw/plugin-sdk/reply-reference` 和 `openclaw/plugin-sdk/reply-chunking`。
|
||||
|
||||
特别是在设置方面：
|
||||
对于设置，具体来说：
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime` 覆盖运行时安全的设置辅助工具：
|
||||
可安全导入的设置补丁适配器（`createPatchedAccountSetupAdapter`、
|
||||
`createEnvPatchedAccountSetupAdapter`、
|
||||
`createSetupInputPresenceValidator`）、查找说明输出、
|
||||
`promptResolvedAllowFrom`、`splitSetupEntries`，以及委托式
|
||||
setup-proxy 构建器
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` 是面向环境变量的窄适配器接口，
|
||||
用于 `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` 覆盖可选安装设置
|
||||
构建器以及一些设置安全的基础能力：
|
||||
- `openclaw/plugin-sdk/setup-runtime` 覆盖运行时安全的设置辅助函数：
|
||||
导入安全的设置补丁适配器（`createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`）、查询说明输出、
|
||||
`promptResolvedAllowFrom`、`splitSetupEntries` 以及委托式 setup-proxy 构建器
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` 是面向环境变量的窄适配器接缝，用于 `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` 覆盖可选安装的设置构建器以及一些设置安全的基础能力：
|
||||
`createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、
|
||||
|
||||
如果你的渠道支持由环境变量驱动的设置或认证，并且通用启动/配置流程应在运行时加载前知道这些环境变量名称，请在插件清单中通过 `channelEnvVars` 声明它们。渠道运行时中的 `envVars` 或本地常量仅保留给面向运维人员的文案使用。
|
||||
如果你的渠道支持由环境变量驱动的设置或认证，并且通用启动/配置流程应在运行时加载前知道这些环境变量名称，请在插件清单中通过 `channelEnvVars` 声明它们。将渠道运行时 `envVars` 或本地常量仅用于面向操作员的文案。
|
||||
`createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、
|
||||
`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled` 和
|
||||
`splitSetupEntries`
|
||||
|
||||
- 仅当你还需要更重的共享设置/配置辅助工具时，才使用更宽泛的 `openclaw/plugin-sdk/setup` 接口，例如
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
- 仅当你还需要更重的共享设置/配置辅助函数，例如
|
||||
`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/inbound-reply-dispatch`，用于入站路由/封装以及记录与分发接线
|
||||
- `openclaw/plugin-sdk/messaging-targets`，用于目标解析/匹配
|
||||
- `openclaw/plugin-sdk/outbound-media` 和
|
||||
`openclaw/plugin-sdk/outbound-runtime`，用于媒体加载以及出站身份/发送委托
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime`，用于线程绑定生命周期和适配器注册
|
||||
- 仅当仍需要旧版智能体/媒体负载字段布局时，才使用 `openclaw/plugin-sdk/agent-media-payload`
|
||||
- `openclaw/plugin-sdk/telegram-command-config`，用于 Telegram 自定义命令规范化、重复/冲突校验，以及具备稳定回退能力的命令配置契约
|
||||
- 仅当仍然需要旧版智能体/媒体负载字段布局时，才使用 `openclaw/plugin-sdk/agent-media-payload`
|
||||
- `openclaw/plugin-sdk/telegram-command-config`，用于 Telegram 自定义命令规范化、重复/冲突校验，以及回退稳定的命令配置契约
|
||||
|
||||
仅认证渠道通常可以停留在默认路径：核心处理批准，而插件只需暴露出站/认证能力。像 Matrix、Slack、Telegram 以及自定义聊天传输这类原生批准渠道，应使用共享的原生辅助工具，而不是自行实现批准生命周期。
|
||||
仅认证渠道通常可以停留在默认路径：核心处理批准，插件只需公开出站/认证能力。像 Matrix、Slack、Telegram 和自定义聊天传输这类原生批准渠道，应使用共享的原生辅助函数，而不是自行实现批准生命周期。
|
||||
|
||||
## 操作演练
|
||||
## 入站提及策略
|
||||
|
||||
请将入站提及处理拆分为两层：
|
||||
|
||||
- 插件拥有的证据收集
|
||||
- 共享策略评估
|
||||
|
||||
共享层请使用 `openclaw/plugin-sdk/channel-inbound`。
|
||||
|
||||
适合放在插件本地逻辑中的内容：
|
||||
|
||||
- 回复机器人检测
|
||||
- 引用机器人检测
|
||||
- 线程参与检查
|
||||
- 服务/系统消息排除
|
||||
- 证明机器人参与所需的平台原生缓存
|
||||
|
||||
适合共享辅助函数处理的内容：
|
||||
|
||||
- `requireMention`
|
||||
- 显式提及结果
|
||||
- 隐式提及允许列表
|
||||
- 命令绕过
|
||||
- 最终跳过决策
|
||||
|
||||
推荐流程：
|
||||
|
||||
1. 计算本地提及事实。
|
||||
2. 将这些事实传给 `resolveInboundMentionDecision({ facts, policy })`。
|
||||
3. 在你的入站闸门中使用 `decision.effectiveWasMentioned`、`decision.shouldBypassMention` 和 `decision.shouldSkip`。
|
||||
|
||||
```typescript
|
||||
import {
|
||||
implicitMentionKindWhen,
|
||||
matchesMentionWithExplicit,
|
||||
resolveInboundMentionDecision,
|
||||
} from "openclaw/plugin-sdk/channel-inbound";
|
||||
|
||||
const mentionMatch = matchesMentionWithExplicit(text, {
|
||||
mentionRegexes,
|
||||
mentionPatterns,
|
||||
});
|
||||
|
||||
const facts = {
|
||||
canDetectMention: true,
|
||||
wasMentioned: mentionMatch.matched,
|
||||
hasAnyMention: mentionMatch.hasExplicitMention,
|
||||
implicitMentionKinds: [
|
||||
...implicitMentionKindWhen("reply_to_bot", isReplyToBot),
|
||||
...implicitMentionKindWhen("quoted_bot", isQuoteOfBot),
|
||||
],
|
||||
};
|
||||
|
||||
const decision = resolveInboundMentionDecision({
|
||||
facts,
|
||||
policy: {
|
||||
isGroup,
|
||||
requireMention,
|
||||
allowedImplicitMentionKinds: requireExplicitMention ? [] : ["reply_to_bot", "quoted_bot"],
|
||||
allowTextCommands,
|
||||
hasControlCommand,
|
||||
commandAuthorized,
|
||||
},
|
||||
});
|
||||
|
||||
if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
`api.runtime.channel.mentions` 为已经依赖运行时注入的内置渠道插件公开了同样的共享提及辅助函数：
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
- `matchesMentionWithExplicit`
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
较旧的 `resolveMentionGating*` 辅助函数仍保留在
|
||||
`openclaw/plugin-sdk/channel-inbound` 中，但仅作为兼容性导出。新代码应使用
|
||||
`resolveInboundMentionDecision({ facts, policy })`。
|
||||
|
||||
## 演练
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="包和清单">
|
||||
创建标准插件文件。`package.json` 中的 `channel` 字段会将它标记为渠道插件。有关完整的包元数据接口，请参见
|
||||
创建标准插件文件。`package.json` 中的 `channel` 字段决定了这是一个渠道插件。完整的包元数据表面请参见
|
||||
[插件设置和配置](/zh-CN/plugins/sdk-setup#openclawchannel)：
|
||||
|
||||
<CodeGroup>
|
||||
@ -178,7 +248,7 @@ x-i18n:
|
||||
</Step>
|
||||
|
||||
<Step title="构建渠道插件对象">
|
||||
`ChannelPlugin` 接口包含许多可选适配器接口。先从最小集合开始——`id` 和 `setup`——然后按需添加适配器。
|
||||
`ChannelPlugin` 接口有很多可选适配器表面。先从最小集合开始——`id` 和 `setup`——然后按需添加适配器。
|
||||
|
||||
创建 `src/channel.ts`：
|
||||
|
||||
@ -273,17 +343,17 @@ x-i18n:
|
||||
});
|
||||
```
|
||||
|
||||
<Accordion title="createChatChannelPlugin 为你完成了什么">
|
||||
你无需手动实现底层适配器接口，而是传入声明式选项，由构建器进行组合：
|
||||
<Accordion title="createChatChannelPlugin 为你做了什么">
|
||||
你无需手动实现底层适配器接口，而是传入声明式选项，由构建器负责组合它们：
|
||||
|
||||
| 选项 | 它负责接线的内容 |
|
||||
| 选项 | 它接线的内容 |
|
||||
| --- | --- |
|
||||
| `security.dm` | 从配置字段解析带作用域的私信安全策略 |
|
||||
| `pairing.text` | 通过验证码交换实现基于文本的私信配对流程 |
|
||||
| `threading` | 回复模式解析器（固定、账户作用域或自定义） |
|
||||
| `security.dm` | 从配置字段解析的作用域化私信安全解析器 |
|
||||
| `pairing.text` | 基于文本代码交换的私信配对流程 |
|
||||
| `threading` | reply-to 模式解析器（固定、账户作用域或自定义） |
|
||||
| `outbound.attachedResults` | 返回结果元数据（消息 ID）的发送函数 |
|
||||
|
||||
如果你需要完全控制，也可以直接传入原始适配器对象，而不是这些声明式选项。
|
||||
如果你需要完全控制，也可以传入原始适配器对象，而不是这些声明式选项。
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
@ -324,16 +394,15 @@ x-i18n:
|
||||
});
|
||||
```
|
||||
|
||||
将渠道自有的 CLI 描述符放在 `registerCliMetadata(...)` 中，这样 OpenClaw 就能在不激活完整渠道运行时的情况下，在根帮助中显示它们；而常规完整加载仍会获取相同描述符以进行真实命令注册。将 `registerFull(...)` 保留给仅运行时的工作。
|
||||
如果 `registerFull(...)` 注册 Gateway 网关 RPC 方法，请使用插件专属前缀。核心管理命名空间（`config.*`、
|
||||
`exec.approvals.*`、`wizard.*`、`update.*`）保留给系统使用，并始终解析为 `operator.admin`。
|
||||
将渠道拥有的 CLI 描述符放在 `registerCliMetadata(...)` 中，这样 OpenClaw 就能在不激活完整渠道运行时的情况下，在根帮助中显示它们；而正常完整加载时，仍会获取相同描述符来完成真实命令注册。将 `registerFull(...)` 保留给仅运行时工作。
|
||||
如果 `registerFull(...)` 注册 Gateway 网关 RPC 方法，请使用插件特定前缀。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并始终解析到 `operator.admin`。
|
||||
`defineChannelPluginEntry` 会自动处理注册模式拆分。有关所有选项，请参见
|
||||
[入口点](/zh-CN/plugins/sdk-entrypoints#definechannelpluginentry)。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="添加设置入口">
|
||||
创建 `setup-entry.ts`，用于新手引导期间的轻量加载：
|
||||
为新手引导期间的轻量加载创建 `setup-entry.ts`：
|
||||
|
||||
```typescript setup-entry.ts
|
||||
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -342,14 +411,13 @@ x-i18n:
|
||||
export default defineSetupPluginEntry(acmeChatPlugin);
|
||||
```
|
||||
|
||||
当渠道被禁用或尚未配置时，OpenClaw 会加载这个入口而不是完整入口。
|
||||
这样可以避免在设置流程中拉入沉重的运行时代码。详情请参见
|
||||
[设置和配置](/zh-CN/plugins/sdk-setup#setup-entry)。
|
||||
当渠道被禁用或尚未配置时，OpenClaw 会加载它，而不是完整入口点。
|
||||
这样可以避免在设置流程中拉取沉重的运行时代码。详情请参见 [设置和配置](/zh-CN/plugins/sdk-setup#setup-entry)。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="处理入站消息">
|
||||
你的插件需要从平台接收入站消息，并将其转发给 OpenClaw。典型模式是使用 webhook 校验请求，然后通过你的渠道入站处理器进行分发：
|
||||
你的插件需要从平台接收入站消息，并将它们转发给 OpenClaw。典型模式是使用一个 webhook 来验证请求，然后通过你的渠道入站处理器进行分发：
|
||||
|
||||
```typescript
|
||||
registerFull(api) {
|
||||
@ -373,15 +441,15 @@ x-i18n:
|
||||
```
|
||||
|
||||
<Note>
|
||||
入站消息处理是渠道特定的。每个渠道插件都负责自己的入站处理管线。请查看内置渠道插件
|
||||
（例如 Microsoft Teams 或 Google Chat 插件包）了解真实模式。
|
||||
入站消息处理是渠道特定的。每个渠道插件都拥有自己的入站流水线。请查看内置渠道插件
|
||||
（例如 Microsoft Teams 或 Google Chat 插件包）以了解真实模式。
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<a id="step-6-test"></a>
|
||||
<Step title="测试">
|
||||
编写同目录测试文件 `src/channel.test.ts`：
|
||||
编写同目录测试到 `src/channel.test.ts`：
|
||||
|
||||
```typescript src/channel.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
@ -419,7 +487,7 @@ x-i18n:
|
||||
pnpm test -- <bundled-plugin-root>/acme-chat/
|
||||
```
|
||||
|
||||
有关共享测试辅助工具，请参见[测试](/zh-CN/plugins/sdk-testing)。
|
||||
共享测试辅助函数请参见 [测试](/zh-CN/plugins/sdk-testing)。
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -453,19 +521,18 @@ x-i18n:
|
||||
<Card title="目标解析" icon="crosshair" href="/zh-CN/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType、looksLikeId、resolveTarget
|
||||
</Card>
|
||||
<Card title="运行时辅助工具" icon="settings" href="/zh-CN/plugins/sdk-runtime">
|
||||
TTS、STT、媒体、通过 api.runtime 使用 subagent
|
||||
<Card title="运行时辅助函数" icon="settings" href="/zh-CN/plugins/sdk-runtime">
|
||||
TTS、STT、媒体、通过 api.runtime 的子智能体
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
一些内置辅助接口仍然存在，用于内置插件维护和兼容性。
|
||||
它们不是新渠道插件的推荐模式；除非你正在直接维护该内置插件系列，否则请优先使用通用 SDK 接口中的 channel/setup/reply/runtime 子路径。
|
||||
一些内置辅助函数接缝仍然存在，用于内置插件维护和兼容性。它们不是新渠道插件的推荐模式；除非你是在直接维护该内置插件系列，否则请优先使用通用 SDK 表面中的 channel/setup/reply/runtime 子路径。
|
||||
</Note>
|
||||
|
||||
## 后续步骤
|
||||
|
||||
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 如果你的插件也提供模型
|
||||
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考
|
||||
- [SDK 测试](/zh-CN/plugins/sdk-testing) — 测试工具和契约测试
|
||||
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考
|
||||
- [插件 SDK 测试](/zh-CN/plugins/sdk-testing) — 测试工具和契约测试
|
||||
- [插件清单](/zh-CN/plugins/manifest) — 完整清单模式
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要知道应从哪个 SDK 子路径导入
|
||||
- 你想查看 OpenClawPluginApi 上所有注册方法的参考
|
||||
- 你想查阅 OpenClawPluginApi 上所有注册方法的参考
|
||||
- 你正在查找某个特定的 SDK 导出
|
||||
sidebarTitle: SDK Overview
|
||||
summary: 导入映射、注册 API 参考和 SDK 架构
|
||||
title: 插件 SDK 概览
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T06:41:32Z"
|
||||
generated_at: "2026-04-07T06:54:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: be651251bc1d8fc6548cb9efd4b7940be093f7f7cdd70d94dc31d5a1ebde80f3
|
||||
source_hash: 533bc3027ed8ad50b706518a4f58e75f6ef717fc8b36f242e928cae54d20985f
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 插件 SDK 概览
|
||||
|
||||
插件 SDK 是插件与核心之间的类型化契约。本页是关于**应导入什么**以及**你可以注册什么**的参考。
|
||||
插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考。
|
||||
|
||||
<Tip>
|
||||
**在找操作指南吗？**
|
||||
- 第一个插件？从[入门指南](/zh-CN/plugins/building-plugins)开始
|
||||
- 渠道插件？参见[渠道插件](/zh-CN/plugins/sdk-channel-plugins)
|
||||
- 提供商插件？参见[提供商插件](/zh-CN/plugins/sdk-provider-plugins)
|
||||
- 渠道插件？请参阅[渠道插件](/zh-CN/plugins/sdk-channel-plugins)
|
||||
- 提供商插件？请参阅[提供商插件](/zh-CN/plugins/sdk-provider-plugins)
|
||||
</Tip>
|
||||
|
||||
## 导入约定
|
||||
@ -35,19 +35,19 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
每个子路径都是一个小型、自包含的模块。这可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括性接口和共享辅助工具，例如 `buildChannelConfigSchema`。
|
||||
每个子路径都是一个小型、独立的模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括性接口和共享辅助工具，例如 `buildChannelConfigSchema`。
|
||||
|
||||
不要添加或依赖带有提供商名称的便捷接口层，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助接口层。内置插件应在自己的 `api.ts` 或 `runtime-api.ts` barrel 文件中组合通用 SDK 子路径，而核心则应使用这些插件本地的 barrel 文件，或者仅在需求确实跨渠道时添加一个狭义的通用 SDK 契约。
|
||||
不要添加或依赖带有提供商名称的便捷接口，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助接口。内置插件应在它们自己的 `api.ts` 或 `runtime-api.ts` barrel 文件中组合通用 SDK 子路径，而核心则应使用这些插件本地 barrel，或在需求确实跨渠道时添加一个窄范围的通用 SDK 契约。
|
||||
|
||||
生成的导出映射仍然包含一小部分内置插件辅助接口层，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅为内置插件维护和兼容性而存在；它们被有意省略在下面的常用表格之外，也不是新第三方插件的推荐导入路径。
|
||||
生成的导出映射仍包含一小组内置插件辅助接口，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅用于内置插件维护和兼容性；它们在下方的常用表格中被有意省略，也不是新的第三方插件推荐使用的导入路径。
|
||||
|
||||
## 子路径参考
|
||||
|
||||
最常用的子路径，按用途分组。包含 200 多个子路径的生成完整列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。
|
||||
最常用的子路径，按用途分组。包含 200 多个子路径的完整生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。
|
||||
|
||||
保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其作为公共接口推广，否则应将其视为实现细节/兼容性接口。
|
||||
保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其作为公共接口推广，否则请将它们视为实现细节/兼容性接口。
|
||||
|
||||
### 插件入口点
|
||||
### 插件入口
|
||||
|
||||
| 子路径 | 关键导出 |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@ -62,127 +62,127 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | 共享的设置向导辅助工具、allowlist 提示、设置状态构建器 |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`、`noteChannelLookupFailure`、`noteChannelLookupSummary`、`promptResolvedAllowFrom`、`splitSetupEntries`、`createAllowlistSetupWizardProxy`、`createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | 多账户配置/操作门控辅助工具、默认账户回退辅助工具 |
|
||||
| `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-helpers` | 窄范围的账户列表/账户操作辅助工具 |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，带内置契约回退 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/验证辅助工具，带内置契约回退 |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 |
|
||||
| `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助工具 |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助工具 |
|
||||
| `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 |
|
||||
| `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 |
|
||||
| `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助工具 |
|
||||
| `plugin-sdk/outbound-runtime` | 出站身份/发送委托辅助工具 |
|
||||
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 |
|
||||
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期与适配器辅助工具 |
|
||||
| `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 |
|
||||
| `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助工具 |
|
||||
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 |
|
||||
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 |
|
||||
| `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助工具 |
|
||||
| `plugin-sdk/channel-config-primitives` | 狭义渠道配置 schema 基元 |
|
||||
| `plugin-sdk/channel-status` | 共享的渠道状态快照/摘要辅助工具 |
|
||||
| `plugin-sdk/channel-config-primitives` | 窄范围的渠道配置 schema 基元 |
|
||||
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 |
|
||||
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
|
||||
| `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出 |
|
||||
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 |
|
||||
| `plugin-sdk/group-access` | 共享群组访问决策辅助工具 |
|
||||
| `plugin-sdk/direct-dm` | 共享直接私信凭证/保护辅助工具 |
|
||||
| `plugin-sdk/group-access` | 共享的群组访问决策辅助工具 |
|
||||
| `plugin-sdk/direct-dm` | 共享的直接私信认证/保护辅助工具 |
|
||||
| `plugin-sdk/interactive-runtime` | 交互式回复负载规范化/归约辅助工具 |
|
||||
| `plugin-sdk/channel-inbound` | 去抖动、提及匹配、envelope 辅助工具 |
|
||||
| `plugin-sdk/channel-inbound` | 入站防抖、提及匹配、提及策略辅助工具，以及 envelope 辅助工具 |
|
||||
| `plugin-sdk/channel-send-result` | 回复结果类型 |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`、`createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 |
|
||||
| `plugin-sdk/channel-contract` | 渠道契约类型 |
|
||||
| `plugin-sdk/channel-feedback` | 反馈/反应接线 |
|
||||
| `plugin-sdk/channel-secret-runtime` | 狭义 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` 和 secret target 类型 |
|
||||
| `plugin-sdk/channel-secret-runtime` | 窄范围的密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="提供商子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/provider-setup` | 精选本地/自托管提供商设置辅助工具 |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管提供商的设置辅助工具 |
|
||||
| `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商设置的聚焦辅助工具 |
|
||||
| `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
|
||||
| `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API key 解析辅助工具 |
|
||||
| `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助工具，例如 `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 |
|
||||
| `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助工具 |
|
||||
| `plugin-sdk/provider-env-vars` | 提供商凭证环境变量查找辅助工具 |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | 通用提供商 HTTP/endpoint 能力辅助工具 |
|
||||
| `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助工具 |
|
||||
| `plugin-sdk/provider-web-search-contract` | 狭义 Web 搜索配置/凭证契约辅助工具，例如 `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter/getter |
|
||||
| `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API 密钥解析辅助工具 |
|
||||
| `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/profile 写入辅助工具，例如 `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 |
|
||||
| `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助工具 |
|
||||
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`、`ensureApiKeyFromOptionEnvOrPrompt`、`upsertAuthProfile`、`upsertApiKeyProfile`、`writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助工具，以及像 `normalizeNativeXaiModelId` 这样的模型 ID 规范化辅助工具 |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具 |
|
||||
| `plugin-sdk/provider-web-fetch` | Web 抓取提供商注册/缓存辅助工具 |
|
||||
| `plugin-sdk/provider-web-search-contract` | 窄范围的 Web 搜索配置/凭证契约辅助工具，例如 `enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域凭证 setter/getter |
|
||||
| `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/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
|
||||
| `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/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
|
||||
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 |
|
||||
| `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="凭证与安全子路径">
|
||||
<Accordion title="认证与安全子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 |
|
||||
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作鉴权辅助工具 |
|
||||
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助工具 |
|
||||
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天动作认证辅助工具 |
|
||||
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤辅助工具 |
|
||||
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 |
|
||||
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 |
|
||||
| `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助工具 |
|
||||
| `plugin-sdk/command-auth-native` | 原生命令鉴权 + 原生会话目标辅助工具 |
|
||||
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 |
|
||||
| `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
|
||||
| `plugin-sdk/command-surface` | 命令体规范化和命令表层辅助工具 |
|
||||
| `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助工具 |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | 面向渠道/插件 secret 表层的狭义 secret 契约收集辅助工具 |
|
||||
| `plugin-sdk/secret-ref-runtime` | 狭义 `coerceSecretRef` 和用于 secret 契约/配置解析的 SecretRef 类型辅助工具 |
|
||||
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助工具 |
|
||||
| `plugin-sdk/channel-secret-runtime` | 用于渠道/插件密钥接口的窄范围密钥契约收集辅助工具 |
|
||||
| `plugin-sdk/secret-ref-runtime` | 用于密钥契约/配置解析的窄范围 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
|
||||
| `plugin-sdk/security-runtime` | 共享的信任、私信门控、外部内容和密钥收集辅助工具 |
|
||||
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 |
|
||||
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、SSRF 保护 fetch 和 SSRF 策略辅助工具 |
|
||||
| `plugin-sdk/secret-input` | secret 输入解析辅助工具 |
|
||||
| `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具 |
|
||||
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助工具 |
|
||||
| `plugin-sdk/secret-input` | 密钥输入解析辅助工具 |
|
||||
| `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助工具 |
|
||||
| `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="运行时与存储子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | 广义运行时/日志/备份/插件安装辅助工具 |
|
||||
| `plugin-sdk/runtime-env` | 狭义运行时 env、logger、timeout、retry 和 backoff 辅助工具 |
|
||||
| `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助工具 |
|
||||
| `plugin-sdk/runtime-env` | 窄范围的运行时环境、logger、超时、重试和回退辅助工具 |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/交互式辅助工具 |
|
||||
| `plugin-sdk/hook-runtime` | 共享 webhook/internal hook 管道辅助工具 |
|
||||
| `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 管道辅助工具 |
|
||||
| `plugin-sdk/lazy-runtime` | 延迟运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | 进程 exec 辅助工具 |
|
||||
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 |
|
||||
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 |
|
||||
| `plugin-sdk/config-runtime` | 配置加载/写入辅助工具 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约表层不可用时也是如此 |
|
||||
| `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、鉴权/profile 辅助工具、原生路由/运行时辅助工具 |
|
||||
| `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、heartbeat、回复规划器 |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | 狭义回复分发/完成辅助工具 |
|
||||
| `plugin-sdk/reply-history` | 共享短时间窗口回复历史辅助工具，例如 `buildHistoryContext`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约接口不可用时也是如此 |
|
||||
| `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/profile 辅助工具、原生路由/运行时辅助工具 |
|
||||
| `plugin-sdk/reply-runtime` | 共享的入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | 窄范围的回复分发/完成辅助工具 |
|
||||
| `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | 狭义文本/Markdown 分块辅助工具 |
|
||||
| `plugin-sdk/reply-chunking` | 窄范围的文本/Markdown 分块辅助工具 |
|
||||
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 |
|
||||
| `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 |
|
||||
| `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助工具、运行时状态默认值和问题元数据辅助工具 |
|
||||
| `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | 共享的渠道/账户状态摘要辅助工具、运行时状态默认值和问题元数据辅助工具 |
|
||||
| `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 |
|
||||
| `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助工具 |
|
||||
| `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL |
|
||||
| `plugin-sdk/run-command` | 带定时功能的命令运行器，输出已规范化的 stdout/stderr 结果 |
|
||||
| `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 |
|
||||
| `plugin-sdk/run-command` | 带定时的命令运行器，输出已规范化的 stdout/stderr 结果 |
|
||||
| `plugin-sdk/param-readers` | 常用工具/CLI 参数读取器 |
|
||||
| `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 |
|
||||
| `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 |
|
||||
| `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 |
|
||||
@ -190,24 +190,24 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 |
|
||||
| `plugin-sdk/file-lock` | 可重入文件锁辅助工具 |
|
||||
| `plugin-sdk/persistent-dedupe` | 基于磁盘的去重缓存辅助工具 |
|
||||
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和 reply-dispatch 辅助工具 |
|
||||
| `plugin-sdk/agent-config-primitives` | 狭义智能体运行时配置 schema 基元 |
|
||||
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 |
|
||||
| `plugin-sdk/agent-config-primitives` | 窄范围的智能体运行时配置 schema 基元 |
|
||||
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
|
||||
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 |
|
||||
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 |
|
||||
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 |
|
||||
| `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 |
|
||||
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
|
||||
| `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助工具 |
|
||||
| `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助工具 |
|
||||
| `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助工具 |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 |
|
||||
| `plugin-sdk/infra-runtime` | 系统事件/心跳辅助工具 |
|
||||
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 |
|
||||
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 |
|
||||
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和 pinned lookup 辅助工具 |
|
||||
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具，`isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | 包装过的 fetch、代理和 pinned 查找辅助工具 |
|
||||
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
|
||||
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 |
|
||||
| `plugin-sdk/agent-runtime` | 智能体目录/身份/workspace 辅助工具 |
|
||||
| `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 |
|
||||
| `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
@ -216,105 +216,105 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具以及媒体负载构建器 |
|
||||
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型提示 |
|
||||
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 |
|
||||
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如 assistant-visible-text 剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 |
|
||||
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型提示信息 |
|
||||
| `plugin-sdk/media-understanding` | 媒体理解提供商类型以及面向提供商的图像/音频辅助工具导出 |
|
||||
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如去除对助手可见的文本、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具和安全文本工具 |
|
||||
| `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
|
||||
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 |
|
||||
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助工具 |
|
||||
| `plugin-sdk/speech` | 语音提供商类型以及面向提供商的指令、注册表和验证辅助工具 |
|
||||
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、指令和规范化辅助工具 |
|
||||
| `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助工具 |
|
||||
| `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 |
|
||||
| `plugin-sdk/image-generation` | 图像生成提供商类型 |
|
||||
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、鉴权和注册表辅助工具 |
|
||||
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助工具 |
|
||||
| `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 |
|
||||
| `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 |
|
||||
| `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 |
|
||||
| `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 |
|
||||
| `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助工具 |
|
||||
| `plugin-sdk/webhook-path` | Webhook 路径规范化辅助工具 |
|
||||
| `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助工具 |
|
||||
| `plugin-sdk/webhook-path` | webhook 路径规范化辅助工具 |
|
||||
| `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助工具 |
|
||||
| `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
|
||||
| `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory 子路径">
|
||||
<Accordion title="记忆子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于 manager/config/file/CLI 辅助工具 |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时门面 |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding engine 导出 |
|
||||
| `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 secret 辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 |
|
||||
| `plugin-sdk/memory-host-core` | 面向供应商中立的 memory host 核心运行时辅助工具别名 |
|
||||
| `plugin-sdk/memory-host-events` | 面向供应商中立的 memory host 事件日志辅助工具别名 |
|
||||
| `plugin-sdk/memory-host-files` | 面向供应商中立的 memory host 文件/运行时辅助工具别名 |
|
||||
| `plugin-sdk/memory-host-markdown` | 面向 Memory 邻接插件的共享托管 Markdown 辅助工具 |
|
||||
| `plugin-sdk/memory-host-search` | 用于 search-manager 访问的 active memory 运行时门面 |
|
||||
| `plugin-sdk/memory-host-status` | 面向供应商中立的 memory host 状态辅助工具别名 |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | 记忆索引/搜索运行时门面 |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | 记忆主机 foundation engine 导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | 记忆主机嵌入 engine 导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | 记忆主机 QMD engine 导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | 记忆主机存储 engine 导出 |
|
||||
| `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` | 记忆主机状态辅助工具 |
|
||||
| `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` | 面向供应商中立的记忆主机状态辅助工具别名 |
|
||||
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="保留的内置辅助子路径">
|
||||
| 家族 | 当前子路径 | 预期用途 |
|
||||
| 系列 | 当前子路径 | 预期用途 |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 browser 插件支持辅助工具（`browser-support` 仍是兼容性 barrel） |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时接口 |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时接口 |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 |
|
||||
| 特定于渠道的辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助接口 |
|
||||
| 鉴权/特定于插件的辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
|
||||
| Browser | `plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` | 内置浏览器插件支持辅助工具（`browser-support` 仍是兼容性 barrel） |
|
||||
| Matrix | `plugin-sdk/matrix`、`plugin-sdk/matrix-helper`、`plugin-sdk/matrix-runtime-heavy`、`plugin-sdk/matrix-runtime-shared`、`plugin-sdk/matrix-runtime-surface`、`plugin-sdk/matrix-surface`、`plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时接口 |
|
||||
| Line | `plugin-sdk/line`、`plugin-sdk/line-core`、`plugin-sdk/line-runtime`、`plugin-sdk/line-surface` | 内置 LINE 辅助/运行时接口 |
|
||||
| IRC | `plugin-sdk/irc`、`plugin-sdk/irc-surface` | 内置 IRC 辅助接口 |
|
||||
| 渠道专用辅助工具 | `plugin-sdk/googlechat`、`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles`、`plugin-sdk/bluebubbles-policy`、`plugin-sdk/mattermost`、`plugin-sdk/mattermost-policy`、`plugin-sdk/feishu-conversation`、`plugin-sdk/msteams`、`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、`plugin-sdk/twitch` | 内置渠道兼容性/辅助接口 |
|
||||
| 认证/插件专用辅助工具 | `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、`plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`、`plugin-sdk/voice-call` | 内置功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 注册 API
|
||||
|
||||
`register(api)` 回调会收到一个带有这些方法的 `OpenClawPluginApi` 对象：
|
||||
`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，包含以下方法：
|
||||
|
||||
### 能力注册
|
||||
|
||||
| 方法 | 注册内容 |
|
||||
| ------------------------------------------------ | -------------------------------- |
|
||||
| `api.registerProvider(...)` | 文本推理（LLM） |
|
||||
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
|
||||
| `api.registerChannel(...)` | 消息渠道 |
|
||||
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
|
||||
| `api.registerProvider(...)` | 文本推理（LLM） |
|
||||
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
|
||||
| `api.registerChannel(...)` | 消息渠道 |
|
||||
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
|
||||
| `api.registerImageGenerationProvider(...)` | 图像生成 |
|
||||
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
|
||||
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
|
||||
| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 |
|
||||
| `api.registerWebSearchProvider(...)` | Web 搜索 |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
|
||||
| `api.registerImageGenerationProvider(...)` | 图像生成 |
|
||||
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
|
||||
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
|
||||
| `api.registerWebFetchProvider(...)` | Web 抓取 / 爬取提供商 |
|
||||
| `api.registerWebSearchProvider(...)` | Web 搜索 |
|
||||
|
||||
### 工具和命令
|
||||
|
||||
| 方法 | 注册内容 |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | 智能体工具（必需，或 `{ optional: true }`） |
|
||||
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
|
||||
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
|
||||
|
||||
### 基础设施
|
||||
|
||||
| 方法 | 注册内容 |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | 事件 hook |
|
||||
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP endpoint |
|
||||
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
|
||||
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
|
||||
| `api.registerService(service)` | 后台服务 |
|
||||
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | 追加式 Memory 邻接提示区段 |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | 追加式 Memory 搜索/读取语料 |
|
||||
| `api.registerHook(events, handler, opts?)` | 事件 hook |
|
||||
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 |
|
||||
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
|
||||
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
|
||||
| `api.registerService(service)` | 后台服务 |
|
||||
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | 增量式记忆相关提示词区段 |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | 增量式记忆搜索/读取语料库 |
|
||||
|
||||
保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用特定于插件的前缀。
|
||||
|
||||
@ -322,10 +322,10 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
|
||||
`api.registerCli(registrar, opts?)` 接受两类顶层元数据：
|
||||
|
||||
- `commands`：由该 registrar 拥有的显式命令根
|
||||
- `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析期命令描述符
|
||||
- `commands`：由 registrar 拥有的显式命令根
|
||||
- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析时命令描述符
|
||||
|
||||
如果你希望插件命令在普通根 CLI 路径中保持惰性加载，请提供覆盖该 registrar 暴露的每个顶层命令根的 `descriptors`。
|
||||
如果你希望插件命令在普通根 CLI 路径中保持延迟加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -337,7 +337,7 @@ api.registerCli(
|
||||
descriptors: [
|
||||
{
|
||||
name: "matrix",
|
||||
description: "管理 Matrix 账户、验证、设备和个人资料状态",
|
||||
description: "管理 Matrix 账户、验证、设备和配置文件状态",
|
||||
hasSubcommands: true,
|
||||
},
|
||||
],
|
||||
@ -345,7 +345,7 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
仅在你不需要惰性根 CLI 注册时单独使用 `commands`。这种急切兼容路径仍受支持，但它不会为解析期惰性加载安装基于 descriptor 的占位符。
|
||||
仅在你不需要延迟根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会为解析时延迟加载安装基于 descriptor 的占位符。
|
||||
|
||||
### CLI 后端注册
|
||||
|
||||
@ -353,83 +353,83 @@ api.registerCli(
|
||||
|
||||
- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。
|
||||
- 后端 `config` 使用与 `agents.defaults.cliBackends.<id>` 相同的结构。
|
||||
- 用户配置仍然优先生效。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上。
|
||||
- 当后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧版 flag 结构）。
|
||||
- 用户配置仍然优先。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上。
|
||||
- 当某个后端在合并后需要兼容性重写时，请使用 `normalizeConfig`（例如规范化旧版 flag 结构）。
|
||||
|
||||
### 独占槽位
|
||||
|
||||
| 方法 | 注册内容 |
|
||||
| ------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只能激活一个） |
|
||||
| `api.registerMemoryPromptSection(builder)` | Memory 提示区段构建器 |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 |
|
||||
| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 |
|
||||
| `api.registerContextEngine(id, factory)` | 上下文引擎（同一时间仅一个处于活动状态） |
|
||||
| `api.registerMemoryPromptSection(builder)` | 记忆提示词区段构建器 |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | 记忆刷新计划解析器 |
|
||||
| `api.registerMemoryRuntime(runtime)` | 记忆运行时适配器 |
|
||||
|
||||
### Memory embedding 适配器
|
||||
### 记忆嵌入适配器
|
||||
|
||||
| 方法 | 注册内容 |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | 用于活动插件的 Memory embedding 适配器 |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的记忆嵌入适配器 |
|
||||
|
||||
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 仅适用于 Memory 插件。
|
||||
- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个 embedding adapter ID（例如 `openai`、`gemini` 或自定义插件定义的 ID）。
|
||||
- 用户配置，例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`，会根据这些已注册的 adapter ID 进行解析。
|
||||
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是记忆插件专属的独占项。
|
||||
- `registerMemoryEmbeddingProvider` 允许活动记忆插件注册一个或多个嵌入适配器 ID（例如 `openai`、`gemini` 或自定义插件定义的 ID）。
|
||||
- 用户配置，例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`，会根据这些已注册的适配器 ID 进行解析。
|
||||
|
||||
### 事件与生命周期
|
||||
### 事件和生命周期
|
||||
|
||||
| 方法 | 作用 |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
|
||||
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
|
||||
| `api.onConversationBindingResolved(handler)` | 会话绑定回调 |
|
||||
|
||||
### Hook 决策语义
|
||||
|
||||
- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任何处理器设置了它，就会跳过更低优先级的处理器。
|
||||
- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
|
||||
- `before_install`：返回 `{ block: true }` 是终止性的。一旦任何处理器设置了它，就会跳过更低优先级的处理器。
|
||||
- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
|
||||
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任何处理器声明接管分发，就会跳过更低优先级的处理器和默认模型分发路径。
|
||||
- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任何处理器设置了它，就会跳过更低优先级的处理器。
|
||||
- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。
|
||||
- `before_tool_call`：返回 `{ block: true }` 为终止性结果。一旦任何处理器设置该值，将跳过更低优先级的处理器。
|
||||
- `before_tool_call`：返回 `{ block: false }` 会被视为未作决策（与省略 `block` 相同），而不是覆盖。
|
||||
- `before_install`：返回 `{ block: true }` 为终止性结果。一旦任何处理器设置该值，将跳过更低优先级的处理器。
|
||||
- `before_install`：返回 `{ block: false }` 会被视为未作决策（与省略 `block` 相同），而不是覆盖。
|
||||
- `reply_dispatch`：返回 `{ handled: true, ... }` 为终止性结果。一旦任何处理器声明已分发，将跳过更低优先级的处理器和默认模型分发路径。
|
||||
- `message_sending`：返回 `{ cancel: true }` 为终止性结果。一旦任何处理器设置该值，将跳过更低优先级的处理器。
|
||||
- `message_sending`：返回 `{ cancel: false }` 会被视为未作决策（与省略 `cancel` 相同），而不是覆盖。
|
||||
|
||||
### API 对象字段
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | 插件 ID |
|
||||
| `api.name` | `string` | 显示名称 |
|
||||
| `api.version` | `string?` | 插件版本（可选） |
|
||||
| `api.description` | `string?` | 插件描述（可选） |
|
||||
| `api.source` | `string` | 插件源路径 |
|
||||
| `api.rootDir` | `string?` | 插件根目录（可选） |
|
||||
| `api.config` | `OpenClawConfig` | 当前配置快照（如可用，则为活动的内存中运行时快照） |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
|
||||
| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | 作用域化 logger（`debug`、`info`、`warn`、`error`） |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量窗口 |
|
||||
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
|
||||
| `api.id` | `string` | 插件 ID |
|
||||
| `api.name` | `string` | 显示名称 |
|
||||
| `api.version` | `string?` | 插件版本（可选） |
|
||||
| `api.description` | `string?` | 插件描述（可选） |
|
||||
| `api.source` | `string` | 插件源路径 |
|
||||
| `api.rootDir` | `string?` | 插件根目录（可选） |
|
||||
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动内存运行时快照） |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
|
||||
| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口前的轻量预启动/设置窗口 |
|
||||
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
|
||||
|
||||
## 内部模块约定
|
||||
|
||||
在你的插件内部，使用本地 barrel 文件进行内部导入：
|
||||
在你的插件内部，请使用本地 barrel 文件进行内部导入：
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # 供外部使用者使用的公共导出
|
||||
api.ts # 面向外部使用方的公共导出
|
||||
runtime-api.ts # 仅供内部使用的运行时导出
|
||||
index.ts # 插件入口点
|
||||
setup-entry.ts # 仅设置用的轻量入口点（可选）
|
||||
setup-entry.ts # 轻量级仅设置入口（可选）
|
||||
```
|
||||
|
||||
<Warning>
|
||||
永远不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>`
|
||||
导入你自己的插件。内部导入应通过 `./api.ts` 或
|
||||
`./runtime-api.ts`。SDK 路径仅是外部契约。
|
||||
不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>` 导入你自己的插件。
|
||||
请通过 `./api.ts` 或 `./runtime-api.ts` 处理内部导入。
|
||||
SDK 路径仅是对外契约。
|
||||
</Warning>
|
||||
|
||||
由门面加载的内置插件公共接口（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似公共入口文件）现在在 OpenClaw 已运行时会优先使用活动的运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上已解析的配置文件。
|
||||
由门面加载的内置插件公共接口（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）现在会在 OpenClaw 已经运行时优先使用活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上解析得到的配置文件。
|
||||
|
||||
当某个辅助工具有意特定于提供商、且暂时不属于通用 SDK 子路径时，提供商插件也可以暴露一个狭义的插件本地契约 barrel。当前内置示例：Anthropic 提供商将其 Claude 流辅助工具保留在自己的公共 `api.ts` / `contract-api.ts` 接口层中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升到通用 `plugin-sdk/*` 契约中。
|
||||
如果某个辅助工具明确是提供商专用，且尚不适合放入通用 SDK 子路径中，提供商插件也可以暴露一个窄范围的插件本地契约 barrel。当前内置示例：Anthropic 提供商将其 Claude 流辅助工具保留在自己的公共 `api.ts` / `contract-api.ts` 接口中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升为通用 `plugin-sdk/*` 契约。
|
||||
|
||||
其他当前内置示例：
|
||||
|
||||
@ -437,17 +437,17 @@ my-plugin/
|
||||
- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/配置辅助工具
|
||||
|
||||
<Warning>
|
||||
扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。
|
||||
如果某个辅助工具确实需要共享，请将它提升到中立的 SDK 子路径，
|
||||
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他
|
||||
面向能力的接口，而不是将两个插件耦合在一起。
|
||||
扩展生产代码也应避免使用 `openclaw/plugin-sdk/<other-plugin>` 导入。
|
||||
如果某个辅助工具确实需要共享，应将其提升到中立的 SDK 子路径，
|
||||
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他
|
||||
面向能力的接口，而不是让两个插件彼此耦合。
|
||||
</Warning>
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` 选项
|
||||
- [运行时辅助工具](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考
|
||||
- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、manifest 和配置 schema
|
||||
- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema
|
||||
- [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则
|
||||
- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用接口迁移
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构和能力模型
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) — 深入的架构与能力模型
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要从插件中调用 core 辅助工具（TTS、STT、图像生成、Web 搜索、子智能体）
|
||||
- 你想了解 api.runtime 暴露了什么
|
||||
- 你正在从插件代码中访问配置、智能体或媒体辅助工具
|
||||
- 当你需要从插件调用核心辅助工具时（TTS、STT、图像生成、Web 搜索、subagent）
|
||||
- 当你想了解 api.runtime 暴露了什么内容时
|
||||
- 当你在插件代码中访问 config、智能体或媒体辅助工具时
|
||||
sidebarTitle: Runtime Helpers
|
||||
summary: api.runtime —— 注入到插件中的可用运行时辅助工具
|
||||
summary: api.runtime —— 在插件中可用的注入式运行时辅助工具
|
||||
title: 插件运行时辅助工具
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T08:40:23Z"
|
||||
generated_at: "2026-04-07T06:53:16Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 667edff734fd30f9b05d55eae6360830a45ae8f3012159f88a37b5e05404e666
|
||||
source_hash: acb9e56678e9ed08d0998dfafd7cd1982b592be5bc34d9e2d2c1f70274f8f248
|
||||
source_path: plugins/sdk-runtime.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 插件运行时辅助工具
|
||||
|
||||
这是在注册期间注入到每个插件中的 `api.runtime` 对象参考。请使用这些辅助工具，而不是直接导入宿主内部实现。
|
||||
这是对在注册期间注入到每个插件中的 `api.runtime` 对象的参考说明。请使用这些辅助工具，而不是直接导入宿主内部实现。
|
||||
|
||||
<Tip>
|
||||
**想看操作演练？** 请参见 [渠道插件](/plugins/sdk-channel-plugins)
|
||||
或 [提供商插件](/plugins/sdk-provider-plugins)，其中提供了分步指南，
|
||||
展示了这些辅助工具在实际场景中的用法。
|
||||
**想看操作演示？** 请参阅 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)
|
||||
或 [提供商插件](/zh-CN/plugins/sdk-provider-plugins) 中的分步指南，
|
||||
它们会结合上下文展示这些辅助工具的用法。
|
||||
</Tip>
|
||||
|
||||
```typescript
|
||||
@ -88,7 +88,7 @@ const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"
|
||||
|
||||
### `api.runtime.subagent`
|
||||
|
||||
启动和管理后台子智能体运行。
|
||||
启动并管理后台 subagent 运行。
|
||||
|
||||
```typescript
|
||||
// Start a subagent run
|
||||
@ -116,15 +116,15 @@ await api.runtime.subagent.deleteSession({
|
||||
```
|
||||
|
||||
<Warning>
|
||||
模型覆盖（`provider`/`model`）需要操作员通过配置中的
|
||||
模型覆盖（`provider`/`model`）需要操作员在 config 中通过
|
||||
`plugins.entries.<id>.subagent.allowModelOverride: true` 明确启用。
|
||||
不受信任的插件仍然可以运行子智能体，但覆盖请求会被拒绝。
|
||||
不受信任的插件仍然可以运行 subagent，但其覆盖请求会被拒绝。
|
||||
</Warning>
|
||||
|
||||
### `api.runtime.taskFlow`
|
||||
|
||||
将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具
|
||||
上下文，然后在每次调用时无需传入 owner 即可创建和管理 Task Flows。
|
||||
将 Task Flow 运行时绑定到现有的 OpenClaw 会话键或受信任的工具上下文，
|
||||
然后在每次调用时无需传入 owner，即可创建和管理 Task Flows。
|
||||
|
||||
```typescript
|
||||
const taskFlow = api.runtime.taskFlow.fromToolContext(ctx);
|
||||
@ -151,9 +151,8 @@ const waiting = taskFlow.setWaiting({
|
||||
});
|
||||
```
|
||||
|
||||
当你已经从自己的绑定层获得了受信任的 OpenClaw 会话键时，请使用
|
||||
`bindSession({ sessionKey, requesterOrigin })`。不要从原始
|
||||
用户输入进行绑定。
|
||||
当你已经从自己的绑定层获得一个受信任的 OpenClaw 会话键时，请使用
|
||||
`bindSession({ sessionKey, requesterOrigin })`。不要从原始用户输入进行绑定。
|
||||
|
||||
### `api.runtime.tts`
|
||||
|
||||
@ -179,8 +178,7 @@ const voices = await api.runtime.tts.listVoices({
|
||||
});
|
||||
```
|
||||
|
||||
使用 core 的 `messages.tts` 配置和提供商选择。返回 PCM 音频
|
||||
缓冲区 + 采样率。
|
||||
使用核心 `messages.tts` 配置和提供商选择。返回 PCM 音频缓冲区和采样率。
|
||||
|
||||
### `api.runtime.mediaUnderstanding`
|
||||
|
||||
@ -214,11 +212,11 @@ const result = await api.runtime.mediaUnderstanding.runFile({
|
||||
});
|
||||
```
|
||||
|
||||
当没有产生输出时，返回 `{ text: undefined }`（例如输入被跳过时）。
|
||||
当未生成输出时（例如输入被跳过），返回 `{ text: undefined }`。
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)` 仍然作为
|
||||
`api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容别名保留。
|
||||
`api.runtime.stt.transcribeAudioFile(...)` 仍保留为
|
||||
`api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容别名。
|
||||
</Info>
|
||||
|
||||
### `api.runtime.imageGeneration`
|
||||
@ -249,7 +247,7 @@ const result = await api.runtime.webSearch.search({
|
||||
|
||||
### `api.runtime.media`
|
||||
|
||||
底层媒体工具。
|
||||
底层媒体实用工具。
|
||||
|
||||
```typescript
|
||||
const webMedia = await api.runtime.media.loadWebMedia(url);
|
||||
@ -262,7 +260,7 @@ const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 });
|
||||
|
||||
### `api.runtime.config`
|
||||
|
||||
配置加载和写入。
|
||||
Config 加载和写入。
|
||||
|
||||
```typescript
|
||||
const cfg = await api.runtime.config.loadConfig();
|
||||
@ -271,7 +269,7 @@ await api.runtime.config.writeConfigFile(cfg);
|
||||
|
||||
### `api.runtime.system`
|
||||
|
||||
系统级工具。
|
||||
系统级实用工具。
|
||||
|
||||
```typescript
|
||||
await api.runtime.system.enqueueSystemEvent(event);
|
||||
@ -295,7 +293,7 @@ api.runtime.events.onSessionTranscriptUpdate((update) => {
|
||||
|
||||
### `api.runtime.logging`
|
||||
|
||||
日志。
|
||||
日志记录。
|
||||
|
||||
```typescript
|
||||
const verbose = api.runtime.logging.shouldLogVerbose();
|
||||
@ -324,7 +322,7 @@ const stateDir = api.runtime.state.resolveStateDir();
|
||||
|
||||
### `api.runtime.tools`
|
||||
|
||||
Memory 工具工厂和 CLI。
|
||||
内存工具工厂和 CLI。
|
||||
|
||||
```typescript
|
||||
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
|
||||
@ -334,12 +332,51 @@ api.runtime.tools.registerMemoryCli(/* ... */);
|
||||
|
||||
### `api.runtime.channel`
|
||||
|
||||
渠道特定运行时辅助工具（在加载渠道插件时可用）。
|
||||
渠道专用运行时辅助工具（在加载渠道插件时可用）。
|
||||
|
||||
`api.runtime.channel.mentions` 是供使用运行时注入的内置渠道插件共享的入站提及策略接口：
|
||||
|
||||
```typescript
|
||||
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
|
||||
mentionRegexes,
|
||||
mentionPatterns,
|
||||
});
|
||||
|
||||
const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({
|
||||
facts: {
|
||||
canDetectMention: true,
|
||||
wasMentioned: mentionMatch.matched,
|
||||
implicitMentionKinds: api.runtime.channel.mentions.implicitMentionKindWhen(
|
||||
"reply_to_bot",
|
||||
isReplyToBot,
|
||||
),
|
||||
},
|
||||
policy: {
|
||||
isGroup,
|
||||
requireMention,
|
||||
allowTextCommands,
|
||||
hasControlCommand,
|
||||
commandAuthorized,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
可用的 mention 辅助工具包括：
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
- `matchesMentionWithExplicit`
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
`api.runtime.channel.mentions` 有意不暴露较旧的
|
||||
`resolveMentionGating*` 兼容辅助工具。请优先使用标准化的
|
||||
`{ facts, policy }` 路径。
|
||||
|
||||
## 存储运行时引用
|
||||
|
||||
使用 `createPluginRuntimeStore` 来存储运行时引用，以便在
|
||||
`register` 回调之外使用：
|
||||
使用 `createPluginRuntimeStore` 存储运行时引用，以便在 `register`
|
||||
回调之外使用：
|
||||
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
@ -368,20 +405,20 @@ export function tryGetRuntime() {
|
||||
|
||||
## 其他顶层 `api` 字段
|
||||
|
||||
除了 `api.runtime` 之外，API 对象还提供：
|
||||
除 `api.runtime` 之外，API 对象还提供：
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | 插件 id |
|
||||
| `api.name` | `string` | 插件显示名称 |
|
||||
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存中运行时快照） |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专用配置 |
|
||||
| `api.logger` | `PluginLogger` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口前的轻量启动/设置窗口 |
|
||||
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
|
||||
| Field | Type | Description |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | 插件 id |
|
||||
| `api.name` | `string` | 插件显示名称 |
|
||||
| `api.config` | `OpenClawConfig` | 当前 config 快照（可用时为活动的内存中运行时快照） |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专用 config |
|
||||
| `api.logger` | `PluginLogger` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量级窗口 |
|
||||
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [SDK 概览](/plugins/sdk-overview) -- 子路径参考
|
||||
- [插件入口点](/plugins/sdk-entrypoints) -- `definePluginEntry` 选项
|
||||
- [插件内部机制](/plugins/architecture) -- 能力模型和注册表
|
||||
- [SDK 概览](/zh-CN/plugins/sdk-overview) —— subpath 参考
|
||||
- [插件入口点](/zh-CN/plugins/sdk-entrypoints) —— `definePluginEntry` 选项
|
||||
- [插件内部架构](/zh-CN/plugins/architecture) —— 能力模型和注册表
|
||||
|
||||
Loading…
Reference in New Issue
Block a user