跳转至

Manifest 与 package.json

当运行时前插件元数据不在清单中时,它位于何处,以及 OpenClaw 如何在两个插件根目录共享同一个 id 时选择一个清单。是插件清单参考的一部分;顶层字段参考列出了所有字段。

清单与 package.json

这两个文件承担不同的职责:

文件 用途
openclaw.plugin.json 发现、配置校验、认证选择元数据,以及必须在插件代码运行前存在的 UI 提示
package.json npm 元数据、依赖安装,以及用于入口点、安装门控、设置或目录元数据的 openclaw 块

如果不确定某项元数据应放在哪里,请使用以下规则:

  • 如果 OpenClaw 必须在加载插件代码之前知道它,请将其放在 openclaw.plugin.json
  • 如果它涉及打包、入口文件或 npm 安装行为,请将其放在 package.json

影响发现的 package.json 字段

一些运行时前插件元数据有意存放在 package.json 的 openclaw 块中,而不是 openclaw.plugin.json。openclaw.bundle 和 openclaw.bundle.json 不是 OpenClaw 插件契约;原生插件必须使用 openclaw.plugin.json 加上下面支持的 package.json#openclaw 字段。

重要示例:

字段 含义
openclaw.extensions 声明原生插件入口点。必须保留在插件包目录内。
openclaw.runtimeExtensions 声明已安装包的内置 JavaScript 运行时入口点。必须保留在插件包目录内。
openclaw.setupEntry 轻量级仅设置入口点,用于入门引导、频道设置以及只读频道状态/SecretRef 发现。必须保留在插件包目录内。
openclaw.runtimeSetupEntry 声明已安装包的内置 JavaScript 设置入口点。要求 setupEntry,必须存在,并且必须保留在插件包目录内。
openclaw.channel 低成本的频道目录元数据,例如标签、文档路径、别名和选择文案。
openclaw.channel.approvalFlags 运行时加载前可用的封闭审批行为标志。native 表示频道拥有原生审批 UI 和同轮解析。
openclaw.channel.commands 静态原生命令和原生技能自动默认元数据,在频道运行时加载前供配置、审计和命令列表界面使用。
openclaw.channel.cliAddOptions 插件拥有的 openclaw channels add 选项。每个条目声明 flags、description、可选的 defaultValue,以及可选的 valueType(int 或 list),用于通用输入强制转换。
openclaw.channel.configuredState 轻量级已配置状态检查器元数据,可以在不加载完整频道运行时的情况下回答“是否已存在仅环境变量的设置?”
openclaw.channel.persistedAuthState 轻量级持久化认证检查器元数据,可以在不加载完整频道运行时的情况下回答“是否已有内容登录?”
openclaw.install.clawhubSpec / openclaw.install.npmSpec / openclaw.install.localPath 用于捆绑和外部发布插件的安装/更新提示。
openclaw.install.defaultChoice 安装路径提示,包括本地检出选择。默认远程请求优先使用声明的 npm,然后是 ClawHub;显式来源选择仍具有权威性。
openclaw.install.minHostVersion 最低支持的 OpenClaw 宿主版本,使用类似 >=2026.3.22 或 >=2026.5.1-beta.1 的 semver 下限。
字段 含义
openclaw.compat.pluginApi 此包所需的最低 OpenClaw 插件 API 范围,使用类似 >=2026.5.27 的 semver 下限。
openclaw.install.expectedIntegrity 预期的 npm dist integrity 字符串,例如 sha512-...;安装和更新流程会用它校验获取到的工件。
openclaw.install.allowInvalidConfigRecovery 当配置无效时,允许一条狭窄的捆绑插件重装恢复路径。
openclaw.install.requiredPlatformPackages 当其 lockfile 平台约束与当前主机匹配时,必须实际存在的 npm 包别名。

清单元数据决定在运行时加载之前,哪些提供商/渠道/设置选项会出现在引导流程中。package.json#openclaw.install 告诉引导流程当用户选择其中一个选项时,如何获取或启用该插件。不要将安装提示移动到 openclaw.plugin.json。

已配置的启动插件会在 Gateway 开始监听后,从它们的完整运行时注册 HTTP 路由。在启动 sidecar 就绪之前,其他未声明的 HTTP 请求会返回 503 并带有 Retry-After: 1;核心路由在整个启动过程中保持可用。

