插件清单

此页面介绍 OpenClaw 原生插件清单 openclaw.plugin.json。有关兼容的捆绑包布局（Codex、Claude、Cursor），请参阅插件捆绑包。

兼容的捆绑包格式改用其各自的清单文件：

• Codex 捆绑包：.codex-plugin/plugin.json
• Claude 捆绑包：.claude-plugin/plugin.json，或不含清单的默认 Claude 组件布局
• Cursor 捆绑包：.cursor-plugin/plugin.json

OpenClaw 会自动检测这些布局，但不会根据下方的 openclaw.plugin.json schema 对其进行验证。对于兼容的捆绑包，当布局符合 OpenClaw 的运行时预期时，OpenClaw 会读取捆绑包元数据、已声明的 skill 根目录、Claude 命令根目录、Claude settings.json 默认值、Claude LSP 默认值以及支持的钩子包。

每个 OpenClaw 原生插件都必须在插件根目录中提供 openclaw.plugin.json。OpenClaw 读取该文件，以便在不执行插件代码的情况下验证配置。清单缺失或无效会阻止配置验证，并被视为插件错误。

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

此文件的作用

openclaw.plugin.json 是 OpenClaw 在加载你的插件代码之前读取的元数据。其中的所有内容都必须足够轻量，无需启动插件运行时即可检查。

它适用于：

• 插件身份、配置验证和配置 UI 提示
• 身份验证、新手引导和设置元数据（别名、自动启用、提供商环境变量、身份验证选项）
• 控制平面界面的激活提示
• 模型系列归属的简写形式
• 静态能力归属快照（contracts）
• 仪表板小组件的数据绑定和操作动词
• 插件启用期间应存在的静态 MCP 服务器
• 共享 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"],
  "setup": {
    "providers": [
      {
        "id": "openrouter",
        "envVars": ["OPENROUTER_API_KEY"]
      }
    ]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API 密钥",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API 密钥",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API 密钥",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

顶层字段参考

MCP 服务器参考

mcpServers 允许原生插件提供 MCP 服务器（包括 MCP App），而无需操作员在 openclaw.json 中重复定义其静态进程：

{
  "mcpServers": {
    "example": {
      "transport": "stdio",
      "command": "node",
      "args": ["./mcp-server.js"]
    }
  }
}

仅当所属插件启用时，OpenClaw 才会包含这些服务器。相对的 command、args、cwd 和 workingDirectory 路径从插件根目录解析。用户配置仍具有最终决定权：mcp.servers.<name> 可以替换插件默认值，也可以将 enabled: false 设为省略该服务器。MCP App 渲染和服务器工具调用仍需满足常规 MCP Apps 设置和有效工具策略；声明服务器不会绕过任一边界。

dashboard 参考

dashboard 允许已启用的插件向获得授权的 dashboard 小组件公开现有 Gateway 网关 RPC，而无需在核心中添加插件策略。数据绑定必须指定同一插件通过 operator.read 注册的方法；操作动词必须指定该插件通过 operator.write 注册的方法。如果不匹配，插件将在注册期间被拒绝。

{
  "dashboard": {
    "dataBindings": [
      {
        "id": "items.list",
        "method": "example.items.list",
        "description": "列出示例项目。"
      }
    ],
    "actionVerbs": [
      {
        "id": "refresh",
        "method": "example.items.refresh",
        "description": "刷新示例项目。",
        "paramShape": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "force": { "type": "boolean" }
          }
        }
      }
    ]
  }
}

清单 ID 仅在插件内有效。小组件授权使用 <plugin-id>.<id>，例如 example.items.list 和 example.refresh。为了使持久化授权命名空间明确无歧义，OpenClaw 会将插件 ID 段中的 % 和 . 分别转义为 %25 和 %2E；普通插件 ID 保持自然形式。paramShape 是可选的 JSON Schema，在 OpenClaw 调用插件 RPC 之前应用于操作参数对象。

目录参考

catalog 为插件浏览器提供可选的显示提示。宿主可以忽略这些提示。它们绝不会安装或启用插件，也不会更改插件的运行时行为或信任级别。

{
  "catalog": {
    "featured": true,
    "order": 10
  }
}

生成提供商元数据参考

