Plugin SDK Overview（Plugin SDK 概述）

Plugin SDK Overview

Plugin SDK 是外掛與核心之間的類型合約。本頁是以下內容的參考指南：應該 import 什麼 以及 可以註冊什麼。

在找實作指南？

• 第一次做外掛？從 入門指南 開始
• Channel 外掛？參考 Channel 外掛
• Provider 外掛？參考 Provider 外掛

Import 慣例

一律從具體 subpath import：

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

每個 subpath 都是小型、自包含的模組。這樣可以保持啟動速度快，並防止循環依賴問題。

Subpath 參考

最常見的 subpath，按用途分組。完整的 100+ subpath 清單在 scripts/lib/plugin-sdk-entrypoints.json。

Plugin entry

Subpath	主要 Export
plugin-sdk/plugin-entry	definePluginEntry
plugin-sdk/core	defineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema

Channel subpath

Subpath	主要 Export
plugin-sdk/channel-setup	createOptionalChannelSetupSurface
plugin-sdk/channel-pairing	createChannelPairingController
plugin-sdk/channel-reply-pipeline	createChannelReplyPipeline
plugin-sdk/channel-config-helpers	createHybridChannelConfigAdapter
plugin-sdk/channel-config-schema	Channel config schema 類型
plugin-sdk/channel-policy	resolveChannelGroupRequireMention
plugin-sdk/channel-lifecycle	createAccountStatusSink
plugin-sdk/channel-inbound	Debounce、mention matching、envelope 輔助函式
plugin-sdk/channel-send-result	Reply result 類型
plugin-sdk/channel-actions	createMessageToolButtonsSchema, createMessageToolCardSchema
plugin-sdk/channel-targets	Target 解析／匹配輔助函式
plugin-sdk/channel-contract	Channel contract 類型
plugin-sdk/channel-feedback	Feedback／reaction 配線

Provider subpath

Subpath	主要 Export
plugin-sdk/provider-auth	createProviderApiKeyAuthMethod, ensureApiKeyFromOptionEnvOrPrompt, upsertAuthProfile
plugin-sdk/provider-models	normalizeModelCompat
plugin-sdk/provider-catalog	Catalog type 重新 export
plugin-sdk/provider-usage	fetchClaudeUsage 及類似函式
plugin-sdk/provider-stream	Stream wrapper 類型
plugin-sdk/provider-onboard	Onboarding config patch 輔助函式

Auth and security subpath

Subpath	主要 Export
plugin-sdk/command-auth	resolveControlCommandGate
plugin-sdk/allow-from	formatAllowFromLowercase
plugin-sdk/secret-input	Secret input 解析輔助函式
plugin-sdk/webhook-ingress	Webhook request／target 輔助函式

Runtime and storage subpath

Subpath	主要 Export
plugin-sdk/runtime-store	createPluginRuntimeStore
plugin-sdk/config-runtime	Config 載入／寫入輔助函式
plugin-sdk/infra-runtime	System event／heartbeat 輔助函式
plugin-sdk/agent-runtime	Agent 目錄／身分／工作區輔助函式
plugin-sdk/directory-runtime	Config 支持的 directory 查詢／去重
plugin-sdk/keyed-async-queue	KeyedAsyncQueue

Capability and testing subpath

Subpath	主要 Export
plugin-sdk/image-generation	Image generation provider 類型
plugin-sdk/media-understanding	Media understanding provider 類型
plugin-sdk/speech	Speech provider 類型
plugin-sdk/testing	installCommonResolveTargetErrorCases, shouldAckReaction

註冊 API

register(api) 回調函式收到 OpenClawPluginApi 物件，提供這些方法：

能力註冊

方法	註冊內容
api.registerProvider(...)	文字推理（LLM）
api.registerChannel(...)	傳訊頻道
api.registerSpeechProvider(...)	文字轉語音／語音合成
api.registerMediaUnderstandingProvider(...)	圖片／音訊／影片分析
api.registerImageGenerationProvider(...)	圖像生成
api.registerWebSearchProvider(...)	網路搜尋

工具與命令

方法	註冊內容
api.registerTool(tool, opts?)	Agent 工具（必須或 { optional: true } ）
api.registerCommand(def)	自訂命令（繞過 LLM）

基礎設施

方法	註冊內容
api.registerHook(events, handler, opts?)	Event hook
api.registerHttpRoute(params)	Gateway HTTP 端點
api.registerGatewayMethod(name, handler)	Gateway RPC 方法
api.registerCli(registrar, opts?)	CLI 子命令
api.registerService(service)	背景服務
api.registerInteractiveHandler(registration)	Interactive handler

獨佔插槽

方法	註冊內容
api.registerContextEngine(id, factory)	Context engine（一次只能有一個有效）
api.registerMemoryPromptSection(builder)	Memory prompt section builder

事件與生命週期

方法	功能
api.on(hookName, handler, opts?)	類型化生命週期 hook
api.onConversationBindingResolved(handler)	Conversation binding 回調

API 物件欄位

欄位	型別	說明
api.id	string	外掛 id
api.name	string	顯示名稱
api.version	string?	外掛版本（可選）
api.description	string?	外掛說明（可選）
api.source	string	外掛來源路徑
api.rootDir	string?	外掛根目錄（可選）
api.config	OpenClawConfig	目前 config 快照
api.pluginConfig	Record<string, unknown>	外掛特定 config，來自 plugins.entries.<id>.config
api.runtime	PluginRuntime	Runtime 輔助函式
api.logger	PluginLogger	範疇化 logger（debug, info, warn, error）
api.registrationMode	PluginRegistrationMode	"full", "setup-only", 或 "setup-runtime"
api.resolvePath(input)	(string) => string	解析相對於外掛根的路徑

內部模組慣例

在你的外掛內，使用本地 barrel 檔案供內部 import：

my-plugin/
  api.ts            # 為外部消費者匯出的公開 export
  runtime-api.ts    # 僅限內部的 runtime export
  index.ts          # 外掛進入點
  setup-entry.ts    # 輕量級僅 setup 進入點（可選）

絕對不要從生產代碼中透過 openclaw/plugin-sdk/<your-plugin> import 你自己的外掛。改為透過 ./api.ts 或 ./runtime-api.ts 路由內部 import。SDK 路徑僅作為外部合約。

相關

• Entry Points — definePluginEntry 和 defineChannelPluginEntry 選項
• Runtime 輔助函式 — 完整 api.runtime namespace 參考
• Setup 與 Config — 打包、manifests、config schemas
• Testing — 測試工具與 lint 規則
• SDK 遷移 — 從舊有介面遷移
• 外掛內部 — 深度架構與能力模型