OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Get started

命令列介面

命令列介面

命令列介面套件：clawhub，執行檔：clawhub。

使用 npm 或 pnpm 進行全域安裝：

bash
npm i -g clawhub# 或pnpm add -g clawhub

接著進行驗證：

bash
clawhub --helpclawhub loginclawhub whoami

全域旗標

  • --workdir <dir>：工作目錄（預設：目前工作目錄；若已設定，則備援使用 Clawdbot 工作區）
  • --dir <dir>：工作目錄下的安裝目錄（預設：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

對於位於公司 Proxy 或受限網路後方的系統，命令列介面會遵循標準 HTTP Proxy 環境變數：

  • HTTPS_PROXY / https_proxy
  • HTTP_PROXY / http_proxy
  • NO_PROXY / no_proxy

設定其中任一變數時，命令列介面會透過指定的 Proxy 路由對外請求。HTTPS 請求使用 HTTPS_PROXY，一般 HTTP 請求則使用 HTTP_PROXY。系統會遵循 NO_PROXY / no_proxy，讓特定主機或網域略過 Proxy。

在直接對外連線遭封鎖的系統上，這是必要設定（例如 Docker 容器、只能透過 Proxy 存取網際網路的 Hetzner VPS、公司防火牆）。

範例：

bash
export HTTPS_PROXY=http://proxy.example.com:3128export NO_PROXY=localhost,127.0.0.1clawhub search "我的查詢"

未設定 Proxy 變數時，行為維持不變（直接連線）。

設定檔

儲存你的 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 存在，命令列介面會沿用舊版路徑
  • 覆寫：CLAWHUB_CONFIG_PATH（舊版 CLAWDHUB_CONFIG_PATH）

命令

login / auth login

  • 預設：開啟瀏覽器前往 <site>/cli/auth，並透過迴送回呼完成登入。
  • 無介面模式：clawhub login --token clh_...
  • 遠端／無介面互動模式：clawhub login --device 會顯示代碼並等待你在 <site>/cli/device 完成授權。

whoami

  • 透過 /api/v1/whoami 驗證已儲存的權杖。

token

  • 將已儲存的 API 權杖輸出至標準輸出。
  • 適合透過管線將本機登入權杖傳入 CI 機密設定命令。

star <skill> / unstar <skill>

  • 將技能加入你的精選項目，或從中移除。
  • 呼叫 POST /api/v1/stars/<slug> 與 DELETE /api/v1/stars/<slug>。
  • --yes 會略過確認。

search <query...>

  • 呼叫 /api/v1/search?q=...。
  • 輸出包含技能 slug、擁有者帳號、顯示名稱與相關性分數。
  • 搜尋排序會優先考量 slug／名稱權杖的完全相符，其次才是下載熱門度。例如獨立的 slug 權杖 map，與 personal-map 的相符程度會高於 amap 中的子字串。
  • 熱門度只會小幅影響排名，無法保證排在最前面。
  • 如果某項技能理應出現卻未顯示，請在登入狀態下執行 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>：檢查特定版本（預設：最新版本）。
  • --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>，並刪除鎖定檔項目。
  • 登入時會盡力傳送遙測資料，以停用目前的安裝計數。
  • 互動模式：要求確認。
  • 非互動模式（--no-input）：需要 --yes。

list

  • 讀取 <workdir>/.clawhub/lock.json（舊版為 .clawdhub）。
  • 在使用 clawhub pin 凍結的技能旁顯示 pinned，包括選填的原因。

pin <skill>

  • 在鎖定檔中將已安裝的技能標記為已釘選。
  • --reason <text> 會記錄凍結技能的原因。
  • update --all 會略過已釘選的技能，直接執行 update <skill> 則會遭拒。
  • 已釘選的技能也會拒絕 install --force，以免意外取代本機內容。

unpin <skill>

  • 從已安裝技能中移除鎖定檔釘選，讓未來的更新可以修改該技能。

update [@owner/slug] / update --all

  • 根據本機檔案計算指紋。
  • 如果指紋符合已知版本：不顯示提示。
  • 如果指紋不符：
    • 預設拒絕
    • 使用 --force 覆寫（若為互動模式，也可透過提示確認）
  • --force 永遠不會更新已釘選的技能。
  • 對已釘選的技能執行 update <skill> 會立即失敗，並提示你先執行 clawhub unpin <skill>。
  • update --all 會略過已釘選的 slug，並顯示哪些項目仍維持凍結的摘要。

