插件打包与配置（Setup and Config）

本页是插件打包（package.json 元数据）、manifest（openclaw.plugin.json）、setup entry 和 config schema 的参考文档。

提示： 在找操作指南？ 各操作指南中包含了打包的上下文示例：渠道插件和 Provider 插件。

包元数据

你的 package.json 需要一个 openclaw 字段，告诉插件系统你的插件提供了什么：

渠道插件：

{
  "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": "渠道的简短描述。"
    }
  }
}

Provider 插件：

{
  "name": "@myorg/openclaw-my-provider",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "providers": ["my-provider"]
  }
}

openclaw 字段说明

字段	类型	描述
extensions	string[]	入口文件（相对于包根目录）
setupEntry	string	轻量级 setup-only 入口（可选）
channel	object	渠道元数据：id、label、blurb、selectionLabel、docsPath、order、aliases
providers	string[]	此插件注册的 Provider ID
install	object	安装提示：npmSpec、localPath、defaultChoice
startup	object	启动行为标志

延迟全量加载

渠道插件可以通过以下配置启用延迟加载：

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

启用后，即使渠道已配置，OpenClaw 在监听前的启动阶段也只加载 setupEntry。完整入口在 gateway 开始监听后才加载。

警告： 仅在你的 setupEntry 能在 gateway 开始监听前注册所有必要内容（渠道注册、HTTP 路由、gateway 方法）时，才启用延迟加载。如果完整入口拥有必要的启动能力，请保持默认行为。

Plugin Manifest

每个原生插件必须在包根目录下提供 openclaw.plugin.json。OpenClaw 使用它在不执行插件代码的情况下校验配置。

{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "为 OpenClaw 添加 My Plugin 能力",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "webhookSecret": {
        "type": "string",
        "description": "Webhook 验证密钥"
      }
    }
  }
}

渠道插件还需要添加 kind 和 channels：

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

即使没有任何配置的插件也必须提供 schema。空 schema 是有效的：

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

完整 schema 参考见 Plugin Manifest。

Setup Entry

setup-entry.ts 是 index.ts 的轻量级替代，当 OpenClaw 只需要 setup 接口（引导、配置修复、已禁用渠道检查）时会加载它。

// setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
import { myChannelPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(myChannelPlugin);

这样可以避免在安装流程中加载重型运行时代码（加密库、CLI 注册、后台服务）。

OpenClaw 在什么情况下使用 setupEntry 而非完整入口：

• 渠道已禁用，但需要 setup/引导接口
• 渠道已启用，但未配置
• 启用了延迟加载（deferConfiguredChannelFullLoadUntilAfterListen）

setupEntry 必须注册的内容：

• 渠道插件对象（通过 defineSetupPluginEntry）
• gateway 监听前需要的任何 HTTP 路由
• 启动期间需要的任何 gateway 方法

setupEntry 不应包含的内容：

• CLI 注册
• 后台服务
• 重型运行时导入（加密库、SDK）
• 仅在启动后需要的 gateway 方法

Config Schema

插件配置会根据 manifest 中的 JSON Schema 进行校验。用户通过以下方式配置插件：

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

你的插件在注册期间通过 api.pluginConfig 接收此配置。

对于渠道专属配置，使用渠道配置部分：

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

构建渠道 config schema

使用 openclaw/plugin-sdk/core 中的 buildChannelConfigSchema 将 Zod schema 转换为 OpenClaw 校验所需的 ChannelConfigSchema 包装器：

import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/core";

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);

Setup Wizard（安装向导）

渠道插件可以为 openclaw onboard 提供交互式安装向导。向导是 ChannelPlugin 上的 ChannelSetupWizard 对象：

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

const setupWizard: ChannelSetupWizard = {
  channel: "my-channel",
  status: {
    configuredLabel: "已连接",
    unconfiguredLabel: "未配置",
    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: "是否使用环境变量 MY_CHANNEL_BOT_TOKEN？",
      keepPrompt: "保留当前 token？",
      inputPrompt: "请输入你的 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 等。完整示例见内置插件（如 extensions/discord/src/channel.setup.ts）。

对于只需要标准 note -> prompt -> parse -> merge -> patch 流程的 DM 白名单提示，优先使用 openclaw/plugin-sdk/setup 中的共享 setup 辅助工具：createPromptParsedAllowFromForAccount(...)、createTopLevelChannelParsedAllowFromPrompt(...) 和 createNestedChannelParsedAllowFromPrompt(...)。

对于只在标签、评分和可选额外行上有区别的渠道 setup 状态块，优先使用 openclaw/plugin-sdk/setup 中的 createStandardChannelSetupStatus(...) 而非在每个插件中手动编写相同的 status 对象。

对于只应在某些上下文中出现的可选 setup 接口，使用 openclaw/plugin-sdk/channel-setup 中的 createOptionalChannelSetupSurface：

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",
});
// 返回 { setupAdapter, setupWizard }

发布与安装

外部插件： 发布到 ClawHub 或 npm，然后安装：

openclaw plugins install @myorg/openclaw-my-plugin

OpenClaw 会优先尝试 ClawHub，如未找到自动回退到 npm。也可以强制指定来源：

openclaw plugins install clawhub:@myorg/openclaw-my-plugin   # 仅 ClawHub
openclaw plugins install npm:@myorg/openclaw-my-plugin       # 仅 npm

仓库内插件： 放在 extensions/ 目录下，构建时会自动发现。

用户可以浏览和安装：

openclaw plugins search <query>
openclaw plugins install <package-name>

信息： 对于通过 npm 安装的情况，openclaw plugins install 运行的是 npm install --ignore-scripts（不执行生命周期脚本）。请保持插件依赖树为纯 JS/TS，避免依赖需要 postinstall 构建的包。

相关链接

• SDK 入口点 — definePluginEntry 和 defineChannelPluginEntry
• Plugin Manifest 规范 — 完整 manifest schema 参考
• 构建插件 — 一步一步的入门指南