生成提供商元数据字段描述在匹配的 contracts.*GenerationProviders 列表中声明的提供商的静态身份验证信号。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"]
          }
        }
      ]
    }
  }
}

每个元数据条目支持：

每个 configSignals 条目支持：

每个 mode 守卫支持：

每个 authSignals 条目支持：

每个 providerBaseUrl 守卫支持：

工具元数据参考

toolMetadata 使用与生成提供商元数据相同的 configSignals 和 authSignals 结构，并以工具名称作为键。contracts.tools 声明所有权。toolMetadata 声明低成本的可用性依据，使 OpenClaw 无需仅为让工具工厂返回 null 而导入插件运行时。

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

toolMetadata 条目除接受上面的共享 configSignals/authSignals 字段外，还接受 optional（将工具标记为插件激活的非必要条件）和 replaySafe（将工具执行标记为可在模型轮次未完成后安全重试）。

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

providerAuthChoices 参考

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

当 appGuidedDiscovery 为 true 时，匹配的提供商身份验证方法必须公开 appGuidedSetup.detect 和 appGuidedSetup.prepare。检测必须是 只读的：不得登录、拉取模型、下载或写入配置。准备阶段会重新检查 选中的确切模型并返回配置提案；OpenClaw 会隔离地对该提案进行实时测试， 并仅在成功后提交。

commandAliases 参考

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

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

activation 参考

当插件可以低成本声明哪些控制平面事件应将其纳入激活/加载计划时，请使用 activation。

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

优先使用已能描述所有权的最精确元数据。当 providers、channels、commandAliases、设置描述符或 contracts 能表达这种关系时，请使用这些字段。对于无法由这些所有权字段表示的额外规划器提示，请使用 activation。对于 claude-cli、my-cli 或 google-gemini-cli 等 CLI 运行时别名，请使用顶层 cliBackends；activation.onAgentHarnesses 仅用于尚无所有权字段的嵌入式 agent harness ID。

每个插件都应有意设置 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"]
  }
}

当前实时使用方：

• Gateway 网关启动规划使用 activation.onStartup 进行显式启动导入。
• 由命令触发的 CLI 规划会回退到旧版 commandAliases[].cliCommand 或 commandAliases[].name。
• Agent 运行时启动规划对嵌入式 harness 使用 activation.onAgentHarnesses，对 CLI 运行时别名使用顶层 cliBackends[]。
• 当缺少显式渠道激活元数据时，由渠道触发的设置/渠道规划会回退到旧版 channels[] 所有权。
• 启动插件规划对非渠道根配置界面使用 activation.onConfigPaths，例如内置浏览器插件的 browser 块。
• 当缺少显式提供商激活元数据时，由提供商触发的设置/运行时规划会回退到旧版 providers[] 和顶层 cliBackends[] 所有权。

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

qaRunners 参考

当插件在共享 openclaw qa 根命令下提供一个或多个传输运行器时， 请使用 qaRunners。此元数据应保持轻量且静态；插件 运行时仍通过轻量级 runtime-api.ts 界面负责实际的 CLI 注册， 该界面导出匹配的 qaRunnerCliRegistrations。可选的 adapterFactory 可将传输协议公开给共享 QA 场景，而不 更改已注册命令的运行器。

{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "针对一次性 homeserver 运行由 Docker 支持的 Matrix 实时 QA 通道"
    }
  ]
}

adapterFactory ID 必须与 commandName 匹配。不要为 清单中不存在的命令导出注册项。

设置参考

当设置和新手引导界面需要在运行时加载前获取轻量的插件自有元数据时，请使用 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.providers 和 setup.cliBackends 是设置发现优先使用的描述符优先查找界面。如果描述符仅缩小候选插件范围，而设置仍需要更丰富的设置时运行时钩子，请设置 requiresRuntime: true，并保留 setup-api 作为回退执行路径。

OpenClaw 会在通用提供商身份验证和环境变量查找中包含 setup.providers[].envVars。请将设置和状态环境元数据放在那里。

当计费或组织级凭据必须激活 resolveUsageAuth、但不能成为推理凭据时，请使用 providerUsageAuthEnvVars。这些名称会加入工作区 dotenv 阻止机制、ACP 子进程剥离、沙箱密钥过滤和广泛的密钥清理。提供商运行时仍会在 resolveUsageAuth 中读取并分类该值。

