Plugin 架構內部機制

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

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

​

載入管線

1. 探索候選 Plugin 根目錄
2. 讀取原生或相容 bundle 資訊清單與套件中繼資料
3. 拒絕不安全的候選項
4. 正規化 Plugin 設定（plugins.enabled、allow、deny、entries、 slots、load.paths）
5. 決定每個候選項是否啟用
6. 載入已啟用的原生模組：已建置的 bundled 模組使用原生載入器； 第三方本機原始碼 TypeScript 使用緊急 Jiti fallback
7. 呼叫原生 register(api) hook，並將註冊收集到 Plugin 登錄表
8. 將登錄表公開給命令/執行階段介面

​

資訊清單優先行為

• 識別 Plugin
• 探索宣告的頻道/skills/設定 schema 或 bundle 能力
• 驗證 plugins.entries.<id>.config
• 補充 Control UI 標籤/placeholder
• 顯示安裝/catalog 中繼資料
• 在不載入 Plugin 執行階段的情況下保留低成本 activation 與設定描述器

• CLI 載入會縮小到擁有所要求主要命令的 Plugin
• 頻道設定/Plugin 解析會縮小到擁有所要求頻道 id 的 Plugin
• 明確的 provider 設定/執行階段解析會縮小到擁有所要求 provider id 的 Plugin
• Gateway 啟動規劃會使用 activation.onStartup 進行明確的啟動匯入與啟動選擇退出；沒有啟動中繼資料的 Plugin 只會透過較窄的 activation 觸發器載入

​

Plugin 快取邊界

• PluginLoaderCacheState 與相容的作用中執行階段登錄表
• 用於避免重複匯入相同執行階段介面的 jiti/模組快取與公開介面載入器快取
• 已安裝 Plugin artifact 的檔案系統快取
• 用於路徑正規化或重複項解析的短生命週期每次呼叫 map

• 探索結果
• 直接資訊清單登錄表
• 從已安裝 Plugin 索引重建的資訊清單登錄表
• provider 擁有者查詢、模型抑制、provider 政策，或公開 artifact 中繼資料
• 任何其他由資訊清單推導的答案，其中變更後的資訊清單、已安裝索引或載入路徑應該在下一次中繼資料讀取時可見

​

登錄表模型

• Plugin 記錄（身分、來源、origin、狀態、診斷）
• 工具
• 舊版 hook 與具型別 hook
• 頻道
• provider
• Gateway RPC handler
• HTTP 路由
• CLI registrar
• 背景服務
• Plugin 擁有的命令

• Plugin 模組 -> 登錄表註冊
• 核心執行階段 -> 登錄表消費

​

對話繫結 callback

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" 或 "denied"
• decision: "allow-once"、"allow-always" 或 "deny"
• binding: 已核准要求的已解析繫結
• request: 原始要求摘要、detach 提示、sender id 與對話中繼資料

​

Provider 執行階段 hook

• 資訊清單中繼資料，用於低成本的執行階段前查詢： setup.providers[].envVars、已棄用的相容性 providerAuthEnvVars、 providerAuthAliases、providerAuthChoices 與 channelEnvVars。
• 設定時間 hook：catalog（舊版 discovery）加上 applyConfigDefaults。
• 執行階段 hook：40 多個選用 hook，涵蓋 auth、模型解析、 stream wrapping、thinking levels、replay policy 與 usage endpoints。請參閱 Hook 順序與用法 下方的完整清單。

​

Hook 順序與用法

​

Provider 範例

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);
  },
});

​

內建範例

​

Runtime helper

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

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

• textToSpeech 會回傳一般核心 TTS output payload，供 file/voice-note surface 使用。
• 使用核心 messages.tts configuration 和 provider selection。
• 回傳 PCM audio buffer + sample rate。Plugin 必須為 provider 重新取樣/編碼。
• listVoices 依 provider 而定是 optional。可用於 vendor 擁有的 voice picker 或 setup flow。
• Voice listing 可以包含更豐富的 metadata，例如 locale、gender 與 personality tag，以供 provider-aware picker 使用。
• OpenAI 和 ElevenLabs 目前支援 telephony。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 policy、fallback 和 reply delivery 保留在核心。
• 使用 speech provider 處理 vendor 擁有的 synthesis 行為。
• 舊版 Microsoft edge input 會 normalize 為 microsoft provider id。
• 偏好的 ownership model 是以公司為導向：一個 vendor plugin 可以在 OpenClaw 新增這些 capability contract 時，擁有 text、speech、image 與未來的 media provider。

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

