openclaw-plugin-swagger

读取服务器上的 Swagger / OpenAPI JSON 文件，将接口归一化后暴露给 OpenClaw。

当前提供三个入口：

• swagger_list_operations
• swagger_match_operations
• /swagger-debug [keyword]

能力范围：

• 读取并解析指定的 Swagger/OpenAPI JSON 文件
• 识别接口路径、方法、标签、摘要、参数、请求体和响应摘要
• 根据关键词匹配相关接口

开发

在仓库根目录执行：

npm install
npm run build:plugin:swagger
npm run smoke:plugin:swagger

使用说明

npm 安装

openclaw plugins install @sam201363/openclaw-plugin-swagger
openclaw plugins enable openclaw-plugin-swagger
openclaw gateway restart

Swagger 文件配置

需要先把 Swagger 文档上传到服务器，例如：

mkdir -p /home/admin/swagger
cp data.json /home/admin/swagger/data.json

插件读取路径的优先级是：

1. OpenClaw 插件配置 plugins.entries.openclaw-plugin-swagger.config.specPath
2. 环境变量 OPENCLAW_SWAGGER_SPEC_PATH
3. 默认路径 /home/admin/swagger/data.json

推荐配置方式一：~/.openclaw/openclaw.json

{
  plugins: {
    entries: {
      "openclaw-plugin-swagger": {
        enabled: true,
        config: {
          specPath: "/home/admin/swagger/data.json"
        }
      }
    }
  }
}

推荐配置方式二：OpenClaw 服务环境变量

export OPENCLAW_SWAGGER_SPEC_PATH=/home/admin/swagger/data.json

修改配置后，重启 Gateway 生效。

• swagger_list_operations
  • 支持按 method、pathKeyword、tag、limit 过滤接口
• swagger_match_operations
  • 支持按 query、method、limit 做关键词匹配
• /swagger-debug
  • 不带参数时展示文档摘要和部分接口
  • 带关键词时展示匹配结果

当前限制

• 第一版只支持读取 JSON 格式的 Swagger/OpenAPI 文档
• 第一版按当前样本的 OpenAPI 3 结构实现，但兼容部分 Swagger 2 字段
• $ref 当前只返回引用摘要，不做深度展开