错误码与排错

CrabCode 常见启动、安装、PATH、登录、App Server、插件、自动化和浏览器问题的排查入口。

先定位层级

CrabCode 是 TUI、GUI、App Server、cron daemon、插件和浏览器自动化共同工作的客户端。排错时先判断卡在哪一层。

现象	所属层级	先看
终端提示 `crabcode: command not found`	安装 / PATH	安装、PATH 与卸载
`crabcode --version` 还是旧版	PATH 顺序 / 多版本残留	安装、PATH 与卸载
`doctor` 提示缺 `git` / `gh`	本机依赖	CLI 参考
GUI 首屏账户服务暂不可用	App Server / 账号状态	GUI 桌面端上手
Work 里没有能力卡	插件 / 技能	GUI Work 板块、插件与技能
自动化页 daemon 不可用	cron daemon	自动化
浏览器拿不到登录态	Chrome 扩展 / browser backend	浏览器自动化
模型报余额、额度或不可用	模型网关 / 账号权益	费用、模型路由

安装与 PATH

最常见的问题是安装成功但当前 shell 找不到命令。

bash

command -v crabcode
crabcode --version
command -v crabcode
crabcode --version

如果没输出，检查真实程序目录：

bash

ls -la "$HOME/.crabcode/bin/crabcode" "$HOME/.local/share/crabcode/crabcode" 2>/dev/null
ls -la "$HOME/.crabcode/bin/crabcode" "$HOME/.local/share/crabcode/crabcode" 2>/dev/null

然后把实际目录加到 PATH。完整 zsh / bash / fish / Windows 步骤见安装、PATH 与卸载。

GUI 与 App Server

桌面端所有真实数据页都通过本机 App Server 读取。如果 GUI 显示账户服务不可用、项目列表为空或页面一直加载：

点 GUI 里的「重试连接」。
关闭并重新打开桌面端。
在终端运行 crabcode doctor。
确认 TUI 可以启动；如果 TUI 都打不开，先修安装/PATH。

GUI 包格式和平台以 /downloads 为准：当前公开 GUI 包是 macOS .dmg 和 Windows x64 setup.exe，Linux 暂以 TUI 为主。

Work 模式

Work 模式的问题通常不是“会话丢了”，而是工作流归属或插件能力没有准备好。

现象	处理
只看到预设工作流，没有能力卡	安装或启用官方插件
点击财务/法律/办公后跳到插件页	正常安装引导，装好后回 Work
自定义技能生成了但没有自定义工作流	技能需启用；如果曾卸载自定义工作流，用 `+` 重新挂载
会话在「未建工作流对话」里	从具体工作流的新建按钮创建，会自动归类

更多见 GUI Work 板块。

自动化与 cron

自动化由本机 crabcode-cron daemon 执行。GUI 自动化页报不可用时：

bash

crabcode cron status
crabcode cron list --json
crabcode cron status
crabcode cron list --json

如果你设置了 CRABCODE_DISABLE_CRON=1，cron 会被禁用。完整命令矩阵见自动化和 CLI 参考。

浏览器自动化

浏览器任务分两类：

模式	排查方向
内置浏览器模式（默认，`crabcode-browser`）	发行包是否自带 `crabcode-browser`（或 `CRABCODE_BROWSER_BINARY` 是否指向可执行文件）、风险动作是否已授权（`CRABCODE_BROWSER_ALLOW_RISKY`）
Chrome 扩展模式	扩展是否加载、native host 是否写入、`CRABCODE_CHROME_EXTENSION_ID` 是否正确

需要真实登录态时用 Chrome 扩展模式。详见浏览器自动化和浏览器扩展安装向导。

什么时候看日志

TUI 可以用调试参数启动：

bash

crabcode --debug
crabcode --debug

调试日志默认写入 CrabCode 配置目录下的 debug 目录；可用 CRABCODE_DEBUG_LOGS_DIR 覆盖。排查前先确认日志目录没有被误删，且当前用户有写权限。