本页是 OpenClaw 原生插件 manifest 文件（openclaw.plugin.json）的完整字段参考。如果你正在构建一个 OpenClaw 插件、需要提供插件配置 schema 或排查插件校验错误，这里列出了所有可用的 manifest 字段、JSON Schema 要求及各字段的业务含义。每个原生插件必须在插件根目录放置 openclaw.plugin.json，缺失或格式错误会直接阻断配置验证，openclaw doctor 可帮助诊断。

OpenClaw Plugin Manifest 完整字段参考：openclaw.plugin.json 配置指南 #

本页仅适用于原生 OpenClaw 插件 manifest。
兼容的 Bundle 格式（Codex/Claude/Cursor）使用各自的 manifest 文件，OpenClaw 会自动检测那些布局，但不会用本页描述的 schema 验证它们。关于兼容 bundle 布局的说明，见 Plugin bundles。

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

完整插件系统指南：插件安装与使用
原生能力模型及外部兼容性指导：能力模型

这个文件的作用 #

openclaw.plugin.json 是 OpenClaw 加载插件代码之前读取的元数据。以下所有内容必须能在不启动插件 runtime 的情况下低成本检查。

用来声明：

• 插件身份、配置验证、配置 UI 提示
• 认证、引导和设置元数据（别名、自动启用、provider 环境变量、认证选项）
• 控制平面激活提示
• 简写模型家族所有权（runtime 之前自动加载）
• 静态能力所有权快照（contracts）
• QA runner 元数据，供共享的 openclaw qa 宿主检查
• 渠道特定配置元数据，合并到 catalog 和验证面

不能用来： 注册运行时行为、声明代码入口点、npm 安装元数据。那些分别属于插件代码和 package.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"
      }
    }
  }
}

顶级字段参考 #

Generation provider metadata 参考 #

生成类 provider（图像/视频/音乐）使用 contracts.*GenerationProviders 声明所有权，使用对应 *GenerationProviderMetadata 字段提供静态 auth 信号。OpenClaw 在 provider runtime 加载前读取这些信号，供核心工具判断可用性，无需导入每个 provider 插件。

只应放入声明性事实。传输、请求转换、令牌刷新、凭证验证和实际生成行为始终位于插件 runtime 中。

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

每个元数据条目支持的字段（以 imageGenerationProviderMetadata 为例，其他类似）：

每个 configSignals 条目的字段：

mode 守卫支持的字段：

每个 authSignals 条目的字段：

providerBaseUrl 守卫支持的字段：

Tool metadata 参考 #

toolMetadata 使用与 generation provider metadata 相同的 configSignals 和 authSignals 形状，按键为工具名。contracts.tools 声明所有权，toolMetadata 声明轻量可用性证据，使 OpenClaw 无需导入插件 runtime 去调用返回 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，而不是让核心导入 runtime 来询问。

providerAuthChoices 参考 #

每条 providerAuthChoices 条目描述一个引导或认证选项。OpenClaw 在 provider runtime 加载前读取。Provider 设置列表使用这些 manifest 选项、描述派生的设置选项和安装目录元数据，无需加载 provider runtime。

commandAliases 参考 #

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

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

activation 参考 #

当插件可以廉价声明哪些控制平面事件应将其包含在激活/加载计划中时，使用 activation。此块是计划器元数据，不是生命周期 API。

每个插件应有意设置 activation.onStartup。仅在插件必须在 Gateway 启动期间运行时设为 true；插件在启动时是惰性的且只应从更窄的触发器加载时设为 false。省略 onStartup 不再隐式启动加载插件。

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

当前实时消费者详见原文的“Current live consumers”部分，这里不再冗余列出。

qaRunners 参考 #

当插件为共享的 openclaw qa 根贡献一个或多个传输 runner 时使用。

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

setup 参考 #

当设置和引导面需要在 runtime 加载前获取插件拥的廉价元数据时使用。

{
  "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 时，它们是设置发现的首选描述符优先查找面。如果描述符只缩小了候选插件，但设置仍需要更丰富的设置时 runtime hooks，则设置 requiresRuntime: true 并保持 setup-api 作为回退执行路径。

setup.providers 字段：

authEvidence 支持的字段：

setup 顶层字段：

uiHints 参考 #

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

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

每个字段提示可包含：

contracts 参考 #

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

{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"],
    "externalAuthProviders": ["acme-ai"],
    "embeddingProviders": ["openai-compatible"],
    "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"]
  }
}

每个列表为可选。关键字段含义：

mediaUnderstandingProviderMetadata 参考 #

当媒体理解 provider 具有默认模型、自动认证回退优先级或核心帮助器在 runtime 加载前需要原生文档支持时使用。键也必须声明在 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 条目可包含：

channelConfigs 参考 #

当渠道插件在 runtime 加载前需要廉价配置元数据时使用。channelConfigs 的 schema 用于验证 channels.<channel-id>，而 configSchema 用于验证 plugins.entries.<plugin-id>.config。

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

每个渠道条目可包含：

替换另一个渠道插件： 使用 preferOver 当你的插件是某个渠道 id 的首选拥有者，而另一个插件也能提供该渠道。例如，重命名的插件 id、替代内置插件的独立插件、或者保持相同渠道 id 以进行配置兼容的维护分支。

