Plugin manifest

本页面仅针对 原生 OpenClaw 插件清单。

有关兼容的捆绑包布局，请参阅插件捆绑包。

兼容的包格式使用不同的清单文件：

Codex bundle：.codex-plugin/plugin.json
Claude bundle：.claude-plugin/plugin.json 或不带 manifest 的默认 Claude 组件布局
Cursor bundle：.cursor-plugin/plugin.json

OpenClaw 也会自动检测那些 bundle 布局，但不会根据此处描述的 OpenClawopenclaw.plugin.json 架构对它们进行验证。

对于兼容的 bundle，当布局符合 OpenClaw 运行时预期时，OpenClaw 目前会读取 bundle 元数据以及声明的技能根目录、Claude 命令根目录、Claude bundle OpenClawsettings.jsonOpenClaw 默认值、Claude bundle LSP 默认值和支持的 hook 包。

每个原生 OpenClaw 插件必须在插件根目录中附带一个 OpenClawopenclaw.plugin.jsonOpenClaw 文件。OpenClaw 使用此 manifest 来验证配置，而无需执行插件代码。缺失或无效的 manifest 将被视为插件错误，并阻止配置验证。

请参阅完整的插件系统指南：插件。有关原生能力模型和当前的外部兼容性指导：能力模型。

此文件的作用

openclaw.plugin.jsonOpenClaw 是 OpenClaw 在加载插件代码之前读取的元数据。下面的所有内容都必须足够轻量，以便在不启动插件运行时的情况下进行检查。

用于：

插件标识、配置验证和配置 UI 提示
身份验证、新手引导和设置元数据（别名、自动启用、提供商环境变量、身份验证选择）
控制平面界面的激活提示
简写模型家族所有权
静态 capability-ownership 快照 (contracts)
共享 openclaw qa 主机可以检查的 QA 运行器元数据
合并到目录和验证界面的渠道特定配置元数据

请勿将其用于： 注册运行时行为、声明代码入口点或 npm install 元数据。这些内容应属于您的插件代码和 npmpackage.json。

最小示例

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

完整示例

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "modelIdNormalization": {
    "providers": {
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  },
  "providerEndpoints": [
    {
      "endpointClass": "openrouter",
      "hostSuffixes": ["openrouter.ai"]
    }
  ],
  "providerRequest": {
    "providers": {
      "openrouter": {
        "family": "openrouter"
      }
    }
  },
  "cliBackends": ["openrouter-cli"],
  "syntheticAuthRefs": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API key",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API key",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

顶级字段参考

字段	必填	类型	含义
`id`	是	`string`	规范插件 id。这是在 `plugins.entries.<id>` 中使用的 id。
`configSchema`	是	`object`	此插件配置的内联 JSON Schema。
`enabledByDefault`	否	`true`	将捆绑的插件标记为默认启用。省略它，或设置为任何非 `true` 值，以使插件默认处于禁用状态。
`enabledByDefaultOnPlatforms`	否	`string[]`	将捆绑的插件标记为仅在列出的 Node.js 平台上默认启用，例如 `["darwin"]`。显式配置优先。
`legacyPluginIds`	否	`string[]`	规范化为此规范插件 ID 的旧 ID。
`autoEnableWhenConfiguredProviders`	否	`string[]`	当身份验证、配置或模型引用提及这些提供商 ID 时，应自动启用此插件的提供商 ID。
`kind`	否	`"memory"` \| `"context-engine"`	声明由 `plugins.slots.*` 使用的独占插件种类。
`channels`	否	`string[]`	由此插件拥有的频道 ID。用于发现和配置验证。
`providers`	否	`string[]`	由此插件拥有的提供商 ID。
`providerCatalogEntry`	否	`string`	轻量级提供商目录模块路径，相对于插件根目录，用于可在不激活完整插件运行时的情况下加载的清单范围提供商目录元数据。
`modelSupport`	否	`object`	清单拥有的简写模型系列元数据，用于在运行时之前自动加载插件。
`modelCatalog`	否	`object`	由此插件拥有的提供商的声明性模型目录元数据。这是用于未来只读列表、新手引导、模型选择器、别名和抑制（无需加载插件运行时）的控制平面契约。
`modelPricing`	否	`object`	提供商拥有的外部价格查找策略。使用它可以让本地/自托管提供商退出远程价格目录，或者在核心中将提供商引用映射到 OpenRouter/LiteLLM 目录 ID，而无需在核心中硬编码提供商 ID。
`modelIdNormalization`	否	`object`	提供商拥有的模型 ID 别名/前缀清理，必须在提供商运行时加载之前运行。
`providerEndpoints`	否	`object[]`	清单拥有的提供商路由的端点主机/baseUrl 元数据，核心必须在提供商运行时加载之前对其进行分类。
`providerRequest`	否	`object`	通用请求策略在提供商运行时加载之前使用的廉价提供商系列和请求兼容性元数据。
`cliBackends`	否	`string[]`	此插件拥有的 CLI 推理后端 ID。用于从显式配置引用进行启动时自动激活。
`syntheticAuthRefs`	否	`string[]`	提供商或 CLI 后端引用，其插件拥有的综合身份验证挂钩应在运行时加载之前的冷模型发现期间进行探测。
`nonSecretAuthMarkers`	否	`string[]`	捆绑插件拥有的占位符 API 密钥值，表示非机密的本地、OAuth 或环境凭据状态。
`commandAliases`	否	`object[]`	此插件拥有的命令名称，应在运行时加载之前生成支持插件的配置和 CLI 诊断信息。
`providerAuthEnvVars`	否	`Record<string, string[]>`	用于提供商身份验证/状态查找的已弃用兼容性环境元数据。对于新插件，首选使用 `setup.providers[].envVars`OpenClaw；在弃用期内，OpenClaw 仍会读取此项。
`providerAuthAliases`	否	`Record<string, string>`	应重用另一个提供商 ID 进行身份验证查找的提供商 ID，例如共享基础提供商 API 密钥和身份验证配置文件的编码提供商。
`channelEnvVars`	否	`Record<string, string[]>`	OpenClaw 可以在不加载插件代码的情况下检查的廉价渠道环境元数据。将其用于通用启动/配置辅助工具应该看到的基于环境的渠道设置或身份验证界面。
`providerAuthChoices`	否	`object[]`	用于新手引导选择器、首选提供商解析和简单 CLI 标志连线的廉价身份验证选择元数据。
`activation`	否	`object`	用于启动、提供商、命令、渠道、路由和功能触发的加载的廉价激活计划程序元数据。仅包含元数据；插件运行时仍拥有实际行为。
`setup`	否	`object`	发现和设置界面可以在不加载插件运行时的情况下检查的廉价设置/新手引导描述符。
`qaRunners`	否	`object[]`	由共享 `openclaw qa` 主机在插件运行时加载之前使用的廉价 QA 运行器描述符。
`contracts`	否	`object`	用于外部身份验证挂钩、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、Web 获取、Web 搜索和工具所有权的静态功能所有权快照。
`mediaUnderstandingProviderMetadata`	否	`Record<string, object>`	在 `contracts.mediaUnderstandingProviders` 中声明的提供商 ID 的廉价媒体理解默认值。
`imageGenerationProviderMetadata`	否	`Record<string, object>`	在 `contracts.imageGenerationProviders` 中声明的提供商 ID 的廉价图像生成身份验证元数据，包括提供商拥有的身份验证别名和基础 URL 守护。
`videoGenerationProviderMetadata`	否	`Record<string, object>`	在 `contracts.videoGenerationProviders` 中声明的提供商 ID 的廉价视频生成身份验证元数据，包括提供商拥有的身份验证别名和基础 URL 守护。
`musicGenerationProviderMetadata`	否	`Record<string, object>`	在 `contracts.musicGenerationProviders` 中声明的提供商 ID 的廉价音乐生成身份验证元数据，包括提供商拥有的身份验证别名和基础 URL 守护。
`toolMetadata`	否	`Record<string, object>`	在 `contracts.tools` 中声明的插件拥有的工具的廉价可用性元数据。当工具除非存在配置、环境或身份验证证据，否则不应加载运行时时使用它。
`channelConfigs`	否	`Record<string, object>`	在运行时加载之前，合并到发现和验证层的清单拥有的渠道配置元数据。
`skills`	否	`string[]`	要加载的技能目录，相对于插件根目录。
`name`	否	`string`	人类可读的插件名称。
`description`	否	`string`	在插件界面显示的简短摘要。
`version`	否	`string`	信息性插件版本。
`uiHints`	否	`Record<string, object>`	配置字段的 UI 标签、占位符和敏感度提示。

生成提供商元数据参考

生成提供商元数据字段描述了在匹配的 contracts.*GenerationProvidersOpenClaw 列表中声明的提供商的静态身份验证信号。 OpenClaw 在提供商运行时加载之前读取这些字段，以便核心工具可以确定生成提供商是否可用，而无需导入每个提供商插件。

这些字段仅用于廉价、声明性的事实。传输、请求转换、令牌刷新、凭据验证和实际生成行为保留在插件运行时中。

{
  "contracts": {
    "imageGenerationProviders": ["example-image"]
  },
  "imageGenerationProviderMetadata": {
    "example-image": {
      "aliases": ["example-image-oauth"],
      "authProviders": ["example-image"],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example-image.config",
          "overlayPath": "image",
          "mode": {
            "path": "mode",
            "default": "local",
            "allowed": ["local"]
          },
          "requiredAny": ["workflow", "workflowPath"],
          "required": ["promptNodeId"]
        }
      ],
      "authSignals": [
        {
          "provider": "example-image"
        },
        {
          "provider": "example-image-oauth",
          "providerBaseUrl": {
            "provider": "example-image",
            "defaultBaseUrl": "https://api.example.com/v1",
            "allowedBaseUrls": ["https://api.example.com/v1"]
          }
        }
      ]
    }
  }
}

