cc-haha/docs/start/troubleshooting.md

title	nav_title	description	order
装不上 / 打不开 / 连不上	排查问题	按症状查：安装失败、启动白屏、模型 401、会话卡住、端口冲突、手机连不上。	4

装不上 / 打不开 / 连不上

按你看到的现象往下找。每条都是「现象 → 为什么 → 怎么办」。

先确认一件事：你用的是 GitHub Releases 上的最新正式版。旧版本上的问题很多已经修掉了。

装不上

macOS 提示「已损坏，无法打开」

为什么 — 文件没坏。macOS 会给从网上下载的包打一个隔离标记，遇到没有 Apple 签名的应用就拒绝启动，而报错文案写成了「已损坏」，非常有误导性。

怎么办 — 从同一个 Release 下载 install-macos-unsigned.sh，放到和 DMG 同一个文件夹，执行 bash install-macos-unsigned.sh；或者应用已经在「应用程序」里的话，直接执行 xattr -dr com.apple.quarantine "/Applications/Claude Code Haha.app"。完整说明见 下载与安装。

Windows 弹出 SmartScreen 蓝屏

为什么 — 未签名的安装包会被 SmartScreen 拦一道。

怎么办 — 确认文件确实来自本仓库 Release，点「更多信息」→「仍要运行」。文件名或来源对不上就别绕过。

Windows 安装器说「程序仍在运行」

为什么 — 旧版本的主进程、sidecar、内嵌终端或 IM adapter 还没退干净，安装器不敢覆盖。

怎么办

1. 退出主窗口，检查系统托盘里的图标也一并退出。
2. 等几秒让后台进程结束。
3. 还不行就去任务管理器里找 Claude Code Haha 相关进程手动结束。
4. 重新双击安装器。不要选「以管理员身份运行」，也不要先手动删掉旧安装目录里的数据。

Linux AppImage 双击没反应

为什么 — 多半是没给执行权限，或者系统缺 FUSE。

怎么办 — 先 chmod +x <文件名>.AppImage。仍报 FUSE 相关错误的话，Ubuntu 22.04 及更早装 libfuse2，24.04 及以后装 libfuse2t64。

打不开

双击后什么都没发生

为什么 — 最常见的是下错了 CPU 架构：Apple Silicon 的机器装了 mac-x64，或者 ARM64 的 Windows 装了 win-x64。

怎么办 — 对照 下载与安装 重新确认架构，下对的那个包重装。旧版进程还在跑的话也会互相打架，先全部退掉。

窗口打开了，但一片白

为什么 — 界面资源没加载出来，通常是升级过程中断，或者显卡驱动异常导致渲染进程起不来。

怎么办

1. 完全退出应用（不是关窗口），重新打开。
2. 还白就重装同一个版本的安装包覆盖一次。会话和配置存在 ~/.claude 下，不在应用目录里，覆盖安装不会丢。
3. 仍然白屏，说明卡在启动阶段。带上系统版本、CPU 架构、安装包文件名去 GitHub Issues 提一条。

:::warning 任何情况下都不要为了排错去删 ~/.claude。你的会话、服务商配置、技能、Agent、记忆全在那里，删了找不回来。 :::

升级后会话列表空了

为什么 — 大概率不是数据没了。侧边栏的会话列表走的是本地 SQLite 索引，那只是一份可重建的派生数据，原始会话仍以 JSON / JSONL 文件存着。索引正在重建时列表会暂时是空的。

怎么办 — 打开「设置 → 诊断 → 本地索引」，看它是不是正在构建，等它跑完。有降级来源或错误代码就点「重建本地索引」——这个操作只重建索引，不碰原始对话和设置。

模型 401 或连不通

提示 401 / 403 / API Key invalid

为什么 — 认证方式和服务商对不上，或者密钥本身有问题。

怎么办 — 打开「设置 → 服务商」，编辑那条配置，按顺序核对：

1. 接口地址是不是 API 根地址，而不是官网地址。
2. 认证变量选对没有。第三方 Anthropic 兼容服务基本都用 Bearer Token (ANTHROPIC_AUTH_TOKEN)，只有直连 Anthropic 官方才用 API Key (ANTHROPIC_API_KEY)。拿不准就两个都试一遍。
3. API 密钥前后有没有粘进空格，或者已经过期、额度用完。
4. 保存后点「测试」，通过再新建一条会话验证。

不要为了改这些去手动编辑 settings.json，应用里改完会自动同步。

提示 404 或「模型不存在」

为什么 — 接口路径写重了，或者模型 ID 用了别的平台的别名。

怎么办 — 检查接口地址里的路径有没有重复（地址里已经有 /anthropic 就别再补 /v1/messages）。模型 ID 用服务商控制台里给的那个原样字符串，别用产品名。

本地模型（LM Studio / Ollama）接口地址后面不要加 /v1，这是最常见的 404 来源。

报 400，或提示不支持某个参数

为什么 — 第三方通道拒绝了 beta 形态的 API 请求，或者模型不支持 tool_reference。

怎么办 — 编辑这个服务商，勾上「关闭实验性 Beta 头」；还不行就把「启用 Tool Search」关掉。这两个开关就是为这类通道准备的。

登录成功，但模型选择器里没有想要的模型

为什么 — 能看到哪些模型由你的账号权限、地区和套餐决定，不是应用决定的。

怎么办 — 先刷新服务商状态，重新打开模型选择器。仍然没有，以服务商官方控制台显示的可用模型为准。

