插件架构内部

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

加载流水线

1. 发现候选插件根目录
2. 读取原生或兼容捆绑清单以及包元数据
3. 拒绝不安全的候选项
4. 规范化插件配置（plugins.enabled、allow、deny、entries、 slots、load.paths）
5. 为每个候选项决定是否启用
6. 加载已启用的原生模块：已构建的捆绑模块使用原生加载器； 第三方本地源码 TypeScript 使用紧急 Jiti 回退
7. 调用原生 register(api) 钩子，并将注册内容收集到插件注册表中
8. 将注册表暴露给命令/运行时界面

​

清单优先行为

• 识别插件
• 发现声明的通道/技能/配置模式或 bundle 能力
• 验证 plugins.entries.<id>.config
• 增强 Control UI 标签/占位符
• 展示安装/目录元数据
• 在不加载插件运行时的情况下保留廉价的激活和设置描述符

• CLI 加载会缩小到拥有所请求主命令的插件
• 通道设置/插件解析会缩小到拥有所请求 通道 id 的插件
• 显式提供者设置/运行时解析会缩小到拥有所请求提供者 id 的插件
• Gateway 启动规划会使用 activation.onStartup 进行显式启动 导入和启动退出；没有启动元数据的插件只会通过更窄的激活触发加载

​

插件缓存边界

• PluginLoaderCacheState 和兼容的活动运行时注册表
• jiti/module 缓存和公共表面加载器缓存，用于避免重复导入 相同的运行时表面
• 用于已安装插件工件的文件系统缓存
• 用于路径规范化或重复项解析的短生命周期、按调用创建的 map

• 发现结果
• 直接的清单注册表
• 从已安装插件索引重建的清单注册表
• 提供者所有者查找、模型抑制、提供者策略或公共工件元数据
• 任何其他派生自清单的答案，只要清单变更、已安装索引变化或加载路径变化，应在下一次元数据读取时可见

​

注册表模型

• 插件记录（标识、来源、origin、状态、诊断）
• 工具
• 旧式 hooks 和类型化 hooks
• 通道
• 提供者
• Gateway RPC 处理器
• HTTP 路由
• CLI 注册器
• 后台服务
• 插件拥有的命令

• 插件模块 -> 注册表注册
• 核心运行时 -> 注册表消费

​

会话绑定回调

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // 现在已经为该插件 + 会话存在一个绑定。
        console.log(event.binding?.conversationId);
        return;
      }

      // 请求被拒绝；清除任何本地待处理状态。
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status："approved" 或 "denied"
• decision："allow-once"、"allow-always" 或 "deny"
• binding：批准请求的已解析绑定
• request：原始请求摘要、detach 提示、发送者 id 和会话元数据

​

提供者运行时钩子

• 清单元数据：用于廉价的运行前查找： setup.providers[].envVars、已弃用的兼容项 providerAuthEnvVars、 providerAuthAliases、providerAuthChoices 和 channelEnvVars。
• 配置期钩子：catalog（旧名 discovery）以及 applyConfigDefaults。
• 运行时钩子：40 多个可选钩子，覆盖认证、模型解析、 流包装、思考层级、回放策略和使用量端点。完整列表见 钩子顺序与使用。

​

钩子顺序与使用

​

提供者示例

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

内置示例

​

运行时辅助工具

