Plugin 設定與組態

Plugin 封裝（package.json 中繼資料）、清單（openclaw.plugin.json）、設定項目與設定結構描述的參考。

# 套件中繼資料

你的 package.json 需要一個 openclaw 欄位，用來告訴 Plugin 系統你的 Plugin 提供什麼：

{
  "name": "@myorg/openclaw-my-channel",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "blurb": "Short description of the channel."
    }
  }
}

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}

# openclaw 欄位

# openclaw.channel

openclaw.channel 是低成本的套件中繼資料，用於在執行階段載入前探索頻道與顯示設定介面。

範例：

{
  "openclaw": {
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "selectionLabel": "My Channel (self-hosted)",
      "detailLabel": "My Channel Bot",
      "docsPath": "/channels/my-channel",
      "docsLabel": "my-channel",
      "blurb": "Webhook-based self-hosted chat integration.",
      "order": 80,
      "aliases": ["mc"],
      "preferOver": ["my-channel-legacy"],
      "selectionDocsPrefix": "Guide:",
      "selectionExtras": ["Markdown"],
      "markdownCapable": true,
      "exposure": {
        "configured": true,
        "setup": true,
        "docs": true
      },
      "quickstartAllowFrom": true
    }
  }
}

exposure 支援：

• configured：將頻道包含在已設定/狀態樣式的清單介面中
• setup：將頻道包含在互動式設定/組態選擇器中
• docs：將頻道標記為在文件/導覽介面中公開顯示

# openclaw.install

openclaw.install 是套件中繼資料，不是清單中繼資料。

