CLI — openclaw plugins

概述

openclaw plugins 管理 Gateway 插件、hook pack 和兼容 bundle。

openclaw plugins list [--enabled] [--verbose] [--json]
openclaw plugins search <query> [--limit N] [--json]
openclaw plugins install <path-or-spec> [options]
openclaw plugins inspect <id> [--runtime] [--json]
openclaw plugins inspect --all
openclaw plugins info <id>           # inspect 的别名
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id> [--dry-run] [--keep-files]
openclaw plugins update <id-or-npm-spec> [--all] [--dry-run]
openclaw plugins registry [--refresh] [--json]
openclaw plugins marketplace list <source> [--json]
openclaw plugins doctor

Nix 模式（OPENCLAW_NIX_MODE=1）下，所有生命周期变更命令（install/update/uninstall/enable/disable）均被禁用，需通过 Nix source 管理。

install

安装来源格式

格式	说明
`<package>`	默认从 npm 安装
`clawhub:<package>`	仅从 ClawHub 安装
`npm:<package>`	显式指定 npm
`npm-pack:<path.tgz>`	本地 npm pack 包（走 npm install 语义）
`git:github.com/<owner>/<repo>[@ref]`	git 仓库
`<local-path>`	本地目录或归档文件
`<plugin>@<marketplace>`	marketplace 简写

openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
openclaw plugins install npm:@scope/plugin-name@1.0.1
openclaw plugins install git:github.com/acme/plugin@v1.2.3
openclaw plugins install ./my-plugin          # 本地目录
openclaw plugins install ./my-plugin -l       # 链接模式（不复制，加入 load.paths）
openclaw plugins install <package> --force    # 覆盖已有安装
openclaw plugins install <package> --pin      # 固定版本（仅 npm）

安装选项

选项	说明
`--force`	覆盖已有安装（用于从新来源重装同一 id）
`--pin`	固定 npm 版本（不支持 git 和 marketplace）
`--dangerously-force-unsafe-install`	忽略内置危险代码扫描的误报（不绕过 hook 策略和扫描失败）
`-l, --link`	链接模式，不复制目录（不支持 `--force`）
`--marketplace <name\|url>`	显式指定 marketplace 来源

安装流程说明

已安装的插件再次 install 会提示用 plugins update；确实要覆盖用 --force
ClawHub 安装会验证 digest 和 artifact 完整性
npm spec 只支持注册表格式（包名 + 精确版本或 dist-tag），不支持 git/URL/文件 spec 和 semver 范围
依赖安装使用 --ignore-scripts 保证安全
本地路径和归档自动检测格式：openclaw.plugin.json（原生插件）、.codex-plugin/、.claude-plugin/、.cursor-plugin/

Marketplace

openclaw plugins marketplace list <source>
openclaw plugins install <plugin>@<marketplace-name>
openclaw plugins install <plugin> --marketplace owner/repo
openclaw plugins install <plugin> --marketplace https://github.com/owner/repo

Marketplace 来源支持：本地路径、marketplace.json 路径、GitHub shorthand（owner/repo）、GitHub URL、git URL。

list / search

openclaw plugins list                  # 所有插件
openclaw plugins list --enabled        # 仅已启用
openclaw plugins list --verbose        # 详细信息（来源/版本/激活元数据）
openclaw plugins list --json           # 机器可读，含依赖状态
openclaw plugins search "calendar"     # 搜索 ClawHub（不影响本地状态）
openclaw plugins search <query> --limit 20

list 读取本地持久化插件注册表，不是运行中 Gateway 的实时探测
修改插件代码、启用状态、hook 策略或 plugins.load.paths 后需重启 Gateway
--json 包含每个插件的 dependencyStatus（检查 node_modules 是否存在，不运行包管理器）
search 是远程 ClawHub 目录查询，结果含包名、版本、摘要和安装提示

inspect / info

openclaw plugins inspect <id>           # 身份、来源、manifest 能力、策略、诊断
openclaw plugins inspect <id> --runtime # 加载模块，显示注册的 hook/tool/command/route
openclaw plugins inspect <id> --json
openclaw plugins inspect --all          # 全局表格视图

插件按实际注册行为分类：

形状	说明
`plain-capability`	仅一种能力类型（如纯 provider 插件）
`hybrid-capability`	多种能力类型（如文本+语音+图像）
`hook-only`	仅 hook，无能力或界面
`non-capability`	有工具/命令/服务，但无能力

--runtime 会加载插件模块，可查看注册的 hook、tool、command、service、gateway method、HTTP route
插件注册的 CLI 命令通常作为根命令组，如 openclaw demo-plugin ping
info 是 inspect 的别名

uninstall

openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files

卸载会清除：

plugins.entries 中的配置
持久化插件索引中的记录
plugin allow/deny 列表条目
链接的 plugins.load.paths 条目
管理的安装目录（除非 --keep-files）

活跃 memory 插件卸载后，memory slot 重置为 memory-core。

update

openclaw plugins update <id>
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id> --dry-run
openclaw plugins update <id> --dangerously-force-unsafe-install

传插件 id 时复用已记录的安装 spec（含之前存储的 @beta 或精确版本）
传 npm spec 时解析回已追踪的插件记录并更新
版本未变时跳过下载和重装
存储的 integrity hash 与获取的 artifact hash 不一致时，交互模式会提示确认，非交互模式直接失败

doctor

openclaw plugins doctor

报告插件加载错误、manifest/discovery 诊断、兼容性提示。一切正常时输出 No plugin issues detected.

插件在磁盘上但被路径安全检查阻止时，显示 present but blocked，需修复路径权限问题，不要直接删除配置
模块形状失败（缺少 register/activate 导出）时，加 OPENCLAW_PLUGIN_LOAD_DEBUG=1 查看导出形状摘要

registry

openclaw plugins registry              # 检查注册表状态
openclaw plugins registry --refresh   # 从插件索引重建注册表
openclaw plugins registry --json

本地插件注册表是已安装插件身份、启用状态、来源元数据的持久化冷读模型，供 Gateway 启动时使用，不需要导入插件运行时模块。

--refresh 是修复路径，不是运行时激活路径
openclaw doctor --fix 也会修复注册表相关的 npm drift 问题

调试技巧

场景	方法
安装/卸载/注册表刷新慢	`OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 输出阶段耗时到 stderr
模块加载失败	`OPENCLAW_PLUGIN_LOAD_DEBUG=1` 查看导出形状摘要
查看运行时注册内容	`openclaw plugins inspect <id> --runtime --json`
确认 Gateway 可达	`openclaw gateway status --deep --require-rpc`
非 bundled 对话 hook 不生效	检查 `plugins.entries.<id>.hooks.allowConversationAccess=true`

Wiki AI

目录