skill publish <path>

  • 將本機套件組合指紋與 ClawHub 比較；若內容已發布，則成功結束。
  • 新技能預設為 1.0.0；已變更的技能預設為下一個修補版本。
  • --version <version> 會明確選取版本，即使內容與現有版本相符仍會發布。
  • --dry-run 會解析發布流程但不上傳；--json 會輸出機器可讀的結果。
  • 當執行者具有發布者存取權時，--owner <handle> 會以組織／使用者的發布者帳號發布。
  • --migrate-owner 會在發布新版本時，將現有技能移轉至 --owner。需要同時具有兩個發布者的管理員／擁有者存取權。
  • 擁有者與審核行為的說明請參閱 docs/publishing.md。
  • 發布技能表示該技能會在 ClawHub 上以 MIT-0 授權發布。
  • 已發布的技能可免費使用、修改與再散布，無須標示出處。
  • ClawHub 不支援付費技能或個別技能定價。
  • 舊版別名：publish <path>。
bash
clawhub skill publish ./my-skill --dry-runclawhub skill publish ./my-skillclawhub skill publish ./my-skill --version 2.0.0

GitHub Actions

ClawHub 的可重複使用 skill-publish.yml 工作流程會針對一個 skill_path 呼叫 skill publish，或針對 root 下的每個第一層技能資料夾呼叫（預設：skills）。它會略過未變更的技能，並採用相同的自動修補版本行為。

設定 dry_run: true 可在不使用權杖的情況下預覽。實際發布需要 clawhub_token 機密。

sync

  • 掃描目前的工作目錄、已設定的技能目錄，以及任何 --root <dir> 資料夾，尋找包含 SKILL.md 或 skill.md 的本機技能資料夾。
  • 將每個本機技能指紋與 ClawHub 比較，只發布新增或已變更的技能。
  • 新技能會以 1.0.0 發布；已變更的技能預設發布下一個修補版本。對於應提升較大語意化版本幅度的更新批次，請使用 --bump minor|major。
  • --dry-run 會顯示發布計畫但不上傳；--json 會輸出機器可讀的計畫。
  • --all 會發布所有新增或已變更的技能，而不顯示提示。若未使用 --all，互動式終端機會讓你選取要發布的技能。
  • 當執行者具有發布者存取權時，--owner <handle> 會以組織／使用者的發布者帳號發布。
  • sync 僅支援單向發布。它不會安裝、更新、下載，也不會回報安裝／下載遙測資料。
bash
clawhub sync --all --dry-runclawhub sync --allclawhub sync --root ./skills --owner openclaw --bump minor

scan --slug <slug>

  • 需要執行 clawhub login。
  • 透過 POST /api/v1/skills/-/scan 執行 ClawHub ClawScan，接著輪詢直到掃描進入終止狀態。
  • 掃描為非同步作業，可能需要一段時間才能完成。排隊期間，終端機的旋轉指示器會顯示目前的優先掃描順位，以及前方還有多少項掃描。
  • 已發布內容的掃描需要擁有權或發布者管理存取權。版主／管理員可透過 clawhub-admin 使用相同的後端。
  • --update 僅可與 --slug 搭配使用；它會將成功的已發布掃描結果寫回所選版本。
  • --output <file.zip> 會下載完整報告封存檔，其中包含 manifest.json、clawscan.json、skillspector.json、static-analysis.json、virustotal.json 與 README.md。
  • --json 會輸出完整的輪詢回應，以供自動化使用。
  • 已不再支援本機路徑掃描。請上傳新版本，然後使用 scan download 擷取該提交版本所儲存的掃描結果。
bash
clawhub scan --slug gifgrepclawhub scan --slug gifgrep --version 1.2.3clawhub scan --slug gifgrep --update --output report.zip

scan download <name>

  • 需要執行 clawhub login。
  • 下載已提交技能或外掛版本所儲存的掃描報告 ZIP，包括遭 ClawHub 安全性檢查封鎖或隱藏的版本。
  • 下載技能時使用技能 slug，且預設為 --kind skill。
  • 下載外掛時使用套件名稱，且必須指定 --kind plugin。
  • --version 為必要選項，讓作者能檢查 ClawHub 封鎖的確切提交版本。
  • --output <file.zip> 用於選擇目的地路徑。