const clip = await api.runtime.tts.textToSpeech({
  text: "来自 OpenClaw 的问候",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "来自 OpenClaw 的问候",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech 会返回用于文件/语音备注界面的标准核心 TTS 输出载荷。
• 使用核心 messages.tts 配置和提供方选择。
• 返回 PCM 音频缓冲区 + 采样率。插件必须针对提供方进行重采样/编码。
• listVoices 是按提供方可选的。可用于供应商自有的语音选择器或设置流程。
• 语音列表可以包含更丰富的元数据，例如地区、性别和个性标签，以便为感知提供方的选择器提供支持。
• OpenAI 和 ElevenLabs 目前支持电话场景。Microsoft 不支持。

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• 将 TTS 策略、回退和回复投递保留在核心中。
• 对于供应商自有的合成行为，请使用语音提供方。
• 旧版 Microsoft edge 输入会被规范化为 microsoft 提供方 id。
• 推荐的所有权模型是公司导向的：一个供应商插件可以拥有文本、语音、图像，以及 OpenClaw 增加这些能力合同时的未来媒体提供方。

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• 将编排、回退、配置和通道接线保留在核心中。
• 将供应商行为保留在提供方插件中。
• 增量扩展应保持类型化：新增可选方法、新增可选结果字段、新增可选能力。
• 视频生成已经遵循相同模式：
  • 核心负责能力合约和运行时辅助工具
  • 供应商插件注册 api.registerVideoGenerationProvider(...)
  • 功能/通道插件消费 api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // 当无法可靠推断 MIME 时可选：
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* 是图像/音频/视频理解的首选共享接口。
• 使用核心媒体理解音频配置（tools.media.audio）和提供方回退顺序。
• 当未产生转写输出时返回 { text: undefined }（例如跳过/不支持的输入）。
• api.runtime.stt.transcribeAudioFile(...) 仍然作为兼容别名保留。

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "将此查询扩展为聚焦的后续搜索。",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider 和 model 是每次运行可选的覆盖项，而不是持久的会话更改。
• OpenClaw 仅对受信任的调用方接受这些覆盖字段。
• 对于插件拥有的回退运行，操作员必须显式开启 plugins.entries.<id>.subagent.allowModelOverride: true。
• 使用 plugins.entries.<id>.subagent.allowedModels 可将受信任插件限制为特定的规范 provider/model 目标，或使用 "*" 明确允许任意目标。
• 不受信任的插件子代理运行仍然可以工作，但覆盖请求会被拒绝，而不是静默回退。
• 插件创建的子代理会话会标记为创建它们的插件 id。兼容的 api.runtime.subagent.deleteSession(...) 只能删除这些归属会话；任意会话删除仍需要管理员范围的 Gateway 请求。

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw 插件运行时辅助工具",
    count: 5,
  },
});

• 将提供方选择、凭据解析和共享请求语义保留在核心中。
• 对于供应商特定的搜索传输，请使用网络搜索提供方。
• api.runtime.webSearch.* 是需要搜索行为、但不依赖代理工具包装器的功能/通道插件的首选共享接口。

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "一个友好的龙虾吉祥物", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...)：使用已配置的图像生成提供方链生成图像。
• listProviders(...)：列出可用的图像生成提供方及其能力。

​

Gateway HTTP 路由

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path：Gateway HTTP 服务器下的路由路径。
• auth：必填。使用 "gateway" 需要普通 Gateway 认证，或使用 "plugin" 进行插件管理的认证/ webhook 验证。
• match：可选。"exact"（默认）或 "prefix"。
• replaceExisting：可选。允许同一插件替换其自己的现有路由注册。
• handler：当路由已处理请求时返回 true。

• api.registerHttpHandler(...) 已被移除，会导致插件加载错误。请改用 api.registerHttpRoute(...)。
• 插件路由必须显式声明 auth。
• 精确的 path + match 冲突会被拒绝，除非使用 replaceExisting: true，且一个插件不能替换另一个插件的路由。
• 不同 auth 级别的重叠路由会被拒绝。仅在相同 auth 级别上保留 exact/prefix 兜底链。
• auth: "plugin" 路由不会自动接收操作员运行时范围。它们用于插件管理的 webhooks/签名验证，而不是特权的 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 头部契约。

​

Plugin SDK 导入路径

• index.js — 打包后的插件入口
• api.js — 辅助工具/类型 barrel
• runtime-api.js — 仅运行时 barrel
• setup-entry.js — 设置插件入口

​

消息工具架构

• presentation：用于语义化展示块（text、context、divider、buttons、select）
• delivery-pin：用于置顶投递请求

​

渠道目标解析

• messaging.inferTargetChatType({ to }) 在目录查找前决定归一化后的目标应被视为 direct、group 还是 channel。
• messaging.targetResolver.looksLikeId(raw, normalized) 告诉 core 输入是否应直接跳过目录搜索，进入类 id 的解析。
• messaging.targetResolver.resolveTarget(...) 是插件级回退逻辑，在 core 在归一化之后或目录未命中之后需要进行最终的 provider 拥有的解析时使用。
• messaging.resolveOutboundSessionRoute(...) 在目标解析完成后负责构建 provider 特定的会话路由。

• 将 inferTargetChatType 用于应在搜索 peers/groups 之前发生的分类决策。
• 将 looksLikeId 用于“将其视为显式/原生目标 id”的检查。
• 将 resolveTarget 用于 provider 特定的归一化回退，而不是用于广泛目录搜索。
• 将 chat id、thread id、JID、handle 和 room id 等 provider 原生 id 保留在 target 值或 provider 特定参数中，而不是放在通用 SDK 字段里。