一直输出文字，就是不动手改文件

为什么 — 这个模型的工具调用能力撑不住 Agent 工作流。小参数量的本地模型经常这样。

怎么办 — 换一个明确支持 function calling 的模型试试。同时确认当前权限模式不是「计划模式」——计划模式本来就不允许它碰文件。

官方账号 OAuth 授权卡住

为什么 — 授权回调落不回正在运行的应用。

怎么办 — 授权全程别关掉应用；让系统浏览器打开授权页，用同一个账号完成；把代理和拦截类浏览器扩展先关掉；系统时间不准也会让授权失败。浏览器没自动打开就点「复制授权链接」自己粘过去。

会话卡住

一直转圈，不出结果

为什么 — 可能是网络抖动，也可能是上游没有正常结束这次响应。

怎么办 — 按顺序来，别一上来就重启：

1. 等十几秒，看是不是短暂波动。
2. 点停止，或按 Cmd/Ctrl + .。
3. 打开活动面板，看后台任务和子 Agent 的真实状态——主对话没动静不代表后台也停了。
4. 切到别的会话再切回来，排除界面刷新问题。
5. 以上都不行，完全退出应用重开。
6. 去「设置 → 诊断」复制错误摘要。

会话跑着时权限模式选不了

为什么 — 这是故意锁的。跑到一半改权限会让界面显示和实际生效的权限对不上。

怎么办 — 等这一轮结束，或者先停止，再切换。

拒绝了编辑，但不确定文件到底改没改

为什么 — 被拒绝的写入不会落盘，但界面展示和磁盘状态是两回事。

怎么办 — 交付前自己跑一遍 git status 和 git diff。磁盘和 Git 才是最终事实源。

端口冲突

现象 — H5 打不开，或者应用启动后本地服务没起来。

为什么 — 本地服务默认用 3456 端口。这个端口被别的程序占了，服务就换端口或者起不来。

怎么办 — 打开「设置 → H5 访问」，看「当前端口」显示的是多少——它可能已经自动换到别的端口了，而你手上的旧二维码还指向老端口。需要一个稳定的地址（比如做书签或配反向代理），在同一页填「固定端口」，范围 1024–65535，改完重启应用生效。

手机连不上

现象 — 扫码后页面打不开，或者提示未授权。

为什么 — 地址、端口、令牌、网络四件事任何一件对不上都连不上。

怎么办 — 打开「设置 → H5 访问」逐项核对：

1. H5 访问的开关是不是真的打开了。
2. 「访问主机 / IP」显示的地址，是不是电脑当前网卡的地址（换了 Wi-Fi 就会变）。
3. 二维码里的端口，和「当前端口」是不是同一个。
4. 手机和电脑在不在同一个局域网里。
5. 系统防火墙有没有放行这个端口。
6. 令牌有没有被重新生成过——一旦重新生成，旧二维码立刻失效。

改过固定端口一定要重启应用。完整部署方式和安全边界见 手机与 IM 接力。

手机锁屏了，正在跑的任务会断吗

不会。短暂断连不影响正在执行的任务，它会在后台跑完，重连之后你能看到结果。只有当任务已经空闲、且没有任何客户端连着时，才会按断连保活设置停掉对应的 CLI（默认 30 秒）。

但这不等于永远不会断——系统休眠、进程退出、代理故障、服务重启，照样会终止连接。

IM 已经扫码绑定了，联系人还是聊不了

扫码只是把平台账号绑上来，不等于授权了所有联系人。对方还需要发一次桌面端生成的一次性配对码，或者被你加进允许列表。两者都为空时默认拒绝。各平台差异见 IM 接入。

Computer Use 没反应

现象 — 让它点屏幕、控制别的应用，它说做不到，或者干脆没动静。

为什么 — Computer Use 有一串前置条件，任何一环没过它都不干活。它只支持 macOS 和 Windows，Linux 上没有这个能力。

怎么办 — 打开「设置 → Computer Use」，从上往下看哪一项是红的：

1. 顶部的启用开关是不是打开了（关着的话新会话根本不会注入这套工具）。
2. Python 3 检测通过了没有。没装就先装，或者在「Python 解释器路径」里指定一个已有的（conda、pyenv 都行）。
3. 虚拟环境和依赖包是不是「已就绪 / 已安装」，没有就点「安装环境」。
4. macOS 上还要「辅助功能权限」和「屏幕录制权限」两项都显示「已授权」——去「系统设置 → 隐私与安全性」里开。
5. 授权之后必须重启 Claude Code Haha，系统权限对已经在跑的进程不生效。
6. 要控制的目标应用有没有在「已授权应用」列表里。

完整说明见 Computer Use。

还是没解决

去「设置 → 诊断」：

1. 点「复制 Issue 报告」，先拿到一份结构化的现场信息。
2. 到 GitHub Issues 搜一下有没有人报过同样的问题，没有再新建。
3. 光靠报告定位不了的话，再点「导出诊断包」附上。

一并提供这些能大幅提高解决速度：应用版本、操作系统和 CPU 架构、安装包文件名、用的哪类服务商（不要贴 API 密钥）、最短复现步骤、完整错误文字、问题出在桌面端还是手机端还是 CLI。

:::warning 诊断报告会尽力省略聊天内容、文件正文、完整环境变量和 API 密钥，但仍可能带上本机路径、服务商主机名这类信息。发出去之前自己看一遍。 :::