插件清单 (openclaw.plugin.json)

每个 OpenClaw 插件必须在插件根目录提供 openclaw.plugin.json 清单文件。OpenClaw 使用此清单在不执行插件代码的情况下验证配置。缺失或无效的清单将被视为插件错误,并阻止配置验证。

必需字段

最小清单文件:

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

string

required

插件的唯一标识符。必须与 plugins.entries.<id> 中的键匹配。命名规范:

使用小写字母和连字符
避免与核心功能冲突
例如: voice-call, memory-lancedb, custom-auth

configSchema

object

required

插件配置的 JSON Schema。用于在运行时加载前验证用户配置。即使插件不接受配置,也必须提供空 schema:

{
  "type": "object",
  "additionalProperties": false,
  "properties": {}
}

可选字段

kind

string

插件类型标识。当前支持:

"memory" - 记忆系统插件

示例:

{
  "id": "memory-lancedb",
  "kind": "memory"
}

channels

string[]

该插件注册的消息平台 ID 列表。用于配置验证:如果 channels.<id> 出现在配置中但未在任何插件清单中声明,将报错。示例:

{
  "id": "matrix",
  "channels": ["matrix"]
}

providers

string[]

该插件注册的 AI 模型提供商 ID 列表。示例:

{
  "id": "custom-llm",
  "providers": ["custom-provider"]
}

skills

string[]

要加载的技能目录列表,相对于插件根目录。示例:

{
  "id": "voice-call",
  "skills": ["skills"]
}

OpenClaw 会在 <plugin-root>/skills/ 下查找技能文件。

name

string

插件的显示名称。用于日志和用户界面。示例:

{
  "id": "voice-call",
  "name": "Voice Call"
}

description

string

插件的简短描述。示例:

{
  "id": "voice-call",
  "description": "Voice-call plugin with Telnyx/Twilio/Plivo providers"
}

version

string

插件版本号(仅供参考)。建议遵循语义化版本规范。示例:

{
  "id": "my-plugin",
  "version": "1.2.3"
}

uiHints

object

用于 UI 渲染的配置字段提示。键为配置路径,值为提示对象。提示对象字段:

label: 字段标签
help: 帮助文本
placeholder: 输入占位符
sensitive: 是否为敏感信息(如密码)
advanced: 是否为高级选项
tags: 标签列表

示例:

{
  "uiHints": {
    "apiKey": {
      "label": "API Key",
      "sensitive": true,
      "placeholder": "输入你的 API key"
    },
    "timeout": {
      "label": "超时(毫秒)",
      "advanced": true
    },
    "nested.field": {
      "label": "嵌套字段",
      "help": "这是一个嵌套配置项"
    }
  }
}

JSON Schema 要求

基础规则

所有插件必须提供 JSON Schema,即使不接受任何配置
Schema 在配置读取/写入时验证,不是运行时验证
使用 additionalProperties: false 防止意外的配置键

空配置 Schema

对于不接受配置的插件:

{
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

带属性的 Schema

{
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "enabled": {
        "type": "boolean"
      },
      "apiKey": {
        "type": "string",
        "minLength": 10
      },
      "timeout": {
        "type": "integer",
        "minimum": 1000,
        "maximum": 60000,
        "default": 5000
      },
      "endpoints": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "required": ["apiKey"]
  }
}

嵌套对象

{
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "provider": {
        "type": "string",
        "enum": ["twilio", "telnyx", "plivo"]
      },
      "twilio": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "accountSid": {
            "type": "string"
          },
          "authToken": {
            "type": "string"
          }
        }
      }
    }
  }
}

条件验证

使用 if/then/else 进行条件验证:

{
  "configSchema": {
    "type": "object",
    "properties": {
      "provider": {
        "type": "string",
        "enum": ["openai", "anthropic"]
      },
      "apiKey": {
        "type": "string"
      }
    },
    "if": {
      "properties": {
        "provider": { "const": "openai" }
      }
    },
    "then": {
      "required": ["apiKey"]
    }
  }
}

验证行为

OpenClaw 在以下时机验证配置:

配置读取时

openclaw config get 或 openclaw doctor 会验证所有插件配置

配置写入时

openclaw config set 会验证受影响的插件配置

网关启动时

加载插件前验证所有启用的插件配置

验证错误

未知频道 ID:

// 错误:没有插件声明 "unknown-channel"
{
  channels: {
    "unknown-channel": {
      enabled: true,
    },
  },
}

未知插件 ID:

// 错误:插件 "nonexistent-plugin" 未安装
{
  plugins: {
    entries: {
      "nonexistent-plugin": {
        config: {},
      },
    },
  },
}

配置不匹配 Schema:

// 错误:apiKey 是必需的
{
  plugins: {
    entries: {
      "my-plugin": {
        config: {
          timeout: 5000,
          // 缺少 apiKey
        },
      },
    },
  },
}

禁用插件的配置

如果插件被禁用但有配置,OpenClaw 会:

保留配置(不删除)
在 doctor 中显示警告
在日志中记录警告
不验证配置(因为插件未加载)

{
  plugins: {
    deny: ["my-plugin"], // 插件被禁用
    entries: {
      "my-plugin": {
        config: {
          // 这些配置会保留但不使用
        },
      },
    },
  },
}

完整示例

简单插件清单

{
  "id": "hello-world",
  "name": "Hello World",
  "version": "1.0.0",
  "description": "A simple example plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "enabled": {
        "type": "boolean"
      },
      "message": {
        "type": "string"
      }
    }
  },
  "uiHints": {
    "enabled": {
      "label": "启用插件"
    },
    "message": {
      "label": "问候消息",
      "placeholder": "输入问候消息"
    }
  }
}