当没有可用的设置条目，或 setup.requiresRuntime: false 声明无需设置运行时时，OpenClaw 也可以从 setup.providers[].authMethods 派生简单的设置选项。对于自定义标签、CLI 标志、新手引导范围和助手元数据，仍优先使用显式的 providerAuthChoices 条目。

仅当这些描述符足以支持设置界面时，才设置 requiresRuntime: false。OpenClaw 会将显式的 false 视为仅描述符契约，并且不会执行 setup-api 或 openclaw.setupEntry 进行设置查找。如果仅描述符插件仍提供其中一个设置运行时条目，OpenClaw 会报告一条附加诊断并继续忽略该条目。省略 requiresRuntime 会保留旧版回退行为，从而避免已添加描述符但未添加该标志的现有插件发生故障。

由于设置查找可能执行插件自有的 setup-api 代码，规范化后的 setup.providers[].id 和 setup.cliBackends[] 值必须在已发现的插件中保持唯一。所有权存在歧义时会以关闭方式失败，而不是根据发现顺序选择一个结果。

当设置运行时确实执行时，如果 setup-api 注册了清单描述符未声明的提供商或 CLI 后端，或者某个描述符没有匹配的运行时注册项，设置注册表诊断会报告描述符漂移。这些诊断是附加性的，不会拒绝旧版插件。

setup.providers 参考

authEvidence 用于无需加载运行时代码即可验证的提供商自有本地凭据标记。这些检查必须保持轻量且仅限本地：不得进行网络调用，不得读取钥匙串或密钥管理器，不得执行 shell 命令，也不得探测提供商 API。

支持的证据条目：

设置字段

uiHints 参考

uiHints 是从配置字段名称到简短渲染提示的映射。键可使用点号表示嵌套配置字段，但任何路径段都不能是 __proto__、constructor 或 prototype；设置过程会拒绝这些名称。

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

每个字段提示可包含：

contracts 参考

