Manifest 与 package.json

当预运行时插件元数据不在清单中时，它存放在哪里，以及当两个插件根共享同一个 id 时，OpenClaw 如何选择一个清单。这是 插件清单 参考的一部分；顶层字段参考 列出了所有字段。

清单与 package.json¶

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

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

• 如果 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 字段。

重要示例：

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

已配置的启动插件会在 Gateway 开始监听后，从其完整运行时注册 HTTP 路由。在启动辅助进程就绪之前，其他未声明的 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、状态或只读存在性流程需要在完整通道插件加载之前进行低成本的是/否认证探测时，请使用它。持久化认证状态不是已配置的通道状态：不要使用此元数据来自动启用插件、修复运行时依赖，或决定是否应加载通道运行时。目标导出应是一个仅读取持久化状态的小函数；不要将其经由完整的通道运行时桶文件（barrel）路由。

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

openclaw.channel.configuredState 支持低成本的已配置检查。当环境变量足够时，优先使用声明式环境元数据：

{
  "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 选择其路径。被跟踪的全局安装也可以覆盖普通捆绑副本，但不能覆盖开发源码捆绑副本。
• 显式配置选择的覆盖会在每个发现代次中为每个插件发出一条信息性诊断，而不会产生配置警告。歧义选择和其他意外重复项仍会发出警告，并标识被丢弃的副本和选定的源。对普通捆绑副本的有意跟踪安装覆盖不会发出重复警告。