Plugin 架構內部機制

Documentation Index

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

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

​

載入管線

1. 探索候選 Plugin 根目錄
2. 讀取原生或相容套件 manifest 與套件中繼資料
3. 拒絕不安全的候選項目
4. 正規化 Plugin 設定（plugins.enabled、allow、deny、entries、 slots、load.paths）
5. 判定每個候選項目的啟用狀態
6. 載入已啟用的原生模組：已建置的 bundled 模組使用原生載入器； 未建置的原生 Plugin 使用 jiti
7. 呼叫原生 register(api) hook，並將註冊內容收集到 Plugin 註冊表
8. 將註冊表公開給命令/執行階段介面

​

Manifest 優先行為

• 識別 Plugin
• 探索宣告的通道/Skills/設定結構描述或套件能力
• 驗證 plugins.entries.<id>.config
• 補充 Control UI 標籤/預留位置
• 顯示安裝/目錄中繼資料
• 在不載入 Plugin 執行階段的情況下，保留低成本的啟用與設定描述子

• CLI 載入會縮小到擁有所要求主要命令的 Plugin
• 通道設定/Plugin 解析會縮小到擁有所要求 通道 id 的 Plugin
• 明確的供應商設定/執行階段解析會縮小到擁有所要求 供應商 id 的 Plugin
• Gateway 啟動規劃會使用 activation.onStartup 來處理明確的啟動 匯入與啟動退出；隨著 OpenClaw 擺脫隱含啟動匯入，每個 Plugin 都應宣告它，而沒有靜態能力中繼資料且沒有 activation.onStartup 的 Plugin，仍會為了相容性使用已棄用的隱含啟動 sidecar fallback

​

Plugin 快取邊界

• PluginLoaderCacheState 與相容的作用中執行階段註冊表
• jiti/模組快取，以及用於避免重複匯入相同執行階段介面的公開介面載入器快取
• 已安裝 Plugin 成品的執行階段相依鏡像與檔案系統快取
• 用於路徑正規化或重複解析的短生命週期逐次呼叫 map

• 探索結果
• 直接 manifest 註冊表
• 從已安裝 Plugin 索引重建的 manifest 註冊表
• 供應商擁有者查詢、模型抑制、供應商策略或公開成品中繼資料
• 任何其他由 manifest 衍生的答案，只要變更的 manifest、已安裝索引或載入路徑 應該在下一次中繼資料讀取時可見

​

註冊表模型

• Plugin 記錄（身分、來源、原點、狀態、診斷）
• 工具
• 舊版 hook 與型別化 hook
• 通道
• 供應商
• Gateway RPC 處理器
• HTTP 路由
• CLI 註冊器
• 背景服務
• Plugin 擁有的命令

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

​

對話繫結回呼

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 提示、寄件者 id 與 對話中繼資料

​

供應商執行階段 hook

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

​

Hook 順序與用法

​

供應商範例

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: "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 輸出承載，用於檔案/語音備註表面。
• 使用核心 messages.tts 設定和供應商選擇。
• 回傳 PCM 音訊緩衝區 + 取樣率。Plugin 必須為供應商重新取樣/編碼。
• 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 新增這些 能力合約，一個廠商 Plugin 可以擁有文字、語音、影像和未來的媒體供應商。

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

• 將編排、後援、設定和頻道接線保留在核心中。
• 將廠商行為保留在供應商 Plugin 中。
• 加法式擴展應保持具型別：新的選用方法、新的選用 結果欄位、新的選用能力。
• 影片生成已遵循相同模式：
  • 核心擁有能力合約和執行階段輔助工具
  • 廠商 Plugin 註冊 api.registerVideoGenerationProvider(...)
  • 功能/頻道 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 { 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.* 是影像/音訊/影片理解的偏好共用表面。
• 使用核心媒體理解音訊設定（tools.media.audio）和供應商後援順序。
• 當未產生轉錄輸出時（例如略過/不支援的輸入），回傳 { text: undefined }。
• api.runtime.stt.transcribeAudioFile(...) 仍作為相容性別名保留。

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 是每次執行的選用覆寫，不是持久性的工作階段變更。
• OpenClaw 只會為受信任呼叫端採納這些覆寫欄位。
• 對於 Plugin 擁有的後援執行，操作員必須使用 plugins.entries.<id>.subagent.allowModelOverride: true 選擇啟用。
• 使用 plugins.entries.<id>.subagent.allowedModels 將受信任 Plugin 限制為特定的標準 provider/model 目標，或使用 "*" 明確允許任何目標。
• 不受信任的 Plugin 子代理執行仍可運作，但覆寫請求會被拒絕，而不是靜默後援。
• Plugin 建立的子代理工作階段會標記建立該工作階段的 Plugin 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 plugin runtime helpers",
    count: 5,
  },
});

• 將供應商選擇、憑證解析和共用請求語意保留在核心中。
• 使用網頁搜尋供應商處理廠商專用搜尋傳輸。
• api.runtime.webSearch.* 是需要搜尋行為但不想依賴代理工具包裝器的功能/頻道 Plugin 的偏好共用表面。

​

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(...)：使用已設定的影像生成供應商鏈生成影像。
• 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" 進行 Plugin 管理的驗證/webhook 驗證。
• match：選用。"exact"（預設）或 "prefix"。
• replaceExisting：選用。允許同一個 Plugin 取代其既有的路由註冊。
• handler：當路由已處理請求時回傳 true。

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

​