仅将 contracts 用于 OpenClaw 无需导入插件运行时即可读取的静态能力所有权元数据。

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"],
    "trustedToolPolicies": ["workflow-budget"],
    "externalAuthProviders": ["acme-ai"],
    "embeddingProviders": ["openai-compatible"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "mediaUnderstandingProviders": ["openai"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "musicGenerationProviders": ["stability-audio"],
    "documentExtractors": ["example-docs"],
    "webContentExtractors": ["firecrawl"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "workerProviders": ["example-worker"],
    "usageProviders": ["acme-ai"],
    "migrationProviders": ["hermes"],
    "gatewayMethodDispatch": ["authenticated-request"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

每个列表均为可选：

contracts.embeddedExtensionFactories 保留用于仅限内置 Codex app-server 的扩展工厂。内置工具结果转换应声明 contracts.agentToolResultMiddleware，并改为使用 api.registerAgentToolResultMiddleware(...) 注册。只有在显式启用的情况下，已安装插件才能使用同一中间件接缝，并且仅限其在 contracts.agentToolResultMiddleware 中声明的运行时。

需要主机可信工具执行前策略层级的已安装插件，必须在 contracts.trustedToolPolicies 中声明每个已注册的本地 ID，并且必须显式启用。内置插件继续使用现有的可信策略路径，但具有未声明策略 ID 的已安装插件会在注册前被拒绝。策略 ID 的作用域限定于注册它的插件，因此两个插件可以同时声明和注册 workflow-budget；单个插件不得重复注册同一本地 ID。

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

实现 resolveExternalAuthProfiles 的提供商插件应声明 contracts.externalAuthProviders；未声明的外部身份验证钩子会被忽略。

同时实现 resolveUsageAuth 和 fetchUsageSnapshot 的提供商插件，应在 contracts.usageProviders 中声明每个自动发现的提供商 ID。用量发现会在加载运行时代码前读取此契约，然后仅加载已声明的所有者，并在加载后验证这两个钩子。

通用嵌入提供商应为使用 api.registerEmbeddingProvider(...) 注册的每个适配器声明 contracts.embeddingProviders。对于可复用向量生成（包括记忆搜索所使用的提供商），请使用通用契约。contracts.memoryEmbeddingProviders 是已弃用的记忆专用兼容机制，仅在现有提供商迁移到通用嵌入提供商接缝期间保留。

工作节点提供商必须在 contracts.workerProviders 中声明每个 api.registerWorkerProvider(...) ID。核心会在调用 provision 前持久化长期意图；提供商会在分配外部资源前验证其设置，并且使用同一操作 ID 的重复调用必须接管同一租约。核心还会持久化该已验证设置的快照，并将其与 leaseId 一起传给 inspect({ leaseId, profile }) 和 destroy({ leaseId, profile })，即使指定的配置文件已被更改或删除也是如此。销毁操作具有幂等性，检查操作返回已关闭的 active / destroyed / unknown 状态联合类型，SSH 私钥材料仅通过 SecretRef 引用。已配置的 SSH 端点还必须包含来自可信配置输出的公共 hostKey，其格式必须严格为 algorithm base64，不得包含主机名或注释，以便核心在连接前固定该主机。生成动态身份引用的提供商可实现权威的 resolveSshIdentity({ leaseId, profile, keyRef })；未实现该功能的提供商使用核心的通用机密解析器。权威的 unknown 会使活动的本地记录成为孤立记录；在持久化销毁请求后，它会确认资源已拆除。

contracts.gatewayMethodDispatch 当前接受 "authenticated-request"。它是一个 API 卫生门禁，适用于有意在进程内分派 Gateway 网关控制平面方法的原生插件 HTTP 路由，而不是防范恶意原生插件的沙箱。仅将其用于经过严格审查、且已要求 Gateway 网关 HTTP 身份验证的内置/操作员界面。只有当获得权限的路由同时声明 auth: "gateway" 和该路由专用的 gatewayRuntimeScopeSurface: "trusted-operator" 时，它才能在 Gateway 网关根工作准入关闭期间继续访问；同一插件中的普通同级路由仍受准入边界限制。这样可在不授予整个插件准入绕过权限的情况下，确保暂停状态和恢复操作仍可访问。应在分派之外对解析和响应整形进行严格限制；实质性或修改性工作必须通过 Gateway 网关方法分派执行，由后者负责准入和权限范围强制执行。

configContracts 参考

当通用核心辅助程序需要使用清单所拥有的配置行为、但不应导入插件运行时时，请使用 configContracts：危险标志检测、SecretRef 迁移目标以及旧版配置路径收窄。

{
  "configContracts": {
    "compatibilityMigrationPaths": ["legacyProvider"],
    "compatibilityRuntimePaths": ["legacyProvider.webhook"],
    "dangerousFlags": [
      {
        "path": "accounts.*.allowUnverifiedSenders",
        "equals": true
      }
    ],
    "secretInputs": {
      "bundledDefaultEnabled": false,
      "paths": [
        {
          "path": "routes.*.secret",
          "expected": "string",
          "ownerKind": "route"
        }
      ]
    }
  }
}

每个 dangerousFlags 条目支持：

secretInputs 支持：

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"],
      "documentModels": {
        "pdf": {
          "textExtraction": "example-doc-text-latest",
          "image": "example-doc-vision-latest"
        }
      }
    }
  }
}

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

channelConfigs 参考

当渠道插件在运行时加载前需要轻量级配置元数据时，请使用 channelConfigs。如果没有可用的设置条目，或 setup.requiresRuntime: false 声明无需设置运行时，则只读渠道设置/状态发现可以直接将此元数据用于已配置的外部渠道。

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

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

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

声明 channels[] 的非内置插件还应声明匹配的 channelConfigs 条目。如果没有这些条目，OpenClaw 仍可加载插件，但冷路径配置架构、设置和 Control UI 界面在插件运行时执行前，无法得知渠道所拥有的选项结构或仅用于显示的 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": "主服务器 URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix 主服务器连接",
      "commands": {
        "nativeCommandsAutoEnabled": true,
        "nativeSkillsAutoEnabled": true
      },
      "preferOver": ["matrix-legacy"]
    }
  }
}

每个渠道条目可以包含：

替换另一个渠道插件

当你的插件是某个渠道 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 会在有效运行时配置中将其禁用，从而由一个插件独占该渠道及其工具。用户的显式选择仍然优先：如果用户显式启用了两个插件（通过 plugins.allow 或实质性的 plugins.entries 配置），OpenClaw 会保留该选择，并报告渠道/工具重复诊断，而不是静默更改请求的插件集。

