OpenClaw.NET 兼容性目录指南(Compatibility Catalog)

面向 OpenClaw.NET 用户与贡献者的 compat/public-smoke.json 完整技术指南。

概述

compat/public-smoke.json 是 OpenClaw.NET 兼容性验证体系的核心清单文件。它承担着以下关键职责：

• 集中管理
  
  所有已知公开插件（NPM Plugin）和技能（ClawHub Skill）的预期行为；
• 作为自动化烟雾测试（Public Smoke Tests） 的唯一数据源；
• 通过 CLI 命令 与 REST API 暴露给运维与集成方查询；
• 在构建期作为嵌入资源（Embedded Resource）编译进 OpenClaw.Core 程序集，对 NativeAOT 完全友好，运行时无需访问文件系统。

无论是发布前的回归验证、外部集成方的兼容性自查，还是社区贡献者新增插件，都以该清单为唯一事实来源（Single Source of Truth）。

文件结构

清单顶层是一个带版本号的 JSON 对象，entries 字段为条目数组：

{"version":2,"entries":[{"id":"agentseo-plugin","category":"ts-jiti-plugin","kind":"npm-plugin","spec":"@agentseo/openclaw-plugin@0.1.4","packageName":"@agentseo/openclaw-plugin","pluginId":"agentseo","expectedStatus":"compatible","configJson":"{\"apiKey\":\"test_key\"}","expectedToolNames":["agentseo_audit","agentseo_keywords"],"expectedSkillNames":["agentseo"]}]}

条目字段说明

字段按用途分为三组：通用字段、技能专用字段、插件专用字段。

通用字段（所有条目必填）

技能专用字段（kind == "clawhub-skill"）

插件专用字段（kind == "npm-plugin"）

⚠️ 注意：NPM 插件条目必须显式指定 expectedStatus，编译期校验会拒绝缺失该字段的条目。

场景分类详解

OpenClaw.NET 共定义了 5 种 category，覆盖了从纯技能到负面用例的全部典型场景：

正面与负面场景

正面场景（expectedStatus = "compatible"）

• 验证插件/技能能够成功加载；
• 验证声明的工具和技能均正确暴露到 Gateway；
• 使用 expectedToolNames 与 expectedSkillNames 进行断言；
• 任何缺失或多余的工具/技能均判定为失败。

负面场景（expectedStatus = "incompatible"）

• 验证错误能被系统显式检测并拒绝，而非”部分加载”或静默忽略；
• 使用 expectedDiagnosticCodes 断言错误码；
• 典型诊断码：

使用方式

CLI 查询

OpenClaw CLI 提供 compatibility catalog 子命令，便于本地查询与脚本消费：

# 查看所有条目openclaw compatibility catalog# 按状态过滤openclaw compatibility catalog --status compatibleopenclaw compatibility catalog --status incompatible# 按类型与分类过滤openclaw compatibility catalog --kind npm-plugin --category ts-jiti-plugin# JSON 格式输出（适用于程序化消费）openclaw compatibility catalog --json# 简写形式openclaw compat catalog

REST API

Gateway 通过 /api/integration/compatibility 路由族对外暴露：

GET /api/integration/compatibility/catalogGET /api/integration/compatibility/catalog?compatibilityStatus=compatibleGET /api/integration/compatibility/catalog?kind=npm-plugin&category=ts-jiti-pluginGET /api/integration/compatibility/export

• /catalog
  
   端点支持 compatibilityStatus、kind、category 三个查询参数过滤；
• /export
  
   端点返回完整的兼容性报告，包含运行时模式（AOT / JIT）、安全态势（Security Posture）、通道就绪状态（Channel Readiness）等额外维度，适合在 CI 中归档或对接外部门户。

自动化测试

测试类 PublicCompatibilitySmokeTests 在运行时自动读取清单并迭代执行：

