diff --git a/docs/zh-CN/concepts/context-engine.md b/docs/zh-CN/concepts/context-engine.md index 5c6deddc5..e7cb2533e 100644 --- a/docs/zh-CN/concepts/context-engine.md +++ b/docs/zh-CN/concepts/context-engine.md @@ -6,10 +6,10 @@ read_when: summary: 上下文引擎：可插拔的上下文组装、压缩和子智能体生命周期 title: 上下文引擎 x-i18n: - generated_at: "2026-04-05T08:21:09Z" + generated_at: "2026-04-07T08:01:12Z" model: gpt-5.4 provider: openai - source_hash: 19fd8cbb0e953f58fd84637fc4ceefc65984312cf2896d338318bc8cf860e6d9 + source_hash: e8290ac73272eee275bce8e481ac7959b65386752caa68044d0c6f3e450acfb1 source_path: concepts/context-engine.md workflow: 15 --- @@ -17,111 +17,96 @@ x-i18n: # 上下文引擎 **上下文引擎**控制 OpenClaw 如何为每次运行构建模型上下文。 -它决定包含哪些消息、如何总结较早的历史，以及 -如何跨子智能体边界管理上下文。 +它决定包含哪些消息、如何总结较早的历史记录，以及如何跨子智能体边界管理上下文。 -OpenClaw 内置了一个 `legacy` 引擎。插件可以注册 -替代引擎，用来替换当前活动的上下文引擎生命周期。 +OpenClaw 内置了一个 `legacy` 引擎。插件可以注册其他引擎，以替换当前激活的上下文引擎生命周期。 ## 快速开始 -检查当前活动的是哪个引擎： +检查当前激活的是哪个引擎： ```bash openclaw doctor -# 或直接检查配置： +# or inspect config directly: cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine' ``` ### 安装上下文引擎插件 -上下文引擎插件的安装方式与其他 OpenClaw 插件相同。先安装， -再在槽位中选择该引擎： +上下文引擎插件的安装方式与其他 OpenClaw 插件相同。先安装，然后在槽位中选择该引擎： ```bash -# 从 npm 安装 +# Install from npm openclaw plugins install @martian-engineering/lossless-claw -# 或从本地路径安装（用于开发） +# Or install from a local path (for development) openclaw plugins install -l ./my-context-engine ``` -然后在配置中启用该插件，并将其选为活动引擎： +然后在配置中启用该插件，并将其选为当前激活的引擎： ```json5 // openclaw.json { plugins: { slots: { - contextEngine: "lossless-claw", // 必须与插件注册的引擎 id 匹配 + contextEngine: "lossless-claw", // must match the plugin's registered engine id }, entries: { "lossless-claw": { enabled: true, - // 插件特定配置放在这里（参见该插件的文档） + // Plugin-specific config goes here (see the plugin's docs) }, }, }, } ``` -安装并配置后，重启 Gateway 网关。 +安装并配置完成后，重启 Gateway 网关。 -要切换回内置引擎，将 `contextEngine` 设为 `"legacy"`（或者 -直接删除该键——`"legacy"` 是默认值）。 +如果要切回内置引擎，将 `contextEngine` 设置为 `"legacy"`（或完全删除该键——`"legacy"` 是默认值）。 ## 工作原理 -每次 OpenClaw 运行一次模型提示时，上下文引擎都会参与 -四个生命周期节点： +每次 OpenClaw 运行模型提示时，上下文引擎都会参与四个生命周期节点： -1. **摄取** — 当新消息被添加到会话时调用。引擎 - 可以将该消息存储或索引到它自己的数据存储中。 -2. **组装** — 在每次模型运行之前调用。引擎返回一个有序 - 消息集合（以及一个可选的 `systemPromptAddition`），并确保其适配 - token 预算。 -3. **压缩** — 当上下文窗口已满，或用户运行 - `/compact` 时调用。引擎会总结较旧的历史以释放空间。 -4. **轮次后** — 在一次运行完成后调用。引擎可以持久化状态、 - 触发后台压缩，或更新索引。 +1. **摄取**——当新消息被添加到会话时调用。引擎可以将该消息存储或索引到它自己的数据存储中。 +2. **组装**——在每次模型运行前调用。引擎返回一组有序消息（以及可选的 `systemPromptAddition`），这些内容会适配令牌预算。 +3. **压缩**——当上下文窗口已满，或用户运行 `/compact` 时调用。引擎会总结较早的历史记录以释放空间。 +4. **回合后**——在一次运行完成后调用。引擎可以持久化状态、触发后台压缩，或更新索引。 ### 子智能体生命周期（可选） -OpenClaw 当前会调用一个子智能体生命周期 hook： +OpenClaw 当前会调用一个子智能体生命周期钩子： -- **onSubagentEnded** — 当子智能体会话完成或被清理时进行清理。 +- **onSubagentEnded**——当子智能体会话完成或被清扫时执行清理。 -`prepareSubagentSpawn` hook 是接口的一部分，供未来使用，但 -运行时尚未调用它。 +`prepareSubagentSpawn` 钩子是接口的一部分，供未来使用，但运行时目前尚未调用它。 ### 系统提示附加内容 -`assemble` 方法可以返回一个 `systemPromptAddition` 字符串。OpenClaw -会将其前置到本次运行的系统提示中。这使引擎能够注入 -动态召回指引、检索说明或上下文感知提示， -而无需依赖静态工作区文件。 +`assemble` 方法可以返回一个 `systemPromptAddition` 字符串。OpenClaw 会将它预先添加到本次运行的系统提示前面。这样，引擎就可以注入动态回忆指引、检索说明或上下文感知提示，而无需依赖静态工作区文件。 -## 旧版引擎 +## legacy 引擎 内置的 `legacy` 引擎保留了 OpenClaw 的原始行为： -- **摄取**：无操作（会话管理器直接处理消息持久化）。 -- **组装**：直通（运行时中的现有 sanitize → validate → limit 流程 - 负责上下文组装）。 -- **压缩**：委托给内置的总结式压缩，它会创建 - 一条较旧消息的摘要，并保留最近消息不变。 -- **轮次后**：无操作。 +- **摄取**：空操作（消息持久化直接由会话管理器处理）。 +- **组装**：直接透传（运行时中的现有 sanitize → validate → limit 流水线负责上下文组装）。 +- **压缩**：委托给内置的总结式压缩机制，它会为较早的消息创建单个摘要，并保留最近的消息不变。 +- **回合后**：空操作。 -旧版引擎不会注册工具，也不会提供 `systemPromptAddition`。 +legacy 引擎不会注册工具，也不会提供 `systemPromptAddition`。 -当未设置 `plugins.slots.contextEngine`（或其值为 `"legacy"`）时， -会自动使用该引擎。 +当未设置 `plugins.slots.contextEngine`（或将其设置为 `"legacy"`）时，会自动使用此引擎。 ## 插件引擎 插件可以使用插件 API 注册一个上下文引擎： ```ts +import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; + export default function register(api) { api.registerContextEngine("my-engine", () => ({ info: { @@ -131,21 +116,24 @@ export default function register(api) { }, async ingest({ sessionId, message, isHeartbeat }) { - // 将消息存储到你的数据存储中 + // Store the message in your data store return { ingested: true }; }, - async assemble({ sessionId, messages, tokenBudget }) { - // 返回适配预算的消息 + async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) { + // Return messages that fit the budget return { messages: buildContext(messages, tokenBudget), estimatedTokens: countTokens(messages), - systemPromptAddition: "Use lcm_grep to search history...", + systemPromptAddition: buildMemorySystemPromptAddition({ + availableTools: availableTools ?? new Set(), + citationsMode, + }), }; }, async compact({ sessionId, force }) { - // 总结较旧上下文 + // Summarize older context return { ok: true, compacted: true }; }, })); @@ -173,57 +161,45 @@ export default function register(api) { 必需成员： -| Member | Kind | Purpose | -| ------------------ | -------- | ------------------------------------ | -| `info` | Property | 引擎 id、名称、版本，以及它是否拥有压缩控制权 | -| `ingest(params)` | Method | 存储单条消息 | -| `assemble(params)` | Method | 为模型运行构建上下文（返回 `AssembleResult`） | -| `compact(params)` | Method | 总结/缩减上下文 | +| Member | Kind | Purpose | +| ------------------ | -------- | -------------------------------------------------------- | +| `info` | Property | 引擎 id、名称、版本，以及它是否负责压缩 | +| `ingest(params)` | Method | 存储单条消息 | +| `assemble(params)` | Method | 为一次模型运行构建上下文（返回 `AssembleResult`） | +| `compact(params)` | Method | 总结/缩减上下文 | -`assemble` 返回一个 `AssembleResult`，其中包含： +`assemble` 返回一个 `AssembleResult`，包含： -- `messages` —— 要发送给模型的有序消息。 -- `estimatedTokens`（必填，`number`）—— 引擎对 - 已组装上下文总 token 数的估计。OpenClaw 会用它来进行压缩阈值 - 决策和诊断报告。 -- `systemPromptAddition`（可选，`string`）—— 前置到系统提示中的附加内容。 +- `messages`——要发送给模型的有序消息。 +- `estimatedTokens`（必需，`number`）——引擎对组装后上下文总令牌数的估算。OpenClaw 会将它用于压缩阈值判断和诊断报告。 +- `systemPromptAddition`（可选，`string`）——预先添加到系统提示之前的内容。 可选成员： -| Member | Kind | Purpose | -| ------------------------------ | ------ | ----------------------------------------------------------------------------------------------- | -| `bootstrap(params)` | Method | 为一个会话初始化引擎状态。当引擎首次看到某个会话时调用一次（例如导入历史）。 | -| `ingestBatch(params)` | Method | 以批处理方式摄取一个已完成轮次。一次运行完成后调用，其中包含该轮次的全部消息。 | -| `afterTurn(params)` | Method | 运行后的生命周期工作（持久化状态、触发后台压缩）。 | -| `prepareSubagentSpawn(params)` | Method | 为子会话设置共享状态。 | -| `onSubagentEnded(params)` | Method | 在子智能体结束后执行清理。 | -| `dispose()` | Method | 释放资源。在 Gateway 网关关闭或插件重载期间调用——不是按会话调用。 | +| Member | Kind | Purpose | +| ------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------- | +| `bootstrap(params)` | Method | 为会话初始化引擎状态。首次看到某个会话时调用一次（例如导入历史记录）。 | +| `ingestBatch(params)` | Method | 以批处理方式摄取一个已完成的回合。在一次运行完成后调用，并一次性提供该回合中的所有消息。 | +| `afterTurn(params)` | Method | 运行后的生命周期工作（持久化状态、触发后台压缩）。 | +| `prepareSubagentSpawn(params)` | Method | 为子会话设置共享状态。 | +| `onSubagentEnded(params)` | Method | 在子智能体结束后执行清理。 | +| `dispose()` | Method | 释放资源。在 Gateway 网关关闭或插件重载时调用——不是按会话调用。 | ### ownsCompaction -`ownsCompaction` 控制 Pi 内置的尝试内自动压缩是否在本次运行中 -保持启用： +`ownsCompaction` 控制 Pi 内置的尝试内自动压缩是否在本次运行中保持启用： -- `true` —— 该引擎拥有压缩行为的控制权。OpenClaw 会禁用 Pi 内置的 - 本次运行自动压缩，而引擎的 `compact()` 实现需要负责 `/compact`、溢出恢复压缩，以及它希望在 `afterTurn()` 中执行的任何主动 - 压缩。 -- `false` 或未设置 —— Pi 内置的自动压缩在提示 - 执行期间仍可能运行，但活动引擎的 `compact()` 方法仍会在 - `/compact` 和溢出恢复时被调用。 +- `true`——该引擎负责压缩行为。OpenClaw 会为该次运行禁用 Pi 的内置自动压缩，而引擎的 `compact()` 实现需要负责 `/compact`、溢出恢复压缩，以及它希望在 `afterTurn()` 中执行的任何主动压缩。 +- `false` 或未设置——Pi 的内置自动压缩在提示执行期间仍可能运行，但当前激活引擎的 `compact()` 方法仍会用于 `/compact` 和溢出恢复。 -`ownsCompaction: false` **并不**意味着 OpenClaw 会自动回退到 -旧版引擎的压缩路径。 +`ownsCompaction: false` **不**意味着 OpenClaw 会自动回退到 legacy 引擎的压缩路径。 这意味着插件有两种有效模式： -- **接管模式** —— 实现你自己的压缩算法，并设置 - `ownsCompaction: true`。 -- **委托模式** —— 设置 `ownsCompaction: false`，并让 `compact()` 调用 - `openclaw/plugin-sdk/core` 中的 `delegateCompactionToRuntime(...)`，以使用 - OpenClaw 内置的压缩行为。 +- **自主管理模式**——实现你自己的压缩算法，并设置 `ownsCompaction: true`。 +- **委托模式**——设置 `ownsCompaction: false`，并让 `compact()` 调用 `openclaw/plugin-sdk/core` 中的 `delegateCompactionToRuntime(...)`，以使用 OpenClaw 的内置压缩行为。 -对于一个活动的非接管型引擎来说，无操作的 `compact()` 是不安全的，因为它 -会为该引擎槽位禁用正常的 `/compact` 和溢出恢复压缩路径。 +对于一个处于激活状态、但不自主管理压缩的引擎来说，空操作 `compact()` 是不安全的，因为它会禁用该引擎槽位的正常 `/compact` 和溢出恢复压缩路径。 ## 配置参考 @@ -231,49 +207,33 @@ export default function register(api) { { plugins: { slots: { - // 选择当前活动的上下文引擎。默认值："legacy"。 - // 设为某个插件 id 以使用插件引擎。 + // Select the active context engine. Default: "legacy". + // Set to a plugin id to use a plugin engine. contextEngine: "legacy", }, }, } ``` -该槽位在运行时是互斥的——对于给定的一次运行或压缩操作， -只会解析一个已注册的上下文引擎。其他已启用的 -`kind: "context-engine"` 插件仍然可以加载并运行它们的注册 -代码；`plugins.slots.contextEngine` 只决定当 OpenClaw -需要上下文引擎时，会解析哪个已注册的引擎 id。 +该槽位在运行时是互斥的——对于给定的一次运行或压缩操作，只会解析一个已注册的上下文引擎。其他已启用的 `kind: "context-engine"` 插件仍然可以加载并运行其注册代码；`plugins.slots.contextEngine` 只决定当 OpenClaw 需要上下文引擎时，解析哪个已注册的引擎 id。 ## 与压缩和记忆的关系 -- **压缩**是上下文引擎的一项职责。旧版引擎 - 委托给 OpenClaw 内置的总结功能。插件引擎可以实现 - 任意压缩策略（DAG 摘要、向量检索等）。 -- **记忆插件**（`plugins.slots.memory`）与上下文引擎是分开的。 - 记忆插件提供搜索/检索；上下文引擎控制 - 模型能看到什么。它们可以协同工作——上下文引擎可能会在组装期间使用记忆 - 插件的数据。 -- **会话修剪**（在内存中裁剪旧工具结果）仍会运行， - 无论当前活动的是哪个上下文引擎。 +- **压缩**是上下文引擎的一项职责。legacy 引擎会委托给 OpenClaw 的内置总结机制。插件引擎可以实现任何压缩策略（DAG 摘要、向量检索等）。 +- **记忆插件**（`plugins.slots.memory`）与上下文引擎是分开的。记忆插件提供搜索/检索；上下文引擎控制模型能看到什么。它们可以协同工作——上下文引擎可能会在组装期间使用记忆插件数据。想使用当前激活记忆提示路径的插件引擎，应优先使用 `openclaw/plugin-sdk/core` 中的 `buildMemorySystemPromptAddition(...)`，它会将当前激活的记忆提示片段转换为可直接预加的 `systemPromptAddition`。如果引擎需要更底层的控制，它仍然可以通过 `openclaw/plugin-sdk/memory-host-core` 中的 `buildActiveMemoryPromptSection(...)` 拉取原始行。 +- **会话修剪**（在内存中裁剪旧的工具结果）仍会运行，无论当前激活的是哪个上下文引擎。 ## 提示 - 使用 `openclaw doctor` 验证你的引擎是否正确加载。 -- 如果正在切换引擎，现有会话会继续保留其当前历史。 - 新引擎会接管后续运行。 -- 引擎错误会被记录并显示在诊断信息中。如果某个插件引擎 - 注册失败，或无法解析所选引擎 id，OpenClaw - 不会自动回退；在你修复插件或将 - `plugins.slots.contextEngine` 切回 `"legacy"` 之前，运行都会失败。 -- 在开发时，使用 `openclaw plugins install -l ./my-engine` 将本地 - 插件目录以链接方式接入，而无需复制。 +- 如果你正在切换引擎，现有会话会继续保留其当前历史记录。新引擎会接管未来的运行。 +- 引擎错误会被记录并显示在诊断信息中。如果插件引擎注册失败，或无法解析所选的引擎 id，OpenClaw 不会自动回退；在你修复插件或将 `plugins.slots.contextEngine` 切回 `"legacy"` 之前，运行将会失败。 +- 在开发时，使用 `openclaw plugins install -l ./my-engine` 可以链接本地插件目录，而无需复制。 -另请参阅：[压缩](/concepts/compaction)、[上下文](/concepts/context)、 -[插件](/tools/plugin)、[插件清单](/plugins/manifest)。 +另请参阅：[压缩](/zh-CN/concepts/compaction)、[上下文](/zh-CN/concepts/context)、[插件](/zh-CN/tools/plugin)、[插件清单](/zh-CN/plugins/manifest)。 ## 相关 -- [上下文](/concepts/context) — 如何为智能体轮次构建上下文 -- [插件架构](/plugins/architecture) — 注册上下文引擎插件 -- [压缩](/concepts/compaction) — 总结长对话 +- [上下文](/zh-CN/concepts/context)——如何为智能体回合构建上下文 +- [插件架构](/zh-CN/plugins/architecture)——注册上下文引擎插件 +- [压缩](/zh-CN/concepts/compaction)——总结长对话 diff --git a/docs/zh-CN/plugins/architecture.md b/docs/zh-CN/plugins/architecture.md index e760a8ccc..8101abc35 100644 --- a/docs/zh-CN/plugins/architecture.md +++ b/docs/zh-CN/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - - 构建或调试原生 OpenClaw 插件 - - 理解插件能力模型或归属边界 - - 处理插件加载流水线或注册表 - - 实现 provider 运行时 hook 或渠道插件 + - 构建或调试原生 OpenClaw 插件时 + - 理解插件能力模型或归属边界时 + - 处理插件加载流水线或注册表时 + - 实现提供商运行时钩子或渠道插件时 sidebarTitle: Internals summary: 插件内部机制：能力模型、归属、契约、加载流水线和运行时辅助工具 title: 插件内部机制 x-i18n: - generated_at: "2026-04-07T06:56:52Z" + generated_at: "2026-04-07T08:04:42Z" model: gpt-5.4 provider: openai - source_hash: ba93f0a748e46ac7c7b9d10d78260e6e13b6e533d85a0b56f3c1ffa8ee5a3850 + source_hash: a48b387152c5a6a9782c5aaa9d6c215c16adb7cb256302d3e85f80b03f9b6898 source_path: plugins/architecture.md workflow: 15 --- @@ -19,131 +19,131 @@ x-i18n: # 插件内部机制 - 这是**深度架构参考**。实用指南请参见： + 这是**深度架构参考**。如需实用指南，请参见： - [安装并使用插件](/zh-CN/tools/plugin) — 用户指南 - [入门指南](/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) — 构建一个模型提供商 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 导入映射和注册 API -本页面介绍 OpenClaw 插件系统的内部架构。 +本页介绍 OpenClaw 插件系统的内部架构。 ## 公共能力模型 -能力是 OpenClaw 内部公开的**原生插件**模型。每个原生 OpenClaw 插件都会注册到一种或多种能力类型： +能力是 OpenClaw 内部公开的**原生插件**模型。每个原生 OpenClaw 插件都会针对一个或多个能力类型进行注册： -| 能力 | 注册方法 | 示例插件 | -| ---------------------- | ------------------------------------------------ | ------------------------------------ | -| 文本推理 | `api.registerProvider(...)` | `openai`, `anthropic` | -| CLI 推理后端 | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| 语音 | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| 图像生成 | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| 音乐生成 | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| 视频生成 | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Web 抓取 | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Web 搜索 | `api.registerWebSearchProvider(...)` | `google` | -| 渠道 / 消息传递 | `api.registerChannel(...)` | `msteams`, `matrix` | +| 能力 | 注册方式 | 示例插件 | +| -------------------- | ------------------------------------------------ | ----------------------------------- | +| 文本推理 | `api.registerProvider(...)` | `openai`, `anthropic` | +| CLI 推理后端 | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| 语音 | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| 图像生成 | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| 音乐生成 | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| 视频生成 | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Web 抓取 | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Web 搜索 | `api.registerWebSearchProvider(...)` | `google` | +| 渠道 / 消息传递 | `api.registerChannel(...)` | `msteams`, `matrix` | -一个注册了零能力、但提供 hooks、工具或服务的插件，是一种**仅遗留 hook** 插件。这种模式仍然受到完整支持。 +一个插件如果注册了零个能力，但提供了 hooks、工具或服务，则属于**旧版仅 hook** 插件。这种模式仍然得到完整支持。 ### 外部兼容性立场 -能力模型已经落地到 core 中，并且如今已被内置/原生插件使用，但外部插件兼容性仍需要比“它已导出，因此它已冻结”更严格的标准。 +能力模型已经在 core 中落地，并已被当前的内置/原生插件使用，但外部插件兼容性仍需要比“已导出，因此已冻结”更严格的标准。 当前指导原则： -- **现有外部插件：** 保持基于 hook 的集成正常工作；将其视为兼容性基线 -- **新的内置/原生插件：** 优先使用显式能力注册，而不是 vendor 专用的内部接入或新的仅 hook 设计 -- **采用能力注册的外部插件：** 可以，但应将各能力专用的辅助工具 surface 视为仍在演进，除非文档明确将某个契约标记为稳定 +- **现有外部插件：** 保持基于 hook 的集成继续可用；将其视为兼容性基线 +- **新的内置/原生插件：** 优先使用显式能力注册，而不是特定厂商的内部直连或新的仅 hook 设计 +- **采用能力注册的外部插件：** 允许这样做，但除非文档明确将某个契约标记为稳定，否则应将能力相关辅助接口视为仍在演进中 -实用规则： +实践规则： -- 能力注册 API 是预期方向 -- 在过渡期间，遗留 hooks 仍然是对外部插件最安全、最不容易破坏兼容性的路径 -- 导出的辅助工具子路径并不完全等价；优先使用文档说明的窄契约，而不是偶然导出的辅助工具 +- 能力注册 API 是预期的发展方向 +- 在过渡期间，旧版 hooks 仍然是对外部插件最安全、最不易破坏的路径 +- 已导出的辅助子路径并不都同等稳定；优先使用文档化的窄契约，而不是偶然暴露的辅助导出 ### 插件形态 -OpenClaw 会根据每个已加载插件的实际注册行为，而不是仅根据静态元数据，将其归类为一种形态： +OpenClaw 会根据每个已加载插件的实际注册行为来将其分类，而不只是看静态元数据： -- **plain-capability** —— 恰好注册一种能力类型（例如仅 provider 的插件 `mistral`） -- **hybrid-capability** —— 注册多种能力类型（例如 `openai` 同时拥有文本推理、语音、媒体理解和图像生成） -- **hook-only** —— 只注册 hooks（typed 或 custom），不注册能力、工具、命令或服务 -- **non-capability** —— 注册工具、命令、服务或路由，但不注册能力 +- **plain-capability** -- 恰好注册一种能力类型（例如像 `mistral` 这样的仅提供商插件） +- **hybrid-capability** -- 注册多种能力类型（例如 `openai` 同时拥有文本推理、语音、媒体理解和图像生成） +- **hook-only** -- 仅注册 hooks（类型化或自定义），不注册能力、工具、命令或服务 +- **non-capability** -- 注册工具、命令、服务或路由，但不注册能力 -使用 `openclaw plugins inspect ` 可查看插件的形态和能力明细。详情请参见 [CLI 参考](/cli/plugins#inspect)。 +使用 `openclaw plugins inspect ` 可查看插件的形态和能力明细。详见 [CLI 参考](/cli/plugins#inspect)。 -### 遗留 hooks +### 旧版 hooks -`before_agent_start` hook 仍作为仅 hook 插件的兼容路径被支持。现实中的遗留插件仍然依赖它。 +`before_agent_start` hook 仍然作为仅 hook 插件的兼容路径受到支持。现实中仍有旧版插件依赖它。 -方向： +方向如下： -- 保持可用 -- 在文档中标记为遗留 -- 对模型/provider 覆盖工作，优先使用 `before_model_resolve` -- 对提示词变更工作，优先使用 `before_prompt_build` -- 仅在真实使用量下降且 fixture 覆盖证明迁移安全后再移除 +- 保持其可用 +- 将其文档化为旧版能力 +- 针对模型/提供商覆写工作，优先使用 `before_model_resolve` +- 针对 prompt 变更工作，优先使用 `before_prompt_build` +- 只有在真实使用量下降且夹具覆盖证明迁移安全后，才移除它 ### 兼容性信号 当你运行 `openclaw doctor` 或 `openclaw plugins inspect ` 时，可能会看到以下标签之一： -| 信号 | 含义 | -| -------------------------- | ------------------------------------------------------------ | -| **config valid** | 配置解析正常，插件也能正确解析 | -| **compatibility advisory** | 插件使用了受支持但较旧的模式（例如 `hook-only`） | -| **legacy warning** | 插件使用了 `before_agent_start`，该能力已弃用 | -| **hard error** | 配置无效或插件加载失败 | +| 信号 | 含义 | +| ------------------------ | ------------------------------------------------------ | +| **config valid** | 配置解析正常，且插件可成功解析 | +| **compatibility advisory** | 插件使用了受支持但较旧的模式（例如 `hook-only`） | +| **legacy warning** | 插件使用了已弃用的 `before_agent_start` | +| **hard error** | 配置无效，或插件加载失败 | -`hook-only` 和 `before_agent_start` 如今都不会破坏你的插件——`hook-only` 只是提示性建议，而 `before_agent_start` 仅会触发警告。这些信号也会显示在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 +`hook-only` 和 `before_agent_start` 目前都不会导致你的插件失效 —— `hook-only` 只是提示，`before_agent_start` 只会触发警告。这些信号也会出现在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 ## 架构概览 OpenClaw 的插件系统有四层： -1. **Manifest + 设备发现** - OpenClaw 会从已配置路径、工作区根目录、全局扩展根目录和内置扩展中查找候选插件。设备发现会先读取原生 `openclaw.plugin.json` manifest，以及受支持 bundle 的 manifest。 +1. **清单 + 发现** + OpenClaw 会从已配置路径、工作区根目录、全局扩展根目录以及内置扩展中查找候选插件。发现阶段会先读取原生 `openclaw.plugin.json` 清单以及受支持的 bundle 清单。 2. **启用 + 验证** - Core 决定一个已发现的插件是启用、禁用、阻止，还是被选中用于某个独占槽位（例如 memory）。 + Core 会决定发现到的插件是启用、禁用、阻止，还是被选入某个排他插槽，例如 memory。 3. **运行时加载** - 原生 OpenClaw 插件通过 jiti 在进程内加载，并将能力注册到中央注册表。兼容 bundle 会被标准化为注册表记录，而无需导入运行时代码。 -4. **Surface 消费** - OpenClaw 的其余部分会读取注册表，以暴露工具、渠道、provider 设置、hooks、HTTP 路由、CLI 命令和服务。 + 原生 OpenClaw 插件会通过 jiti 在进程内加载，并将能力注册到中央注册表中。兼容 bundles 会被规范化为注册表记录，而无需导入运行时代码。 +4. **接口消费** + OpenClaw 的其余部分会读取注册表，以暴露工具、渠道、提供商设置、hooks、HTTP 路由、CLI 命令和服务。 -对于插件 CLI，根命令设备发现专门分为两个阶段： +对插件 CLI 而言，根命令发现会拆分为两个阶段： -- 解析期元数据来自 `registerCli(..., { descriptors: [...] })` -- 真正的插件 CLI 模块可以保持惰性加载，并在首次调用时注册 +- 解析时元数据来自 `registerCli(..., { descriptors: [...] })` +- 真正的插件 CLI 模块可以保持惰性，并在首次调用时注册 -这样既能让插件自有的 CLI 代码保留在插件内部，又能让 OpenClaw 在解析前预留根命令名称。 +这使插件自有的 CLI 代码保留在插件内部，同时仍允许 OpenClaw 在解析前预留根命令名称。 -关键设计边界： +重要的设计边界是： -- 设备发现 + 配置验证应当能够仅基于 **manifest/schema 元数据** 完成，而无需执行插件代码 +- 发现和配置验证应通过**清单 / schema 元数据**完成，而无需执行插件代码 - 原生运行时行为来自插件模块的 `register(api)` 路径 -这种拆分让 OpenClaw 能在完整运行时尚未激活之前，就验证配置、解释插件缺失/禁用原因，并构建 UI/schema 提示。 +这种拆分让 OpenClaw 可以在完整运行时激活前，先验证配置、解释缺失/禁用的插件，并构建 UI/schema 提示。 -### 渠道插件和共享 message 工具 +### 渠道插件与共享 message 工具 -对于常规聊天动作，渠道插件不需要单独注册发送/编辑/响应工具。OpenClaw 在 core 中保留一个共享的 `message` 工具，而渠道插件则拥有其背后的渠道专用设备发现与执行逻辑。 +渠道插件在普通聊天操作中，不需要单独注册发送/编辑/响应工具。OpenClaw 在 core 中保留一个共享的 `message` 工具，而渠道插件负责其背后的特定渠道发现和执行逻辑。 当前边界如下： -- core 拥有共享 `message` 工具宿主、提示词接线、session/thread 记录和执行分发 -- 渠道插件拥有作用域动作设备发现、能力设备发现以及所有渠道专用 schema 片段 -- 渠道插件拥有 provider 专用的 session 会话语法，例如会话 id 如何编码 thread id，或如何从父会话继承 -- 渠道插件通过其动作适配器执行最终动作 +- core 拥有共享 `message` 工具宿主、prompt 接线、会话/线程记录和执行分发 +- 渠道插件拥有作用域化动作发现、能力发现，以及所有渠道特定 schema 片段 +- 渠道插件拥有提供商特定的会话对话语法，例如会话 id 如何编码线程 id，或如何从父会话继承 +- 渠道插件通过自己的动作适配器执行最终动作 -对于渠道插件，SDK surface 是 -`ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的设备发现调用允许插件将可见动作、能力和 schema 贡献一起返回，从而避免这些部分彼此漂移。 +对于渠道插件，SDK 接口是 +`ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的发现调用允许插件一起返回其可见动作、能力和 schema 贡献，从而避免这些部分彼此漂移。 -Core 会将运行时作用域传入这个设备发现步骤。重要字段包括： +Core 会将运行时作用域传入这个发现步骤。重要字段包括： - `accountId` - `currentChannelId` @@ -152,87 +152,87 @@ Core 会将运行时作用域传入这个设备发现步骤。重要字段包括 - `sessionKey` - `sessionId` - `agentId` -- 可信入站 `requesterSenderId` +- 受信任的入站 `requesterSenderId` -这对上下文敏感的插件很重要。一个渠道可以根据当前活跃账户、当前房间/thread/message，或可信请求者身份，来隐藏或暴露消息动作，而无需在 core `message` 工具中硬编码渠道专用分支。 +这对上下文敏感型插件非常重要。渠道可以根据当前账户、当前房间/线程/消息，或受信任的请求者身份来隐藏或暴露消息动作，而不需要在 core 的 `message` 工具中硬编码渠道特定分支。 -这也是为什么嵌入式 runner 路由变更仍然属于插件工作：runner 负责把当前聊天/session 身份转发到插件设备发现边界，以便共享的 `message` 工具为当前轮次暴露正确的渠道自有 surface。 +这也是为什么嵌入式 runner 路由变更仍然属于插件工作：runner 负责将当前聊天/会话身份转发到插件发现边界，以便共享 `message` 工具在当前轮次暴露出正确的渠道自有接口。 -对于渠道自有的执行辅助工具，内置插件应将执行运行时保留在自己的扩展模块中。Core 不再拥有位于 `src/agents/tools` 下的 Discord、Slack、Telegram 或 WhatsApp 消息动作运行时。我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，内置插件应直接从其扩展自有模块导入本地运行时代码。 +对于渠道自有的执行辅助工具，内置插件应将执行运行时保留在自己的扩展模块中。Core 不再拥有位于 `src/agents/tools` 下的 Discord、Slack、Telegram 或 WhatsApp 消息动作运行时。我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，内置插件应直接从其扩展自有模块中导入本地运行时代码。 -同样的边界也适用于一般性的 provider 命名 SDK seam：core 不应导入面向 Slack、Discord、Signal、WhatsApp 或类似扩展的渠道专用便捷 barrel。如果 core 需要某种行为，要么消费该内置插件自己的 `api.ts` / `runtime-api.ts` barrel，要么把需求提升为共享 SDK 中的窄型通用能力。 +同样的边界也适用于一般情况下按提供商命名的 SDK 接缝：core 不应导入 Slack、Discord、Signal、WhatsApp 或类似扩展的渠道特定便捷 barrel。如果 core 需要某种行为，要么消费内置插件自己的 `api.ts` / `runtime-api.ts` barrel，要么将该需求提升为共享 SDK 中一个狭义的通用能力。 -对投票而言，目前有两条执行路径： +对投票来说，当前有两条执行路径： - `outbound.sendPoll` 是适用于符合通用投票模型渠道的共享基线 -- `actions.handleAction("poll")` 是更推荐的路径，用于渠道专用投票语义或额外投票参数 +- `actions.handleAction("poll")` 是用于渠道特定投票语义或额外投票参数的优先路径 -现在，core 会先等待插件投票分发拒绝该动作之后，才进行共享投票解析，这样插件自有的投票处理器就可以接受渠道专用投票字段，而不会先被通用投票解析器拦住。 +现在，core 会在插件投票分发拒绝该动作之后，才执行共享投票解析，因此插件自有的投票处理器可以接受渠道特定的投票字段，而不会先被通用投票解析器拦住。 完整启动顺序请参见 [加载流水线](#load-pipeline)。 ## 能力归属模型 -OpenClaw 将原生插件视为**公司**或**功能**的归属边界，而不是杂乱无章的一堆无关集成。 +OpenClaw 将原生插件视为某个**公司**或某个**功能**的归属边界，而不是一堆互不相关集成的杂物袋。 这意味着： -- 一个公司插件通常应拥有该公司的所有 OpenClaw 对接 surface -- 一个功能插件通常应拥有它引入的完整功能 surface -- 渠道应消费共享 core 能力，而不是临时重新实现 provider 行为 +- 一个公司插件通常应拥有该公司的全部 OpenClaw 对接接口 +- 一个功能插件通常应拥有它引入的完整功能接口 +- 渠道应消费共享 core 能力，而不是临时重新实现提供商行为 -示例： +例如： -- 内置的 `openai` 插件拥有 OpenAI 模型提供商行为，以及 OpenAI 的语音 + 实时语音 + 媒体理解 + 图像生成行为 +- 内置的 `openai` 插件拥有 OpenAI 模型提供商行为，以及 OpenAI 的语音、实时语音、媒体理解和图像生成行为 - 内置的 `elevenlabs` 插件拥有 ElevenLabs 语音行为 - 内置的 `microsoft` 插件拥有 Microsoft 语音行为 -- 内置的 `google` 插件拥有 Google 模型提供商行为，以及 Google 的媒体理解 + 图像生成 + Web 搜索行为 +- 内置的 `google` 插件拥有 Google 模型提供商行为，以及 Google 的媒体理解、图像生成和 Web 搜索行为 - 内置的 `firecrawl` 插件拥有 Firecrawl Web 抓取行为 - 内置的 `minimax`、`mistral`、`moonshot` 和 `zai` 插件拥有它们的媒体理解后端 -- 内置的 `qwen` 插件拥有 Qwen 文本 provider 行为，以及媒体理解和视频生成行为 -- `voice-call` 插件是一个功能插件：它拥有通话传输、工具、CLI、路由和 Twilio media-stream bridge，但它会消费共享的语音、实时转写和实时语音能力，而不是直接导入 vendor 插件 +- 内置的 `qwen` 插件拥有 Qwen 文本提供商行为，以及媒体理解和视频生成行为 +- `voice-call` 插件是一个功能插件：它拥有通话传输、工具、CLI、路由和 Twilio 媒体流桥接，但它消费共享的语音、实时转录和实时语音能力，而不是直接导入厂商插件 -预期最终状态是： +预期的最终状态是： -- OpenAI 保持在一个插件中，即使它横跨文本模型、语音、图像和未来的视频 -- 其他 vendor 也可以用同样方式管理自己的 surface area -- 渠道不需要关心哪个 vendor 插件拥有该 provider；它们只消费 core 暴露的共享能力契约 +- OpenAI 即使同时覆盖文本模型、语音、图像和未来视频，也仍然存在于一个插件中 +- 其他厂商也可以以同样方式管理自己的接口范围 +- 渠道不需要关心是哪一个厂商插件拥有该提供商；它们消费的是 core 暴露的共享能力契约 这就是关键区别： - **plugin** = 归属边界 - **capability** = 可由多个插件实现或消费的 core 契约 -所以，如果 OpenClaw 增加一个新领域，比如视频，首要问题不是“应该由哪个 provider 硬编码视频处理？”而是“core 的视频能力契约应当是什么？”一旦该契约存在，vendor 插件就可以对其进行注册，而渠道/功能插件也可以消费它。 +因此，如果 OpenClaw 新增像视频这样的领域，首先要问的不是“哪个提供商应该硬编码视频处理？”而是“core 的视频能力契约应该是什么？”一旦契约存在，厂商插件就可以据此注册，而渠道/功能插件也可以消费它。 -如果这个能力还不存在，通常正确的做法是： +如果该能力尚不存在，通常正确的做法是： 1. 在 core 中定义缺失的能力 -2. 通过类型化方式把它暴露到插件 API/运行时 -3. 让渠道/功能围绕这个能力接线 -4. 让 vendor 插件注册实现 +2. 通过插件 API/运行时以类型化方式暴露它 +3. 让渠道/功能对接到该能力 +4. 让厂商插件注册实现 -这样既能保持归属清晰，也能避免 core 行为依赖单一 vendor 或一次性的插件专用代码路径。 +这样既能保持归属明确，又能避免 core 行为依赖单一厂商或某条一次性的插件专用代码路径。 ### 能力分层 -在决定代码应当放在哪里时，可以使用这个心智模型： +在决定代码应该放在哪里时，请使用以下思维模型： -- **core 能力层**：共享编排、策略、回退、配置合并规则、交付语义和类型化契约 -- **vendor 插件层**：vendor 专用 API、认证、模型目录、语音合成、图像生成、未来视频后端、用量端点 -- **渠道/功能插件层**：Slack/Discord/voice-call 等集成，它们消费 core 能力并将其呈现到某个 surface 上 +- **core 能力层**：共享编排、策略、回退、配置合并规则、投递语义和类型化契约 +- **厂商插件层**：厂商特定 API、认证、模型目录、语音合成、图像生成、未来视频后端、用量端点 +- **渠道/功能插件层**：Slack / Discord / voice-call 等集成，这一层消费 core 能力并将其呈现在某个接口上 -例如，TTS 采用如下结构： +例如，TTS 遵循如下结构： -- core 拥有回复时 TTS 策略、回退顺序、偏好和渠道交付 +- core 拥有回复时 TTS 策略、回退顺序、偏好和渠道投递 - `openai`、`elevenlabs` 和 `microsoft` 拥有合成实现 -- `voice-call` 消费电话场景的 TTS 运行时辅助工具 +- `voice-call` 消费电话 TTS 运行时辅助工具 -未来能力也应优先遵循同样模式。 +未来的能力也应优先采用同样模式。 ### 多能力公司插件示例 -一个公司插件从外部看来应当是内聚的。如果 OpenClaw 具备模型、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、Web 抓取和 Web 搜索等共享契约，一个 vendor 就可以在一个地方拥有其所有 surface： +从外部看，一个公司插件应当是内聚的。如果 OpenClaw 拥有针对模型、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、Web 抓取和 Web 搜索的共享契约，那么一个厂商就可以在同一处拥有其全部接口： ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -286,185 +286,182 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -重点不在于具体辅助工具名称。关键在于这种结构： +关键不在于具体的辅助工具名称。关键在于这种结构： -- 一个插件拥有 vendor surface +- 一个插件拥有该厂商的接口 - core 仍拥有能力契约 -- 渠道和功能插件消费 `api.runtime.*` 辅助工具，而不是 vendor 代码 +- 渠道和功能插件消费的是 `api.runtime.*` 辅助工具，而不是厂商代码 - 契约测试可以断言插件确实注册了它声称拥有的能力 ### 能力示例：视频理解 -OpenClaw 已经将图像/音频/视频理解视为一种共享能力。这里同样适用相同的归属模型： +OpenClaw 已经将图像/音频/视频理解视为一种共享能力。同样的归属模型也适用于这里： 1. core 定义媒体理解契约 -2. vendor 插件按需注册 `describeImage`、`transcribeAudio` 和 `describeVideo` -3. 渠道和功能插件消费共享的 core 行为，而不是直接接到 vendor 代码 +2. 厂商插件按需注册 `describeImage`、`transcribeAudio` 和 `describeVideo` +3. 渠道和功能插件消费共享 core 行为，而不是直接连接厂商代码 -这样可以避免把某个 provider 的视频假设烘焙进 core 中。插件拥有 vendor surface；core 拥有能力契约和回退行为。 +这可以避免把某个提供商关于视频的假设硬编码进 core。插件拥有厂商接口；core 拥有能力契约和回退行为。 -视频生成已经使用同样的顺序：core 拥有类型化的能力契约和运行时辅助工具，而 vendor 插件则针对它注册 `api.registerVideoGenerationProvider(...)` 实现。 +视频生成已经采用了同样的顺序：core 拥有类型化能力契约和运行时辅助工具，而厂商插件针对 `api.registerVideoGenerationProvider(...)` 注册实现。 -需要一个具体的发布清单？请参见 +需要具体的发布清单吗？请参见 [能力扩展手册](/zh-CN/plugins/architecture)。 -## 契约与约束执行 +## 契约与强制执行 -插件 API surface 被有意设计为类型化，并集中在 -`OpenClawPluginApi` 中。这个契约定义了受支持的注册点，以及插件可以依赖的运行时辅助工具。 +插件 API 接口被有意设计为类型化，并集中在 +`OpenClawPluginApi` 中。这个契约定义了受支持的注册点，以及插件可依赖的运行时辅助工具。 -这很重要，原因如下： +其重要性在于： -- 插件作者可以获得一个稳定的内部标准 -- core 可以拒绝重复归属，例如两个插件注册相同的 provider id -- 启动时可以为格式错误的注册提供可执行的诊断 -- 契约测试可以强制约束内置插件的归属，并防止静默漂移 +- 插件作者可以获得统一、稳定的内部标准 +- core 可以拒绝重复归属，例如两个插件注册同一个提供商 id +- 启动时可以为格式错误的注册提供可操作的诊断信息 +- 契约测试可以强制内置插件的归属关系，并防止无声漂移 -有两层约束执行： +存在两层强制执行： -1. **运行时注册约束执行** - 插件注册表在插件加载时验证各项注册。例如：重复的 provider id、重复的 speech provider id，以及格式错误的注册，都会产生插件诊断，而不是导致未定义行为。 +1. **运行时注册强制执行** + 插件注册表会在插件加载时验证注册。例如，重复的提供商 id、重复的语音提供商 id，以及格式错误的注册，都会产出插件诊断，而不是导致未定义行为。 2. **契约测试** - 内置插件在测试运行期间会被捕获进契约注册表，以便 OpenClaw 能显式断言归属。当前这一机制用于模型提供商、语音提供商、Web 搜索提供商以及内置注册归属。 + 内置插件会在测试运行中被捕获到契约注册表内，从而使 OpenClaw 能显式断言归属关系。当前这已用于模型提供商、语音提供商、Web 搜索提供商以及内置注册归属。 -实际效果是，OpenClaw 能够预先知道哪个插件拥有哪个 surface。这使得 core 和渠道能够无缝组合，因为归属是声明式、类型化且可测试的，而不是隐式的。 +实际效果是，OpenClaw 从一开始就知道，哪个插件拥有哪个接口。这让 core 和渠道能够无缝组合，因为归属是声明式、类型化且可测试的，而不是隐式的。 -### 什么应该属于契约 +### 什么内容应该属于契约 -好的插件契约应当是： +好的插件契约应当： -- 类型化的 -- 小而精的 -- 能力专用的 -- 由 core 拥有 +- 类型化 +- 小而精 +- 针对特定能力 +- 由 core 持有 - 可被多个插件复用 -- 渠道/功能无需了解 vendor 即可消费 +- 可被渠道/功能消费而无需知道厂商细节 -不好的插件契约则是： +坏的插件契约则是： -- 隐藏在 core 中的 vendor 专用策略 -- 绕过注册表的一次性插件逃逸口 -- 渠道代码直接访问某个 vendor 实现 +- 隐藏在 core 中的厂商特定策略 +- 绕过注册表的一次性插件逃生口 +- 渠道代码直接深入厂商实现 - 不属于 `OpenClawPluginApi` 或 `api.runtime` 的临时运行时对象 -如果拿不准，提升抽象层级：先定义能力，再让插件接入它。 +如果拿不准，请提升抽象层级：先定义能力，再让插件接入。 ## 执行模型 -原生 OpenClaw 插件会与 Gateway 网关 **在同一进程内** 运行。它们不是沙箱隔离的。已加载的原生插件与 core 代码处于同一进程级信任边界。 +原生 OpenClaw 插件与 Gateway 网关**在同一进程内**运行。它们不是沙箱隔离的。已加载的原生插件与 core 代码处于相同的进程级信任边界。 这意味着： - 原生插件可以注册工具、网络处理器、hooks 和服务 -- 原生插件中的 bug 可能导致 gateway 崩溃或不稳定 -- 恶意原生插件等同于在 OpenClaw 进程内执行任意代码 +- 原生插件中的 bug 可能导致 Gateway 网关崩溃或不稳定 +- 恶意原生插件等同于在 OpenClaw 进程中执行任意代码 -兼容 bundle 默认更安全，因为 OpenClaw 当前将其视为元数据/内容包。就当前版本而言，这主要意味着内置 skills。 +兼容 bundles 默认更安全，因为 OpenClaw 目前将它们视为元数据/内容包。在当前版本中，这主要指内置 skills。 -对于非内置插件，请使用 allowlist 和显式安装/加载路径。应把工作区插件视为开发期代码，而不是生产默认值。 +对于非内置插件，请使用 allowlist 和显式安装/加载路径。应将工作区插件视为开发期代码，而不是生产默认值。 -对于内置工作区 package 名称，保持插件 id 锚定在 npm 名称中：默认使用 `@openclaw/`，或在插件刻意暴露更窄角色时，使用已批准的类型化后缀，例如 -`-provider`、`-plugin`、`-speech`、`-sandbox` 或 `-media-understanding`。 +对于内置工作区包名，应让插件 id 锚定在 npm 名称中：默认使用 `@openclaw/`，或者使用已批准的类型后缀，如 `-provider`、`-plugin`、`-speech`、`-sandbox` 或 `-media-understanding`，前提是该包有意暴露更窄的插件角色。 -重要信任说明： +重要的信任说明： -- `plugins.allow` 信任的是**插件 id**，而不是来源出处。 -- 如果某个工作区插件与某个内置插件拥有相同 id，当该工作区插件被启用/加入 allowlist 时，它会有意遮蔽内置副本。 -- 这是正常且有用的，适合本地开发、补丁测试和热修复。 +- `plugins.allow` 信任的是**插件 id**，而不是其来源 +- 与内置插件具有相同 id 的工作区插件，在该工作区插件启用/加入 allowlist 时，会有意遮蔽内置副本 +- 这属于正常且有用的行为，适用于本地开发、补丁测试和热修复 ## 导出边界 -OpenClaw 导出的是能力，而不是实现便利性。 +OpenClaw 导出的是能力，而不是实现层面的便捷接口。 -请保持能力注册公开，同时收紧非契约辅助工具导出： +保持能力注册为公共接口。收缩非契约辅助导出： -- 内置插件专用辅助工具子路径 -- 非公共 API 的运行时管线子路径 -- vendor 专用的便利辅助工具 -- 属于实现细节的 setup/onboarding 辅助工具 +- 内置插件特定的辅助子路径 +- 不打算作为公共 API 的运行时管道子路径 +- 厂商特定的便捷辅助工具 +- 属于实现细节的设置/新手引导辅助工具 -出于兼容性和内置插件维护原因，一些内置插件辅助工具子路径仍保留在生成的 SDK 导出映射中。当前示例包括 -`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 -`plugin-sdk/zalo-setup` 以及若干 `plugin-sdk/matrix*` seams。应将这些视为保留的实现细节导出，而不是新第三方插件推荐采用的 SDK 模式。 +为兼容性和内置插件维护起见，一些内置插件辅助子路径仍保留在生成的 SDK 导出映射中。当前示例包括 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup`，以及若干 `plugin-sdk/matrix*` 接缝。应将它们视为保留的实现细节导出，而不是推荐新第三方插件采用的 SDK 模式。 ## 加载流水线 -在启动时，OpenClaw 大致会这样执行： +启动时，OpenClaw 大致会执行以下步骤： 1. 发现候选插件根目录 -2. 读取原生或兼容 bundle 的 manifest 和 package 元数据 -3. 拒绝不安全候选项 -4. 标准化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、 +2. 读取原生或兼容 bundle 清单及包元数据 +3. 拒绝不安全的候选项 +4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、 `slots`、`load.paths`） -5. 为每个候选项决定是否启用 +5. 为每个候选项决定启用状态 6. 通过 jiti 加载已启用的原生模块 -7. 调用原生 `register(api)`（或 `activate(api)`——遗留别名）hooks，并把注册项收集到插件注册表中 -8. 将注册表暴露给命令/运行时 surfaces +7. 调用原生 `register(api)`（或 `activate(api)` —— 一个旧版别名）hook，并将注册收集到插件注册表中 +8. 将注册表暴露给命令/运行时接口 -`activate` 是 `register` 的遗留别名——加载器会解析当前存在的那个（`def.register ?? def.activate`），并在同一时机调用。所有内置插件都使用 `register`；新插件请优先使用 `register`。 +`activate` 是 `register` 的旧版别名 —— 加载器会解析现有者（`def.register ?? def.activate`），并在同一位置调用它。所有内置插件都使用 `register`；新插件请优先使用 `register`。 -安全关卡发生在**运行时执行之前**。如果入口路径逃逸出插件根目录、路径对所有人可写，或者对于非内置插件而言路径归属可疑，候选项都会被阻止。 +安全门会发生在**运行时执行之前**。当入口逃逸插件根目录、路径对所有人可写，或者对非内置插件而言路径归属看起来可疑时，候选项会被阻止。 -### Manifest 优先行为 +### 清单优先行为 -manifest 是控制平面的事实来源。OpenClaw 使用它来： +清单是控制平面的事实来源。OpenClaw 用它来： -- 标识插件 -- 发现已声明的 channels/skills/config schema 或 bundle 能力 +- 识别插件 +- 发现已声明的渠道/skills/配置 schema 或 bundle 能力 - 验证 `plugins.entries..config` - 增强 Control UI 标签/占位符 - 显示安装/目录元数据 -对于原生插件，运行时模块是数据平面部分。它会注册实际行为，例如 hooks、tools、commands 或 provider 流程。 +对于原生插件，运行时模块属于数据平面部分。它会注册实际行为，如 hooks、工具、命令或提供商流程。 -### 加载器缓存的内容 +### 加载器会缓存什么 -OpenClaw 会保留以下短生命周期的进程内缓存： +OpenClaw 会为以下内容保留短期的进程内缓存： -- 设备发现结果 -- manifest 注册表数据 +- 发现结果 +- 清单注册表数据 - 已加载的插件注册表 -这些缓存可减少启动抖动和重复命令开销。可以把它们视为短期性能缓存，而不是持久化。 +这些缓存可以减少突发启动和重复命令开销。可以安全地将其视为短生命周期的性能缓存，而不是持久化。 性能说明： - 设置 `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` 或 - `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` 可禁用这些缓存。 + `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` 可以禁用这些缓存。 - 使用 `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` 和 `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` 调整缓存窗口。 ## 注册表模型 -已加载插件不会直接改写各种随机的 core 全局状态。它们会注册到一个中央插件注册表中。 +已加载的插件不会直接修改 core 中随意的全局状态。它们会注册到一个中央插件注册表中。 注册表会跟踪： - 插件记录（身份、来源、出处、状态、诊断） - 工具 -- 遗留 hooks 和 typed hooks +- 旧版 hooks 和类型化 hooks - 渠道 -- providers -- Gateway RPC 处理器 +- 提供商 +- Gateway 网关 RPC 处理器 - HTTP 路由 - CLI 注册器 - 后台服务 - 插件自有命令 -然后，core 功能会从该注册表读取，而不是直接与插件模块交互。这样可以保持加载的单向性： +然后，core 功能会从该注册表中读取，而不是直接与插件模块交互。这样可以保持加载为单向过程： - 插件模块 -> 注册表注册 - core 运行时 -> 注册表消费 -这种分离对可维护性非常重要。它意味着大多数 core surface 只需要一个集成点：“读取注册表”，而不是“为每个插件模块写特殊分支”。 +这种分离对可维护性很重要。它意味着多数 core 接口只需要一个集成点：“读取注册表”，而不是“为每个插件模块写特例”。 ## 会话绑定回调 -绑定会话的插件可以在审批结果确定后做出响应。 +绑定会话的插件可以在审批解析后做出响应。 -使用 `api.onConversationBindingResolved(...)` 可在绑定请求被批准或拒绝后接收回调： +使用 `api.onConversationBindingResolved(...)` 可以在绑定请求被批准或拒绝后收到回调： ```ts export default { @@ -488,101 +485,101 @@ export default { - `status`：`"approved"` 或 `"denied"` - `decision`：`"allow-once"`、`"allow-always"` 或 `"deny"` -- `binding`：已批准请求对应的解析后绑定 -- `request`：原始请求摘要、detach 提示、sender id 和会话元数据 +- `binding`：已批准请求所解析出的绑定 +- `request`：原始请求摘要、分离提示、发送者 id 和会话元数据 -这个回调仅用于通知。它不会改变谁有权限绑定会话，并且它会在 core 审批处理完成后才运行。 +此回调仅用于通知。它不会改变谁可以绑定会话，并且会在 core 的审批处理完成之后运行。 -## 提供商运行时 hooks +## 提供商运行时钩子 -Provider 插件现在有两层： +提供商插件现在有两层： -- manifest 元数据：`providerAuthEnvVars` 用于在运行时加载前，以低成本查找 provider 的环境变量认证；`channelEnvVars` 用于在运行时加载前，以低成本查找渠道环境变量认证/设置；`providerAuthChoices` 用于在运行时加载前，以低成本提供 onboarding/认证选择标签和 CLI flag 元数据 -- 配置期 hooks：`catalog` / 遗留 `discovery` 以及 `applyConfigDefaults` -- 运行时 hooks：`normalizeModelId`、`normalizeTransport`、 - `normalizeConfig`、 - `applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、 - `resolveSyntheticAuth`、`resolveExternalAuthProfiles`、 - `shouldDeferSyntheticProfileAuth`、 - `resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、 - `contributeResolvedModelCompat`、`capabilities`、 - `normalizeToolSchemas`、`inspectToolSchemas`、 - `resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、 - `wrapStreamFn`、`resolveTransportTurnState`、 - `resolveWebSocketSessionPolicy`、`formatApiKey`、`refreshOAuth`、 - `buildAuthDoctorHint`、`matchesContextOverflowError`、 - `classifyFailoverReason`、`isCacheTtlEligible`、 - `buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、 - `isBinaryThinking`、`supportsXHighThinking`、 - `resolveDefaultThinkingLevel`、`isModernModelRef`、`prepareRuntimeAuth`、 - `resolveUsageAuth`、`fetchUsageSnapshot`、`createEmbeddingProvider`、 - `buildReplayPolicy`、 +- 清单元数据：`providerAuthEnvVars` 用于在运行时加载前进行廉价的提供商环境认证查找，`channelEnvVars` 用于在运行时加载前进行廉价的渠道环境/设置查找，`providerAuthChoices` 用于在运行时加载前提供廉价的新手引导/认证选择标签和 CLI flag 元数据 +- 配置时 hooks：`catalog` / 旧版 `discovery` 以及 `applyConfigDefaults` +- 运行时 hooks：`normalizeModelId`、`normalizeTransport`, + `normalizeConfig`, + `applyNativeStreamingUsageCompat`、`resolveConfigApiKey`, + `resolveSyntheticAuth`、`resolveExternalAuthProfiles`, + `shouldDeferSyntheticProfileAuth`, + `resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`, + `contributeResolvedModelCompat`、`capabilities`, + `normalizeToolSchemas`、`inspectToolSchemas`, + `resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`, + `wrapStreamFn`、`resolveTransportTurnState`, + `resolveWebSocketSessionPolicy`、`formatApiKey`、`refreshOAuth`, + `buildAuthDoctorHint`、`matchesContextOverflowError`, + `classifyFailoverReason`、`isCacheTtlEligible`, + `buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`, + `isBinaryThinking`、`supportsXHighThinking`, + `resolveDefaultThinkingLevel`、`isModernModelRef`、`prepareRuntimeAuth`, + `resolveUsageAuth`、`fetchUsageSnapshot`、`createEmbeddingProvider`, + `buildReplayPolicy`, `sanitizeReplayHistory`、`validateReplayTurns`、`onModelSelected` -OpenClaw 仍然拥有通用的智能体循环、故障转移、转录处理和工具策略。这些 hooks 是 provider 专用行为的扩展 surface，而不需要完整自定义的推理传输层。 +OpenClaw 仍然拥有通用智能体循环、故障切换、转录处理和工具策略。这些 hooks 是提供商特定行为的扩展接口，而无需整套自定义推理传输。 -当 provider 拥有基于环境变量的凭证，且通用认证/状态/模型选择器路径需要在不加载插件运行时的情况下看到它们时，请使用 manifest `providerAuthEnvVars`。当 onboarding/认证选择 CLI surface 需要在不加载 provider 运行时的情况下知道 provider 的 choice id、group 标签和简单单 flag 认证接线时，请使用 manifest `providerAuthChoices`。把 provider 运行时 `envVars` 保留给面向操作员的提示，例如 onboarding 标签或 OAuth client-id/client-secret 设置变量。 +当提供商具有基于环境变量的凭证，并且通用认证/状态/模型选择器路径需要在不加载插件运行时的情况下看到它们时，请使用清单中的 `providerAuthEnvVars`。当新手引导/认证选择 CLI 接口需要在不加载提供商运行时的情况下了解该提供商的 choice id、分组标签和简单单 flag 认证接线时，请使用清单中的 `providerAuthChoices`。将提供商运行时中的 `envVars` 保留给面向操作员的提示，例如新手引导标签或 OAuth client-id/client-secret 设置变量。 -当某个渠道具有由环境变量驱动的认证或设置，且通用 shell-env 回退、配置/状态检查或设置提示需要在不加载渠道运行时的情况下看到这些内容时，请使用 manifest `channelEnvVars`。 +当渠道具有由环境变量驱动的认证或设置，并且通用 shell-env 回退、配置/状态检查或设置提示需要在不加载渠道运行时的情况下看到它们时，请使用清单中的 `channelEnvVars`。 -### Hook 顺序和使用方式 +### Hook 顺序与用法 -对于模型/provider 插件，OpenClaw 会大致按以下顺序调用 hooks。 +对于模型/提供商插件，OpenClaw 大致按以下顺序调用 hooks。 “何时使用”列是快速决策指南。 -| # | Hook | 它的作用 | 何时使用 | -| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | 在生成 `models.json` 期间将 provider 配置发布到 `models.providers` 中 | provider 拥有目录或 base URL 默认值 | -| 2 | `applyConfigDefaults` | 在配置具体化期间应用 provider 自有的全局配置默认值 | 默认值依赖认证模式、环境变量或 provider 模型家族语义 | -| -- | _(built-in model lookup)_ | OpenClaw 先尝试常规的注册表/目录路径 | _(不是插件 hook)_ | -| 3 | `normalizeModelId` | 在查找前标准化遗留或预览版 model-id 别名 | provider 在规范模型解析前拥有别名清理逻辑 | -| 4 | `normalizeTransport` | 在通用模型组装前标准化 provider 家族的 `api` / `baseUrl` | provider 为同一传输家族中的自定义 provider id 拥有传输清理逻辑 | -| 5 | `normalizeConfig` | 在运行时/provider 解析前标准化 `models.providers.` | provider 需要将配置清理逻辑放在插件中；内置的 Google 家族辅助工具也会为受支持的 Google 配置项提供兜底 | -| 6 | `applyNativeStreamingUsageCompat` | 将原生分块流式传输用量兼容性重写应用到配置 providers | provider 需要基于端点的原生分块流式传输用量元数据修复 | -| 7 | `resolveConfigApiKey` | 在加载运行时认证前，为配置 providers 解析 env-marker 认证 | provider 拥有自己的 env-marker API key 解析逻辑；`amazon-bedrock` 在这里还有一个内置 AWS env-marker 解析器 | -| 8 | `resolveSyntheticAuth` | 在不持久化明文的情况下暴露本地/自托管或配置支持的认证 | provider 可以使用 synthetic/local 凭证标记运行 | -| 9 | `resolveExternalAuthProfiles` | 覆盖 provider 自有的外部认证 profile；默认 `persistence` 为 `runtime-only`，适用于 CLI/应用自有凭证 | provider 复用外部认证凭证，而不持久化复制的 refresh token | -| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的 synthetic profile 占位符优先级降到 env/config 支持认证之后 | provider 存储了不应抢占优先级的 synthetic 占位 profile | -| 11 | `resolveDynamicModel` | 针对本地注册表尚不存在的 provider 自有 model id，提供同步回退解析 | provider 接受任意上游 model id | -| 12 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | provider 在解析未知 id 前需要网络元数据 | -| 13 | `normalizeResolvedModel` | 在嵌入式 runner 使用已解析模型前进行最终重写 | provider 需要传输层重写，但仍使用 core 传输 | -| 14 | `contributeResolvedModelCompat` | 为经由其他兼容传输的 vendor 模型贡献兼容标志 | provider 能在代理传输上识别自己的模型，而无需接管该 provider | -| 15 | `capabilities` | 供共享 core 逻辑使用的 provider 自有 transcript/tooling 元数据 | provider 需要 transcript/provider 家族特性处理 | -| 16 | `normalizeToolSchemas` | 在嵌入式 runner 看到工具 schema 前对其进行标准化 | provider 需要传输家族级 schema 清理 | -| 17 | `inspectToolSchemas` | 在标准化后暴露 provider 自有 schema 诊断 | provider 希望给出关键字警告，而不需要 core 学会 provider 专用规则 | -| 18 | `resolveReasoningOutputMode` | 选择原生或带标签的 reasoning-output 契约 | provider 需要带标签的 reasoning/final output，而不是原生字段 | -| 19 | `prepareExtraParams` | 在通用流选项包装器之前标准化请求参数 | provider 需要默认请求参数或每 provider 的参数清理 | -| 20 | `createStreamFn` | 用自定义传输完全替换普通流路径 | provider 需要自定义线协议，而不仅仅是包装器 | -| 21 | `wrapStreamFn` | 在应用通用包装器之后对流进行包装 | provider 需要请求头/请求体/模型兼容包装器，而不是自定义传输 | -| 22 | `resolveTransportTurnState` | 附加原生的每轮传输头或元数据 | provider 希望通用传输发送 provider 原生轮次标识 | -| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或 session 冷却策略 | provider 希望通用 WS 传输调优 session 头或回退策略 | -| 24 | `formatApiKey` | auth-profile 格式化器：已存储 profile 会变成运行时 `apiKey` 字符串 | provider 存储额外认证元数据，并需要自定义运行时 token 形态 | -| 25 | `refreshOAuth` | 为自定义 refresh 端点或 refresh 失败策略覆盖 OAuth refresh | provider 不适配共享 `pi-ai` refresh 逻辑 | -| 26 | `buildAuthDoctorHint` | 当 OAuth refresh 失败时附加修复提示 | provider 在 refresh 失败后需要 provider 自有的认证修复指导 | -| 27 | `matchesContextOverflowError` | provider 自有的上下文窗口溢出匹配器 | provider 存在通用启发式无法识别的原始溢出错误 | -| 28 | `classifyFailoverReason` | provider 自有的故障转移原因分类 | provider 能把原始 API/传输错误映射为限流/过载等 | -| 29 | `isCacheTtlEligible` | 面向 proxy/backhaul providers 的提示词缓存策略 | provider 需要 proxy 专用的缓存 TTL 限制 | -| 30 | `buildMissingAuthMessage` | 替换通用缺失认证恢复消息 | provider 需要 provider 专用的缺失认证恢复提示 | -| 31 | `suppressBuiltInModel` | 过期上游模型隐藏，以及可选的面向用户错误提示 | provider 需要隐藏过期上游条目，或用 vendor 提示替换它们 | -| 32 | `augmentModelCatalog` | 在设备发现后附加 synthetic/final 目录条目 | provider 需要在 `models list` 和选择器中添加 synthetic 前向兼容条目 | -| 33 | `isBinaryThinking` | 面向 binary-thinking providers 的开/关推理切换 | provider 只暴露二元开关式 thinking | -| 34 | `supportsXHighThinking` | 为选定模型提供 `xhigh` 推理支持 | provider 只希望部分模型支持 `xhigh` | -| 35 | `resolveDefaultThinkingLevel` | 为特定模型家族提供默认 `/think` 级别 | provider 拥有某模型家族的默认 `/think` 策略 | -| 36 | `isModernModelRef` | 用于 live profile 过滤和 smoke 选择的现代模型匹配器 | provider 拥有 live/smoke 首选模型匹配逻辑 | -| 37 | `prepareRuntimeAuth` | 在推理前，将已配置凭证交换成实际运行时 token/key | provider 需要 token 交换或短期请求凭证 | -| 38 | `resolveUsageAuth` | 为 `/usage` 及相关状态 surface 解析用量/计费凭证 | provider 需要自定义用量/配额 token 解析或不同的用量凭证 | -| 39 | `fetchUsageSnapshot` | 在认证解析后获取并标准化 provider 专用的用量/配额快照 | provider 需要 provider 专用用量端点或负载解析器 | -| 40 | `createEmbeddingProvider` | 为 memory/search 构建 provider 自有 embedding 适配器 | memory embedding 行为应归 provider 插件所有 | -| 41 | `buildReplayPolicy` | 返回控制该 provider transcript 处理方式的 replay 策略 | provider 需要自定义 transcript 策略（例如剥离 thinking block） | -| 42 | `sanitizeReplayHistory` | 在通用 transcript 清理后重写 replay 历史 | provider 需要超出共享压缩辅助工具范围的 provider 专用 replay 重写 | -| 43 | `validateReplayTurns` | 在嵌入式 runner 前对 replay 轮次进行最终验证或整形 | provider 传输在通用清理后仍需更严格的轮次验证 | -| 44 | `onModelSelected` | 当模型变为活动状态时运行 provider 自有的后续副作用 | provider 需要遥测或 provider 自有状态处理 | +| # | Hook | 作用 | 何时使用 | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | 在生成 `models.json` 时将提供商配置发布到 `models.providers` | 提供商拥有目录或 base URL 默认值 | +| 2 | `applyConfigDefaults` | 在配置具体化期间应用提供商自有的全局配置默认值 | 默认值依赖认证模式、环境变量或提供商模型族语义 | +| -- | _(内置模型查找)_ | OpenClaw 会先尝试常规注册表/目录路径 | _(不是插件 hook)_ | +| 3 | `normalizeModelId` | 在查找前规范化旧版或预览版 model-id 别名 | 提供商拥有在规范模型解析前进行别名清理的逻辑 | +| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商家族的 `api` / `baseUrl` | 提供商拥有同一传输家族中自定义 provider id 的传输清理逻辑 | +| 5 | `normalizeConfig` | 在运行时/提供商解析前规范化 `models.providers.` | 提供商需要将配置清理逻辑保留在插件中；内置 Google 家族辅助工具也会为受支持的 Google 配置项提供兜底清理 | +| 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式用量兼容性重写 | 提供商需要按端点驱动修复原生流式用量元数据 | +| 7 | `resolveConfigApiKey` | 在加载运行时认证前，为配置提供商解析 env-marker 认证 | 提供商拥有自有的 env-marker API key 解析；`amazon-bedrock` 在这里也有内置的 AWS env-marker 解析器 | +| 8 | `resolveSyntheticAuth` | 在不持久化明文的前提下，暴露 local/self-hosted 或配置支持的认证 | 提供商可以使用 synthetic/local 凭证标记运行 | +| 9 | `resolveExternalAuthProfiles` | 叠加提供商自有的外部认证配置文件；默认 `persistence` 为 `runtime-only`，用于 CLI/应用自有凭证 | 提供商复用外部认证凭证，而不持久化复制的 refresh token | +| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的 synthetic 配置文件占位符降级到环境变量/配置支持认证之后 | 提供商存储了 synthetic 占位配置文件，而这些配置文件不应获得更高优先级 | +| 11 | `resolveDynamicModel` | 为尚未出现在本地注册表中的提供商自有 model id 提供同步回退 | 提供商接受任意上游 model id | +| 12 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 前需要网络元数据 | +| 13 | `normalizeResolvedModel` | 在嵌入式 runner 使用已解析模型前做最终重写 | 提供商需要传输重写，但仍使用 core 传输 | +| 14 | `contributeResolvedModelCompat` | 为另一种兼容传输背后的厂商模型提供兼容标志 | 提供商能在代理传输上识别自己的模型，而无需接管该提供商 | +| 15 | `capabilities` | 由共享 core 逻辑使用的提供商自有 transcript/tooling 元数据 | 提供商需要 transcript/提供商家族层面的特殊处理 | +| 16 | `normalizeToolSchemas` | 在嵌入式 runner 看到工具 schema 前对其进行规范化 | 提供商需要针对传输家族进行 schema 清理 | +| 17 | `inspectToolSchemas` | 在规范化后暴露提供商自有的 schema 诊断 | 提供商想要关键字警告，而不想让 core 学习提供商特定规则 | +| 18 | `resolveReasoningOutputMode` | 选择原生或带标签的 reasoning-output 契约 | 提供商需要带标签的 reasoning/final output，而不是原生字段 | +| 19 | `prepareExtraParams` | 在通用流选项包装器之前进行请求参数规范化 | 提供商需要默认请求参数或按提供商进行参数清理 | +| 20 | `createStreamFn` | 用自定义传输完全替换常规流路径 | 提供商需要自定义线协议，而不只是包装器 | +| 21 | `wrapStreamFn` | 在应用通用包装器后对流进行包装 | 提供商需要请求头/请求体/模型兼容包装器，而不需要自定义传输 | +| 22 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | 提供商希望通用传输发送提供商原生轮次身份 | +| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | 提供商希望通用 WS 传输调整会话头或回退策略 | +| 24 | `formatApiKey` | 认证配置文件格式化器：已存储配置文件变成运行时 `apiKey` 字符串 | 提供商存储额外认证元数据，并需要自定义运行时 token 形态 | +| 25 | `refreshOAuth` | 为自定义刷新端点或刷新失败策略覆写 OAuth 刷新逻辑 | 提供商不适配共享的 `pi-ai` 刷新器 | +| 26 | `buildAuthDoctorHint` | 当 OAuth 刷新失败时追加修复提示 | 提供商需要在刷新失败后给出自有认证修复指导 | +| 27 | `matchesContextOverflowError` | 提供商自有的上下文窗口溢出错误匹配器 | 提供商有原始溢出错误，而通用启发式无法识别 | +| 28 | `classifyFailoverReason` | 提供商自有的故障切换原因分类 | 提供商可以把原始 API/传输错误映射为限流/过载等 | +| 29 | `isCacheTtlEligible` | 面向代理/回传提供商的 prompt-cache 策略 | 提供商需要针对代理场景控制 cache TTL | +| 30 | `buildMissingAuthMessage` | 用于替换通用缺失认证恢复消息 | 提供商需要特定的缺失认证恢复提示 | +| 31 | `suppressBuiltInModel` | 过时上游模型的抑制，以及可选的面向用户错误提示 | 提供商需要隐藏过时的上游条目，或用厂商提示替换它们 | +| 32 | `augmentModelCatalog` | 在发现之后追加 synthetic/最终目录条目 | 提供商需要在 `models list` 和选择器中添加 synthetic 的前向兼容条目 | +| 33 | `isBinaryThinking` | 针对二元 thinking 提供商的开/关推理开关 | 提供商仅暴露二元 thinking 开/关 | +| 34 | `supportsXHighThinking` | 为选定模型提供 `xhigh` 推理支持 | 提供商仅希望部分模型支持 `xhigh` | +| 35 | `resolveDefaultThinkingLevel` | 为特定模型家族确定默认 `/think` 级别 | 提供商拥有某个模型家族的默认 `/think` 策略 | +| 36 | `isModernModelRef` | 用于 live profile 过滤和 smoke 选择的 modern-model 匹配器 | 提供商拥有 live/smoke 首选模型匹配逻辑 | +| 37 | `prepareRuntimeAuth` | 在推理前将已配置凭证交换成实际运行时 token/key | 提供商需要 token 交换或短时请求凭证 | +| 38 | `resolveUsageAuth` | 为 `/usage` 及相关状态接口解析用量/计费凭证 | 提供商需要自定义用量/配额 token 解析或不同的用量凭证 | +| 39 | `fetchUsageSnapshot` | 在认证解析后，抓取并规范化提供商特定的用量/配额快照 | 提供商需要提供商特定的用量端点或负载解析器 | +| 40 | `createEmbeddingProvider` | 为 memory/search 构建提供商自有 embedding 适配器 | Memory embedding 行为应属于提供商插件 | +| 41 | `buildReplayPolicy` | 返回一个控制 transcript 处理方式的 replay 策略 | 提供商需要自定义 transcript 策略（例如移除 thinking block） | +| 42 | `sanitizeReplayHistory` | 在通用 transcript 清理后重写 replay 历史 | 提供商需要超出共享压缩辅助工具之外的 replay 重写 | +| 43 | `validateReplayTurns` | 在嵌入式 runner 前对 replay turns 做最终验证或重塑 | 提供商传输在通用清洗后仍需要更严格的 turn 验证 | +| 44 | `onModelSelected` | 在模型变为活跃后运行提供商自有副作用 | 提供商需要遥测或提供商自有状态更新 | -`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配的 provider 插件，然后回落到其他支持 hook 的 provider 插件，直到某个插件真正更改了 model id 或 transport/config。这样可以让 alias/兼容 provider shim 正常工作，而不要求调用方知道哪个内置插件拥有该重写逻辑。如果没有任何 provider hook 重写受支持的 Google 家族配置项，内置的 Google 配置标准化器仍会执行兼容性清理。 +`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查匹配到的提供商插件，然后回退遍历其他具备 hook 能力的提供商插件，直到其中某个插件实际修改了 model id 或 transport/config。这样可以让别名/兼容提供商 shim 继续工作，而无需调用方知道哪个内置插件拥有该重写逻辑。如果没有任何提供商 hook 重写某个受支持的 Google 家族配置项，内置 Google 配置规范器仍会执行该兼容性清理。 -如果 provider 需要完全自定义的线协议或自定义请求执行器，那就是另一类扩展。这些 hooks 适用于仍运行在 OpenClaw 常规推理循环上的 provider 行为。 +如果提供商需要完全自定义的线协议或自定义请求执行器，那就是另一类扩展了。这里的 hooks 适用于仍运行在 OpenClaw 常规推理循环上的提供商行为。 -### Provider 示例 +### 提供商示例 ```ts api.registerProvider({ @@ -640,63 +637,103 @@ api.registerProvider({ - Anthropic 使用 `resolveDynamicModel`、`capabilities`、`buildAuthDoctorHint`、 `resolveUsageAuth`、`fetchUsageSnapshot`、`isCacheTtlEligible`、 - `resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef` - 和 `wrapStreamFn`，因为它拥有 Claude 4.6 前向兼容、provider 家族提示、认证修复指导、用量端点集成、提示词缓存资格、带认证感知的配置默认值、Claude 默认/自适应 thinking 策略，以及针对 beta headers、`/fast` / `serviceTier` 和 `context1m` 的 Anthropic 专用流整形。 -- Anthropic 的 Claude 专用流辅助工具目前保留在该内置插件自己的公共 `api.ts` / `contract-api.ts` seam 中。该 package surface 导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 - `resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 Anthropic wrapper builder，而不是为了某个 provider 的 beta-header 规则扩展通用 SDK。 + `resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、 + 以及 `wrapStreamFn`，因为它拥有 Claude 4.6 前向兼容、 + 提供商家族提示、认证修复指导、用量端点集成、 + prompt-cache 资格、感知认证的配置默认值、Claude 的 + 默认/自适应 thinking 策略，以及 Anthropic 特定的流塑形逻辑，用于处理 + beta headers、`/fast` / `serviceTier` 和 `context1m`。 +- Anthropic 的 Claude 特定流辅助工具目前保留在该内置插件自己的 + 公共 `api.ts` / `contract-api.ts` 接缝中。该包接口 + 导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 + `resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及更底层的 + Anthropic 包装器构建器，而不是为了某个提供商的 beta-header 规则去扩展通用 SDK。 - OpenAI 使用 `resolveDynamicModel`、`normalizeResolvedModel` 和 `capabilities`，以及 `buildMissingAuthMessage`、`suppressBuiltInModel`、 `augmentModelCatalog`、`supportsXHighThinking` 和 `isModernModelRef`， - 因为它拥有 GPT-5.4 前向兼容、直接 OpenAI - `openai-completions` -> `openai-responses` 标准化、面向 Codex 的认证提示、Spark 抑制、synthetic OpenAI 列表条目，以及 GPT-5 thinking / live-model 策略；`openai-responses-defaults` 流家族则拥有共享的原生 OpenAI Responses 包装器，用于 attribution headers、 - `/fast`/`serviceTier`、文本冗长度、原生 Codex Web 搜索、reasoning-compat 负载整形和 Responses 上下文管理。 -- OpenRouter 使用 `catalog`、`resolveDynamicModel` 和 - `prepareDynamicModel`，因为这个 provider 是透传型的，可能会在 OpenClaw 静态目录更新之前暴露新的 model id；它还使用 - `capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，以便将 provider 专用请求头、路由元数据、reasoning 补丁和提示词缓存策略从 core 中分离出去。它的 replay 策略来自 - `passthrough-gemini` 家族，而 `openrouter-thinking` 流家族则负责代理推理注入，以及对不支持模型和 `auto` 的跳过处理。 + 因为它拥有 GPT-5.4 前向兼容、直接 OpenAI 的 + `openai-completions` -> `openai-responses` 规范化、感知 Codex 的认证 + 提示、Spark 抑制、synthetic OpenAI 列表条目，以及 GPT-5 的 thinking / + live-model 策略；`openai-responses-defaults` 流家族拥有共享的原生 OpenAI Responses 包装器，用于处理 attribution headers、 + `/fast`/`serviceTier`、文本冗长度、原生 Codex Web 搜索、 + reasoning-compat 负载塑形，以及 Responses 上下文管理。 +- OpenRouter 使用 `catalog`，以及 `resolveDynamicModel` 和 + `prepareDynamicModel`，因为该提供商是透传型的，可能会在 OpenClaw 静态目录更新之前暴露新的 + model id；它还使用 + `capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，以便将 + 提供商特定请求头、路由元数据、reasoning 补丁和 + prompt-cache 策略保留在 core 之外。它的 replay 策略来自 + `passthrough-gemini` 家族，而 `openrouter-thinking` 流家族 + 拥有代理推理注入以及对不受支持模型 / `auto` 的跳过逻辑。 - GitHub Copilot 使用 `catalog`、`auth`、`resolveDynamicModel` 和 - `capabilities`，以及 `prepareRuntimeAuth` 和 `fetchUsageSnapshot`，因为它需要 provider 自有的设备登录、模型回退行为、Claude transcript 特性、GitHub token -> Copilot token 交换，以及 provider 自有的用量端点。 + `capabilities`，以及 `prepareRuntimeAuth` 和 `fetchUsageSnapshot`，因为它 + 需要提供商自有的设备登录、模型回退行为、Claude transcript 特殊处理、 + GitHub token -> Copilot token 交换，以及提供商自有的用量端点。 - OpenAI Codex 使用 `catalog`、`resolveDynamicModel`、 - `normalizeResolvedModel`、`refreshOAuth` 和 `augmentModelCatalog`， - 以及 `prepareExtraParams`、`resolveUsageAuth` 和 `fetchUsageSnapshot`， - 因为它仍运行在 core 的 OpenAI 传输上，但拥有自己的 transport/base URL 标准化、OAuth refresh 回退策略、默认传输选择、synthetic Codex 目录条目和 ChatGPT 用量端点集成；它与直接 OpenAI 共享同一个 `openai-responses-defaults` 流家族。 + `normalizeResolvedModel`、`refreshOAuth` 和 `augmentModelCatalog`，以及 + `prepareExtraParams`、`resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它 + 仍运行在 core 的 OpenAI 传输上，但拥有自己的 transport/base URL + 规范化、OAuth 刷新回退策略、默认传输选择、 + synthetic Codex 目录条目，以及 ChatGPT 用量端点集成；它与直接 OpenAI 共享同一个 + `openai-responses-defaults` 流家族。 - Google AI Studio 和 Gemini CLI OAuth 使用 `resolveDynamicModel`、 `buildReplayPolicy`、`sanitizeReplayHistory`、 - `resolveReasoningOutputMode`、`wrapStreamFn` 和 `isModernModelRef`， - 因为 `google-gemini` replay 家族拥有 Gemini 3.1 前向兼容回退、原生 Gemini replay 验证、bootstrap replay 清理、带标签的 reasoning-output 模式和现代模型匹配，而 - `google-thinking` 流家族负责 Gemini thinking 负载标准化； + `resolveReasoningOutputMode`、`wrapStreamFn` 和 `isModernModelRef`，因为 + `google-gemini` replay 家族拥有 Gemini 3.1 前向兼容回退、 + 原生 Gemini replay 验证、bootstrap replay 清洗、带标签的 + reasoning-output 模式，以及 modern-model 匹配，而 + `google-thinking` 流家族拥有 Gemini thinking 负载规范化； Gemini CLI OAuth 还使用 `formatApiKey`、`resolveUsageAuth` 和 `fetchUsageSnapshot` 来处理 token 格式化、token 解析和配额端点接线。 -- Anthropic Vertex 通过 `anthropic-by-model` replay 家族使用 - `buildReplayPolicy`，以便把 Claude 专用 replay 清理限定在 Claude id 范围内，而不是所有 `anthropic-messages` 传输。 +- Anthropic Vertex 通过 + `anthropic-by-model` replay 家族使用 `buildReplayPolicy`，这样 Claude 特定的 replay 清理会保持仅作用于 Claude id，而不是每一个 `anthropic-messages` 传输。 - Amazon Bedrock 使用 `buildReplayPolicy`、`matchesContextOverflowError`、 - `classifyFailoverReason` 和 `resolveDefaultThinkingLevel`，因为它拥有针对 Bedrock 上 Anthropic 流量的 Bedrock 专用 throttle/not-ready/context-overflow 错误分类；它的 replay 策略仍与 Claude 专用的 `anthropic-by-model` guard 共享。 + `classifyFailoverReason` 和 `resolveDefaultThinkingLevel`，因为它拥有 + 面向 Anthropic-on-Bedrock 流量的 Bedrock 特定 throttle/not-ready/context-overflow 错误分类； + 它的 replay 策略仍共享同一个仅限 Claude 的 `anthropic-by-model` 防护。 - OpenRouter、Kilocode、Opencode 和 Opencode Go 通过 - `passthrough-gemini` replay 家族使用 `buildReplayPolicy`，因为它们通过 OpenAI 兼容传输代理 Gemini 模型，并且需要 Gemini thought-signature 清理，而不需要原生 Gemini replay 验证或 bootstrap 重写。 + `passthrough-gemini` replay 家族使用 `buildReplayPolicy`， + 因为它们通过 OpenAI 兼容传输代理 Gemini 模型，并且需要 Gemini + thought-signature 清洗，而不需要原生 Gemini replay 验证或 + bootstrap 重写。 - MiniMax 通过 - `hybrid-anthropic-openai` replay 家族使用 `buildReplayPolicy`，因为同一个 provider 同时拥有 Anthropic-message 和 OpenAI 兼容语义；它在 Anthropic 一侧保留 Claude 专用 thinking-block 丢弃逻辑，同时把 reasoning output mode 覆盖回原生模式，而 `minimax-fast-mode` 流家族则负责在共享流路径上进行 fast-mode 模型重写。 -- Moonshot 使用 `catalog` 和 `wrapStreamFn`，因为它仍使用共享的 - OpenAI 传输，但需要 provider 自有的 thinking 负载标准化；`moonshot-thinking` 流家族会把配置和 `/think` 状态映射到其原生二元 thinking 负载上。 + `hybrid-anthropic-openai` replay 家族使用 `buildReplayPolicy`，因为同一提供商同时拥有 + Anthropic-message 和 OpenAI 兼容语义；它会在 Anthropic 一侧保留仅限 Claude 的 + thinking-block 丢弃逻辑，同时将 reasoning + output 模式覆写回原生，而 `minimax-fast-mode` 流家族拥有共享流路径上的 + fast-mode 模型重写。 +- Moonshot 使用 `catalog` 和 `wrapStreamFn`，因为它 + 仍使用共享的 OpenAI 传输，但需要提供商自有的 thinking 负载规范化；`moonshot-thinking` 流家族会将配置加上 `/think` 状态映射到其原生二元 thinking 负载。 - Kilocode 使用 `catalog`、`capabilities`、`wrapStreamFn` 和 - `isCacheTtlEligible`，因为它需要 provider 自有的请求头、reasoning 负载标准化、Gemini transcript 提示和 Anthropic 缓存 TTL 控制；`kilocode-thinking` 流家族会把 Kilo thinking 注入保留在共享代理流路径上，同时跳过 `kilo/auto` 和其他不支持显式推理负载的代理 model id。 + `isCacheTtlEligible`，因为它需要提供商自有请求头、 + reasoning 负载规范化、Gemini transcript 提示，以及 Anthropic + cache-TTL 控制；`kilocode-thinking` 流家族将 Kilo thinking 注入保留在共享代理流路径中，同时跳过 `kilo/auto` 和其他不支持显式 reasoning 负载的代理 model id。 - Z.AI 使用 `resolveDynamicModel`、`prepareExtraParams`、`wrapStreamFn`、 `isCacheTtlEligible`、`isBinaryThinking`、`isModernModelRef`、 `resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它拥有 GLM-5 回退、 - `tool_stream` 默认值、二元 thinking UX、现代模型匹配，以及用量认证 + 配额抓取；`tool-stream-default-on` 流家族则把默认开启的 `tool_stream` wrapper 从各 provider 手写 glue 中抽离出来。 + `tool_stream` 默认值、二元 thinking UX、modern-model 匹配，以及 + 用量认证和配额抓取；`tool-stream-default-on` 流家族让默认开启的 `tool_stream` 包装器无需出现在每个提供商的手写 glue 里。 - xAI 使用 `normalizeResolvedModel`、`normalizeTransport`、 `contributeResolvedModelCompat`、`prepareExtraParams`、`wrapStreamFn`、 `resolveSyntheticAuth`、`resolveDynamicModel` 和 `isModernModelRef`， - 因为它拥有原生 xAI Responses 传输标准化、Grok fast-mode 别名重写、默认 `tool_stream`、strict-tool / reasoning-payload 清理、面向插件自有工具的回退认证复用、前向兼容的 Grok 模型解析，以及 provider 自有兼容补丁，例如 xAI 工具 schema 配置、受支持程度不足的 schema 关键字、原生 `web_search` 和 HTML 实体工具调用参数解码。 -- Mistral、OpenCode Zen 和 OpenCode Go 仅使用 `capabilities`，以便将 transcript/tooling 特性从 core 中分离出去。 -- 仅目录型内置 providers，例如 `byteplus`、`cloudflare-ai-gateway`、 + 因为它拥有原生 xAI Responses 传输规范化、Grok fast-mode + 别名重写、默认 `tool_stream`、strict-tool / reasoning-payload + 清理、自有工具的回退认证复用、前向兼容的 Grok + 模型解析，以及提供商自有兼容补丁，例如 xAI 工具 schema + 配置文件、不受支持的 schema 关键字、原生 `web_search` 和 HTML 实体化的 + 工具调用参数解码。 +- Mistral、OpenCode Zen 和 OpenCode Go 仅使用 `capabilities`，以便将 transcript/tooling 特殊处理保留在 core 之外。 +- 仅目录型的内置提供商，例如 `byteplus`、`cloudflare-ai-gateway`、 `huggingface`、`kimi-coding`、`nvidia`、`qianfan`、 - `synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine` 仅使用 `catalog`。 -- Qwen 为其文本 provider 使用 `catalog`，并为其多模态 surfaces 共享媒体理解和视频生成注册。 -- MiniMax 和 Xiaomi 使用 `catalog` 加上 usage hooks，因为尽管推理仍通过共享传输运行，但它们的 `/usage` 行为归插件所有。 + `synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine` 仅使用 + `catalog`。 +- Qwen 为其文本提供商使用 `catalog`，并为其多模态接口使用共享的媒体理解和视频生成注册。 +- MiniMax 和 Xiaomi 使用 `catalog` 加上用量 hooks，因为它们的 `/usage` + 行为属于插件自有，即使推理仍通过共享传输运行。 ## 运行时辅助工具 -插件可以通过 `api.runtime` 访问部分选定的 core 辅助工具。以 TTS 为例： +插件可以通过 `api.runtime` 访问选定的 core 辅助工具。对于 TTS： ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -717,14 +754,14 @@ const voices = await api.runtime.tts.listVoices({ 说明： -- `textToSpeech` 返回正常的 core TTS 输出负载，用于文件/语音消息 surface。 -- 使用 core `messages.tts` 配置和 provider 选择。 -- 返回 PCM 音频缓冲区 + 采样率。插件必须自行进行重采样/编码以适配 providers。 -- `listVoices` 对每个 provider 来说都是可选的。可将其用于 vendor 自有语音选择器或设置流程。 -- 语音列表可以包含更丰富的元数据，例如 locale、gender 和 personality 标签，以支持具有 provider 感知的选择器。 -- 目前 OpenAI 和 ElevenLabs 支持电话场景。Microsoft 不支持。 +- `textToSpeech` 返回普通 core TTS 输出负载，适用于文件/语音消息接口。 +- 使用 core 的 `messages.tts` 配置和提供商选择。 +- 返回 PCM 音频缓冲区 + 采样率。插件必须针对提供商自行重采样/编码。 +- `listVoices` 对每个提供商都是可选的。可将其用于厂商自有语音选择器或设置流程。 +- 语音列表可以包含更丰富的元数据，如 locale、gender 和 personality 标签，以便用于感知提供商的选择器。 +- OpenAI 和 ElevenLabs 目前支持电话场景。Microsoft 不支持。 -插件也可以通过 `api.registerSpeechProvider(...)` 注册语音 providers。 +插件也可以通过 `api.registerSpeechProvider(...)` 注册语音提供商。 ```ts api.registerSpeechProvider({ @@ -744,13 +781,12 @@ api.registerSpeechProvider({ 说明： -- 把 TTS 策略、回退和回复交付保留在 core。 -- 使用 speech providers 处理 vendor 自有的合成行为。 -- 遗留的 Microsoft `edge` 输入会被标准化为 `microsoft` provider id。 -- 推荐的归属模型是面向公司的：随着 OpenClaw 增加这些能力契约，一个 vendor 插件可以统一拥有文本、语音、图像以及未来媒体 providers。 +- 将 TTS 策略、回退和回复投递保留在 core 中。 +- 将厂商自有合成行为放在语音提供商中。 +- 旧版 Microsoft `edge` 输入会被规范化为 `microsoft` provider id。 +- 推荐的归属模型是面向公司的：随着 OpenClaw 增加这些能力契约，一个厂商插件可以同时拥有文本、语音、图像和未来媒体提供商。 -对于图像/音频/视频理解，插件注册的是一个类型化的 -media-understanding provider，而不是通用的键值包： +对于图像/音频/视频理解，插件应注册一个类型化的媒体理解提供商，而不是通用的键值袋： ```ts api.registerMediaUnderstandingProvider({ @@ -764,15 +800,15 @@ api.registerMediaUnderstandingProvider({ 说明： -- 把编排、回退、配置和渠道接线保留在 core。 -- 把 vendor 行为保留在 provider 插件中。 +- 将编排、回退、配置和渠道接线保留在 core 中。 +- 将厂商行为保留在提供商插件中。 - 增量扩展应保持类型化：新的可选方法、新的可选结果字段、新的可选能力。 -- 视频生成已经遵循相同模式： +- 视频生成已经采用同样模式： - core 拥有能力契约和运行时辅助工具 - - vendor 插件注册 `api.registerVideoGenerationProvider(...)` + - 厂商插件注册 `api.registerVideoGenerationProvider(...)` - 功能/渠道插件消费 `api.runtime.videoGeneration.*` -对于 media-understanding 运行时辅助工具，插件可以调用： +对于媒体理解运行时辅助工具，插件可以调用： ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -787,7 +823,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -对于音频转写，插件可以使用 media-understanding 运行时，也可以使用较旧的 STT 别名： +对于音频转录，插件可以使用媒体理解运行时，也可以使用较旧的 STT 别名： ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -800,10 +836,10 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ 说明： -- `api.runtime.mediaUnderstanding.*` 是图像/音频/视频理解的首选共享 surface。 -- 使用 core 的媒体理解音频配置（`tools.media.audio`）和 provider 回退顺序。 -- 当未产生转写输出时（例如输入被跳过/不受支持），返回 `{ text: undefined }`。 -- `api.runtime.stt.transcribeAudioFile(...)` 仍保留作为兼容别名。 +- `api.runtime.mediaUnderstanding.*` 是图像/音频/视频理解的首选共享接口。 +- 使用 core 的媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。 +- 当没有生成转录输出时（例如输入被跳过/不受支持），返回 `{ text: undefined }`。 +- `api.runtime.stt.transcribeAudioFile(...)` 仍保留为兼容别名。 插件还可以通过 `api.runtime.subagent` 启动后台子智能体运行： @@ -819,13 +855,13 @@ const result = await api.runtime.subagent.run({ 说明： -- `provider` 和 `model` 是每次运行的可选覆盖项，不是持久化的 session 变更。 -- OpenClaw 仅对受信调用方接受这些覆盖字段。 +- `provider` 和 `model` 是每次运行可选的覆写项，不会持久化更改会话。 +- OpenClaw 仅对受信任调用方接受这些覆写字段。 - 对于插件自有的回退运行，操作员必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式启用。 -- 使用 `plugins.entries..subagent.allowedModels` 将受信插件限制为特定的规范 `provider/model` 目标，或使用 `"*"` 显式允许任意目标。 -- 不受信插件的子智能体运行仍可工作，但覆盖请求会被拒绝，而不是静默回退。 +- 使用 `plugins.entries..subagent.allowedModels` 将受信任插件限制到特定规范 `provider/model` 目标，或使用 `"*"` 显式允许任意目标。 +- 不受信任的插件子智能体运行仍然可用，但覆写请求会被拒绝，而不是静默回退。 -对于 Web 搜索，插件可以消费共享运行时辅助工具，而不是直接接入智能体工具接线： +对于 Web 搜索，插件可以消费共享运行时辅助工具，而不是深入智能体工具接线： ```ts const providers = api.runtime.webSearch.listProviders({ @@ -841,14 +877,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -插件也可以通过 -`api.registerWebSearchProvider(...)` 注册 Web 搜索 providers。 +插件还可以通过 +`api.registerWebSearchProvider(...)` 注册 Web 搜索提供商。 说明： -- 把 provider 选择、凭证解析和共享请求语义保留在 core。 -- 使用 Web 搜索 providers 处理 vendor 专用搜索传输。 -- `api.runtime.webSearch.*` 是功能/渠道插件在需要搜索行为但不依赖智能体工具包装器时的首选共享 surface。 +- 将提供商选择、凭证解析和共享请求语义保留在 core 中。 +- 将厂商特定搜索传输放在 Web 搜索提供商中。 +- `api.runtime.webSearch.*` 是功能/渠道插件在不依赖智能体工具包装器的情况下实现搜索行为的首选共享接口。 ### `api.runtime.imageGeneration` @@ -863,12 +899,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`：使用已配置的图像生成 provider 链生成图像。 -- `listProviders(...)`：列出可用的图像生成 providers 及其能力。 +- `generate(...)`：使用已配置的图像生成提供商链生成图像。 +- `listProviders(...)`：列出可用的图像生成提供商及其能力。 ## Gateway 网关 HTTP 路由 -插件可以使用 `api.registerHttpRoute(...)` 暴露 HTTP 端点。 +插件可以通过 `api.registerHttpRoute(...)` 暴露 HTTP 端点。 ```ts api.registerHttpRoute({ @@ -886,7 +922,7 @@ api.registerHttpRoute({ 路由字段： - `path`：Gateway 网关 HTTP 服务器下的路由路径。 -- `auth`：必填。使用 `"gateway"` 以要求普通 Gateway 网关认证，或使用 `"plugin"` 以启用插件自主管理的认证/webhook 验证。 +- `auth`：必填。使用 `"gateway"` 表示需要常规 Gateway 网关认证，或使用 `"plugin"` 表示由插件管理认证/webhook 验证。 - `match`：可选。`"exact"`（默认）或 `"prefix"`。 - `replaceExisting`：可选。允许同一插件替换自己已有的路由注册。 - `handler`：当路由处理了请求时返回 `true`。 @@ -895,18 +931,18 @@ api.registerHttpRoute({ - `api.registerHttpHandler(...)` 已被移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。 - 插件路由必须显式声明 `auth`。 -- 精确的 `path + match` 冲突会被拒绝，除非设置了 `replaceExisting: true`，并且一个插件不能替换另一个插件的路由。 -- 不同 `auth` 级别的重叠路由会被拒绝。请仅在相同 auth 级别内建立 `exact`/`prefix` 的贯穿链。 -- `auth: "plugin"` 路由**不会**自动接收操作员运行时作用域。它们用于插件自主管理的 webhook/签名验证，而不是特权 Gateway 网关辅助工具调用。 -- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域内运行，但该作用域刻意保持保守： - - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` - - 可信、带身份的 HTTP 模式（例如 `trusted-proxy` 或私有入口上的 `gateway.auth.mode = "none"`）只有在显式提供该头时，才会尊重 `x-openclaw-scopes` - - 如果这些带身份的插件路由请求未提供 `x-openclaw-scopes`，运行时作用域会回退到 `operator.write` -- 实用规则：不要假设 gateway 认证插件路由天然就是管理员 surface。如果你的路由需要仅管理员可用的行为，请要求使用带身份的认证模式，并记录显式的 `x-openclaw-scopes` 头契约。 +- 完全相同的 `path + match` 冲突会被拒绝，除非设置了 `replaceExisting: true`，且一个插件不能替换另一个插件的路由。 +- 不同 `auth` 级别的重叠路由会被拒绝。请仅在相同认证级别内保留 `exact`/`prefix` 的贯穿链。 +- `auth: "plugin"` 路由**不会**自动接收操作员运行时作用域。它们用于插件管理的 webhook/签名验证，而不是特权 Gateway 网关辅助调用。 +- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域内运行，但该作用域有意保持保守： + - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由的运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` + - 受信任的、带身份的 HTTP 模式（例如 `trusted-proxy` 或私有入口上的 `gateway.auth.mode = "none"`）仅在明确存在该头时，才会尊重 `x-openclaw-scopes` + - 如果这些带身份的插件路由请求中不存在 `x-openclaw-scopes`，则运行时作用域会回退到 `operator.write` +- 实践规则：不要假设一个经过 gateway-auth 的插件路由天然就是管理员接口。如果你的路由需要仅管理员行为，请要求使用带身份的认证模式，并记录显式 `x-openclaw-scopes` 头契约。 ## 插件 SDK 导入路径 -在编写插件时，请使用 SDK 子路径，而不是单体式的 `openclaw/plugin-sdk` 导入： +编写插件时，请使用 SDK 子路径，而不是单体式 `openclaw/plugin-sdk` 导入： - `openclaw/plugin-sdk/plugin-entry` 用于插件注册原语。 - `openclaw/plugin-sdk/core` 用于通用共享的面向插件契约。 @@ -923,13 +959,15 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-lifecycle`、 `openclaw/plugin-sdk/channel-reply-pipeline`、 `openclaw/plugin-sdk/command-auth`、 - `openclaw/plugin-sdk/secret-input` 和 - `openclaw/plugin-sdk/webhook-ingress` 用于共享设置/认证/回复/webhook - 接线。`channel-inbound` 是 debounce、mention 匹配、入站 mention-policy 辅助工具、envelope 格式化和入站 envelope 上下文辅助工具的共享归属位置。 - `channel-setup` 是一个窄型可选安装设置 seam。 - `setup-runtime` 是 `setupEntry` / 延迟启动所使用的运行时安全设置 surface，包括导入安全的 setup patch 适配器。 - `setup-adapter-runtime` 是带环境感知的账户设置适配器 seam。 - `setup-tools` 是小型 CLI/archive/docs 辅助工具 seam（`formatCliCommand`、 + `openclaw/plugin-sdk/secret-input` 以及 + `openclaw/plugin-sdk/webhook-ingress`，用于共享设置/认证/回复/webhook + 接线。`channel-inbound` 是防抖、提及匹配、 + 入站提及策略辅助工具、信封格式化以及入站信封上下文辅助工具的共享归属位置。 + `channel-setup` 是一个更窄的可选安装设置接缝。 + `setup-runtime` 是 `setupEntry` / + 延迟启动使用的运行时安全设置接口，包括可安全导入的 setup patch 适配器。 + `setup-adapter-runtime` 是感知环境变量的账户设置适配器接缝。 + `setup-tools` 是一个小型 CLI/归档/文档辅助接口（`formatCliCommand`、 `detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、 `CONFIG_DIR`）。 - 领域子路径，例如 `openclaw/plugin-sdk/channel-config-helpers`、 @@ -948,149 +986,163 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/text-runtime`、 `openclaw/plugin-sdk/runtime-store` 和 `openclaw/plugin-sdk/directory-runtime`，用于共享运行时/配置辅助工具。 - `telegram-command-config` 是 Telegram 自定义命令标准化/验证的窄型公共 seam，即使内置 Telegram 契约 surface 暂时不可用，它也仍可使用。 - `text-runtime` 是共享的文本/Markdown/日志 seam，包括 assistant 可见文本剥离、Markdown 渲染/分块辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本工具。 -- 审批专用的渠道 seams 应优先采用插件上的单一 `approvalCapability` - 契约。然后 core 会通过这一种能力读取审批认证、交付、渲染和原生路由行为，而不是把审批行为混入无关的插件字段中。 -- `openclaw/plugin-sdk/channel-runtime` 已弃用，目前仅保留为老插件的兼容 shim。新代码应导入更窄的通用原语，仓库代码也不应新增对此 shim 的导入。 -- 内置扩展内部实现仍然是私有的。外部插件应只使用 - `openclaw/plugin-sdk/*` 子路径。OpenClaw core/test 代码可以使用插件 package 根目录下的仓库公共入口点，例如 `index.js`、`api.js`、 - `runtime-api.js`、`setup-entry.js`，以及范围很窄的文件，例如 - `login-qr-api.js`。绝不要从 core 或其他扩展中导入某个插件 package 的 `src/*`。 -- 仓库入口点拆分： + `telegram-command-config` 是 Telegram 自定义 + 命令规范化/验证的狭义公共接缝，即使内置 Telegram 契约接口暂时不可用，也会继续可用。 + `text-runtime` 是共享的文本/markdown/日志接缝，包括 + 对智能体可见文本的剥离、markdown 渲染/分块辅助工具、脱敏 + 辅助工具、directive-tag 辅助工具以及安全文本工具。 +- 审批特定的渠道接缝应优先使用插件上的一个 `approvalCapability` + 契约。这样 core 就可以通过这一个能力读取审批认证、投递、渲染和原生路由行为，而不需要把审批行为混入无关的插件字段中。 +- `openclaw/plugin-sdk/channel-runtime` 已弃用，仅作为旧插件的兼容 shim 保留。 + 新代码应导入更窄的通用原语，repo 代码也不应再新增对该 shim 的导入。 +- 内置扩展内部实现仍然是私有的。外部插件应只使用 `openclaw/plugin-sdk/*` 子路径。 + OpenClaw core/测试代码可以使用插件包根目录下 repo 的公共入口点，例如 `index.js`、`api.js`、 + `runtime-api.js`、`setup-entry.js`，以及更窄的文件，例如 + `login-qr-api.js`。不要从 core 或其他扩展中导入某个插件包的 `src/*`。 +- Repo 入口点拆分： `/api.js` 是辅助工具/类型 barrel， `/runtime-api.js` 是仅运行时 barrel， `/index.js` 是内置插件入口， - `/setup-entry.js` 是 setup 插件入口。 -- 当前内置 provider 示例： - - Anthropic 使用 `api.js` / `contract-api.js` 提供 Claude 流辅助工具，例如 `wrapAnthropicProviderStream`、beta-header 辅助工具和 `service_tier` + `/setup-entry.js` 是设置插件入口。 +- 当前内置提供商示例： + - Anthropic 使用 `api.js` / `contract-api.js` 提供 Claude 流辅助工具，例如 + `wrapAnthropicProviderStream`、beta-header 辅助工具，以及 `service_tier` 解析。 - - OpenAI 使用 `api.js` 提供 provider builder、默认模型辅助工具和实时 provider builder。 - - OpenRouter 使用 `api.js` 提供其 provider builder 以及 onboarding/config - 辅助工具，而 `register.runtime.js` 仍可为仓库内部使用重新导出通用 + - OpenAI 使用 `api.js` 提供 provider builder、默认模型辅助工具和 + 实时提供商 builder。 + - OpenRouter 使用 `api.js` 提供其 provider builder 以及新手引导/配置 + 辅助工具，而 `register.runtime.js` 仍可为 repo 本地使用重新导出通用的 `plugin-sdk/provider-stream` 辅助工具。 -- 外观加载的公共入口点优先使用当前活动的运行时配置快照；如果 OpenClaw 尚未提供运行时快照，则回退到磁盘上的已解析配置文件。 -- 通用共享原语仍然是首选公共 SDK 契约。当前仍存在一小组保留的、带内置渠道品牌的辅助工具兼容 seams。应将这些视为内置维护/兼容 seams，而不是新的第三方导入目标；新的跨渠道契约仍应落在通用 `plugin-sdk/*` 子路径，或插件本地 `api.js` / - `runtime-api.js` barrels 上。 +- 通过 facade 加载的公共入口点在存在活动运行时配置快照时，优先使用该快照； + 当 OpenClaw 尚未提供运行时快照时，则回退到磁盘上的已解析配置文件。 +- 通用共享原语仍然是首选的公共 SDK 契约。仍保留一小组 + 按渠道品牌命名的内置辅助兼容接缝。应将其视为内置维护/兼容接缝，而不是新的第三方导入目标；新的跨渠道契约仍应落在通用的 `plugin-sdk/*` 子路径或插件本地的 `api.js` / + `runtime-api.js` barrel 上。 兼容性说明： -- 新代码请避免使用根级 `openclaw/plugin-sdk` barrel。 -- 优先使用窄型稳定原语。较新的 setup/pairing/reply/ +- 新代码应避免使用根 `openclaw/plugin-sdk` barrel。 +- 优先使用狭义稳定原语。较新的 setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool 子路径，是新的内置和外部插件工作的预期契约。 - 目标解析/匹配应归于 `openclaw/plugin-sdk/channel-targets`。 - Message 动作关卡和 reaction message-id 辅助工具应归于 + allowlist/status/message-tool 子路径，是新的 + 内置和外部插件工作的预期契约。 + 目标解析/匹配应放在 `openclaw/plugin-sdk/channel-targets`。 + 消息动作 gate 和 reaction message-id 辅助工具应放在 `openclaw/plugin-sdk/channel-actions`。 -- 默认情况下，内置扩展专用辅助工具 barrel 并不稳定。如果某个辅助工具仅供某个内置扩展使用，应将其保留在该扩展的本地 `api.js` 或 - `runtime-api.js` seam 后面，而不是提升到 +- 内置扩展特定的辅助 barrel 默认不稳定。如果某个 + 辅助工具仅被某个内置扩展需要，应将其保留在该扩展本地的 + `api.js` 或 `runtime-api.js` 接缝之后，而不是提升到 `openclaw/plugin-sdk/`。 -- 新的共享辅助工具 seam 应该是通用的，而不是带渠道品牌的。共享目标解析应归于 `openclaw/plugin-sdk/channel-targets`；渠道专用内部实现则保留在归属插件的本地 `api.js` 或 `runtime-api.js` - seam 后面。 -- 像 `image-generation`、`media-understanding` 和 `speech` 这样的能力专用子路径之所以存在，是因为当前内置/原生插件正在使用它们。但这并不自动意味着其中导出的每个辅助工具都是长期冻结的外部契约。 +- 新的共享辅助接缝应是通用的，而不是按渠道命名的。共享目标 + 解析应归于 `openclaw/plugin-sdk/channel-targets`；渠道特定 + 内部实现则保留在所属插件本地的 `api.js` 或 `runtime-api.js` + 接缝之后。 +- 像 `image-generation`、 + `media-understanding` 和 `speech` 这样的能力特定子路径之所以存在，是因为当前内置/原生插件正在使用它们。它们的存在本身并不意味着每个导出的辅助工具都是长期冻结的对外契约。 -## Message 工具 schema +## Message 工具 schemas -插件应拥有渠道专用的 `describeMessageTool(...)` schema 贡献。请把 provider 专用字段保留在插件中，而不是放进共享 core。 +插件应拥有渠道特定的 `describeMessageTool(...)` schema +贡献。将提供商特定字段保留在插件中，而不是放在共享 core 中。 -对于共享且可移植的 schema 片段，请复用通过 +对于可共享的可移植 schema 片段，请复用通过 `openclaw/plugin-sdk/channel-actions` 导出的通用辅助工具： - `createMessageToolButtonsSchema()` 用于按钮网格风格的负载 - `createMessageToolCardSchema()` 用于结构化卡片负载 -如果某个 schema 形状只对一个 provider 有意义，应将其定义在该插件自己的源码中，而不是把它提升到共享 SDK 中。 +如果某种 schema 形状只对一个提供商有意义，请将其定义在该插件自己的源代码中，而不要把它提升到共享 SDK 中。 ## 渠道目标解析 -渠道插件应拥有渠道专用的目标语义。请保持共享出站宿主通用，并使用消息适配器 surface 处理 provider 规则： +渠道插件应拥有渠道特定的目标语义。请保持共享出站宿主的通用性，并使用消息适配器接口来承载提供商规则： -- `messaging.inferTargetChatType({ to })` 决定在目录查找之前，标准化目标应被视为 `direct`、`group` 还是 `channel` -- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉 core 某个输入是否应跳过目录搜索，直接进入类似 id 的解析 -- `messaging.targetResolver.resolveTarget(...)` 是插件回退路径，当 core 在标准化之后或目录未命中后需要最终的 provider 自有解析时调用 -- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后，负责 provider 专用的 session 路由构建 +- `messaging.inferTargetChatType({ to })` 会在目录查找前决定规范化目标应被视为 `direct`、`group` 还是 `channel`。 +- `messaging.targetResolver.looksLikeId(raw, normalized)` 会告诉 core 某个输入是否应跳过目录搜索，直接进入类 id 解析。 +- `messaging.targetResolver.resolveTarget(...)` 是 core 在规范化之后或目录未命中之后，所使用的插件回退逻辑，用于最终的提供商自有解析。 +- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后拥有提供商特定的会话路由构造逻辑。 推荐拆分方式： -- 用 `inferTargetChatType` 处理应在搜索 peers/groups 前做出的类别决策 -- 用 `looksLikeId` 处理“将此视为显式/原生目标 id”的检查 -- 用 `resolveTarget` 处理 provider 专用标准化回退，而不是进行广泛目录搜索 -- 将 provider 原生 id，如 chat id、thread id、JID、handle 和 room id，保存在 `target` 值或 provider 专用参数中，而不是通用 SDK 字段中 +- 使用 `inferTargetChatType` 处理应在搜索 peers/groups 之前发生的分类决策。 +- 使用 `looksLikeId` 处理“将其视为显式/原生目标 id”的判断。 +- 使用 `resolveTarget` 处理提供商特定的规范化回退，而不是广泛的目录搜索。 +- 将提供商原生 id，如 chat id、thread id、JID、handle 和 room id，保留在 `target` 值或提供商特定参数中，而不要放入通用 SDK 字段。 ## 配置支持的目录 -从配置派生目录项的插件，应把这部分逻辑保留在插件中，并复用 +对于从配置推导目录条目的插件，应将这部分逻辑保留在插件内部，并复用 `openclaw/plugin-sdk/directory-runtime` 中的共享辅助工具。 -当某个渠道需要配置支持的 peers/groups 时，应使用这种方式，例如： +适用场景包括渠道需要基于配置的 peers/groups，例如： -- 由 allowlist 驱动的私信 peers +- 由 allowlist 驱动的 DM peers - 已配置的渠道/群组映射 -- 账户作用域的静态目录回退 +- 按账户划分的静态目录回退 `directory-runtime` 中的共享辅助工具只处理通用操作： - 查询过滤 -- 限制数量应用 -- 去重/标准化辅助工具 +- 限制应用 +- 去重/规范化辅助工具 - 构建 `ChannelDirectoryEntry[]` -渠道专用的账户检查和 id 标准化应保留在插件实现中。 +渠道特定的账户检查和 id 规范化应保留在插件实现中。 -## Provider 目录 +## 提供商目录 -Provider 插件可以通过 +提供商插件可以通过 `registerProvider({ catalog: { run(...) { ... } } })` 定义用于推理的模型目录。 -`catalog.run(...)` 返回的形状与 OpenClaw 写入 `models.providers` 的内容相同： +`catalog.run(...)` 返回与 OpenClaw 写入 +`models.providers` 相同的结构： -- `{ provider }` 表示一个 provider 条目 -- `{ providers }` 表示多个 provider 条目 +- `{ provider }` 表示单个提供商条目 +- `{ providers }` 表示多个提供商条目 -当插件拥有 provider 专用 model id、base URL 默认值或受认证控制的模型元数据时，请使用 `catalog`。 +当插件拥有提供商特定 model id、base URL 默认值或按认证控制的模型元数据时，请使用 `catalog`。 -`catalog.order` 控制插件目录相对于 OpenClaw 内置隐式 providers 的合并时机： +`catalog.order` 控制插件目录相对 OpenClaw 内置隐式提供商的合并时机： -- `simple`：纯 API key 或环境变量驱动的 providers -- `profile`：存在 auth profiles 时出现的 providers -- `paired`：会合成多个相关 provider 条目的 providers -- `late`：最后一轮，在其他隐式 providers 之后 +- `simple`：纯 API key 或环境变量驱动的提供商 +- `profile`：当存在认证配置文件时出现的提供商 +- `paired`：合成多个相关提供商条目的提供商 +- `late`：最后一轮，在其他隐式提供商之后 -后面的 provider 会在键冲突时胜出，因此插件可以有意用相同 provider id 覆盖某个内置 provider 条目。 +后出现的提供商在键冲突时获胜，因此插件可以有意使用相同 provider id 覆盖内置提供商条目。 兼容性： -- `discovery` 仍可作为遗留别名使用 +- `discovery` 仍然可用，作为旧版别名 - 如果同时注册了 `catalog` 和 `discovery`，OpenClaw 会使用 `catalog` ## 只读渠道检查 -如果你的插件注册了一个渠道，请优先实现 -`plugin.config.inspectAccount(cfg, accountId)`，并同时实现 `resolveAccount(...)`。 +如果你的插件注册了一个渠道，建议在实现 +`resolveAccount(...)` 的同时，也实现 `plugin.config.inspectAccount(cfg, accountId)`。 原因： -- `resolveAccount(...)` 是运行时路径。它可以假设凭证已经完全具体化，并在缺失必要 secret 时快速失败。 +- `resolveAccount(...)` 是运行时路径。它可以假设凭证已完全具体化，并在缺少必需 secret 时快速失败。 - 像 `openclaw status`、`openclaw status --all`、 `openclaw channels status`、`openclaw channels resolve` 以及 doctor/config - 修复流程这样的只读命令路径，不应为了描述配置而不得不具体化运行时凭证。 + 修复流程这样的只读命令路径，不应为了描述配置而去具体化运行时凭证。 推荐的 `inspectAccount(...)` 行为： -- 仅返回描述性的账户状态。 +- 只返回描述性的账户状态。 - 保留 `enabled` 和 `configured`。 - 在相关时包含凭证来源/状态字段，例如： - `tokenSource`、`tokenStatus` - `botTokenSource`、`botTokenStatus` - `appTokenSource`、`appTokenStatus` - `signingSecretSource`、`signingSecretStatus` -- 为了报告只读可用性，你不需要返回原始 token 值。返回 - `tokenStatus: "available"`（以及对应的 source 字段）就足够用于状态类命令。 -- 当某个凭证通过 SecretRef 配置，但在当前命令路径中不可用时，请使用 `configured_unavailable`。 +- 你不需要为了报告只读可用性而返回原始 token 值。返回 `tokenStatus: "available"`（以及对应的 source 字段）就足够用于状态类命令。 +- 当凭证通过 SecretRef 配置，但在当前命令路径中不可用时，请使用 `configured_unavailable`。 -这样，只读命令就可以报告“已配置，但在此命令路径中不可用”，而不是崩溃或误报账户未配置。 +这样只读命令就能报告“已配置，但在当前命令路径中不可用”，而不是崩溃或错误地把账户报告为未配置。 -## Package packs +## 包集合 一个插件目录可以包含带有 `openclaw.extensions` 的 `package.json`： @@ -1104,43 +1156,49 @@ Provider 插件可以通过 } ``` -每个条目都会变成一个插件。如果 pack 列出了多个扩展，插件 id -将变为 `name/`。 +每个条目都会成为一个插件。如果包列出了多个扩展，则插件 id +会变成 `name/`。 -如果你的插件导入 npm 依赖，请在该目录中安装它们，以便 `node_modules` -可用（`npm install` / `pnpm install`）。 +如果你的插件导入了 npm 依赖，请在该目录中安装它们，以便 +`node_modules` 可用（`npm install` / `pnpm install`）。 -安全护栏：每个 `openclaw.extensions` 条目在符号链接解析之后，都必须保留在插件目录内部。任何逃逸出 package 目录的条目都会被拒绝。 +安全护栏：每个 `openclaw.extensions` 条目在解析 symlink 后，都必须保留在插件目录内部。逃逸包目录的条目会被拒绝。 -安全说明：`openclaw plugins install` 会使用 -`npm install --omit=dev --ignore-scripts` 安装插件依赖（无生命周期脚本，运行时也不安装开发依赖）。请保持插件依赖树为“纯 JS/TS”，并避免需要 `postinstall` 构建的包。 +安全说明：`openclaw plugins install` 会通过 +`npm install --omit=dev --ignore-scripts` 安装插件依赖（不运行生命周期脚本，运行时也不包含开发依赖）。请保持插件依赖树为“纯 JS/TS”，并避免依赖需要 `postinstall` 构建的包。 -可选：`openclaw.setupEntry` 可以指向一个轻量级、仅 setup 的模块。 -当 OpenClaw 需要为一个已禁用的渠道插件提供 setup surface，或者当某个渠道插件已启用但仍未配置时，它会加载 `setupEntry` 而不是完整插件入口。这样在主插件入口还会接线 tools、hooks 或其他仅运行时代码时，可以让启动和 setup 更轻量。 +可选：`openclaw.setupEntry` 可以指向一个轻量级的仅设置模块。 +当 OpenClaw 需要为一个已禁用的渠道插件提供设置接口，或 +当渠道插件已启用但尚未配置时，它会加载 `setupEntry`，而不是完整插件入口。这样在你的主插件入口还会接线工具、hooks 或其他仅运行时代码时，启动和设置会更轻量。 可选：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -可以让某个渠道插件在 Gateway 网关监听前的启动阶段，即使该渠道已配置，也改走同样的 `setupEntry` 路径。 +可以让一个渠道插件在 Gateway 网关预监听启动阶段，即使该渠道已经配置完成，也改用同一个 `setupEntry` 路径。 -仅当 `setupEntry` 完全覆盖了在 Gateway 网关开始监听前必须存在的启动 surface 时，才使用此选项。实际而言，这意味着 setup 入口必须注册启动依赖的每个渠道自有能力，例如： +仅当 `setupEntry` 完整覆盖了启动前必须存在的接口时，才应使用它。 +实际中，这意味着 setup entry +必须注册启动所依赖的每一项渠道自有能力，例如： - 渠道注册本身 -- 任何必须在 Gateway 网关开始监听前就可用的 HTTP 路由 -- 任何在同一窗口内必须存在的 gateway 方法、工具或服务 +- 任何必须在 Gateway 网关开始监听前可用的 HTTP 路由 +- 任何在同一窗口中必须存在的 gateway 方法、工具或服务 -如果完整入口仍拥有任何必需的启动能力，就不要启用这个标志。请保持默认行为，让 OpenClaw 在启动期间加载完整入口。 +如果你的完整入口仍拥有任何必需的启动能力，请不要启用该标志。应保持插件使用默认行为，并让 OpenClaw 在启动期间加载完整入口。 -内置渠道也可以发布仅 setup 用的契约 surface 辅助工具，以便 core 在完整渠道运行时加载前进行查询。当前 setup 提升 surface 为： +内置渠道也可以发布仅设置用的契约接口辅助工具，以便 core 在完整渠道运行时加载前进行查询。当前的 setup promotion 接口如下： - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -当 core 需要在不加载完整插件入口的情况下，把遗留的单账户渠道配置提升到 `channels..accounts.*` 时，就会使用这些 surface。Matrix 是当前的内置示例：当已存在命名账户时，它只会把 auth/bootstrap 键移动到某个已命名提升账户中，并且它可以保留一个已配置的、非规范默认账户键，而不是总是创建 `accounts.default`。 +当 core 需要在不加载完整插件入口的情况下，将旧版单账户渠道配置提升到 `channels..accounts.*` 时，就会使用这个接口。 +Matrix 是当前的内置示例：当已存在命名账户时，它只会把认证/bootstrap 键移动到一个命名的提升账户中，并且可以保留已配置的非规范默认账户键，而不是总是创建 +`accounts.default`。 -这些 setup patch 适配器可以让内置契约 surface 设备发现保持惰性。导入时间保持轻量；提升 surface 只会在首次使用时加载，而不会在模块导入时重新进入内置渠道启动流程。 +这些 setup patch 适配器让内置契约接口发现保持惰性。导入时保持轻量；只有首次使用时才会加载提升接口，而不会在模块导入时重新进入内置渠道启动逻辑。 -当这些启动 surfaces 包含 gateway RPC 方法时，请保持它们位于插件专用前缀下。Core 管理员命名空间（`config.*`、 -`exec.approvals.*`、`wizard.*`、`update.*`）仍然保留，并且始终解析为 `operator.admin`，即使某个插件请求更窄的作用域。 +当这些启动接口包含 Gateway 网关 RPC 方法时，应将它们保留在 +插件专用前缀下。Core 管理员命名空间（`config.*`、 +`exec.approvals.*`、`wizard.*`、`update.*`）仍然是保留的，并且始终会解析到 `operator.admin`，即使某个插件请求更窄的作用域。 示例： @@ -1159,7 +1217,7 @@ Provider 插件可以通过 ### 渠道目录元数据 -渠道插件可以通过 `openclaw.channel` 声明 setup/设备发现元数据，并通过 `openclaw.install` 声明安装提示。这样可以让 core 目录保持无数据化。 +渠道插件可以通过 `openclaw.channel` 公布设置/发现元数据，并通过 `openclaw.install` 提供安装提示。这样可使 core 目录保持无数据状态。 示例： @@ -1187,47 +1245,56 @@ Provider 插件可以通过 } ``` -除最小示例外，其他有用的 `openclaw.channel` 字段还包括： +除最小示例外，有用的 `openclaw.channel` 字段还包括： -- `detailLabel`：用于更丰富目录/状态 surface 的次级标签 +- `detailLabel`：用于更丰富目录/状态接口的次级标签 - `docsLabel`：覆盖文档链接文本 -- `preferOver`：该目录条目应优先于哪些低优先级插件/渠道 id -- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择 surface 文案控制 -- `markdownCapable`：将该渠道标记为支持 Markdown，以供出站格式决策使用 -- `exposure.configured`：设为 `false` 时，在已配置渠道列表 surface 中隐藏该渠道 -- `exposure.setup`：设为 `false` 时，在交互式 setup/configure 选择器中隐藏该渠道 -- `exposure.docs`：在文档导航 surface 中将该渠道标记为内部/私有 -- `showConfigured` / `showInSetup`：出于兼容性仍接受的遗留别名；优先使用 `exposure` -- `quickstartAllowFrom`：将该渠道加入标准快速开始 `allowFrom` 流程 -- `forceAccountBinding`：即使只存在一个账户，也要求显式账户绑定 -- `preferSessionLookupForAnnounceTarget`：在解析 announce 目标时优先使用 session 查找 +- `preferOver`：该目录条目应优先于的较低优先级插件/渠道 id +- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：控制选择界面的文案 +- `markdownCapable`：将渠道标记为支持 markdown，以便做出站格式决策 +- `exposure.configured`：设为 `false` 时，从已配置渠道列表界面中隐藏该渠道 +- `exposure.setup`：设为 `false` 时，从交互式设置/配置选择器中隐藏该渠道 +- `exposure.docs`：将渠道标记为内部/私有，以便文档导航界面处理 +- `showConfigured` / `showInSetup`：旧版别名，仍为兼容性接受；请优先使用 `exposure` +- `quickstartAllowFrom`：让渠道接入标准快速开始 `allowFrom` 流程 +- `forceAccountBinding`：即使仅存在一个账户，也要求显式账户绑定 +- `preferSessionLookupForAnnounceTarget`：在解析 announce 目标时优先使用会话查找 OpenClaw 还可以合并**外部渠道目录**（例如 MPM -注册表导出）。将 JSON 文件放在以下任一路径： +注册表导出）。将 JSON 文件放到以下任意位置： - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（以逗号/分号/`PATH` 分隔）。每个文件都应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的遗留别名。 +或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（以逗号/分号/`PATH` 分隔）。每个文件都应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧版别名。 ## 上下文引擎插件 -上下文引擎插件拥有 session 上下文编排，包括摄取、组装和压缩。请在你的插件中使用 -`api.registerContextEngine(id, factory)` 进行注册，然后通过 +上下文引擎插件拥有会话上下文的编排逻辑，包括摄取、组装和压缩。请在你的插件中通过 +`api.registerContextEngine(id, factory)` 注册它们，然后使用 `plugins.slots.contextEngine` 选择活动引擎。 -当你的插件需要替换或扩展默认上下文流水线，而不仅仅是添加 memory 搜索或 hooks 时，请使用这种方式。 +当你的插件需要替换或扩展默认上下文流水线，而不只是添加 memory search 或 hooks 时，请使用它。 ```ts +import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; + export default function (api) { api.registerContextEngine("lossless-claw", () => ({ info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true }, async ingest() { return { ingested: true }; }, - async assemble({ messages }) { - return { messages, estimatedTokens: 0 }; + async assemble({ messages, availableTools, citationsMode }) { + return { + messages, + estimatedTokens: 0, + systemPromptAddition: buildMemorySystemPromptAddition({ + availableTools: availableTools ?? new Set(), + citationsMode, + }), + }; }, async compact() { return { ok: true, compacted: false }; @@ -1236,10 +1303,14 @@ export default function (api) { } ``` -如果你的引擎**不**拥有压缩算法，请保持 `compact()` 已实现，并显式委托： +如果你的引擎**不**拥有压缩算法，请保持 `compact()` +已实现，并显式委托它： ```ts -import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core"; +import { + buildMemorySystemPromptAddition, + delegateCompactionToRuntime, +} from "openclaw/plugin-sdk/core"; export default function (api) { api.registerContextEngine("my-memory-engine", () => ({ @@ -1251,8 +1322,15 @@ export default function (api) { async ingest() { return { ingested: true }; }, - async assemble({ messages }) { - return { messages, estimatedTokens: 0 }; + async assemble({ messages, availableTools, citationsMode }) { + return { + messages, + estimatedTokens: 0, + systemPromptAddition: buildMemorySystemPromptAddition({ + availableTools: availableTools ?? new Set(), + citationsMode, + }), + }; }, async compact(params) { return await delegateCompactionToRuntime(params); @@ -1261,41 +1339,41 @@ export default function (api) { } ``` -## 添加一个新能力 +## 添加新能力 -当插件需要当前 API 无法容纳的行为时，不要通过私有内部接入绕过插件系统。请添加缺失的能力。 +当插件需要当前 API 无法容纳的行为时，不要通过私有内部直连绕过插件系统。应添加缺失的能力。 推荐顺序： 1. 定义 core 契约 - 确定哪些共享行为应由 core 拥有：策略、回退、配置合并、 - 生命周期、面向渠道的语义，以及运行时辅助工具形态。 -2. 添加类型化插件注册/运行时 surface - 以最小且有用的类型化能力 surface 扩展 `OpenClawPluginApi` 和/或 - `api.runtime`。 -3. 接线 core + 渠道/功能消费者 - 渠道和功能插件应通过 core 消费这个新能力，而不是直接导入某个 vendor 实现。 -4. 注册 vendor 实现 - 然后让 vendor 插件针对这个能力注册它们的后端。 + 明确 core 应拥有哪些共享行为：策略、回退、配置合并、 + 生命周期、面向渠道的语义以及运行时辅助工具形态。 +2. 添加类型化的插件注册/运行时接口 + 用最小且有用的类型化能力接口扩展 `OpenClawPluginApi` 和/或 `api.runtime`。 +3. 连接 core + 渠道/功能消费者 + 渠道和功能插件应通过 core 消费新能力， + 而不是直接导入某个厂商实现。 +4. 注册厂商实现 + 然后由厂商插件将其后端注册到该能力之下。 5. 添加契约覆盖 - 增加测试，使归属和注册形状在长期内保持显式。 + 添加测试，让归属关系和注册结构长期保持明确。 -这正是 OpenClaw 能在保持鲜明主张的同时，不会被某一家 provider 的世界观所硬编码绑定的原因。请参见 [能力扩展手册](/zh-CN/plugins/architecture) 获取具体的文件清单和完整示例。 +这就是 OpenClaw 保持有主见、却不被某个提供商世界观硬编码绑死的方式。具体文件清单和完整示例请参见 [能力扩展手册](/zh-CN/plugins/architecture)。 ### 能力清单 -当你添加一个新能力时，通常应当一并修改以下 surfaces： +当你添加一个新能力时，实现通常应同时触及以下接口： - `src//types.ts` 中的 core 契约类型 - `src//runtime.ts` 中的 core runner/运行时辅助工具 -- `src/plugins/types.ts` 中的插件 API 注册 surface +- `src/plugins/types.ts` 中的插件 API 注册接口 - `src/plugins/registry.ts` 中的插件注册表接线 -- 当功能/渠道插件需要消费时，`src/plugins/runtime/*` 中的插件运行时暴露 +- 当功能/渠道插件需要消费它时，在 `src/plugins/runtime/*` 中暴露插件运行时 - `src/test-utils/plugin-registration.ts` 中的捕获/测试辅助工具 - `src/plugins/contracts/registry.ts` 中的归属/契约断言 -- `docs/` 中的操作员/插件文档 +- `docs/` 中面向操作员/插件的文档 -如果这些 surface 中有某个缺失，通常意味着该能力尚未完成完整集成。 +如果这些接口中缺失某一项，通常意味着该能力尚未完成整体集成。 ### 能力模板 @@ -1334,6 +1412,6 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); 这样规则就很简单： - core 拥有能力契约 + 编排 -- vendor 插件拥有 vendor 实现 +- 厂商插件拥有厂商实现 - 功能/渠道插件消费运行时辅助工具 -- 契约测试让归属保持显式 +- 契约测试让归属关系保持明确 diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index a443894c4..ac3e2e3cd 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -1,16 +1,16 @@ --- read_when: - - 你需要知道应从哪个 SDK 子路径导入 + - 你需要知道应该从哪个 SDK 子路径导入 - 你想查看 OpenClawPluginApi 上所有注册方法的参考 - 你正在查找某个特定的 SDK 导出 sidebarTitle: SDK Overview summary: 导入映射、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-04-07T07:38:26Z" + generated_at: "2026-04-07T08:02:18Z" model: gpt-5.4 provider: openai - source_hash: 9f05178454058038cd69a58bc8392e2574a48a61fbaef9b7db9eba2ffa9f1374 + source_hash: 6ba11d1708a117f3872a09fd0bebb0481d36b89b473aec861192e8c2745ef727 source_path: plugins/sdk-overview.md workflow: 15 --- @@ -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,20 +62,20 @@ 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/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-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/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | 多账户 config/action-gate 辅助函数、默认账户回退辅助函数 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 | | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 | | `plugin-sdk/account-helpers` | 狭义的账户列表/账户操作辅助函数 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助函数，并带有内置契约回退 | + | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/验证辅助函数，带内置契约回退 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助函数 | @@ -85,24 +85,24 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/outbound-runtime` | 出站身份/发送委托辅助函数 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 | | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 | - | `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助函数 | + | `plugin-sdk/conversation-runtime` | 对话/线程绑定、配对和已配置绑定辅助函数 | | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 | | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 | | `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助函数 | - | `plugin-sdk/channel-config-primitives` | 狭义渠道配置 schema 基元 | + | `plugin-sdk/channel-config-primitives` | 狭义渠道配置 schema 原语 | | `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/interactive-runtime` | 交互式回复负载规范化/缩减辅助函数 | - | `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助函数以及 envelope 辅助函数 | + | `plugin-sdk/interactive-runtime` | 交互式回复负载规范化/归约辅助函数 | + | `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` | 狭义 secret 契约辅助函数，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` 以及 secret 目标类型 | @@ -112,22 +112,22 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助函数 | | `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容自托管提供商的设置辅助函数 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 为提供商插件提供的运行时 API 密钥解析辅助函数 | + | `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API 密钥解析辅助函数 | | `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/配置文件写入辅助函数，例如 `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | - | `plugin-sdk/provider-auth-login` | 为提供商插件提供的共享交互式登录辅助函数 | + | `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 构建器、提供商端点辅助函数，以及模型 ID 规范化辅助函数，例如 `normalizeNativeXaiModelId` | - | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 | + | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助函数 | | `plugin-sdk/provider-web-fetch-contract` | 狭义 web-fetch 配置/选择契约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册/缓存辅助函数 | - | `plugin-sdk/provider-web-search-contract` | 狭义 web-search 配置/凭证契约辅助函数，例如 `enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 和作用域凭证 setter/getter | + | `plugin-sdk/provider-web-search-contract` | 狭义 web-search 配置/凭证契约辅助函数，例如 `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-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-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 辅助函数 | @@ -136,18 +136,18 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 | - | `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作认证辅助函数 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤辅助函数 | - | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天 action-auth 辅助函数 | + | `plugin-sdk/approval-client-runtime` | 原生执行审批配置文件/过滤器辅助函数 | + | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/传递适配器 | | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 | - | `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助函数 | + | `plugin-sdk/approval-reply-runtime` | exec/plugin 审批回复负载辅助函数 | | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 | | `plugin-sdk/command-detection` | 共享命令检测辅助函数 | - | `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助函数 | + | `plugin-sdk/command-surface` | 命令体规范化和命令 surface 辅助函数 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 用于渠道/插件 secret 表面的狭义 secret 契约收集辅助函数 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道/插件 secret surface 的狭义 secret 契约收集辅助函数 | | `plugin-sdk/secret-ref-runtime` | 狭义 `coerceSecretRef` 和用于 secret 契约/配置解析的 SecretRef 类型辅助函数 | - | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助函数 | + | `plugin-sdk/security-runtime` | 共享信任、私信 gating、外部内容和 secret 收集辅助函数 | | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 | | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助函数 | | `plugin-sdk/secret-input` | secret 输入解析辅助函数 | @@ -158,57 +158,57 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助函数 | + | `plugin-sdk/runtime` | 广义运行时/日志/备份/插件安装辅助函数 | | `plugin-sdk/runtime-env` | 狭义运行时环境、logger、超时、重试和退避辅助函数 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | | `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/交互辅助函数 | - | `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 管道辅助函数 | - | `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程 exec 辅助函数 | + | `plugin-sdk/hook-runtime` | 共享 webhook/internal hook pipeline 辅助函数 | + | `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程执行辅助函数 | | `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/插件审批辅助函数、审批能力构建器、认证/配置文件辅助函数、原生路由/运行时辅助函数 | - | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助函数、分块、分发、heartbeat、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 狭义回复分发/完成辅助函数 | - | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化和重复/冲突检查，即使内置 Telegram 契约 surface 不可用时也适用 | + | `plugin-sdk/approval-runtime` | exec/plugin 审批辅助函数、审批能力构建器、认证/配置文件辅助函数、原生路由/运行时辅助函数 | + | `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/session-store-runtime` | 会话存储路径 + updated-at 辅助函数 | | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助函数 | - | `plugin-sdk/routing` | 路由/会话键/账户绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | + | `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/request-url` | 从 fetch/request-like 输入中提取字符串 URL | + | `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化 stdout/stderr 结果 | | `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 | - | `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 | + | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | | `plugin-sdk/temp-path` | 共享临时下载路径辅助函数 | | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助函数 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助函数 | | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 | | `plugin-sdk/file-lock` | 可重入文件锁辅助函数 | - | `plugin-sdk/persistent-dedupe` | 基于磁盘的去重缓存辅助函数 | - | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助函数 | - | `plugin-sdk/agent-config-primitives` | 狭义智能体运行时配置 schema 基元 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 | + | `plugin-sdk/acp-runtime` | ACP 运行时/会话和 reply-dispatch 辅助函数 | + | `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/extension-shared` | 共享被动渠道、状态和 ambient proxy 辅助原语 | | `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.AI 端点检测辅助函数 | - | `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助函数 | + | `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/fetch-runtime` | 包装后的 fetch、代理和 pinned lookup 辅助函数 | | `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` | @@ -216,12 +216,12 @@ 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/日志辅助函数，例如剥离对助手可见的文本、Markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 | + | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助函数，以及媒体负载构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障切换辅助函数、候选项选择和缺失模型消息 | + | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助函数导出 | + | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助函数，例如仅对助手可见文本剥离、Markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 | | `plugin-sdk/text-chunking` | 出站文本分块辅助函数 | - | `plugin-sdk/speech` | 语音提供商类型以及面向提供商的 directive、注册表和校验辅助函数 | + | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和验证辅助函数 | | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助函数 | | `plugin-sdk/realtime-transcription` | 实时转写提供商类型和注册表辅助函数 | | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 | @@ -231,20 +231,20 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `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-targets` | webhook 目标注册表和 route-install 辅助函数 | | `plugin-sdk/webhook-path` | webhook 路径规范化辅助函数 | | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助函数 | | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` | + | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助表面，用于 manager/config/file/CLI 辅助函数 | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助 surface，用于 manager/config/file/CLI 辅助函数 | | `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时门面 | | `plugin-sdk/memory-core-host-engine-foundation` | Memory 主机基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机 embedding 引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机嵌入引擎导出 | | `plugin-sdk/memory-core-host-engine-qmd` | Memory 主机 QMD 引擎导出 | | `plugin-sdk/memory-core-host-engine-storage` | Memory 主机存储引擎导出 | | `plugin-sdk/memory-core-host-multimodal` | Memory 主机多模态辅助函数 | @@ -255,78 +255,78 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时辅助函数 | | `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时辅助函数 | | `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件/运行时辅助函数 | - | `plugin-sdk/memory-host-core` | Memory 主机核心运行时辅助函数的供应商中立别名 | - | `plugin-sdk/memory-host-events` | Memory 主机事件日志辅助函数的供应商中立别名 | - | `plugin-sdk/memory-host-files` | Memory 主机文件/运行时辅助函数的供应商中立别名 | - | `plugin-sdk/memory-host-markdown` | 用于 memory 相邻插件的共享受管 Markdown 辅助函数 | - | `plugin-sdk/memory-host-search` | 用于搜索管理器访问的活动 Memory 运行时门面 | - | `plugin-sdk/memory-host-status` | Memory 主机状态辅助函数的供应商中立别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助表面 | + | `plugin-sdk/memory-host-core` | 面向供应商中立的 Memory 主机核心运行时辅助函数别名 | + | `plugin-sdk/memory-host-events` | 面向供应商中立的 Memory 主机事件日志辅助函数别名 | + | `plugin-sdk/memory-host-files` | 面向供应商中立的 Memory 主机文件/运行时辅助函数别名 | + | `plugin-sdk/memory-host-markdown` | 面向与 Memory 相邻插件的共享托管 Markdown 辅助函数 | + | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时门面 | + | `plugin-sdk/memory-host-status` | 面向供应商中立的 Memory 主机状态辅助函数别名 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助 surface | - | 系列 | 当前子路径 | 预期用途 | + | 类别 | 当前子路径 | 预期用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` | 内置 Browser 插件支持辅助函数（`browser-support` 仍是兼容性 barrel） | - | Matrix | `plugin-sdk/matrix`、`plugin-sdk/matrix-helper`、`plugin-sdk/matrix-runtime-heavy`、`plugin-sdk/matrix-runtime-shared`、`plugin-sdk/matrix-runtime-surface`、`plugin-sdk/matrix-surface`、`plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时表面 | - | Line | `plugin-sdk/line`、`plugin-sdk/line-core`、`plugin-sdk/line-runtime`、`plugin-sdk/line-surface` | 内置 LINE 辅助/运行时表面 | - | IRC | `plugin-sdk/irc`、`plugin-sdk/irc-surface` | 内置 IRC 辅助表面 | - | 特定于渠道的辅助函数 | `plugin-sdk/googlechat`、`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles`、`plugin-sdk/bluebubbles-policy`、`plugin-sdk/mattermost`、`plugin-sdk/mattermost-policy`、`plugin-sdk/feishu-conversation`、`plugin-sdk/msteams`、`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、`plugin-sdk/twitch` | 内置渠道兼容性/辅助接口 | - | 认证/插件特定辅助函数 | `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、`plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`、`plugin-sdk/voice-call` | 内置功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助函数（`browser-support` 仍为兼容性 barrel） | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时 surface | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时 surface | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助 surface | + | 特定渠道辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助层 | + | 认证/插件特定辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助层；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, 和 `resolveCopilotApiToken` | ## 注册 API -`register(api)` 回调会接收一个带有这些方法的 `OpenClawPluginApi` 对象： +`register(api)` 回调接收一个 `OpenClawPluginApi` 对象，包含以下方法： ### 能力注册 -| 方法 | 它注册的内容 | +| 方法 | 注册内容 | | ------------------------------------------------ | -------------------------------- | -| `api.registerProvider(...)` | 文本推理（LLM） | -| `api.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 端点 | -| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | -| `api.registerCli(registrar, opts?)` | CLI 子命令 | -| `api.registerService(service)` | 后台服务 | -| `api.registerInteractiveHandler(registration)` | 交互式处理器 | -| `api.registerMemoryPromptSupplement(builder)` | 附加式 memory 相邻提示词部分 | -| `api.registerMemoryCorpusSupplement(adapter)` | 附加式 memory 搜索/读取语料 | +| `api.registerHook(events, handler, opts?)` | 事件 hook | +| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | +| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | +| `api.registerCli(registrar, opts?)` | CLI 子命令 | +| `api.registerService(service)` | 后台服务 | +| `api.registerInteractiveHandler(registration)` | 交互式处理器 | +| `api.registerMemoryPromptSupplement(builder)` | 增量式 Memory 相邻提示词区段 | +| `api.registerMemoryCorpusSupplement(adapter)` | 增量式 Memory 搜索/读取语料 | -保留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使某个插件尝试为其分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件特定前缀。 +保留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件拥有的方法，优先使用插件特定前缀。 ### CLI 注册元数据 `api.registerCli(registrar, opts?)` 接受两类顶层元数据： -- `commands`：由 registrar 拥有的显式命令根 +- `commands`：由注册器拥有的显式命令根 - `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析时命令描述符 -如果你希望插件命令在普通根 CLI 路径中保持惰性加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。 +如果你希望某个插件命令在常规根 CLI 路径中保持惰性加载，请提供 `descriptors`，覆盖该注册器暴露的每一个顶层命令根。 ```typescript api.registerCli( @@ -346,69 +346,72 @@ api.registerCli( ); ``` -仅在你不需要惰性根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但不会为解析时惰性加载安装基于 descriptor 的占位符。 +只有在你不需要惰性根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍然受支持，但它不会安装基于描述符的占位符来实现解析时惰性加载。 ### CLI 后端注册 -`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。 +`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端的默认配置，例如 `codex-cli`。 - 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。 - 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的结构。 -- 用户配置仍然优先。OpenClaw 会在运行 CLI 前，将 `agents.defaults.cliBackends.` 合并到插件默认值之上。 -- 当某个后端在合并后需要兼容性重写时，请使用 `normalizeConfig`（例如规范化旧版 flag 结构）。 +- 用户配置仍然优先生效。OpenClaw 会在运行 CLI 前，将 `agents.defaults.cliBackends.` 合并到插件默认值之上。 +- 当后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧版标志结构）。 ### 独占槽位 -| 方法 | 它注册的内容 | +| 方法 | 注册内容 | | ------------------------------------------ | ------------------------------------- | -| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个活动） | -| `api.registerMemoryPromptSection(builder)` | Memory 提示词部分构建器 | -| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 | -| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 | +| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只激活一个） | +| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 | +| `api.registerMemoryPromptSection(builder)` | Memory 提示词区段构建器 | +| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 | +| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 | -### Memory embedding 适配器 +### Memory 嵌入适配器 -| 方法 | 它注册的内容 | +| 方法 | 注册内容 | | ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory embedding 适配器 | +| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory 嵌入适配器 | -- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是 Memory 插件独占的。 -- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个 embedding 适配器 ID（例如 `openai`、`gemini` 或自定义插件定义的 ID）。 -- 用户配置（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会根据这些已注册的适配器 ID 进行解析。 +- `registerMemoryCapability` 是首选的独占 Memory 插件 API。 +- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 消费导出的 Memory 制品，而不必深入某个特定 Memory 插件的私有布局。 +- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 Memory 插件 API。 +- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个嵌入适配器 id（例如 `openai`、`gemini` 或自定义的插件定义 id）。 +- 用户配置，例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`，会基于这些已注册的适配器 id 进行解析。 -### 事件和生命周期 +### 事件与生命周期 -| 方法 | 它的作用 | +| 方法 | 作用 | | -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook | -| `api.onConversationBindingResolved(handler)` | 会话绑定回调 | +| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook | +| `api.onConversationBindingResolved(handler)` | 对话绑定回调 | ### Hook 决策语义 -- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦有任意处理器设置它，就会跳过更低优先级的处理器。 -- `before_tool_call`：返回 `{ block: false }` 会被视为没有决策（等同于省略 `block`），而不是覆盖。 -- `before_install`：返回 `{ block: true }` 是终止性的。一旦有任意处理器设置它，就会跳过更低优先级的处理器。 -- `before_install`：返回 `{ block: false }` 会被视为没有决策（等同于省略 `block`），而不是覆盖。 -- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦有任意处理器声明已分发，就会跳过更低优先级的处理器以及默认模型分发路径。 -- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦有任意处理器设置它，就会跳过更低优先级的处理器。 -- `message_sending`：返回 `{ cancel: false }` 会被视为没有决策（等同于省略 `cancel`），而不是覆盖。 +- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。 +- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 +- `before_install`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。 +- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 +- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任意处理器声明已分发，就会跳过更低优先级的处理器以及默认模型分发路径。 +- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。 +- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。 ### API 对象字段 -| 字段 | 类型 | 描述 | +| 字段 | 类型 | 说明 | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | 插件 ID | -| `api.name` | `string` | 显示名称 | -| `api.version` | `string?` | 插件版本（可选） | -| `api.description` | `string?` | 插件描述（可选） | -| `api.source` | `string` | 插件源路径 | -| `api.rootDir` | `string?` | 插件根目录（可选） | -| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动内存运行时快照） | -| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件专用配置 | -| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是轻量级的完整入口点前启动/设置窗口 | -| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | +| `api.id` | `string` | 插件 id | +| `api.name` | `string` | 显示名称 | +| `api.version` | `string?` | 插件版本（可选） | +| `api.description` | `string?` | 插件描述（可选） | +| `api.source` | `string` | 插件源路径 | +| `api.rootDir` | `string?` | 插件根目录（可选） | +| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动内存运行时快照） | +| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件特定配置 | +| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口之前的轻量级启动/设置窗口 | +| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | ## 内部模块约定 @@ -419,24 +422,31 @@ my-plugin/ api.ts # 面向外部使用者的公共导出 runtime-api.ts # 仅供内部使用的运行时导出 index.ts # 插件入口点 - setup-entry.ts # 轻量级仅设置入口点（可选） + setup-entry.ts # 仅设置用的轻量入口（可选） ``` - 不要在生产代码中通过 `openclaw/plugin-sdk/` 导入你自己的插件。请通过 `./api.ts` 或 `./runtime-api.ts` 路由内部导入。SDK 路径仅是对外契约。 + 不要在生产代码中通过 `openclaw/plugin-sdk/` + 导入你自己的插件。请通过 `./api.ts` 或 + `./runtime-api.ts` 进行内部导入。SDK 路径只是外部契约。 -门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）现在在 OpenClaw 已运行时优先使用活动运行时配置快照。如果尚不存在运行时快照，则回退到磁盘上解析得到的配置文件。 +通过门面加载的内置插件公共 surface（`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/*` 契约。 其他当前内置示例： -- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助函数和实时提供商构建器 -- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/配置辅助函数 +- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、 + 默认模型辅助函数和实时提供商构建器 +- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及 + 新手引导/配置辅助函数 - 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。如果某个辅助函数确实需要共享，请将其提升为中立的 SDK 子路径，例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他面向能力的表面，而不是让两个插件彼此耦合。 + 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。 + 如果某个辅助函数确实是共享的，应将其提升到一个中立的 SDK 子路径， + 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他 + 面向能力的 surface，而不是让两个插件耦合在一起。 ## 相关内容 @@ -445,5 +455,5 @@ my-plugin/ - [运行时辅助函数](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考 - [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、manifest、配置 schema - [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则 -- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移 -- [插件内部原理](/zh-CN/plugins/architecture) — 深入的架构和能力模型 +- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用 surface 迁移 +- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构和能力模型