请将 preferOver 仅限用于确实能够提供同一渠道的插件 ID。它不是通用优先级字段，也不会重命名用户配置键。

modelSupport 参考

如果 OpenClaw 应在插件运行时加载前，根据 gpt-5.6-sol 或 claude-sonnet-4.6 等简写模型 ID 推断你的提供商插件，请使用 modelSupport。

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

OpenClaw 按以下优先级处理：

• 显式 provider/model 引用使用所属 providers 的清单元数据
• modelPatterns 优先于 modelPrefixes
• 如果一个非内置插件和一个内置插件均匹配，则非内置插件优先
• 其余歧义会被忽略，直到用户或配置指定提供商

字段：

modelPatterns 条目通过 compileSafeRegex 编译，该机制会拒绝包含嵌套重复的模式（例如 (a+)+$）。未通过安全检查的模式会被静默跳过，与语法无效的正则表达式相同。请保持模式简单，并避免嵌套量词。

modelCatalog 参考

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

{
  "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"
    }
  }
}

顶层字段：

aliases 参与模型目录规划的提供商所有权查找。别名目标必须是同一插件拥有的顶层提供商。当按提供商筛选的列表使用别名时，OpenClaw 无需加载提供商运行时，即可读取所属清单并应用别名 API/基础 URL 覆盖。别名不会扩展未筛选的目录列表；宽泛列表只会输出所属的规范提供商行。

suppressions 取代旧的提供商运行时 suppressBuiltInModel 钩子。仅当提供商由该插件拥有，或声明为指向所属提供商的 modelCatalog.aliases 键时，抑制条目才会生效。在模型解析期间不再调用运行时抑制钩子。

提供商字段：

模型字段：

抑制字段：

不要在 modelCatalog 中放置仅供运行时使用的数据。仅当清单行足够完整，使按提供商筛选的列表和选择器界面能够跳过注册表/运行时发现时，才使用 static。当清单行可用作有价值的可列出种子或补充项，但之后刷新/缓存可以添加更多行时，使用 refreshable；可刷新行本身并非权威数据。当 OpenClaw 必须加载提供商运行时才能获知列表时，使用 runtime。

modelIdNormalization 参考

对于必须在提供商运行时加载前执行的低开销、由提供商所有的模型 ID 清理，请使用 modelIdNormalization。这样可将短模型名称、提供商本地旧版 ID 和代理前缀规则等别名保留在所属插件的清单中，而不是放入核心模型选择表。

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

提供商字段：

providerEndpoints 参考

对于通用请求策略在提供商运行时加载前必须获知的端点分类，请使用 providerEndpoints。核心仍负责定义每个 endpointClass 的含义；插件清单负责主机和基础 URL 元数据。

正式外置的提供商插件不包含在核心发行版中，因此在安装前无法看到 其清单。其 providerEndpoints 还必须镜像到 scripts/lib/official-external-provider-catalog.json 中，以便 在没有该插件时端点分类仍可正常工作；契约测试会强制确保镜像一致。

端点字段：

providerRequest 参考

对于通用请求策略无需加载提供商运行时便能使用的低开销请求兼容性元数据，请使用 providerRequest。特定行为的载荷重写应保留在提供商运行时钩子或共享提供商系列辅助程序中。

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

提供商字段：

secretProviderIntegrations 参考

当插件可以发布可复用的 SecretRef exec 提供商预设时，请使用 secretProviderIntegrations。OpenClaw 会在插件运行时加载前读取此元数据，将插件所有权存储在 secrets.providers.<alias>.pluginIntegration 中，并将实际密钥解析交由 SecretRef 运行时处理。预设仅对内置插件以及从托管插件安装根目录中发现的已安装插件公开，例如通过 git 和 ClawHub 安装的插件。

{
  "secretProviderIntegrations": {
    "secret-store": {
      "providerAlias": "team-secrets",
      "displayName": "Team secrets",
      "source": "exec",
      "command": "${node}",
      "args": ["./bin/resolve-secrets.mjs"]
    }
  }
}

映射键是集成 ID。如果省略 providerAlias，OpenClaw 将使用集成 ID 作为 SecretRef 提供商别名。提供商别名必须符合常规 SecretRef 提供商别名模式，例如 team-secrets 或 onepassword-work。

