Plugin SDK 概覽

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.

​

匯入慣例

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

​

子路徑參考

​

註冊 API

​

能力註冊

​

工具與命令

​

基礎設施

​

工作流程 Plugin 的主機 Hook

• 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(...)

• 外部 plugins 可以擁有工作階段擴充、UI 描述器、命令、工具中繼資料、下一輪注入，以及一般 hooks。
• 受信任的工具政策會先於一般 before_tool_call hooks 執行，且僅限內建，因為它們參與主機安全政策。
• 保留命令所有權僅限內建。外部 plugins 應使用自己的命令名稱或別名。
• allowPromptInjection=false 會停用會變更提示的 hooks，包括 agent_turn_prepare、before_prompt_build、heartbeat_prompt_contribution、 舊版 before_agent_start 的提示欄位，以及 enqueueNextTurnInjection。

​

Gateway 探索註冊

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

​

CLI 註冊中繼資料

• commands：由註冊器擁有的明確命令名稱
• descriptors：用於 CLI 說明、 路由，以及延遲 plugin CLI 註冊的解析時命令描述器
• 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,
      },
    ],
  },
);

​

CLI 後端註冊

• 後端 id 會成為模型參照中的提供者前綴，例如 codex-cli/gpt-5。
• 後端 config 使用與 agents.defaults.cliBackends.<id> 相同的形狀。
• 使用者設定仍會優先。OpenClaw 會先將 agents.defaults.cliBackends.<id> 合併到 plugin 預設值上，再執行 CLI。
• 當後端需要在合併後進行相容性重寫時，請使用 normalizeConfig （例如將舊旗標形狀正規化）。
• 對於屬於 CLI 方言的請求範圍 argv 重寫，請使用 resolveExecutionArgs， 例如將 OpenClaw 思考層級對應到原生 effort 旗標。

​

專屬插槽

​

記憶嵌入配接器

• registerMemoryCapability 是首選的專屬記憶 plugin API。
• registerMemoryCapability 也可以公開 publicArtifacts.listArtifacts(...)， 讓配套 plugins 能透過 openclaw/plugin-sdk/memory-host-core 使用匯出的記憶成品，而不是深入特定 記憶 plugin 的私有版面。
• registerMemoryPromptSection、registerMemoryFlushPlan 和 registerMemoryRuntime 是舊版相容的專屬記憶 plugin API。
• MemoryFlushPlan.model 可以將清除輪次釘選到精確的 provider/model 參照，例如 ollama/qwen3:8b，而不繼承作用中的後援 鏈。
• registerMemoryEmbeddingProvider 可讓作用中的記憶 plugin 註冊一個或多個嵌入配接器 ID（例如 openai、gemini，或自訂 plugin 定義的 ID）。
• 使用者設定（例如 agents.defaults.memorySearch.provider 和 agents.defaults.memorySearch.fallback）會依據那些已註冊的 配接器 ID 解析。

​

事件與生命週期

​

Hook 決策語意

• before_tool_call：回傳 { block: true } 是終止性決策。一旦任何處理器設定它，較低優先序的處理器就會被略過。
• before_tool_call：回傳 { block: false } 會被視為沒有決策（等同於省略 block），而不是覆寫。
• before_install：回傳 { block: true } 是終止性決策。一旦任何處理器設定它，較低優先序的處理器就會被略過。
• before_install：回傳 { block: false } 會被視為沒有決策（等同於省略 block），而不是覆寫。
• reply_dispatch：回傳 { handled: true, ... } 是終止性決策。一旦任何處理器宣告已分派，較低優先序的處理器和預設模型分派路徑就會被略過。
• message_sending：回傳 { cancel: true } 是終止性決策。一旦任何處理器設定它，較低優先序的處理器就會被略過。
• message_sending：回傳 { cancel: false } 會被視為沒有決策（等同於省略 cancel），而不是覆寫。
• message_received：當你需要傳入 thread/topic 路由時，請使用型別化的 threadId 欄位。將 metadata 保留給通道專屬的額外資料。
• message_sending：先使用型別化的 replyToId / threadId 路由欄位，再退回到通道專屬的 metadata。
• gateway_start：使用 ctx.config、ctx.workspaceDir 和 ctx.getCron?.() 取得 gateway 擁有的啟動狀態，而不是依賴內部 gateway:startup hooks。
• cron_changed：觀察 gateway 擁有的 cron 生命週期變更。同步外部喚醒排程器時，請使用 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 匯出 provider builder、 default-model 輔助工具與 realtime provider builder。
• @openclaw/openrouter-provider：api.ts 匯出 provider builder 以及 onboarding/設定輔助工具。

​

相關