Plugin SDK 匯入路徑

• index.js — bundled Plugin 入口
• api.js — 輔助工具/types barrel
• runtime-api.js — 僅限執行階段的 barrel
• setup-entry.js — setup Plugin 入口

​

Message tool schemas

• presentation 用於語義化 presentation blocks（text、context、divider、buttons、select）
• delivery-pin 用於 pinned-delivery 請求

​

Channel target resolution

• messaging.inferTargetChatType({ to }) 會在 directory lookup 前決定 normalized target 應視為 direct、group 或 channel。
• messaging.targetResolver.looksLikeId(raw, normalized) 會告訴 core 某個輸入是否應跳過 directory search，直接進入 id-like resolution。
• messaging.targetResolver.resolveTarget(...) 是當 core 在 normalization 後或 directory miss 後需要最終 provider 所擁有 resolution 時的 Plugin fallback。
• messaging.resolveOutboundSessionRoute(...) 會在 target 解析完成後，擁有 provider 專屬 session route 建構。

• 使用 inferTargetChatType 處理應在搜尋 peers/groups 前發生的 category 決策。
• 使用 looksLikeId 處理「將此視為明確/原生 target id」檢查。
• 使用 resolveTarget 作為 provider 專屬 normalization fallback，而不是用於廣泛的 directory search。
• 將 chat ids、thread ids、JIDs、handles 與 room ids 等 provider 原生 ids 保留在 target 值或 provider 專屬 params 中，不要放在通用 SDK 欄位。

​

Config-backed directories

• allowlist 驅動的 DM peers
• 已設定的 channel/group maps
• account-scoped 靜態 directory fallbacks

• query filtering
• limit application
• deduping/normalization helpers
• 建立 ChannelDirectoryEntry[]

​

Provider catalogs

• { provider } 用於單一 provider entry
• { providers } 用於多個 provider entries

• simple：純 API-key 或 env 驅動的 providers
• profile：當 auth profiles 存在時出現的 providers
• paired：合成多個相關 provider entries 的 providers
• late：最後一輪，在其他 implicit providers 之後

• discovery 仍可作為舊版 alias 使用
• 如果同時註冊了 catalog 與 discovery，OpenClaw 會使用 catalog

​

唯讀 channel inspection

• resolveAccount(...) 是執行階段路徑。它可以假設 credentials 已完整具現化，並在缺少必要 secrets 時快速失敗。
• 唯讀命令路徑，例如 openclaw status、openclaw status --all、 openclaw channels status、openclaw channels resolve，以及 doctor/config repair flows，不應只為了描述設定就需要具現化執行階段 credentials。

• 只回傳描述性的 account state。
• 保留 enabled 與 configured。
• 相關時包含 credential source/status 欄位，例如：
  • tokenSource、tokenStatus
  • botTokenSource、botTokenStatus
  • appTokenSource、appTokenStatus
  • signingSecretSource、signingSecretStatus
• 你不需要回傳原始 token 值就能回報唯讀可用性。回傳 tokenStatus: "available"（以及對應的 source 欄位）對 status-style 命令就足夠了。
• 當 credential 透過 SecretRef 設定，但在目前命令路徑中不可用時，使用 configured_unavailable。

​

Package packs

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

• channel registration 本身
• Gateway 開始 listening 前必須可用的任何 HTTP routes
• 在同一時間窗口內必須存在的任何 gateway methods、tools 或 services

• 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 時，從互動式設定/設定精靈選擇器隱藏該頻道
• exposure.docs：將頻道標記為文件導覽介面的內部/私有項目
• showConfigured / showInSetup：為了相容性仍接受的舊版別名；優先使用 exposure
• quickstartAllowFrom：讓頻道加入標準快速入門 allowFrom 流程
• forceAccountBinding：即使只存在一個帳號，也要求明確帳號繫結
• preferSessionLookupForAnnounceTarget：解析公告目標時優先使用工作階段查找

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

​

上下文引擎 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. 定義 Core 合約 決定 Core 應擁有哪些共享行為：政策、fallback、設定合併、 生命週期、面向頻道的語義，以及 runtime helper 形狀。
2. 新增型別化 Plugin 註冊/runtime 介面 以最小可用的型別化能力介面擴充 OpenClawPluginApi 和/或 api.runtime。
3. 串接 Core + 頻道/功能消費者 頻道與功能 Plugin 應透過 Core 消費新能力， 而不是直接匯入供應商實作。
4. 註冊供應商實作 接著供應商 Plugin 會針對該能力註冊其後端。
5. 新增合約覆蓋 新增測試，讓擁有權與註冊形狀隨時間保持明確。

​

能力檢查清單

• src/<capability>/types.ts 中的 Core 合約型別
• src/<capability>/runtime.ts 中的 Core runner/runtime helper
• src/plugins/types.ts 中的 Plugin API 註冊介面
• src/plugins/registry.ts 中的 Plugin registry 串接
• 當功能/頻道 Plugin 需要消費它時，src/plugins/runtime/* 中的 Plugin runtime 暴露
• src/test-utils/plugin-registration.ts 中的擷取/測試 helper
• 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"]);

• Core 擁有能力合約 + 編排
• 供應商 Plugin 擁有供應商實作
• 功能/頻道 Plugin 消費 runtime helper
• 合約測試讓擁有權保持明確

​

相關

• Plugin 架構 — 公開能力模型與形狀
• Plugin SDK 子路徑
• Plugin SDK 設定
• 建置 Plugin