设置与配置

插件打包参考：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."
    }
  }
}

openclaw 字段¶

extensions string[] (路径)

入口点文件（相对于包根目录）。适用于工作区（workspace）和 git checkout 开发的有效源码入口。

runtimeExtensions string[] (路径)

extensions 对应的已构建 JavaScript 对等文件，OpenClaw 加载已安装的 npm 包时优先使用。源码/构建的解析顺序参见 SDK 入口点。

setupEntry string (路径)

仅用于设置的轻量级入口（可选）。

runtimeSetupEntry string (路径)

setupEntry 对应的已构建 JavaScript 对等文件。要求同时设置 setupEntry。

plugin object (路径)

{ id, label } 回退插件身份标识，用于当插件没有可从中推导出 id 或 label 的 channel/provider 元数据时。

channel object (路径)

供设置、选择器、快速开始和状态界面使用的 channel 目录元数据。

install object (路径)

安装提示：npmSpec、localPath、defaultChoice、minHostVersion、expectedIntegrity、allowInvalidConfigRecovery、requiredPlatformPackages。

startup object (路径)

启动行为标志。

compat object (路径)

此插件支持的 pluginApi 版本范围。ClawHub 对外发布时需要。

openclaw.channel¶

openclaw.channel 是轻量级的包元数据，用于在运行时加载之前呈现 channel 发现和设置界面。

Channel 自有设置字段¶

Channel 插件应通过 defineChannelSetupContract(...) 在运行时代码中定义一次设置字段，并将对应的可序列化投影发布到 openclaw.channel.setup.fields 下。运行时定义会推断插件局部的输入类型，解析引导式和非交互式的值，并让 channel 专属的键不进入核心类型。借助包元数据，openclaw channels add <channel-id> --help 和 openclaw channels add --channel <channel-id> --help 无需加载插件即可仅发现所选 channel 的选项。

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

export const setupContract = defineChannelSetupContract({
  fields: {
    endpoint: {
      kind: "string",
      cli: { flags: "--endpoint <url>", description: "Service endpoint" },
    },
    transport: {
      kind: "choice",
      choices: ["native", "container"],
      cli: { flags: "--transport <kind>", description: "Transport owner" },
    },
  },
  adapter: {
    applyAccountConfig: ({ cfg, input }) => ({
      ...cfg,
      channels: { ...cfg.channels, example: input },
    }),
  },
});

{
  "openclaw": {
    "channel": {
      "id": "example",
      "setup": {
        "fields": [
          {
            "key": "endpoint",
            "kind": "string",
            "cli": { "flags": "--endpoint <url>", "description": "Service endpoint" }
          },
          {
            "key": "transport",
            "kind": "choice",
            "choices": ["native", "container"],
            "cli": { "flags": "--transport <kind>", "description": "Transport owner" }
          }
        ]
      }
    }
  }
}

支持的字段类型为 string、boolean、integer、string-list 和 choice。凭证字段请使用 sensitive: true。每个字段的 key 必须与其长 CLI 标志的驼峰式属性名一致，包括否定形式，例如 apiToken 对应 --api-token。当同时需要肯定形式和 --no-* 形式时，布尔字段可以添加 cli.negatedFlags。channel、account 以及账户显示名 name 仍然是共享控制封装。

对于布尔类型的 useEnv 字段，请将 envVars 设置为插件运行时所需要的一组静态环境变量名。这样，在非交互式 channel 设置中，如果有任何声明的变量为空，会在写入配置前拒绝 --use-env。当列表中的任一变量即可满足要求时（例如内联凭证或文件路径二选一），请设置 envVarMode: "any"。省略 envVars 将保留插件原有的校验行为。

已发布的 setup/ChannelSetupInput 适配器仍可供现有外部插件使用。新插件应暴露 setupContract。当两者同时存在时，OpenClaw 始终优先使用 setupContract。

