CLI 命令
插件
管理 Gateway 网关插件、钩子包和兼容包。
命令
openclaw plugins list [--enabled] [--verbose] [--json]openclaw plugins search <query> [--limit <n>] [--json]openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--marketplace <source>]openclaw plugins inspect <id> [--runtime] [--json]openclaw plugins inspect --all [--runtime] [--json]openclaw plugins info <id> # alias for inspectopenclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins uninstall <id> [--dry-run] [--keep-files] [--force]openclaw plugins update <id-or-npm-spec> | --all [--dry-run]openclaw plugins registry [--refresh] [--json]openclaw plugins doctoropenclaw plugins init <id> [--name <name>] [--type tool|provider] [--directory <path>]openclaw plugins build [--entry <path>] [--check]openclaw plugins validate [--entry <path>]openclaw plugins marketplace entries [--offline] [--feed-profile <name>] [--json]openclaw plugins marketplace list <source> [--json]openclaw plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]调查缓慢的安装、检查、卸载或注册表刷新操作时，请使用
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 运行命令。跟踪信息会将各阶段耗时
写入标准错误，同时保持 JSON 输出可解析。请参阅调试。
编写插件
openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm run plugin:buildnpm run plugin:validate默认情况下，plugins init 会创建一个最小化的 TypeScript 工具插件。第一个
参数是插件 ID；--name 用于设置显示名称。OpenClaw 使用该
ID 确定默认输出目录和包名。工具脚手架使用
defineToolPlugin，并在 package.json 中生成 plugin:build 和
plugin:validate 脚本；这些脚本会先执行构建，然后调用 openclaw plugins build/validate。
plugins build 会导入构建后的入口，读取其静态工具元数据，写入
openclaw.plugin.json，并使 package.json 中的 openclaw.extensions 保持同步。
plugins validate 会检查生成的清单、包元数据和
当前入口导出是否仍然一致。完整的编写工作流请参阅工具插件。
脚手架会写入 TypeScript 源代码，但从构建后的
./dist/index.js 入口生成元数据，因此该工作流也适用于已发布的 CLI。当入口不是默认包入口时，请使用
--entry <path>。在 CI 中使用
plugins build --check，可在生成的元数据过期时让检查失败，而不会
重写文件。
提供商脚手架
openclaw plugins init acme-models --name "Acme Models" --type providercd acme-modelsnpm installnpm run buildnpm testnpm run validate提供商脚手架会创建一个通用的 OpenAI 兼容模型提供商插件，
其中包含 API 密钥身份验证流程、运行
clawhub package validate 的 npm run validate 脚本、ClawHub 包元数据，以及一个
可手动触发的 GitHub Actions 工作流，用于将来通过 GitHub
OIDC 进行可信发布。提供商脚手架不会生成 Skills，也不使用
openclaw plugins build/validate；这些命令用于工具
脚手架的元数据生成路径。
发布前，请将占位 API 基础 URL、模型目录、文档 路由、凭据文本和 README 内容替换为真实的提供商详细信息。首次发布到 ClawHub 和设置可信发布者时，请使用 生成的 README。
安装
openclaw plugins search "calendar" # search ClawHub pluginsopenclaw plugins install <package> # source auto-detectionopenclaw plugins install clawhub:<package> # ClawHub onlyopenclaw plugins install npm:<package> # npm onlyopenclaw plugins install npm-pack:<path.tgz> # local npm-pack tarballopenclaw plugins install git:github.com/<owner>/<repo> # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path> # local path or archiveopenclaw plugins install -l <path> # link instead of copyopenclaw plugins install <plugin>@<marketplace> # marketplace shorthandopenclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)openclaw plugins install <package> --force # overwrite existing installopenclaw plugins install <package> --pin # pin resolved npm versionopenclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-install维护者测试设置阶段的安装时，可以使用受保护的环境变量覆盖自动插件安装 来源。请参阅 插件安装覆盖项。
plugins search 会查询 ClawHub 中可安装的 code-plugin 和
bundle-plugin 包（不包括 Skills；搜索 Skills 请使用 openclaw skills search）。
默认 --limit 为 20，上限为 100。它只读取远程目录：不会
检查本地状态、修改配置、安装包或加载插件运行时。
结果包括 ClawHub 包名、系列、频道、版本、
摘要，以及类似 openclaw plugins install clawhub:<package> 的安装提示。
配置包含项和无效配置修复
如果你的 plugins 部分由单文件 $include 提供，plugins install/update/enable/disable/uninstall 会将更改写入该包含文件，并保持 openclaw.json 不变。对于根包含项、包含数组以及带有同级覆盖项的包含项，操作会采用安全失败，而不是将其扁平化。受支持的形式请参阅配置包含项。
如果安装期间配置无效，plugins install 通常会采用安全失败，并提示你先运行 openclaw doctor --fix。在 Gateway 网关启动和热重载期间，无效的插件配置会像其他无效配置一样采用安全失败；openclaw doctor --fix 可以隔离无效的插件条目。唯一有文档说明的安装阶段例外，是一个范围严格受限的内置插件恢复路径，仅适用于明确选择启用 openclaw.install.allowInvalidConfigRecovery 的插件。
--force、重新安装与更新
--force 会复用现有安装目标，并原地覆盖已安装的插件或钩子包。当你有意从新的本地路径、归档、ClawHub 包或 npm 制品重新安装同一 ID 时，请使用此选项。对于已跟踪的 npm 插件的常规升级，请优先使用 openclaw plugins update <id-or-npm-spec>。
如果你对已安装的插件 ID 运行 plugins install，OpenClaw 会停止操作，并提示你使用 plugins update <id-or-npm-spec> 执行常规升级；如果你确实要从其他来源覆盖当前安装，则提示使用 plugins install <package> --force。--force 不支持与 --link 一起使用。
--pin 的适用范围
--pin 仅适用于 npm 安装，并记录解析后的确切 <name>@<version>。它不支持 git: 安装（应改为在规格中固定引用，例如 git:github.com/acme/plugin@v1.2.3），也不支持 --marketplace（市场安装会持久保存市场来源元数据，而不是 npm 规格）。
--dangerously-force-unsafe-install
--dangerously-force-unsafe-install 已弃用，现在不执行任何操作。OpenClaw 不再对插件安装执行内置的安装阶段危险代码阻止检查。
当需要特定于主机的安装策略时，请使用由操作员管理的 security.installPolicy 界面。插件的 before_install 钩子是插件运行时生命周期钩子，而不是 CLI 安装的主要策略边界。
如果你发布到 ClawHub 的插件因注册表扫描而被隐藏或阻止，请按照 ClawHub 发布中的发布者步骤操作。--dangerously-force-unsafe-install 不会要求 ClawHub 重新扫描插件，也不会将被阻止的版本公开。
--acknowledge-clawhub-risk
下载前，社区 ClawHub 安装会检查所选版本的信任记录。如果 ClawHub 禁止下载该版本、报告恶意扫描发现，或将该版本置于阻止性审核状态（已隔离、已撤销），无论是否使用此标志，OpenClaw 都会直接拒绝安装。对于不会阻止安装的风险扫描状态或审核状态，OpenClaw 会显示信任详细信息，并在继续前请求确认。
仅当你查看了 ClawHub 警告并决定在没有交互式提示的情况下继续时，才应使用 --acknowledge-clawhub-risk。待处理或过期（尚未确认干净）的扫描结果会触发警告，但不要求确认风险。官方 ClawHub 包和内置 OpenClaw 插件来源会完全跳过此版本信任检查。
钩子包和 npm 规格
plugins install 也是安装在 package.json 中公开 openclaw.hooks 的钩子包的入口。请使用 openclaw hooks 查看经过筛选的钩子并逐个启用钩子，而不是安装包。
Npm 规范仅限注册表（包名加可选的精确版本或 dist-tag）。Git/URL/文件规范和 semver 范围会被拒绝。为确保安全，依赖安装会针对每个插件在一个托管的 npm 项目中使用 --ignore-scripts 执行，即使你的 shell 配置了全局 npm 安装设置也是如此。托管插件的 npm 项目会继承 OpenClaw 包级别的 npm overrides，因此宿主的安全版本锁定也适用于提升安装的插件依赖。
使用 npm:<package> 明确指定通过 npm 解析。裸包规范在发布切换期间也会直接从 npm 安装，除非它与官方插件 ID 匹配。
与内置插件匹配的原始 @openclaw/* 规范会先解析到镜像自带的内置副本，然后才回退到 npm。例如，openclaw plugins install @openclaw/discord@2026.5.20 --pin 会使用当前 OpenClaw 构建中的内置 Discord 插件，而不会创建托管的 npm 覆盖。若要强制使用外部 npm 包，请使用 openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin。
裸规范和 @latest 会保持在稳定版本轨道。OpenClaw 的日期标记修正版（如 2026.5.3-1）在此检查中也视为稳定版本。如果 npm 将其中任一形式解析为预发布版本，OpenClaw 会停止，并要求你使用预发布标签（@beta/@rc）或精确的预发布版本（@1.2.3-beta.4）明确选择加入。
对于未指定精确版本的 npm 安装（npm:<package> 或 npm:<package>@latest），OpenClaw 会在安装前检查解析出的包元数据。如果最新稳定包要求更新的 OpenClaw 插件 API 或更高的最低宿主版本，OpenClaw 会检查较旧的稳定版本，并改为安装最新的兼容版本。精确版本和显式 dist-tag 仍采用严格模式：不兼容的选择会失败，并要求你升级 OpenClaw 或选择兼容版本。
如果裸安装规范与官方插件 ID 匹配（例如 diffs），OpenClaw 会直接安装目录中的条目。若要安装同名 npm 包，请使用显式的作用域规范（例如 @scope/diffs）。
Git 仓库
使用 git:<repo> 直接从 Git 仓库安装。支持的形式包括：git:github.com/owner/repo、git:owner/repo、完整的 https://、ssh://、git://、file://，以及 git@host:owner/repo.git 克隆 URL。添加 @<ref> 或 #<ref>，即可在安装前检出分支、标签或提交。
Git 安装会将仓库克隆到临时目录，在提供所请求的引用时将其检出，然后使用常规的插件目录安装程序，因此清单验证、操作员安装策略、包管理器安装工作和安装记录的行为与 npm 安装一致。记录的 Git 安装会包含源 URL/引用以及解析出的提交，以便 openclaw plugins update 之后可以重新解析该来源。
从 Git 安装后，使用 openclaw plugins inspect <id> --runtime --json 验证 Gateway 网关方法和 CLI 命令等运行时注册。如果插件使用 api.registerCli 注册了 CLI 根命令，请直接通过 OpenClaw 根 CLI 运行该命令，例如 openclaw demo-plugin ping。
归档文件
支持的归档格式：.zip、.tgz、.tar.gz、.tar。原生 OpenClaw 插件归档必须在解压后的插件根目录中包含有效的 openclaw.plugin.json；仅包含 package.json 的归档会在 OpenClaw 写入安装记录前被拒绝。
当文件是 npm-pack tarball，并且你希望使用与注册表安装相同的按插件托管 npm 项目路径时，请使用 npm-pack:<path.tgz>，其中包括 package-lock.json 验证、提升依赖扫描和 npm 安装记录。普通归档路径仍会作为本地归档安装到插件扩展根目录下。
也支持从 Claude 市场安装。
ClawHub 安装使用显式的 clawhub:<package> 定位符：
openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:openclaw-codex-app-server@1.2.3在发布切换期间，符合 npm 安全命名规则的裸插件规范默认从 npm 安装，除非它与官方插件 ID 匹配：
openclaw plugins install openclaw-codex-app-server使用 npm: 明确指定仅通过 npm 解析：
openclaw plugins install npm:openclaw-codex-app-serveropenclaw plugins install npm:@openclaw/discord@2026.5.20openclaw plugins install npm:@scope/plugin-name@1.0.1OpenClaw 会在安装前检查声明的插件 API / 最低 Gateway 网关兼容性。当选定的 ClawHub 版本发布了 ClawPack 制品时，OpenClaw 会下载带版本号的 npm-pack .tgz，验证 ClawHub 摘要标头和制品摘要，然后通过常规归档路径进行安装。没有 ClawPack 元数据的旧版 ClawHub 版本仍会通过旧版包归档验证路径安装。记录的安装会保留其 ClawHub 来源元数据、制品类型、npm 完整性值、npm shasum、tarball 名称和 ClawPack 摘要信息，以供后续更新使用。
未指定版本的 ClawHub 安装会保留未指定版本的已记录规范，以便 openclaw plugins update 可以跟随更新的 ClawHub 版本；显式版本或标签选择器（如 clawhub:pkg@1.2.3 和 clawhub:pkg@beta）仍会固定到该选择器。
市场简写
当市场名称存在于 Claude 的本地注册表缓存 ~/.claude/plugins/known_marketplaces.json 中时，可使用 plugin@marketplace 简写：
openclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>使用 --marketplace 显式传递市场来源：
openclaw plugins install <plugin-name> --marketplace <marketplace-name>openclaw plugins install <plugin-name> --marketplace <owner/repo>openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <plugin-name> --marketplace ./my-marketplace市场来源
~/.claude/plugins/known_marketplaces.json中的 Claude 已知市场名称- 本地市场根目录或
marketplace.json路径 - GitHub 仓库简写，例如
owner/repo - GitHub 仓库 URL，例如
https://github.com/owner/repo - Git URL
远程市场规则
对于从 GitHub 或 Git 加载的远程市场，插件条目必须位于克隆的市场仓库内。OpenClaw 接受该仓库中的相对路径来源，并拒绝远程清单中的 HTTP(S)、绝对路径、Git、GitHub 和其他非路径插件来源。
对于本地路径和归档，OpenClaw 会自动检测：
- 原生 OpenClaw 插件（
openclaw.plugin.json） - Codex 兼容包（
.codex-plugin/plugin.json） - Claude 兼容包（
.claude-plugin/plugin.json；如果没有该清单文件，则使用默认的 Claude 组件布局） - Cursor 兼容包（
.cursor-plugin/plugin.json）
托管的本地安装必须是插件目录或归档。独立的 .js、.mjs、.cjs 和 .ts 插件文件不会由 plugins install 复制到托管插件根目录中，也不会因为直接放入 ~/.openclaw/extensions 或 <workspace>/.openclaw/extensions 而被加载；这些自动发现根目录会加载插件包或插件包目录，并将顶层脚本文件作为本地辅助文件跳过。请改为在 plugins.load.paths 中显式列出独立文件。
使用 -l/--link 指向本地插件目录而不复制该目录（将其添加到 plugins.load.paths）：
openclaw plugins install -l ./my-plugin--link 不支持与 --force（链接插件直接指向源路径，因此没有可在原位置覆盖的内容）、--marketplace 或 git: 安装一起使用，并且要求本地路径已存在。
列表
openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --json--enabledboolean仅显示已启用的插件。
--verboseboolean从表格视图切换为每个插件一行的详细信息，其中包含格式/来源/起源/版本/激活元数据。
--jsonboolean机器可读的插件清单，以及注册表诊断和包依赖安装状态。
如果启动日志显示 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显示通过模块加载检查流程注册的钩子和诊断信息。运行时检查绝不会安装依赖项；请使用openclaw doctor --fix清理旧版依赖状态，或恢复配置中引用但缺失的可下载插件。openclaw gateway status --deep --require-rpc确认可访问的 Gateway 网关 URL/配置文件、服务/进程提示、配置路径和 RPC 健康状态。- 非内置的对话钩子（
llm_input、llm_output、before_model_resolve、before_agent_reply、before_agent_run、before_agent_finalize、agent_end）需要设置plugins.entries.<id>.hooks.allowConversationAccess=true。
插件索引
插件安装元数据是由系统管理的状态，而不是用户配置。安装和更新操作会将其写入当前 OpenClaw 状态目录下的共享 SQLite 状态数据库。installed_plugin_index 行存储持久的 installRecords 元数据，其中包括清单损坏或缺失的插件记录，以及由清单派生的冷注册表缓存，供 openclaw plugins update、卸载、诊断和冷插件注册表使用。
当 OpenClaw 在配置中发现已发布的旧版 plugins.installs 记录时，运行时读取会将其视为兼容性输入，但不会重写 openclaw.json。显式插件写入操作和 openclaw doctor --fix 会将这些记录移入插件索引，并在允许写入配置时移除该配置键；如果任一写入失败，则会保留配置记录，以免丢失安装元数据。
卸载
openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-filesopenclaw plugins uninstall <id> --forceuninstall 会从 plugins.entries、持久化插件索引、插件允许/拒绝列表条目以及适用的关联 plugins.load.paths 条目中移除插件记录。除非设置了 --keep-files，否则卸载还会移除被跟踪的托管安装目录，但仅限于该目录解析后位于 OpenClaw 的插件扩展根目录内。如果插件当前占用 memory 或 contextEngine 槽位，该槽位会重置为默认值（记忆使用 memory-core，上下文引擎使用 legacy）。
uninstall 会先输出将被移除内容的预览，然后在进行更改前提示 Uninstall plugin "<id>"?。传入 --force 可跳过确认提示（适用于脚本和非交互式运行）；如果未传入此参数，卸载需要交互式 TTY。--dry-run 会输出相同的预览，然后退出，不显示提示，也不进行任何更改。
更新
openclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins update <id-or-npm-spec> --dry-runopenclaw plugins update @openclaw/voice-callopenclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install更新适用于托管插件索引中被跟踪的插件安装，以及 hooks.internal.installs 中被跟踪的钩子包安装。
解析插件 ID 与 npm 规范
传入插件 ID 时，OpenClaw 会复用该插件记录的安装规范。这意味着先前存储的 @beta 等 dist-tag 和精确固定版本会继续用于后续的 update <id> 运行。
在执行 update <id> --dry-run 时，使用精确版本固定的 npm 安装会保持固定。如果 OpenClaw 还能解析该软件包的注册表默认发布线，并且该默认发布线比已安装的固定版本更新，试运行会报告固定版本，并输出显式的 @latest 软件包更新命令，以便切换到注册表默认发布线。
此定向更新规则不同于批量维护路径 openclaw plugins update --all。批量更新仍会遵循常规的已跟踪安装规范，但受信任的 OpenClaw 官方插件记录可以同步到当前官方目录目标，而不是停留在过时的官方软件包精确版本上。如果你有意保持某个精确或带标签的官方规范不变，请使用定向的 update <id>。
对于 npm 安装，你也可以传入带有 dist-tag 或精确版本的显式 npm 软件包规范。OpenClaw 会将该软件包名称解析回被跟踪的插件记录，更新已安装的插件，并记录新的 npm 规范，供以后基于 ID 的更新使用。
传入不带版本或标签的 npm 软件包名称，也会解析回被跟踪的插件记录。当插件被固定到精确版本，而你希望将其移回注册表默认发布线时，请使用此方式。
Beta 渠道更新
除非传入新规范，否则定向的 openclaw plugins update <id-or-npm-spec> 会复用被跟踪的插件规范。批量的 openclaw plugins update --all 在将受信任的官方插件记录同步到官方目录目标时，会使用配置的 update.channel，因此 Beta 渠道安装可以留在 Beta 发布线上，而不会被静默归一化到稳定版/最新版。
openclaw update 也能识别当前 OpenClaw 更新渠道：在 Beta 渠道上，使用默认发布线的 npm 和 ClawHub 插件记录会先尝试 @beta。如果不存在插件 Beta 版本，它们会回退到记录的默认/最新规范；如果 npm 插件存在 Beta 软件包但未通过安装验证，也会回退。此回退会作为警告报告，但不会导致核心更新失败。对于定向更新，精确版本和显式标签会继续固定到对应的选择器。
版本检查和完整性漂移
在实际执行 npm 更新之前，OpenClaw 会根据 npm 注册表元数据检查已安装的软件包版本。如果已安装版本和记录的制品标识均已与解析出的目标匹配，则会跳过更新，不进行下载、重新安装或重写 openclaw.json。
如果存在已存储的完整性哈希，而获取到的制品哈希发生变化，OpenClaw 会将其视为 npm 制品漂移。交互式 openclaw plugins update 命令会输出预期哈希和实际哈希，并在继续前请求确认。除非调用方提供显式的继续策略，否则非交互式更新辅助程序会以失败关闭方式处理。
更新时使用 --dangerously-force-unsafe-install
为保持兼容性，plugins update 仍接受 --dangerously-force-unsafe-install，但该参数已弃用，并且不再改变插件更新行为。操作员的 security.installPolicy 仍可阻止更新；插件的 before_install 钩子仅适用于已加载插件钩子的进程。
更新时使用 --acknowledge-clawhub-risk
在下载替换软件包之前，由社区 ClawHub 支持的插件更新会执行与安装相同的精确版本信任检查。对于已经过审核的自动化，如果在所选 ClawHub 版本存在高风险信任警告时仍应继续，请使用 --acknowledge-clawhub-risk。ClawHub 官方软件包和内置 OpenClaw 插件源会绕过此版本信任提示。
检查
openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --all默认情况下，检查功能无需导入插件运行时，即可显示标识、加载状态、来源、清单能力、策略标志、诊断信息、安装元数据、内置包能力，以及检测到的任何 MCP 或 LSP 服务器支持。JSON 输出包含插件清单契约，例如 contracts.agentToolResultMiddleware 和 contracts.trustedToolPolicies，以便操作员在启用或重启插件之前审核受信任界面声明。添加 --runtime 可加载插件模块，并包含已注册的钩子、工具、命令、服务、Gateway 网关方法和 HTTP 路由。运行时检查会直接报告缺失的插件依赖项；安装和修复仍由 openclaw plugins install、openclaw plugins update 和 openclaw doctor --fix 负责。
插件自有的 CLI 命令通常作为根级 openclaw 命令组安装，但插件也可以在 openclaw nodes 等核心父命令下注册嵌套命令。当 inspect --runtime 在 cliCommands 下显示某个命令后，请在列出的路径运行该命令；例如，可以使用 openclaw demo-git ping 验证注册了 demo-git 的插件。
每个插件都会根据其在运行时实际注册的内容进行分类：
| 形态 | 含义 |
|---|---|
plain-capability |
恰好一种能力类型（例如仅提供商插件） |
hybrid-capability |
多于一种能力类型（例如文本 + 语音 + 图像） |
hook-only |
仅包含钩子，不包含能力、工具、命令、服务或路由 |
non-capability |
包含工具/命令/服务，但不包含能力 |
有关能力模型的更多信息，请参阅插件形态。
Doctor
openclaw plugins doctordoctor 会报告插件加载错误、清单/设备发现诊断、兼容性通知，以及插件槽位缺失等过时的插件配置引用。当安装树和插件配置均无问题时，它会输出 No plugin issues detected.。如果仍存在过时配置，但安装树在其他方面健康，摘要会明确说明这一点，而不会暗示插件整体完全健康。
如果已配置的插件存在于磁盘上，但被加载器的路径安全检查阻止，配置验证会保留该插件条目，并将其报告为 present but blocked。请修复此前报告的插件阻止诊断问题，例如路径所有权或所有用户可写权限，而不是移除 plugins.entries.<id> 或 plugins.allow 配置。
对于缺少 register/activate 导出等模块形态故障，请设置 OPENCLAW_PLUGIN_LOAD_DEBUG=1 后重新运行，以在诊断输出中包含简洁的导出形态摘要。
注册表
openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --json本地插件注册表是 OpenClaw 持久化的冷读取模型，用于保存已安装插件的标识、启用状态、来源元数据和贡献所有权。常规启动、提供商所有者查找、渠道设置分类和插件清单均可读取该注册表，无需导入插件运行时模块。
使用 plugins registry 检查持久化注册表是否存在、是否为当前状态或是否已过时。使用 --refresh 根据持久化插件索引、配置策略和清单/软件包元数据重建注册表。这是一条修复路径，而不是运行时激活路径。
openclaw doctor --fix 还会修复注册表相关的托管 npm 漂移：如果托管插件 npm 项目或旧版扁平托管 npm 根目录下存在孤立或恢复的 @openclaw/* 软件包，并且该软件包遮蔽了内置插件，Doctor 会移除这个过时软件包并重建注册表，以便启动过程依据内置清单进行验证。Doctor 还会将宿主 openclaw 软件包重新链接到声明了 peerDependencies.openclaw 的托管 npm 插件中，使 openclaw/plugin-sdk/* 等软件包本地运行时导入在更新或 npm 修复后能够正常解析。
市场
openclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace entries --feed-profile <name>openclaw plugins marketplace entries --feed-url <url>openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile <name>openclaw plugins marketplace refresh --feed-url <url>openclaw plugins marketplace refresh --expected-sha256 <sha256> --jsonplugins marketplace entries 列出已配置的 OpenClaw 市场源中的条目。默认情况下，它会尝试使用托管源，并在失败时回退到最近接受的快照或内置数据。使用 --feed-profile <name> 读取已配置的特定配置文件，使用 --feed-url <url> 读取显式指定的托管源 URL，使用 --offline 在不获取源的情况下读取最近接受的快照。
plugins marketplace refresh 刷新已配置的托管源快照，并报告 OpenClaw 接受的是托管数据、托管快照还是内置回退数据。当调用方要求仅在新获取的托管载荷与固定校验和匹配时命令才能成功，请使用 --expected-sha256。
市场 list 接受本地市场路径、marketplace.json 路径、类似 owner/repo 的 GitHub 简写、GitHub 仓库 URL 或 git URL。--json 会输出解析后的源标签，以及解析出的市场清单和插件条目。
市场刷新会加载托管的 OpenClaw 市场源，并将经过验证的响应持久化为本地托管源快照。不带选项时，它使用已配置的默认源配置文件。使用 --feed-profile <name> 刷新已配置的特定配置文件，使用 --feed-url <url> 刷新显式指定的托管源 URL，使用 --expected-sha256 <sha256> 要求载荷校验和匹配（sha256:<hex> 或不带前缀的 64 字符十六进制摘要），使用 --json 获取机器可读输出。显式指定的托管源 URL 不得包含凭据、查询字符串或片段。未固定校验和的刷新可以报告托管快照或内置回退结果，而不会导致命令失败。固定校验和的刷新必须接受新获取的托管载荷才能成功；成功获取托管数据后，如果 OpenClaw 无法持久化经过验证的快照，刷新也会失败。
