插件清单 - OpenClaw 中文文档

本页面仅适用于原生 OpenClaw 插件清单。有关兼容的 bundle 布局，请参见插件 bundles。兼容的 bundle 格式使用不同的清单文件：

Codex bundle: .codex-plugin/plugin.json
Claude bundle: .claude-plugin/plugin.json 或默认的 Claude 组件布局（不带清单）
Cursor bundle: .cursor-plugin/plugin.json

OpenClaw 也会自动检测这些 bundle 布局，但它们不会根据此处描述的 openclaw.plugin.json schema 进行校验。对于兼容的 bundles，OpenClaw 当前会读取 bundle 元数据以及声明的 skill roots、Claude command roots、Claude bundle settings.json 默认值、 Claude bundle LSP 默认值，以及在布局符合 OpenClaw 运行时预期时支持的 hook packs。每个原生 OpenClaw 插件必须在插件根目录下提供一个 openclaw.plugin.json 文件。OpenClaw 使用此清单在不执行插件代码的情况下验证配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。查看完整的插件系统指南：插件。有关原生能力模型和当前外部兼容性指导，请参见：能力模型。

此文件的作用

openclaw.plugin.json 是 OpenClaw 在加载你的插件代码之前读取的元数据。下面的一切都必须足够轻量，才能在不启动插件运行时的情况下检查。 用于：

插件标识、配置校验和配置 UI 提示
认证、引导和设置元数据（别名、自动启用、提供方环境变量、认证选项）
控制平面界面的激活提示
简写模型族归属
静态能力归属快照（contracts）
共享 openclaw qa 主机可以检查的 QA 运行器元数据
合并到目录和校验界面的按通道配置元数据

不要用于： 注册运行时行为、声明代码入口点，或 npm 安装元数据。这些属于你的插件代码和 package.json。

最小示例

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

丰富示例

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter 提供方插件",
  "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。此 id 用于 `plugins.entries.<id>`。
`configSchema`	是	`object`	此插件配置的内联 JSON Schema。
`enabledByDefault`	否	`true`	标记打包插件默认启用。省略它，或设置任何非 `true` 值，都将使插件默认保持禁用。
`enabledByDefaultOnPlatforms`	否	`string[]`	仅在列出的 Node.js 平台上将打包插件标记为默认启用，例如 `["darwin"]`。显式配置仍然优先生效。
`legacyPluginIds`	否	`string[]`	规范化为此 canonical 插件 id 的旧 id。
`autoEnableWhenConfiguredProviders`	否	`string[]`	当认证、配置或模型引用提到这些 provider id 时，应自动启用此插件的 provider id。
`kind`	否	`"memory"` \| `"context-engine"`	声明由 `plugins.slots.*` 使用的独占插件类型。
`channels`	否	`string[]`	此插件拥有的 channel id。用于发现和配置校验。
`providers`	否	`string[]`	此插件拥有的 provider id。
`providerDiscoveryEntry`	否	`string`	轻量级 provider-discovery 模块路径，相对于插件根目录，用于可在不激活完整插件运行时的情况下加载的、清单作用域 provider 目录元数据。
`modelSupport`	否	`object`	由清单拥有的简写模型族元数据，用于在运行时之前自动加载插件。
`modelCatalog`	否	`object`	由此插件拥有的 provider 的声明式模型目录元数据。这是面向控制平面的契约，用于未来的只读列表、引导、模型选择器、别名和抑制，而无需加载插件运行时。
`modelPricing`	否	`object`	provider 拥有的外部定价查询策略。可用于将本地/自托管 provider 排除在远程定价目录之外，或将 provider 引用映射到 OpenRouter/LiteLLM 目录 id，而无需在核心中硬编码 provider id。
`modelIdNormalization`	否	`object`	provider 拥有的模型 id 别名/前缀清理，必须在加载 provider 运行时之前执行。
`providerEndpoints`	否	`object[]`	清单拥有的 endpoint 主机/baseUrl 元数据，供核心在加载 provider 运行时之前对 provider 路由进行分类。
`providerRequest`	否	`object`	供通用请求策略在加载 provider 运行时之前使用的、廉价的 provider 族与请求兼容性元数据。
`cliBackends`	否	`string[]`	此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。
`syntheticAuthRefs`	否	`string[]`	其插件拥有的 synthetic auth hook 应在运行时加载之前、冷启动模型发现期间探测的 provider 或 CLI 后端引用。
`nonSecretAuthMarkers`	否	`string[]`	打包插件拥有的占位 API key 值，表示非密钥的本地、OAuth 或环境凭证状态。
`commandAliases`	否	`object[]`	此插件拥有的命令名，在运行时加载之前应生成感知插件的配置和 CLI 诊断。
`providerAuthEnvVars`	否	`Record<string, string[]>`	已弃用的兼容性环境变量元数据，用于 provider 认证/状态查找。新插件请优先使用 `setup.providers[].envVars`；在弃用窗口期内 OpenClaw 仍会读取此项。
`providerAuthAliases`	否	`Record<string, string>`	认证查找时应复用另一个 provider id 的 provider id，例如共享基础 provider API key 和认证配置文件的 coding provider。
`channelEnvVars`	否	`Record<string, string[]>`	OpenClaw 可在不加载插件代码的情况下检查的廉价 channel 环境变量元数据。用于基于环境变量的 channel 设置或认证界面，供通用启动/配置辅助工具查看。
`providerAuthChoices`	否	`object[]`	供引导选择器、首选 provider 解析和简单 CLI 标志绑定使用的廉价认证选项元数据。
`activation`	否	`object`	用于启动、provider、命令、channel、路由和能力触发加载的廉价激活规划器元数据。仅为元数据；实际行为仍由插件运行时负责。
`setup`	否	`object`	发现和设置界面可在不加载插件运行时的情况下检查的廉价设置/引导描述符。
`qaRunners`	否	`object[]`	在加载插件运行时之前，由共享 `openclaw qa` 主机使用的廉价 QA 运行器描述符。
`contracts`	否	`object`	外部 auth hook、speech、实时转写、实时语音、媒体理解、图像生成、音乐生成、视频生成、web-fetch、web search 和工具所有权的静态能力归属快照。
`mediaUnderstandingProviderMetadata`	否	`Record<string, object>`	为 `contracts.mediaUnderstandingProviders` 中声明的 provider id 提供的廉价媒体理解默认值。
`imageGenerationProviderMetadata`	否	`Record<string, object>`	为 `contracts.imageGenerationProviders` 中声明的 provider id 提供的廉价图像生成认证元数据，包括 provider 拥有的认证别名和 base-url 保护。
`videoGenerationProviderMetadata`	否	`Record<string, object>`	为 `contracts.videoGenerationProviders` 中声明的 provider id 提供的廉价视频生成认证元数据，包括 provider 拥有的认证别名和 base-url 保护。
`musicGenerationProviderMetadata`	否	`Record<string, object>`	为 `contracts.musicGenerationProviders` 中声明的 provider id 提供的廉价音乐生成认证元数据，包括 provider 拥有的认证别名和 base-url 保护。
`toolMetadata`	否	`Record<string, object>`	为 `contracts.tools` 中声明的插件拥有工具提供的廉价可用性元数据。当某个工具在配置、环境变量或认证证据存在之前不应加载运行时，就使用它。
`channelConfigs`	否	`Record<string, object>`	清单拥有的 channel 配置元数据，在运行时加载之前合并到发现和校验界面。
`skills`	否	`string[]`	要加载的 skill 目录，相对于插件根目录。
`name`	否	`string`	人类可读的插件名称。
`description`	否	`string`	在插件界面中显示的简短摘要。
`version`	否	`string`	信息性的插件版本。
`uiHints`	否	`Record<string, object>`	配置字段的 UI 标签、占位符和敏感性提示。

