命令列介面
命令列介面套件：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 Proxy
命令列介面會遵循標準 HTTP Proxy 環境變數，供位於企業 Proxy 或受限網路後方的系統使用：HTTPS_PROXY/https_proxyHTTP_PROXY/http_proxyNO_PROXY/no_proxy
HTTPS_PROXY 用於 HTTPS 請求，HTTP_PROXY 用於純 HTTP。NO_PROXY / no_proxy 會被遵循，以便針對特定主機或網域略過 Proxy。
這在直接對外連線遭封鎖的系統上是必要的（例如 Docker 容器、僅能透過 Proxy 上網的 Hetzner VPS、企業防火牆）。
範例：
設定檔
儲存你的 API 權杖與快取的 registry 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存在，命令列介面會重用舊版路徑 - 覆寫：
CLAWHUB_CONFIG_PATH（舊版CLAWDHUB_CONFIG_PATH）
命令
login / auth login
- 預設：開啟瀏覽器到
<site>/cli/auth，並透過 loopback callback 完成。 - 無介面：
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>（摘要會截斷為 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 項目。 - 登入時會以 best-effort telemetry 傳送資料，以便停用目前的安裝計數。
- 互動式：要求確認。
- 非互動式（
--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
- 從本機檔案計算 fingerprint。
- 如果 fingerprint 符合已知版本：不提示。
- 如果 fingerprint 不符合：
- 預設拒絕
- 使用
--force覆寫（若為互動式，則提示）
- 已釘選技能永遠不會被
--force更新。 update <skill>會對已釘選技能快速失敗，並告訴你先執行clawhub unpin <skill>。update --all會略過已釘選 slug，並列印哪些保持凍結的摘要。
skill publish <path>
- 比較本機 bundle fingerprint 與 ClawHub；內容已發布時會成功結束。
- 新技能預設為
1.0.0；已變更技能預設為下一個 patch 版本。 --version <version>會明確選取版本，並在內容符合既有版本時仍然發布。--dry-run會在不上傳的情況下解析發布；--json會列印機器可讀結果。--owner <handle>會在執行者具備 publisher 存取權時，以組織/使用者 publisher handle 發布。--migrate-owner會在發布新版本時，將既有技能移至--owner。需要兩個 publisher 的管理員/擁有者存取權。- 擁有者與審查行為在
docs/publishing.md中說明。 - 發布技能表示它會在 ClawHub 上以
MIT-0發行。 - 已發布技能可免費使用、修改與再散布，無需署名。
- ClawHub 不支援付費技能或按技能定價。
- 舊版別名：
publish <path>。
GitHub Actions
ClawHub 的可重用skill-publish.yml
workflow 會對一個 skill_path 呼叫 skill publish，或對 root 下每個直接技能資料夾呼叫（預設：skills）。它會略過未變更技能，並使用相同的自動 patch 版本行為。
設定 dry_run: true 可在沒有權杖的情況下預覽。實際發布需要 clawhub_token secret。
sync
- 掃描目前 workdir、已設定的 skills 目錄，以及任何
--root <dir>資料夾，尋找包含SKILL.md或skill.md的本機技能資料夾。 - 比較每個本機技能 fingerprint 與 ClawHub，並只發布新的或已變更的技能。
- 新技能發布為
1.0.0；已變更技能預設發布為下一個 patch 版本。針對應以更大 semver 步幅移動的更新批次，請使用--bump minor|major。 --dry-run顯示發布計畫而不上傳；--json會列印機器可讀計畫。--all會在不提示的情況下發布每個新的或已變更技能。沒有--all時，互動式終端機可讓你選取要發布的技能。--owner <handle>會在執行者具備 publisher 存取權時，以組織/使用者 publisher handle 發布。sync只會單向發布。它不會安裝、更新、下載，或回報安裝/下載 telemetry。
scan --slug <slug>
- 需要
clawhub login。 - 透過
POST /api/v1/skills/-/scan執行 ClawHub ClawScan，然後輪詢直到掃描進入終端狀態。 - 掃描是非同步的，可能需要一些時間完成。排隊期間，終端機 spinner 會顯示目前的優先掃描位置，以及前方還有多少掃描。
- 已發布掃描需要擁有權或 publisher 管理存取權。版主/管理員可透過
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
提供官方可重用 workflow，供技能 repo 與 catalog repo 使用。
典型 catalog 設定：
root對 catalog repo 預設為skills。- 傳入
skill_path: skills/review-helper可處理單一技能資料夾。 owner對應到命令列介面的--owner旗標；省略它則以已驗證使用者身分發布。- V1 技能發布使用
clawhub_token；GitHub OIDC trusted publishing 目前僅適用於套件。
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>：檢查特定版本（預設：最新）。--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
sha512integrity、 npm shasum，以及 tarball 的package.json名稱/版本。 - 舊版 ZIP 版本會透過舊版 ZIP 路由下載。
- 旗標：
--version <version>：下載特定版本。--tag <tag>：下載帶有標籤的版本（預設：latest）。-o, --output <path>：輸出檔案或目錄。--force：覆寫現有輸出檔案。--json：機器可讀輸出。
package verify <file>
- 為本機成品計算 ClawHub SHA-256、npm
sha512integrity 和 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 命令列介面內建的 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>
- 顯示可取代 bundled OpenClaw 外掛的套件之面向操作員的遷移狀態。
- 呼叫與
package readiness相同的計算後 readiness 端點，但會列印 以遷移為重點的狀態、最新版本、官方套件狀態、檢查和 阻擋項目。 - 旗標：
--json：機器可讀輸出。
publisher create <handle>
- 建立由已驗證使用者擁有的組織發布者。
- handle 會正規化為小寫，並可帶或不帶
@傳入。 - 新建立的組織發布者預設不是受信任/官方。
- 如果 handle 已被現有發布者、使用者或保留路由使用，則會失敗。
package publish <source>
- 透過
POST /api/v1/packages發佈程式碼外掛或 bundle 外掛。 <source>可接受：- 本機資料夾路徑：
./my-plugin - 本機 ClawPack npm-pack tarball：
./my-plugin-1.2.3.tgz - GitHub repo：
owner/repo或owner/repo@ref - GitHub URL：
https://github.com/owner/repo
- 本機資料夾路徑：
- 中繼資料會從
package.json、openclaw.plugin.json，以及 真正的 OpenClaw bundle 標記自動偵測，例如.codex-plugin/plugin.json、.claude-plugin/plugin.json和.cursor-plugin/plugin.json。 .tgz來源會被視為 ClawPack。命令列介面會上傳確切的 npm-pack 位元組，並只使用解出的package/內容進行驗證與 中繼資料預先填入。- 程式碼外掛資料夾會先封裝成 ClawPack npm tarball 再上傳，讓 OpenClaw 安裝項目可以驗證確切成品。bundle 外掛資料夾仍然 使用解出檔案的發佈路徑。
- 對於 GitHub 來源，來源歸屬會從 repo、解析後的 commit、ref 和子路徑自動填入。
- 對於本機資料夾，當 origin remote 指向 GitHub 時，來源歸屬會從本機 git 自動偵測。
- 外部程式碼外掛必須明確宣告
openclaw.compat.pluginApi和openclaw.build.openclawVersion。 頂層package.json.version不會作為發佈驗證的 fallback。 --dry-run會預覽解析後的發佈 payload，而不上傳。--json會輸出 CI 可讀取的機器可讀格式。- 當執行者具有 publisher 存取權時，
--owner <handle>會以使用者或組織 publisher handle 發佈。 - scoped package 名稱必須符合選取的 owner。請參閱
docs/publishing.md。 - 既有旗標（
--family、--name、--version、--source-repo、--source-commit、--source-ref、--source-path）仍可作為覆寫使用。 - 私有 GitHub repo 需要
GITHUB_TOKEN。
建議的本機流程
先使用--dry-run，如此你可以在建立正式 release 前確認解析後的 package 中繼資料和
來源歸屬：
本機資料夾流程
對於程式碼外掛，資料夾發佈會從 package 資料夾建置並上傳 ClawPack 成品：--family code-plugin 的最小 package.json
外部程式碼外掛需要在
package.json 中提供少量 OpenClaw 中繼資料。這個最小 manifest 足以成功發佈：
openclaw.compat.pluginApiopenclaw.build.openclawVersion
package.json.version是你的 package release 版本，但它不會作為 OpenClaw 相容性/建置驗證的 fallback。openclaw.hostTargets和openclaw.environment是選用中繼資料。 ClawHub 可能會在存在時顯示它們，但發佈時不需要。- 如果你想發佈
更詳細的相容性中繼資料，
openclaw.compat.minGatewayVersion和openclaw.build.pluginSdkVersion是選用附加項。 - 如果你使用較舊的
clawhub命令列介面 release，請先升級再發佈，讓 本機 preflight 檢查在上傳前執行。 - 如果驗證回報 remediation code，請參閱 外掛驗證修正。
GitHub Actions
ClawHub 也為外掛 repo 提供官方可重用 workflow：/.github/workflows/package-publish.yml。
典型 caller 設定：
- 可重用 workflow 預設將
source設為 caller repo。 - 對於 monorepo，請傳入
source_path，讓 workflow 發佈外掛 package 資料夾，例如source_path: extensions/codex。 - 將可重用 workflow pin 到穩定 tag 或完整 commit SHA。不要從
@main執行 release 發佈。 pull_request應使用dry_run: true，讓 CI 維持不污染狀態。- 真正的發佈應限制在受信任事件，例如
workflow_dispatch或 tag pushes。 - 不使用 secret 的受信任發佈只適用於
workflow_dispatch；tag pushes 仍需要clawhub_token。 - 保留
clawhub_token供首次發佈、不受信任 package，或 break-glass 發佈使用。 - workflow 會將 JSON 結果作為 artifact 上傳，並將其公開為 workflow outputs。
package trusted-publisher get <name>
- 顯示 package 的 GitHub Actions 受信任 publisher 設定。
- 設定 config 後使用此命令，以確認 repository、workflow filename， 以及選用的 environment pin。
- 旗標：
--json：機器可讀輸出。
package trusted-publisher set <name>
- 為既有 package 附加或取代 GitHub Actions 受信任 publisher 設定。
- package 必須先透過一般手動或 token-authenticated
clawhub package publish建立。 - 設定 config 後，未來支援的 GitHub Actions 發佈可以使用 OIDC/受信任發佈，而不需要長期有效的 ClawHub token。
--repository <repo>必須是owner/repo。--workflow-filename <file>必須符合.github/workflows/中的 workflow 檔名。--environment <name>是選用項。設定後，OIDC claim 中的 GitHub Actions environment 必須完全相符。- ClawHub 會在此命令執行時驗證已設定的 GitHub repository。 公開 repository 可透過公開 GitHub 中繼資料驗證。私有 repository 需要 ClawHub 具有該 repository 的 GitHub 存取權，例如 透過未來的 ClawHub GitHub App 安裝或其他已授權的 GitHub 整合。
- 旗標：
--repository <repo>：GitHub repository，例如openclaw/example-plugin。--workflow-filename <file>：workflow 檔名，例如package-publish.yml。--environment <name>：選用的 exact-match GitHub Actions environment。--json：機器可讀輸出。
package trusted-publisher delete <name>
- 從 package 移除受信任 publisher 設定。
- 如果 workflow、repository 或 environment pin 需要 停用或重新建立，請將此作為 rollback 使用。
- 未來真正發佈必須使用一般 authenticated publishing，直到再次設定 config。
- 旗標：
--json：機器可讀輸出。
安裝遙測
- 登入時，在
clawhub install <slug>後傳送，除非 已設定CLAWHUB_DISABLE_TELEMETRY=1。 - 回報採 best-effort。若 telemetry 不可用，install 命令不會失敗。
- 詳情：
docs/telemetry.md。