每个元数据条目支持：

字段	必填	类型	含义
`aliases`	否	`string[]`	应计为此生成提供商的静态身份验证别名的其他提供商 ID。
`authProviders`	否	`string[]`	其配置的身份验证配置文件应计为此生成提供商的身份验证的提供商 ID。
`configSignals`	否	`object[]`	适用于可以在没有身份验证配置文件或环境变量的情况下配置的本地或自托管提供商的廉价仅配置可用性信号。
`authSignals`	否	`object[]`	显式身份验证信号。如果存在，这些信号将替换来自提供商 ID、`aliases` 和 `authProviders` 的默认信号集。
`referenceAudioInputs`	否	`boolean`	仅限视频生成。当提供商接受参考音频资源时设置为 `true`；否则 `video_generate` 会隐藏音频参考参数。

每个 configSignals 条目支持：

字段	必需	类型	含义
`rootPath`	是	`string`	要检查的插件拥有的配置对象的点路径，例如 `plugins.entries.example.config`。
`overlayPath`	否	`string`	根配置内部的点路径，其对象应在评估信号之前覆盖根对象。将其用于特定于能力的配置，例如 `image`、`video` 或 `music`。
`required`	否	`string[]`	有效配置内必须具有已配置值的点路径。字符串必须非空；对象和数组不得为空。
`requiredAny`	否	`string[]`	有效配置内的点路径，其中至少一个必须具有已配置的值。
`mode`	否	`object`	有效配置内的可选字符串模式保护。当仅基于配置的可用性仅适用于一种模式时，请使用此选项。

每个 mode 保护支持：

字段	必需	类型	含义
`path`	否	`string`	有效配置内的点路径。默认为 `mode`。
`default`	否	`string`	当配置省略该路径时使用的模式值。
`allowed`	否	`string[]`	如果存在，则仅当有效模式为这些值之一时，信号才会通过。
`disallowed`	否	`string[]`	如果存在，当有效模式是这些值之一时，信号将失败。

每个 authSignals 条目支持：

字段	必填	类型	含义
`provider`	是	`string`	要在配置的身份提供商配置文件中检查的提供商 ID。
`providerBaseUrl`	否	`object`	可选保护条件，仅当引用的配置提供商使用允许的 Base URL 时，该信号才计入。当身份别名仅对特定 API 有效时使用此项。

每个 providerBaseUrl 保护条件支持：

字段	必填	类型	含义
`provider`	是	`string`	应检查其 `baseUrl` 的提供商配置 ID。
`defaultBaseUrl`	否	`string`	当提供商配置省略 `baseUrl` 时假定的 Base URL。
`allowedBaseUrls`	是	`string[]`	此身份信号的允许 Base URL。当配置的或默认的 Base URL 与这些规范化值之一不匹配时，该信号将被忽略。

工具元数据参考

toolMetadata 使用与生成提供商元数据相同的 configSignals 和 authSignals 形状，按工具名称键入。contracts.tools 声明所有权。toolMetadata 声明低成本可用性证据，以便 OpenClaw 可以避免导入插件运行时，仅为了让其工具工厂返回 null。

{
  "providerAuthEnvVars": {
    "example": ["EXAMPLE_API_KEY"]
  },
  "contracts": {
    "tools": ["example_search"]
  },
  "toolMetadata": {
    "example_search": {
      "authSignals": [
        {
          "provider": "example"
        }
      ],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example.config",
          "overlayPath": "search",
          "required": ["apiKey"]
        }
      ]
    }
  }
}

如果工具没有 toolMetadata，OpenClaw 将保留现有行为，并在工具契约与策略匹配时加载所属插件。对于工厂依赖于身份/配置的热路径工具，插件作者应声明 toolMetadata，而不是让核心导入运行时去询问。

providerAuthChoices 参考

每个 providerAuthChoicesOpenClaw 条目描述一个新手引导或身份验证选项。 OpenClaw 会在提供商运行时加载之前读取此内容。提供商设置列表使用这些清单选项、描述符派生的设置选项以及安装目录元数据，而无需加载提供商运行时。

