宿主表面字段

提供具体宿主界面的清单字段：图标、命令、服务器、面板、小部件、运行器、通道或备份资源。是插件清单参考的一部分；顶层字段参考列出所有字段。

插件图标¶

将可移植插件图标放置在相对于插件根目录的 assets/icon.png。无需清单字段。使用在 16 px 下仍可识别的正方形 PNG；建议使用 512×512。缺失、无法读取或无效的图标会被忽略，且不会使插件无效。

这是插件在目录、设置、通道设置和安装卡片中的身份标识图形。紧凑工具调用使用单独的内联活动图标，因此改进聊天字形不会改变插件在其他地方的品牌标识。

OpenClaw 将此固定包路径作为其图标约定，与 Agent Plugins 规范提案 agent-plugins-spec#66 中提出的路径一致。OpenClaw 本身实现 Agent Plugins 1.0.0。除非该提案被采用，其他 Agent Plugins 使用者可能无法发现它。固定路径使包保持可移植且可检查，避免清单路径间接引用和优先级规则，并让 OpenClaw 无需运行时网络请求即可渲染图标。不会加载顶层插件品牌图标 URL；provider-auth 图形仍属于服务器拥有的目录元数据。

对于静态 Doctor 所有权，优先使用顶层 sessionRouteStateOwners。旧的 doctorContract.sessionRouteStateOwners: true 声明加上从 doctor-contract-api 导出的 sessionRouteStateOwners 仍对外部插件保持支持，但已弃用。当清单字段存在时，OpenClaw 会使用它，而无需加载 doctor-contract 模块。移除计划：在外部插件迁移窗口之后，于 OpenClaw 2027.1 中移除模块回退。

当 doctor-contract 模块导出非空的 legacyConfigRules、normalizeCompatibilityConfig 函数或两者时，设置 doctorContract.configRepair: true。一个声明即可覆盖完整的配置修复产物。

当 Doctor 重命名已保存的凭据时，它会更新插件配置和通道配置中精确的 authProfileId 和 defaultAuthProfileId 引用。这保留了已发布的 authProfileId 迁移，也覆盖诸如 LLM Task 的 defaultAuthProfileId 之类的默认值，包括较旧的已安装插件。引用查找会修剪周围空白，与凭据读取器一致。未映射的值和其他位置的字符串字面量保持不变。插件无需在其兼容性回调中实现宿主机的凭据重命名。

捆绑插件按执行顺序声明每个状态迁移，以便 Doctor 无需加载插件代码即可规划其所有者和回执：

{
  "doctorContract": {
    "stateMigrations": [
      { "id": "legacy-cache-to-state" },
      { "id": "session-owner-repair", "doctorOnly": true, "phase": "after-session-repair" }
    ]
  }
}

该数组必须与 doctor-contract 模块导出的迁移 ID、顺序、doctorOnly 标志和阶段相匹配。旧值 true 仍声明动态模块。已安装的外部插件清单仍位于复制状态和候选内容标识之外，即使它们使用描述符数组也是如此。候选验证必须单独绑定这些产物。在此之前，Doctor 会记录明确的规划拒绝，而不是将已安装清单视为写入权限。

状态迁移返回 changes 和 warnings，可选返回 notices。默认情况下，警告会拒绝后续的 Doctor 修复。只有当每个警告都是建议性的，且所需状态对后续修复仍然安全时，迁移才可以返回 warningDisposition: "recoverable"。Doctor 会在其回执中保留这些警告并继续。检测错误、抛出的失败以及来自另一个迁移的未分类警告仍会拒绝组合步骤。

对于 definePluginDoctorMigrationFromPlans，当 plugin-state-import 计划的退役来源是一个未使用且可重建的产物时，可以设置 cleanupWarningDisposition: "recoverable"。这仅适用于导入成功后的清理失败。读取、导入和验证失败仍会拒绝迁移。每个消费共享来源的计划都必须选择加入，其清理失败才会变为建议性。

