跳转至

设置和配置

插件打包参考:package.json 元数据、openclaw.plugin.json 清单、设置入口与配置模式。

Tip

在找分步教程? 操作指南会结合实际场景讲解打包流程:Channel 插件 和 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": "Short description of the channel."
    }
  }
}

json openclaw-clawhub-package.json { "name": "@myorg/openclaw-my-plugin", "version": "1.0.0", "type": "module", "dependencies": { "typebox": "1.3.34" }, "peerDependencies": { "openclaw": ">=2026.3.24-beta.2" }, "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" } } }

Note

在 ClawHub 上对外发布需要 compat 和 build。规范的发布片段位于 docs/snippets/plugin-publish/。

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 对外发布时需要。

Note

Provider id(providers: string[])属于清单元数据,而非包元数据。请在 openclaw.plugin.json 中声明,而不是这里 —— 参见 插件清单。

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} 引用。如果已保存配置缺失或无效,回调将不会执行。回调失败会作为设置后警告报告,而不会撤销已保存的配置。

字段 类型 含义
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 为此频道解析通知目标时,优先使用会话查找。
setup object 可序列化的频道自有设置字段,用于惰性 CLI 选项发现。

示例:

{
  "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 dist 完整性字符串,通常为 sha512-...。
allowInvalidConfigRecovery boolean 允许捆绑插件的重新安装流程从特定过期配置故障中恢复。
requiredPlatformPackages string[] 在 npm 安装期间验证所需的平台特定 npm 别名。
引导行为

交互式引导使用 openclaw.install 来处理按需安装的界面:如果你的插件在运行时加载之前就暴露了提供商认证选项或渠道设置/目录元数据,引导流程可以提示用户通过 ClawHub、npm 或本地安装来安装或启用插件,然后继续执行所选流程。ClawHub 选项使用 clawhubSpec,且在存在时优先使用。来自 npm 的选项需要带有注册表 npmSpec 的受信任目录元数据(精确版本和 expectedIntegrity 是可选固定值,设置后会在安装/更新时强制执行)。将“显示什么”保留在 openclaw.plugin.json 中,将“如何安装”保留在 package.json 中。

minHostVersion 强制执行

如果设置了 minHostVersion,安装和非捆绑的清单注册表加载都会强制执行该版本要求。较旧的主机会跳过外部插件。无效的版本字符串会被拒绝。捆绑的源插件被视为与主机检出保持版本同步。

固定版本 npm 安装

对于固定版本(pinned)的 npm 安装,请在 npmSpec 中保留精确版本,并添加预期的产物完整性值:

{
  "openclaw": {
    "install": {
      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}
allowInvalidConfigRecovery 的作用范围

allowInvalidConfigRecovery 不是针对损坏配置的通用绕过机制。它仅用于狭窄的捆绑插件恢复场景,让重新安装/设置能够修复已知的升级残留,例如缺失的捆绑插件路径或同一插件过时的 channels.<id> 条目。如果配置因无关原因损坏,安装仍会安全失败(fail closed),并提示操作员运行 openclaw doctor --fix。

设置时的网关方法

如果你的设置/完整入口注册了网关 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 导出,以便设置时的运行时接线可以保持轻量和明确。

OpenClaw 在何时使用 setupEntry 而不是完整入口
  • 渠道已被禁用,但需要设置/引导界面。
  • 渠道已启用但未配置。
setupEntry 必须注册什么
  • 渠道插件对象(通过 defineSetupPluginEntry)。
  • 需要时,通过 registerSetupRuntime 声明的设置时运行时界面。

设置时的网关方法仍应避免使用保留的核心管理员命名空间,例如 config.* 或 update.*。

setupEntry 不应包含的内容
  • CLI 注册。
  • 后台服务。
  • 繁重的运行时导入(加密库、SDK)。
  • 仅在启动后才需要的网关方法。

精简设置辅助导入

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

导入路径 用途 主要导出
plugin-sdk/setup-runtime 在 setupEntry 中保持可用的设置时(setup-time)运行时辅助工具 createSetupTranslator, createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-tools 设置/安装 CLI/归档/文档辅助工具 formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR

当你需要完整的共享设置工具箱(包括诸如 moveSingleAccountChannelSectionToDefaultAccount(...) 之类的配置补丁辅助工具)时,请使用更宽泛的 plugin-sdk/setup 接缝(seam)。

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

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

频道自有的设置输入字段

ChannelSetupInput 是一个由设置调用方和频道插件共享的通用信封(envelope)。其固定类型字段为 name、token、tokenFile、useEnv、allowFrom 和 defaultTo。插件自有的附加键仍可出现在运行时输入对象上,但共享类型未声明索引签名。每个插件必须声明并收窄自己的设置字段,或者在适配器边界使用插件自有的 schema 进行校验:

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 个已发布的第三方(out-of-tree)频道插件,移除了 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 就是这种布局的一个示例。

当使用已解析的插件调用 moveSingleAccountChannelSectionToDefaultAccount(...) 时,请将其设置适配器作为 setupSurface 传入。调用方提供的设置界面优先于已加载和捆绑查找,这使作用域限定或仅用于设置的插件独立于全局注册。

Note

Matrix 是当前捆绑示例。如果已经存在恰好一个命名的 Matrix 账户,或者 defaultAccount 指向一个已存在的非规范键(例如 Ops),提升操作会保留该账户,而不是创建新的 accounts.default 条目。

配置模式

插件配置会根据你清单中的 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。

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

共享 allowFrom 提示

对于只需要标准 note -> prompt -> parse -> merge -> patch 流程的 DM 允许列表提示,请优先使用 openclaw/plugin-sdk/setup 中的共享设置辅助函数:createPromptParsedAllowFromForAccount(...) 和 createTopLevelChannelParsedAllowFromPrompt(...)。

标准频道设置状态

对于仅通过标签、分数和可选额外行变化的频道设置状态块,请优先使用 openclaw/plugin-sdk/setup 中的 createStandardChannelSetupStatus(...),而不是在每个插件中手动编写相同的 status 对象。

可选频道设置界面

对于应仅在特定上下文中出现的可选设置界面,请使用 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(...) 用于基于路径的文本输入
    • createDelegatedSetupWizardProxy(...) 当 setupEntry 需要延迟地将 status、prepare 或 finalize 行为转发到更重的完整向导时
    • createDelegatedTextInputShouldPrompt(...) 当 setupEntry 只需要委托一个 textInputs[*].shouldPrompt 决策时

发布与安装

外部插件: 发布到 ClawHub,然后安装:

openclaw plugins install @myorg/openclaw-my-plugin

裸包规范会从 npm 安装,除非名称匹配捆绑或官方插件 id,在这种情况下 OpenClaw 会改用该本地/官方副本。使用 clawhub:、npm:、git: 或 npm-pack: 进行确定性源选择 — 参见 管理插件。

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

当包尚未迁移到 ClawHub,或者在迁移期间需要 直接的 npm 安装路径时,请使用 npm:

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

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

Info

对于来自 npm 的安装,openclaw plugins install 会将包安装到 ~/.openclaw/npm/projects 下的每个插件项目中,并禁用生命周期脚本(--ignore-scripts)。请保持插件依赖树为纯 JS/TS,并避免需要 postinstall 构建的包。

Note

网关启动不会安装插件依赖。npm/git/ClawHub 安装流程负责依赖收敛。本地插件必须已经安装好其依赖。

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

ClawHub 发布

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

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

Note

clawhub skill publish <path> 是用于发布技能文件夹的不同命令,而不是插件包。参见 在 ClawHub 上发布。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw