列出已安装的插件

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

列表

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --json

如果启动记录 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 中。当警告可以列出每个发现的插件时，它会打印一个已包含这些 ID 的可粘贴的 plugins.allow 片段。如果加载的插件没有 install/load-path 来源，请检查该插件 ID，然后将可信 ID 固定在 plugins.allow 中，或者从可信来源重新安装插件，以便 OpenClaw 记录安装来源。

对于打包在 Docker 镜像内的捆绑插件工作，请将插件源码目录通过 bind-mount 挂载到匹配的打包源码路径上，例如 /app/extensions/synology-chat。OpenClaw 会在 /app/dist/extensions/synology-chat 之前发现该挂载的源码覆盖层；直接复制的源码目录仍然不会生效，因此正常的打包安装仍会使用编译后的 dist。

用于运行时 hook 调试：

• openclaw plugins inspect <id> --runtime --json 显示来自模块加载检查通道的已注册挂钩和诊断。运行时检查使用未缓存、非激活的注册表，并在打印结果之前发布其检查声明。它等待该版本的处置，并且失败会阻止成功的结果。如果 SDK 主机仍然从检查中借用提供者回调，则该主机将保留其支持资源并在拆卸期间报告任何后续处理失败；参见保留的SDK合约。这不会停止正在运行的网关或调用上下文引擎工厂。运行时检查永远不会安装依赖项；使用 openclaw doctor --fix 清理遗留依赖状态或恢复 config 引用的丢失的可下载插件。
• openclaw gateway status --deep --require-rpc 确认可访问的网关 URL/profile、service/process 提示、配置路径和 RPC 运行状况。
• 如果某个仅包含 hook 的插件未出现在运行时检查中，请确认其hook 启动意图：要么清单中的 activation.onCapabilities: ["hook"] 配合显式启用插件，要么使用会发出启动信号的 plugins.entries.<id>.hooks 策略，例如 allowConversationAccess: true。全局禁用、拒绝规则和限制性 allowlist 仍然优先。
• 非捆绑的会话 hook（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 将旧配置记录导入索引并在正常运行时使用之前删除已停用的密钥。