古法编程

Appearance

本页是 OpenClaw 原生插件 manifest 文件（openclaw.plugin.json）的完整字段参考。涵盖必填字段（id、configSchema）、Provider 认证元数据（providerAuthEnvVars、providerAuthChoices）、UI 提示（uiHints）、能力所有权声明（contracts）、渠道配置（channelConfigs）以及模型支持（modelSupport），并说明 manifest 与 package.json 的职责边界。养好龙虾第一步，从写对 manifest 开始。

Plugin Manifest（openclaw.plugin.json） ​

本页仅适用于原生 OpenClaw 插件 manifest。

兼容 Bundle 格式的 manifest 文件请参考 Plugin Bundles：

  • Codex bundle：.codex-plugin/plugin.json
  • Claude bundle：.claude-plugin/plugin.json 或默认 Claude 组件布局（无 manifest）
  • Cursor bundle：.cursor-plugin/plugin.json

OpenClaw 同样会自动检测这些 bundle 布局，但不会用 openclaw.plugin.json schema 进行验证。

每个原生 OpenClaw 插件的插件根目录下必须提供一个 openclaw.plugin.json 文件。OpenClaw 用它在不执行插件代码的情况下验证配置。缺失或格式不合法的 manifest 会被视为插件错误并阻断配置验证。

完整插件系统指南见：插件安装与使用；原生能力模型说明见：能力模型。

这个文件的作用 ​

openclaw.plugin.json 是 OpenClaw 在加载插件代码之前读取的元数据。

用它来声明：

  • 插件身份（id、name、description）
  • 配置校验 schema
  • 认证和引导元数据（无需启动插件运行时即可访问）
  • 别名和自动启用元数据
  • 模型家族所有权（runtime 加载前自动激活插件）
  • 静态能力所有权快照（用于 bundle 兼容接线和合约覆盖检查）
  • 渠道特定配置元数据
  • 配置 UI 提示

不要用它来：

  • 注册运行时行为
  • 声明代码入口点
  • 放置 npm 安装元数据

这些内容分别属于插件代码和 package.json。

最简示例 ​

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

完整示例 ​

json
{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "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 则默认禁用
legacyPluginIds否string[]规范化到此插件 id 的旧 id 列表
autoEnableWhenConfiguredProviders否string[]当 auth/config/模型引用中出现这些 provider id 时自动启用本插件
kind否"memory" | "context-engine"声明独占插件类型，用于 plugins.slots.*
channels否string[]此插件拥有的渠道 id 列表
providers否string[]此插件拥有的 Provider id 列表
modelSupport否objectmanifest 端的模型家族元数据，runtime 加载前自动激活插件
providerAuthEnvVars否Record<string, string[]>不加载插件代码即可访问的环境变量认证元数据
providerAuthChoices否object[]引导选择器的认证选项元数据
contracts否object静态能力所有权快照
channelConfigs否Record<string, object>runtime 加载前合并到校验面的渠道配置元数据
skills否string[]要加载的 skill 目录（相对插件根目录）
name否string可读的插件名称
description否string插件摘要
version否string插件版本（仅供参考）
uiHints否Record<string, object>配置字段的 UI 标签、占位符和敏感性提示

providerAuthChoices 字段参考 ​

每条 providerAuthChoices 条目描述一个引导或认证选项，OpenClaw 在 Provider runtime 加载前读取此数据。

字段必填类型说明
provider是string此选项所属的 Provider id
method是string调度目标的认证方法 id
choiceId是string引导和 CLI 流程使用的稳定认证选项 id
choiceLabel否string用户可见标签，省略时回退到 choiceId
choiceHint否string选择器的简短提示文字
assistantPriority否number值越小在助手驱动的交互选择器中排越靠前
assistantVisibility否"visible" | "manual-only"在助手选择器中隐藏但仍允许手动 CLI 选择
groupId否string分组 id
groupLabel否string分组的用户可见标签
optionKey否string简单单 flag 认证流程的内部 option key
cliFlag否stringCLI flag 名，如 --openrouter-api-key
cliOption否string完整 CLI option，如 --openrouter-api-key <key>
cliDescription否stringCLI help 中显示的描述
onboardingScopes否Array<"text-inference" | "image-generation">在哪些引导页面显示此选项；省略时默认 ["text-inference"]

uiHints 字段参考 ​

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

json
{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "用于 OpenRouter 请求",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}
字段类型说明
labelstring用户可见字段标签
helpstring简短帮助文字
tagsstring[]可选 UI 标签
advancedboolean标记为高级字段
sensitiveboolean标记为敏感/秘密字段
placeholderstring表单输入框占位符

contracts 字段参考 ​

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

json
{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
字段类型说明
speechProvidersstring[]此插件拥有的语音 Provider id
realtimeTranscriptionProvidersstring[]实时转录 Provider id
realtimeVoiceProvidersstring[]实时语音 Provider id
mediaUnderstandingProvidersstring[]媒体理解 Provider id
imageGenerationProvidersstring[]图像生成 Provider id
videoGenerationProvidersstring[]视频生成 Provider id
webFetchProvidersstring[]网页抓取 Provider id
webSearchProvidersstring[]网页搜索 Provider id
toolsstring[]此插件拥有的 Agent 工具名（用于 bundle 合约检查）

channelConfigs 字段参考 ​

渠道插件在 runtime 加载前需要配置元数据时使用 channelConfigs：

json
{
  "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 连接",
      "preferOver": ["matrix-legacy"]
    }
  }
}
字段类型说明
schemaobjectchannels.<id> 的 JSON Schema（每个声明条目必填）
uiHintsRecord<string, object>可选 UI 标签/占位符/敏感性提示
labelstringruntime 未就绪时合并到选择器和 inspect 面的渠道标签
descriptionstring渠道简短描述
preferOverstring[]本渠道在选择面中优先于这些旧/低优先级插件 id