对于 openclaw.channel.cliAddOptions,请使用 Commander 的长选项语法,例如 --initial-sync-limit <n>。设置 valueType: "int" 以解析非负整数,或设置 valueType: "list" 以在插件设置适配器接收之前,将逗号、分号或换行分隔的输入拆分为字符串。省略 valueType 可原样传递解析后的 Commander 值。

openclaw.install.minHostVersion 会在安装以及清单注册表加载期间,针对非捆绑插件源强制执行。无效值会被拒绝;较新但有效的值会在较旧主机上跳过外部插件。捆绑源插件假定与主机检出保持同版本。

openclaw.install.requiredPlatformPackages 用于通过可选的、平台特定的别名暴露所需原生二进制的 npm 包。为每个受支持的平台别名列出裸 npm 包名。在 npm 安装期间,OpenClaw 仅校验其 lockfile 约束与当前主机匹配的已声明别名。如果 npm 报告成功但省略了该别名,OpenClaw 会使用全新缓存重试一次,如果该别名仍然缺失,则回滚安装。

openclaw.compat.pluginApi 会在非捆绑插件源的包安装期间强制执行。用它表示该包所针对的 OpenClaw 插件 SDK/运行时 API 下限。当插件包需要更新的 API,但仍为其他流程保留较低的安装提示时,它可以比 minHostVersion 更严格。官方 OpenClaw 版本同步会将较低的官方插件 API 下限提升到 OpenClaw 版本,并保留插件所需的较高下限。仅插件版本发布可以在包有意支持较旧主机时保留较低下限。不要仅使用包版本作为兼容性契约。peerDependencies.openclaw 仍然是 npm 包元数据;OpenClaw 使用 openclaw.compat.pluginApi 契约进行安装兼容性决策。

官方按需安装元数据应在两者发布同一插件时,将 npmSpec 声明为默认值,并将 clawhubSpec 声明为次要源。默认远程安装会先尝试 npm,仅当 npm 目标不可用时,才尝试已声明的 ClawHub 源。仅 ClawHub 的插件保留在 ClawHub;OpenClaw 绝不会从 ClawHub slug 推导 npm 包名。显式源选择、精确版本和非 latest 标签仍然具有权威性。Doctor 现有的过期运行时修复可以刷新绑定到当前 OpenClaw 发布队列的官方插件,在其记录的注册表上,通过记录替换版本来保留精确 npm 固定意图。裸规范和 @latest 遵循当前发布渠道策略,同时在安装记录中保留请求的选择器。完整性、兼容性、信任、安装策略和能力同意失败不会授权切换源。

精确 npm 版本固定已经存在于 npmSpec 中,例如 "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"。官方外部目录条目应将精确规范与 expectedIntegrity 配对,以便在获取的 npm 工件不再匹配固定版本时,更新流程失败关闭。交互式引导仍会提供受信任注册表的 npm 规范,包括裸包名和 dist-tags,以保持兼容性。目录诊断可以区分精确、浮动、完整性固定、缺少完整性、包名不匹配以及无效默认选择源。当存在 expectedIntegrity 但没有可固定的有效 npm 源时,它们也会发出警告。当存在 expectedIntegrity 时,安装/更新流程会强制执行它;当省略时,注册表解析会被记录而不带完整性固定。

通道插件在状态、通道列表或 SecretRef 扫描需要识别已配置账户,而无需加载完整运行时时应提供 openclaw.setupEntry。设置入口应暴露通道元数据以及设置安全的配置、状态和密钥适配器;网络客户端、网关监听器和传输运行时保留在主扩展入口点中。

在首次加载设置入口之前,OpenClaw 会应用所选插件根目录的文件边界和硬链接策略,即使发现元数据已经缓存。经过验证的设置模块会在该插件缓存代中保持缓存;此检查不会在每次状态调用时重新发现元数据。

运行时入口点字段不会覆盖源入口点字段的包边界检查。例如,openclaw.runtimeExtensions 无法使越界的 openclaw.extensions 路径可加载。

openclaw.install.allowInvalidConfigRecovery 被有意设计得较为狭窄。它不会使任意损坏的配置可安装。它只允许安装流程从可归因于正在安装的捆绑插件的配置问题中恢复:缺失的所属插件加载路径、该插件未知或无效的 channels.<id> 条目、需要编译运行时输出的 plugins.entries.<id> 条目,或命名该插件的 tools.web.search.provider 值。无关的配置错误仍会阻止安装,并引导操作员使用 openclaw doctor --fix。