{
  "openclaw": {
    "install": {
      "npmSpec": "@wecom/[email protected]",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}

# 延後完整載入

頻道 Plugin 可以使用下列設定選擇延後載入：

{
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

啟用後，即使是已設定的頻道，OpenClaw 在監聽前啟動階段也只會載入 setupEntry。完整進入點會在 Gateway 開始監聽後載入。

如果你的設定/完整進入點會註冊 Gateway RPC 方法，請將它們放在 Plugin 專屬前綴下。保留的核心管理命名空間（config.*、exec.approvals.*、wizard.*、update.*）仍由核心擁有，並且一律解析為 operator.admin。

# Plugin 清單

每個原生 Plugin 都必須在套件根目錄隨附 openclaw.plugin.json。OpenClaw 會使用它在不執行 Plugin 程式碼的情況下驗證設定。

{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "Adds My Plugin capabilities to OpenClaw",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "webhookSecret": {
        "type": "string",
        "description": "Webhook verification secret"
      }
    }
  }
}

對於頻道 Plugin，請加入 kind 與 channels：

{
  "id": "my-channel",
  "kind": "channel",
  "channels": ["my-channel"],
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

即使 Plugin 沒有設定，也必須隨附結構描述。空結構描述是有效的：

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

完整結構描述參考請見 Plugin manifest。

# ClawHub 發布

對於 Plugin 套件，請使用套件專屬的 ClawHub 指令：

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin

# 設定入口

setup-entry.ts 檔案是 index.ts 的輕量替代方案，OpenClaw 只需要設定介面時會載入它（初始設定、設定修復、停用頻道檢查）。

// setup-entry.ts


export default defineSetupPluginEntry(myChannelPlugin);

這可避免在設定流程期間載入繁重的執行階段程式碼（加密函式庫、CLI 註冊、背景服務）。

將設定安全匯出保留在 sidecar 模組中的內建工作區頻道，可以使用來自 openclaw/plugin-sdk/channel-entry-contract 的 defineBundledChannelSetupEntry(...)，而不是 defineSetupPluginEntry(...)。該內建合約也支援選用的 runtime 匯出，因此設定期間的執行階段接線可以保持輕量且明確。

# 窄範圍設定輔助匯入

對於熱門的純設定路徑，若你只需要設定介面的一部分，請優先使用窄範圍設定輔助接縫，而不是較廣的 plugin-sdk/setup 總括匯入：

當你需要完整共用設定工具箱時，請使用較廣的 plugin-sdk/setup 接縫，包括 moveSingleAccountChannelSectionToDefaultAccount(...) 這類設定修補輔助工具。

設定修補配接器在匯入時保持熱門路徑安全。它們內建的單帳號提升合約介面查找是惰性的，因此匯入 plugin-sdk/setup-runtime 不會在配接器實際使用前急切載入內建合約介面探索。

# 頻道擁有的單帳號提升

當頻道從單帳號頂層設定升級到 channels.<id>.accounts.* 時，預設的共用行為是將提升後的帳號範圍值移入 accounts.default。

內建頻道可以透過其設定合約介面縮窄或覆寫該提升：

• singleAccountKeysToMove：應移入提升帳號的額外頂層鍵
• namedAccountPromotionKeys：當具名帳號已存在時，只有這些鍵會移入提升帳號；共用政策／遞送鍵會保留在頻道根層
• resolveSingleAccountPromotionTarget(...)：選擇哪個現有帳號接收提升值

# 設定結構描述

Plugin 設定會依據 manifest 中的 JSON Schema 驗證。使用者可透過以下方式設定 Plugin：

{
  plugins: {
    entries: {
      "my-plugin": {
        config: {
          webhookSecret: "abc123",
        },
      },
    },
  },
}

你的 Plugin 會在註冊期間以 api.pluginConfig 接收此設定。

對於頻道專屬設定，請改用頻道設定區段：

{
  channels: {
    "my-channel": {
      token: "bot-token",
      allowFrom: ["user1", "user2"],
    },
  },
}

# 建立頻道設定結構描述

使用 buildChannelConfigSchema 將 Zod schema 轉換為 Plugin 擁有的設定成品所使用的 ChannelConfigSchema 包裝器：

const accountSchema = z.object({
  token: z.string().optional(),
  allowFrom: z.array(z.string()).optional(),
  accounts: z.object({}).catchall(z.any()).optional(),
  defaultAccount: z.string().optional(),
});

const configSchema = buildChannelConfigSchema(accountSchema);

如果你已經將合約撰寫為 JSON Schema 或 TypeBox，請使用直接輔助工具，讓 OpenClaw 可在中繼資料路徑上略過 Zod 到 JSON Schema 的轉換：

const configSchema = buildJsonChannelConfigSchema(
  Type.Object({
    token: Type.Optional(Type.String()),
    allowFrom: Type.Optional(Type.Array(Type.String())),
  }),
);

對於第三方 Plugin，冷路徑合約仍是 Plugin manifest：將產生的 JSON Schema 鏡像到 openclaw.plugin.json#channelConfigs，讓設定結構描述、設定和 UI 介面可在不載入執行階段程式碼的情況下檢查 channels.<id>。

# 設定精靈

頻道 Plugin 可為 openclaw onboard 提供互動式設定精靈。精靈是 ChannelPlugin 上的 ChannelSetupWizard 物件：

const setupWizard: ChannelSetupWizard = {
  channel: "my-channel",
  status: {
    configuredLabel: "Connected",
    unconfiguredLabel: "Not configured",
    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
  },
  credentials: [
    {
      inputKey: "token",
      providerHint: "my-channel",
      credentialLabel: "Bot token",
      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
      keepPrompt: "Keep current token?",
      inputPrompt: "Enter your bot token:",
      inspect: ({ cfg, accountId }) => {
        const token = (cfg.channels as any)?.["my-channel"]?.token;
        return {
          accountConfigured: Boolean(token),
          hasConfiguredValue: Boolean(token),
        };
      },
    },
  ],
};

ChannelSetupWizard 型別支援 credentials、textInputs、dmPolicy、allowFrom、groupAccess、prepare、finalize 等。完整範例請參閱內建 Plugin 套件（例如 Discord Plugin 的 src/channel.setup.ts）。

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";

const setupSurface = createOptionalChannelSetupSurface({
  channel: "my-channel",
  label: "My Channel",
  npmSpec: "@myorg/openclaw-my-channel",
  docsPath: "/channels/my-channel",
});
// Returns { setupAdapter, setupWizard }

# 發布與安裝

**外部 Plugin：**發布到 ClawHub，然後安裝：

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

儲存庫內 Plugin： 放在隨附的 Plugin 工作區樹狀結構下，它們會在建置期間自動被探索。

使用者可以安裝：

openclaw plugins install <package-name>

隨附套件中繼資料是明確定義的，不會在 Gateway 啟動時從已建置的 JavaScript 推斷。執行階段依賴項應屬於擁有它們的 Plugin 套件；已封裝的 OpenClaw 啟動程序絕不會修復或鏡像 Plugin 依賴項。

# 相關

• 建置 Plugin — 逐步入門指南
• Plugin manifest — 完整 manifest schema 參考
• SDK 進入點 — definePluginEntry 和 defineChannelPluginEntry