bash
clawhub scan download gifgrep --version 1.2.3clawhub scan download @scope/demo --version 2.0.0 --kind plugin --output report.zip

GitHub Actions

ClawHub 在 /.github/workflows/skill-publish.yml 提供官方可重複使用的工作流程，供技能儲存庫與目錄儲存庫使用。

典型的目錄設定：

yaml
name: 技能發布 on:  pull_request:  workflow_dispatch: jobs:  dry-run:    if: github.event_name == 'pull_request'    uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1    with:      owner: nvidia      dry_run: true   publish:    if: github.event_name == 'workflow_dispatch'    uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1    with:      owner: nvidia      dry_run: false    secrets:      clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}

注意事項：

  • 對於目錄儲存庫，root 預設為 skills。
  • 傳入 skill_path: skills/review-helper 可處理單一技能資料夾。
  • owner 對應命令列介面的 --owner 旗標；省略時會以已驗證身分的使用者發布。
  • V1 技能發布使用 clawhub_token；GitHub OIDC 受信任發布目前僅適用於套件。

delete <skill>

  • 若未指定 --version，則軟刪除 Skills（擁有者、版主或管理員）。
  • 呼叫 DELETE /api/v1/skills/{slug}。
  • 由擁有者發起的軟刪除會保留該 slug 30 天；此命令會列印到期時間。
  • --version <version> 會透過預設拒絕、 版本專用的路由，永久刪除一個由你擁有且非最新的版本。 已刪除的版本無法還原或重新發布。刪除目前的最新版本前，請先發布替代版本。 在此僅限版本的流程中，平台工作人員無法略過擁有權限制。
  • --reason <text> 會在整個 Skills 的軟刪除記錄與稽核日誌中記錄審核備註。
  • --note <text> 是 --reason 的別名。
  • --yes 會略過確認。

undelete <skill>

  • 還原隱藏的 Skills（擁有者、版主或管理員）。
  • 無法取消刪除版本；永久刪除的版本無法還原。
  • 呼叫 POST /api/v1/skills/{slug}/undelete。
  • --reason <text> 會在 Skills 與稽核日誌中記錄審核備註。
  • --note <text> 是 --reason 的別名。
  • --yes 會略過確認。

hide <skill>

  • 隱藏 Skills（擁有者、版主或管理員）。
  • delete 的別名。

unhide <skill>

  • 取消隱藏 Skills（擁有者、版主或管理員）。
  • undelete 的別名。

skill rename <skill> <new-name>

  • 重新命名你擁有的 Skills，並保留先前的 slug 作為重新導向別名。
  • 呼叫 POST /api/v1/skills/{slug}/rename。
  • --yes 會略過確認。

skill merge <source> <target>

  • 將一個你擁有的 Skills 合併到另一個你擁有的 Skills。
  • 來源 slug 將不再公開列出，並成為指向目標的重新導向別名。
  • 呼叫 POST /api/v1/skills/{sourceSlug}/merge。
  • --yes 會略過確認。

transfer

  • 擁有權移轉工作流程。
  • 移轉至使用者代號時，會建立待處理要求，由接收者接受。
  • 移轉至組織／發布者代號時，只有在執行者同時具備目前擁有者與目標發布者的 管理員存取權時，才會立即套用。
  • 子命令：
    • 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}/transfer
    • POST /api/v1/skills/{slug}/transfer/accept
    • POST /api/v1/skills/{slug}/transfer/reject
    • POST /api/v1/skills/{slug}/transfer/cancel
    • GET /api/v1/transfers/incoming
    • GET /api/v1/transfers/outgoing

package explore [query...]

  • 透過 GET /api/v1/packages 和 GET /api/v1/packages/search 瀏覽或搜尋統一的套件目錄。
  • 對外掛和其他套件家族項目使用此命令；頂層 search 仍是 Skills 搜尋介面。
  • 旗標：
    • --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

範例：

bash
clawhub package explore --family code-pluginclawhub package explore --family code-plugin --os darwin --requires-desktopclawhub package explore --family code-plugin --artifact-kind npm-packclawhub package explore --npm-mirrorclawhub package explore episodic-claw --family code-plugin

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 sha512 完整性、 npm shasum，以及壓縮封存檔的 package.json 名稱／版本。
  • 舊版 ZIP 版本會透過舊版 ZIP 路由下載。
  • 旗標：
    • --version <version>：下載特定版本。
    • --tag <tag>：下載加上標籤的版本（預設值：latest）。
    • -o, --output <path>：輸出檔案或目錄。
    • --force：覆寫現有的輸出檔案。
    • --json：機器可讀的輸出。