openclaw.channel.persistedAuthState 是用于小型检查器模块的包元数据:

{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}

当设置、doctor、状态或只读存在性流程需要在完整通道插件加载之前进行廉价的“是/否”身份验证检查时,请使用它。持久化身份验证状态不是已配置的通道状态:不要使用此元数据来自动启用插件、修复运行时依赖项,或决定通道运行时是否应加载。目标导出应是一个仅读取持久化状态的小型函数;不要通过完整通道运行时桶文件路由它。

如果某个 persistedAuthState 检查器的数据完全来自主机的键控插件状态存储,它可以声明 "backingStore": "plugin-state"。在加载该检查器之前,OpenClaw 会询问现有的状态读取所有者,底层数据库是否确定不存在。活动保留快照、缓存的打开句柄、现有文件或符号链接,或不确定的文件系统结果都会保持正常检查器路径。不存在结果不会被缓存,因此同一进程中稍后创建的状态仍会被发现。这一事实不会建立身份验证或授予状态访问权限;检查器仍会验证现有记录。对于可以在其他存储或文件中找到持久化身份验证的检查器,请省略它。较旧的主机会忽略该可选事实并正常运行检查器。

openclaw.channel.configuredState 支持廉价的已配置检查。当环境变量足够时,优先使用声明式 env 元数据:

{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "env": {
          "allOf": ["TELEGRAM_BOT_TOKEN"]
        }
      }
    }
  }
}

当所有列出的变量都必需时使用 env.allOf,当任意一个非空变量足够时使用 env.anyOf。如果小型非运行时检查需要超出环境元数据的能力,请使用 specifier 加 exportName,如 persistedAuthState 所示。完整且非空的 specifier 和 exportName 组合优先于 env。如果任一字段缺失或为空,该检查将使用其 env 元数据,而不加载模块。

声明的 configuredState 元数据同时拥有正向和负向引导结果。负向结果不会回退到运行时钩子或已存储凭据。没有该声明的通道保留旧版 config.hasConfiguredState 回退。需要当前已存储凭据的操作检查使用 config.hasConfiguredStateAsync;将它们与基于配置和环境变量的激活分开。

对于这两种状态检查,OpenClaw 仅为完整模块对构建重写源说明符,并命名确切输出的 JavaScript 工件,包括其 .js 或 .cjs 扩展名。基于 env 的不完整对保持不变。已构建的检出元数据使用相对于插件根目录的路径;独立包使用插件本地的 dist/ 目录。

发现优先级(重复插件 ID)

OpenClaw 从显式 plugins.load.paths 条目、当前工作区根目录(<workspace>/.openclaw/extensions)、随 OpenClaw 分发的捆绑插件以及全局安装位置(~/.openclaw/extensions 加上受跟踪的安装路径)发现插件。仅发现顺序并不能确定加载哪个副本。

如果两个不同的插件根目录共享相同的 id,则只保留最高优先级的清单;较低优先级的重复项会被丢弃,而不是与其一起加载。优先级从高到低:

  1. 配置选择 — 在 plugins.load.paths 中显式选择的路径
  2. 源检出捆绑 — 运行主机源检出中的已编译捆绑插件,或由 OPENCLAW_DEV_SOURCE_ROOT 选择的检出中的捆绑插件
  3. 匹配受跟踪安装记录的全局安装 — 其路径与其安装记录匹配的已安装全局候选项,由 openclaw plugins install/openclaw plugins update 管理
  4. 捆绑 — 随 OpenClaw 分发的其他插件
  5. 工作区 — 相对于当前工作区发现的插件
  6. 未跟踪全局 — 在全局根目录中发现的其他插件

影响:

  • 自动发现的工作区或未跟踪全局副本不会遮蔽捆绑插件,即使其 id 已启用或在允许列表中。plugins.allow 和 plugins.entries.<id>.enabled 控制加载权限,而不是源选择。
  • 若要有意覆盖捆绑插件,请通过 plugins.load.paths 选择其路径。受跟踪的全局安装也可以覆盖普通捆绑副本,但不能覆盖开发源捆绑副本。
  • 显式配置选择覆盖会在每个发现代中为每个插件发出一个信息性诊断,而不发出配置警告。模糊的选择和其他意外重复仍会发出警告,并标识被丢弃的副本和所选源。对普通捆绑副本的有意受跟踪安装覆盖不会发出重复警告。

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