字段	必需	类型	含义
`provider`	是	`string`	此选项所属的提供商 ID。
`method`	是	`string`	要分发到的身份验证方法 ID。
`choiceId`	是	`string`	由新手引导和 CLI 流程使用的稳定身份验证选项 ID。
`choiceLabel`	否	`string`	面向用户的标签。如果省略，OpenClaw 将回退到 OpenClaw`choiceId`。
`choiceHint`	否	`string`	选择器的简短辅助文本。
`assistantPriority`	否	`number`	在助手驱动的交互式选择器中，数值越低排序越靠前。
`assistantVisibility`	否	`"visible"` \| `"manual-only"`	在助手选择器中隐藏该选项，同时仍允许手动 CLI 选择。
`deprecatedChoiceIds`	否	`string[]`	应将用户重定向到此替换选项的旧选项 ID。
`groupId`	否	`string`	用于对相关选项进行分组的可选组 ID。
`groupLabel`	否	`string`	该组面向用户的标签。
`groupHint`	否	`string`	该组的简短辅助文本。
`optionKey`	否	`string`	用于简单单标志身份验证流程的内部选项键。
`cliFlag`	否	`string`	CLI 标志名称，例如 CLI`--openrouter-api-key`。
`cliOption`	否	`string`	完整的 CLI 选项结构，例如 CLI`--openrouter-api-key <key>`。
`cliDescription`	否	`string`	CLI 帮助中使用的描述。
`onboardingScopes`	否	`Array<"text-inference" \| "image-generation" \| "music-generation">`	此选项应出现在哪些新手引导界面中。如果省略，则默认为 `["text-inference"]`。

commandAliases 参考

当插件拥有用户可能会错误地放入 plugins.allowCLIOpenClaw 或尝试作为根 CLI 命令运行的运行时命令名称时，请使用 commandAliases。OpenClaw 使用此元数据进行诊断，而无需导入插件运行时代码。

{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}

字段	必填	类型	含义
`name`	是	`string`	属于此插件的命令名称。
`kind`	否	`"runtime-slash"`	将别名标记为聊天斜杠命令，而不是根 CLI 命令。
`cliCommand`	否	`string`	如果存在，则为 CLI 操作建议的相关根 CLI 命令。

activation 参考

当插件可以轻松声明哪些控制平面事件应将其包含在激活/加载计划中时，请使用 activation。

此块是规划器元数据，而不是生命周期 API。它不注册运行时行为，不替换 APIregister(...)，也不承诺插件代码已执行。激活规划器使用这些字段在回退到现有的清单所有权元数据（例如 providers、channels、commandAliases、setup.providers、contracts.tools 和钩子）之前缩小候选插件范围。

优先使用已经描述所有权范围最窄的元数据。当这些字段表达该关系时，请使用 providers、channels、commandAliases、setup descriptors 或 contracts。对于无法由那些所有权字段表示的额外规划器提示，请使用 activation。对于诸如 claude-cli、my-cli 或 google-gemini-cli 之类的 CLI 运行时别名，请使用顶层的 cliBackends；activation.onAgentHarnesses 仅适用于尚未具有所有权字段的嵌入式 agent harness id。

此块仅为元数据。它不注册运行时行为，也不替代 register(...)、setupEntry 或其他运行时/插件入口点。当前的使用者在更广泛的插件加载之前将其作为缩小提示，因此除非 manifest 所有权回退仍然存在，否则缺少非启动激活元数据通常只会影响性能；它不应改变正确性。

每个插件都应有意地设置 activation.onStartup。仅当插件必须在 Gateway(网关) 启动期间运行时，才将其设置为 true。当插件在启动时处于非活动状态且应仅从更窄的触发器加载时，将其设置为 false。省略 onStartup 不再隐含地启动加载插件；对于启动、渠道、配置、agent-harness、内存或其他更窄的激活触发器，请使用显式激活元数据。

{
  "activation": {
    "onStartup": false,
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onConfigPaths": ["browser"],
    "onCapabilities": ["provider", "tool"]
  }
}

字段	必需	类型	含义
`onStartup`	否	`boolean`	显式 Gateway(网关) 启动激活。每个插件都应设置此项。`true` 在启动期间导入插件；`false` 使其在启动时保持惰性，除非另一个匹配的触发器需要加载。
`onProviders`	否	`string[]`	应在激活/加载计划中包含此插件的 Provider id。
`onAgentHarnesses`	否	`string[]`	嵌入式代理 harness 运行时 ID，这些 ID 应在激活/加载计划中包含此插件。使用顶级 `cliBackends`CLI 作为 CLI 后端别名。
`onCommands`	否	`string[]`	应在激活/加载计划中包含此插件的命令 ID。
`onChannels`	否	`string[]`	应在激活/加载计划中包含此插件的渠道 ID。
`onRoutes`	否	`string[]`	应在激活/加载计划中包含此插件的路由类型。
`onConfigPaths`	否	`string[]`	相对于根目录的配置路径，当这些路径存在且未被显式禁用时，应在启动/加载计划中包含此插件。
`onCapabilities`	否	`Array<"provider" \| "channel" \| "tool" \| "hook">`	控制平面激活规划所使用的广泛能力提示。尽可能使用更窄的字段。

当前活跃的使用者：

Gateway(网关) 启动规划使用 Gateway(网关)activation.onStartup 进行显式启动导入
命令触发的 CLI 规划会回退到旧的 CLIcommandAliases[].cliCommand 或 commandAliases[].name
agent-runtime 启动规划将 activation.onAgentHarnesses 用于嵌入式 harness，将顶级 cliBackends[]CLI 用于 CLI 运行时别名
渠道触发的设置/渠道规划会回退到旧的 channels[] 所有权，当缺少显式渠道激活元数据时
启动插件规划使用 activation.onConfigPaths 处理非渠道根配置层面，例如捆绑的浏览器插件的 browser 块
提供商触发的设置/运行时规划会回退到旧的 providers[] 和顶级 cliBackends[] 所有权，当缺少显式提供商激活元数据时

Planner 诊断可以区分显式激活提示和清单所有权回退。例如，activation-command-hint 表示 activation.onCommands 匹配成功，而 manifest-command-alias 表示 Planner 改用了 commandAliases 所有权。这些原因标签仅供主机诊断和测试使用；插件作者应继续声明最能描述所有权的元数据。

qaRunners 参考

当插件在共享的 openclaw qa 根目录下提供了一个或多个传输运行器时，请使用 qaRunners。请保持此元数据的低成本和静态特性；插件运行时仍通过导出 qaRunnerCliRegistrations 的轻量级 runtime-api.ts 表面来拥有实际的 CLI 注册。

{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
    }
  ]
}

字段	必需	类型	含义
`commandName`	是	`string`	挂载在 `openclaw qa` 下的子命令，例如 `matrix`。
`description`	否	`string`	当共享主机需要存根命令时使用的回退帮助文本。