範例：

bash
clawhub package download @openclaw/example-plugin --tag latestclawhub package download @openclaw/example-plugin --version 1.2.3 -o artifacts/

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 完整性。
    • --npm-shasum <sha1>：預期的 npm shasum。
    • --json：機器可讀的輸出。

範例：

bash
clawhub package verify ./example-plugin-1.2.3.tgz --package @openclaw/example-plugin --version 1.2.3clawhub package verify ./example-plugin-1.2.3.tgz --sha256 <hex>

package validate <source>

  • 對本機外掛套件 資料夾執行 ClawHub 命令列介面內建的外掛檢查器。
  • 預設執行離線／靜態驗證，不會尋找或匯入本機 OpenClaw 原始碼簽出。
  • 嚴重相容性錯誤會以非零狀態結束。僅警告的發現會列印出來，但 會以零狀態結束。
  • 旗標：
    • --out <dir>：將外掛檢查器報告寫入此目錄。
    • --openclaw <path>：針對明確指定的本機 OpenClaw 原始碼簽出進行檢查。
    • --runtime：啟用執行階段擷取；會匯入外掛程式碼。
    • --allow-execute：允許在隔離的工作區中進行執行階段擷取。
    • --no-mock-sdk：停用執行階段擷取期間模擬的 OpenClaw SDK。
    • --json：機器可讀的輸出。

範例：

bash
clawhub package validate ./example-plugin

若驗證回報套件、資訊清單、SDK 匯入或成品發現，請參閱 外掛驗證修正，然後重新執行命令。

package delete <name>

  • 若未指定 --version，則軟刪除套件及所有發行版本。
  • --version <version> 會透過預設拒絕、 版本專用的路由，永久刪除一個由你擁有且非最新的發行版本。 已刪除的版本無法還原或重新發布。刪除目前的最新版本前，請先發布替代版本。 此僅限版本的流程要求套件擁有者或組織發布者管理員執行； 平台工作人員無法略過套件擁有權限制。
  • 整個套件的軟刪除要求套件擁有者、組織發布者擁有者／管理員、平台 版主或平台管理員執行。
  • 旗標：
    • --version <version>：永久刪除一個非最新版本。
    • --yes：略過確認。
    • --json：機器可讀的輸出。

範例：

bash
clawhub package delete @openclaw/example-plugin --yesclawhub package delete @openclaw/example-plugin --version 1.2.3 --yes

package undelete <name>

  • 還原已軟刪除的套件與發行版本。
  • 無法取消刪除版本；永久刪除的版本無法還原。
  • 要求套件擁有者、組織發布者擁有者／管理員、平台版主 或平台管理員執行。
  • 呼叫 POST /api/v1/packages/{name}/undelete。
  • 旗標：
    • --yes：略過確認。
    • --json：機器可讀的輸出。

範例：

bash
clawhub package undelete @openclaw/example-plugin --yes

package transfer <name>

  • 將套件移轉給另一個發布者。
  • 除非由平台管理員執行，否則必須同時具備目前套件擁有者與目標 發布者的管理員存取權。
  • 具範圍的套件名稱必須移轉給相符的範圍擁有者。
  • 呼叫 POST /api/v1/packages/{name}/transfer。
  • 旗標：
    • --to <owner>：目標發布者代號。
    • --reason <text>：選用的稽核原因。
    • --json：機器可讀的輸出。

範例：

bash
clawhub package transfer @openclaw/example-plugin --to openclaw

package report

  • 用於向版主檢舉套件的已驗證命令。
  • 呼叫 POST /api/v1/packages/{name}/report。
  • 檢舉以套件為層級，可選擇與某個版本相關聯，並會顯示 給版主進行審查。
  • 檢舉本身不會自動隱藏套件或封鎖下載。
  • 旗標：
    • --version <version>：選擇性附加至檢舉的套件版本。
    • --reason <text>：必要的檢舉原因。
    • --json：機器可讀的輸出。

範例：

bash
clawhub package report @openclaw/example-plugin --version 1.2.3 --reason "可疑的原生承載內容"

