本页是 OpenClaw 插件打包配置的完整参考，涵盖 package.json openclaw 字段（extensions/setupEntry/channel/compat/build/install/startup）、manifest 文件结构、setup-entry.ts 轻量入口的设计原则与延迟加载（deferred loading）配置、插件配置 schema（通过 JSON Schema 和 buildChannelConfigSchema），以及 ChannelSetupWizard 的写法和可选安装面辅助工具。养龙虾前，先把包打好。

OpenClaw 插件打包与配置

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

需要实操指导？ 各指南已包含打包上下文：渠道插件开发和 Provider 插件开发第一步均涵盖包和 manifest 配置。

Package 元数据

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

渠道插件：

json

{
  "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 插件 / ClawHub 发布基线：

json

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

发布到 ClawHub 时，compat 和 build 字段必填。

`openclaw` 字段

字段	类型	说明
`extensions`	`string[]`	入口文件（相对于包根目录）
`setupEntry`	`string`	轻量 setup-only 入口（可选）
`channel`	`object`	渠道目录元数据，用于 setup/picker/quickstart/status 面
`providers`	`string[]`	此插件注册的 Provider id
`install`	`object`	安装提示：`npmSpec`、`localPath`、`defaultChoice`、`minHostVersion`、`allowInvalidConfigRecovery`
`startup`	`object`	启动行为标志

`openclaw.channel` 字段

openclaw.channel 是廉价的包元数据，用于渠道发现和 setup 面，在 runtime 加载前读取。

字段	类型	说明
`id`	`string`	规范渠道 id
`label`	`string`	主要渠道标签
`selectionLabel`	`string`	Picker/setup 标签（与 label 不同时使用）
`detailLabel`	`string`	丰富渠道目录和状态面的次要标签
`docsPath`	`string`	setup 和选择链接的文档路径
`blurb`	`string`	简短引导/目录描述
`order`	`number`	渠道目录中的排序顺序
`aliases`	`string[]`	渠道选择的额外别名
`preferOver`	`string[]`	本渠道优先于这些低优先级插件/渠道 id
`markdownCapable`	`boolean`	标记渠道支持 markdown 出站格式化
`exposure`	`object`	渠道在 setup/configured/docs 面的可见性控制
`quickstartAllowFrom`	`boolean`	将渠道纳入标准 quickstart allowFrom 流程

exposure 支持 configured（状态列表）、setup（安装向导）、docs（公开文档面）三个子字段。

示例：

json

{
  "openclaw": {
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "blurb": "基于 Webhook 的自托管聊天集成。",
      "order": 80,
      "markdownCapable": true,
      "exposure": {
        "configured": true,
        "setup": true,
        "docs": true
      },
      "quickstartAllowFrom": true
    }
  }
}

`openclaw.install` 字段

字段	类型	说明
`npmSpec`	`string`	安装/更新流程的规范 npm spec
`localPath`	`string`	本地开发或内置安装路径
`defaultChoice`	`"npm"` \| `"local"`	两者都可用时的首选安装来源
`minHostVersion`	`string`	最低支持的 OpenClaw 版本，格式 `>=x.y.z`
`allowInvalidConfigRecovery`	`boolean`	允许内置插件重装流程从特定的过期配置故障中恢复

延迟完整加载

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

json

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

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

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

Plugin Manifest

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

json

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

渠道插件加 kind 和 channels：

json

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

即使不接受任何配置的插件也必须提供 manifest，空 schema 完全合法：

json

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

完整 manifest 字段参考见 Plugin Manifest。

Setup Entry

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

typescript

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

export default defineSetupPluginEntry(myChannelPlugin);

这样可以避免在 setup 流程中加载繁重的 runtime 代码（加密库、CLI 注册、后台服务）。

OpenClaw 使用 setupEntry 而非完整入口的时机：

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

setupEntry 必须注册的内容：

渠道插件对象（通过 defineSetupPluginEntry）
gateway 监听前所需的 HTTP 路由
启动时所需的 gateway 方法

setupEntry 不应包含的内容：

CLI 注册
后台服务
繁重的 runtime 导入（加密、SDK）
只在启动后才需要的 gateway 方法

窄型 Setup Helper 导入

对于热门 setup-only 路径，优先使用窄型 helper 而非宽泛的 plugin-sdk/setup：

导入路径	用途	关键导出
`plugin-sdk/setup-runtime`	`setupEntry`/延迟渠道启动中的 runtime helper	`createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`、`noteChannelLookupFailure`、`noteChannelLookupSummary`、`promptResolvedAllowFrom`、`splitSetupEntries`、`createAllowlistSetupWizardProxy`、`createDelegatedSetupWizardProxy`
`plugin-sdk/setup-adapter-runtime`	环境感知账号 setup 适配器	`createEnvPatchedAccountSetupAdapter`
`plugin-sdk/setup-tools`	setup/安装 CLI/归档/文档 helper	`formatCliCommand`、`detectBinary`、`extractArchive`、`formatDocsLink`