setup 参考

当设置和表面在运行时加载之前需要廉价的插件拥有的元数据时，请使用 setup。

{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"],
        "authEvidence": [
          {
            "type": "local-file-with-env",
            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",
            "requiresAllEnv": ["OPENAI_PROJECT"],
            "credentialMarker": "openai-local-credentials",
            "source": "openai local credentials"
          }
        ]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}

顶层 cliBackends 保持有效，并继续描述 CLI 推理后端。setup.cliBackends 是特定于控制的设置描述符表面/设置流程，应保持仅为元数据。

如果存在，setup.providers 和 setup.cliBackends 是设置发现的首选描述符优先查找表面。如果描述符仅缩小了候选插件范围，而设置仍需要更丰富的设置时运行时钩子，请设置 requiresRuntime: true 并将 setup-api 保留作为回退执行路径。

OpenClaw 还在通用提供商身份验证和环境变量查找中包含 OpenClawsetup.providers[].envVars。在弃用窗口期内，providerAuthEnvVars 通过兼容性适配器继续获得支持，但仍在使用它的非打包插件会收到清单诊断。新插件应将设置/状态环境元数据放在 setup.providers[].envVars 上。

当没有可用的设置条目，或者 setup.requiresRuntime: false 声明设置运行时不需要时，OpenClaw 也可以从 OpenClawsetup.providers[].authMethods 推导简单的设置选择。对于自定义标签、CLI 标志、新手引导范围和助手元数据，显式的 providerAuthChoicesCLI 条目仍然是首选。

仅当这些描述符足以满足设置界面时，才设置 requiresRuntime: falseOpenClaw。OpenClaw 将显式的 false 视为仅描述符契约，不会执行 setup-api 或 openclaw.setupEntryOpenClaw 进行设置查找。如果一个仅描述符插件仍然提供了这些设置运行时条目之一，OpenClaw 会报告一个附加诊断并继续忽略它。省略 requiresRuntime 会保留传统的回退行为，以便那些添加了描述符但没有设置该标志的现有插件不会中断。

由于设置查找可以执行插件拥有的 setup-api 代码，因此标准化的 setup.providers[].id 和 setup.cliBackends[] 值必须在所有发现的插件中保持唯一。所有权模糊会导致失败关闭，而不是从发现顺序中选择一个优胜者。

当设置运行时确实执行时，如果 setup-apiCLI 注册了清单描述符未声明的提供商或 CLI 后端，或者描述符没有匹配的运行时注册，则设置注册表诊断会报告描述符偏差。这些诊断是附加的，不会拒绝传统插件。

setup.providers 参考

字段	必填	类型	含义
`id`	是	`string`	在设置或新手引导期间暴露的提供商 ID。请保持规范化 ID 全局唯一。
`authMethods`	否	`string[]`	该提供商在无需加载完整运行时的情况下支持的设置/身份验证方法 ID。
`envVars`	否	`string[]`	通用设置/状态界面可以在插件运行时加载之前检查的环境变量。
`authEvidence`	否	`object[]`	针对可通过非机密标记进行身份验证的提供商的低成本本地身份验证证据检查。

authEvidence 用于提供商拥有的本地凭据标记，这些标记可以在不加载运行时代码的情况下进行验证。这些检查必须保持低成本和本地化：不进行网络调用，不读取钥匙串或机密管理器，不执行 Shell 命令，也不进行提供商 API API 探测。

支持的证据条目：

字段	必填	类型	含义
`type`	是	`string`	当前为 `local-file-with-env`。
`fileEnvVar`	否	`string`	包含显式凭据文件路径的环境变量。
`fallbackPaths`	否	`string[]`	当 `fileEnvVar` 不存在或为空时检查的本地凭据文件路径。支持 `${HOME}` 和 `${APPDATA}`。
`requiresAnyEnv`	否	`string[]`	列出的环境变量中必须至少有一个非空，证据才有效。
`requiresAllEnv`	否	`string[]`	列出的所有环境变量必须全部非空，证据才有效。
`credentialMarker`	是	`string`	当证据存在时返回的非机密标记。
`source`	否	`string`	用于身份验证/状态输出的面向用户的源标签。

setup 字段

字段	必填	类型	含义
`providers`	否	`object[]`	在设置和新手引导期间暴露的提供商设置描述符。
`cliBackends`	否	`string[]`	用于以描述符为首的设置查找的设置时后端 ID。请保持标准化 ID 在全局范围内唯一。
`configMigrations`	否	`string[]`	由此插件的设置层拥有的配置迁移 ID。
`requiresRuntime`	否	`boolean`	在描述符查找之后，设置是否仍需要执行 `setup-api`。

uiHints 参考

uiHints 是从配置字段名称到小型渲染提示的映射。