modelSupport 字段参考 ​

当 OpenClaw 在 runtime 加载前需要从简写模型 id（如 gpt-5.4）推断 Provider 插件时使用：

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

优先级规则：

  1. 显式 provider/model 引用 → 使用拥有者插件的 providers 元数据
  2. modelPatterns 优先于 modelPrefixes
  3. 一个非内置插件和一个内置插件都匹配时，非内置插件胜出
字段类型说明
modelPrefixesstring[]用 startsWith 匹配简写模型 id 的前缀
modelPatternsstring[]去掉 profile 后缀后匹配的正则表达式

旧版顶级能力键已废弃。运行 openclaw doctor --fix 将 speechProviders、mediaUnderstandingProviders 等移入 contracts。

Manifest 与 package.json 的职责划分 ​

文件用途
openclaw.plugin.json插件代码运行前的发现、配置校验、认证选项元数据和 UI 提示
package.jsonnpm 元数据、依赖安装、入口点声明、安装门控、Setup 配置

判断规则：插件代码运行前 OpenClaw 必须知道的 → 放 manifest；关于打包/入口/npm 安装行为的 → 放 package.json。

JSON Schema 要求 ​

  • 每个插件必须附带 JSON Schema，即使不接受任何配置
  • 空 schema 完全合法：{ "type": "object", "additionalProperties": false }
  • Schema 在配置读写时验证，不在运行时验证

验证行为 ​

  • 未声明渠道 id 的 channels.* 键会被报为错误
  • plugins.entries.<id>、plugins.allow、plugins.deny、plugins.slots.* 必须引用可发现的插件 id
  • 插件 manifest 缺失或损坏时，Doctor 会报告插件错误
  • 插件配置存在但插件已禁用时，Doctor 和日志会显示警告

相关文档 ​

常见问题 ​

Q: manifest 中的 configSchema 必须包含所有配置字段吗？

A: 必须。OpenClaw 以 manifest 中的 schema 为准进行配置校验。如果字段存在于配置中但 schema 未声明，且 additionalProperties 为 false，就会报错。建议将所有用到的配置字段都声明在 schema 中。

Q: providerAuthEnvVars 和 providerAuthChoices 有什么区别？

A: providerAuthEnvVars 仅声明哪些环境变量用于认证（用于 env 探测和快速检查），不需要加载 runtime。providerAuthChoices 则声明完整的认证选项（用于引导向导和 CLI flag），比 env vars 包含更多用户可见信息。两者都在 runtime 加载前即可使用。

Q: 插件已安装但配置里报 hard error，该怎么排查？

A: 先运行 openclaw plugins inspect <id> 查看详细诊断。常见原因：manifest 字段格式错误（如 configSchema 不是合法 JSON Schema）、providers 字段有重复 id，或 contracts 下的能力 id 在系统中已被另一个插件声明。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策