如何在 OpenClaw 中安装本地插件

OpenClaw 上的很多插件可以从 ClawHub 一键安装。但开发时更常见的是：插件还在你自己的电脑上------一个本地目录，或者打好的 .tgz 包。这篇教程讲的就是这种本地安装。

你需要准备什么

• 本机已安装 openclaw 命令行，并能正常执行 openclaw --version
• 要装插件的那台机器上，Gateway 正在运行（装到本机就对本机装；装到服务器就 SSH 到服务器再装）
• 一份可安装的插件：
  • 本地目录（里面有 openclaw.plugin.json / package.json 等），或
  • npm pack 打出来的 .tgz 文件

注意：只把某个 tool 的 JSON 描述文件拷进 workspace，不等于 安装插件。必须走 openclaw plugins install。

---

方式一：从本地目录安装（最常用）

假设插件在 ./my-plugin：

openclaw plugins install ./my-plugin

装完后检查是否被识别：

openclaw plugins list
openclaw plugins inspect my-plugin --runtime

把 my-plugin 换成你插件在 openclaw.plugin.json 里声明的 id。

期望看到类似：

• 列表里该插件为 enabled
• inspect 里 Status: loaded
• 若插件注册了 tool，能在输出里看到 tool 名称

然后重启或 reload Gateway，让运行时真正加载插件。

---

方式二：从 .tgz 包安装

先打好包（在插件项目目录）：

npm pack
# 会生成类似 my-plugin-0.1.0.tgz

再安装：

openclaw plugins install npm-pack:./my-plugin-0.1.0.tgz --force

较新的 OpenClaw（例如 2026.9 一带）对「非 ClawHub 来源」可能还会要求你确认能力声明，这时加上：

openclaw plugins install npm-pack:./my-plugin-0.1.0.tgz --force --accept-capabilities

同样用 plugins inspect <id> --runtime 验收，然后重启 Gateway。

---

让模型真的能调用插件里的工具

有些插件的 tool 标成了 optional。插件「已加载」不等于对话里一定能调到。

常见做法是在对应 Agent 的配置里用 alsoAllow 额外放行 （不要把整个 tools.allow 收成只剩少数几个工具，以免影响正常聊天）：

{
  "tools": {
    "profile": "full",
    "alsoAllow": ["your_tool_name"]
  }
}

把 your_tool_name 换成插件实际注册的 tool 名；有多个就都写上。改完后按你环境的要求 reload / 重启。

---

怎么算装成功了

按下面三条自检即可：

1. openclaw plugins inspect <插件id> --runtime → Status: loaded
2. 配置里已放行需要的 tool（如用了 alsoAllow）
3. 打开对话，让模型做一件必须靠该 tool 才能完成的事 → 聊天里出现 tool call，而不是只在正文里「口头说做完了」

---

常见问题

装完了，对话里还是没有这个工具？

多半是 optional tool 没放进 allowlist / alsoAllow，或装完没重启 Gateway。

我在自己电脑上装好了，线上还是没有？

插件装在「执行 plugins install 的那台 Gateway」上。本机安装不会同步到远程服务器，要在目标机器（或对应容器）里再装一次。

控制台 / 面板的插件列表里看不到？

有的管理面板只展示特定安装渠道（例如装到 extensions/ 的托管插件）。CLI 装成功、runtime loaded，功能仍然可用；以 plugins inspect 为准。

提示要 accept capabilities / 不信任的来源？

本地路径和 .tgz 不在 ClawHub 审核列表里，属正常提示。确认插件来源可信后，使用文档要求的 --force / --accept-capabilities 即可。

---

小结

1. 准备本地目录或 .tgz
2. openclaw plugins install ...
3. plugins inspect ... --runtime 确认 loaded
4. 按需配置 alsoAllow
5. 重启 Gateway，用真实对话验收 tool call

按这五步，本地插件就能在 OpenClaw 里跑起来。

文章来自：aimaji.top/blog/opencl...