插件设置和配置

打包插件（package.json 元数据）、清单（openclaw.plugin.json）、设置入口和配置 schema 的参考。

# 包元数据

你的 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": "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：在已配置/Status 样式的列表界面中包含该渠道
• setup：在交互式设置/配置选择器中包含该渠道
• docs：在文档/导航界面中将该渠道标记为面向公众

# openclaw.install

openclaw.install 是包元数据，不是清单元数据。

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

# 延迟完整加载

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

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

启用后，即使对于已配置的渠道，OpenClaw 在预监听启动阶段也只加载 setupEntry。完整入口会在 Gateway 网关开始监听后加载。

如果你的设置/完整入口注册 Gateway 网关 RPC 方法，请将它们放在插件专属前缀下。保留的核心管理命名空间（config.*、exec.approvals.*、wizard.*、update.*）仍归核心所有，并且始终解析到 operator.admin。

# 插件清单

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

{
  "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"
      }
    }
  }
}

对于渠道插件，添加 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 参考见 插件清单。

# ClawHub 发布

对于插件包，使用包专属的 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 注册、后台服务）。

将设置安全导出保存在旁路模块中的内置工作区渠道，可以使用来自 openclaw/plugin-sdk/channel-entry-contract 的 defineBundledChannelSetupEntry(...)，而不是 defineSetupPluginEntry(...)。该内置契约还支持可选的 runtime 导出，因此设置时的运行时接线可以保持轻量且显式。

# 窄范围设置辅助导入

对于热路径的仅设置路径，如果你只需要设置表面的一部分，请优先使用窄范围设置辅助接缝，而不是更宽泛的 plugin-sdk/setup 总入口：

当你想要完整的共享设置工具箱（包括 moveSingleAccountChannelSectionToDefaultAccount(...) 等配置补丁辅助工具）时，请使用更宽泛的 plugin-sdk/setup 接缝。

设置补丁适配器在导入时保持热路径安全。其内置单账号提升契约表面查找是惰性的，因此导入 plugin-sdk/setup-runtime 不会在适配器实际使用前急切加载内置契约表面发现。

# 渠道拥有的单账号提升

当某个渠道从单账号顶层配置升级到 channels.<id>.accounts.* 时，默认共享行为会将提升后的账号范围值移动到 accounts.default。

内置渠道可以通过它们的设置契约表面缩小或覆盖该提升：

• singleAccountKeysToMove：应移动到提升账号中的额外顶层键
• namedAccountPromotionKeys：当具名账号已存在时，只有这些键会移动到提升账号中；共享策略/投递键保留在渠道根部
• resolveSingleAccountPromotionTarget(...)：选择哪个现有账号接收提升值

# 配置架构

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

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

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

对于渠道特定配置，请改用渠道配置部分：

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

# 构建渠道配置架构

使用 buildChannelConfigSchema 将 Zod 架构转换为插件拥有的配置工件使用的 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())),
  }),
);

对于第三方插件，冷路径契约仍然是插件清单：将生成的 JSON Schema 镜像到 openclaw.plugin.json#channelConfigs，这样配置架构、设置和 UI 表面无需加载运行时代码即可检查 channels.<id>。

# 设置向导

渠道插件可以为 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 等。完整示例请参阅内置插件包（例如 Discord 插件的 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 }

# 发布和安装

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

openclaw plugins install @myorg/openclaw-my-plugin

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

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

仓库内插件： 放在内置插件工作区树下，它们会在构建期间自动被发现。

用户可以安装：

openclaw plugins install <package-name>

内置包元数据是显式的，不会在 Gateway 网关启动时从已构建的 JavaScript 中推断。运行时依赖应放在拥有它们的插件包中；打包版 OpenClaw 启动时绝不会修复或镜像插件依赖。

# 相关内容

• 构建插件 — 分步式入门指南
• 插件清单 — 完整清单 schema 参考
• SDK 入口点 — definePluginEntry 和 defineChannelPluginEntry