插件为 OpenClaw 扩展频道、工具、语音、搜索等能力，安装后需要 Gateway 重启才生效。用 openclaw plugins install <来源>:<包> 从 ClawHub / npm / git / 本地路径安装，openclaw plugins inspect <id> --runtime --json 验证运行态是否加载。plugins.deny 高于所有其他规则，独占插槽（memory 等）可强制启用对应插件。

OpenClaw 插件安装与配置排查指南

插件为 OpenClaw 扩展了频道、模型 provider、智能体框架、工具、技能、语音、实时转录、实时语音、媒体理解与生成、网页抓取与搜索等运行时能力。

安装插件前确认：

• 已安装 openclaw CLI 并能在终端执行
• 能访问 ClawHub、npm 或 git 主机等目标源
• 准备好插件文档要求的凭据、配置键或操作系统工具
• 有对应频道的 Gateway 重启/重载权限

快速开始（5 步）

1. 查找插件

从 ClawHub 搜索社区插件：

openclaw plugins search "calendar"

ClawHub 是社区插件的主要发现入口。过渡期内裸包名仍从 npm 安装；需要确定源时加上前缀。

2. 安装插件

# 从 ClawHub
openclaw plugins install clawhub:<package>

# 从 npm
openclaw plugins install npm:<package>

# 从 git 仓库（分支、标签或 commit）
openclaw plugins install git:github.com/<owner>/<repo>@<ref>

# 从本地开发目录
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin

生产环境推荐锁定版本号。

3. 配置并启用

在 plugins.entries.<id>.config 下设置插件专属配置。未启用的插件需要手动启用：

openclaw plugins enable <plugin-id>

如果配置文件里存在 plugins.allow 限制列表，安装的插件 ID 必须出现在该列表中才能加载。openclaw plugins install 会自动将已安装 ID 加入 plugins.allow 并从 plugins.deny 移除，确保重启后能加载。

4. 重启 Gateway

插件代码的安装、更新、卸载都需要 Gateway 重启。如果已启动的托管 Gateway 开启了配置重载，OpenClaw 检测到插件安装记录变化后会自动重启。如果没有托管或禁用重载，手动重启：

openclaw gateway restart

启用/禁用操作只更新配置和冷注册表。要确认运行时状态，必须走运行时检查。

5. 验证运行时注册

openclaw plugins inspect <plugin-id> --runtime --json

加 --runtime 可以确认已注册的工具、钩子、服务、Gateway 方法或插件专属 CLI 命令。不加 --runtime 只检查冷清单和注册表状态。

配置

选择安装源

源	适用场景	示例
ClawHub	需要 OpenClaw 原生发现、扫描、版本元数据和安装提示	openclaw plugins install clawhub:<package>
npm	需要直接操作 npm 注册表或 dist-tag	openclaw plugins install npm:<package>
git	需要仓库的某个分支、标签或 commit	openclaw plugins install git:github.com/<owner>/<repo>@<ref>
本地路径	在同一台机器上开发或测试插件	openclaw plugins install --link ./my-plugin
marketplace	安装 Claude 兼容的 marketplace 插件	openclaw plugins install &lt;plugin&gt; --marketplace <source>

裸包名（不加前缀）的兼容行为：如果裸名匹配内置插件 ID，使用内置源；如果匹配官方外部插件 ID，使用官方包目录；其他裸包名在过渡期间通过 npm 安装。需要确定源时，请使用 clawhub:、npm:、git: 或 npm-pack: 前缀。

配置插件策略

常见的插件配置结构：

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    slots: { memory: "memory-core" },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

策略规则说明：

