插件

理解 OpenClaw Plugins：用于增加工具、渠道、模型提供商、hooks、语音、媒体和 packaged skills 的可安装能力。

Plugins 给 OpenClaw 增加运行时能力。Skill 教 Agent 怎么做，Plugin 则让某个能力真的存在：代码、凭证、生命周期 hooks 和 manifest contract 都在这里。

Plugin 能添加什么

OpenClaw plugins 可以提供：

• tools
• channel adapters
• model providers
• web search / web fetch providers
• speech 和 realtime voice
• media generation
• hooks
• CLI surfaces
• packaged skills
• UI 或 node 相关能力

什么时候用 Plugin

当你需要这些能力时，用 Plugin：

• 调用新的 API
• 增加一个新渠道
• 增加模型提供商
• 需要持久化生命周期状态
• 需要二进制、包元数据或 runtime hooks
• 想分发和更新能力

纯文字流程说明够用时，用 Skill。

安装与管理

openclaw plugins list
openclaw plugins install <plugin>
openclaw plugins enable <plugin>
openclaw plugins disable <plugin>
openclaw plugins doctor <plugin>
openclaw plugins uninstall <plugin>

安装后如果插件依赖 native packages、外部服务或凭证，先跑 doctor。

Plugin Contracts

一个插件应该明确声明它贡献了什么：

• tool definitions 和 schema
• channel account 行为
• provider catalog 和 auth
• hook events
• packaged skill directories
• permission requests

Contract 是信任边界的一部分。启用前要知道它给 OpenClaw 增加了什么。

Bundled 与 External

有些插件随 OpenClaw 发布，有些按需安装，有些由社区维护。很多渠道、媒体和搜索 provider 都是 plugin-backed。

这会影响运维：

• 更新插件可以修复渠道问题
• 缺少 optional packages 会禁用能力
• plugin auth 可能独立于 agent auth
• plugin tools 仍然经过正常工具策略过滤

Publishing

如果你构建了可复用能力，优先通过 plugin 路径发布，而不是要求用户把很长的设置说明粘进 AGENTS.md。

好的 plugin package 应包含：

• 窄范围 manifest
• 显式配置
• 安全凭证处理
• 设置和排查文档
• 测试或 smoke checks
• 不带意外的宽权限

安全检查

启用插件前：

1. 确认来源和维护者。
2. 检查它请求的 tools、channels、hooks 或 provider 能力。
3. 检查凭证存储和 SecretRef 支持。
4. 运行 validation 或 doctor。
5. 保持 Agent 工具 profile 尽量窄。
6. 对不可信输入使用沙盒。