modelSupport 参考 #

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

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

优先级：

• 显式 provider/model 引用 → 使用拥有者插件的 providers 元数据
• modelPatterns 优先于 modelPrefixes
• 一个非内置插件和一个内置插件都匹配时，非内置插件胜出
• 其余歧义忽略，直到用户/配置指定 provider

modelCatalog 参考 #

当 OpenClaw 在加载 plugin runtime 之前需要 provider 模型元数据时使用。这是 manifest 拥有的固定目录行、provider 别名、抑制规则和发现模式的来源。运行时刷新仍属于 provider runtime 代码，但 manifest 告诉核心何时需要 runtime。

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

discovery 字段使用 "static"、"refreshable" 或 "runtime" 指示目录如何获取。不要将运行时数据放入 modelCatalog。

modelIdNormalization 参考 #

用于 provider 拥有的模型 id 清理，必须在 provider runtime 加载前执行。

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

Provider 字段包括 aliases（不区分大小写的精确模型 id 别名）、stripPrefixes（在别名查找前去除的前缀）和 prefixWhenBare（当规范化模型 id 不包含 / 时添加的前缀）等。

providerEndpoints 参考 #

用于通用请求策略在 provider runtime 加载前必须知道的端点分类。核心仍拥有每个 endpointClass 的含义；插件 manifest 拥有 host 和 base URL 元数据。

端点字段：endpointClass、hosts、hostSuffixes、baseUrls、googleVertexRegion、googleVertexRegionHostSuffix。

providerRequest 参考 #

用于通用请求策略需要的轻量请求兼容性元数据。保持行为特定的有效负载重写在 provider runtime hooks 或共享的 provider 家族帮助器中。

Provider 字段：family、compatibilityFamily、openAICompletions。

modelPricing 参考 #

用于需要对 model pricing 进行控制平面行为的 provider，例如本地/自托管 provider 设置 external: false 阻止 OpenRouter/LiteLLM 定价查找。

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

Provider 字段：external（false 禁用外部定价）、openRouter、liteLLM。源字段包括 provider、passthroughProviderModel、modelIdTransforms。

Manifest 与 package.json 的职责划分 #

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

package.json 下 openclaw 块中的关键发现字段（只列出常用项，完整列表见原文）：

详细字段说明请参见原文的“package.json fields that affect discovery”部分。

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

OpenClaw 从多个根发现插件。如果两个发现共享相同的 id，只有最高优先级的 manifest 会保留，低优先级的副本会被丢弃。优先级从高到低：

1. 配置选择 - 在 plugins.entries.<id> 中显式固定的路径
2. 内置 - 随 OpenClaw 发布的插件
3. 全局安装 - 安装在全局 OpenClaw 插件根目录的插件
4. 工作区 - 从当前工作区发现的插件

JSON Schema 要求 #

• 每个插件必须附带 JSON Schema，即使不接受任何配置
• 空 schema 合法（例如 { "type": "object", "additionalProperties": false }）
• Schema 在配置读写时验证，不在运行时验证
• 扩展或复刻内置插件时，必须同步更新 configSchema

验证行为 #

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

注意事项 #

• Manifest 对原生插件必需，包括本地文件系统加载。Runtime 单独加载插件模块，manifest 仅用于发现和验证
• 原生 manifest 使用 JSON5 解析，支持注释、尾逗号、未引号的键
• 只读取文档化的 manifest 字段。避免自定义顶级键
• channels、providers、cliBackends、skills 可在不需要时忽略
• providerCatalogEntry 必须保持轻量，不应导入广泛 runtime 代码
• 独占插件类型（memory/context-engine）通过 plugins.slots.* 选择
• 环境变量元数据（setup.providers[].envVars、废弃的 providerAuthEnvVars、channelEnvVars）仅声明性。读状态面仍应用插件信任和有效激活策略
• 旧版顶级能力键（speechProviders 等）已废弃，使用 openclaw doctor --fix 移入 contracts

相关文档 #

• Building plugins
• Plugin architecture
• SDK overview
• Configuration reference

常见问题 #

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

是。OpenClaw 以 manifest 中 configSchema 为准进行配置校验。如果某个字段在用户配置中存在但 schema 未声明，且 additionalProperties 为 false，就会报错。建议将所有插件配置字段都声明在 schema 的 properties 中。

插件 manifest 缺失或损坏时会出现什么表现？ #

配置验证失败，OpenClaw 会阻止启动。运行 openclaw doctor 可以查看详细的插件错误报告。最常见的错误是缺少 openclaw.plugin.json 文件、JSON 格式错误或必填字段（如 id、configSchema）缺失。

如何让插件在启动时自动启用？ #

在 manifest 中设置 "enabledByDefault": true（仅对内置插件有效）。对于非内置插件，需要在用户配置的 plugins.entries.<id> 中显式启用。另外，使用 activation.onStartup: true 可以让插件在 Gateway 启动时加载（无论是否内置）。注意，enabledByDefault 控制默认启用状态，而 activation.onStartup 控制启动时是否加载代码。