• plugins.enabled: false 禁用所有插件，跳过发现/加载。生效期间旧插件引用不生效；重新启用后需要 doctor 清理时才会移除过期 ID。
• plugins.deny 优先于 allow 和单插件启用。
• plugins.allow 是白名单。不在白名单内的插件工具始终不可用，即使 tools.allow 包含 "*"。
• plugins.entries.<id>.enabled: false 禁用单个插件但保留其配置。
• plugins.load.paths 添加显式本地插件文件或目录。
• 工作区来源的插件默认禁用，必须显式启用或加入白名单。
• 内置插件遵循内置的默认启用/禁用元数据，除非配置显式覆盖。
• plugins.slots.<slot> 为独占类别（如记忆、上下文引擎）选择一个插件。插槽选择会强制启用该插件（视为显式激活），但 plugins.deny 和 plugins.entries.<id>.enabled: false 仍可阻止它。
• 内置的 opt-in 插件在配置命名其拥有的表面（如 provider/model 引用、频道配置、CLI 后端、智能体框架运行时）时可自动激活。
• OpenAI 系列 Codex 路由保持 provider 和运行时插件边界分离：openai-codex/* 是 legacy OpenAI provider 配置，内置 codex 插件负责 Codex app-server 运行时（对应 openai/* 代理引用、agentRuntime.id: "codex" 和 legacy codex/* 引用）。

配置校验出现过期插件 ID、白名单与工具不匹配或遗留内置插件路径时，运行 openclaw doctor 或 openclaw doctor --fix。

理解插件格式

OpenClaw 识别两种插件格式：

格式	加载方式	适用场景
原生 OpenClaw 插件	openclaw.plugin.json + 进程内运行时模块	安装或构建 OpenClaw 专属运行时能力
兼容 Bundle	将 Codex/Claude/Cursor 插件布局映射到 OpenClaw 插件清单	复用兼容的技能、命令、钩子或 bundle 元数据

两种格式都会出现在 openclaw plugins list、inspect、enable、disable 等命令中。bundle 兼容边界参见 Plugin bundles，原生插件作者参见 Building plugins。

冷热两张图：验证活动 Gateway

openclaw plugins list 和普通的 openclaw plugins inspect 读取的是冷配置、清单和注册表状态。它们不能证明已运行的 Gateway 已导入同样的插件代码。

如果插件显示已安装但聊天流量没有使用它：

openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw gateway restart

托管 Gateway 在插件安装、更新、卸载等源变更后会自动重启。在 VPS 或容器上手动重启时，确保目标是实际服务频道的 openclaw gateway run 子进程，而不是 wrapper 或 supervisor。

故障排查

症状	检查方法	修复操作
插件在 plugins list 中但运行时钩子不执行	用 openclaw plugins inspect <id> --runtime --json 确认，再跑 gateway status --deep --require-rpc 确认活动 Gateway	安装、更新、配置或源变更后重启活动 Gateway
出现重复频道或工具归属诊断	跑 openclaw plugins list --enabled --verbose，对每个嫌疑插件用 --runtime --json 检查频道/工具归属	禁用一个所有者、移除过期安装、或用 manifest 的 preferOver 做有意替换
配置提示插件缺失	查 Plugin inventory 确认是内置、官方外部还是仅源码	安装外部包、启用内置插件、或移除过期配置
安装时配置无效	读校验信息，提示过期插件状态时跑 openclaw doctor --fix	Doctor 可以通过禁用入口并移除无效负载来隔离无效插件配置
插件路径因可疑所有权或权限被阻止	先检查配置错误前的诊断信息	修复文件系统所有权/权限，然后跑 openclaw plugins registry --refresh
OPENCLAW_NIX_MODE=1 阻止生命周期命令	确认安装由 Nix 管理	在 Nix source 中更改插件选择，不要用插件修改命令
运行时依赖导入失败	检查插件是通过 npm/git/ClawHub 安装还是从本地路径加载	跑 openclaw plugins update <id>、重装源、或自己安装本地插件依赖

当过期插件配置仍指向已不存在的频道插件时，Gateway 启动时会跳过那个插件支持的频道，不会阻塞其他频道。跑 openclaw doctor --fix 移除过期插件和频道条目。没有过期插件证据的未知频道键仍会校验失败，以便发现拼写错误。

有意替换频道时，首选的插件应在 channelConfigs.<channel-id>.preferOver 中声明被替换的插件 ID。如果两个插件都显式启用，OpenClaw 会保留该请求并报告重复频道或工具诊断，而不是静默选一个所有者。

如果安装的包提示 requires compiled runtime output for TypeScript entry ...，说明包发布时缺少 OpenClaw 运行需要的 JavaScript 文件。等发布者编译后更新或重装，或者暂时禁用/卸载该插件。

插件路径所有权被阻止

如果插件诊断提示 blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) 且配置校验紧随其后报 plugin present but blocked，说明插件文件由与加载进程不同的 Unix 用户拥有。保留插件配置，修复文件系统所有权，或用同一个用户运行 OpenClaw。

Docker 环境：官方镜像以 node（uid 1000）运行，所以主机挂载的 OpenClaw 配置和工作区目录通常应属于 uid 1000：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

如果你故意以 root 运行 OpenClaw，将托管插件根目录改为 root 所有：

sudo chown -R root:root /path/to/openclaw-config/npm

修复所有权后，重新跑 openclaw doctor --fix 或 openclaw plugins registry --refresh 让持久化插件注册表匹配已修复的文件。

插件工具设置慢

如果智能体 turn 在准备工具时卡住，开启 trace 日志并检查插件工具工厂时间：

openclaw config set logging.level trace
openclaw logs --follow

查找：

[trace:plugin-tools] factory timings ...

摘要列出总工厂时间和最慢的插件工具工厂，包括插件 ID、声明的工具名、结果形状和是否可选。单个工厂至少 1 秒或总插件工具工厂准备至少 5 秒时，慢的行会升级为警告。

OpenClaw 会缓存重复请求上下文中成功的插件工具工厂结果。缓存键包含有效运行时配置、工作区、智能体/会话 ID、沙箱策略、浏览器设置、投递上下文、请求者身份和所有权状态。因此当上下文变化时，依赖这些字段的工厂会重新运行。如果耗时仍然高，插件可能在做重量的工作后才返回工具定义。

如果一个插件占用了大部分时间，用以下命令检查它的运行时注册：

openclaw plugins inspect <plugin-id> --runtime --json

然后更新、重装或禁用该插件。插件作者应将重量级依赖加载移到工具执行路径内，而不是在工具工厂中完成。

关于依赖根、包元数据校验、注册表记录、启动重载行为和过期清理，参见 Plugin dependency resolution。

相关文档

• Manage plugins — 安装、更新、卸载、发布的命令示例
• openclaw plugins — 完整 CLI 参考
• Plugin inventory — 内置和外部插件清单
• Plugin reference — 每个插件的详细参考页
• Community plugins — ClawHub 发现和文档 PR 策略
• Plugin dependency resolution — 安装根、注册表记录和运行时边界
• Building plugins — 原生插件开发指南
• Plugin SDK overview — 运行时注册、钩子和 API 字段
• Plugin manifest — manifest 和包元数据

常见问题

插件明明安装了但聊天里用不上？

openclaw plugins list 显示已安装不代表 Gateway 运行时已加载它。用 openclaw plugins inspect <id> --runtime --json 检查运行态注册，然后 openclaw gateway status --deep --require-rpc 确认活动 Gateway 是哪个进程。缺失运行态注册 -> 手动重启 Gateway。

插件依赖导入失败怎么办？

先确认插件来源：npm/git/ClawHub 还是本地路径。对应操作：openclaw plugins update <id>、重装源、或自己在本地安装插件依赖。如果包提示缺少编译后的 JavaScript 输出，说明发布者漏了编译产物，暂时禁用等发布者修正。

插件路径报 "suspicious ownership" 怎么修？

说明插件文件的所有者不是运行 OpenClaw 的 Unix 用户。保留插件配置先不动，用 sudo chown -R 改回正确 uid。Docker 场景下官方镜像 uid 是 1000，主人为 1000:1000；root 运行则改为 root:root。改完跑 openclaw doctor --fix 刷新注册表。