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

# 装不上 / 打不开 / 连不上

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

先确认一件事：你用的是 [GitHub Releases](https://github.com/NanmiCoder/cc-haha/releases/latest) 上的最新正式版。旧版本上的问题很多已经修掉了。

## 装不上

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

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

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

### 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`。

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

### 窗口打开了，但一片白

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

**怎么办**

1. 完全退出应用（不是关窗口），重新打开。
2. 还白就重装同一个版本的安装包覆盖一次。会话和配置存在 `~/.claude` 下，不在应用目录里，覆盖安装不会丢。
3. 仍然白屏，说明卡在启动阶段。带上系统版本、CPU 架构、安装包文件名去 [GitHub Issues](https://github.com/NanmiCoder/cc-haha/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 接力](../desktop/remote.md)。

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

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

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

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

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

## 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](../desktop/computer-use.md)。

## 还是没解决

去「设置 → 诊断」：

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

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

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