插件设置与配置

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

包元数据

您的 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` 字段

入口点文件（相对于包根目录）。轻量级仅设置入口（可选）。用于设置、选择器、快速入门和状态界面的渠道目录元数据。此插件注册的提供者 ID。安装提示：`npmSpec`、`localPath`、`defaultChoice`、`minHostVersion`、`expectedIntegrity`、`allowInvalidConfigRecovery`。启动行为标志。

`openclaw.channel`

openclaw.channel 是用于在运行时加载之前进行渠道发现和设置界面的廉价包元数据。

字段	类型	含义
`id`	`string`	规范渠道 ID。
`label`	`string`	主要渠道标签。
`selectionLabel`	`string`	当应与 `label` 不同时的选择器/设置标签。
`detailLabel`	`string`	次要详情标签，用于更丰富的渠道目录和状态界面。
`docsPath`	`string`	设置和选择链接的文档路径。
`docsLabel`	`string`	覆盖用于文档链接的标签，当其应与渠道 ID 不同时使用。
`blurb`	`string`	简短的新手引导/目录描述。
`order`	`number`	在渠道目录中的排序顺序。
`aliases`	`string[]`	用于渠道选择的额外查找别名。
`preferOver`	`string[]`	此渠道应排名在前的较低优先级插件/渠道 ID。
`systemImage`	`string`	用于渠道 UI 目录的可选图标/系统图像名称。
`selectionDocsPrefix`	`string`	在选择界面中文档链接前的前缀文本。
`selectionDocsOmitLabel`	`boolean`	在选中内容的复制中直接显示文档路径，而不是带标签的文档链接。
`selectionExtras`	`string[]`	附加在选中内容复制中的额外短字符串。
`markdownCapable`	`boolean`	将渠道标记为支持 Markdown，以便进行出站格式化决策。
`exposure`	`object`	针对设置、已配置列表和文档界面的渠道可见性控制。
`quickstartAllowFrom`	`boolean`	选择此渠道加入标准快速入门 `allowFrom` 设置流程。
`forceAccountBinding`	`boolean`	即使只存在一个帐户，也需要显式进行帐户绑定。
`preferSessionLookupForAnnounceTarget`	`boolean`	在解析此渠道的通知目标时，首选会话查找。

示例：

{
  "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 是包元数据，而非清单元数据。

字段	类型	含义
`clawhubSpec`	`string`	用于安装/更新和新手引导按需安装流程的规范 ClawHub 规范。
`npmSpec`	`string`	用于安装/更新回退流程的规范 npm 规范。
`localPath`	`string`	本地开发或打包安装路径。
`defaultChoice`	`"clawhub"` \| `"npm"` \| `"local"`	当有多个源可用时首选的安装源。
`minHostVersion`	`string`	支持的最低 OpenClaw 版本，格式为 `>=x.y.z` 或 `>=x.y.z-prerelease`。
`expectedIntegrity`	`string`	预期的 npm 分发完整性字符串，通常为 `sha512-...`，用于固定安装。
`allowInvalidConfigRecovery`	`boolean`	允许捆绑插件重新安装流程从特定的配置失效故障中恢复。

新手引导行为

交互式新手引导也对按需安装界面使用 openclaw.installClawHubnpmClawHub。如果你的插件在运行时加载之前公开了提供商身份验证选项或渠道设置/目录元数据，新手引导可以显示该选项，提示进行 ClawHub、npm 或本地安装，安装或启用插件，然后继续所选的流程。ClawHub 新手引导选项使用 clawhubSpecnpm，如果存在则首选；npm 选项需要受信任的目录元数据和注册表 npmSpec；确切版本和 expectedIntegritynpm 是可选的 npm 固定项。如果存在 expectedIntegritynpm，安装/更新流程会对 npm 强制执行它。将“显示什么”的元数据保留在 openclaw.plugin.json 中，将“如何安装它”的元数据保留在 package.json 中。

minHostVersion 强制执行

如果设置了 minHostVersion，安装和非捆绑的清单注册表加载都会强制执行它。较旧的主机会跳过外部插件；无效的版本字符串将被拒绝。捆绑的源插件被假定与主机检出版本一致。

npm固定的 npm 安装

对于固定的 npm 安装，请在 npmSpec 中保留确切版本并添加预期的产物完整性：

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

allowInvalidConfigRecovery scope

allowInvalidConfigRecovery 并非针对损坏配置的通用绕过方法。它仅用于特定的捆绑插件恢复，以便重新安装/设置可以修复已知的升级遗留问题，例如缺少的捆绑插件路径或该插件的陈旧 `channels.

