外掛 SDK 概覽

​

匯入慣例

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

​

子路徑參考

​

註冊 API

​

能力註冊

​

工具和命令

agentPromptGuidance: [
  "Global command hint.",
  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },
];

​

基礎設施

​

工作流程外掛的主機鉤子

api.session.controls.registerControlUiDescriptor({
  surface: "tab",
  id: "logbook",
  label: "Logbook",
  description: "Your day as a timeline, built from screen snapshots.",
  icon: "sun",
  group: "control",
  requiredScopes: ["operator.write"],
});

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

• 外部外掛可以擁有工作階段擴充、UI 描述元、命令、工具 中繼資料、下一回合注入，以及一般鉤子。
• 受信任工具政策會在一般 before_tool_call 鉤子之前執行，並受到 主機信任。Bundled 政策會先執行；已安裝外掛政策需要 明確啟用，加上其在 contracts.trustedToolPolicies 中的本機 ID， 並會接著依外掛載入順序執行。政策 ID 的範圍限於註冊它的外掛。
• 保留命令擁有權僅限 bundled。外部外掛應使用自己的 命令名稱或別名。
• allowPromptInjection=false 會停用會變更提示的鉤子，包括 agent_turn_prepare、before_prompt_build、heartbeat_prompt_contribution、 舊版 before_agent_start 的提示欄位，以及 enqueueNextTurnInjection。

​

閘道探索註冊

api.registerGatewayDiscoveryService({
  id: "my-discovery",
  async advertise(ctx) {
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
      displayName: ctx.machineDisplayName,
    });
    return { stop: () => handle.stop() };
  },
});

​

命令列介面註冊中繼資料

• commands：註冊器擁有的明確命令名稱
• descriptors：剖析時使用的命令描述元，用於命令列介面說明、 路由和延遲外掛命令列介面註冊
• parentPath：巢狀命令群組的選用父命令路徑，例如 ["nodes"]

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

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Capture or render canvas content from a paired node",
        hasSubcommands: true,
      },
    ],
  },
);

​

命令列介面後端註冊

• 後端 id 會成為模型參照中的供應商前綴，例如 my-cli/gpt-5。
• 後端 config 使用與 agents.defaults.cliBackends.<id> 相同的形狀。
• 使用者設定仍會優先。OpenClaw 會先將 agents.defaults.cliBackends.<id> 合併到 外掛預設值之上，再執行命令列介面。
• 當後端在合併後需要相容性重寫時，請使用 normalizeConfig （例如正規化舊旗標形狀）。
• 對於屬於命令列介面方言的請求範圍 argv 重寫，請使用 resolveExecutionArgs， 例如將 OpenClaw 思考層級對應到原生 effort 旗標。此 hook 會接收 ctx.executionMode；使用 "side-question" 為短暫的 /btw 呼叫新增 後端原生隔離旗標。如果這些旗標 能可靠地停用原本永遠開啟的命令列介面的原生工具，也請宣告 sideQuestionToolMode: "disabled"。

​

專屬插槽

​

已棄用的記憶嵌入配接器

• registerMemoryCapability 是偏好的專屬記憶外掛 API。
• registerMemoryCapability 也可以公開 publicArtifacts.listArtifacts(...)， 讓配套外掛透過 openclaw/plugin-sdk/memory-host-core 使用匯出的記憶成品， 而不是深入特定 記憶外掛的私有版面配置。
• registerMemoryPromptSection、registerMemoryFlushPlan 和 registerMemoryRuntime 是相容舊版的專屬記憶外掛 API。
• MemoryFlushPlan.model 可以將清除回合固定到精確的 provider/model 參照，例如 ollama/qwen3:8b，而不繼承作用中的 fallback 鏈。
• registerMemoryEmbeddingProvider 已棄用。新的嵌入供應商 應使用 api.registerEmbeddingProvider(...) 和 contracts.embeddingProviders。
• 現有的記憶專用供應商在遷移 期間仍會繼續運作，但外掛檢查會將此回報為 非內建外掛的相容性債務。

​

事件與生命週期

​

Hook 決策語意

• before_tool_call：回傳 { block: true } 為終止狀態。一旦任何 handler 設定它，就會略過較低優先順序的 handler。
• before_tool_call：回傳 { block: false } 會被視為沒有決策（與省略 block 相同），而不是覆寫。
• before_install：回傳 { block: true } 為終止狀態。一旦任何 handler 設定它，就會略過較低優先順序的 handler。
• before_install：回傳 { block: false } 會被視為沒有決策（與省略 block 相同），而不是覆寫。
• reply_dispatch：回傳 { handled: true, ... } 為終止狀態。一旦任何 handler 宣告已處理派送，就會略過較低優先順序的 handler 與預設模型派送路徑。
• message_sending：回傳 { cancel: true } 為終止狀態。一旦任何 handler 設定它，就會略過較低優先順序的 handler。
• message_sending：回傳 { cancel: false } 會被視為沒有決策（與省略 cancel 相同），而不是覆寫。
• message_received：當你需要傳入執行緒/主題路由時，請使用型別化 threadId 欄位。保留 metadata 用於通道特定的額外資訊。
• message_sending：在 fallback 到通道特定 metadata 之前，請先使用型別化 replyToId / threadId 路由欄位。
• gateway_start：使用 ctx.config、ctx.workspaceDir 和 ctx.getCron?.() 取得閘道擁有的啟動狀態，而不是依賴內部 gateway:startup hooks。
• cron_changed：觀察閘道擁有的排程生命週期變更。同步外部喚醒排程器時，請使用 event.job?.state?.nextRunAtMs 和 ctx.getCron?.()，並讓 OpenClaw 作為到期檢查與執行的唯一事實來源。

​

API 物件欄位

​

內部模組慣例

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)

• Anthropic：Claude beta-header 和 service_tier 串流輔助工具的公開 api.ts / contract-api.ts 邊界。
• @openclaw/openai-provider：api.ts 匯出供應商建構器、 預設模型輔助工具，以及即時供應商建構器。
• @openclaw/openrouter-provider：api.ts 匯出供應商建構器 加上入門/設定輔助工具。

​

相關內容