列出已安装插件
本页介绍 openclaw plugins list、其选项与发现诊断,以及为其提供支撑的机器管理的插件索引。
列表¶
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
--enabledboolean (path)- 仅显示已启用的插件。
--verboseboolean (path)- 从表格视图切换为逐插件的详细信息行,包含格式/来源/出处/版本/激活元数据。
--jsonboolean (path)- 机器可读的清单,外加注册表诊断信息和包依赖安装状态。
Note
plugins list 首先读取持久化的本地插件注册表;当注册表缺失或无效时,则使用仅由清单派生的回退数据。它适用于检查插件是否已安装、已启用,以及是否对冷启动规划可见,但它并非对已运行的 Gateway 进程的实时运行时检查。编辑插件代码后,在期望新的 register(api) 代码或钩子运行之前,请对服务于该频道的 Gateway 运行 plugins reload <id>。默认的混合重载模式同样会应用插件配置和发现路径的更改;当被动重载被禁用时,管理用的 plugins.refresh RPC 会显式刷新清单。
plugins list --json 包含每个插件在 package.json 的 dependencies 和 optionalDependencies 中的 dependencyStatus。OpenClaw 会检查这些包名是否存在于插件正常的 Node node_modules 查找路径中;它不会导入插件运行时代码、运行包管理器或修复缺失的依赖。
如果启动日志记录 plugins.allow is empty; discovered non-bundled plugins may auto-load: ...,请使用列出的插件 id 运行 openclaw plugins list --enabled --verbose 或 openclaw plugins inspect <id>,以确认插件 id,并将受信任的 id 复制到 openclaw.json 的 plugins.allow 中。当警告能够列出所有已发现的插件时,它会打印一段现成可粘贴的 plugins.allow 片段,其中已包含这些 id。如果某个插件在缺少安装/加载路径来源信息的情况下加载,请检查该插件 id,然后在 plugins.allow 中固定受信任的 id,或从受信任的来源重新安装该插件,以便 OpenClaw 记录安装来源信息。
对于打包 Docker 镜像内的捆绑插件开发,请将插件源代码目录绑定挂载到对应的打包源码路径上,例如 /app/extensions/synology-chat。OpenClaw 会优先于 /app/dist/extensions/synology-chat 发现该挂载的源码覆盖层;仅复制过来的源码目录不会生效,因此常规打包安装仍使用编译后的 dist。
运行时钩子调试:
openclaw plugins inspect <id> --runtime --json通过一次模块加载检查过程显示已注册的钩子和诊断信息。运行时检查使用未缓存、非激活的注册表,并在打印结果之前释放其检查声明。它会等待与该释放相对应的销毁操作完成;若销毁失败,则无法返回成功结果。如果某个 SDK 宿主仍从检查中借用 provider 回调,该宿主持有这些回调的底层资源,并在拆除阶段报告任何后续销毁失败;参见 保留的 SDK 契约。此操作不会停止正在运行的 Gateway,也不会调用上下文引擎工厂。运行时检查从不安装依赖;请使用openclaw doctor --fix清理遗留依赖状态,或恢复配置引用但缺失的可下载插件。openclaw gateway status --deep --require-rpc确认可访问的 Gateway URL/配置文件、服务/进程提示、配置路径和 RPC 健康状态。- 如果仅含钩子的插件在运行时检查中缺失,请确认其 钩子启动意图:要么在清单中声明
activation.onCapabilities: ["hook"]并显式启用插件,要么采用启动信号式的plugins.entries.<id>.hooks策略(例如allowConversationAccess: true)。全局禁用、拒绝以及限制性允许列表仍然具有优先权。 - 非捆绑的对话钩子(
before_model_resolve、agent_turn_prepare、before_prompt_build、before_agent_reply、llm_input、llm_output、before_agent_run、before_agent_finalize、agent_end)要求plugins.entries.<id>.hooks.allowConversationAccess=true。 session_end元数据本身不需要对话访问权限。但其有界读取器ctx.endedTranscript需要该权限;当权限未被授予时,会报告conversation-access-required。
插件索引¶
插件安装元数据是机器管理的状态,而非用户配置。安装和更新会将其写入当前生效的 OpenClaw 状态目录下的共享 SQLite 状态数据库。以 plugins.installedIndex 为键的 config_machine_state 值存储持久的 installRecords 元数据,包括损坏或缺失插件清单的记录,以及由清单派生的冷注册表缓存,供 openclaw plugins update、卸载、诊断和冷插件注册表使用。
无法读取的索引并不等同于无效数据。权限、锁及其他读取错误会以原始错误中止回退、迁移和刷新。请恢复数据库访问,然后在尝试修复之前重新运行 openclaw plugins registry 检查状态。除非检查成功并确认存在无效的安装记录,否则不要删除 plugins.installedIndex 行;仅凭读取失败不足以构成删除的理由。
当通过状态模式 13 升级旧版插件索引时,格式错误的 JSON 或意外的 JSON 结构不再使安装台账被丢弃。迁移会将完整的原始行保留在 diagnostic_events 中 plugins.installedIndex.quarantine 之下,记录一条警告,然后继续。即使派生的注册表元数据已损坏,有效的安装记录仍然可用。运行 openclaw doctor --fix 或 openclaw plugins registry --refresh 以重建该元数据。无效的安装记录仍会被标记为无效,需要从保留的行或经过验证的备份中恢复;它们绝不会被视为空安装。恢复记录在重新打开和常规诊断保留后依然保留。如果保留失败,迁移将回滚,并保持旧版行完好无损。
plugins.installs 是一个已弃用的作者配置表面。运行时和更新命令仅读取 SQLite 机器状态插件索引。运行 openclaw doctor --fix 以将旧版配置记录导入索引,并在正常运行时使用之前移除已弃用的键。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw