列出已安装插件

本页介绍 openclaw plugins list、其选项和发现诊断，以及支撑它的机器管理插件索引。

列表¶

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json

--enabled 布尔值 (路径)

仅显示已启用的插件。

--verbose 布尔值 (路径)

从表格视图切换到按插件的详细行，包含格式/来源/出处/版本/激活元数据。

--json 布尔值 (路径)

机器可读清单，外加注册表诊断和包依赖安装状态。

如果启动日志记录 plugins.allow is empty; discovered non-bundled plugins may auto-load: ...，请运行 openclaw plugins list --enabled --verbose 或使用列出的插件 id 运行 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 宿主仍从检查中借用提供者回调，则该宿主会保留其底层资源，并在拆除期间报告任何后续处置失败；参见保留的 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 是一个已弃用的 authored-config 配置面。运行时和更新命令仅读取 SQLite 机器状态插件索引。在正常运行时使用之前，请运行 openclaw doctor --fix，将旧配置记录导入索引并移除已弃用的键。