​

基于配置的目录

• 基于 allowlist 的 DM peers
• 已配置的 channel/group 映射
• 账户作用域的静态目录回退

• 查询过滤
• limit 应用
• 去重/归一化辅助
• 构建 ChannelDirectoryEntry[]

​

provider 目录

• { provider } 表示单个 provider 条目
• { providers } 表示多个 provider 条目

• simple：普通 API key 或 env 驱动的 provider
• profile：在存在认证 profile 时出现的 provider
• paired：合成多个相关 provider 条目的 provider
• late：最后一轮，在其他隐式 provider 之后

• discovery 仍作为旧版别名可用
• 如果同时注册了 catalog 和 discovery，OpenClaw 使用 catalog

​

只读渠道检查

• resolveAccount(...) 是运行时路径。它可以假设凭据已经完全 materialize，并且在所需密钥缺失时快速失败。
• 诸如 openclaw status、openclaw status --all、openclaw channels status、openclaw channels resolve 以及 doctor/config 修复流程等只读命令路径，不应仅为了描述配置而去 materialize 运行时凭据。

• 只返回具描述性的账户状态。
• 保留 enabled 和 configured。
• 在相关时包含凭据来源/状态字段，例如：
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• 仅为了报告只读可用性，不需要返回原始 token 值。返回 tokenStatus: "available"（以及匹配的 source 字段）对状态类命令已经足够。
• 当凭据通过 SecretRef 配置，但在当前命令路径中不可用时，使用 configured_unavailable。

​

包集合

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• 渠道注册本身
• gateway 开始监听前必须可用的任何 HTTP 路由
• 在同一窗口中必须存在的任何 gateway 方法、工具或服务

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

渠道目录元数据

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk（自托管）",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "通过 Nextcloud Talk webhook bots 提供自托管聊天。",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel：用于更丰富目录/状态界面的次级标签
• docsLabel：覆盖文档链接的链接文本
• preferOver：此目录条目应优先于哪些低优先级插件/渠道 id
• selectionDocsPrefix、selectionDocsOmitLabel、selectionExtras：选择界面的文案控制
• markdownCapable：将渠道标记为支持 markdown，用于出站格式化决策
• exposure.configured：设为 false 时，从已配置渠道列表界面隐藏该渠道
• exposure.setup：设为 false 时，从交互式 setup/configure 选择器中隐藏该渠道
• exposure.docs：将该渠道在文档导航界面中标记为内部/私有
• showConfigured / showInSetup：仍接受的旧版别名；优先使用 exposure
• quickstartAllowFrom：让渠道进入标准 quickstart 的 allowFrom 流程
• forceAccountBinding：即使只有一个账户也要求显式账户绑定
• preferSessionLookupForAnnounceTarget：解析 announce 目标时优先使用会话查找

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

上下文引擎插件

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "无损爪", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "我的记忆引擎",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

添加新能力

1. 定义核心契约
   决定核心应负责哪些共享行为：策略、回退、配置合并、生命周期、面向通道的语义，以及运行时辅助函数的形状。
2. 添加带类型的插件注册/运行时表面
   在 OpenClawPluginApi 和/或 api.runtime 上扩展最小且有用的类型化能力表面。
3. 连接 core + channel/feature 消费方
   通道和功能插件应通过 core 消费新能力，而不是直接导入某个厂商实现。
4. 注册厂商实现
   然后由厂商插件针对该能力注册其后端实现。
5. 添加契约覆盖
   添加测试，使所有权和注册形式能够长期保持明确。

​

能力检查清单

• src/<capability>/types.ts 中的 core 契约类型
• src/<capability>/runtime.ts 中的 core 运行器/运行时辅助函数
• src/plugins/types.ts 中的插件 API 注册表面
• src/plugins/registry.ts 中的插件注册表连接线
• 当功能/通道插件需要消费它时，在 src/plugins/runtime/* 中暴露插件运行时
• src/test-utils/plugin-registration.ts 中的捕获/测试辅助函数
• src/plugins/contracts/registry.ts 中的所有权/契约断言
• docs/ 中的运维/插件文档

​

能力模板

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• core 负责能力契约 + 编排
• 厂商插件负责厂商实现
• 功能/通道插件消费运行时辅助函数
• 契约测试让所有权保持明确

​

相关内容

• 插件架构 — 公共能力模型和形状
• 插件 SDK 子路径
• 插件 SDK 设置
• 构建插件