Codex 插件在其公共 API 导出健康检查注册时设置 doctorHealthChecks: true。Doctor 在加载此界面之前会检查所选插件的信任状态。没有该声明的较旧已安装版本会跳过 Codex 健康注册，但不会阻止其他检查；已声明但缺失或损坏的 API 仍会视为错误。这不会授予插件能力，也不会替代升级同意。

在 OpenClaw 源代码树中维护的通道插件还通过纯 config-doctor-api.ts 入口点公开这些配置导出。当插件运行时单独分发时，核心包会保留该入口点及其通道模式。这使得 doctor --fix 能够在插件安装或能力同意之前迁移旧配置。已安装插件的 doctor 契约仍具有权威性；保留的入口点不会公开状态迁移、安装插件或授予能力。

内联活动图标¶

在 assets/activity.svg 放置单色 SVG，用于插件工具调用和折叠工具结果旁的紧凑图标。无需清单字段。设计时确保其在 16 px 下仍清晰，并使用透明背景。Control UI 会以活动行的文本颜色渲染其形状，包括深色模式；源颜色不会成为该行中的品牌颜色。

仅当某个工具需要不同形状时，才使用 assets/activity/<tool-name>.svg。文件名必须与该工具在 tools.effective 中的 id 完全匹配，包括大小写。例如，ID 为 calendar_search 的工具可以附带：

assets/
  icon.png
  activity.svg
  activity/
    calendar_search.svg

工具 ID 最多为 128 个 ASCII 字符，以字母、数字或下划线开头，并且只能包含字母、数字、下划线、连字符或句点。 将覆盖目录保持在最多 128 个条目；更大的目录会被整体忽略。默认活动图标覆盖其他工具 ID，包括其路由会为工具名称添加前缀的集成。这些文件仅提供展示；它们不会注册工具或更改工具所有权。

将每个 SVG 文件保持在 32 KiB 以内。使用简单的 SVG 几何图形：path、circle、ellipse、line、polygon、polyline 和 rect，可选地放在 g 内。SVG 最多可包含四个元素（包括根元素）、8 KiB 的路径和点数据合计，以及 1,024 条路径命令。为根元素提供具有正宽度和正高度的 viewBox，或提供正数值 width 和 height，且每个值最多为 4,096。不支持脚本、样式表、事件处理程序、外部引用、嵌入图像和滤镜。例如：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
  <path d="M5 5h14v14H5zM8 2v6m8-6v6M5 10h14"/>
</svg>

OpenClaw 会验证 SVG 并在将其用作活动蒙版之前对其进行栅格化；它绝不会将包中的 SVG 标记插入聊天 DOM。缺失或无效的美术资源会回退到现有工具字形，而不会显示打包的品牌图像。插件仍可使用。