{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

每个字段提示可以包括：

字段	类型	含义
`label`	`string`	面向用户的字段标签。
`help`	`string`	简短的辅助文本。
`tags`	`string[]`	可选的 UI 标签。
`advanced`	`boolean`	将字段标记为高级。
`sensitive`	`boolean`	将字段标记为机密或敏感。
`placeholder`	`string`	表单输入的占位符文本。

contracts 参考

仅将 contractsOpenClaw 用于 OpenClaw 可以在无需导入插件运行时的情况下读取的静态能力所有权元数据。

{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"],
    "externalAuthProviders": ["acme-ai"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "migrationProviders": ["hermes"],
    "gatewayMethodDispatch": ["authenticated-request"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

每个列表都是可选的：

字段	类型	含义
`embeddedExtensionFactories`	`string[]`	Codex 应用服务器扩展工厂 ID，目前为 `codex-app-server`。
`agentToolResultMiddleware`	`string[]`	打包插件可能为其注册工具结果中间件的运行时 ID。
`externalAuthProviders`	`string[]`	此插件拥有的外部身份验证配置文件挂钩的提供商 ID。
`speechProviders`	`string[]`	此插件拥有的语音提供商 ID。
`realtimeTranscriptionProviders`	`string[]`	此插件拥有的实时转录提供商 ID。
`realtimeVoiceProviders`	`string[]`	此插件拥有的实时语音提供商 ID。
`memoryEmbeddingProviders`	`string[]`	此插件拥有的内存嵌入提供商 ID。
`mediaUnderstandingProviders`	`string[]`	此插件拥有的媒体理解提供商 ID。
`imageGenerationProviders`	`string[]`	此插件拥有的图像生成提供商 ID。
`videoGenerationProviders`	`string[]`	此插件拥有的视频生成提供商 ID。
`webFetchProviders`	`string[]`	此插件拥有的 Web 抓取提供商 ID。
`webSearchProviders`	`string[]`	此插件拥有的 Web 搜索提供商 ID。
`migrationProviders`	`string[]`	此插件拥有的导入提供商 ID，用于 `openclaw migrate`。
`gatewayMethodDispatch`	`string[]`	为经过身份验证的插件 HTTP 路由保留的权限，这些路由在进程内调度 Gateway(网关) 方法。
`tools`	`string[]`	此插件拥有的代理工具名称。

contracts.embeddedExtensionFactories 为捆绑的 Codex 应用服务器专用扩展工厂保留。捆绑的工具结果转换应改为声明 contracts.agentToolResultMiddleware 并通过 api.registerAgentToolResultMiddleware(...) 注册。外部插件无法注册工具结果中间件，因为接缝可以在模型看到之前重写高信任工具输出。

运行时 api.registerTool(...) 注册必须匹配 contracts.tools。工具发现使用此列表仅加载可以拥有所请求工具的插件运行时。

实现 resolveExternalAuthProfiles 的提供商插件应声明 contracts.externalAuthProviders。没有该声明的插件仍然通过已弃用的兼容性回退运行，但该回退速度较慢，并将在迁移窗口之后被移除。

捆绑的内存嵌入提供商应该为其公开的每个适配器 ID 声明 contracts.memoryEmbeddingProviders，包括内置适配器，例如 local。独立的 CLI 路径使用此清单合约在完整的 Gateway(网关) 运行时注册提供商之前仅加载所有者插件。

contracts.gatewayMethodDispatch 目前接受 "authenticated-request"。这是一个针对原生插件 HTTP 路由的 API 卫生门，用于有意在进程内调度 Gateway(网关) 控制平面方法，而不是针对恶意原生插件的沙箱。请仅将其用于经过严格审查的捆绑/运营商界面，这些界面已经需要 Gateway(网关) HTTP 身份验证。

mediaUnderstandingProviderMetadata 参考

当媒体理解提供商具有默认模型、自动身份验证回退优先级或通用核心助手在运行时加载之前需要的原生文档支持时，请使用 mediaUnderstandingProviderMetadata。键也必须在 contracts.mediaUnderstandingProviders 中声明。

{
  "contracts": {
    "mediaUnderstandingProviders": ["example"]
  },
  "mediaUnderstandingProviderMetadata": {
    "example": {
      "capabilities": ["image", "audio"],
      "defaultModels": {
        "image": "example-vision-latest",
        "audio": "example-transcribe-latest"
      },
      "autoPriority": {
        "image": 40
      },
      "nativeDocumentInputs": ["pdf"]
    }
  }
}

每个提供商条目可以包含：

字段	类型	含义
`capabilities`	`("image" \| "audio" \| "video")[]`	此提供商公开的媒体功能。
`defaultModels`	`Record<string, string>`	当配置未指定模型时使用的功能到模型的默认值。
`autoPriority`	`Record<string, number>`	对于基于凭据的自动提供商回退，数字越小排序越靠前。
`nativeDocumentInputs`	`"pdf"[]`	提供商支持的原生文档输入。

channelConfigs 参考

当渠道插件需要在运行时加载之前获取廉价的配置元数据时，请使用 channelConfigs。只读渠道设置/状态发现可以直接使用此元数据用于配置的外部渠道，当没有可用的设置条目时，或者当 setup.requiresRuntime: false 声明设置运行时不需要时。

channelConfigs 是插件清单元数据，而不是新的顶层用户配置部分。用户仍然在 channels.<channel-id>OpenClaw 下配置渠道实例。 OpenClaw 读取清单元数据以在插件运行时代码执行之前确定哪个插件拥有该配置的渠道。

对于渠道插件，configSchema 和 channelConfigs 描述了不同的路径：

configSchema 验证 plugins.entries.<plugin-id>.config
channelConfigs.<channel-id>.schema 验证 channels.<channel-id>

声明 channels[] 的非捆绑插件还应声明匹配的 channelConfigsOpenClaw 条目。如果没有这些条目，OpenClaw 仍然可以加载插件，但是冷路径配置架构、设置和控制 UI 界面在插件运行时执行之前无法知道渠道拥有的选项形状。

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled 和 nativeSkillsAutoEnabled 可以为在渠道运行时加载之前运行的命令配置检查声明静态 auto 默认值。捆绑渠道也可以通过 package.json#openclaw.channel.commands 发布相同的默认值，与其其他包拥有的渠道目录元数据并列。

{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "commands": {
        "nativeCommandsAutoEnabled": true,
        "nativeSkillsAutoEnabled": true
      },
      "preferOver": ["matrix-legacy"]
    }
  }
}

每个渠道条目可以包括：

字段	类型	含义
`schema`	`object`	`channels.<id>` 的 JSON 架构。每个声明的渠道配置条目必需。
`uiHints`	`Record<string, object>`	该渠道配置部分的可选 UI 标签/占位符/敏感提示。
`label`	`string`	当运行时元数据未准备好时，合并到选择器和检查界面中的渠道标签。
`description`	`string`	用于检查和目录界面的简短渠道描述。
`commands`	`object`	用于运行前配置检查的静态本机命令和本机技能自动默认值。
`preferOver`	`string[]`	该渠道在选择界面中应优先于的旧版或较低优先级插件 ID。

替换另一个渠道插件

当您的插件是另一个插件也能提供的渠道 ID 的首选所有者时，请使用 preferOver。常见情况包括重命名的插件 ID、取代捆绑插件的独立插件，或者为保持配置兼容性而保留相同渠道 ID 的维护分支。

{
  "id": "acme-chat",
  "channels": ["chat"],
  "channelConfigs": {
    "chat": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "webhookUrl": { "type": "string" }
        }
      },
      "preferOver": ["chat"]
    }
  }
}

当配置了 channels.chat 时，OpenClaw 会同时考虑渠道 ID 和首选插件 ID。如果选择较低优先级的插件仅仅是因为它是捆绑插件或默认启用的，OpenClaw 将在有效的运行时配置中禁用它，以便一个插件拥有该渠道及其工具。明确的用户选择仍然优先：如果用户明确启用了这两个插件，OpenClaw 将保留该选择并报告重复的渠道/工具诊断信息，而不是静默更改请求的插件集。

请将 preferOver 的范围限定在真正可以提供相同渠道的插件 ID 内。这不是一个通用的优先级字段，它也不会重命名用户配置键。

modelSupport 参考

当 OpenClaw 应该在插件运行时加载之前，从 gpt-5.5 或 claude-sonnet-4.6 等简写模型 ID 推断您的提供商插件时，请使用 modelSupport。

{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}

OpenClaw 应用以下优先级：

显式 provider/model 引用使用拥有 providers 的清单元数据
modelPatterns 优先于 modelPrefixes
如果一个非捆绑插件和一个捆绑插件都匹配，则非捆绑插件获胜
剩余的歧义将被忽略，直到用户或配置指定提供商

字段：

字段	类型	含义
`modelPrefixes`	`string[]`	使用 `startsWith` 与简写模型 ID 匹配的前缀。
`modelPatterns`	`string[]`	在移除配置文件后缀后，与简写模型 ID 进行匹配的 Regex 源。

modelCatalog 参考