Generation provider metadata reference

生成 provider 元数据字段描述了匹配的 contracts.*GenerationProviders 列表中声明的 provider 的静态 auth 信号。OpenClaw 在 provider 运行时加载之前读取这些字段，因此核心工具可以在不导入每个 provider 插件的情况下决定某个 generation provider 是否可用。这些字段只应用于低成本、声明式的事实。传输、请求转换、token 刷新、凭据验证以及实际的生成行为都留在插件运行时中。

{
  "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[]`	额外的 provider id，应将其计为该 generation provider 的静态 auth 别名。
`authProviders`	否	`string[]`	其已配置 auth 配置文件应计为该 generation provider 的 auth 的 provider id。
`configSignals`	否	`object[]`	用于本地或自托管 provider 的低成本、仅配置可用性信号，这类 provider 可在没有 auth 配置文件或环境变量的情况下配置。
`authSignals`	否	`object[]`	明确的 auth 信号。存在时，它们会替代来自 provider id、`aliases` 和 `authProviders` 的默认信号集。

每个 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`	要在已配置 auth 配置文件中检查的 provider id。
`providerBaseUrl`	否	`object`	可选守卫：仅当引用的已配置 provider 使用允许的 base URL 时，该信号才计入。仅当某个 auth 别名只对特定 API 有效时使用。

每个 providerBaseUrl 守卫支持：

字段	必填	类型	含义
`provider`	是	`string`	应检查其 `baseUrl` 的 provider 配置 id。
`defaultBaseUrl`	否	`string`	当 provider 配置省略 `baseUrl` 时假定使用的 base URL。
`allowedBaseUrls`	是	`string[]`	该 auth 信号允许的 base URL。当已配置或默认的 base URL 与这些规范化后的值都不匹配时，该信号将被忽略。

Tool metadata reference

toolMetadata 使用与 generation provider 元数据相同的 configSignals 和 authSignals 形状，并以 tool 名称作为键。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 会保留现有行为，并在工具契约符合策略时加载所属插件。对于工厂依赖 auth/config 的热路径工具，插件作者应声明 toolMetadata，而不是让核心去导入运行时询问。

providerAuthChoices 参考

每个 providerAuthChoices 条目描述一个 onboarding 或 auth 选择项。OpenClaw 在 provider runtime 加载之前会先读取这些内容。Provider setup 列表会使用这些 manifest 选择项、基于 descriptor 派生的 setup 选择项，以及 install-catalog 元数据，而无需加载 provider runtime。

字段	必填	类型	含义
`provider`	是	`string`	此选择项所属的 provider id。
`method`	是	`string`	要分发到的 auth method id。
`choiceId`	是	`string`	由 onboarding 和 CLI 流程使用的稳定 auth-choice id。
`choiceLabel`	否	`string`	面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。
`choiceHint`	否	`string`	用于选择器的简短帮助文本。
`assistantPriority`	否	`number`	较小的值会在助手驱动的交互式选择器中排得更靠前。
`assistantVisibility`	否	`"visible"` \| `"manual-only"`	在助手选择器中隐藏该选择项，同时仍允许通过手动 CLI 选择。
`deprecatedChoiceIds`	否	`string[]`	应将用户重定向到此替代选择项的旧 choice id。
`groupId`	否	`string`	用于将相关选择项分组的可选 group id。
`groupLabel`	否	`string`	该分组面向用户的标签。
`groupHint`	否	`string`	该分组的简短帮助文本。
`optionKey`	否	`string`	简单单标志 auth 流程使用的内部 option key。
`cliFlag`	否	`string`	CLI 标志名，例如 `--openrouter-api-key`。
`cliOption`	否	`string`	完整的 CLI option 形式，例如 `--openrouter-api-key <key>`。
`cliDescription`	否	`string`	用于 CLI 帮助信息中的描述。
`onboardingScopes`	否	`Array<"text-inference" \| "image-generation">`	该选择项应出现在哪些 onboarding 界面中。如果省略，默认值为 `["text-inference"]`。

commandAliases 参考

当某个插件拥有一个运行时命令名，而用户可能会误把它填进 plugins.allow，或者试图将其作为根 CLI 命令运行时，请使用 commandAliases。OpenClaw 会在不导入插件 runtime 代码的情况下使用这些元数据进行诊断。

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

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

activation 参考

当插件能够低成本声明哪些控制平面事件应将其纳入 activation/load 计划时，请使用 activation。此块是 planner 元数据，不是生命周期 API。它不会注册运行时行为，不会替代 register(...)，也不保证插件代码已经执行。activation planner 会使用这些字段在回退到现有 manifest 所有权元数据之前先缩小候选插件范围，这些元数据包括 providers、channels、commandAliases、setup.providers、contracts.tools 和 hooks。优先使用已经描述所有权的最窄元数据。当这些字段已经表达了关系时，请使用 providers、channels、commandAliases、setup descriptors 或 contracts。当这些所有权字段无法表达时，再使用 activation 作为额外的 planner 提示。对于诸如 claude-cli、codex-cli 或 google-gemini-cli 这类 CLI runtime 别名，请使用顶层 cliBackends； activation.onAgentHarnesses 仅用于那些没有现成所有权字段的嵌入式 agent harness id。 This block is metadata only. It does not register runtime behavior, and it does not replace register(...), setupEntry, or other runtime/plugin entrypoints. Current consumers use it as a narrowing hint before broader plugin loading, so missing non-startup activation metadata usually only costs performance; it should not change correctness while manifest ownership fallbacks still exist. Every plugin should set activation.onStartup intentionally. Set it to true only when the plugin must run during Gateway startup. Set it to false when the plugin is inert at startup and should load only from narrower triggers. Omitting onStartup no longer startup-loads the plugin implicitly; use explicit activation metadata for startup, channel, config, agent-harness, memory, or other narrower activation triggers.

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

| Field | Required | Type | What it means | | ------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | onStartup | No | boolean | 显式的 Gateway 启动激活。每个插件都应设置此项。true 会在启动期间导入插件；false 会保持启动时惰性加载，除非其他匹配的触发器要求加载。 | | onProviders | No | string[] | 在 activation/load 计划中应包含此插件的 provider id。 | | onAgentHarnesses | No | string[] | 在 activation/load 计划中应包含此插件的嵌入式 agent harness runtime id。CLI backend 别名请使用顶层 cliBackends。 | | onCommands | No | string[] | 在 activation/load 计划中应包含此插件的命令 id。 | | onChannels | No | string[] | 在 activation/load 计划中应包含此插件的 channel id。 | | onRoutes | No | string[] | 在 activation/load 计划中应包含此插件的 route 类型。 | | onConfigPaths | No | string[] | 当路径存在且未被显式禁用时，在 startup/load 计划中应包含此插件的根相对配置路径。 | | onCapabilities | No | Array<"provider" \| "channel" \| "tool" \| "hook"> | 控制平面激活规划使用的宽泛能力提示。尽可能优先使用更窄的字段。 | 当前实时消费者：

Gateway startup planning uses activation.onStartup for explicit startup import
command-triggered CLI planning falls back to legacy commandAliases[].cliCommand or commandAliases[].name
agent-runtime startup planning uses activation.onAgentHarnesses for embedded harnesses and top-level cliBackends[] for CLI runtime aliases
channel-triggered setup/channel planning falls back to legacy channels[] ownership when explicit channel activation metadata is missing
startup plugin planning uses activation.onConfigPaths for non-channel root config surfaces such as the bundled browser plugin’s browser block
provider-triggered setup/runtime planning falls back to legacy providers[] and top-level cliBackends[] ownership when explicit provider activation metadata is missing

planner 诊断可以区分显式 activation 提示与 manifest 所有权回退。例如，activation-command-hint 表示匹配到了 activation.onCommands，而 manifest-command-alias 表示 planner 改用了 commandAliases 所有权。这些原因标签用于宿主诊断和测试；插件作者应继续声明最能描述所有权的元数据。

qaRunners 参考

当某个插件在共享的 openclaw qa 根命令下提供一个或多个传输运行器时，使用 qaRunners。请保持此元数据轻量且静态；插件运行时仍通过一个轻量级的 runtime-api.ts 接口负责实际的 CLI 注册，该接口导出 qaRunnerCliRegistrations。

{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "在可丢弃的 homeserver 上运行 Docker 支持的 Matrix 实时 QA 流程"
    }
  ]
}

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

setup 参考

当 setup 和 onboarding 界面在运行时加载之前需要轻量的、由插件拥有的元数据时，使用 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 本地凭据"
          }
        ]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}

顶层 cliBackends 仍然有效，并继续用于描述 CLI 推断后端。setup.cliBackends 是面向 setup 的专用描述字段，用于应保持仅为元数据的控制平面/setup 流程。当存在时，setup.providers 和 setup.cliBackends 是 setup 发现中优先使用的、先描述符再查找的界面。如果描述符仅缩小了候选插件范围，而 setup 仍然需要更丰富的 setup 期运行时钩子，请设置 requiresRuntime: true，并保留 setup-api 作为回退执行路径。 OpenClaw 也会将 setup.providers[].envVars 纳入通用的 provider 认证与环境变量查找中。providerAuthEnvVars 在弃用期内仍通过兼容适配器受支持，但仍使用它的未打包插件会收到清单诊断。新插件应将 setup/status 的环境变量元数据放在 setup.providers[].envVars 上。当没有 setup 条目可用时，或者当 setup.requiresRuntime: false 声明 setup 不需要运行时执行时，OpenClaw 也可以从 setup.providers[].authMethods 推导出简单的 setup 选项。对于自定义标签、CLI 标志、onboarding 范围和助手元数据，显式的 providerAuthChoices 条目仍然是首选。仅当这些描述符足以满足 setup 界面时，才将 requiresRuntime: false 设为 false。OpenClaw 会将显式的 false 视为仅描述符契约，并且不会为了 setup 查找而执行 setup-api 或 openclaw.setupEntry。如果一个仅描述符插件仍然提供了其中任一 setup 运行时条目，OpenClaw 会报告一个附加诊断并继续忽略它。省略 requiresRuntime 会保留旧版回退行为，因此没有添加该标志的现有插件不会被破坏。由于 setup 查找可能会执行插件拥有的 setup-api 代码，规范化后的 setup.providers[].id 和 setup.cliBackends[] 值在所有已发现插件之间必须保持唯一。若所有权有歧义，则会直接失败，而不是根据发现顺序选出一个胜者。当 setup 运行时确实执行时，如果 setup-api 注册了清单描述符未声明的 provider 或 CLI backend，或者某个描述符没有匹配的运行时注册，setup 注册表诊断会报告 descriptor drift。这些诊断是附加性的，不会拒绝旧版插件。

setup.providers 参考

Field	Required	Type	What it means
`id`	Yes	`string`	在 setup 或 onboarding 期间暴露的 provider id。请保持规范化 id 全局唯一。
`authMethods`	No	`string[]`	在无需加载完整运行时的情况下，该 provider 支持的 setup/auth 方法 id。
`envVars`	No	`string[]`	在插件运行时加载前，通用 setup/status 界面可以检查的环境变量。
`authEvidence`	No	`object[]`	适用于能通过非机密标记进行认证的 provider 的廉价本地认证证据检查。

authEvidence is for provider-owned local credential markers that can be verified without loading runtime code. These checks must stay cheap and local: no network calls, no keychain or secret-manager reads, no shell commands, and no provider API probes. Supported evidence entries:

Field	Required	Type	What it means
`type`	Yes	`string`	当前为 `local-file-with-env`。
`fileEnvVar`	No	`string`	包含显式凭据文件路径的环境变量。
`fallbackPaths`	No	`string[]`	当 `fileEnvVar` 缺失或为空时检查的本地凭据文件路径。支持 `${HOME}` 和 `${APPDATA}`。
`requiresAnyEnv`	No	`string[]`	在该证据有效之前，所列环境变量中至少一个必须非空。
`requiresAllEnv`	No	`string[]`	在该证据有效之前，所列环境变量都必须非空。
`credentialMarker`	Yes	`string`	证据存在时返回的非机密标记。
`source`	No	`string`	用于 auth/status 输出的面向用户的来源标签。

setup 字段

字段	必需	类型	含义
`providers`	否	`object[]`	在 setup 和 onboarding 期间暴露的 provider setup 描述符。
`cliBackends`	否	`string[]`	用于基于描述符优先查找 setup 的 setup 期 backend id。请保持规范化 id 全局唯一。
`configMigrations`	否	`string[]`	该插件的 setup 界面所拥有的配置迁移 id。
`requiresRuntime`	否	`boolean`	在描述符查找之后，setup 是否仍需要执行 `setup-api`。

uiHints 参考

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

{
  "uiHints": {
    "apiKey": {
      "label": "API 密钥",
      "help": "用于 OpenRouter 请求",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

每个字段提示可以包含：

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

contracts 参考

仅在 OpenClaw 无需导入插件运行时即可读取的静态能力归属元数据中使用 contracts。

{
  "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"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

每个列表都是可选的：

字段	类型	含义
`embeddedExtensionFactories`	`string[]`	Codex 应用服务器扩展工厂 id，目前为 `codex-app-server`。
`agentToolResultMiddleware`	`string[]`	打包插件可以为其注册工具结果中间件的运行时 id。
`externalAuthProviders`	`string[]`	该插件拥有其外部认证配置文件钩子的 provider id。
`speechProviders`	`string[]`	该插件拥有的语音 provider id。
`realtimeTranscriptionProviders`	`string[]`	该插件拥有的实时转写 provider id。
`realtimeVoiceProviders`	`string[]`	该插件拥有的实时语音 provider id。
`memoryEmbeddingProviders`	`string[]`	该插件拥有的记忆嵌入 provider id。
`mediaUnderstandingProviders`	`string[]`	该插件拥有的媒体理解 provider id。
`imageGenerationProviders`	`string[]`	该插件拥有的图像生成 provider id。
`videoGenerationProviders`	`string[]`	该插件拥有的视频生成 provider id。
`webFetchProviders`	`string[]`	该插件拥有的 Web 抓取 provider id。
`webSearchProviders`	`string[]`	该插件拥有的 Web 搜索 provider id。
`migrationProviders`	`string[]`	该插件为 `openclaw migrate` 拥有的导入 provider id。
`tools`	`string[]`	该插件拥有的代理工具名称。

contracts.embeddedExtensionFactories 保留给仅用于打包的 Codex 应用服务器扩展工厂。打包的工具结果转换应声明 contracts.agentToolResultMiddleware，并改为通过 api.registerAgentToolResultMiddleware(...) 注册。外部插件不能注册工具结果中间件，因为该接缝可以在模型看到之前重写高信任度的工具输出。 Runtime api.registerTool(...) registrations must match contracts.tools. Tool discovery uses this list to load only the plugin runtimes that can own the requested tools. Provider plugins that implement resolveExternalAuthProfiles should declare contracts.externalAuthProviders. Plugins without the declaration still run through a deprecated compatibility fallback, but that fallback is slower and will be removed after the migration window. 打包的记忆嵌入 provider 应为其暴露的每个适配器 id 声明 contracts.memoryEmbeddingProviders，包括诸如 local 之类的内置适配器。独立 CLI 路径使用此清单契约在完整 Gateway 运行时注册 provider 之前，仅加载对应拥有者插件。

mediaUnderstandingProviderMetadata 参考

当某个媒体理解 provider 具有默认模型、自动认证回退优先级，或通用核心辅助程序在运行时加载前需要的原生文档支持时，使用 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"]
    }
  }
}

每个 provider 条目可以包含：

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

channelConfigs 参考

当某个 channel 插件在其运行时代码加载之前需要轻量级的配置元数据时，请使用 channelConfigs。如果没有可用的 setup 条目，或者 setup.requiresRuntime: false 声明 setup 不需要运行时，那么只读的 channel 设置/状态发现可以直接使用这些元数据来处理已配置的外部 channel。 channelConfigs 是插件 manifest 元数据，不是新的顶层用户配置节。用户仍然在 channels.<channel-id> 下配置 channel 实例。OpenClaw 会在插件运行时代码执行之前读取 manifest 元数据，以决定哪个插件拥有该已配置的 channel。对于 channel 插件，configSchema 和 channelConfigs 描述的是不同的路径：

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

声明了 channels[] 的非打包插件也应声明匹配的 channelConfigs 条目。没有这些条目时，OpenClaw 仍然可以加载插件，但在插件运行时代码执行之前，冷路径配置 schema、setup 和 Control UI 界面将无法知道该 channel 所拥有的选项结构。 channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled 和 nativeSkillsAutoEnabled 可以为在 channel 运行时加载之前执行的命令配置检查声明静态的 auto 默认值。打包的 channels 也可以通过 package.json#openclaw.channel.commands 与它们其他归属包的 channel catalog 元数据一起发布相同的默认值。

{
  "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 连接",
      "commands": {
        "nativeCommandsAutoEnabled": true,
        "nativeSkillsAutoEnabled": true
      },
      "preferOver": ["matrix-legacy"]
    }
  }
}

每个 channel 条目可以包含：

字段	类型	含义
`schema`	`object`	`channels.<id>` 的 JSON Schema。每个已声明的 channel config 条目都必须提供。
`uiHints`	`Record<string, object>`	适用于该 channel config 区域的可选 UI 标签/占位符/敏感性提示。
`label`	`string`	当运行时元数据尚未就绪时，会合并到选择器和 inspect 界面的 channel 标签。
`description`	`string`	用于 inspect 和 catalog 界面的简短 channel 描述。
`commands`	`object`	用于运行前配置检查的静态 native command 和 native skill 自动默认值。
`preferOver`	`string[]`	该 channel 在选择界面中应优先于哪些旧插件或较低优先级的插件 id。

替换另一个 channel 插件

当你的插件是某个 channel id 的首选拥有者，而另一个插件也可以提供该 channel 时，请使用 preferOver。常见情况包括：插件 id 重命名、某个独立插件取代了一个打包插件，或者某个维护中的 fork 为了配置兼容性保留了相同的 channel id。

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

当配置了 channels.chat 时，OpenClaw 会同时考虑 channel id 和首选的插件 id。如果较低优先级的插件只是因为它是打包的或默认启用的而被选中，OpenClaw 会在有效运行时配置中禁用它，从而让一个插件独占该 channel 及其工具。显式的用户选择仍然优先：如果用户显式启用了两个插件，OpenClaw 会保留该选择，并报告重复的 channel/tool 诊断，而不是静默地更改请求的插件集合。请将 preferOver 的作用域限制在确实能够提供相同 channel 的插件 id 上。它不是通用的优先级字段，也不会重命名用户配置键。

modelSupport 参考

当 OpenClaw 需要在插件运行时加载之前，根据 gpt-5.5 或 claude-sonnet-4.6 这样的简写 model id 推断你的 provider 插件时，请使用 modelSupport。

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

OpenClaw 按以下优先级应用：

显式的 provider/model 引用使用其所属的 providers manifest 元数据
modelPatterns 优先于 modelPrefixes
如果一个非打包插件和一个打包插件都匹配，则非打包插件胜出
剩余的歧义会被忽略，直到用户或配置指定 provider

字段：

字段	类型	含义
`modelPrefixes`	`string[]`	与简写 model id 进行 `startsWith` 匹配的前缀。
`modelPatterns`	`string[]`	在移除 profile 后缀后，与简写 model id 匹配的正则表达式源码。

modelCatalog 参考

当 OpenClaw 需要在加载插件运行时之前了解 provider model 元数据时，请使用 modelCatalog。这是静态 catalog 行、provider 别名、抑制规则以及发现模式的 manifest 归属来源。运行时刷新仍然属于 provider 运行时代码，但 manifest 会告诉 core 何时需要运行时。

{
  "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": "在 Azure OpenAI Responses 上不可用"
      }
    ],
    "discovery": {
      "openai": "static"
    }
  }
}

顶层字段：

字段	类型	含义
`providers`	`Record<string, object>`	由该插件拥有的 provider id 的 catalog 行。键也应出现在顶层 `providers` 中。
`aliases`	`Record<string, object>`	应解析为某个已拥有 provider 的 provider 别名，用于 catalog 或 suppression 规划。
`suppressions`	`object[]`	来自其他来源、因某个特定 provider 原因而被该插件抑制的 model 行。
`discovery`	`Record<string, "static" \| "refreshable" \| "runtime">`	该 provider catalog 是否可以从 manifest 元数据读取、刷新到缓存，或需要运行时。

aliases 参与 model-catalog 规划中的 provider 所有权查找。别名目标必须是同一插件拥有的顶层 providers。当 provider 过滤列表使用别名时，OpenClaw 可以读取拥有者 manifest，并在不加载 provider 运行时的情况下应用别名 API/base URL 覆盖。别名不会扩展未过滤的 catalog 列表；宽泛列表只会输出拥有者的规范 provider 行。 suppressions 取代了旧的 provider 运行时 suppressBuiltInModel 钩子。只有当 provider 由该插件拥有，或者声明为指向已拥有 provider 的 modelCatalog.aliases 键时，suppression 条目才会被遵守。模型解析期间不再调用运行时 suppression 钩子。 Provider 字段：

字段	类型	含义
`baseUrl`	`string`	该 provider catalog 中模型的可选默认 base URL。
`api`	`ModelApi`	该 provider catalog 中模型的可选默认 API 适配器。
`headers`	`Record<string, string>`	适用于该 provider catalog 的可选静态 headers。
`models`	`object[]`	必填的 model 行。没有 `id` 的行会被忽略。

Model 字段：

字段	类型	含义
`id`	`string`	provider 本地的 model id，不含 `provider/` 前缀。
`name`	`string`	可选显示名称。
`api`	`ModelApi`	可选的逐模型 API 覆盖。
`baseUrl`	`string`	可选的逐模型 base URL 覆盖。
`headers`	`Record<string, string>`	可选的逐模型静态 headers。
`input`	`Array<"text" \| "image" \| "document" \| "audio" \| "video">`	该模型接受的模态。
`reasoning`	`boolean`	该模型是否暴露 reasoning 行为。
`contextWindow`	`number`	provider 原生上下文窗口。
`contextTokens`	`number`	当与 `contextWindow` 不同时，可选的有效运行时上下文上限。
`maxTokens`	`number`	已知情况下的最大输出 token 数。
`cost`	`object`	可选的每百万 token 美元定价，包含可选的 `tieredPricing`。
`compat`	`object`	与 OpenClaw model config 兼容性匹配的可选兼容标志。
`status`	`"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"`	列表状态。仅当该行根本不应出现时才应抑制。
`statusReason`	`string`	在非可用状态下显示的可选原因。
`replaces`	`string[]`	该模型所取代的旧 provider 本地 model id。
`replacedBy`	`string`	已弃用行的替代 provider 本地 model id。
`tags`	`string[]`	供选择器和筛选器使用的稳定标签。

抑制字段：

字段	类型	含义
`provider`	`string`	要抑制的上游行的 provider id。必须由该插件拥有，或声明为指向已拥有别名。
`model`	`string`	要抑制的 provider 本地 model id。
`reason`	`string`	当直接请求被抑制的行时显示的可选消息。
`when.baseUrlHosts`	`string[]`	应用该 suppression 之前所需的有效 provider base URL host 列表（可选）。
`when.providerConfigApiIn`	`string[]`	应用该 suppression 之前所需的精确 provider-config `api` 值列表（可选）。

不要将仅在运行时可用的数据放入 modelCatalog。仅当 manifest 行已经足够完整，使 provider 过滤列表和选择器界面可以跳过 registry/runtime 发现时，才使用 static。当 manifest 行只是有用的种子或补充，但后续刷新/缓存可以增加更多行时，使用 refreshable；refreshable 行本身并不具有权威性。当 OpenClaw 必须加载 provider 运行时才能知道列表时，使用 runtime。

modelIdNormalization 参考

将 modelIdNormalization 用于廉价的、由提供方拥有的 model-id 清理，这必须在提供方运行时加载之前完成。这样可以把短模型名、提供方本地的旧 id，以及代理前缀规则保留在所属插件清单中，而不是放在核心模型选择表里。

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

提供方字段：

字段	类型	含义
`aliases`	`Record<string,string>`	忽略大小写的精确 model-id 别名。返回值保持原样。
`stripPrefixes`	`string[]`	在别名查找前要移除的前缀，适用于旧版提供方/model 重复。
`prefixWhenBare`	`string`	当归一化后的 model id 不包含 `/` 时要添加的前缀。
`prefixWhenBareAfterAliasStartsWith`	`object[]`	别名查找后的条件性裸 id 前缀规则，以 `modelPrefix` 和 `prefix` 为键。

providerEndpoints 参考

将 providerEndpoints 用于端点分类，这种分类必须在提供方运行时加载之前被通用请求策略知晓。核心仍然负责每个 endpointClass 的含义；插件清单负责主机和 base URL 元数据。端点字段：

字段	类型	含义
`endpointClass`	`string`	已知的核心端点类别，例如 `openrouter`、`moonshot-native` 或 `google-vertex`。
`hosts`	`string[]`	映射到该端点类别的精确主机名。
`hostSuffixes`	`string[]`	映射到该端点类别的主机后缀。对仅域后缀匹配时请在前面加 `.`。
`baseUrls`	`string[]`	映射到该端点类别的精确标准化 HTTP(S) base 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 兼容的 completions 请求标志，目前是 `supportsStreamingUsage`。

modelPricing 参考

当某个提供方在运行时加载之前需要控制面定价行为时，请使用 modelPricing。Gateway 定价缓存会在不导入提供方运行时代码的情况下读取这些元数据。

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

提供方字段：

字段	类型	含义
`external`	`boolean`	对本地/自托管提供方设为 `false`，它们不应获取 OpenRouter 或 LiteLLM 定价。
`openRouter`	`false \| object`	OpenRouter 定价查找映射。`false` 会为该提供方禁用 OpenRouter 查找。
`liteLLM`	`false \| object`	LiteLLM 定价查找映射。`false` 会为该提供方禁用 LiteLLM 查找。

来源字段：

字段	类型	含义
`provider`	`string`	当外部目录提供方 id 与 OpenClaw 提供方 id 不同时使用，例如 `zai` 提供方对应 `z-ai`。
`passthroughProviderModel`	`boolean`	将包含斜杠的 model id 视为嵌套的 provider/model 引用，对 OpenRouter 等代理提供方很有用。
`modelIdTransforms`	`"version-dots"[]`	额外的外部目录 model-id 变体。`version-dots` 会尝试带点的版本 id，例如 `claude-opus-4.6`。

OpenClaw Provider Index

OpenClaw Provider Index 是由 OpenClaw 拥有的、面向尚未安装其插件的提供方的预览元数据。它不是插件清单的一部分。插件清单仍然是已安装插件的权威来源。Provider Index 是内部回退契约，未来的可安装提供方和预安装模型选择器界面会在提供方插件未安装时使用它。目录权威顺序：

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

Provider Index 不得包含密钥、启用状态、运行时钩子或实时的、按账户区分的模型数据。它的预览目录使用与插件清单相同的 modelCatalog provider row 形状，但应限制在稳定的显示元数据，除非诸如 api、baseUrl、定价或兼容性标志等运行时适配器字段被有意保持与已安装插件清单一致。具有实时 /models 发现能力的提供方应通过显式模型目录缓存路径写入刷新的行，而不是在普通列表或入门流程中调用提供方 API。 Provider Index 条目也可以携带可安装插件元数据，适用于那些插件已经从 core 移出或尚未安装的提供方。该元数据镜像 channel catalog 模式：包名、npm 安装规格、预期完整性以及廉价的认证选择标签，就足以展示一个可安装的设置选项。一旦插件安装完成，其清单将获胜，Provider Index 中对应的条目会被忽略。旧的顶层能力键已弃用。请使用 openclaw doctor --fix 将 speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders 和 webSearchProviders 移到 contracts 下；正常的清单加载不再将这些顶层字段视为能力归属。

Manifest 与 package.json

这两个文件用途不同：

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

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

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

影响发现的 package.json 字段

Some pre-runtime plugin metadata intentionally lives in package.json under the openclaw block instead of openclaw.plugin.json. openclaw.bundle and openclaw.bundle.json are not OpenClaw plugin contracts; native plugins must use openclaw.plugin.json plus the supported package.json#openclaw fields below. 重要示例：

Field	What it means
`openclaw.extensions`	Declares native plugin entrypoints. Must stay inside the plugin package directory.
`openclaw.runtimeExtensions`	Declares built JavaScript runtime entrypoints for installed packages. Must stay inside the plugin package directory.
`openclaw.setupEntry`	Lightweight setup-only entrypoint used during onboarding, deferred channel startup, and read-only channel status/SecretRef discovery. Must stay inside the plugin package directory.
`openclaw.runtimeSetupEntry`	Declares the built JavaScript setup entrypoint for installed packages. Requires `setupEntry`, must exist, and must stay inside the plugin package directory.
`openclaw.channel`	Cheap channel catalog metadata like labels, docs paths, aliases, and selection copy.
`openclaw.channel.commands`	Static native command and native skill auto-default metadata used by config, audit, and command-list surfaces before channel runtime loads.
`openclaw.channel.configuredState`	Lightweight configured-state checker metadata that can answer “does env-only setup already exist?” without loading the full channel runtime.
`openclaw.channel.persistedAuthState`	Lightweight persisted-auth checker metadata that can answer “is anything already signed in?” without loading the full channel runtime.
`openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath`	Install/update hints for bundled and externally published plugins.
`openclaw.install.defaultChoice`	Preferred install path when multiple install sources are available.
`openclaw.install.minHostVersion`	Minimum supported OpenClaw host version, using a semver floor like `>=2026.3.22` or `>=2026.5.1-beta.1`.
`openclaw.install.expectedIntegrity`	Expected npm dist integrity string such as `sha512-...`; install and update flows verify the fetched artifact against it.
`openclaw.install.allowInvalidConfigRecovery`	Allows a narrow bundled-plugin reinstall recovery path when config is invalid.
`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`	Lets setup-only channel surfaces load before the full channel plugin during startup.

清单元数据决定在运行时加载前哪些 provider/channel/setup 选项会出现在 onboarding 中。package.json#openclaw.install 告诉 onboarding 在用户选择这些选项之一时如何获取或启用该插件。不要把安装提示移到 openclaw.plugin.json 中。 openclaw.install.minHostVersion 在非 bundled 插件来源的安装和清单注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会在旧主机上跳过外部插件。bundled source 插件被假定与主机 checkout 同版本。官方按需安装元数据在插件发布到 ClawHub 时应使用 clawhubSpec；onboarding 会将其视为首选远程来源，并在安装后记录 ClawHub 工件事实。npmSpec 仍然是尚未迁移到 ClawHub 的包的兼容性回退。精确的 npm 版本锁定已经存在于 npmSpec 中，例如 "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"。官方外部目录条目应将精确规格与 expectedIntegrity 配对，这样如果获取到的 npm 工件不再匹配锁定的发布版本，更新流程就会关闭失败。为了兼容性，交互式 onboarding 仍然提供受信任注册表的 npm 规格，包括裸包名和 dist-tag。目录诊断可以区分精确、浮动、带完整性固定、缺失完整性、包名不匹配以及无效默认选择来源。它们还会在存在 expectedIntegrity 但没有可用来固定它的有效 npm 来源时发出警告。当存在 expectedIntegrity 时，安装/更新流程会强制执行它；当它省略时，注册表解析会被记录下来，但不会附加完整性固定。当 status、channel 列表或 SecretRef 扫描需要在加载完整运行时之前识别已配置账户时，channel 插件应提供 openclaw.setupEntry。设置入口应暴露 channel 元数据以及设置安全的 config、status 和 secrets 适配器；把网络客户端、gateway 监听器和传输运行时保留在主扩展入口点中。运行时入口点字段不会覆盖源入口点字段的包边界检查。例如，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"
      }
    }
  }
}

当设置、doctor、status 或只读存在性流程在完整 channel 插件加载前需要一个廉价的认证是/否探测时使用它。持久化认证状态不是已配置的 channel 状态：不要使用这些元数据来自动启用插件、修复运行时依赖，或决定是否应该加载某个 channel 运行时。目标导出应当是一个只读取持久化状态的小函数；不要通过完整的 channel 运行时 barrel 去路由它。 openclaw.channel.configuredState 采用相同的结构，用于廉价的仅环境变量已配置检查：

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

当某个 channel 能从环境变量或其他很小的非运行时输入中回答已配置状态时使用它。如果检查需要完整的配置解析或真实的 channel 运行时，请把该逻辑保留在插件的 config.hasConfiguredState 钩子中。

发现优先级（重复的插件 id）

OpenClaw 会从多个根目录发现插件（捆绑、全局安装、工作区、显式配置选择的路径）。如果两次发现共享相同的 id，则只保留优先级最高的 manifest；较低优先级的重复项会被丢弃，而不会与其并列加载。优先级从高到低：

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

影响：

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

JSON Schema 要求

每个插件都必须提供 JSON Schema，即使它不接受任何配置。
空 schema 是可以接受的（例如，{ "type": "object", "additionalProperties": false }）。
Schema 会在配置读写时进行验证，而不是在运行时。
当扩展或分叉捆绑插件并加入新的配置键时，请同时更新该插件的 openclaw.plugin.json 中的 configSchema。捆绑插件的 schema 很严格，因此如果没有在 configSchema.properties 中添加 myNewKey，就在用户配置中添加 plugins.entries.<id>.config.myNewKey，会在插件运行时加载之前被拒绝。

示例 schema 扩展示例：

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

校验行为

未知的 channels.* 键都是错误，除非该 channel id 已由插件 manifest 声明。
plugins.entries.<id>、plugins.allow、plugins.deny 和 plugins.slots.* 必须引用可发现的插件 id。未知 id 是错误。
如果某个插件已安装，但其 manifest 或 schema 损坏或缺失，校验会失败，Doctor 会报告该插件错误。
如果插件配置存在但插件已被禁用，配置会被保留，并且 Doctor + 日志会显示一个警告。

完整的 plugins.* schema 请参见配置参考。

注意事项

manifest 是 OpenClaw 原生插件的必需项，包括本地文件系统加载。运行时仍然会单独加载插件模块；manifest 仅用于发现 + 校验。
原生 manifest 使用 JSON5 解析，因此只要最终值仍然是对象，就接受注释、尾随逗号和未加引号的键。
manifest 加载器只读取文档中说明的 manifest 字段。请避免使用自定义顶层键。
当插件不需要这些字段时，channels、providers、cliBackends 和 skills 都可以省略。
providerDiscoveryEntry 必须保持轻量，不应导入大范围运行时代码；应将其用于静态 provider 目录元数据或较窄的发现描述符，而不是请求时执行。
独占插件类型通过 plugins.slots.* 选择：通过 plugins.slots.memory 选择 kind: "memory"，通过 plugins.slots.contextEngine 选择 kind: "context-engine"（默认 legacy）。
请在此 manifest 中声明独占插件类型。运行时入口 OpenClawPluginDefinition.kind 已废弃，仅作为旧插件的兼容回退保留。
环境变量元数据（setup.providers[].envVars、已废弃的 providerAuthEnvVars 和 channelEnvVars）仅具有声明性。状态、审计、cron 投递校验以及其他只读界面在将 env var 视为已配置之前，仍会应用插件信任与有效激活策略。
关于需要 provider 代码的运行时向导元数据，请参见Provider runtime hooks。
如果你的插件依赖原生模块，请说明构建步骤以及任何包管理器允许列表要求（例如，pnpm allow-build-scripts + pnpm rebuild <package>）。

构建插件

插件入门。

插件架构

内部架构和能力模型。

SDK 概览

插件 SDK 参考和子路径导入。

概览

插件

技能

自动化与任务

工具

智能体协作

Documentation Index

​此文件的作用

​最小示例

​丰富示例

​顶层字段参考

​Generation provider metadata reference

​Tool metadata reference

​providerAuthChoices 参考

​commandAliases 参考

​activation 参考

​qaRunners 参考

​setup 参考

​setup.providers 参考

​setup 字段

​uiHints 参考

​contracts 参考

​mediaUnderstandingProviderMetadata 参考

​channelConfigs 参考

​替换另一个 channel 插件

​modelSupport 参考

​modelCatalog 参考

​modelIdNormalization 参考

​providerEndpoints 参考

​providerRequest 参考

​modelPricing 参考

​OpenClaw Provider Index

​Manifest 与 package.json

​影响发现的 package.json 字段

​发现优先级（重复的插件 id）

​JSON Schema 要求

​校验行为

​注意事项

​相关内容

构建插件

插件架构

SDK 概览

此文件的作用

最小示例

丰富示例

顶层字段参考

Generation provider metadata reference

Tool metadata reference

providerAuthChoices 参考

commandAliases 参考

activation 参考

qaRunners 参考

setup 参考

setup.providers 参考

setup 字段

uiHints 参考

contracts 参考

mediaUnderstandingProviderMetadata 参考

channelConfigs 参考

替换另一个 channel 插件

modelSupport 参考

modelCatalog 参考

modelIdNormalization 参考

providerEndpoints 参考

providerRequest 参考

modelPricing 参考

OpenClaw Provider Index

Manifest 与 package.json

影响发现的 package.json 字段

发现优先级（重复的插件 id）

JSON Schema 要求

校验行为

注意事项

相关内容