Skip to content
OpenClaw Docs

Plugin SDK 概觀

Plugin SDK 概觀

Section titled “Plugin SDK 概觀”

Plugin SDK 是外掛與核心之間的型別合約。此頁面是關於要匯入什麼以及您可以註冊什麼的參考。

匯入慣例

Section titled “匯入慣例”

請務必從特定的子路徑匯入：

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";

每個子路徑都是一個小型的自包含模組。這可以保持啟動速度並防止循環相依性問題。

子路徑參考

Section titled “子路徑參考”

依用途分組的最常用子路徑。包含 100 多個子路徑的完整清單位於 scripts/lib/plugin-sdk-entrypoints.json。

外掛入口點

Section titled “外掛入口點”
子路徑主要匯出
plugin-sdk/plugin-entrydefinePluginEntry
plugin-sdk/coredefineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema
Channel subpaths
SubpathKey exports
plugin-sdk/channel-setupcreateOptionalChannelSetupSurface
plugin-sdk/channel-pairingcreateChannelPairingController
plugin-sdk/channel-reply-pipelinecreateChannelReplyPipeline
plugin-sdk/channel-config-helperscreateHybridChannelConfigAdapter
plugin-sdk/channel-config-schema頻道設定結構描述類型
plugin-sdk/channel-policyresolveChannelGroupRequireMention
plugin-sdk/channel-lifecyclecreateAccountStatusSink
plugin-sdk/channel-inbound防抖動、提及相符、信封輔助程式
plugin-sdk/channel-send-result回覆結果類型
plugin-sdk/channel-actionscreateMessageToolButtonsSchema, createMessageToolCardSchema
plugin-sdk/channel-targets目標解析/相符輔助程式
plugin-sdk/channel-contract頻道合約類型
plugin-sdk/channel-feedback意見反應/反應連線
Provider 子路徑

| 子路徑 | 主要匯出 | | --- | --- | | plugin-sdk/cli-backend | CLI 後端預設值 + 監看常數 | | plugin-sdk/provider-auth | createProviderApiKeyAuthMethod, ensureApiKeyFromOptionEnvOrPrompt, upsertAuthProfile | | plugin-sdk/provider-model-shared | normalizeModelCompat | | plugin-sdk/provider-catalog-shared | findCatalogTemplate, buildSingleProviderApiKeyCatalog | | plugin-sdk/provider-usage | fetchClaudeUsage 及類似內容 | | plugin-sdk/provider-stream | 串流包裝器類型 | | plugin-sdk/provider-onboard | 入門設定修補輔助程式 | | plugin-sdk/global-singleton | 行程本機單例/對映/快取輔助程式 |

驗證與安全性子路徑

| 子路徑 | 主要匯出 | | --- | --- | | plugin-sdk/command-auth | resolveControlCommandGate | | plugin-sdk/allow-from | formatAllowFromLowercase | | plugin-sdk/secret-input | 密鑰輸入解析輔助程式 | | plugin-sdk/webhook-ingress | Webhook 請求/目標輔助程式 | | plugin-sdk/webhook-request-guards | 請求主體大小/逾時輔助程式 |

Runtime and storage subpaths

| Subpath | Key exports | | --- | --- | | plugin-sdk/runtime-store | createPluginRuntimeStore | | plugin-sdk/config-runtime | Config load/write helpers | | plugin-sdk/approval-runtime | Exec and plugin approval helpers | | plugin-sdk/infra-runtime | System event/heartbeat helpers | | plugin-sdk/collection-runtime | Small bounded cache helpers | | plugin-sdk/diagnostic-runtime | Diagnostic flag and event helpers | | plugin-sdk/error-runtime | Error graph and formatting helpers | | plugin-sdk/fetch-runtime | Wrapped fetch, proxy, and pinned lookup helpers | | plugin-sdk/host-runtime | Hostname and SCP host normalization helpers | | plugin-sdk/retry-runtime | Retry config and retry runner helpers | | plugin-sdk/agent-runtime | Agent dir/identity/workspace helpers | | plugin-sdk/directory-runtime | Config-backed directory query/dedup | | plugin-sdk/keyed-async-queue | KeyedAsyncQueue |

Capability and testing subpaths
SubpathKey exports
plugin-sdk/image-generationImage generation provider types
plugin-sdk/media-understandingMedia understanding provider types
plugin-sdk/speechSpeech provider types
plugin-sdk/testinginstallCommonResolveTargetErrorCases, shouldAckReaction

註冊 API

Section titled “註冊 API”

The register(api) callback receives an OpenClawPluginApi object with these methods:

功能註冊

Section titled “功能註冊”
方法註冊內容
api.registerProvider(...)文字推論 (LLM)
api.registerCliBackend(...)本機 CLI 推理後端
api.registerChannel(...)訊息頻道
api.registerSpeechProvider(...)文字轉語音 / STT 合成
api.registerMediaUnderstandingProvider(...)圖像/音訊/視訊分析
api.registerImageGenerationProvider(...)圖像生成
api.registerWebSearchProvider(...)網路搜尋

工具與指令