需要完整 setup 工具箱（包含配置 patch helper 如 moveSingleAccountChannelSectionToDefaultAccount）时，使用宽泛的 plugin-sdk/setup。

setup patch 适配器在热路径上是安全的：其内置的单账号升级合约接口查找是惰性的，导入 plugin-sdk/setup-runtime 不会在适配器实际使用前急切加载合约接口发现。

渠道自有的单账号升级

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

内置渠道可通过其 setup 合约接口缩窄或覆盖该升级策略：

singleAccountKeysToMove：应移入升级账号的额外顶层键
namedAccountPromotionKeys：当命名账号已存在时，只将这些键移入升级账号；共享策略/交付键保留在渠道根
resolveSingleAccountPromotionTarget(...)：选择哪个已有账号接收升级值

Matrix 是当前的内置示例。如果恰好有一个已命名的 Matrix 账号存在，或 defaultAccount 指向非规范键（如 Ops），升级会保留该账号而非创建新的 accounts.default。

Config Schema

插件配置按 manifest 中的 JSON Schema 验证。用户通过以下配置来配置插件：

json5

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

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

渠道特定配置使用渠道配置区块：

json5

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

构建渠道 Config Schema

用 buildChannelConfigSchema（来自 openclaw/plugin-sdk/core）将 Zod schema 转换为 OpenClaw 验证的 ChannelConfigSchema 包装器：

typescript

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 向导

渠道插件可以为 openclaw onboard 提供交互式 setup 向导：

typescript

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 等字段。完整示例参考内置插件包（如 Discord 插件的 src/channel.setup.ts）。

对于只需标准 note → prompt → parse → merge → patch 流程的 DM allowlist 提示，优先使用 plugin-sdk/setup 中的共享 helper：createPromptParsedAllowFromForAccount(...)、createTopLevelChannelParsedAllowFromPrompt(...) 等。

对于可选安装面，使用 plugin-sdk/channel-setup 中的 createOptionalChannelSetupSurface：

typescript

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，然后安装：

bash

openclaw plugins install @myorg/openclaw-my-plugin

OpenClaw 先尝试 ClawHub，失败后自动回退到 npm。也可以强制 ClawHub：

bash

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

ClawHub 发布命令：

bash

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

openclaw plugins install 运行 npm install --ignore-scripts（不执行生命周期脚本）。保持插件依赖树为纯 JS/TS，避免需要 postinstall 构建的包。

常见问题

Q: setupEntry 和 index.ts（完整入口）的职责怎么划分？

A: setupEntry 只注册"渠道禁用/未配置时也需要的最小集合"：渠道插件对象本身（通过 defineSetupPluginEntry）、setup 流程中需要的 HTTP 路由和 gateway 方法。繁重的后台服务、CLI 注册器、SDK 初始化都放完整入口。原则：setupEntry 不引入 runtime 依赖，开机即可加载。

Q: 什么情况下需要开启 deferConfiguredChannelFullLoadUntilAfterListen？

A: 当渠道 runtime 较重（如需要动态编译、大量 SDK 初始化）且 pre-listen 阶段不需要它时，开启延迟加载可以缩短 gateway 启动时间。前提是 setupEntry 已经注册好 gateway 监听前所需的全部内容。如果完整入口有启动必需的内容，不要开启，否则 gateway 可能在完整入口加载完成前就开始处理请求。

Q: 发布插件时 compat.minGatewayVersion 有什么作用？

A: minGatewayVersion 声明插件运行所需的最低 OpenClaw 版本。用户使用旧版 gateway 安装你的插件时，系统会提示版本不兼容并拒绝安装，防止因接口不匹配导致的静默错误。发布到 ClawHub 时此字段必填。

OpenClaw 插件打包与配置 ​

Package 元数据 ​

openclaw 字段 ​

openclaw.channel 字段 ​

openclaw.install 字段 ​

延迟完整加载 ​

Plugin Manifest ​

Setup Entry ​

窄型 Setup Helper 导入 ​

渠道自有的单账号升级 ​

Config Schema ​

构建渠道 Config Schema ​

Setup 向导 ​

发布与安装 ​

相关文档 ​

常见问题 ​

OpenClaw 插件打包与配置

Package 元数据

`openclaw` 字段

`openclaw.channel` 字段

`openclaw.install` 字段

延迟完整加载

Plugin Manifest

Setup Entry

窄型 Setup Helper 导入

渠道自有的单账号升级

Config Schema

构建渠道 Config Schema

Setup 向导

发布与安装

相关文档

常见问题