• 简体中文

    • 解决 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。

    未成功时

    • 同一个处理方法连续失败两次后，请停止操作并联系支持。
    • 付费或上传结果不确定时，先查询现有记录，不要重新提交。