Section titled “工具與指令”
方法註冊內容
api.registerTool(tool, opts?)Agent tool (required or { optional: true })
api.registerCommand(def)自訂指令（繞過 LLM）

基礎架構

Section titled “基礎架構”
方法註冊內容
api.registerHook(events, handler, opts?)事件掛鉤
api.registerHttpRoute(params)閘道 HTTP 端點
api.registerGatewayMethod(name, handler)閘道 RPC 方法
api.registerCli(registrar, opts?)CLI 子指令
api.registerService(service)背景服務
api.registerInteractiveHandler(registration)互動式處理程序

CLI 註冊元數據

Section titled “CLI 註冊元數據”

api.registerCli(registrar, opts?) 接受兩種頂層元數據：

  • commands：由註冊器擁有的顯式命令根
  • descriptors：用於根 CLI 說明、路由和延遲加載插件 CLI 註冊的解析時命令描述符

如果您希望插件命令在正常的根 CLI 路徑中保持延遲加載狀態， 請提供涵蓋該註冊器暴露的每個頂層命令根的 descriptors。

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

僅當您不需要延遲根 CLI 註冊時，才單獨使用 commands。 該急切相容性路徑仍受支援，但它不會為解析時延遲加載 安裝由描述符支援的佔位符。

CLI 後端註冊

Section titled “CLI 後端註冊”

api.registerCliBackend(...) 允許插件擁有本地 AI CLI 後端（例如 claude-cli 或 codex-cli）的預設配置。

  • 後端 id 會成為模型參考（如 claude-cli/opus）中的提供者前綴。
  • 後端 config 使用與 agents.defaults.cliBackends.<id> 相同的形狀。
  • 用戶配置優先。OpenClaw 會在運行 CLI 之前將 agents.defaults.cliBackends.<id> 合併到 插件預設配置之上。
  • 當後端在合併後需要相容性重寫時（例如標準化舊的標誌形狀）， 請使用 normalizeConfig。

獨佔槽位

Section titled “獨佔槽位”
方法註冊內容
api.registerContextEngine(id, factory)上下文引擎（一次啟用一個）
api.registerMemoryPromptSection(builder)記憶提示區段構建器
api.registerMemoryFlushPlan(resolver)記憶刷新計劃解析器
api.registerMemoryRuntime(runtime)記憶運行時適配器

記憶嵌入適配器

Section titled “記憶嵌入適配器”
方法註冊內容
api.registerMemoryEmbeddingProvider(adapter)用於活動插件的記憶嵌入適配器
  • registerMemoryPromptSection、registerMemoryFlushPlan 和 registerMemoryRuntime 是記憶插件專用的。
  • registerMemoryEmbeddingProvider 讓使用中的記憶體插件註冊一個或多個嵌入介面卡 ID（例如 openai、gemini 或自訂的插件定義 ID）。
  • 使用者設定（如 agents.defaults.memorySearch.provider 和 agents.defaults.memorySearch.fallback）會根據這些已註冊的介面卡 ID 進行解析。

事件與生命週期

Section titled “事件與生命週期”
方法用途
api.on(hookName, handler, opts?)型別化生命週期鉤子
api.onConversationBindingResolved(handler)對話綁定回呼

鉤子決定語意

Section titled “鉤子決定語意”
  • before_tool_call：傳回 { block: true } 即為終止。一旦有任何處理程式設定了該值，優先順序較低的處理程式將會被跳過。
  • before_tool_call：傳回 { block: false } 被視為無決定（等同於省略 block），而非覆寫。
  • before_install：傳回 { block: true } 即為終止。一旦有任何處理程式設定了該值，優先順序較低的處理程式將會被跳過。
  • before_install：傳回 { block: false } 被視為無決定（等同於省略 block），而非覆寫。
  • message_sending：傳回 { cancel: true } 即為終止。一旦有任何處理程式設定了該值，優先順序較低的處理程式將會被跳過。
  • message_sending：傳回 { cancel: false } 被視為無決定（等同於省略 cancel），而非覆寫。

API 物件欄位

Section titled “API 物件欄位”
欄位型別描述
api.idstring插件 ID
api.namestring顯示名稱
api.versionstring?插件版本（選填）
api.descriptionstring?插件描述（選填）
api.sourcestring插件來源路徑
api.rootDirstring?插件根目錄（選填）
api.configOpenClawConfig目前的設定快照
api.pluginConfigRecord<string, unknown>來自 plugins.entries.<id>.config 的外掛程式專屬設定
api.runtimePluginRuntimeRuntime helpers
api.loggerPluginLogger範圍日誌記錄器 (debug, info, warn, error)
api.registrationModePluginRegistrationMode"full", "setup-only", "setup-runtime", 或 "cli-metadata"
api.resolvePath(input)(string) => string解析相對於外掛程式根目錄的路徑

內部模組慣例

Section titled “內部模組慣例”

在您的外掛程式中，請使用本地 barrel 檔案進行內部匯入：

my-plugin/
  api.ts            # Public exports for external consumers
  runtime-api.ts    # Internal-only runtime exports
  index.ts          # Plugin entry point
  setup-entry.ts    # Lightweight setup-only entry (optional)

相關

Section titled “相關”