package moderation-status

  • 用於檢查套件審核可見性的擁有者命令。
  • 呼叫 GET /api/v1/packages/{name}/moderation。
  • 顯示目前的套件掃描狀態、未結案檢舉數量、最新發行版本的人工 審核狀態、下載封鎖狀態及審核原因。
  • 旗標：
    • --json：機器可讀的輸出。

範例：

bash
clawhub package moderation-status @openclaw/example-plugin

package readiness <name>

  • 檢查套件是否已準備好供未來的 OpenClaw 使用。
  • 呼叫 GET /api/v1/packages/{name}/readiness。
  • 回報正式狀態、ClawPack 可用性、成品摘要、 來源出處、OpenClaw 相容性、主機目標、環境中繼資料 及掃描狀態的阻礙因素。
  • 旗標：
    • --json：機器可讀的輸出。

範例：

bash
clawhub package readiness @openclaw/example-plugin

package migration-status <name>

  • 顯示可能取代 OpenClaw 內建外掛之套件的 操作者導向遷移狀態。
  • 呼叫與 package readiness 相同的計算式準備度端點，但會列印 以遷移為重點的狀態、最新版本、正式套件狀態、檢查項目及 阻礙因素。
  • 旗標：
    • --json：機器可讀的輸出。

範例：

bash
clawhub package migration-status @openclaw/example-plugin

publisher create <handle>

  • 建立由已驗證使用者擁有的組織發布者。
  • 代號會正規化為小寫，傳入時可包含或不包含 @。
  • 新建立的組織發布者預設不受信任／非正式。
  • 若代號已由現有發布者、使用者或保留路由使用，則會失敗。
bash
clawhub publisher create opik --display-name "Opik"

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，以及 .codex-plugin/plugin.json、.claude-plugin/plugin.json 和 .cursor-plugin/plugin.json 等實際 OpenClaw 套件組合標記自動偵測中繼資料。
  • .tgz 來源會視為 ClawPack。命令列介面會上傳完全相同的 npm-pack 位元組，並僅將解壓縮後的 package/ 內容用於驗證與 預先填入中繼資料。
  • 程式碼外掛資料夾會在上傳前封裝成 ClawPack npm tarball，讓 OpenClaw 安裝程序能驗證完全相同的成品。套件組合外掛資料夾仍會 使用解壓縮檔案發布路徑。
  • 對於 GitHub 來源，系統會根據儲存庫、解析後的提交、ref 和子路徑自動填入來源歸屬資訊。
  • 對於本機資料夾，當 origin 遠端指向 GitHub 時，系統會從本機 git 自動偵測來源歸屬資訊。
  • 外部程式碼外掛必須明確宣告 openclaw.compat.pluginApi 和 openclaw.build.openclawVersion。 頂層 package.json.version 不會作為發布驗證的備援值。
  • --dry-run 可在不上傳的情況下預覽解析後的發布承載資料。
  • --json 會輸出可供 CI 機器讀取的結果。
  • 當操作者具有發布者存取權時，--owner <handle> 會以使用者或組織發布者代號發布。
  • 有範圍的套件名稱必須符合所選擁有者。請參閱 docs/publishing.md。
  • 現有旗標（--family、--name、--version、--source-repo、--source-commit、--source-ref、--source-path）仍可用於覆寫。
  • 私有 GitHub 儲存庫需要 GITHUB_TOKEN。
bash
clawhub package publish ./plugin.tgz --owner openclaw

建議的本機流程

請先使用 --dry-run，以便在建立正式版本之前確認解析後的套件中繼資料與 來源歸屬資訊：

bash
npm packclawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin --dry-runclawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin

本機資料夾流程

對於程式碼外掛，資料夾發布會從套件資料夾建置並上傳 ClawPack 成品：

bash
clawhub package publish ./my-plugin --family code-plugin --dry-runclawhub package publish ./my-plugin --family code-plugin

--family code-plugin 的最小 package.json

外部程式碼外掛需要在 package.json 中加入少量 OpenClaw 中繼資料。 以下最小資訊清單足以成功發布：

