疑難排解
clawhub login 會開啟瀏覽器，但始終無法完成
命令列介面會在瀏覽器登入期間啟動一個短暫運作的本機回呼伺服器。
- 請確認瀏覽器可以連線至
http://127.0.0.1:<port>/callback。 - 如果始終未收到回呼，請檢查本機防火牆、VPN 和 Proxy 規則。
- 在無頭環境中，請在 ClawHub Web UI 建立 API Token，然後執行：
whoami 或 publish 傳回 Unauthorized (401)
- 請使用
clawhub login重新登入。 - 如果你使用自訂設定路徑，請確認
CLAWHUB_CONFIG_PATH指向 包含目前 Token 的檔案。 - 如果你使用 API Token，請確認該 Token 未在 Web UI 中遭撤銷。
搜尋或安裝傳回 Rate limit exceeded (429)
請閱讀回應中的重試資訊：
Retry-After：重試前要等待的秒數。RateLimit-Limit：套用至此請求的限制。RateLimit-Remaining：標頭存在時，你的確切剩餘配額。在429上，此值為0。RateLimit-Reset或X-RateLimit-Reset：重設時間。
透過 Proxy 時搜尋或安裝失敗
命令列介面支援標準 Proxy 變數：HTTPS_PROXY、HTTP_PROXY、https_proxy 和
http_proxy。
搜尋中未顯示某項 Skill
- 如果你知道確切的 slug 或擁有者頁面，請加以檢查。
- 請確認該版本為公開狀態，且未因掃描或審核而遭保留。
- 如果你擁有該 Skill，請登入並檢查它：
發布因缺少必要的中繼資料而失敗
對於 Skills，請檢查SKILL.md frontmatter。應宣告必要的環境變數和
工具，讓使用者與掃描器能夠瞭解該套件。
對於外掛，請檢查 package.json 相容性中繼資料。發布程式碼外掛時，
需要 OpenClaw 相容性欄位，例如 openclaw.compat.pluginApi 和
openclaw.build.openclawVersion。
請先預覽發布承載內容：
發布因 GitHub 擁有者或來源錯誤而失敗
ClawHub 使用 GitHub 身分和來源歸屬，將套件與其 發布者建立關聯。- 請確認你已使用擁有該套件或可發布該套件的 GitHub 帳號登入。
- 請檢查來源 URL 是否公開，或 ClawHub 是否可存取。
- 對於 GitHub 來源，請使用
owner/repo、owner/repo@ref或完整的 GitHub URL。
發布因命名空間已被認領或保留而失敗
如果發布因擁有者代稱、組織命名空間、套件範圍、Skill slug 或套件名稱已被認領或保留而失敗，請先確認你是以符合該命名空間的 擁有者身分發布。對於外掛套件，@example-org/example-plugin 等限定範圍名稱必須以相符的
example-org 擁有者身分發布。
如果你認為你的組織、專案或品牌才是命名空間的正當擁有者，但
無法管理目前的 ClawHub 擁有者，請使用公開且非敏感的證明建立
組織／命名空間認領問題。
如需證明指引，以及瞭解哪些內容不應放入公開 Issue，請參閱
組織與命名空間認領。
sync 顯示找不到 Skills
sync 會尋找包含 SKILL.md 或 skill.md 的資料夾。
請將它指向你要掃描的根目錄：
update 因本機變更而拒絕執行
本機檔案與 ClawHub 已知的任何版本皆不相符。請選擇一種做法：
- 保留本機編輯並略過更新。
- 以已發布的版本覆寫：
- 以新的 slug 或分支版本發布你編輯過的副本。
在 OpenClaw 中安裝外掛失敗
- 請使用明確的 ClawHub 來源：
- 請檢查套件詳細資料頁面的掃描狀態和相容性中繼資料。
- 請確認你的 OpenClaw 版本符合套件所宣告的 相容性範圍。
- 如果套件遭隱藏、保留或封鎖，在擁有者解決問題前， 該套件可能無法安裝。
公開 API 請求失敗
- 請遵守
429重試標頭，並快取公開的清單／搜尋回應。 - 請將使用者連回標準的 ClawHub 項目頁面。
- 請勿在公開 API 介面之外鏡像隱藏、私人、遭保留或因審核而封鎖的內容。