• 触发开关
  
  ：环境变量 OPENCLAW_PUBLIC_SMOKE=1必须设置，否则测试整体跳过；
• ClawHub 技能
  
  ：通过 npx clawhub 安装并校验 expectedRelativePath 文件存在；
• compatible 插件
  
  ：执行安装、加载、然后断言 expectedToolNames / expectedSkillNames 完整暴露；
• incompatible 插件
  
  ：执行安装、加载，断言加载失败且诊断码集合至少包含expectedDiagnosticCodes 中的全部条目。

CI/CD 集成

在 GitHub Actions 中，public-compatibility-smoke 作业承担清单的回归验证：

• 触发条件
  
  ：定时执行（schedule）或手动派发（workflow_dispatch）；
• 依赖环境
  
  ：Node.js 20（用于 npm 与 clawhub 命令链路）；
• 执行流程
  
  ：dotnet test + --filter Category=PublicSmoke；
• 报告产物
  
  ：生成 TRX 格式测试报告并作为 artifact 上传；
• 失败语义
  
  ：任意条目断言失败即视为整个作业失败，需在合并前修复。

如何贡献新条目

添加新技能

{"id":"my-new-skill","category":"pure-skill","kind":"clawhub-skill","slug":"my-new-skill","version":"1.0.0","expectedRelativePath":"skills/my-new-skill/SKILL.md"}

添加兼容插件（正面场景）

{"id":"my-plugin","category":"js-tool-plugin","kind":"npm-plugin","spec":"@my-org/openclaw-plugin@1.0.0","packageName":"@my-org/openclaw-plugin","pluginId":"my-plugin","expectedStatus":"compatible","configJson":"{\"apiKey\":\"test_key\"}","expectedToolNames":["my_tool_1","my_tool_2"],"expectedSkillNames":["my-skill"]}

添加不兼容场景（负面场景）

{"id":"broken-plugin-example","category":"config-schema-plugin","kind":"npm-plugin","spec":"@my-org/broken-plugin@1.0.0","packageName":"@my-org/broken-plugin","pluginId":"broken-plugin","expectedStatus":"incompatible","configJson":"{\"wrongField\": 123}","expectedDiagnosticCodes":["config_one_of_mismatch"]}

贡献流程

1. 在 compat/public-smoke.json 的 entries 数组末尾追加条目；

2. 确保必填字段完整：

• NPM 插件
  
  ：必须包含 expectedStatus、spec、packageName、pluginId；
• 技能
  
  ：必须包含 slug、version、expectedRelativePath；

3. 本地设置 OPENCLAW_PUBLIC_SMOKE=1 并执行：

   dotnet test OpenClaw.Net.slnx --filterCategory=PublicSmoke

4. 如引入了新的 category 或 kind，需同步：

• 升级清单顶层 version 字段；
• 更新 PublicCompatibilityCatalog 中的枚举与转换逻辑；
• 更新本文档的场景分类详解表格。

数据转换逻辑

清单在运行时通过 PublicCompatibilityCatalog.CreateCatalog() 转换为富目录（Rich Catalog），以便 CLI 与 REST API 直接消费。核心映射规则如下：

与 NativeAOT 的关系

OpenClaw.NET 的 NativeAOT 约束直接影响清单的加载与序列化方式：

• 嵌入资源
  
  ：compat/public-smoke.json 在 .csproj 中以 <EmbeddedResource> 方式编译进 OpenClaw.Core.dll，运行时无任何文件 I/O；
• JSON 源生成
  
  ：使用 CoreJsonContext（基于 JsonSerializerContext 的 source generator）反序列化清单，完全规避反射；
• 桥接协议
  
  ：插件通过 plugin-bridge.mjs 走 JSON-RPC over stdio，避免在主进程中动态加载托管程序集；
• AOT/JIT 一致性
  
  ：清单驱动的烟雾测试同时覆盖 AOT 与 JIT 两种发布模式，确保行为一致。

故障排查