对于连接检查以及其他需要已保存配置的工作，请使用 afterAccountConfigWritten（或向导的 afterConfigWritten）。OpenClaw 会在写入成功后运行这些回调，并传入从实际写入的文件重新读取的运行时 cfg，同时解析环境引用和插件默认值。保存的文件可以保留 ${VAR} 引用。如果已保存配置缺失或无效，回调将不会执行。回调失败会作为设置后警告报告，而不会撤销已保存的配置。

示例：

{
  "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/wecom-openclaw-plugin@1.2.3",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}

设置时的网关方法¶

如果你的设置/完整入口注册了网关 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"
      }
    }
  }
}

对于渠道插件，请添加 channels（提供商插件则添加 providers）：

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

即使是没有配置的插件也必须附带 schema。空 schema 也是有效的：

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

完整 schema 参考请参阅 插件清单。

设置入口¶

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

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

export default defineSetupPluginEntry(myChannelPlugin);

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

捆绑的工作区渠道如果在 sidecar 模块中保留了设置安全的导出，则可以使用来自 openclaw/plugin-sdk/channel-entry-contract 的 defineBundledChannelSetupEntry(...)，而不是 defineSetupPluginEntry(...)。该捆绑契约还支持可选的 runtime 导出，以便设置时的运行时接线可以保持轻量和明确。

精简设置辅助导入¶

对于仅设置的热路径，当你只需要部分设置界面时，请优先使用精简的设置辅助接缝，而不是更宽泛的 plugin-sdk/setup 总括模块：

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

使用 createSetupTranslator(...) 处理固定的设置向导文案。它会按顺序使用 OPENCLAW_LOCALE、LC_ALL、LC_MESSAGES 和 LANG 中第一个非空值，然后回退到英语。设置 OPENCLAW_LOCALE=en 可显式覆盖为英语。将插件特定的设置文本保留在插件自有代码中，并仅对通用设置标签、状态文本以及官方捆绑插件的设置文案使用共享目录键。

当插件导入设置补丁适配器时，它们不会执行任何急切操作。其捆绑的单账户提升契约表面查找是惰性的，因此导入 plugin-sdk/setup-runtime 不会在实际使用适配器之前急切加载捆绑的契约表面发现。

通道拥有的设置输入字段¶

ChannelSetupInput 是由设置调用方和通道插件共享的通用信封。其永久类型化字段为 name、token、tokenFile、useEnv、allowFrom 和 defaultTo。运行时输入对象上仍可能存在额外的插件自有键，但共享类型未声明索引签名。每个插件必须声明并收窄其自身的设置字段，或在适配器边界处使用插件自有模式对其进行验证：

import type { ChannelSetupAdapter, ChannelSetupInput } from "openclaw/plugin-sdk/channel-setup";

type AcmeSetupInput = ChannelSetupInput & {
  workspaceId?: string;
  webhookUrl?: string;
};

export const acmeSetupAdapter: ChannelSetupAdapter = {
  applyAccountConfig: ({ cfg, input }) => {
    const setupInput = input as AcmeSetupInput;
    return {
      ...cfg,
      channels: {
        ...cfg.channels,
        acme: {
          token: setupInput.token,
          workspaceId: setupInput.workspaceId,
          webhookUrl: setupInput.webhookUrl,
        },
      },
    };
  },
};

之前直接声明在 ChannelSetupInput 上的通道特定字段，为了外部源代码兼容性而暂时保留类型。它们已弃用。2026-07-22 对 426 个已发布的树外通道插件进行的注册表扫描移除了 21 个没有读取者的字段，并保留了 22 个具有已知读取者的字段。每个保留字段会在没有任何已发布插件读取它时立即删除。无需版本边界。新插件和捆绑插件不得依赖此层级。应在本地声明它们拥有的字段。

通道拥有的单账户提升¶

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

每个通道插件都可以通过其设置适配器扩展或收窄该提升：

