openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 15:22:42 +00:00
parent 321421b3b6
commit 702c3595f0
3 changed files with 413 additions and 402 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

228
docs/zh-CN/gateway/heartbeat.md
View File

@ -1,51 +1,51 @@
---
read_when:
- 调整 Heartbeat 频率或消息文案
- 为定时任务在 Heartbeat 和 cron 之间做选择
- 调整 Heartbeat 节奏或消息内容
- 为定时任务选择 Heartbeat 还是 cron
sidebarTitle: Heartbeat
summary: Heartbeat 轮询消息和通知规则
title: Heartbeat
x-i18n:
generated_at: "2026-05-01T18:34:40Z"
generated_at: "2026-05-02T15:20:22Z"
model: gpt-5.5
provider: openai
source_hash: c8198c74e2712c7ed9d34c41bad7c4e9be62043e8755cb4c9a60649222e04e37
source_hash: 20ce96feb2512312ec8dc5ef3b6722ed552f0a03c55b80a9c3f5b42594ab0d36
source_path: gateway/heartbeat.md
workflow: 16
---
<Note>
**Heartbeat 与 cron？** 请参阅 [自动化与任务](/zh-CN/automation)，了解何时使用二者。
**Heartbeat 和 cron？** 请参阅 [自动化与任务](/zh-CN/automation)，了解何时使用二者。
</Note>
Heartbeat 会在主会话中运行**周期性智能体轮次**，让模型能够显示需要关注的事项，而不会向你发送垃圾信息。
Heartbeat 会在主会话中运行**周期性的智能体轮次**，让模型可以提示任何需要注意的事项，而不会向你发送大量消息。
Heartbeat 是一次定时的主会话轮次——它**不会**创建 [后台任务](/zh-CN/automation/tasks)记录。任务记录用于脱离当前会话的工作（ACP 运行、子智能体、隔离的 cron 作业）。
Heartbeat 是一次计划的主会话轮次，它**不会**创建[后台任务](/zh-CN/automation/tasks)记录。任务记录用于脱离主流程的工作（ACP 运行、子智能体、隔离的 cron 作业）。
故障排除：[定时任务](/zh-CN/automation/cron-jobs#troubleshooting)
## 快速开始（初学者）
<Steps>
<Step title="选择频率">
保持 Heartbeat 启用（默认是 `30m`，如果使用 Anthropic OAuth/token 凭证，包括复用 Claude CLI，则为 `1h`），或设置你自己的频率。
<Step title="选择节奏">
保持 heartbeat 启用（默认是 `30m`，Anthropic OAuth/token auth 时为 `1h`，包括 Claude CLI 复用），或设置你自己的节奏。
</Step>
<Step title="添加 HEARTBEAT.md（可选）">
在 Agent 工作区中创建一个很小的 `HEARTBEAT.md` 检查清单或 `tasks:` 块。
在 Agent 工作区中创建一个小型 `HEARTBEAT.md` 清单或 `tasks:` 块。
</Step>
<Step title="决定 Heartbeat 消息应发送到哪里">
`target: "none"` 是默认值；设置 `target: "last"` 可路由到上次联系对象。
<Step title="决定 heartbeat 消息应发送到哪里">
`target: "none"` 是默认值；设置 `target: "last"` 可路由到最近的联系人。
</Step>
<Step title="可选调优">
- 启用 Heartbeat 推理投递以提高透明度。
- 如果 Heartbeat 运行只需要 `HEARTBEAT.md`，使用轻量级引导上下文。
- 启用隔离会话，避免每次 Heartbeat 都发送完整对话历史。
- 将 Heartbeat 限制在活跃时段内（本地时间）。
- 启用 heartbeat 推理传递以提高透明度。
- 如果 heartbeat 运行只需要 `HEARTBEAT.md`，使用轻量级 bootstrap 上下文。
- 启用隔离会话，以避免每次 heartbeat 都发送完整对话历史。
- 将 heartbeat 限制在活跃时段（本地时间）。
</Step>
</Steps>
示例配置：
配置示例：
```json5
{
@ -68,33 +68,33 @@ Heartbeat 是一次定时的主会话轮次——它**不会**创建 [后台任
## 默认值
- 间隔：`30m`（当检测到 Anthropic OAuth/token 凭证模式时为 `1h`，包括复用 Claude CLI）。设置 `agents.defaults.heartbeat.every` 或按智能体设置 `agents.list[].heartbeat.every`；使用 `0m` 可禁用。
- 间隔：`30m`（当检测到的 auth 模式为 Anthropic OAuth/token auth 时为 `1h`，包括 Claude CLI 复用）。设置 `agents.defaults.heartbeat.every` 或每个智能体的 `agents.list[].heartbeat.every`；使用 `0m` 禁用。
- 提示正文（可通过 `agents.defaults.heartbeat.prompt` 配置）：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
- Heartbeat 提示会作为用户消息**逐字**发送。只有当默认智能体启用了 Heartbeat 时，系统提示才会包含 “Heartbeat” 部分，并且本次运行会在内部标记。
- 使用 `0m` 禁用 Heartbeat 时，普通运行也会从引导上下文中省略 `HEARTBEAT.md`，因此模型不会看到仅用于 Heartbeat 的指令。
- 活跃时段（`heartbeat.activeHours`）会在配置的时区中检查。在时间窗口外，Heartbeat 会被跳过，直到窗口内的下一次 tick。
- 当 cron 工作处于活跃或排队状态时，Heartbeat 会自动推迟。设置 `heartbeat.skipWhenBusy: true` 后，在额外繁忙的通道（子智能体或嵌套命令工作）上也会推迟；这对本地 Ollama 和其他受限的单运行时主机很有用。
- heartbeat 提示会作为用户消息**逐字**发送。只有当默认智能体启用了 heartbeat 时，系统提示才会包含 “Heartbeat” 部分，并且该运行会在内部标记。
- 当使用 `0m` 禁用 heartbeat 时，普通运行也会从 bootstrap 上下文中省略 `HEARTBEAT.md`，因此模型不会看到仅用于 heartbeat 的指令。
- 活跃时段（`heartbeat.activeHours`）会按配置的时区检查。在窗口外，heartbeat 会被跳过，直到窗口内的下一个 tick。
- 当 cron 工作处于活动或排队状态时，heartbeat 会自动延后。设置 `heartbeat.skipWhenBusy: true`，还会在额外繁忙的通道（子智能体或嵌套命令工作）上延后；这对本地 Ollama 和其他受限的单运行时主机很有用。
## Heartbeat 提示的用途
## heartbeat 提示的用途
默认提示有意保持宽泛：
- **后台任务**：“Consider outstanding tasks” 会提示智能体检查后续事项（收件箱、日历、提醒、排队工作），并显示任何紧急事项。
- **人工签到**：“Checkup sometimes on your human during day time” 会提示偶尔发送轻量级的“你有什么需要吗？”消息，但会使用你配置的本地时区避免夜间打扰（请参阅[时区](/zh-CN/concepts/timezone)）。
- **后台任务**：“Consider outstanding tasks” 会提示智能体审查跟进事项（收件箱、日历、提醒、排队工作），并提示任何紧急事项。
- **与人类确认**：“Checkup sometimes on your human during day time” 会提示偶尔发送轻量的“anything you need?”消息，但会使用你配置的本地时区来避免夜间打扰（参见[时区](/zh-CN/concepts/timezone)）。
Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但 Heartbeat 运行本身不会创建任务记录。
Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但 heartbeat 运行本身不会创建任务记录。
如果你希望 Heartbeat 执行非常具体的操作（例如“检查 Gmail PubSub 统计数据”或“验证 Gateway 网关健康状态”），请将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义正文（逐字发送）。
如果你希望 heartbeat 执行非常具体的事项（例如“检查 Gmail PubSub 统计信息”或“验证 Gateway 网关健康状况”），请将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义正文（逐字发送）。
## 响应契约
- 如果没有需要关注的事项，请回复 **`HEARTBEAT_OK`**。
- 支持工具的 Heartbeat 运行也可以调用 `heartbeat_respond`，在没有可见更新时使用 `notify: false`，或在需要提醒时使用 `notify: true` 加 `notificationText`。如果存在结构化工具响应，它优先于文本回退。
- 在 Heartbeat 运行期间，如果 `HEARTBEAT_OK` 出现在回复的**开头或结尾**，OpenClaw 会将其视为确认。该 token 会被剥离；如果剩余内容 **≤ `ackMaxChars`**（默认值：300），该回复会被丢弃。
- 如果 `HEARTBEAT_OK` 出现在回复**中间**，不会进行特殊处理。
- 如果没有需要注意的事项，回复 **`HEARTBEAT_OK`**。
- 支持工具的 heartbeat 运行也可以调用 `heartbeat_respond`，使用 `notify: false` 表示没有可见更新，或使用 `notify: true` 加 `notificationText` 发送提醒。存在结构化工具响应时，它优先于文本回退。
- 在 heartbeat 运行期间，如果 `HEARTBEAT_OK` 出现在回复的**开头或结尾**，OpenClaw 会将其视为确认。该 token 会被移除；如果剩余内容**≤ `ackMaxChars`**（默认：300），回复会被丢弃。
- 如果 `HEARTBEAT_OK` 出现在回复**中间**，不会被特殊处理。
- 对于提醒，**不要**包含 `HEARTBEAT_OK`；只返回提醒文本。
在 Heartbeat 之外，消息开头/结尾散落的 `HEARTBEAT_OK` 会被剥离并记录；仅包含 `HEARTBEAT_OK` 的消息会被丢弃。
在 heartbeat 之外，消息开头/结尾出现的游离 `HEARTBEAT_OK` 会被移除并记录；只有 `HEARTBEAT_OK` 的消息会被丢弃。
## 配置
@ -120,17 +120,17 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但
}
```
### 作用域与优先级
### 范围和优先级
- `agents.defaults.heartbeat` 设置全局 Heartbeat 行为。
- `agents.list[].heartbeat` 在其上合并；如果任何智能体有 `heartbeat` 块，**只有这些智能体**会运行 Heartbeat。
- `channels.defaults.heartbeat` 设置所有渠道的可见性默认值。
- `agents.defaults.heartbeat` 设置全局 heartbeat 行为。
- `agents.list[].heartbeat` 在其上合并；如果任何智能体有 `heartbeat` 块，**只有这些智能体**会运行 heartbeat。
- `channels.defaults.heartbeat` 为所有渠道设置可见性默认值。
- `channels.<channel>.heartbeat` 覆盖渠道默认值。
- `channels.<channel>.accounts.<id>.heartbeat`（多账号渠道）覆盖按渠道的设置。
- `channels.<channel>.accounts.<id>.heartbeat`（多账号渠道）覆盖每个渠道的设置。
### 按智能体设置 Heartbeat
### 每智能体 Heartbeat
如果任何 `agents.list[]` 条目包含 `heartbeat` 块，**只有这些智能体**会运行 Heartbeat。按智能体的块会合并到 `agents.defaults.heartbeat` 之上（因此你可以一次设置共享默认值，并按智能体覆盖）。
如果任何 `agents.list[]` 条目包含 `heartbeat` 块，**只有这些智能体**会运行 Heartbeat。每智能体块会合并到 `agents.defaults.heartbeat` 之上（因此你可以只设置一次共享默认值，并按智能体覆盖）。
示例：两个智能体，只有第二个智能体运行 Heartbeat。
@ -182,9 +182,9 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但
}
```
在此窗口之外（东部时间早上 9 点前或晚上 10 点后），Heartbeat 会被跳过。窗口内的下一次计划 tick 会正常运行。
在此时间窗口之外（美国东部时间上午 9 点之前或晚上 10 点之后），会跳过 Heartbeat。窗口内的下一次计划触发会正常运行。
### 24/7 设置
### 全天候设置
如果你希望 Heartbeat 全天运行，请使用以下模式之一：
@ -192,12 +192,12 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但
- 设置全天窗口：`activeHours: { start: "00:00", end: "24:00" }`。
<Warning>
不要将 `start` 和 `end` 设为同一时间（例如从 `08:00` 到 `08:00`）。这会被视为零宽度窗口，因此 Heartbeat 始终会被跳过。
不要将 `start` 和 `end` 时间设置为相同（例如从 `08:00` 到 `08:00`）。这会被视为零宽窗口，因此 Heartbeat 总是会被跳过。
</Warning>
### 多账号示例
使用 `accountId` 定位到 Telegram 等多账号渠道上的特定账号：
使用 `accountId` 在 Telegram 等多账号渠道中定位特定账号：
```json5
{
@ -227,55 +227,55 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但
### 字段说明
<ParamField path="every" type="string">
Heartbeat 间隔（持续时间字符串；默认单位 = 分钟）。
Heartbeat 间隔（时长字符串；默认单位 = 分钟）。
</ParamField>
<ParamField path="model" type="string">
Heartbeat 运行的可选模型覆盖（`provider/model`）。
</ParamField>
<ParamField path="includeReasoning" type="boolean" default="false">
启用后，在可用时也会投递单独的 `Reasoning:` 消息（形状与 `/reasoning on` 相同）。
启用后，在可用时也会发送单独的 `Reasoning:` 消息（形状与 `/reasoning on` 相同）。
</ParamField>
<ParamField path="lightContext" type="boolean" default="false">
为 true 时，Heartbeat 运行使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。
为 true 时，Heartbeat 运行会使用轻量级启动上下文，并且只保留工作区启动文件中的 `HEARTBEAT.md`。
</ParamField>
<ParamField path="isolatedSession" type="boolean" default="false">
为 true 时，每次 Heartbeat 都会在没有先前对话历史的新会话中运行。使用与 cron `sessionTarget: "isolated"` 相同的隔离模式。会显著降低每次 Heartbeat 的 token 成本。与 `lightContext: true` 结合使用可最大化节省。投递路由仍使用主会话上下文。
为 true 时，每次 Heartbeat 都会在一个没有先前对话历史的全新会话中运行。使用与 cron `sessionTarget: "isolated"` 相同的隔离模式。可大幅降低每次 Heartbeat 的 token 成本。与 `lightContext: true` 结合使用可获得最大节省。递送路由仍使用主会话上下文。
</ParamField>
<ParamField path="skipWhenBusy" type="boolean" default="false">
为 true 时，Heartbeat 运行会在额外繁忙的通道上推迟：子智能体或嵌套命令工作。即使没有此标志，cron 通道也始终会推迟 Heartbeat，因此本地模型主机不会同时运行 cron 和 Heartbeat 提示。
为 true 时，Heartbeat 运行会在额外繁忙的执行通道上延后：子智能体或嵌套命令工作。cron 执行通道始终会延后 Heartbeat，即使没有此标志也是如此，因此本地模型主机不会同时运行 cron 和 Heartbeat prompt。
</ParamField>
<ParamField path="session" type="string">
Heartbeat 运行的可选会话键。
- `main`（默认）：智能体主会话。
- 显式会话键（从 `openclaw sessions --json` 或[会话 CLI](/zh-CN/cli/sessions) 复制）。
- 会话键格式：请参阅[会话](/zh-CN/concepts/session)和[群组](/zh-CN/channels/groups)。
- 显式会话键（从 `openclaw sessions --json` 或 [会话 CLI](/zh-CN/cli/sessions) 复制）。
- 会话键格式：请参阅[会话](/zh-CN/concepts/session)和[组](/zh-CN/channels/groups)。
</ParamField>
<ParamField path="target" type="string">
- `last`：投递到上次使用的外部渠道。
- 显式渠道：任何已配置的渠道或插件 id，例如 `discord`、`matrix`、`telegram` 或 `whatsapp`。
- `none`（默认）：运行 Heartbeat，但**不向外部投递**。
- `last`：递送到上次使用的外部渠道。
- 显式渠道：任何已配置的渠道或插件 ID，例如 `discord`、`matrix`、`telegram` 或 `whatsapp`。
- `none`（默认）：运行 Heartbeat，但**不向外部递送**。
</ParamField>
<ParamField path="directPolicy" type='"allow" | "block"' default="allow">
控制直接/私信投递行为。`allow`：允许直接/私信 Heartbeat 投递。`block`：抑制直接/私信投递（`reason=dm-blocked`）。
控制直接/私信递送行为。`allow`：允许直接/私信 Heartbeat 递送。`block`：禁止直接/私信递送（`reason=dm-blocked`）。
</ParamField>
<ParamField path="to" type="string">
可选收件人覆盖（渠道特定 id，例如 WhatsApp 的 E.164 或 Telegram chat id）。对于 Telegram topic/thread，使用 `<chatId>:topic:<messageThreadId>`。
可选的接收者覆盖（特定于渠道的 ID，例如 WhatsApp 的 E.164 或 Telegram 聊天 ID）。对于 Telegram 主题/线程，使用 `<chatId>:topic:<messageThreadId>`。
</ParamField>
<ParamField path="accountId" type="string">
多账号渠道的可选账号 id。当 `target: "last"` 时，如果解析出的上次渠道支持账号，该账号 id 会应用于该渠道；否则会被忽略。如果账号 id 与解析出的渠道中已配置的账号不匹配，投递会被跳过。
多账户渠道的可选账户 ID。当 `target: "last"` 时，如果解析出的上次渠道支持账户，则账户 ID 会应用于该渠道；否则会被忽略。如果账户 ID 与解析出的渠道中已配置的账户不匹配，则会跳过递送。
</ParamField>
<ParamField path="prompt" type="string">
覆盖默认提示正文（不合并）。
覆盖默认提示词正文（不合并）。
</ParamField>
<ParamField path="ackMaxChars" type="number" default="300">
`HEARTBEAT_OK` 之后、交付之前允许的最大字符数。
`HEARTBEAT_OK` 后、递送前允许的最大字符数。
</ParamField>
<ParamField path="suppressToolErrorWarnings" type="boolean">
@ -283,46 +283,46 @@ Heartbeat 可以响应已完成的[后台任务](/zh-CN/automation/tasks)，但
</ParamField>
<ParamField path="activeHours" type="object">
将 Heartbeat 运行限制在一个时间窗口内。对象包含 `start`（HH:MM，包含；使用 `00:00` 表示一天开始）、`end`（HH:MM，不包含；允许 `24:00` 表示一天结束），以及可选的 `timezone`。
将 Heartbeat 运行限制在一个时间窗口内。对象包含 `start`（HH:MM，含起点；使用 `00:00` 表示一天开始）、`end`（HH:MM，不含终点；允许 `24:00` 表示一天结束），以及可选的 `timezone`。
- 省略或 `"user"`：如果设置了你的 `agents.defaults.userTimezone`，则使用它，否则回退到宿主系统时区。
- `"local"`：始终使用宿主系统时区。
- 省略或 `"user"`：如果已设置，则使用你的 `agents.defaults.userTimezone`，否则回退到主机系统时区。
- `"local"`：始终使用主机系统时区。
- 任意 IANA 标识符（例如 `America/New_York`）：直接使用；如果无效，则回退到上面的 `"user"` 行为。
- 对于活动窗口，`start` 和 `end` 不能相等；相等的值会被视为零宽度窗口（始终在窗口外）。
- 在活动窗口外，Heartbeat 会被跳过，直到窗口内的下一个 tick。
- 对于活跃窗口，`start` 和 `end` 不能相等；相等的值会被视为零宽度（始终在窗口外）。
- 在活跃窗口之外，Heartbeat 会被跳过，直到窗口内的下一个 tick。
</ParamField>
## 交付行为
## 递送行为
<AccordionGroup>
<Accordion title="Session and target routing">
- 默认情况下，Heartbeat 在智能体的主会话中运行（`agent:<id>:<mainKey>`），或者当 `session.scope = "global"` 时在 `global` 中运行。设置 `session` 可覆盖到特定渠道会话（Discord/WhatsApp 等）。
- `session` 只影响运行上下文；交付由 `target` 和 `to` 控制。
- 要交付给特定渠道/接收者，请设置 `target` + `to`。使用 `target: "last"` 时，交付会使用该会话最后一个外部渠道。
- Heartbeat 交付默认允许直接/私信目标。设置 `directPolicy: "block"` 可在仍然运行 Heartbeat 回合的同时抑制直接目标发送。
- 如果主队列、目标会话 lane、cron lane 或活动 cron 作业正忙，Heartbeat 会被跳过并稍后重试。
- 如果 `skipWhenBusy: true`，子智能体和嵌套 lane 也会延后 Heartbeat 运行。
- 如果 `target` 未解析到外部目的地，运行仍会发生，但不会发送出站消息。
<Accordion title="会话和目标路由">
- Heartbeat 默认在智能体的主会话中运行（`agent:<id>:<mainKey>`），或者当 `session.scope = "global"` 时在 `global` 中运行。设置 `session` 可覆盖为特定渠道会话（Discord/WhatsApp 等）。
- `session` 只影响运行上下文；递送由 `target` 和 `to` 控制。
- 要递送到特定渠道/接收者，请设置 `target` + `to`。使用 `target: "last"` 时，递送会使用该会话的最后一个外部渠道。
- Heartbeat 递送默认允许直接目标/私信目标。设置 `directPolicy: "block"` 可抑制直接目标发送，同时仍然运行 Heartbeat 回合。
- 如果主队列、目标会话 lane、cron lane 或活跃 cron 作业正忙，Heartbeat 会被跳过并稍后重试。
- 如果 `skipWhenBusy: true`，子智能体和嵌套 lane 也会推迟 Heartbeat 运行。
- 如果 `target` 解析不到外部目的地，运行仍会发生，但不会发送出站消息。
</Accordion>
<Accordion title="Visibility and skip behavior">
- 如果 `showOk`、`showAlerts` 和 `useIndicator` 全部禁用，运行会预先以 `reason=alerts-disabled` 跳过。
- 如果只禁用了告警交付，OpenClaw 仍可运行 Heartbeat、更新到期任务时间戳、恢复会话空闲时间戳，并抑制对外告警载荷。
- 如果解析出的 Heartbeat 目标支持正在输入状态，OpenClaw 会在 Heartbeat 运行处于活动状态时显示正在输入。这会使用 Heartbeat 原本会向其发送聊天输出的同一目标，并且会被 `typingMode: "never"` 禁用。
<Accordion title="可见性和跳过行为">
- 如果 `showOk`、`showAlerts` 和 `useIndicator` 全部禁用，运行会在前置阶段以 `reason=alerts-disabled` 跳过。
- 如果只禁用了告警递送，OpenClaw 仍可运行 Heartbeat、更新到期任务时间戳、恢复会话空闲时间戳，并抑制对外告警载荷。
- 如果解析出的 Heartbeat 目标支持 typing，OpenClaw 会在 Heartbeat 运行处于活跃状态时显示 typing。这会使用 Heartbeat 本应向其发送聊天输出的同一目标，并且可通过 `typingMode: "never"` 禁用。
</Accordion>
<Accordion title="Session lifecycle and audit">
- 仅 Heartbeat 的回复**不会**让会话保持存活。Heartbeat 元数据可能会更新会话行，但空闲过期使用最后一条真实用户/渠道消息的 `lastInteractionAt`，每日过期使用 `sessionStartedAt`。
- Control UI 和 WebChat 历史会隐藏 Heartbeat 提示词和仅 OK 的确认。底层会话 transcript 仍可包含这些回合，用于审计/重放。
- 分离的[后台任务](/zh-CN/automation/tasks)可以将系统事件入队，并在主会话应快速注意到某事时唤醒 Heartbeat。该唤醒不会让 Heartbeat 运行后台任务。
<Accordion title="会话生命周期和审计">
- 仅 Heartbeat 的回复**不会**保持会话存活。Heartbeat 元数据可能会更新会话行，但空闲过期使用最后一条真实用户/渠道消息的 `lastInteractionAt`，每日过期使用 `sessionStartedAt`。
- Control UI 和 WebChat 历史会隐藏 Heartbeat 提示词和仅 OK 的确认。底层会话转录仍可包含这些回合，用于审计/重放。
- 分离的[后台任务](/zh-CN/automation/tasks)可以入队一个系统事件，并在主会话应快速注意到某些内容时唤醒 Heartbeat。该唤醒不会让 Heartbeat 运行变成后台任务。
</Accordion>
</AccordionGroup>
## 可见性控制
默认情况下，`HEARTBEAT_OK` 确认会被抑制，而告警内容会被交付。你可以按渠道或按账户调整：
默认情况下，`HEARTBEAT_OK` 确认会被抑制，而告警内容会被递送。你可以按渠道或按账号调整：
```yaml
channels:
@ -341,7 +341,7 @@ channels:
showAlerts: false # Suppress alert delivery for this account
```
优先级：按账户 → 按渠道 → 渠道默认值 → 内置默认值。
优先级：按账号 → 按渠道 → 渠道默认值 → 内置默认值。
### 每个标志的作用
@ -349,9 +349,9 @@ channels:
- `showAlerts`：当模型返回非 OK 回复时，发送告警内容。
- `useIndicator`：为 UI Status 表面发出指示器事件。
如果**全部三个**都是 false，OpenClaw 会完全跳过 Heartbeat 运行（不会调用模型）。
如果**三个**都为 false，OpenClaw 会完全跳过 Heartbeat 运行（不会调用模型）。
### 按渠道与按账户示例
### 按渠道与按账号示例
```yaml
channels:
@ -376,22 +376,22 @@ channels:
| 目标 | 配置 |
| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| 默认行为（静默 OK，告警开启） | _(无需配置)_ |
| 完全静默（无消息，无指示器） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
| 默认行为（静默 OK，开启告警） | _（无需配置）_ |
| 完全静默（无消息、无指示器） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
| 仅指示器（无消息） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` |
| 仅在一个渠道中显示 OK | `channels.telegram.heartbeat: { showOk: true }` |
## HEARTBEAT.md（可选）
如果工作区中存在 `HEARTBEAT.md` 文件，默认提示词会告诉智能体读取它。你可以把它看作你的“Heartbeat 检查清单”：小巧、稳定，并且适合每 30 分钟纳入一次。
如果工作区中存在 `HEARTBEAT.md` 文件，默认提示词会告诉智能体读取它。可以把它看作你的 “Heartbeat 检查清单”：小巧、稳定，并且可安全地每 30 分钟纳入一次。
在正常运行中，只有当默认智能体启用了 Heartbeat 指导时，才会注入 `HEARTBEAT.md`。使用 `0m` 禁用 Heartbeat 节奏，或设置 `includeSystemPromptSection: false`，会将它从正常 bootstrap 上下文中省略。
在正常运行中，只有为默认智能体启用 Heartbeat 指引时，才会注入 `HEARTBEAT.md`。用 `0m` 禁用 Heartbeat 节奏，或设置 `includeSystemPromptSection: false`，会将它从正常引导上下文中省略。
如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和像 `# Heading` 这样的 Markdown 标题），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。该跳过会报告为 `reason=empty-heartbeat-file`。如果文件缺失，Heartbeat 仍会运行，由模型决定要做什么。
如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和类似 `# Heading` 的 markdown 标题），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。该跳过会报告为 `reason=empty-heartbeat-file`。如果文件缺失，Heartbeat 仍会运行，并由模型决定要做什么。
保持它很小（简短检查清单或提醒），以避免提示词膨胀。
保持精简（简短检查清单或提醒），以避免提示词膨胀。
示例 `HEARTBEAT.md`：
`HEARTBEAT.md` 示例：
```md
# Heartbeat checklist
@ -403,7 +403,7 @@ channels:
### `tasks:` 块
`HEARTBEAT.md` 还支持一个小型结构化 `tasks:` 块，用于在 Heartbeat 内部执行基于间隔的检查。
`HEARTBEAT.md` 还支持一个小型结构化 `tasks:` 块，用于在 Heartbeat 本身内部进行基于间隔的检查。
示例：
@ -424,37 +424,37 @@ tasks:
```
<AccordionGroup>
<Accordion title="Behavior">
- OpenClaw 会解析 `tasks:` 块，并根据每个任务自己的 `interval` 检查它。
<Accordion title="行为">
- OpenClaw 解析 `tasks:` 块，并按每个任务自己的 `interval` 检查它。
- 只有**到期**任务会被包含在该 tick 的 Heartbeat 提示词中。
- 如果没有任务到期，Heartbeat 会被完全跳过（`reason=no-tasks-due`），以避免浪费一次模型调用。
- `HEARTBEAT.md` 中的非任务内容会被保留，并作为额外上下文附加在到期任务列表之后。
- 任务上次运行时间戳会存储在会话状态（`heartbeatTaskState`）中，因此间隔能在正常重启后保留。
- 任务时间戳只会在 Heartbeat 运行完成其正常回复路径后推进。被跳过的 `empty-heartbeat-file` / `no-tasks-due` 运行不会将任务标记为已完成。
- 如果没有任务到期，Heartbeat 会被完全跳过（`reason=no-tasks-due`），以避免浪费模型调用。
- `HEARTBEAT.md` 中的非任务内容会保留，并作为附加上下文追加到到期任务列表之后。
- 任务上次运行时间戳会存储在会话状态中（`heartbeatTaskState`），因此间隔能在正常重启后保留。
- 只有在 Heartbeat 运行完成其正常回复路径后，任务时间戳才会推进。被跳过的 `empty-heartbeat-file` / `no-tasks-due` 运行不会将任务标记为已完成。
</Accordion>
</AccordionGroup>
当你希望一个 Heartbeat 文件承载多个周期性检查，而不是每个 tick 都为全部检查付费时，任务模式很有用。
当你希望一个 Heartbeat 文件保存多个周期性检查，但不想每个 tick 都为所有检查付费时，任务模式很有用。
### 智能体可以更新 HEARTBEAT.md 吗？
可以，只要你要求它这样做。
`HEARTBEAT.md` 只是智能体工作区中的普通文件，因此你可以在普通聊天中告诉智能体，例如：
`HEARTBEAT.md` 只是智能体工作区中的普通文件，所以你可以在普通聊天中告诉智能体，例如：
- “更新 `HEARTBEAT.md`，添加每日日历检查。”
- “重写 `HEARTBEAT.md`，让它更短并聚焦于收件箱跟进。”
- “重写 `HEARTBEAT.md`，让它更短，并专注于收件箱跟进。”
如果你希望这主动发生，也可以在 Heartbeat 提示词中包含一行明确指令，例如：“如果检查清单变得过时，请用更好的版本更新 HEARTBEAT.md。”
如果你希望这主动发生，也可以在 Heartbeat 提示词中加入明确的一行，例如：“如果检查清单变得过时，请用更好的版本更新 HEARTBEAT.md。”
<Warning>
不要把秘密（API key、电话号码、私有 token）放入 `HEARTBEAT.md`，它会成为提示词上下文的一部分。
不要把秘密（API key、电话号码、私有令牌）放进 `HEARTBEAT.md`，它会成为提示词上下文的一部分。
</Warning>
## 手动唤醒（按需）
你可以用以下命令将系统事件入队并触发立即 Heartbeat：
你可以用以下命令入队一个系统事件并触发即时 Heartbeat：
```bash
openclaw system event --text "Check for urgent follow-ups" --mode now
@ -464,35 +464,35 @@ openclaw system event --text "Check for urgent follow-ups" --mode now
使用 `--mode next-heartbeat` 等待下一个计划 tick。
## Reasoning 交付（可选）
## 推理递送（可选）
默认情况下，Heartbeat 只交付最终“answer”载荷。
默认情况下，Heartbeat 只递送最终 “answer” 载荷。
如果你需要透明度，请启用：
如果你想提高透明度，请启用：
- `agents.defaults.heartbeat.includeReasoning: true`
启用后，Heartbeat 还会交付一条单独消息，前缀为 `Reasoning:`（形状与 `/reasoning on` 相同）。当智能体管理多个会话/codexes，而你想看到它为何决定 ping 你时，这会很有用，但它也可能泄露比你想要更多的内部细节。建议在群聊中保持关闭。
启用后，Heartbeat 还会递送一条以 `Reasoning:` 为前缀的单独消息（形状与 `/reasoning on` 相同）。当智能体管理多个会话/codex，并且你想了解它为何决定 ping 你时，这会很有用，但它也可能泄露比你想要的更多内部细节。建议在群聊中保持关闭。
## 成本意识
Heartbeat 会运行完整的智能体回合。更短的间隔会消耗更多 token。要降低成本：
- 使用 `isolatedSession: true`，避免发送完整对话历史（每次运行从约 100K token 降至约 2-5K）。
- 使用 `lightContext: true`，将 bootstrap 文件限制为仅 `HEARTBEAT.md`。
- 使用 `isolatedSession: true`，避免发送完整对话历史（每次运行从约 100K token 降到约 2-5K）。
- 使用 `lightContext: true`，将引导文件限制为只有 `HEARTBEAT.md`。
- 设置更便宜的 `model`（例如 `ollama/llama3.2:1b`）。
- 保持 `HEARTBEAT.md` 小巧。
- 如果你只想要内部状态更新，请使用 `target: "none"`。
- 如果你只想更新内部状态，请使用 `target: "none"`。
## Heartbeat 后的上下文溢出
如果 Heartbeat 使用较小的本地模型，例如上下文窗口为 32k 的 Ollama 模型，并且下一个主会话回合报告上下文溢出，请检查上一次 Heartbeat 是否让会话停留在 Heartbeat 模型上。当最后一个运行时模型与配置的 `heartbeat.model` 匹配时，OpenClaw 的重置消息会指出这一点。
如果某次 Heartbeat 之前把现有会话留在较小的本地模型上，例如窗口为 32k 的 Ollama 模型，并且下一次主会话回合报告上下文溢出，请将会话运行时模型重置回已配置的主模型。当最后一个运行时模型匹配已配置的 `heartbeat.model` 时，OpenClaw 的重置消息会指出这一点。
使用 `isolatedSession: true` 在新会话中运行 Heartbeat，将它与 `lightContext: true` 结合以获得最小提示词，或者选择上下文窗口足够容纳共享会话的 Heartbeat 模型。
当前 Heartbeat 会在运行完成后保留共享会话的现有运行时模型。你仍可使用 `isolatedSession: true` 在新会话中运行 Heartbeat，将它与 `lightContext: true` 结合以获得最小提示词，或选择上下文窗口足以容纳共享会话的 Heartbeat 模型。
## 相关
- [自动化和任务](/zh-CN/automation) — 所有自动化机制一览
- [自动化与任务](/zh-CN/automation) — 一览所有自动化机制
- [后台任务](/zh-CN/automation/tasks) — 分离工作如何被跟踪
- [时区](/zh-CN/concepts/timezone) — 时区如何影响 Heartbeat 调度
- [故障排除](/zh-CN/automation/cron-jobs#troubleshooting) — 调试自动化问题

212
docs/zh-CN/plugins/sdk-setup.md
View File

@ -2,28 +2,28 @@
read_when:
- 你正在为插件添加设置向导
- 你需要理解 setup-entry.ts 与 index.ts 的区别
- 你正在定义插件配置架构或 package.json 的 openclaw 元数据
- 你正在定义插件配置模式或 package.json 中的 openclaw 元数据
sidebarTitle: Setup and config
summary: 设置向导、setup-entry.ts、配置架构和 package.json 元数据
summary: 设置向导、setup-entry.ts、配置 schema 和 package.json 元数据
title: 插件设置和配置
x-i18n:
generated_at: "2026-05-02T14:31:56Z"
generated_at: "2026-05-02T15:20:32Z"
model: gpt-5.5
provider: openai
source_hash: 9474dbbbc984e19019f7d14c7d63d944c544868407f7908df282bc7c080dc0c2
source_hash: 3975be167ef48e4840fa1abc2a0412f0fc5ab569898742ebc11a1c52f89871c9
source_path: plugins/sdk-setup.md
workflow: 16
---
插件打包（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置入口和配置架构的参考。
插件打包（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置条目和配置架构的参考。
<Tip>
**想要查看演练？** 操作指南会在上下文中介绍打包：[渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和 [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。
**想看演练？** 操作指南会结合上下文介绍打包：[渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和 [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。
</Tip>
## 包元数据
你的 `package.json` 需要一个 `openclaw` 字段，用于告诉插件系统你的插件提供什么：
你的 `package.json` 需要一个 `openclaw` 字段，用来告诉插件系统你的插件提供什么：
<Tabs>
<Tab title="Channel plugin">
@ -67,7 +67,7 @@ x-i18n:
</Tabs>
<Note>
如果你在 ClawHub 上对外发布插件，则这些 `compat` 和 `build` 字段是必需的。规范发布片段位于 `docs/snippets/plugin-publish/`。
如果你在 ClawHub 上对外发布插件，这些 `compat` 和 `build` 字段是必需的。规范发布片段位于 `docs/snippets/plugin-publish/`。
</Note>
### `openclaw` 字段
@ -76,10 +76,10 @@ x-i18n:
入口点文件（相对于包根目录）。
</ParamField>
<ParamField path="setupEntry" type="string">
轻量的仅设置入口（可选）。
轻量级、仅用于设置的入口（可选）。
</ParamField>
<ParamField path="channel" type="object">
用于设置、选择器、快速开始和 Status 表面的渠道目录元数据。
用于设置、选择器、快速开始和 Status 界面的渠道目录元数据。
</ParamField>
<ParamField path="providers" type="string[]">
此插件注册的提供商 ID。
@ -93,29 +93,29 @@ x-i18n:
### `openclaw.channel`
`openclaw.channel` 是低成本包元数据，用于在运行时加载前支持渠道发现和设置表面。
`openclaw.channel` 是廉价的包元数据，用于在运行时加载前提供渠道设备发现和设置界面。
| 字段 | 类型 | 含义 |
| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
| `id` | `string` | 规范渠道 ID。 |
| `label` | `string` | 主渠道标签。 |
| `selectionLabel` | `string` | 当需要不同于 `label` 时使用的选择器/设置标签。 |
| `detailLabel` | `string` | 用于更丰富的渠道目录和 Status 表面的次级详情标签。 |
| `docsPath` | `string` | 用于设置和选择链接的文档路径。 |
| `docsLabel` | `string` | 当需要不同于渠道 ID 时，用于文档链接的覆盖标签。 |
| `blurb` | `string` | 简短的新手引导/目录描述。 |
| `order` | `number` | 渠道目录中的排序顺序。 |
| `aliases` | `string[]` | 用于渠道选择的额外查找别名。 |
| `preferOver` | `string[]` | 此渠道应优先于的较低优先级插件/渠道 ID。 |
| `systemImage` | `string` | 用于渠道 UI 目录的可选图标/系统图像名称。 |
| `selectionDocsPrefix` | `string` | 选择表面中文档链接前的前缀文本。 |
| `selectionDocsOmitLabel` | `boolean` | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 |
| `selectionExtras` | `string[]` | 追加到选择文案中的额外短字符串。 |
| `markdownCapable` | `boolean` | 将渠道标记为支持 markdown，用于出站格式化决策。 |
| `exposure` | `object` | 用于设置、已配置列表和文档表面的渠道可见性控制。 |
| `quickstartAllowFrom` | `boolean` | 让此渠道加入标准快速开始 `allowFrom` 设置流程。 |
| `forceAccountBinding` | `boolean` | 即使只存在一个账号，也要求显式账号绑定。 |
| `preferSessionLookupForAnnounceTarget` | `boolean` | 为此渠道解析公告目标时，优先使用会话查找。 |
| `id` | `string` | 规范渠道 ID。 |
| `label` | `string` | 主要渠道标签。 |
| `selectionLabel` | `string` | 当需要不同于 `label` 时使用的选择器/设置标签。 |
| `detailLabel` | `string` | 用于更丰富的渠道目录和 Status 界面的次级详情标签。 |
| `docsPath` | `string` | 用于设置和选择链接的文档路径。 |
| `docsLabel` | `string` | 当需要不同于渠道 ID 时，用于文档链接的覆盖标签。 |
| `blurb` | `string` | 简短的新手引导/目录描述。 |
| `order` | `number` | 渠道目录中的排序顺序。 |
| `aliases` | `string[]` | 用于渠道选择的额外查找别名。 |
| `preferOver` | `string[]` | 此渠道应优先于其上的低优先级插件/渠道 ID。 |
| `systemImage` | `string` | 用于渠道 UI 目录的可选图标/系统图像名称。 |
| `selectionDocsPrefix` | `string` | 选择界面中文档链接前的前缀文本。 |
| `selectionDocsOmitLabel` | `boolean` | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 |
| `selectionExtras` | `string[]` | 附加到选择文案中的额外短字符串。 |
| `markdownCapable` | `boolean` | 将渠道标记为支持 Markdown，以用于出站格式化决策。 |
| `exposure` | `object` | 控制渠道在设置、已配置列表和文档界面中的可见性。 |
| `quickstartAllowFrom` | `boolean` | 让此渠道加入标准快速开始 `allowFrom` 设置流程。 |
| `forceAccountBinding` | `boolean` | 即使只有一个账号，也要求显式绑定账号。 |
| `preferSessionLookupForAnnounceTarget` | `boolean` | 为此渠道解析公告目标时优先使用会话查找。 |
示例：
@ -149,9 +149,9 @@ x-i18n:
`exposure` 支持：
- `configured`：在已配置/Status 风格的列表表面中包含该渠道
- `configured`：在已配置/Status 风格的列表界面中包含该渠道
- `setup`：在交互式设置/配置选择器中包含该渠道
- `docs`：在文档/导航表面中将该渠道标记为面向公众
- `docs`：在文档/导航界面中将该渠道标记为面向公众
<Note>
`showConfigured` 和 `showInSetup` 仍作为旧版别名受支持。优先使用 `exposure`。
@ -161,25 +161,25 @@ x-i18n:
`openclaw.install` 是包元数据，不是清单元数据。
| 字段 | 类型 | 含义 |
| ---------------------------- | ----------------------------------- | --------------------------------------------------------------------------------- |
| `clawhubSpec` | `string` | 用于安装/更新和新手引导按需安装流程的规范 ClawHub 规格。 |
| `npmSpec` | `string` | 用于安装/更新回退流程的规范 npm 规格。 |
| `localPath` | `string` | 本地开发或内置安装路径。 |
| `defaultChoice` | `"clawhub"` \| `"npm"` \| `"local"` | 当有多个来源可用时的首选安装来源。 |
| `minHostVersion` | `string` | 受支持的最低 OpenClaw 版本，格式为 `>=x.y.z` 或 `>=x.y.z-prerelease`。 |
| `expectedIntegrity` | `string` | 预期的 npm dist 完整性字符串，通常为 `sha512-...`，用于固定安装。 |
| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重装流程从特定过期配置失败中恢复。 |
| 字段 | 类型 | 含义 |
| ---------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------- |
| `clawhubSpec` | `string` | 用于安装/更新和新手引导按需安装流程的规范 ClawHub 规格。 |
| `npmSpec` | `string` | 用于安装/更新回退流程的规范 npm 规格。 |
| `localPath` | `string` | 本地开发或内置安装路径。 |
| `defaultChoice` | `"clawhub"` \| `"npm"` \| `"local"` | 当有多个来源可用时的首选安装来源。 |
| `minHostVersion` | `string` | 支持的最低 OpenClaw 版本，格式为 `>=x.y.z` 或 `>=x.y.z-prerelease`。 |
| `expectedIntegrity` | `string` | 预期的 npm dist 完整性字符串，通常为 `sha512-...`，用于固定版本安装。 |
| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重装流程从特定的过期配置故障中恢复。 |
<AccordionGroup>
<Accordion title="Onboarding behavior">
交互式新手引导也会将 `openclaw.install` 用于按需安装表面。如果你的插件在运行时加载前暴露提供商认证选项或渠道设置/目录元数据，新手引导可以显示该选项，提示选择 ClawHub、npm 或本地安装，安装或启用插件，然后继续所选流程。ClawHub 新手引导选项使用 `clawhubSpec`，存在时优先使用；npm 选项需要可信目录元数据以及注册表 `npmSpec`；精确版本和 `expectedIntegrity` 是可选的 npm 固定项。如果存在 `expectedIntegrity`，安装/更新流程会对 npm 强制校验它。将“显示什么”元数据保留在 `openclaw.plugin.json` 中，将“如何安装它”元数据保留在 `package.json` 中。
交互式新手引导也会将 `openclaw.install` 用于按需安装界面。如果你的插件在运行时加载前公开提供商认证选项或渠道设置/目录元数据，新手引导可以显示该选项，提示选择 ClawHub、npm 或本地安装，安装或启用插件，然后继续所选流程。ClawHub 新手引导选项使用 `clawhubSpec`，并且在存在时优先使用；npm 选项需要带有注册表 `npmSpec` 的可信目录元数据；精确版本和 `expectedIntegrity` 是可选的 npm 固定项。如果存在 `expectedIntegrity`，安装/更新流程会对 npm 强制校验它。将“显示什么”的元数据放在 `openclaw.plugin.json` 中，将“如何安装它”的元数据放在 `package.json` 中。
</Accordion>
<Accordion title="minHostVersion enforcement">
如果设置了 `minHostVersion`，安装和非内置清单注册表加载都会强制执行它。较旧的宿主会跳过外部插件；无效的版本字符串会被拒绝。内置源码插件被假定与宿主检出版本一致。
如果设置了 `minHostVersion`，安装和非内置的清单注册表加载都会强制执行它。较旧的主机会跳过外部插件；无效的版本字符串会被拒绝。内置源码插件会被假定与主机检出版本同版本。
</Accordion>
<Accordion title="Pinned npm installs">
对于固定的 npm 安装，请在 `npmSpec` 中保留精确版本，并添加预期制品完整性：
对于固定版本的 npm 安装，将精确版本保留在 `npmSpec` 中，并添加预期制品完整性：
```json
{
@ -195,7 +195,7 @@ x-i18n:
</Accordion>
<Accordion title="allowInvalidConfigRecovery scope">
`allowInvalidConfigRecovery` 不是破损配置的通用绕过机制。它仅用于狭义的内置插件恢复，因此重装/设置可以修复已知的升级残留，例如缺失的内置插件路径，或同一插件的过期 `channels.<id>` 条目。如果配置因无关原因损坏，安装仍会失败关闭，并提示操作员运行 `openclaw doctor --fix`。
`allowInvalidConfigRecovery` 不是损坏配置的通用绕过机制。它只用于狭窄的内置插件恢复场景，因此重装/设置可以修复已知的升级遗留问题，例如缺少内置插件路径，或同一插件存在过期的 `channels.<id>` 条目。如果配置因无关原因损坏，安装仍会失败关闭，并提示操作员运行 `openclaw doctor --fix`。
</Accordion>
</AccordionGroup>
@ -215,17 +215,17 @@ x-i18n:
}
```
启用后，即使对于已配置的渠道，OpenClaw 在监听前启动阶段也只会加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后加载。
启用后，即使对已经配置的渠道，OpenClaw 在监听前启动阶段也只加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后加载。
<Warning>
只有当你的 `setupEntry` 在 Gateway 网关开始监听前注册了它所需的一切（渠道注册、HTTP 路由、Gateway 网关方法）时，才启用延迟加载。如果完整入口拥有必需的启动能力，请保留默认行为。
只有当你的 `setupEntry` 在 Gateway 网关开始监听前注册了它所需的一切（渠道注册、HTTP 路由、Gateway 网关方法）时，才启用延迟加载。如果必需的启动能力由完整入口负责，请保留默认行为。
</Warning>
如果你的设置/完整入口注册 Gateway 网关 RPC 方法，请将它们放在插件专用前缀下。保留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍归核心所有，并始终解析为 `operator.admin`。
如果你的设置/完整入口注册 Gateway 网关 RPC 方法，请将它们放在插件特定的前缀下。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍由核心拥有，并且始终解析到 `operator.admin`。
## 插件清单
每个原生插件都必须在包根目录中附带一个 `openclaw.plugin.json`。OpenClaw 使用它在不执行插件代码的情况下验证配置。
每个原生插件都必须在包根目录提供一个 `openclaw.plugin.json`。OpenClaw 使用它在不执行插件代码的情况下验证配置。
```json
{
@ -245,7 +245,7 @@ x-i18n:
}
```
对于渠道插件，请添加 `kind` 和 `channels`：
对于渠道插件，添加 `kind` 和 `channels`：
```json
{
@ -260,7 +260,7 @@ x-i18n:
}
```
即使没有配置的插件也必须附带 schema。空 schema 是有效的：
即使插件没有配置，也必须提供架构。空架构是有效的：
```json
{
@ -272,7 +272,7 @@ x-i18n:
}
```
请参阅 [插件清单](/zh-CN/plugins/manifest) 获取完整的 schema 参考。
完整架构参考见 [插件清单](/zh-CN/plugins/manifest)。
## ClawHub 发布
@ -284,12 +284,12 @@ clawhub package publish your-org/your-plugin
```
<Note>
旧版仅 Skills 发布别名用于 Skills。插件包应始终使用 `clawhub package publish`。
旧版仅 Skills 发布别名面向 Skills。插件包应始终使用 `clawhub package publish`。
</Note>
## 设置入口
`setup-entry.ts` 文件是 `index.ts` 的轻量替代方案，当 OpenClaw 只需要设置界面（新手引导、配置修复、已禁用渠道检查）时会加载它。
`setup-entry.ts` 文件是 `index.ts` 的轻量替代方案，OpenClaw 会在只需要设置界面（新手引导、配置修复、已禁用渠道检查）时加载它。
```typescript
// setup-entry.ts
@ -299,57 +299,57 @@ import { myChannelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(myChannelPlugin);
```
这可以避免在设置流程中加载繁重的运行时代码（加密库、CLI 注册、后台服务）。
这避免在设置流程期间加载繁重的运行时代码（加密库、CLI 注册、后台服务）。
在旁路模块中保留设置安全导出的内置工作区渠道，可以使用 `openclaw/plugin-sdk/channel-entry-contract` 中的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，因此设置时的运行时接线可以保持轻量且明确。
在 sidecar 模块中保留设置安全导出的内置工作区渠道，可以使用来自 `openclaw/plugin-sdk/channel-entry-contract` 的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，因此设置时的运行时接线可以保持轻量且明确。
<AccordionGroup>
<Accordion title="OpenClaw 何时使用 setupEntry 而不是完整入口">
<Accordion title="When OpenClaw uses setupEntry instead of the full entry">
- 渠道已禁用，但需要设置/新手引导界面。
- 渠道已启用但尚未配置。
- 渠道已启用，但未配置。
- 已启用延迟加载（`deferConfiguredChannelFullLoadUntilAfterListen`）。
</Accordion>
<Accordion title="setupEntry 必须注册什么">
<Accordion title="What setupEntry must register">
- 渠道插件对象（通过 `defineSetupPluginEntry`）。
- Gateway 网关监听前所需的任何 HTTP 路由。
- 启动期间所需的任何 Gateway 网关方法。
这些启动期 Gateway 网关方法仍应避免使用保留的核心管理命名空间，例如 `config.*` 或 `update.*`。
这些启动 Gateway 网关方法仍应避免使用保留的核心管理命名空间，例如 `config.*` 或 `update.*`。
</Accordion>
<Accordion title="setupEntry 不应包含什么">
<Accordion title="What setupEntry should NOT include">
- CLI 注册。
- 后台服务。
- 繁重的运行时导入（加密、SDK）。
- 仅在启动后才需要的 Gateway 网关方法。
- 仅在启动后需要的 Gateway 网关方法。
</Accordion>
</AccordionGroup>
### 窄范围设置辅助导入
### 精简设置辅助导入
对于热路径上的仅设置流程，如果你只需要设置界面的一部分，优先使用窄范围设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 伞形入口：
对于热路径的仅设置流程，如果你只需要设置界面的一部分，请优先使用精简的设置辅助接口，而不是更宽泛的 `plugin-sdk/setup` 汇总入口：
| 导入路径 | 用途 | 关键导出 |
| 导入路径 | 用途 | 关键导出 |
| ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | 在 `setupEntry` / 延迟渠道启动中仍可用的设置时运行时辅助工具 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | 感知环境的账号设置适配器 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置/安装 CLI/归档/文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/setup-runtime` | 在 `setupEntry` / 延迟渠道启动中保持可用的设置时运行时辅助工具 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | 感知环境的账号设置适配器 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置/安装 CLI/归档/文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
当你需要完整的共享设置工具箱，包括 `moveSingleAccountChannelSectionToDefaultAccount(...)` 等配置补丁辅助工具时，请使用更宽泛的 `plugin-sdk/setup` 接缝。
当你需要完整的共享设置工具箱，包括 `moveSingleAccountChannelSectionToDefaultAccount(...)` 等配置补丁辅助工具时，请使用更宽泛的 `plugin-sdk/setup` 接口。
这些设置补丁适配器在导入时保持热路径安全。它们内置的单账号提升契约界面查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在实际使用适配器前急切加载内置契约界面发现逻辑。
设置补丁适配器在导入时保持热路径安全。它们内置的单账号提升契约界面查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在适配器实际使用前提前加载内置契约界面发现逻辑。
### 渠道拥有的单账号提升
当渠道从单账号顶层配置升级到 `channels.<id>.accounts.*` 时，默认共享行为会将提升后的账号作用域值移动到 `accounts.default`。
当渠道从单账号顶层配置升级到 `channels.<id>.accounts.*` 时，默认共享行为是将被提升的账号作用域值移动到 `accounts.default`。
内置渠道可以通过其设置契约界面缩小或覆盖该提升行为：
- `singleAccountKeysToMove`：应移动到提升后账号中的额外顶层键
- `namedAccountPromotionKeys`：当命名账号已存在时，只有这些键会移动到提升后的账号中；共享策略/投递键保留在渠道根部
- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账号接收提升后的值
- `singleAccountKeysToMove`：应移动到被提升账号中的额外顶层键
- `namedAccountPromotionKeys`：当命名账号已存在时，只有这些键会移动到被提升的账号；共享策略/投递键保留在渠道根级
- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账号接收被提升的值
<Note>
Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix 账号，或者 `defaultAccount` 指向现有的非规范键（例如 `Ops`），提升会保留该账号，而不是创建新的 `accounts.default` 条目。
@ -357,7 +357,7 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix
## 配置架构
插件配置会根据清单中的 JSON Schema 进行验证。用户通过以下方式配置插件：
插件配置会根据你的清单中的 JSON Schema 进行验证。用户通过以下方式配置插件：
```json5
{
@ -373,9 +373,9 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix
}
```
你的插件会在注册期间以 `api.pluginConfig` 接收此配置。
你的插件会在注册期间以 `api.pluginConfig` 的形式接收此配置。
对于渠道专用配置，请改用渠道配置部分：
对于特定于渠道的配置，请改用渠道配置部分：
```json5
{
@ -390,7 +390,7 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix
### 构建渠道配置架构
使用 `buildChannelConfigSchema` 将 Zod 架构转换为插件拥有的配置构件所使用的 `ChannelConfigSchema` 包装器：
使用 `buildChannelConfigSchema` 将 Zod 架构转换为插件拥有的配置产物所使用的 `ChannelConfigSchema` 包装器：
```typescript
import { z } from "zod";
@ -406,6 +406,20 @@ const accountSchema = z.object({
const configSchema = buildChannelConfigSchema(accountSchema);
```
如果你已经以 JSON Schema 或 TypeBox 编写契约，请使用直接辅助工具，这样 OpenClaw 就可以在元数据路径上跳过 Zod 到 JSON Schema 的转换：
```typescript
import { Type } from "typebox";
import { buildJsonChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
const configSchema = buildJsonChannelConfigSchema(
Type.Object({
token: Type.Optional(Type.String()),
allowFrom: Type.Optional(Type.Array(Type.String())),
}),
);
```
对于第三方插件，冷路径契约仍然是插件清单：将生成的 JSON Schema 镜像到 `openclaw.plugin.json#channelConfigs`，这样配置架构、设置和 UI 界面无需加载运行时代码即可检查 `channels.<id>`。
## 设置向导
@ -446,14 +460,14 @@ const setupWizard: ChannelSetupWizard = {
`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` 等。完整示例请参阅内置插件包（例如 Discord 插件的 `src/channel.setup.ts`）。
<AccordionGroup>
<Accordion title="共享 allowFrom 提示">
对于只需要标准 `note -> prompt -> parse -> merge -> patch` 流程的私信允许列表提示，优先使用 `openclaw/plugin-sdk/setup` 中的共享设置辅助工具：`createPromptParsedAllowFromForAccount(...)`、`createTopLevelChannelParsedAllowFromPrompt(...)` 和 `createNestedChannelParsedAllowFromPrompt(...)`。
<Accordion title="Shared allowFrom prompts">
对于只需要标准 `note -> prompt -> parse -> merge -> patch` 流程的私信允许列表提示，请优先使用来自 `openclaw/plugin-sdk/setup` 的共享设置辅助工具：`createPromptParsedAllowFromForAccount(...)`、`createTopLevelChannelParsedAllowFromPrompt(...)` 和 `createNestedChannelParsedAllowFromPrompt(...)`。
</Accordion>
<Accordion title="标准渠道设置 Status">
对于只因标签、分数和可选额外行而变化的渠道设置 Status 块，优先使用 `openclaw/plugin-sdk/setup` 中的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。
<Accordion title="Standard channel setup status">
对于仅因标签、分数和可选额外行而变化的渠道设置 Status 块，请优先使用来自 `openclaw/plugin-sdk/setup` 的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。
</Accordion>
<Accordion title="可选渠道设置界面">
对于只应在特定上下文中出现的可选设置界面，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface`：
<Accordion title="Optional channel setup surface">
对于只应在特定上下文中出现的可选设置界面，请使用来自 `openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface`：
```typescript
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";
@ -467,16 +481,16 @@ const setupWizard: ChannelSetupWizard = {
// Returns { setupAdapter, setupWizard }
```
当你只需要该可选安装界面的一半时，`plugin-sdk/channel-setup` 还公开更底层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器。
当你只需要该可选安装界面的一半时，`plugin-sdk/channel-setup` 还公开了更底层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器。
生成的可选适配器/向导会对真实配置写入采取失败关闭策略。它们在 `validateInput`、`applyAccountConfig` 和 `finalize` 中复用同一条需要安装的消息，并在设置了 `docsPath` 时附加文档链接。
生成的可选适配器/向导会对真实配置写入失败关闭。它们在 `validateInput`、`applyAccountConfig` 和 `finalize` 中复用同一条需要安装的消息，并在设置了 `docsPath` 时追加文档链接。
</Accordion>
<Accordion title="二进制支持的设置辅助工具">
对于二进制支持的设置 UI，优先使用共享的委托辅助工具，而不是在每个渠道中复制相同的二进制/Status 胶水代码：
<Accordion title="Binary-backed setup helpers">
对于由二进制文件支撑的设置 UI，请优先使用共享的委托辅助工具，而不是将相同的二进制/Status 胶水代码复制到每个渠道中：
- `createDetectedBinaryStatus(...)`：用于仅因标签、提示、分数和二进制检测而变化的 Status 块
- `createCliPathTextInput(...)`：用于基于路径的文本输入
- `createDetectedBinaryStatus(...)` 用于仅因标签、提示、分数和二进制检测而变化的 Status 块
- `createCliPathTextInput(...)` 用于由路径支撑的文本输入
- 当 `setupEntry` 需要惰性转发到更重的完整向导时，使用 `createDelegatedSetupWizardStatusResolvers(...)`、`createDelegatedPrepare(...)`、`createDelegatedFinalize(...)` 和 `createDelegatedResolveConfigured(...)`
- 当 `setupEntry` 只需要委托 `textInputs[*].shouldPrompt` 决策时，使用 `createDelegatedTextInputShouldPrompt(...)`
@ -488,21 +502,21 @@ const setupWizard: ChannelSetupWizard = {
**外部插件：**发布到 [ClawHub](/zh-CN/tools/clawhub)，然后安装：
<Tabs>
<Tab title="自动（先 ClawHub 后 npm）">
<Tab title="Auto (ClawHub then npm)">
```bash
openclaw plugins install @myorg/openclaw-my-plugin
```
OpenClaw 会先尝试 ClawHub，并自动回退到 npm。
OpenClaw 会先尝试 ClawHub，并在失败时自动回退到 npm。
</Tab>
<Tab title="仅 ClawHub">
<Tab title="ClawHub only">
```bash
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
</Tab>
<Tab title="npm 包规范">
当包尚未迁移到 ClawHub，或者迁移期间需要直接 npm 安装路径时，请使用 npm：
<Tab title="npm package spec">
当包尚未迁移到 ClawHub，或者你在迁移期间需要直接的 npm 安装路径时，请使用 npm：
```bash
openclaw plugins install npm:@myorg/openclaw-my-plugin
@ -520,16 +534,16 @@ openclaw plugins install <package-name>
```
<Info>
对于来自 npm 的安装，`openclaw plugins install` 会在禁用生命周期脚本的情况下，将包安装到 `~/.openclaw/npm` 下。保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。
对于来自 npm 的安装，`openclaw plugins install` 会在禁用生命周期脚本的情况下，将包安装到 `~/.openclaw/npm` 下。请保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。
</Info>
<Note>
Gateway 网关启动不会安装插件依赖。npm/git/ClawHub 安装流程负责依赖收敛；本地插件必须已经安装好自己的依赖。
Gateway 网关启动不会安装插件依赖项。npm/git/ClawHub 安装流程负责依赖收敛；本地插件必须已经安装好自己的依赖项。
</Note>
内置包元数据是显式的，不会在 Gateway 网关启动时从构建后的 JavaScript 推断。运行时依赖属于拥有它们的插件包；打包版 OpenClaw 启动永远不会修复或镜像插件依赖。
内置包元数据是显式的，而不是在 Gateway 网关启动时从构建后的 JavaScript 推断出来的。运行时依赖项应放在拥有它们的插件包中；打包版 OpenClaw 启动流程绝不会修复或镜像插件依赖项。
## 相关
## 相关内容
- [构建插件](/zh-CN/plugins/building-plugins) — 分步入门指南
- [插件清单](/zh-CN/plugins/manifest) — 完整清单架构参考

375
docs/zh-CN/plugins/sdk-subpaths.md
View File

@ -1,260 +1,260 @@
---
read_when:
- 为插件导入选择正确的 plugin-sdk 子路径
- 审计内置插件的子路径和辅助接口
summary: 插件 SDK 子路径目录：哪些导入位于何处，按区域分组
- 审计内置插件子路径和辅助接口面
summary: 插件 SDK 子路径目录：按领域分组说明各导入项位于何处
title: 插件 SDK 子路径
x-i18n:
generated_at: "2026-04-30T03:17:52Z"
generated_at: "2026-05-02T15:20:25Z"
model: gpt-5.5
provider: openai
source_hash: 6a8c431c1835fff6720a00984171e3f55886363654074d81859f50ca28a35104
source_hash: bc0d2dcf030796d2c73d4d679b9f8d7f6a8aaf71c6b5232b60afbbb50f42b348
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/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema`, `buildJsonChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/testing` | 旧版插件测试的宽兼容 barrel；新的插件测试应优先使用聚焦的测试子路径 |
| `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小 `OpenClawPluginApi` mock 构建器 |
| `plugin-sdk/agent-runtime-test-contracts` | 原生 Agent Runtime 适配器合约夹具，覆盖鉴权配置文件、投递抑制、回退分类、工具钩子、提示词叠加、schema 和转录修复 |
| `plugin-sdk/channel-test-helpers` | 渠道账号生命周期、目录、发送配置、运行时 mock、钩子、内置渠道入口、信封时间戳、配对回复和通用渠道合约测试辅助 |
| `plugin-sdk/testing` | 面向旧版插件测试的宽兼容性桶形导出；新的扩展测试应优先使用更聚焦的测试子路径 |
| `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小 `OpenClawPluginApi` 模拟构建器 |
| `plugin-sdk/agent-runtime-test-contracts` | 原生智能体运行时适配器契约夹具，覆盖认证配置文件、投递抑制、回退分类、工具钩子、提示词覆盖、模式以及转录修复 |
| `plugin-sdk/channel-test-helpers` | 渠道账号生命周期、目录、发送配置、运行时模拟、钩子、内置渠道入口、信封时间戳、配对回复以及通用渠道契约测试辅助工具 |
| `plugin-sdk/channel-target-testing` | 共享的渠道目标解析错误场景测试套件 |
| `plugin-sdk/plugin-test-contracts` | 插件注册、包 manifest、公开构件、运行时 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`、`withCachedMigrationConfigRuntime` 和 `writeMigrationReport` |
| `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/认证模拟 |
| `plugin-sdk/test-env` | 测试环境、获取/网络、一次性 HTTP 服务器、传入请求、实时测试、临时文件系统以及时间控制夹具 |
| `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、技能、智能体消息、系统事件、模块重载、内置插件路径、终端、分块、认证令牌以及类型化用例测试夹具 |
| `plugin-sdk/test-node-mocks` | 用于 Vitest `vi.mock("node:*")` 工厂内部的聚焦 Node 内置模拟辅助工具 |
| `plugin-sdk/migration` | 迁移提供商条目辅助工具，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助工具以及 `summarizeMigrationItems` |
| `plugin-sdk/migration-runtime` | 运行时迁移辅助工具，例如 `copyMigrationFileItem`、`withCachedMigrationConfigRuntime` 和 `writeMigrationReport` |
<AccordionGroup>
<Accordion title="渠道子路径">
| 子路径 | 主要导出 |
<Accordion title="Channel subpaths">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
| `plugin-sdk/config-schema` | 根 `openclaw.json` Zod 模式导出（`OpenClawSchema`） |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | 共享设置向导辅助、allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup` | 共享设置向导辅助工具、允许列表提示、设置状态构建器 |
| `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`, `resolveChannelDmAccess`, `resolveChannelDmAllowFrom`, `resolveChannelDmPolicy`, `normalizeChannelDmPolicy`, `normalizeLegacyDmAliases` |
| `plugin-sdk/channel-config-schema` | 共享渠道配置 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/channel-config-schema` | 共享渠道配置模式基元，以及 Zod 和直接 JSON/TypeBox 构建器 |
| `plugin-sdk/bundled-channel-config-schema` | 仅供维护的内置插件使用的内置 OpenClaw 渠道配置模式 |
| `plugin-sdk/channel-config-schema-legacy` | 内置渠道配置模式的已弃用兼容性别名 |
| `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/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/conversation-runtime` | 对话/线程绑定、配对以及已配置绑定辅助工具 |
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 |
| `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助工具 |
| `plugin-sdk/channel-config-primitives` | 窄渠道配置模式基元 |
| `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 兼容 facade，用于已发布的 `@openclaw/discord@2026.3.13` 和受跟踪的所有者兼容性；新插件应使用通用渠道 SDK 子路径 |
| `plugin-sdk/telegram-account` | 已弃用的 Telegram 账号解析兼容 facade，用于受跟踪的所有者兼容性；新插件应使用注入的运行时辅助或通用渠道 SDK 子路径 |
| `plugin-sdk/zalouser` | 已弃用的 Zalo Personal 兼容 facade，用于仍会导入发送者命令授权的已发布 Lark/Zalo 包；新插件应使用 `plugin-sdk/command-auth` |
| `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` | 用于传入丢弃和输入中/确认失败的渠道日志辅助 |
| `plugin-sdk/allowlist-config-edit` | 允许列表配置编辑/读取辅助工具 |
| `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/zalouser` | 已弃用的 Zalo Personal 兼容性门面，用于仍导入发送方命令授权的已发布 Lark/Zalo 包；新插件应使用 `plugin-sdk/command-auth` |
| `plugin-sdk/interactive-runtime` | 语义消息呈现、投递以及旧版交互式回复辅助工具。见 [消息呈现](/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` | 用于入站丢弃和输入/确认失败的渠道日志辅助工具 |
| `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-contract` | 渠道合约类型 |
| `plugin-sdk/channel-feedback` | 反馈/反应接线 |
| `plugin-sdk/channel-secret-runtime` | 窄密钥合约辅助，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 |
| `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生模式辅助工具 |
| `plugin-sdk/channel-route` | 共享路由规范化、由解析器驱动的目标解析、线程 ID 字符串化、路由键去重/压缩、已解析目标类型以及路由/目标比较辅助工具 |
| `plugin-sdk/channel-targets` | 目标解析辅助工具；路由比较调用方应使用 `plugin-sdk/channel-route` |
| `plugin-sdk/channel-contract` | 渠道契约类型 |
| `plugin-sdk/channel-feedback` | 反馈/回应接线 |
| `plugin-sdk/channel-secret-runtime` | 窄密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及密钥目标类型 |
</Accordion>
<Accordion title="提供商子路径">
| 子路径 | 主要导出 |
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/lmstudio` | 用于设置、目录发现和运行时模型准备的受支持 LM Studio 提供商外观 |
| `plugin-sdk/lmstudio-runtime` | 用于本地服务器默认值、模型发现、请求标头和已加载模型辅助函数的受支持 LM Studio 运行时外观 |
| `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/cli-backend` | CLI 后端默认值 + watchdog 常量 |
| `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助函数 |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导/配置文件写入辅助函数，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | 标准 OAuth 授权结果构建器 |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助函数，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | 标准 OAuth 凭证结果构建器 |
| `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助函数 |
| `plugin-sdk/provider-env-vars` | 提供商授权环境变量查找辅助函数 |
| `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-catalog-runtime` | 提供商目录增强运行时钩子，以及用于合约测试的插件提供商注册表接缝 |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`，共享 replay-policy 构建器、提供商端点辅助函数，以及模型 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` | 狭窄的网页抓取配置/选择合约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | 网页抓取提供商注册/缓存辅助函数 |
| `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用接线的提供商的狭窄网页搜索配置/凭据辅助函数 |
| `plugin-sdk/provider-web-search-contract` | 狭窄的网页搜索配置/凭据合约辅助函数，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及限定作用域的凭据设置器/获取器 |
| `plugin-sdk/provider-web-search` | 网页搜索提供商注册/缓存/运行时辅助函数 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `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-search 配置/凭证辅助函数，适用于不需要插件启用接线的提供商 |
| `plugin-sdk/provider-web-search-contract` | 窄范围 web-search 配置/凭证契约辅助函数，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及有作用域的凭证 setter/getter |
| `plugin-sdk/provider-web-search` | web-search 提供商注册/缓存/运行时辅助函数 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 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-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/global-singleton` | 进程本地 singleton/map/cache 辅助函数 |
| `plugin-sdk/group-activation` | 窄范围群组激活模式和命令解析辅助函数 |
</Accordion>
<Accordion title="授权和安全子路径">
| 子路径 | 主要导出 |
<Accordion title="凭证和安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `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-delivery-runtime` | 原生审批能力/交付适配器 |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作凭证辅助函数 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助函数 |
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 |
| `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助函数 |
| `plugin-sdk/approval-handler-adapter-runtime` | 用于热渠道入口点的轻量级原生审批适配器加载辅助函数 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助函数；当更狭窄的适配器/Gateway 网关接缝足够时，优先使用它们 |
| `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/approval-reply-runtime` | Exec/插件审批回复 payload 辅助函数 |
| `plugin-sdk/approval-runtime` | Exec/插件审批 payload 辅助函数、原生审批路由/运行时辅助函数，以及结构化审批显示辅助函数，例如 `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` | 主机 allowlist 和专用网络 SSRF 策略辅助函数 |
| `plugin-sdk/ssrf-dispatcher` | 不包含宽泛基础设施运行时表面的狭窄固定 dispatcher 辅助函数 |
| `plugin-sdk/ssrf-runtime` | 固定 dispatcher、SSRF 保护 fetch、SSRF 错误，以及 SSRF 策略辅助函数 |
| `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` | 不包含宽泛基础设施运行时表面的窄范围 pinned-dispatcher 辅助函数 |
| `plugin-sdk/ssrf-runtime` | Pinned-dispatcher、SSRF 保护的 fetch、SSRF 错误和 SSRF 策略辅助函数 |
| `plugin-sdk/secret-input` | 密钥输入解析辅助函数 |
| `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助函数，以及原始 websocket/body 强制转换 |
| `plugin-sdk/webhook-request-guards` | 请求 body 大小/超时辅助函数 |
| `plugin-sdk/webhook-request-guards` | 请求正文大小/超时辅助函数 |
</Accordion>
<Accordion title="运行时和存储子路径">
<Accordion title="Runtime and storage subpaths">
| 子路径 | 主要导出 |
| --- | --- |
| `plugin-sdk/runtime` | 广泛的运行时、日志、备份和插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 精简的运行时环境、记录器、超时、重试和退避辅助工具 |
| `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/lazy-runtime` | 延迟运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `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 网关协议错误和渠道状态补丁辅助工具 |
| `plugin-sdk/config-types` | 插件配置形状的仅类型配置表面，例如 `OpenClawConfig` 和渠道/提供商配置类型 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和惰性命令组辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端、事件循环就绪客户端启动辅助工具、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道 Status 补丁辅助工具 |
| `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` | 不依赖广泛 text-runtime barrel 的文件引用自动链接检测 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化和重复/冲突检查，即使内置 Telegram 契约表面不可用也可使用 |
| `plugin-sdk/text-autolink-runtime` | 文件引用自动链接检测，无需广泛的文本运行时桶文件 |
| `plugin-sdk/approval-runtime` | 执行/插件审批辅助工具、审批能力构建器、认证/配置文件辅助工具、原生路由/运行时辅助工具，以及结构化审批显示路径格式化 |
| `plugin-sdk/reply-runtime` | 共享的入站/回复运行时辅助工具、分块、调度、Heartbeat、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 精简的回复调度/最终化和会话标签辅助工具 |
| `plugin-sdk/reply-runtime` | 共享的入站/回复运行时辅助工具、分块、分发、Heartbeat、回复规划器 |
| `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 分块辅助工具 |
| `plugin-sdk/reply-chunking` | 窄范围文本/Markdown 分块辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储路径、会话键、更新时间和存储变更辅助工具 |
| `plugin-sdk/cron-store-runtime` | Cron 存储路径/加载/保存辅助工具 |
| `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` | 共享的渠道/账号 Status 摘要辅助工具、运行时状态默认值和问题元数据辅助工具 |
| `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/request-url` | 从类似 fetch/request 的输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带超时的命令运行器，提供规范化的 stdout/stderr 结果 |
| `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 |
| `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 |
| `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化 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 提供商配置解析辅助工具 |
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助工具 |
| `plugin-sdk/persistent-dedupe` | 基于磁盘的去重缓存辅助工具 |
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复调度辅助工具 |
| `plugin-sdk/acp-runtime-backend` | 面向启动时加载插件的轻量级 ACP 后端注册和回复调度辅助工具 |
| `plugin-sdk/acp-binding-resolve-runtime` | 无生命周期启动导入的只读 ACP 绑定解析 |
| `plugin-sdk/agent-config-primitives` | 精简的 agent 运行时配置模式原语 |
| `plugin-sdk/boolean-param` | 宽松的布尔参数读取器 |
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 |
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 |
| `plugin-sdk/acp-runtime-backend` | 用于启动加载插件的轻量级 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` | 共享的被动渠道、状态和环境代理辅助原语 |
| `plugin-sdk/extension-shared` | 共享的被动渠道、Status 和环境代理辅助原语 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 |
| `plugin-sdk/agent-harness` | 面向底层 agent harness 的实验性受信任插件表面：harness 类型、活动运行引导/中止辅助工具、OpenClaw 工具桥辅助工具、运行时计划工具策略辅助工具、终端结果分类、工具进度格式化/详情辅助工具，以及尝试结果实用工具 |
| `plugin-sdk/agent-harness` | 面向低层级智能体 harness 的实验性可信插件表面：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具、运行时计划工具策略辅助工具、终端结果分类、工具进度格式化/详情辅助工具，以及尝试结果实用工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 |
| `plugin-sdk/async-lock-runtime` | 面向小型运行时状态文件的进程本地异步锁辅助工具 |
| `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/file-access-runtime` | 安全的本地文件和媒体源路径辅助工具 |
| `plugin-sdk/delivery-queue-runtime` | 出站待处理投递排空辅助工具 |
| `plugin-sdk/file-access-runtime` | 安全本地文件和媒体源路径辅助工具 |
| `plugin-sdk/heartbeat-runtime` | Heartbeat 事件和可见性辅助工具 |
| `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 选项和固定 lookup 辅助工具 |
| `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` | 感知调度器的运行时 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` | Agent 目录/身份/工作区辅助工具 |
| `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 |
| `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 |
| `plugin-sdk/directory-runtime` | 配置支持的目录查询/去重 |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
@ -264,65 +264,62 @@ x-i18n:
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具、基于 ffprobe 的视频尺寸探测，以及媒体载荷构建器 |
| `plugin-sdk/media-store` | 精简媒体存储辅助工具，例如 `saveMediaBuffer` |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选选择，以及缺失模型消息 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助工具导出 |
| `plugin-sdk/text-runtime` | 共享文本/markdown/日志辅助工具，例如剥离智能体可见文本、markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具，以及安全文本实用工具 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如 assistant 可见文本剥离、Markdown 渲染/分块/表格辅助工具、遮蔽辅助工具、指令标签辅助工具，以及安全文本实用工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的指令、注册表、验证、OpenAI 兼容 TTS 构建器和语音辅助工具导出 |
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、指令、规范化和语音辅助工具导出 |
| `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具，以及共享 WebSocket 会话辅助工具 |
| `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/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` | 用于旧版插件测试的宽泛兼容性 barrel。新的插件测试应改为导入聚焦的 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 和转录投影测试的原生 Agent Runtimes 适配器契约夹具 |
| `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/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 契约、目录断言、账号启动生命周期、发送配置线程、运行时 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:*")` 工厂内部 |
</Accordion>
<Accordion title="记忆子路径">
| 子路径 | 主要导出 |
| --- | --- |
| `plugin-sdk/memory-core` | 用于管理器/配置/文件/CLI 辅助工具的内置 memory-core 辅助工具表面 |
| `plugin-sdk/memory-core-engine-runtime` | 记忆索引/搜索运行时外观 |
| `plugin-sdk/memory-core-host-engine-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 辅助工具的厂商中立别名 |
| `plugin-sdk/memory-core` | 用于管理器/配置/文件/CLI 辅助工具的内置 memory-core 辅助表面 |
| `plugin-sdk/memory-core-engine-runtime` | 记忆索引/搜索运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | 记忆主机基础引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | 记忆主机 embedding 契约、注册表访问、本地提供商，以及通用批处理/远程辅助工具 |
| `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` | 记忆主机 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` | 用于访问搜索管理器的主动记忆运行时门面 |
| `plugin-sdk/memory-host-status` | 记忆主机 Status 辅助工具的厂商中立别名 |
</Accordion>
<Accordion title="保留的内置辅助工具子路径">
当前没有保留的内置辅助工具 SDK 子路径。所有者特定的
辅助工具位于所属插件包内，而可复用的宿主契约
使用通用 SDK 子路径，例如 `plugin-sdk/gateway-runtime`、
`plugin-sdk/security-runtime` 和 `plugin-sdk/plugin-config-runtime`。
<Accordion title="预留的内置辅助子路径">
当前没有预留的内置辅助 SDK 子路径。所有者特定的辅助工具位于所属插件包内部，而可复用的主机契约使用通用 SDK 子路径，例如 `plugin-sdk/gateway-runtime`、`plugin-sdk/security-runtime` 和 `plugin-sdk/plugin-config-runtime`。
</Accordion>
</AccordionGroup>