操作员选择该预设时，OpenClaw 会写入如下提供商引用：

{
  "secrets": {
    "providers": {
      "team-secrets": {
        "source": "exec",
        "pluginIntegration": {
          "pluginId": "acme-secrets",
          "integrationId": "secret-store"
        }
      }
    }
  }
}

启动/重新加载时，OpenClaw 会通过加载当前插件清单元数据来解析该提供商，检查所属插件是否已安装且处于活动状态，并根据清单具体化 exec 命令。禁用或移除插件会撤销活动 SecretRef 对该提供商的使用。需要独立 exec 配置的操作员仍可直接手动编写 command/args 提供商。

目前仅支持 source: "exec" 预设。command 必须为 ${node}，且 args[0] 必须是 ./ 相对于插件根目录的解析器脚本。OpenClaw 会在启动/重新加载时将其具体化为当前 Node 可执行文件和插件内脚本的绝对路径。--require、--import、--loader、--env-file、--eval 和 --print 等 Node 选项不属于清单预设契约。需要非 Node 命令的操作员可以直接配置独立的手动 exec 提供商。

对于清单预设，OpenClaw 会根据插件根目录推导 trustedDirs；对于 ${node} 预设，还会根据当前 Node 可执行文件目录推导该值。清单中编写的 trustedDirs 将被忽略。timeoutMs、noOutputTimeoutMs、maxOutputBytes、jsonOnly、env、passEnv 和 allowInsecurePath 等其他 exec 提供商选项会原样传递给常规 SecretRef exec 提供商配置。

modelPricing 参考

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

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

提供商字段：

来源字段：

OpenClaw 提供商索引

OpenClaw 提供商索引是 OpenClaw 所有的预览元数据，面向其插件可能尚未安装的提供商。它不属于插件清单。插件清单仍是已安装插件的权威来源。提供商索引是内部回退契约；当提供商插件未安装时，未来的可安装提供商和安装前模型选择器界面将使用它。

目录权威顺序：

1. 用户配置。
2. 已安装插件清单 modelCatalog。
3. 显式刷新生成的模型目录缓存。
4. OpenClaw 提供商索引预览行。

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

对于插件已移出核心或尚未安装的提供商，提供商索引条目还可以携带可安装插件元数据。此元数据遵循频道目录模式：包名称、npm 安装规范、预期完整性以及轻量的身份验证选项标签足以显示可安装的设置选项。插件安装后，以其清单为准，并忽略该提供商的提供商索引条目。

openclaw doctor --fix 会将一小组封闭的旧版顶层清单能力键迁移到 contracts.*：speechProviders、mediaUnderstandingProviders、imageGenerationProviders 和 tools。这些键（或任何其他能力列表）都不再作为顶层清单字段读取；常规清单加载仅在 contracts 下识别它们。

清单与 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。

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

对于非内置插件来源，安装和清单注册表加载期间会强制执行 openclaw.install.minHostVersion。无效值会被拒绝；较新但有效的值会使较旧的主机跳过外部插件。假定内置源插件与主机检出代码使用相同版本。

openclaw.install.requiredPlatformPackages 用于通过可选的特定平台别名提供所需原生二进制文件的 npm 包。请为每个受支持的平台别名列出不带版本的 npm 包名称。在 npm 安装期间，OpenClaw 仅验证锁文件约束与当前主机匹配的已声明别名。如果 npm 报告成功但省略该别名，OpenClaw 会使用全新缓存重试一次；如果别名仍然缺失，则回滚安装。

对于非内置插件来源，包安装期间会强制执行 openclaw.compat.pluginApi。使用它指定构建该包时所依据的 OpenClaw 插件 SDK/运行时 API 下限。当插件包需要较新的 API，但仍为其他流程保留较低的安装提示时，它可以比 minHostVersion 更严格。默认情况下，官方 OpenClaw 发布同步会将现有官方插件的 API 下限提升到 OpenClaw 发布版本，但如果包有意支持较旧的主机，仅发布插件时可以保留较低的下限。不要仅使用包版本作为兼容性契约。peerDependencies.openclaw 仍是 npm 包元数据；OpenClaw 使用 openclaw.compat.pluginApi 契约作出安装兼容性决策。

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

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