当 OpenClaw 需要在加载插件运行时之前知道提供商模型元数据时，请使用 modelCatalogOpenClaw。这是固定目录行、提供商别名、抑制规则和发现模式的清单所属来源。运行时刷新仍属于提供商运行时代码，但清单会告知核心何时需要运行时。

{
  "providers": ["openai"],
  "modelCatalog": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT-5.4",
            "input": ["text", "image"],
            "reasoning": true,
            "contextWindow": 256000,
            "maxTokens": 128000,
            "cost": {
              "input": 1.25,
              "output": 10,
              "cacheRead": 0.125
            },
            "status": "available",
            "tags": ["default"]
          }
        ]
      }
    },
    "aliases": {
      "azure-openai-responses": {
        "provider": "openai",
        "api": "azure-openai-responses"
      }
    },
    "suppressions": [
      {
        "provider": "azure-openai-responses",
        "model": "gpt-5.3-codex-spark",
        "reason": "not available on Azure OpenAI Responses"
      }
    ],
    "discovery": {
      "openai": "static"
    }
  }
}

顶级字段：

字段	类型	含义
`providers`	`Record<string, object>`	归此插件所有的提供商 ID 的目录行。键也应出现在顶级 `providers` 中。
`aliases`	`Record<string, object>`	应解析为归此插件所有的提供商的提供商别名，用于目录或抑制规划。
`suppressions`	`object[]`	来自其他源的模型行，此插件因提供商特定原因而将其抑制。
`discovery`	`Record<string, "static" \| "refreshable" \| "runtime">`	提供商目录是可以从清单元数据读取、刷新到缓存，还是需要运行时。

aliasesOpenClawAPI 参与模型目录规划的提供商所有权查找。别名目标必须是归同一插件所有的顶级提供商。当使用提供商过滤的列表使用别名时，OpenClaw 可以读取所属清单并应用别名 API/基本 URL 覆盖，而无需加载提供商运行时。别名不会扩展未过滤的目录列表；广泛列表仅发出所属的规范提供商行。

suppressions 替换了旧的提供商运行时 suppressBuiltInModel 挂钩。抑制条目仅在提供商归插件所有或声明为指向归此插件所有的提供商的 modelCatalog.aliases 键时才会被遵守。模型解析期间不再调用运行时抑制挂钩。

提供商字段：

字段	类型	含义
`baseUrl`	`string`	此提供商目录中模型的可选默认基本 URL。
`api`	`ModelApi`	此提供商目录中模型的可选默认 API 适配器。
`headers`	`Record<string, string>`	应用于此提供商目录的可选静态标头。
`models`	`object[]`	必需的模型行。没有 `id` 的行将被忽略。

模型字段：

字段	类型	含义
`id`	`string`	提供商本地的模型 ID，不带 `provider/` 前缀。
`name`	`string`	可选显示名称。
`api`	`ModelApi`	可选的每个模型 API 覆盖。
`baseUrl`	`string`	可选的每个模型基础 URL 覆盖。
`headers`	`Record<string, string>`	可选的每个模型静态标头。
`input`	`Array<"text" \| "image" \| "document" \| "audio" \| "video">`	模型接受的模态。
`reasoning`	`boolean`	模型是否公开推理行为。
`contextWindow`	`number`	本机提供商上下文窗口。
`contextTokens`	`number`	当与 `contextWindow` 不同时，可选的有效运行时上下文上限。
`maxTokens`	`number`	已知时的最大输出令牌数。
`cost`	`object`	可选的每百万令牌美元定价，包括可选的 `tieredPricing`。
`compat`	`object`	与 OpenClaw 模型配置兼容性匹配的可选兼容性标志。
`status`	`"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"`	列出状态。仅当该行根本不得出现时才隐藏。
`statusReason`	`string`	与不可用状态一起显示的可选原因。
`replaces`	`string[]`	此模型取代的较旧的提供商本地模型 ID。
`replacedBy`	`string`	用于已弃用行的替换提供商本地模型 ID。
`tags`	`string[]`	选择器和过滤器使用的稳定标签。

抑制字段：

字段	类型	含义
`provider`	`string`	要抑制的上游行的提供商 ID。必须由此插件拥有或声明为拥有的别名。
`model`	`string`	要抑制的提供商本地模型 ID。
`reason`	`string`	直接请求被抑制的行时显示的可选消息。
`when.baseUrlHosts`	`string[]`	在抑制应用之前所需的有效提供商基础 URL 主机的可选列表。
`when.providerConfigApiIn`	`string[]`	在抑制应用之前所需的确切提供商-config `api` 值的可选列表。

请勿在 modelCatalog 中放置仅运行时数据。仅当清单行足够完整，使得提供商过滤列表和选择器界面可以跳过注册表/运行时发现时，才使用 static。当清单行是有用的可列出种子或补充内容，但刷新/缓存稍后可以添加更多行时，使用 refreshable；可刷新行本身不具有权威性。当 OpenClaw 必须加载提供商运行时才能知道该列表时，请使用 runtime。

modelIdNormalization 参考

使用 modelIdNormalization 进行必须在提供商运行时加载之前发生的低成本提供商拥有的模型 ID 清理。这会将短模型名称、提供商本地旧 ID 和代理前缀规则等别名保留在拥有插件清单中，而不是核心模型选择表中。

