CLI
CLI 包：clawhub，二进制文件：clawhub。
使用 npm 或 pnpm 全局安装：
全局标志
--workdir <dir>：工作目录（默认：cwd；如果已配置，则回退到 Clawdbot 工作区）--dir <dir>：workdir 下的安装目录（默认：skills）--site <url>：浏览器登录的基础 URL（默认：https://clawhub.ai）--registry <url>：API 基础 URL（默认：自动发现，否则为https://clawhub.ai）--no-input：禁用提示
CLAWHUB_SITE（旧版CLAWDHUB_SITE）CLAWHUB_REGISTRY（旧版CLAWDHUB_REGISTRY）CLAWHUB_WORKDIR（旧版CLAWDHUB_WORKDIR）
HTTP 代理
对于位于企业代理或受限网络之后的系统，CLI 遵循标准 HTTP 代理环境变量：HTTPS_PROXY/https_proxyHTTP_PROXY/http_proxyNO_PROXY/no_proxy
HTTPS_PROXY 用于 HTTPS 请求，HTTP_PROXY 用于普通 HTTP。NO_PROXY / no_proxy 会被遵循，用于对特定主机或域名绕过代理。
在直接出站连接被阻止的系统上需要这样做（例如 Docker 容器、仅代理联网的 Hetzner VPS、企业防火墙）。
示例：
配置文件
存储你的 API 令牌和缓存的注册表 URL。- macOS：
~/Library/Application Support/clawhub/config.json - Linux/XDG：
$XDG_CONFIG_HOME/clawhub/config.json或~/.config/clawhub/config.json - Windows：
%APPDATA%\\clawhub\\config.json - 旧版回退：如果
clawhub/config.json尚不存在，但clawdhub/config.json存在，CLI 会复用旧版路径 - 覆盖：
CLAWHUB_CONFIG_PATH（旧版CLAWDHUB_CONFIG_PATH）
命令
login / auth login
- 默认：打开浏览器到
<site>/cli/auth，并通过 loopback 回调完成。 - 无头：
clawhub login --token clh_... - 远程/无头交互：
clawhub login --device会打印代码，并在你到<site>/cli/device授权时等待。
whoami
- 通过
/api/v1/whoami验证已存储的令牌。
token
- 将已存储的 API 令牌打印到 stdout。
- 适用于将本地登录令牌通过管道传入 CI secret 设置命令。
star <skill> / unstar <skill>
- 将技能添加到你的高亮列表或从中移除。
- 调用
POST /api/v1/stars/<slug>和DELETE /api/v1/stars/<slug>。 --yes跳过确认。
search <query...>
- 调用
/api/v1/search?q=...。 - 输出包括技能 slug、所有者 handle、显示名称和相关性分数。
- 搜索会先偏好精确的 slug/名称 token 匹配，然后才考虑下载热度。像
map这样的独立 slug token 会比amap内部的子字符串更强地匹配personal-map。 - 热度只是一个较小的排名先验，并不保证排在顶部。
- 如果某个技能应当出现但没有出现，请在登录状态下运行
clawhub inspect @owner/slug，先检查所有者可见的审核诊断，再重命名元数据。
explore
- 通过
/api/v1/skills?limit=...&sort=createdAt列出最新技能（按createdAt降序排序）。 - 标志：
--limit <n>（1-200，默认：25）--sort newest|updated|rating|downloads|trending（默认：newest）。旧版安装排序别名仍可用于兼容。--json（机器可读输出）
- 输出：
<slug> v<version> <age> <summary>（summary 截断为 50 个字符）。
inspect @owner/slug
- 获取技能元数据和版本文件，但不安装。
--version <version>：检查特定版本（默认：latest）。--tag <tag>：检查带标签的版本（例如latest）。--versions：列出版本历史（第一页）。--limit <n>：要列出的最大版本数（1-200）。--files：列出所选版本的文件。--file <path>：获取原始文件内容（仅文本文件；200KB 限制）。--json：机器可读输出。
install @owner/slug
- 解析指定所有者和技能的最新版本。
- 通过
/api/v1/download下载 zip。 - 解压到
<workdir>/<dir>/<slug>。 - 拒绝覆盖已固定的技能；请先运行
clawhub unpin <skill>。 - 写入：
<workdir>/.clawhub/lock.json（旧版.clawdhub）<skill>/.clawhub/origin.json（旧版.clawdhub）
uninstall <skill>
- 移除
<workdir>/<dir>/<slug>并删除 lockfile 条目。 - 登录时发送尽力而为的遥测，以便停用当前安装计数。
- 交互式：请求确认。
- 非交互式（
--no-input）：需要--yes。
list
- 读取
<workdir>/.clawhub/lock.json（旧版.clawdhub）。 - 在通过
clawhub pin冻结的技能旁显示pinned，包括可选原因。
pin <skill>
- 在 lockfile 中将已安装技能标记为已固定。
--reason <text>记录冻结该技能的原因。update --all会跳过已固定技能，直接update <skill>会被拒绝。- 已固定技能也会拒绝
install --force，因此本地字节不会被意外替换。
unpin <skill>
- 从已安装技能移除 lockfile 固定标记，使未来更新可以修改它。
update [@owner/slug] / update --all
- 根据本地文件计算指纹。
- 如果指纹匹配已知版本：不提示。
- 如果指纹不匹配：
- 默认拒绝
- 使用
--force覆盖（或者如果是交互式，则提示）
- 已固定技能永远不会被
--force更新。 update <skill>对已固定技能会快速失败，并提示你先运行clawhub unpin <skill>。update --all会跳过已固定的 slug，并打印哪些内容保持冻结的摘要。
skill publish <path>
- 将本地 bundle 指纹与 ClawHub 比较，如果内容已经发布则成功退出。
- 新技能默认使用
1.0.0；已更改技能默认使用下一个 patch 版本。 --version <version>显式选择一个版本，即使内容匹配现有版本也会发布。--dry-run解析发布但不上传；--json打印机器可读结果。- 当执行者拥有 publisher 访问权限时，
--owner <handle>会在组织/用户发布者 handle 下发布。 --migrate-owner会在发布新版本时将现有技能移动到--owner。需要对两个发布者都拥有 admin/owner 访问权限。- 所有者和审核行为在
docs/publishing.md中说明。 - 发布技能意味着它在 ClawHub 上以
MIT-0发布。 - 已发布技能可免费使用、修改和重新分发，无需署名。
- ClawHub 不支持付费技能或按技能定价。
- 旧版别名：
publish <path>。
GitHub Actions
ClawHub 的可复用skill-publish.yml
工作流会对一个 skill_path 调用 skill publish，或对 root（默认：skills）下每个直接技能文件夹调用。它会跳过未更改的技能，并使用相同的自动 patch 版本行为。
设置 dry_run: true 可在没有令牌的情况下预览。实际发布需要 clawhub_token secret。
sync
- 扫描当前 workdir、已配置的 skills 目录，以及任何
--root <dir>文件夹，查找包含SKILL.md或skill.md的本地技能文件夹。 - 将每个本地技能指纹与 ClawHub 比较，只发布新的或已更改的技能。
- 新技能发布为
1.0.0；已更改技能默认发布下一个 patch 版本。对于应移动更大 semver 步长的更新批次，请使用--bump minor|major。 --dry-run显示发布计划但不上传；--json打印机器可读计划。--all会发布每个新的或已更改的技能，不再提示。没有--all时，交互式终端会让你选择要发布的技能。- 当执行者拥有 publisher 访问权限时，
--owner <handle>会在组织/用户发布者 handle 下发布。 sync仅执行单向发布。它不会安装、更新、下载，也不会报告安装/下载遥测。
scan --slug <slug>
- 需要
clawhub login。 - 通过
POST /api/v1/skills/-/scan运行 ClawHub ClawScan，然后轮询直到扫描进入终止状态。 - 扫描是异步的，可能需要一些时间才能完成。排队期间，终端 spinner 会显示当前优先扫描位置以及前面还有多少个扫描。
- 已发布扫描需要所有权或发布者管理访问权限。moderators/admins 可以通过
clawhub-admin使用同一后端。 --update仅在与--slug一起使用时有效；它会将成功的已发布扫描结果写回所选版本。--output <file.zip>下载完整报告归档，其中包含manifest.json、clawscan.json、skillspector.json、static-analysis.json、virustotal.json和README.md。--json打印完整轮询响应，供自动化使用。- 不再支持本地路径扫描。请上传新版本，然后使用
scan download获取该提交版本的已存储扫描结果。
scan download <name>
- 需要
clawhub login。 - 下载已提交技能或插件版本的已存储扫描报告 ZIP，包括被 ClawHub 安全检查阻止或隐藏的版本。
- 技能下载使用技能 slug，并默认使用
--kind skill。 - 插件下载使用包名，并且需要
--kind plugin。 --version是必需的，以便作者检查 ClawHub 阻止的确切提交版本。--output <file.zip>选择目标路径。
GitHub Actions
ClawHub 在/.github/workflows/skill-publish.yml
提供一个官方可复用工作流，用于技能仓库和目录仓库。
典型目录设置：
root对目录仓库默认是skills。- 传递
skill_path: skills/review-helper可处理一个技能文件夹。 owner映射到 CLI--owner标志；省略它则以已认证用户身份发布。- V1 技能发布使用
clawhub_token；GitHub OIDC 可信发布目前仅适用于包。
delete <skill>
- 不带
--version时，软删除一个技能（所有者、版主或管理员）。 - 调用
DELETE /api/v1/skills/{slug}。 - 由所有者发起的软删除会保留该 slug 30 天；该命令会打印到期时间。
--version <version>会通过故障关闭的版本专用路由，永久删除一个归属自己的非最新版本。 已删除的版本无法恢复或重新发布。删除当前最新版本前，请先发布替代版本。平台工作人员不会在此仅限版本的流程中绕过所有权。--reason <text>会在整个技能的软删除和审计日志中记录一条审核备注。--note <text>是--reason的别名。--yes跳过确认。
undelete <skill>
- 恢复一个已隐藏的技能（所有者、版主或管理员）。
- 没有版本恢复；永久删除的版本无法恢复。
- 调用
POST /api/v1/skills/{slug}/undelete。 --reason <text>会在该技能和审计日志中记录一条审核备注。--note <text>是--reason的别名。--yes跳过确认。
hide <skill>
- 隐藏一个技能（所有者、版主或管理员）。
delete的别名。
unhide <skill>
- 取消隐藏一个技能（所有者、版主或管理员）。
undelete的别名。
skill rename <skill> <new-name>
- 重命名一个归属自己的技能，并将先前的 slug 保留为重定向别名。
- 调用
POST /api/v1/skills/{slug}/rename。 --yes跳过确认。
skill merge <source> <target>
- 将一个归属自己的技能合并到另一个归属自己的技能中。
- 源 slug 停止公开列出，并变为目标的重定向别名。
- 调用
POST /api/v1/skills/{sourceSlug}/merge。 --yes跳过确认。
transfer
- 所有权转移工作流。
- 转移给用户 handle 会创建一个待处理请求，由接收者接受。
- 仅当操作者对当前所有者和目标发布者都拥有管理员访问权限时，转移给组织/发布者 handle 才会立即生效。
- 子命令：
transfer request <skill> <handle> [--message "..."] [--yes]transfer list [--outgoing]transfer accept <skill> [--yes]transfer reject <skill> [--yes]transfer cancel <skill> [--yes]
- 端点：
POST /api/v1/skills/{slug}/transferPOST /api/v1/skills/{slug}/transfer/acceptPOST /api/v1/skills/{slug}/transfer/rejectPOST /api/v1/skills/{slug}/transfer/cancelGET /api/v1/transfers/incomingGET /api/v1/transfers/outgoing
package explore [query...]
- 通过
GET /api/v1/packages和GET /api/v1/packages/search浏览或搜索统一的软件包目录。 - 将此命令用于插件和其他软件包族条目；顶层
search仍然是技能搜索界面。 - 标志：
--family skill|code-plugin|bundle-plugin--official--executes-code--target <target>,--os <os>,--arch <arch>,--libc <libc>--requires-browser,--requires-desktop,--requires-native-deps--requires-external-service,--external-service <name>--binary <name>,--os-permission <name>--artifact-kind legacy-zip|npm-pack--npm-mirror--limit <n>（1-100，默认值：25）--json
package inspect <name>
- 在不安装的情况下获取软件包元数据。
- 将此命令用于插件元数据、兼容性、验证、来源以及版本/文件检查。
--version <version>：检查指定版本（默认值：latest）。--tag <tag>：检查带标签的版本（例如latest）。--versions：列出版本历史（第一页）。--limit <n>：要列出的最大版本数（1-100）。--files：列出所选版本的文件。--file <path>：获取原始文件内容（仅文本文件；限制 200KB）。--json：机器可读输出。
package download <name>
- 通过
GET /api/v1/packages/{name}/versions/{version}/artifact解析软件包版本。 - 从解析器的
downloadUrl下载工件。 - 验证所有工件的 ClawHub SHA-256。
- 对于 ClawPack npm-pack 工件，还会验证 npm
sha512完整性、 npm shasum，以及 tarball 的package.json名称/版本。 - 旧版 ZIP 版本通过旧版 ZIP 路由下载。
- 标志：
--version <version>：下载指定版本。--tag <tag>：下载带标签的版本（默认值：latest）。-o, --output <path>：输出文件或目录。--force：覆盖现有输出文件。--json：机器可读输出。
package verify <file>
- 为本地工件计算 ClawHub SHA-256、npm
sha512完整性和 npm shasum。 - 配合
--package使用时，会从 ClawHub 解析预期元数据，并将本地文件与已发布的工件元数据进行比较。 - 配合直接摘要标志使用时，无需网络查找即可验证。
- 标志：
--package <name>：用于解析预期工件元数据的软件包名称。--version <version>或--tag <tag>：预期的软件包版本。--sha256 <hex>：预期的 ClawHub SHA-256。--npm-integrity <sri>：预期的 npm integrity。--npm-shasum <sha1>：预期的 npm shasum。--json：机器可读输出。
package validate <source>
- 针对本地插件软件包文件夹运行 ClawHub CLI 内置的 Plugin Inspector。
- 默认使用离线/静态验证，不会定位或导入本地 OpenClaw checkout。
- 硬性兼容性错误会以非零状态退出。仅警告的发现会被打印，但以零状态退出。
- 标志：
--out <dir>：将 Plugin Inspector 报告写入此目录。--openclaw <path>：针对显式指定的本地 OpenClaw checkout 进行检查。--runtime：启用运行时捕获；会导入插件代码。--allow-execute：允许在隔离工作区中进行运行时捕获。--no-mock-sdk：在运行时捕获期间禁用模拟的 OpenClaw SDK。--json：机器可读输出。
package delete <name>
- 不带
--version时，软删除一个软件包及其所有发布版本。 --version <version>会通过故障关闭的版本专用路由，永久删除一个归属自己的非最新发布版本。 已删除的版本无法恢复或重新发布。删除当前最新版本前，请先发布替代版本。此仅限版本的流程要求软件包所有者或组织发布者管理员；平台工作人员不会绕过软件包所有权。- 整个软件包软删除要求软件包所有者、组织发布者所有者/管理员、平台版主或平台管理员。
- 标志：
--version <version>：永久删除一个非最新版本。--yes：跳过确认。--json：机器可读输出。
package undelete <name>
- 恢复一个已软删除的软件包及其发布版本。
- 没有版本恢复；永久删除的版本无法恢复。
- 要求软件包所有者、组织发布者所有者/管理员、平台版主或平台管理员。
- 调用
POST /api/v1/packages/{name}/undelete。 - 标志：
--yes：跳过确认。--json：机器可读输出。
package transfer <name>
- 将软件包转移给另一个发布者。
- 要求对当前软件包所有者和目标发布者都拥有管理员访问权限，除非由平台管理员执行。
- 作用域软件包名称必须转移给匹配的作用域所有者。
- 调用
POST /api/v1/packages/{name}/transfer。 - 标志：
--to <owner>：目标发布者 handle。--reason <text>：可选审计原因。--json：机器可读输出。
package report
- 用于向版主报告软件包的已认证命令。
- 调用
POST /api/v1/packages/{name}/report。 - 报告是软件包级别的，可选绑定到某个版本，并会对版主可见以供审核。
- 报告本身不会自动隐藏软件包或阻止下载。
- 标志：
--version <version>：要附加到报告的可选软件包版本。--reason <text>：必填报告原因。--json：机器可读输出。
package moderation-status
- 用于检查软件包审核可见性的所有者命令。
- 调用
GET /api/v1/packages/{name}/moderation。 - 显示当前软件包扫描状态、开放报告数量、最新发布版本的手动审核状态、下载阻止状态以及审核原因。
- 标志：
--json：机器可读输出。
package readiness <name>
- 检查软件包是否已准备好供未来的 OpenClaw 使用。
- 调用
GET /api/v1/packages/{name}/readiness。 - 报告官方状态、ClawPack 可用性、工件摘要、来源出处、OpenClaw 兼容性、主机目标、环境元数据和扫描状态的阻碍项。
- 标志：
--json：机器可读输出。
package migration-status <name>
- 显示面向操作员的迁移状态，用于可能替换内置 OpenClaw 插件的软件包。
- 调用与
package readiness相同的计算型就绪状态端点，但会打印聚焦迁移的状态、最新版本、官方软件包状态、检查和阻碍项。 - 标志：
--json：机器可读输出。
publisher create <handle>
- 创建一个由已认证用户拥有的组织发布者。
- handle 会规范化为小写，并且可以带或不带
@传入。 - 新创建的组织发布者默认不是受信任/官方的。
- 如果该 handle 已被现有发布者、用户或保留路由使用，则失败。
package publish <source>
- 通过
POST /api/v1/packages发布代码插件或捆绑插件。 <source>接受：- 本地文件夹路径：
./my-plugin - 本地 ClawPack npm-pack tarball：
./my-plugin-1.2.3.tgz - GitHub 仓库：
owner/repo或owner/repo@ref - GitHub URL：
https://github.com/owner/repo
- 本地文件夹路径：
- 元数据会从
package.json、openclaw.plugin.json以及 真实的 OpenClaw 捆绑标记自动检测，例如.codex-plugin/plugin.json、.claude-plugin/plugin.json和.cursor-plugin/plugin.json。 .tgz来源会被视为 ClawPack。CLI 会上传精确的 npm-pack 字节，并且仅将提取出的package/内容用于验证和 元数据预填。- 代码插件文件夹会在上传前打包为 ClawPack npm tarball，以便 OpenClaw 安装可以验证精确 artifact。捆绑插件文件夹仍然 使用提取文件的发布路径。
- 对于 GitHub 来源，来源归属会从仓库、解析后的 commit、ref 和子路径自动填充。
- 对于本地文件夹，当 origin remote 指向 GitHub 时，来源归属会从本地 git 自动检测。
- 外部代码插件必须显式声明
openclaw.compat.pluginApi和openclaw.build.openclawVersion。 顶层package.json.version不会作为发布验证的回退使用。 --dry-run会预览解析后的发布 payload，而不上传。--json会为 CI 输出机器可读结果。- 当操作者拥有发布者访问权限时，
--owner <handle>会在用户或组织发布者 handle 下发布。 - 作用域包名必须匹配所选 owner。请参阅
docs/publishing.md。 - 现有标志（
--family、--name、--version、--source-repo、--source-commit、--source-ref、--source-path）仍可作为覆盖项使用。 - 私有 GitHub 仓库需要
GITHUB_TOKEN。
推荐的本地流程
先使用--dry-run，这样你可以在创建真实发布前确认解析后的包元数据和
来源归属：
本地文件夹流程
对于代码插件，文件夹发布会从包文件夹构建并上传 ClawPack artifact：--family code-plugin 的最小 package.json
外部代码插件需要在 package.json 中提供少量 OpenClaw 元数据。
这个最小 manifest 足以成功发布：
openclaw.compat.pluginApiopenclaw.build.openclawVersion
package.json.version是你的包发布版本，但它不会作为 OpenClaw 兼容性/构建验证的回退使用。openclaw.hostTargets和openclaw.environment是可选元数据。 ClawHub 可能会在存在时展示它们，但发布并不要求这些字段。- 如果你想发布更详细的兼容性元数据，
openclaw.compat.minGatewayVersion和openclaw.build.pluginSdkVersion是可选扩展项。 - 如果你使用的是较旧的
clawhubCLI 版本，请在发布前升级，以便 本地预检能在上传前运行。 - 如果验证报告了修复代码，请参阅 插件验证修复。
GitHub Actions
ClawHub 还为插件仓库提供官方可复用 workflow：/.github/workflows/package-publish.yml。
典型调用方设置：
- 可复用 workflow 默认将
source设为调用方仓库。 - 对于 monorepo，传入
source_path，让 workflow 发布插件 包文件夹，例如source_path: extensions/codex。 - 将可复用 workflow 固定到稳定 tag 或完整 commit SHA。不要从
@main运行发布。 pull_request应使用dry_run: true，这样 CI 不会产生污染。- 真实发布应限制为可信事件，例如
workflow_dispatch或 tag push。 - 不带 secret 的可信发布仅适用于
workflow_dispatch；tag push 仍需要clawhub_token。 - 保持
clawhub_token可用，用于首次发布、不可信包或应急发布。 - workflow 会将 JSON 结果作为 artifact 上传，并将其公开为 workflow outputs。
package trusted-publisher get <name>
- 显示包的 GitHub Actions 可信发布者配置。
- 设置配置后使用此命令，以确认仓库、workflow 文件名 以及可选的 environment pin。
- 标志：
--json：机器可读输出。
package trusted-publisher set <name>
- 为现有包附加或替换 GitHub Actions 可信发布者配置。
- 包必须先通过普通的手动发布或 token 认证的
clawhub package publish创建。 - 配置设置后，未来受支持的 GitHub Actions 发布可以使用 OIDC/可信发布，而无需长期有效的 ClawHub token。
--repository <repo>必须是owner/repo。--workflow-filename <file>必须匹配.github/workflows/中的 workflow 文件名。--environment <name>是可选项。配置后，OIDC claim 中的 GitHub Actions environment 必须完全匹配。- ClawHub 会在运行此命令时验证配置的 GitHub 仓库。 公共仓库可以通过公开 GitHub 元数据验证。私有 仓库需要 ClawHub 拥有该仓库的 GitHub 访问权限，例如 通过未来的 ClawHub GitHub App 安装或另一个已授权的 GitHub 集成。
- 标志：
--repository <repo>：GitHub 仓库，例如openclaw/example-plugin。--workflow-filename <file>：workflow 文件名，例如package-publish.yml。--environment <name>：可选的精确匹配 GitHub Actions environment。--json：机器可读输出。
package trusted-publisher delete <name>
- 从包中移除可信发布者配置。
- 如果需要禁用或重新创建 workflow、仓库或 environment pin，请将此命令用作回滚。
- 在重新设置配置前，未来的真实发布必须使用普通的认证发布。
- 标志：
--json：机器可读输出。
安装遥测
- 登录后运行
clawhub install <slug>时发送，除非 设置了CLAWHUB_DISABLE_TELEMETRY=1。 - 报告采用尽力而为方式。如果遥测不可用，安装命令不会失败。
- 详情：
docs/telemetry.md。