• configPromotion: "preserve-root"：保留所有根值，包括通用名称、策略和投递字段。插件拥有其账户布局
• singleAccountKeysToMove：应移动到提升账户中的额外顶层键
• namedAccountPromotionKeys：当已存在命名账户时，仅这些键会移动到提升账户中。共享策略/投递键保留在通道根
• resolveSingleAccountPromotionTarget(...)：选择哪个现有账户接收提升的值

singleAccountKeysToMove 的存在表示提升契约已完成。即使该字段是空数组，也应声明它以选择退出旧键提升。空数组不会抑制通用字段。省略该字段的适配器会为已发布插件保留一个由读取者支持的预声明提升层级。2026-07-22 的注册表扫描移除了 23 个没有已发布依赖者的键，并保留了六个通用键以及仅用于设置的 rooms 键。每个保留键会在其已发布读取者迁移到声明时立即删除。无需版本边界。

当 Doctor 必须从轻量级设置入口加载这些声明时，在插件包清单中声明 openclaw.setupFeatures.configPromotion: true。Doctor 通过插件清单为捆绑插件和已安装插件（包括已禁用插件）发现该入口。仅设置插件表面和完整通道插件必须暴露相同的声明。

对于插件自有的根布局，还应在 package.json 中声明 openclaw.setupFeatures.configPromotion: "preserve-root"。Doctor 会为已安装插件和捆绑插件（包括已禁用插件）读取此静态声明，而无需执行其运行时。省略该声明或使用 false 不会选择退出提升。运行时声明应位于传递给 defineChannelSetupContract 的适配器上，并覆盖共享 CLI、声明式向导和策略写入器提升。它不会更改显式迁移基础名称的辅助函数。当根仍为隐式身份时，请使用选定账户写入器。Buzz 是此布局的一个示例。

When calling moveSingleAccountChannelSectionToDefaultAccount(...) with an already resolved plugin, pass its setup adapter as setupSurface. Caller-supplied setup surfaces take precedence over loaded and bundled lookup, which keeps scoped or setup-only plugins independent of global registration.

配置模式¶

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

{
  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 还支持 textInputs、dmPolicy、allowFrom、groupAccess、prepare、finalize 等。有关完整的捆绑示例，请参阅 Discord 插件的 src/setup-core.ts。

在执行持久化设置效果之前，请 await options.beforePersistentEffect?.() 以运行宿主准备。托管频道向导还提供 options.assertPersistentEffectCurrent，这是对当前活动向导所有者的同步检查。在异步凭据准备过程中携带该检查，并在存储所有者的最终写入准入时调用它。分离的 QR 登录回调必须在其向导被释放、替换或完成后停止；先前成功的准备检查不会使该向导保持存活。此可选生命周期检查不会取代现有的异步准备回调。

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 }

• createDetectedBinaryStatus(...) 用于仅通过标签、提示、分数和二进制检测变化的状态块
  • createCliPathTextInput(...) 用于基于路径的文本输入
  • createDelegatedSetupWizardProxy(...) 当 setupEntry 需要延迟地将 status、prepare 或 finalize 行为转发到更重的完整向导时
  • createDelegatedTextInputShouldPrompt(...) 当 setupEntry 只需要委托一个 textInputs[*].shouldPrompt 决策时

发布与安装¶

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

openclaw plugins install @myorg/openclaw-my-plugin

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

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

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

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

ClawHub 发布¶

技能和插件包使用不同的 ClawHub 发布命令。对于插件包，请使用包专用命令：

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

相关¶

• 构建插件 — 分步入门指南
• 插件清单 — 完整清单模式参考
• SDK 入口点 — definePluginEntry 和 defineChannelPluginEntry
• 插件 SDK 概览 — 导入映射和注册 API 参考
• 插件 SDK 子路径 — 公共入口点目录
• 插件架构内部机制 — 加载管道和注册表模型