{
  "providers": ["anthropic", "openrouter"],
  "modelIdNormalization": {
    "providers": {
      "anthropic": {
        "aliases": {
          "sonnet-4.6": "claude-sonnet-4-6"
        }
      },
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  }
}

提供商字段：

字段	类型	含义
`aliases`	`Record<string,string>`	不区分大小写的精确模型 ID 别名。值将按原样返回。
`stripPrefixes`	`string[]`	在查找别名之前要移除的前缀，适用于遗留的提供商/模型重复情况。
`prefixWhenBare`	`string`	当标准化模型 ID 尚未包含 `/` 时要添加的前缀。
`prefixWhenBareAfterAliasStartsWith`	`object[]`	别名查找后的条件性裸 ID 前缀规则，按 `modelPrefix` 和 `prefix` 键控。

providerEndpoints 参考

使用 providerEndpoints 进行端点分类，这是通用请求策略在提供商运行时加载之前必须知道的。Core 仍然拥有每个 endpointClass 的含义；插件清单拥有主机和基础 URL 元数据。

端点字段：

字段	类型	含义
`endpointClass`	`string`	已知的 Core 端点类，例如 `openrouter`、`moonshot-native` 或 `google-vertex`。
`hosts`	`string[]`	映射到端点类的精确主机名。
`hostSuffixes`	`string[]`	映射到端点类的主机后缀。添加 `.` 前缀以进行仅域名后缀匹配。
`baseUrls`	`string[]`	映射到端点类的精确标准化 HTTP(S) 基础 URL。
`googleVertexRegion`	`string`	用于精确全局主机的静态 Google Vertex 区域。
`googleVertexRegionHostSuffix`	`string`	要从匹配主机中剥离的后缀，以暴露 Google Vertex 区域前缀。

providerRequest 参考

使用 providerRequest 表示廉价的请求兼容性元数据，这是通用请求策略在无需加载提供商运行时的情况下所需要的。将特定行为的负载重写保留在提供商运行时钩子或共享的提供商系列辅助程序中。

{
  "providers": ["vllm"],
  "providerRequest": {
    "providers": {
      "vllm": {
        "family": "vllm",
        "openAICompletions": {
          "supportsStreamingUsage": true
        }
      }
    }
  }
}

提供商字段：

字段	类型	含义
`family`	`string`	用于通用请求兼容性决策和诊断的提供商系列标签。
`compatibilityFamily`	`"moonshot"`	用于共享请求辅助程序的可选提供商系列兼容性分组。
`openAICompletions`	`object`	OpenAI 兼容的补全请求标志，目前为 `supportsStreamingUsage`。

modelPricing 参考

当提供商在运行时加载之前需要控制平面定价行为时，请使用 modelPricing。Gateway(网关) 定价缓存会读取此元数据，而无需导入提供商运行时代码。

{
  "providers": ["ollama", "openrouter"],
  "modelPricing": {
    "providers": {
      "ollama": {
        "external": false
      },
      "openrouter": {
        "openRouter": {
          "passthroughProviderModel": true
        },
        "liteLLM": false
      }
    }
  }
}

提供商字段：

字段	类型	含义
`external`	`boolean`	对于绝不应获取 OpenRouter 或 LiteLLM 定价的本地/自托管提供商，请设置 `false`。
`openRouter`	`false \| object`	OpenRouter 定价查找映射。`false` 禁用此提供商的 OpenRouter 查找。
`liteLLM`	`false \| object`	LiteLLM 定价查找映射。`false` 禁用此提供商的 LiteLLM 查找。

源字段：

字段	类型	含义
`provider`	`string`	当外部目录提供商 ID 与 OpenClaw 提供商 ID 不同时的外部目录提供商 ID，例如对于 `zai` 提供商为 `z-ai`。
`passthroughProviderModel`	`boolean`	将包含斜杠的模型 ID 视为嵌套的提供商/模型引用，对于诸如 OpenRouter 之类的代理提供商非常有用。
`modelIdTransforms`	`"version-dots"[]`	额外的外部目录模型 ID 变体。`version-dots` 会尝试像 `claude-opus-4.6` 这样的带点版本 ID。

OpenClaw 提供商索引

OpenClaw Provider Index 是 OpenClaw 拥有的预览元数据，针对那些插件可能尚未安装的提供商。它不是插件清单的一部分。插件清单仍然是已安装插件的权威来源。Provider Index 是内部备用契约，当提供商插件未安装时，未来的可安装提供商和预安装模型选择器界面将使用该契约。

目录权威顺序：

用户配置。
已安装的插件清单 modelCatalog。
通过显式刷新获得的模型目录缓存。
OpenClaw Provider Index 预览行。

Provider Index 不得包含密钥、启用状态、运行时钩子或实时帐户特定的模型数据。其预览目录使用与插件清单相同的 modelCatalog 提供商行形状，但应仅限于稳定的显示元数据，除非 api、baseUrl、定价或兼容性标志等运行时适配器字段有意与已安装的插件清单保持一致。具有实时 /models 发现功能的提供商应通过显式模型目录缓存路径写入刷新的行，而不是进行正常的列出或新手引导调用提供商 API。

Provider Index 条目还可能包含针对那些插件已移出核心或尚未安装的提供商的可安装插件元数据。此元数据反映了渠道目录模式：包名称、npm 安装规范、预期完整性和廉价的身份验证选择标签足以显示可安装的设置选项。一旦安装了插件，其清单优先，并且该提供商的 Provider Index 条目将被忽略。

传统的顶层功能键已弃用。使用 openclaw doctor --fix 将 speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders 和 webSearchProviders 移至 contracts 下；正常的清单加载不再将这些顶层字段视为功能所有权。

清单与 package. 的对比

这两个文件服务于不同的目的：

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

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

如果 OpenClaw 必须在加载插件代码之前知道它，请将其放在 OpenClawopenclaw.plugin.json 中
如果它与打包、入口文件或 npm install 行为有关，请将其放在 npmpackage.json 中

影响设备发现的 package. 字段

一些运行前的插件元数据有意位于 package.json 下的 openclaw 块中，而不是 openclaw.plugin.json 中。openclaw.bundle 和 openclaw.bundle.jsonOpenClaw 不是 OpenClaw 插件约定；原生插件必须使用 openclaw.plugin.json 以及下面支持的 package.json#openclaw 字段。

重要示例：

字段	含义
`openclaw.extensions`	声明原生插件入口点。必须保留在插件包目录内。
`openclaw.runtimeExtensions`	声明已安装软件包的构建 JavaScript 运行时入口点。必须保留在插件包目录内。
`openclaw.setupEntry`	轻量级仅设置入口点，用于新手引导、延迟渠道启动以及只读渠道状态/SecretRef 发现。必须保留在插件包目录内。
`openclaw.runtimeSetupEntry`	声明已安装包的构建 JavaScript 设置入口点。需要 `setupEntry`，必须存在，并且必须保留在插件包目录内。
`openclaw.channel`	廉价的渠道目录元数据，如标签、文档路径、别名和选择文案。
`openclaw.channel.commands`	配置、审核和命令列表界面在加载渠道运行时之前使用的静态本机命令和本机技能自动默认元数据。
`openclaw.channel.configuredState`	轻量级配置状态检查器元数据，可以在不加载完整渠道运行时的情况下回答“是否已存在仅环境设置？”。
`openclaw.channel.persistedAuthState`	轻量级持久化身份验证检查器元数据，可以在不加载完整渠道运行时的情况下回答“是否已登录任何内容？”。
`openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath`	捆绑和外部发布插件的安装/更新提示。
`openclaw.install.defaultChoice`	当有多个安装源可用时的首选安装路径。
`openclaw.install.minHostVersion`	支持的最低 OpenClaw 主机版本，使用如 `>=2026.3.22` 或 `>=2026.5.1-beta.1` 的 semver 下限。
`openclaw.install.expectedIntegrity`	预期的 npm 分发完整性字符串，例如 `sha512-...`；安装和更新流程会根据它验证获取的工件。
`openclaw.install.allowInvalidConfigRecovery`	当配置无效时，允许狭窄的捆绑插件重新安装恢复路径。
`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`	允许仅设置渠道界面在启动期间于完整渠道插件之前加载。

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

在安装和非打包插件源的清单注册表加载期间，会强制执行 openclaw.install.minHostVersion。无效值会被拒绝；在较旧的主机上，较新但有效的值会跳过外部插件。打包的源插件被假定与主机检出版本一致。

当插件发布到 ClawHub 时，官方的按需安装元数据应使用 clawhubSpec；新手引导将其视为首选的远程来源，并在安装后记录 ClawHub 构件事实。对于尚未迁移到 ClawHub 的软件包，npmSpec 仍然是兼容性回退方案。

精确的 npm 版本锁定已经存在于 npmSpec 中，例如 "npmSpec": "@wecom/[email protected]"。官方外部目录条目应将精确规范与 expectedIntegrity 配对，以便当获取的 npm 构件不再匹配锁定版本时，更新流程将失败关闭。为了兼容性，交互式新手引导仍然提供受信任的注册表 npm 规范，包括纯软件包名称和分发标签。目录诊断可以区分精确、浮动、完整性锁定、缺少完整性、软件包名称不匹配和无效默认选择的来源。当存在 expectedIntegrity 但没有有效的 npm 源可以锁定时，它们也会发出警告。当存在 expectedIntegrity 时，安装/更新流程会强制执行它；当省略它时，注册表解析结果将在没有完整性锁定的情况下被记录。

当状态、渠道列表或 SecretRef 扫描需要在未加载完整运行时的情况下识别已配置的帐户时，渠道插件应提供 openclaw.setupEntry。设置入口应公开渠道元数据以及设置安全的配置、状态和密钥适配器；将网络客户端、网关侦听器和传输运行时保留在主扩展入口点中。

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

openclaw.install.allowInvalidConfigRecovery 的范围特意设计得很窄。它不会使任意损坏的配置变为可安装。目前，它仅允许安装流程从特定的过时打包插件升级失败中恢复，例如缺少打包插件路径或该同一打包插件的过时 channels.<id> 条目。不相关的配置错误仍然会阻止安装，并将操作员引导至 openclaw doctor --fix。

openclaw.channel.persistedAuthState 是一个微型检查器模块的包元数据：

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

当设置、诊断、状态或只读存在流程需要在完整的渠道插件加载之前进行廉价的“是/否”身份验证探测时，请使用它。持久化的身份验证状态不是已配置的渠道状态：不要使用此元数据自动启用插件、修复运行时依赖项或决定是否应加载渠道运行时。目标导出应该是一个仅读取持久化状态的小型函数；不要将其通过完整的渠道运行时入口进行路由。

openclaw.channel.configuredState 遵循相同的形状，用于廉价的仅环境配置检查：

{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}

当渠道可以从环境或其他微型非运行时输入回答已配置状态时，请使用它。如果检查需要完整的配置解析或真实的渠道运行时，请将该逻辑保留在插件的 config.hasConfiguredState 挂钩中。

设备发现优先级（重复的插件 ID）

OpenClaw 从多个根目录发现插件。有关原始文件系统扫描顺序，请参阅插件扫描顺序。如果两个设备发现共享相同的 id，则仅保留最高优先级的清单；较低优先级的重复项将被丢弃，而不是与其一起加载。

优先级，从高到低：

配置选定 — 在 plugins.entries.<id> 中显式固定的路径
打包 — 随 OpenClaw 一起提供的插件
全局安装 — 安装到全局 OpenClaw 插件根目录的插件
工作区 — 相对于当前工作区发现的插件

影响：

位于工作区中的打包插件的分叉或过时副本不会屏蔽打包的构建。
要真正用本地插件覆盖打包的插件，请通过 plugins.entries.<id> 固定它，以便其通过优先级胜出，而不是依赖工作区发现。
重复的丢弃项会被记录下来，以便 Doctor 和启动诊断可以指向被丢弃的副本。
配置选择的重复覆盖在诊断中会被表述为显式覆盖，但仍会发出警告，以便过时的分支和意外的影子保持可见。

JSON Schema 要求

每个插件必须附带一个 JSON Schema，即使它不接受任何配置。
空 schema 是可接受的（例如，{ "type": "object", "additionalProperties": false }）。
Schema 在配置读/写时进行验证，而不是在运行时。
当使用新的配置键扩展或派生打包插件时，请同时更新该插件的 openclaw.plugin.json configSchema。打包插件的 schema 是严格的，因此如果在用户配置中添加 plugins.entries.<id>.config.myNewKey 而未将 myNewKey 添加到 configSchema.properties，将在插件运行时加载之前被拒绝。

示例 schema 扩展：

{
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "myNewKey": {
        "type": "string"
      }
    }
  }
}