• 將 orchestration、fallback、config 與 channel wiring 保留在核心。
• 將 vendor 行為保留在 provider plugin。
• Additive expansion 應維持 typed：新的 optional method、新的 optional result field、新的 optional capability。
• Video generation 已遵循相同模式：
  • 核心擁有 capability contract 和 runtime helper
  • vendor plugin 註冊 api.registerVideoGenerationProvider(...)
  • feature/channel plugin 使用 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 extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.5",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* 是 image/audio/video understanding 偏好的共用 surface。
• extractStructuredWithModel(...) 是面向 plugin 的 seam，用於 bounded provider-owned image-first extraction。至少包含一個 image input； text input 是補充 context。 product plugin 擁有其 route 與 schema，而 OpenClaw 擁有 provider/runtime boundary。
• 使用核心 media-understanding audio configuration（tools.media.audio）和 provider fallback order。
• 當沒有產生 transcription output 時（例如 skipped/unsupported input），回傳 { text: undefined }。
• api.runtime.stt.transcribeAudioFile(...) 仍保留為 compatibility alias。

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider 和 model 是每次 run 的 optional override，不是 persistent session change。
• OpenClaw 只會對受信任的 caller 採用這些 override field。
• 對於 plugin-owned fallback run，operator 必須以 plugins.entries.<id>.subagent.allowModelOverride: true 選用。
• 使用 plugins.entries.<id>.subagent.allowedModels 將受信任 plugin 限制到特定 canonical provider/model target，或使用 "*" 明確允許任何 target。
• Untrusted plugin subagent run 仍可運作，但 override request 會被拒絕，而不是 silently falling back。
• Plugin 建立的 subagent session 會以建立它的 plugin id 標記。Fallback api.runtime.subagent.deleteSession(...) 只能刪除這些 owned session；任意 session deletion 仍需要 admin-scoped Gateway request。

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

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• 將 provider selection、credential resolution 與 shared request semantics 保留在核心。
• 使用 web-search provider 處理 vendor-specific search transport。
• api.runtime.webSearch.* 是需要 search 行為但不想依賴 agent tool wrapper 的 feature/channel plugin 偏好的共用 surface。

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

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

• generate(...)：使用 configured image-generation provider chain 產生 image。
• listProviders(...)：列出可用的 image-generation provider 及其 capability。

​

Gateway HTTP route

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

• path：Gateway HTTP server 下的 route path。
• auth：必填。使用 "gateway" 要求一般 Gateway auth，或使用 "plugin" 進行 plugin-managed auth/webhook verification。
• match：optional。"exact"（default）或 "prefix"。
• replaceExisting：optional。允許同一個 plugin 取代自己的既有 route registration。
• handler：當 route 已處理 request 時回傳 true。

• api.registerHttpHandler(...) 已移除，且會造成 Plugin 載入錯誤。請改用 api.registerHttpRoute(...)。
• Plugin 路由必須明確宣告 auth。
• 除非設定 replaceExisting: true，否則會拒絕完全相同的 path + match 衝突，而且一個 Plugin 不能取代另一個 Plugin 的路由。
• 會拒絕具有不同 auth 層級的重疊路由。請只在相同的 auth 層級上保留 exact/prefix 後援鏈。
• auth: "plugin" 路由不會自動收到操作者執行階段範圍。這些路由是供 Plugin 管理的 Webhook/簽章驗證使用，不是供具特權的 Gateway 輔助呼叫使用。
• auth: "gateway" 路由會在 Gateway 請求執行階段範圍內執行，但該範圍刻意保守：
  • 共用密鑰 bearer auth（gateway.auth.mode = "token" / "password"）會讓 Plugin 路由執行階段範圍固定在 operator.write，即使呼叫者送出 x-openclaw-scopes 也是如此
  • 受信任、帶有身分的 HTTP 模式（例如 trusted-proxy，或私有入口上的 gateway.auth.mode = "none"）只有在標頭明確存在時，才會採用 x-openclaw-scopes
  • 如果這些帶有身分的 Plugin 路由請求缺少 x-openclaw-scopes，執行階段範圍會退回 operator.write
• 實務規則：不要假設 gateway-auth Plugin 路由是隱含的管理員介面。如果你的路由需要僅限管理員的行為，請要求帶有身分的 auth 模式，並記錄明確的 x-openclaw-scopes 標頭合約。

​

Plugin SDK 匯入路徑

• index.js — 隨附 Plugin 進入點
• api.js — 輔助工具/型別 barrel
• runtime-api.js — 僅限執行階段的 barrel
• setup-entry.js — 設定 Plugin 進入點

​

訊息工具結構描述

• presentation 用於語意呈現區塊（text, context, divider, buttons, select）
• delivery-pin 用於釘選傳送請求