完整功能清单

{
  "id": "voice-call",
  "name": "Voice Call",
  "version": "2026.3.3",
  "description": "Voice-call plugin with Telnyx/Twilio/Plivo providers",
  "skills": ["skills"],
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "enabled": { "type": "boolean" },
      "provider": {
        "type": "string",
        "enum": ["telnyx", "twilio", "plivo", "mock"]
      },
      "fromNumber": {
        "type": "string",
        "pattern": "^\\+[1-9]\\d{1,14}$"
      },
      "toNumber": {
        "type": "string",
        "pattern": "^\\+[1-9]\\d{1,14}$"
      },
      "twilio": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "accountSid": { "type": "string" },
          "authToken": { "type": "string" }
        }
      },
      "serve": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "port": { "type": "integer", "minimum": 1 },
          "bind": { "type": "string" },
          "path": { "type": "string" }
        }
      }
    }
  },
  "uiHints": {
    "provider": {
      "label": "Provider",
      "help": "Use twilio, telnyx, or mock for dev/no-network."
    },
    "fromNumber": {
      "label": "From Number",
      "placeholder": "+15550001234"
    },
    "toNumber": {
      "label": "Default To Number",
      "placeholder": "+15550005678"
    },
    "twilio.accountSid": {
      "label": "Twilio Account SID"
    },
    "twilio.authToken": {
      "label": "Twilio Auth Token",
      "sensitive": true
    },
    "serve.port": {
      "label": "Webhook Port"
    },
    "serve.bind": {
      "label": "Webhook Bind",
      "advanced": true
    }
  }
}

消息平台插件清单

{
  "id": "matrix",
  "name": "Matrix",
  "channels": ["matrix"],
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "enabled": { "type": "boolean" },
      "homeserver": {
        "type": "string",
        "format": "uri"
      },
      "accessToken": {
        "type": "string"
      },
      "allowFrom": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["homeserver", "accessToken"]
  },
  "uiHints": {
    "homeserver": {
      "label": "Homeserver URL",
      "placeholder": "https://matrix.org"
    },
    "accessToken": {
      "label": "Access Token",
      "sensitive": true
    },
    "allowFrom": {
      "label": "允许的用户 ID"
    }
  }
}

最佳实践

使用 additionalProperties: false

防止意外的配置键,帮助用户发现拼写错误

{
  "type": "object",
  "additionalProperties": false,
  "properties": { ... }
}

提供默认值

在 schema 中设置合理的默认值

{
  "timeout": {
    "type": "integer",
    "default": 5000
  }
}

标记敏感字段

使用 uiHints 标记密码、token 等敏感信息

{
  "uiHints": {
    "apiKey": { "sensitive": true }
  }
}

使用 enum 限制选项

对于有限的选项集合,使用 enum 约束

{
  "provider": {
    "type": "string",
    "enum": ["openai", "anthropic", "ollama"]
  }
}

添加格式验证

使用 format、pattern 验证特定格式

{
  "email": {
    "type": "string",
    "format": "email"
  },
  "phone": {
    "type": "string",
    "pattern": "^\\+[1-9]\\d{1,14}$"
  }
}

提供 UI 提示

为所有用户可配置的字段提供 label 和 help

{
  "uiHints": {
    "timeout": {
      "label": "超时(毫秒)",
      "help": "API 请求的超时时间,范围 1000-60000"
    }
  }
}

常见问题

清单文件必须在哪里?

openclaw.plugin.json 必须在插件根目录,与 package.json 同级。

my-plugin/
├── openclaw.plugin.json  ✅ 正确位置
├── package.json
├── src/
│   └── index.ts
└── dist/

可以省略 configSchema 吗?

不可以。即使插件不接受配置,也必须提供空 schema:

{
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

如何验证清单文件?

使用 openclaw doctor 检查插件配置:

openclaw doctor

它会报告清单错误和配置验证问题。

清单更改后需要做什么?

重新构建插件(如果需要)
重启网关以重新加载清单

openclaw gateway restart

uiHints 是必需的吗?

不是必需的,但强烈推荐。它提供更好的用户体验,特别是在 UI 配置工具中。

下一步

创建插件

从零开始构建你的第一个插件

Plugin SDK

探索完整的 SDK API 参考

代理工具

为 AI 代理添加自定义工具

插件系统

扩展示例

插件清单

插件清单 (openclaw.plugin.json)

必需字段

可选字段

JSON Schema 要求

基础规则

空配置 Schema

带属性的 Schema

嵌套对象

条件验证

验证行为

验证错误

禁用插件的配置

完整示例

简单插件清单

完整功能清单

消息平台插件清单

最佳实践

常见问题

下一步

创建插件

Plugin SDK

代理工具

插件系统

扩展示例

​插件清单 (openclaw.plugin.json)

​必需字段

​可选字段

​JSON Schema 要求

​基础规则

​空配置 Schema

​带属性的 Schema

​嵌套对象

​条件验证

​验证行为

​验证错误

​禁用插件的配置

​完整示例

​简单插件清单

​完整功能清单

​消息平台插件清单

​最佳实践

​常见问题

​下一步

创建插件

Plugin SDK

代理工具

插件清单 (openclaw.plugin.json)

必需字段

可选字段

JSON Schema 要求

基础规则

空配置 Schema

带属性的 Schema

嵌套对象

条件验证

验证行为

验证错误

禁用插件的配置

完整示例

简单插件清单

完整功能清单

消息平台插件清单

最佳实践

常见问题

下一步