json
{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2"    }  }}

必要欄位：

  • openclaw.compat.pluginApi
  • openclaw.build.openclawVersion

注意事項：

  • package.json.version 是你的套件發行版本，但不會作為 OpenClaw 相容性／建置驗證的備援值。
  • openclaw.hostTargets 和 openclaw.environment 是選用的中繼資料。 若存在，ClawHub 可能會顯示它們，但發布並不要求這些資料。
  • 如果你想發布更詳細的相容性中繼資料， openclaw.compat.minGatewayVersion 和 openclaw.build.pluginSdkVersion 是選用的額外欄位。
  • 如果你使用較舊版本的 clawhub 命令列介面，請在發布前升級，以便 在上傳前執行本機預檢。
  • 如果驗證回報修復代碼，請參閱 外掛驗證修正。

GitHub Actions

ClawHub 也在 /.github/workflows/package-publish.yml 提供適用於外掛儲存庫的官方可重複使用工作流程。

典型的呼叫端設定：

yaml
name: Package Publish on:  pull_request:  workflow_dispatch:  push:    tags:      - "v*" jobs:  dry-run:    if: github.event_name == 'pull_request'    uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0    with:      dry_run: true   publish:    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/')    permissions:      contents: read      id-token: write    uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0    with:      dry_run: false    secrets:      clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}

注意事項：

  • 可重複使用工作流程預設會將 source 設為呼叫端儲存庫。
  • 對於 monorepo，請傳入 source_path，讓工作流程發布外掛 套件資料夾，例如 source_path: extensions/codex。
  • 請將可重複使用工作流程固定至穩定標籤或完整提交 SHA。不要從 @main 執行版本發布。
  • pull_request 應使用 dry_run: true，以避免 CI 產生正式資料。
  • 實際發布應僅限於 workflow_dispatch 或標籤推送等受信任事件。
  • 不使用密鑰的受信任發布僅適用於 workflow_dispatch；標籤推送仍需要 clawhub_token。
  • 請保留 clawhub_token，以供首次發布、不受信任的套件或緊急發布使用。
  • 工作流程會將 JSON 結果上傳為成品，並將其公開為工作流程輸出。

package trusted-publisher get <name>

  • 顯示套件的 GitHub Actions 受信任發布者設定。
  • 設定完成後，請使用此命令確認儲存庫、工作流程檔案名稱 以及選用的環境固定設定。
  • 旗標：
    • --json：機器可讀取的輸出。

範例：

bash
clawhub package trusted-publisher get @openclaw/example-plugin

package trusted-publisher set <name>

  • 為現有套件附加或取代 GitHub Actions 受信任發布者設定。
  • 必須先透過一般手動或權杖驗證的 clawhub package publish 建立套件。
  • 設定完成後，未來受支援的 GitHub Actions 發布即可使用 OIDC／受信任發布，而不需要長效 ClawHub 權杖。
  • --repository <repo> 必須為 owner/repo。
  • --workflow-filename <file> 必須符合 .github/workflows/ 中的工作流程檔案名稱。
  • --environment <name> 是選用項目。設定後，OIDC 宣告中的 GitHub Actions 環境必須完全相符。
  • 執行此命令時，ClawHub 會驗證設定的 GitHub 儲存庫。 公開儲存庫可透過公開 GitHub 中繼資料驗證。私有 儲存庫需要 ClawHub 擁有該儲存庫的 GitHub 存取權，例如 透過未來的 ClawHub GitHub App 安裝或其他已授權的 GitHub 整合。
  • 旗標：
    • --repository <repo>：GitHub 儲存庫，例如 openclaw/example-plugin。
    • --workflow-filename <file>：工作流程檔案名稱，例如 package-publish.yml。
    • --environment <name>：選用的完全相符 GitHub Actions 環境。
    • --json：機器可讀取的輸出。

範例：

bash
clawhub package trusted-publisher set @openclaw/example-plugin \  --repository openclaw/example-plugin \  --workflow-filename package-publish.yml \  --environment release

package trusted-publisher delete <name>

  • 從套件移除受信任發布者設定。
  • 如果需要停用或重新建立工作流程、儲存庫或環境固定設定，請將此命令用於復原。
  • 在再次設定前，未來的實際發布必須使用一般驗證發布。
  • 旗標：
    • --json：機器可讀取的輸出。

範例：

bash
clawhub package trusted-publisher delete @openclaw/example-plugin

安裝遙測

  • 登入後執行 clawhub install <slug> 時傳送，除非已設定 CLAWHUB_DISABLE_TELEMETRY=1。
  • 回報採盡力而為。即使遙測無法使用，安裝命令也不會失敗。
  • 詳細資訊：docs/telemetry.md。
Was this useful?
On this page

On this page