当状态、频道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账户时，频道插件应提供 openclaw.setupEntry。设置入口应公开频道元数据以及设置安全的配置、状态和密钥适配器；网络客户端、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、状态或只读在线状态流程需要在完整渠道插件加载前执行低成本的是/否身份验证探测时，请使用它。持久化身份验证状态并非已配置的渠道状态：不要使用此元数据自动启用插件、修复运行时依赖项，或决定是否应加载渠道运行时。目标导出应是仅用于读取持久化状态的小型函数；不要让它通过完整的渠道运行时 barrel。

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

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

当列出的每个变量均为必需项时，使用 env.allOf；当任意一个非空变量就足够时，使用 env.anyOf。如果小型非运行时检查需要环境元数据以外的信息，请像 persistedAuthState 所示使用 specifier 加 exportName；当存在 env 时，OpenClaw 会直接使用它，而不加载该模块。如果检查需要完整的配置解析或实际渠道运行时，则应将该逻辑保留在插件的 config.hasConfiguredState 钩子中。

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

OpenClaw 从三个根目录发现插件，并按以下顺序检查：随 OpenClaw 一起提供的内置插件、全局安装根目录（~/.openclaw/extensions）和当前工作区根目录（<workspace>/.openclaw/extensions），此外还包括任何显式的 plugins.load.paths 条目。

如果两个发现结果具有相同的 id，则仅保留优先级最高的插件清单；优先级较低的重复项会被丢弃，而不会与其并列加载。优先级从高到低如下：

1. 配置选定 — 在 plugins.entries.<id> 中显式固定的路径
2. 与已跟踪安装记录匹配的全局安装 — 通过 openclaw plugin install/openclaw plugin update 安装，且 OpenClaw 的安装跟踪针对同一 ID 能够识别的插件，即使该 ID 也属于内置插件
3. 内置 — 随 OpenClaw 一起提供的插件
4. 工作区 — 相对于当前工作区发现的插件
5. 任何其他发现的候选项

影响如下：

• 位于工作区或全局根目录中且未被跟踪的内置插件分支副本或过时副本，不会遮蔽内置构建版本。
• 要覆盖内置插件，可以针对该 ID 运行 openclaw plugin install，使已跟踪的全局安装优先于内置副本；也可以通过 plugins.entries.<id> 固定特定路径，使其凭借配置选定的优先级胜出。
• 重复项丢弃操作会被记录到日志中，以便 Doctor 和启动诊断指出被丢弃的副本。
• 配置选定的重复项覆盖在诊断中会被明确表述为覆盖操作，但仍会发出警告，以确保过时分支副本和意外遮蔽保持可见。

JSON Schema 要求

• 每个插件都必须提供 JSON Schema，即使它不接受任何配置。
• 空 Schema 是可接受的（例如 { "type": "object", "additionalProperties": false }）。
• Schema 在读取/写入配置时验证，而不是在运行时验证。
• 使用新配置键扩展内置插件或为其创建分支时，请同时更新该插件的 openclaw.plugin.json configSchema。内置插件的 Schema 是严格的，因此，如果在用户配置中添加 plugins.entries.<id>.config.myNewKey，但未向 configSchema.properties 添加 myNewKey，则会在插件运行时加载前遭到拒绝。

Schema 扩展示例：

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

验证行为

• 未知的 channels.* 键属于错误，除非该渠道 ID 已由插件清单声明。如果同一 ID 也出现在 plugins.allow、plugins.entries 或 plugins.installs 中（即引用了该插件，但当前无法发现），OpenClaw 会将其降级为警告。
• plugins.entries.<id>、plugins.allow 和 plugins.deny 引用未知插件 ID 时属于警告（“已忽略过时的配置条目”），而不是错误，因此升级以及插件移除/重命名不会阻止 Gateway 网关启动。
• plugins.slots.memory 引用未知插件 ID 时属于错误，但已知的 memory-lancedb 官方外部插件除外，对它会发出警告。
• 如果插件已安装，但其插件清单或 Schema 损坏或缺失，验证将失败，Doctor 会报告插件错误。
• 如果插件配置存在，但插件已禁用，则会保留配置，并在 Doctor 和日志中显示警告。

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

说明

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

相关内容

• 构建插件：插件入门指南。
• 插件架构：内部架构和能力模型。
• SDK 概览：插件 SDK 参考和子路径导入。