条目。如果配置因无关原因损坏，安装仍然会失败并提示操作员运行openclaw doctor —fix`。

延迟完全加载

渠道插件可以选择通过以下方式启用延迟加载：

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

启用后，OpenClaw 在预监听启动阶段仅加载 OpenClawsetupEntry，即使是针对已配置的渠道也是如此。完整条目将在网关开始监听后加载。

如果您的设置/完整条目注册了网关 RPC 方法，请将它们保留在特定于插件的前缀上。保留的核心管理命名空间（RPCconfig.*、exec.approvals.*、wizard.*、update.*）保持核心所有，并始终解析为 operator.admin。

插件清单

每个原生插件必须在包根目录中附带一个 openclaw.plugin.jsonOpenClaw。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": {}
  }
}

即使没有配置的插件也必须附带一个架构。空架构是有效的：

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

有关完整的架构参考，请参阅插件清单。

ClawHub 发布

对于插件包，请使用特定的 ClawHub 命令：

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

设置入口

setup-entry.ts 文件是 index.ts 的轻量级替代方案，当 OpenClaw 仅需要设置界面（新手引导、配置修复、禁用的渠道检查）时会加载它。

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

export default defineSetupPluginEntry(myChannelPlugin);

这可以避免在设置流程中加载繁重的运行时代码（加密库、CLI 注册、后台服务）。

如果打包的工作区渠道将设置安全的导出保留在辅助模块中，则可以使用 openclaw/plugin-sdk/channel-entry-contract 中的 defineBundledChannelSetupEntry(...) 来代替 defineSetupPluginEntry(...)。该打包合约还支持可选的 runtime 导出，以便设置时的运行时连接保持轻量和显式。

当 OpenClaw 使用 setupEntry 而不是完整入口时

渠道已禁用但需要设置/新手引导界面。
渠道已启用但未配置。
延迟加载已启用 (deferConfiguredChannelFullLoadUntilAfterListen)。

setupEntry 必须注册的内容

渠道插件对象（通过 defineSetupPluginEntry）。
网关监听之前所需的任何 HTTP 路由。
启动期间所需的任何网关方法。

这些启动网关方法仍应避免使用保留的核心管理员命名空间，例如 config.* 或 update.*。

setupEntry 不应包含的内容

CLI 注册。
后台服务。
繁重的运行时导入（加密、SDK）。
仅在启动后需要的 Gateway(网关) 方法。

精确的设置辅助导入

对于仅用于热设置的路径，当您只需要设置界面的一部分时，最好使用精确的设置辅助接口，而不是更广泛的 plugin-sdk/setup 覆盖范围：

导入路径	用于	主要导出
`plugin-sdk/setup-runtime`	在 `setupEntry` / 延迟渠道启动中保持可用的设置时运行时辅助工具	`createSetupTranslator`、`createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`、`noteChannelLookupFailure`、`noteChannelLookupSummary`、`promptResolvedAllowFrom`、`splitSetupEntries`、`createAllowlistSetupWizardProxy`、`createDelegatedSetupWizardProxy`
`plugin-sdk/setup-adapter-runtime`	已弃用的兼容性别名；请使用 `plugin-sdk/setup-runtime`	`createEnvPatchedAccountSetupAdapter`
`plugin-sdk/setup-tools`	setup/install CLI/archive/docs helpers	`formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR`

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

使用 createSetupTranslator(...)CLI 获取固定的设置向导副本。它遵循 CLI 向导区域设置（OPENCLAW_LOCALE，然后是系统区域设置变量），并回退到英语。请将插件特定的设置文本保留在插件拥有的代码中，并仅对通用设置标签、状态文本和官方捆绑插件设置副本使用共享目录键。

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

渠道拥有的单帐户提升

当渠道从单帐户顶级配置升级到 channels.<id>.accounts.* 时，默认的共享行为是将提升的帐户作用域值移动到 accounts.default 中。

捆绑渠道可以通过其设置合约表面缩小或覆盖该提升行为：

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

配置架构

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

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

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

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

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

构建渠道配置架构

使用 buildChannelConfigSchema 将 Zod 架构转换为插件拥有的配置工件所使用的 ChannelConfigSchema 包装器：

import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

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 的转换：

import { Type } from "typebox";
import { buildJsonChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-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 对象：

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

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）。

Shared allowFrom prompts

对于只需要标准 note -> prompt -> parse -> merge -> patch 流程的私信允许列表提示，建议使用 openclaw/plugin-sdk/setup 中的共享设置辅助程序：createPromptParsedAllowFromForAccount(...)、createTopLevelChannelParsedAllowFromPrompt(...) 和 createNestedChannelParsedAllowFromPrompt(...)。

Standard 渠道 setup status

对于仅在标签、评分和可选额外行上有所不同的渠道设置状态块，建议使用 openclaw/plugin-sdk/setup 中的 createStandardChannelSetupStatus(...)，而不是在每个插件中手动构建相同的 status 对象。

Optional 渠道 setup surface

对于应仅出现在特定上下文中的可选设置界面，请使用 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",
});
// Returns { setupAdapter, setupWizard }

当您只需要该可选安装界面的一半时，plugin-sdk/channel-setup 还会暴露较低级别的 createOptionalChannelSetupAdapter(...) 和 createOptionalChannelSetupWizard(...) 构建器。

生成的可选适配器/向导在真实配置写入时处于“失败关闭”状态。它们在 validateInput、applyAccountConfig 和 finalize 之间重用一条“需要安装”的消息，并在设置了 docsPath 时附加文档链接。

二进制支持设置助手

对于基于二进制的设置 UI，优先使用共享的委托助手，而不是将相同的二进制/状态粘合代码复制到每个渠道中：

createDetectedBinaryStatus(...) 用于仅标签、提示、分数和二进制检测不同的状态块
createCliPathTextInput(...) 用于基于路径的文本输入
createDelegatedSetupWizardStatusResolvers(...)、createDelegatedPrepare(...)、createDelegatedFinalize(...) 和 createDelegatedResolveConfigured(...) 当 setupEntry 需要懒惰地转发到更重的完整向导时
createDelegatedTextInputShouldPrompt(...) 当 setupEntry 仅需要委托 textInputs[*].shouldPrompt 决策时

发布与安装

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

openclaw plugins install @myorg/openclaw-my-plugin

纯包规范在启动切换期间从 npm 安装。

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

当包尚未迁移至 npm，或者您在迁移期间需要直接的 ClawHub 安装路径时，请使用 npm：

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

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

用户可以安装：

openclaw plugins install <package-name>

打包的包元数据是显式的，而不是在 Gateway(网关) 启动时从构建的 JavaScript 推断的。运行时依赖属于拥有它们的插件包；打包的 OpenClaw 启动永远不会修复或镜像插件依赖。