使用时，请将 assets/activity.svg 和 assets/activity/*.svg 都包含在已发布包的 files 列表中。OpenClaw 内置的元数据复制器和插件运行时包构建器会自动包含这些路径。资源发现使用 Gateway 准备好的插件元数据；更改其美术资源后，请重启或显式重新加载插件。

主题¶

在 openclaw.plugin.json 中声明可移植主题，使其可在 设置 → 外观 以及代理的主题工具 中使用。同一个目录同时服务于这两个界面。主题发现读取静态 JSON，不会执行插件代码，也不需要 Custom plugin UI Labs 设置。

{
  "id": "starship",
  "configSchema": { "type": "object", "additionalProperties": false },
  "themes": [
    {
      "id": "xenovessel",
      "name": "Xenovessel",
      "description": "Near-black indigo, acid lime, and alien cyan with monospace text.",
      "source": "themes/xenovessel.json",
      "hats": { "beret": "assets/theme-art/beret.svg" },
      "critters": {
        "ferris": {
          "source": "assets/theme-art/ferris.svg",
          "title": "a crab, allegedly",
          "crossMs": 12000
        }
      }
    }
  ]
}

目录 ID 为 starship/xenovessel。它会保留插件的规范 ID，包括大小写、诸如 @scope/starship 的作用域 ID，以及诸如 pack/one 的多条目 ID；它们的主题 ID 分别为 @scope/starship/xenovessel 和 pack/one/xenovessel。完整目录 ID 限制为 256 个字符。每个插件最多可声明 32 个主题。 本地 ID 必须以一个小写字母或数字开头，只能包含小写字母、数字、下划线或连字符，且最多为 64 个字符。user/ 命名空间属于个人导入的主题。

source 是插件根目录内的相对 .json 路径；请将其包含在已发布包的 files 列表中。绝对路径、路径遍历以及逃逸根目录的符号链接会被拒绝。每个源文件最多可包含 16 KiB（包括格式化空白）。其规范化定义必须能容纳在 4096 个 UTF-8 字节内。

每个主题可以声明 hats，即从美术资源 ID 到相对 .svg 路径的映射，以及 critters，即从美术资源 ID 到包含 source 以及可选 title 和 crossMs 的对象的映射。每个映射最多允许 8 个条目。美术资源 ID 必须匹配 ^[a-z0-9][a-z0-9_-]{0,31}$；重复项以及与相应内置帽子或小动物目录的冲突属于清单错误。title 是未翻译的悬停文本，最多 60 个可打印字符。crossMs 是 5000 到 90000 之间的整数，默认值为 12000 毫秒。

美术资源路径遵循与 source 相同的包含规则。每个 SVG 必须自包含且最多为 32 KiB；脚本、事件处理程序、外部引用和嵌入资源会被拒绝。Control UI 会将美术资源栅格化为 256 × 256 像素画布，然后再将其作为图像渲染。它使用活动图标限制：最多 4 个元素（包括根元素）、8 KiB 的路径和点数据合计、1024 条路径命令，以及不超过 4096 的正源尺寸。使用 path、circle、ellipse、line、polygon、polyline 和 rect，可选地放在 g 内；根元素为 svg，并且在元素限制内也支持 title 和 desc。不支持样式表、滤镜和嵌入图像。帽子会覆盖头像的完整正方形；请将帽子放在 SVG viewBox 的顶部附近，并让下部区域保持透明。

请将定义 JSON 和每个已声明的 SVG 包含在已发布包的 files 列表中。OpenClaw 内置的元数据复制器和运行时包构建器会自动包含这些已声明路径。无法读取或无效的 SVG 会使整个主题从目录中省略，并产生插件警告诊断；其他插件功能仍可用。

JSON 文件包含 name、description，以及 light 或 dark 中的至少一个；其名称和描述必须与清单匹配。名称限制为 80 个字符，描述限制为 320 个字符。每个存在的模式都提供来自主题定义示例 的所有语义颜色，以及可选的 font-sans 和 font-mono 字体族列表。单个值限制为 120 个字符。支持的颜色包括十六进制、rgb()、rgba()、hsl()、hsla()、lab()、lch()、oklab()、oklch()、color()、black、white 和 transparent。CSS 声明、URL 以及对其他 CSS 变量的引用不属于主题数据。无效定义会被从目录中省略，并产生插件诊断；其他插件功能仍可用。

源 JSON 也接受可选的展示字段。它们属于由 themes[].source 引用的定义，与 name、description 以及调色板一起：

• mascot: "claw"（默认）或 "none"；"none" 使用中性品牌标识，并隐藏常驻龙虾和来访的龙虾陌生人。普通小动物仍可在启用 Lobster visits 时穿过 composer 边缘，且该开关保持不变。
• workingPhrases: 最多 24 条字面、未翻译的长等待状态短语。每个短语会被修剪，必须包含 1–24 个字符，且不能包含控制字符，也不能与其他修剪后的短语重复。省略它以保留默认词汇；使用 [] 隐藏长等待短语。
• critters: 最多 8 个唯一 ID，来自内置 "penguin" 和 "fedora" 目录，或此主题声明的 critters 映射，在启用 Lobster visits 时为普通 composer 边缘流量添加偶尔的访客。省略它或使用 [] 表示没有主题提供的小动物。未知 ID 和重复项会被拒绝。
• avatarHat: "fedora"、"crown"、"santa"、"party"、"pumpkin"，或此主题声明的 hats 映射中的某个 ID，会为 agent 头像添加偶尔出现的装饰帽；省略则不添加帽子。

这些字段计入相同的 4096 字节规范化定义限制，并随目录描述符一起返回。主题定义示例 包含全部四个字段。 定义仅携带 ID，绝不携带 SVG 标记或 URL。通过 agent 的 theme 工具导入的个人主题仍限于内置美术资源 ID。

仅已启用的插件会贡献主题。OpenClaw 会随当前插件清单保留已验证的定义和美术资源字节。编辑源、美术资源文件或清单后，运行 openclaw plugins reload starship 或在插件的 Lifecycle 设置中选择 Reload。重新加载会发布新调色板并刷新已连接客户端，而无需重启 Gateway。美术资源 URL 包含内容哈希，因此更改后的图像会绕过页面的美术资源缓存。提供美术资源时读取的是已捕获的生成版本，而不是磁盘上已更改的文件。无需文件系统轮询。禁用或移除插件会将其主题从目录中移除；随后所选主题可按 插件主题和热重载 中所述回退。

转录源参考¶

transcriptSources 将 provider ID 映射到静态设置描述符。每个键还必须出现在此插件的 contracts.transcriptSourceProviders 中；未声明 ID 的描述符会被忽略。名称和设置控件可从准备好的清单快照中获取，而无需导入 provider 运行时。

{
  "contracts": { "transcriptSourceProviders": ["captions"] },
  "transcriptSources": {
    "captions": {
      "name": "Captions",
      "autoStart": { "accountId": "optional", "meetingUrl": "required" }
    }
  }
}

name 是可选的显示名称。autoStart 通过 transcripts.status 向 Gateway 客户端通告设置控件。它唯一的键是 accountId、guildId、channelId 和 meetingUrl；每个值必须是 "required" 或 "optional"。显式空对象支持在没有定位控件的情况下进行设置。对于仅附加到已激活会议机器人的源，省略 autoStart。格式错误的对象、未知定位键或无效模式不会通告部分设置。标题和自定义会话 ID 仍是现有配置字段，而不是定位描述符键。

设置需要一个已启用的插件。运行时能力仍是观察到的事实：缺失的 canStart 不会隐藏清单描述符，而观察到的 canStart: false 会阻止新的设置。该描述符不会改变对现有 transcripts.autoStart 配置的接受，也不会改变 provider 启动语义。当元数据不可用时，现有源编辑会保留已配置的字段。

backupResources 参考¶

使用 backupResources 声明插件拥有的持久数据（备份必须包含），或 OpenClaw 可以安全省略并在恢复后重新生成的生成数据。备份规划器读取此元数据时不会加载插件运行时或修改插件文件。只有实际激活且可加载的插件才会贡献资源；已禁用或不可加载的插件不能排除数据。

include 声明还会要求 OpenClaw 为该资源管理 SQLite 备份。位于声明路径下或该路径处的 SQLite 文件会获得经过验证的在线快照和离线压缩，其已提交的预写日志（WAL）内容会被包含，而 sidecar 会被省略。当所需 SQLite 能力不可用时，创建会拒绝声明的数据库。在这些资源中声明每个硬链接别名，以便备份可以识别其日志所有者。

其他插件 SQLite 文件仍是不透明字节副本，包括其 sidecar，除非它们别名指向规范的 OpenClaw 数据库。备份会在 warnings 中报告每个不透明 SQLite 文件和 sidecar；验证和恢复会保留其字节，而不会应用 SQLite 验证或压缩。仅仅将数据库放在 state 或 agent 目录下并不会使其加入受管理的快照。未声明的 SQLite 符号链接如果超过链接解析限制（ELOOP），包括循环，会被跳过并带有文件名警告。声明的数据库链接如果无法安全捕获，仍会失败关闭。

{
  "backupResources": [
    {
      "disposition": "include",
      "scope": "state",
      "relativePath": "example-plugin/durable-state"
    },
    {
      "disposition": "regenerable",
      "scope": "agent",
      "relativePath": "example-plugin/generated-cache"
    }
  ]
}

每个条目都是一个封闭对象，且恰好包含以下字段：

插件身份及其受信根来自 manifest 发现；资源条目不能声明或覆盖 owner。relativePath 不能为空或绝对路径，且不能包含反斜杠、NUL、空路径段、.、..、Windows 驱动器或 UNC 前缀、URI 样式的值，或任何逃逸其选定锚点的路径。无效条目会被拒绝，而不是被规范化。

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 渲染和 server-tool 调用仍需要正常的 MCP Apps 设置和生效的工具策略；声明服务器不会绕过这两个边界。

UI 功能¶

在 openclaw.plugin.json 中声明 uiCapabilities，以描述插件为 OpenClaw 界面添加的内容。插件详情页会在安装前以及插件处于禁用或启用状态时，在其 功能 部分显示这些类型。显示读取静态 manifest 或目录元数据，而不执行插件代码。

{
  "uiCapabilities": ["page", "navigation", "accessory", "widget"]
}

该字段是可选的。省略表示未指定；[] 显式声明没有 UI 贡献。OpenClaw 会忽略无效声明（未知值或非数组值）并报告插件警告；插件仍会加载。旧版 OpenClaw 会忽略此字段，因此格式错误的显示元数据不会在更新后破坏现有安装。重复项会被移除，值使用上述顺序。仅声明类型，不声明实例数量或实时可用性。条件注册可能在特定会话中缺失，而不会使声明无效。

此字段独立于 controlUi.entry：使用主机渲染链接阅读器的插件可以声明 link-reader，而无需提供浏览器 JavaScript。它不会激活插件、授予权限，或证明某项功能当前已配置或健康。浏览器注册和已知的后端 UI 注册会在观察到的类型缺失于显式声明时发出诊断；省略会跳过该比较。这些诊断不会阻止激活。

对于目录列表，请随所选插件版本发布相同元数据。如果目录省略它，OpenClaw 会将 UI 贡献类型保留为未指定，而不是加载插件来推断它们。对于原生浏览器模块，显式 UI 重载会读取更新后的声明，并在浏览器代码未更改时创建新修订版本。

controlUi 参考¶

controlUi 为 Control UI 声明受信的原生浏览器入口和可选样式表。路径相对于插件根目录，且必须命名已编译的 JavaScript 和 CSS。资源遵循 Gateway 的认证策略，被捕获为不可变修订版本，并且仅通过显式 UI 重载流程刷新。

用户安装的原生 UI 需要 设置 → 实验室 → 自定义插件 UI （gateway.controlUi.experimental.customPlugins，默认 false）。来自已启用捆绑插件的原生 UI 仍可用。有关重启和浏览器重载要求，请参阅 启用自定义插件 UI。此门控不会禁用插件的后端 API 或下文中的沙箱仪表板绑定。

{
  "controlUi": {
    "entry": "dist/control-ui/<content-hash>/index.js",
    "styles": ["dist/control-ui/<content-hash>/index.css"]
  }
}

使用 package.json.openclaw.controlUi 作为源入口，并让 openclaw plugins build 生成此声明。原生 UI 以浏览器应用程序的信任级别执行；它与下文中的范围化仪表板小部件绑定不同。有关编写、替换、重载和激活回执，请参阅 功能插件。

dashboard 参考¶

dashboard 允许已启用的插件将现有的 Gateway RPC 暴露给已授权的 dashboard 组件，而无需向核心添加插件策略。数据绑定必须指定同一插件通过 operator.read 注册的方法；操作动词必须指定其通过 operator.write 注册的方法。不匹配会在注册期间拒绝该插件。

{
  "dashboard": {
    "dataBindings": [
      {
        "id": "items.list",
        "method": "example.items.list",
        "description": "List example items."
      }
    ],
    "actionVerbs": [
      {
        "id": "refresh",
        "method": "example.items.refresh",
        "description": "Refresh example items.",
        "paramShape": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "force": { "type": "boolean" }
          }
        }
      }
    ]
  }
}

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

catalog 参考¶

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

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

cliCommands 参考¶

在 cliCommands 中声明每个插件拥有的根命令，使根帮助和命令所有者路由保持仅基于元数据：

{
  "cliCommands": [
    {
      "name": "example",
      "description": "Manage the example integration",
      "hasSubcommands": true
    }
  ]
}

清单行是规范帮助文本。在运行时使用 api.registerCli(..., { descriptors: [...] }) 注册同一命令；运行时描述符还可以额外提供 machineOutput。诸如 openclaw nodes <feature> 之类的嵌套命令不是根命令，不应放在 cliCommands 中。

commandAliases 参考¶

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

如果插件加载失败，在聊天中调用其声明的 runtime-slash 命令会返回插件名称、简短的失败原因以及恢复指导（openclaw doctor 和 gateway 日志）。未知命令以及属于有意禁用插件的命令保持其正常处理；仅凭清单所有权不会使命令可执行。

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

qaRunners 参考¶

当插件在共享的 openclaw qa 根下贡献一个或多个传输 runner 时，请使用 qaRunners。保持此元数据轻量且静态；插件运行时仍通过轻量的 qa-runner-api.ts 接口拥有实际的 CLI 注册，该接口导出匹配的 qaRunnerCliRegistrations。对于使用随附 runtime-api.ts 契约的插件，该旧接口在作者迁移期间仍被接受，直至 2026-10-01。可选的 adapterFactory 可将传输暴露给共享 QA 场景，而不会更改已注册命令的 runner。

模块支持的流程场景是一种由 adapter 拥有的执行形式。仅当由该工厂创建的每个 adapter 都实现了 prepareFlow 时，才将 adapterFactory.supportsModuleFlows 设置为 true；QA 规划会从未声明支持的实现中排除模块流程。

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

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

channelAccountKeyPolicies 参考¶

channelAccountKeyPolicies 为插件 channels 数组中列出的通道声明已存储的账户密钥选择规则。它是插件元数据；操作员将其账户配置保存在 channels.<id>.accounts 下。

{
  "channels": ["signal"],
  "channelAccountKeyPolicies": {
    "signal": { "canonicalAliasesRequireOwnField": "account" }
  }
}

canonicalAliasesRequireOwnField 是账户条目中一个字符串字段的名称。仅在 account-id 规范化之后才匹配的别名，在该条目对此字段具有非空值时才有资格。根值不满足此条件。精确的已存储密钥优先；现有的不区分大小写匹配保持其行为。读取器和写入器使用同一选定的已存储密钥。

对于 Signal，当 Work Phone 拥有自己的 account 号码时，它会解析为 work-phone。此时，即使频道根节点也有号码，它的设置也会生效。如果没有自己的号码，之前被忽略的条目仍保持忽略状态，路由会保留其继承的设置。Doctor 会保留该键，并报告所需的手动更改。Doctor 还会报告规范化键冲突，并保留两个条目；精确的 work-phone 键在运行时优先。

未声明频道的规则会被忽略。运行时读取使用所选插件的元数据快照；它们不会加载插件代码来查找规则。有关 SDK 契约，请参阅 账户查找参数。

channelConfigs 参考¶

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

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

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

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

声明了 channels[] 的非捆绑插件也应声明对应的 channelConfigs 条目。如果没有这些条目，OpenClaw 仍然可以加载插件，但在插件运行时执行之前，冷路径配置架构、setup 和 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": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "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 范围内。它不是一般优先级字段，也不会重命名用户配置键。