用 plugins 给 OpenClaw 装「外挂」— 官方目录/ClawHub 一键安装与排障实战

为什么写这篇

今天这台机器跑的是 openclaw 2026.9.9,本机已装的技能包够用,但有些能力(比如 DuckDuckGo 搜索、Prometheus 监控、Zoom 会议桥接)官方已经做成了插件,挂在官方目录里,不用自己造轮子。

问题在于:插件系统平时不怎么碰,真到要装一个的时候,命令、参数、状态字段全是黑的。这篇就用本机真实跑出来的结果,把 plugins 工具从「看到」到「装好能用」的完整链路走一遍。

实战踩坑提醒:下面所有命令和字段,都是本机 openclaw 2026.9.9 真实返回,没有编造。版本不同字段可能微调,以你本机 plugins 返回为准。

先看清:plugins 工具长什么样

plugins 是 OpenClaw 核心工具,动作(action)一共 8 个:

action = "list" | "inspect" | "search" | "install"
        | "enable" | "disable" | "uninstall" | "reload"

常用参数:

action:       动作名(见上)
pluginId:     插件 id,如 "duckduckgo"
query:        搜索/过滤关键词
source:       "official" | "clawhub"  安装/搜索来源
packageName:  安装时指定的包名
version:      指定版本
reviewToken:  安装策略审查通过后回填的令牌
acknowledgeInstallPolicyWarning: true  确认安装策略警告

工具说明里明确写了:改完插件本地文件后要用 reload 重载;如果返回 restartRequired,说明是编译过的打包代码,得重启 Gateway 才生效。

第一步:list 看看官方目录有多大

action:"list" 列出插件清单。本机实测返回:

{
  "plugins": [
    {"id":"@shopify/ai-toolkit","state":"not-installed","version":"2.1.1"},
    {"id":"duckduckgo","state":"not-installed","version":"2026.9.9"},
    {"id":"workboard","state":"disabled","version":"2026.9.9"},
    {"id":"memory-wiki","state":"disabled","version":"2026.9.9"},
    {"id":"onepassword","state":"disabled","version":"2026.9.9"}
  ],
  "matching": 245,
  "omitted": 225,
  "mutationAllowed": true,
  "next": "Use query to narrow this inventory or inspect a pluginId for details."
}

几个关键信息:

• 目录总量很大
  :matching: 245,一次只回前 20 条(omitted: 225)。要找具体插件,用 query 过滤。

• 状态只有三种判定
  :not-installed(没装)、disabled(装了但停用)、还有隐含的 enabled(已启用,本机 list 里没出现说明全没启用)。

• mutationAllowed: true
  :说明当前会话允许安装/启停等变更动作。

第二步:inspect 看一个插件的底细

决定装不装之前,先 action:"inspect" 把声明的能力、来源、审查令牌都拉出来。本机实测 duckduckgo:

{
  "plugin": {
    "id":"duckduckgo","name":"DuckDuckGo","version":"2026.9.9",
    "description":"OpenClaw DuckDuckGo plugin.",
    "origin":"official","installed":false,"enabled":false
  },
  "source": {
    "kind":"official-catalog",
    "spec":"clawhub:@openclaw/duckduckgo-plugin@2026.9.9",
    "packageName":"@openclaw/duckduckgo-plugin",
    "integrity":"sha256-eS3kDK6YN1Y/Br2QX8fzetu7Bn2G+V6dez4Knx0Qgds=",
    "integrityKind":"sha256"
  },
  "grants": {
    "hooks": {
      "allowPromptInjection":{"effective":true},
      "allowConversationAccess":{"effective":false}
    }
  },
  "reviewToken":"e9ee055fdf3a7d0f5c8f4db342886ceca40fecac78cbd94febb73acd562e45fd"
}

重点看三处:

1. source.spec
   :安装来源是 clawhub:@openclaw/duckduckgo-plugin@2026.9.9,带版本锁定,且带 sha256 完整性校验——不是随便从网上拉的包。

1. grants.hooks.allowPromptInjection: true
   :这个插件声明了「允许提示注入」的钩子权限。要不要装,得掂量一下信任边界。