验证行为

未知的 channels.* 键是错误，除非渠道 id 由插件清单声明。
plugins.entries.<id>、plugins.allow、plugins.deny 和 plugins.slots.* 必须引用可发现的插件 id。未知的 id 是错误。
如果插件已安装但清单或 schema 损坏或缺失，验证将失败，Doctor 将报告插件错误。
如果插件配置存在但插件已禁用，配置将被保留，并在 Doctor + 日志中显示警告。

有关完整的 plugins.* schema，请参阅配置参考。

注

对于原生 OpenClaw 插件，清单是必需的，包括本地文件系统加载。运行时仍会单独加载插件模块；清单仅用于发现 + 验证。
原生清单使用 JSON5 解析，因此只要最终值仍然是对象，就允许注释、尾随逗号和无引号键。
清单加载器仅读取文档化的清单字段。请避免自定义顶级键。
当插件不需要时，channels、providers、cliBackends 和 skills 均可省略。
providerCatalogEntry 必须保持轻量，不应导入广泛的运行时代码；将其用于静态提供商目录元数据或狭窄的发现描述符，而非请求时执行。providerDiscoveryEntry 是旧式拼写，对于现有插件仍然有效。
互斥插件类型通过 plugins.slots.* 选择：kind: "memory" 通过 plugins.slots.memory，kind: "context-engine" 通过 plugins.slots.contextEngine（默认为 legacy）。
在此清单中声明互斥插件类型。运行时入口 OpenClawPluginDefinition.kind 已弃用，仅作为旧插件的兼容性后备保留。
环境变量元数据（setup.providers[].envVars、已弃用的 providerAuthEnvVars 和 channelEnvVars）仅用于声明。状态、审计、cron 交付验证和其他只读界面在将环境变量视为已配置之前，仍会应用插件信任和有效激活策略。
有关需要提供商代码的运行时向导元数据，请参阅提供商运行时钩子。
如果您的插件依赖于原生模块，请记录构建步骤和任何包管理器允许列表要求（例如，pnpm allow-build-scripts + pnpm rebuild <package>）。

Plugin manifest

此文件的作用

最小示例

完整示例

顶级字段参考

生成提供商元数据参考

工具元数据参考

providerAuthChoices 参考

commandAliases 参考

activation 参考

qaRunners 参考

setup 参考

setup.providers 参考

setup 字段

uiHints 参考

contracts 参考

mediaUnderstandingProviderMetadata 参考

channelConfigs 参考

替换另一个渠道插件

modelSupport 参考

modelCatalog 参考

modelIdNormalization 参考

providerEndpoints 参考

providerRequest 参考

modelPricing 参考

OpenClaw 提供商索引

清单与 package. 的对比

影响设备发现的 package. 字段

设备发现优先级（重复的插件 ID）

JSON Schema 要求

验证行为

注

相关内容