• 繁體中文（台灣）

    • 解決 HolyCrab CLI 常見問題

    先在下表找到相同或相近的報錯。向他人求助前，請遮住 API Key 和私人資訊。

    安裝問題

    故障現象可能原因處理方法
    缺少 Python 或低於 3.10當前 Python 無法啟動 CLI。安裝 Python 3.12，重開終端機，再執行安裝器。
    找不到 holycrab 命令當前終端機沒載入使用者 PATH，或安裝中斷。在新終端機執行 holycrab doctor --json（各系統通用）。仍找不到命令時，使用下方按系統列出的修復命令。
    PowerShell 提示找不到 sh把 macOS/Linux 命令貼上到了 Windows。開啟 Windows 安裝指南，複製“安裝 HolyCrab”步驟中的命令，在 PowerShell 執行。這裡缺少的是 Unix Shell sh，不需要安裝 SSH。
    doctor 提示檔案缺少或變化受管理檔案損壞、缺失或版本不一致。執行下方對應系統的安裝命令修復，再執行 holycrab doctor --json。

    找不到 holycrab 命令時

    1. 開啟新終端機並檢查

    Windows 開啟新的 PowerShell 視窗；macOS 或 Linux 開啟新的終端機視窗。執行下面的命令，三個系統通用。

    holycrab doctor --json

    2. 仍找不到命令時，重新安裝

    只有終端機仍提示找不到 holycrab 時，才執行下方與系統匹配的官方安裝命令。安裝完成後，再執行 holycrab doctor --json；安裝失敗時，按對應系統的安裝指南排查。

    詳細步驟：Windows 安裝指南 · macOS / Linux 安裝指南。

    Windows PowerShell

    irm https://holycrab.ai/cli/install.ps1 | iex

    macOS / Linux (Bash / Zsh)

    curl -fsSL https://holycrab.ai/cli/install.sh | sh && export PATH="$HOME/.local/bin:$PATH"

    API Key 和 Agent 問題

    故障現象可能原因處理方法
    API Key 無效複製不完整、已撤銷或來自錯誤帳號。在 API Key 頁面確認有效，再執行 holycrab setup。
    環境變數覆蓋提示臨時 Key 設定優先於本機儲存的 Key。不要把兩份 Key 發到聊天；按 doctor 顯示的系統指令清理。
    Codex 找不到 HolyCrabCodex 在安裝前啟動，或本機連線仍指向舊路徑。重新執行安裝器一次，然後新開一個 Codex 任務。

    任務和素材問題

    在手機上左右滑動表格，可檢視完整處理方法。

    故障現象含義下一步
    素材 FAILED線上處理拒絕檔案。看公開錯誤，修復檔案；新上傳前再次詢問。
    任務等待超時任務可能仍在處理。儲存任務 ID，繼續等待同一個任務。
    授權等待超時本人尚未進入最終狀態。儲存授權 ID，不建立新的。
    生成或上傳結果 unknown線上可能已經執行。先查已有記錄，絕不重複同一付費或上傳操作。

    安全檢查命令

    檢視不會產生費用的診斷命令

    這些命令只檢查本機狀態或已有記錄，不會建立付費生成任務。

    holycrab --version
holycrab doctor --json
holycrab doctor --json --online
    holycrab tasks list
holycrab generate attempts list

    聯絡支援時請提供

    • 電腦系統、CLI 版本、執行的命令和完整報錯。
    • 如已獲得任務或素材編號，可以一併提供；請遮住真人姓名和私密連結。
    • 不要傳送 API Key。

    未成功時

    • 同一個處理方法連續失敗兩次後，請停止操作並聯系支援。
    • 付費或上傳結果不確定時，先查詢現有記錄，不要重新提交。