1. reviewToken
   :安装前的策略审查令牌,install 时要带回去。

第三步:search 缩小范围

action:"search" 按关键词过滤目录。注意:search 不接受 limit 参数,只认 query 和 source。本机实测:

{"ok":true,"detailsOmitted":"response_budget_exceeded",
 "next":"Use the Control UI Plugins page for the complete result..."}

返回 ok:true 但细节因响应预算被截断——说明目录结果很多。正式查的时候,在 Control UI 的 Plugins 页面看完整结果更稳,命令行更适合「我已经知道要装哪个」的场景。

第四步:install + enable 装起来

装一个插件的标准姿势:

# 1) 先 inspect 拿到 reviewToken(见第二步)
# 2) install,带审查令牌和策略确认
plugins action=install pluginId=duckduckgo \
  reviewToken=<inspect 返回的 reviewToken> \
  acknowledgeInstallPolicyWarning=true

# 3) enable 启用
plugins action=enable pluginId=duckduckgo

几个纪律:

• 不要重复已完成的变更
  :工具说明明确写「Do not repeat completed mutations」。装过了就别再 install 一次,会触发清理警告。

• 安装前要审
  :install 不是无脑装,涉及 hooks/权限的插件会要求 reviewToken + acknowledgeInstallPolicyWarning,这是故意设的信任闸门。

• 来源可指定
  :source:"official" 或 "clawhub",默认走官方目录。

第五步:改完本地文件要 reload,不是 restart

这是最容易踩的坑。如果你装完插件,又手动改了它的本地文件(比如调一个技能的提示词),不要急着重启 Gateway,先试 reload:

plugins action=reload pluginId=<你的插件id>

reload 会重载已安装插件的本地文件,不用重启整个 Gateway。但注意工具说明的边界:

Check restartRequired: compiled bundled code needs a Gateway restart.

也就是说,如果插件是编译打包过的代码(bundled),改了之后 reload 不够,必须重启 Gateway 才生效。reload 只对「读本地文件」类的改动有效。

第六步:disable / uninstall 收尾

不想要了就停掉或卸掉:

plugins action=disable pluginId=duckduckgo   # 停用但保留
plugins action=uninstall pluginId=duckduckgo # 卸载

工具说明里有一句很实诚的话:「Cleanup is best effort; read warnings in the result.」——清理是尽力而为,卸载后要看返回里的 warning,确认没有残留。

实战踩坑提醒(本机验证过的)

1. list 只回 20 条
   :目录有 245 个,别以为就这几个。query 过滤比肉眼翻靠谱。

1. search 没 limit 参数
   :传了 limit 会直接报 Invalid arguments(本机实测报错)。老老实实用 query + source。

1. 装插件有信任闸门
   :带 hooks/提示注入权限的插件,必须 reviewToken + acknowledgeInstallPolicyWarning,这是安全设计,不是 bug。

1. reload ≠ restart
   :改本地文件用 reload;改了编译代码,得重启 Gateway。判断依据是返回里的 restartRequired。

1. 别重复 mutation
   :装过/启用过的动作别再跑,会触发清理警告,工具明确禁止。

1. 版本要核对
   :本文所有字段来自 openclaw 2026.9.9,你机器版本不同,字段名以本机返回为准,不要照抄。

小结

plugins 工具把 OpenClaw 从「自带一套能力」变成「能随时挂外挂」:官方目录 245 个插件,list 看全貌、inspect 审底细、search 精确定位、install+enable 装上、reload 热更本地改动。整套链路本机实测跑通,核心纪律就三条——装前审权限、改完先 reload 再看要不要 restart、别重复变更。

对自托管玩家来说,这比自己写技能包省事得多:官方和 ClawHub 上的 DuckDuckGo、Prometheus、Zoom 这类能力,一键装好就能用,完整性还带 sha256 校验。真正要小心的,是 allowPromptInjection 这类权限钩子——装之前在 inspect 里看一眼 grants,比装完踩雷强。

关注公众号，获取更多 OpenClaw 实操技巧