​

通道目標解析

• messaging.inferTargetChatType({ to }) 會在目錄查找前決定正規化目標 應被視為 direct、group 還是 channel。
• messaging.targetResolver.looksLikeId(raw, normalized) 會告訴核心某個輸入 是否應略過目錄搜尋，直接進入類似 ID 的解析。
• messaging.targetResolver.resolveTarget(...) 是核心在正規化後或目錄未命中後， 需要最終由提供者擁有的解析時使用的 Plugin 後援。
• messaging.resolveOutboundSessionRoute(...) 會在目標解析後，負責提供者專用的工作階段 路由建構。

• 使用 inferTargetChatType 處理應在搜尋對等端/群組前發生的分類決策。
• 使用 looksLikeId 進行「將此視為明確/原生目標 ID」檢查。
• 使用 resolveTarget 作為提供者專用正規化後援，而不是用於寬泛的目錄搜尋。
• 將提供者原生 ID（例如聊天 ID、執行緒 ID、JID、控制代碼和房間 ID）保留在 target 值或提供者專用參數中， 不要放在通用 SDK 欄位中。

​

由設定支援的目錄

• 由允許清單驅動的 DM 對等端
• 已設定的通道/群組對應
• 以帳號為範圍的靜態目錄後援

• 查詢篩選
• 套用限制
• 去重/正規化輔助工具
• 建立 ChannelDirectoryEntry[]

​

提供者目錄

• { provider } 用於單一提供者項目
• { providers } 用於多個提供者項目

• simple：普通 API 金鑰或由環境驅動的提供者
• profile：當 auth 設定檔存在時出現的提供者
• paired：合成多個相關提供者項目的提供者
• late：最後一道處理，在其他隱含提供者之後

• discovery 仍可作為舊版別名運作，但會發出棄用警告
• 如果同時註冊 catalog 和 discovery，OpenClaw 會使用 catalog
• augmentModelCatalog 已棄用；隨附提供者應透過 registerModelCatalogProvider 發布 補充列

​

唯讀通道檢查

• resolveAccount(...) 是執行階段路徑。它可以假設認證資料 已完整具體化，並且可在缺少必要秘密時快速失敗。
• 唯讀命令路徑，例如 openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve，以及 doctor/設定 修復流程，不應只是為了描述設定就需要具體化執行階段認證資料。

• 只回傳描述性的帳號狀態。
• 保留 enabled 和 configured。
• 視需要包含認證資料來源/狀態欄位，例如：
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• 你不需要為了回報唯讀可用性而回傳原始權杖值。 回傳 tokenStatus: "available"（以及相符的來源欄位）就足以供狀態類命令使用。
• 當認證資料透過 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 (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via 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：此目錄項目應優先於其上的較低優先權 Plugin/通道 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 target 時優先使用 session lookup

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

​

Context engine Plugin

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

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", 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: "My Memory Engine",
      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. 定義核心契約 決定核心應擁有哪些共享行為：政策、fallback、設定合併、生命週期、面向通道的語意，以及執行階段輔助工具形狀。
2. 加入型別化的 Plugin 註冊/執行階段介面 以最小實用的型別化能力介面擴充 OpenClawPluginApi 和/或 api.runtime。
3. 串接核心 + 通道/功能消費者 通道與功能 Plugin 應透過核心消費新能力，而不是直接匯入 vendor 實作。
4. 註冊 vendor 實作 然後由 vendor Plugin 針對該能力註冊其後端。
5. 加入契約覆蓋 加入測試，讓所有權與註冊形狀能隨時間保持明確。

​

能力檢查清單

• src/<capability>/types.ts 中的核心契約型別
• src/<capability>/runtime.ts 中的核心 runner/執行階段輔助工具
• src/plugins/types.ts 中的 Plugin API 註冊介面
• src/plugins/registry.ts 中的 Plugin registry 串接
• 當功能/通道 Plugin 需要消費它時，src/plugins/runtime/* 中的 Plugin 執行階段公開
• src/test-utils/plugin-registration.ts 中的 capture/test 輔助工具
• src/plugins/contracts/registry.ts 中的所有權/契約斷言
• docs/ 中的 operator/Plugin 文件

​

能力範本

// 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"]);

• 核心擁有能力契約 + 編排
• vendor Plugin 擁有 vendor 實作
• 功能/通道 Plugin 消費執行階段輔助工具
• 契約測試讓所有權保持明確

​

相關

• Plugin 架構 — 公開能力模型與形狀
• Plugin SDK subpaths
• Plugin SDK setup
• 建置 Plugin