7.0 KiB
常见问题与求助
遇到问题时，怎样最快获得帮助？
先确认正在使用 GitHub Releases Latest，并重试一次能稳定复现问题的最短步骤。
如果 Desktop 仍能打开：
- 进入 设置 → 诊断。
- 点击 复制 Issue 报告。
- 在 GitHub Issues 搜索相同问题；没有重复 Issue 时再新建。
- 粘贴报告，并补充复现步骤、预期结果和实际结果。
如果仅凭报告无法定位，可以再点击 导出诊断包。Issue 报告和诊断包会尽力省略聊天内容、文件内容、完整环境变量和 API Key，但仍可能含有路径、Provider 主机名等私密元数据；分享前必须自行检查。
建议同时提供：
- Claude Code Haha 版本
- 操作系统、CPU 架构和安装包类型
- 使用的 Provider 类型与 API 格式，不要提供 API Key
- 最短复现步骤和完整错误文字
- 问题发生在 Desktop、H5 还是 CLI
如果应用无法启动，提供安装包版本、系统错误截图和启动前最后一个可见操作即可。不要为了排错直接删除或覆盖 ~/.claude。
Provider 与 OAuth
我一定要安装 LiteLLM 才能用 OpenAI 兼容服务吗？
不需要。Desktop 的 Custom Provider 支持：
- Anthropic Messages（原生）
- OpenAI Chat Completions（本地代理转换）
- OpenAI Responses API（本地代理转换）
只有当上游服务使用了应用尚未支持的协议或特殊字段时，才需要考虑 LiteLLM 等外部网关。
自定义 Provider 返回 401 或 API Key invalid
在 设置 → 服务商 中编辑该 Provider，依次检查：
- Base URL 是否是服务商要求的 API 根地址，没有多写或漏写路径。
- API 格式是否与服务商真实接口一致。
- 认证方式是否正确：部分 Anthropic 兼容服务使用 Bearer Token，官方 Anthropic API 使用
x-api-key。 - 主模型 ID 是否真实存在，并且当前 Key 有权访问。
- 点击 测试连接，先处理第一步连通失败；OpenAI 格式还会显示第二步代理转换结果。
不要同时在截图、Issue 或诊断附件中公开 Base URL 查询参数、Token 或 API Key。
Claude、ChatGPT 或 Grok 官方登录没有完成
- 保持 Claude Code Haha 正在运行，不要提前关闭登录页面或应用。
- 允许系统浏览器打开授权页，并完成同一个账号的授权。
- 检查系统时间是否正确，并确认代理、防火墙或浏览器扩展没有阻止服务商页面和本机 OAuth 回调。
- 如果浏览器显示授权成功但应用没有更新，回到 设置 → 服务商 重新发起登录。
仍然失败时，复制 Issue 报告，并注明卡在“未打开浏览器”“授权页报错”还是“授权后未回到应用”。不要分享 OAuth code、access token 或浏览器 Cookie。
测试连接成功，聊天仍然失败
确认当前任务实际选择了刚配置的 Provider 和模型，而不只是把 Provider 保存到了列表中。再检查主模型和角色模型映射是否受该账号支持。
用新任务发送一条最短纯文本消息复测；如果仍失败，在诊断页复制 Issue 报告。连接测试证明接口、认证和基础转换可用，不等于所有模型能力、工具调用和长上下文组合都已验证。
安装与更新
macOS 提示无法验证、已损坏或打不开
优先确认安装包来自 官方 Latest Release，并选择了正确的 Intel 或 Apple Silicon 架构。正式签名和公证的版本通常只显示标准的下载来源确认。
旧版、draft 或临时 unsigned 包可能需要额外放行，见 Desktop 安装指南。不要从不明镜像下载后绕过系统安全提示。
Windows 出现 SmartScreen
确认安装包来自官方 Release。未签名的 Windows 安装包可能显示 SmartScreen，可以展开“更多信息”核对发布者和文件名后再决定是否运行。
覆盖升级前先完全退出 Claude Code Haha。如果安装器提示进程仍在运行，关闭对应窗口和后台进程后重试，不要先删除用户配置目录。
Linux AppImage 无法启动
先赋予执行权限：
chmod +x Claude-Code-Haha-<版本>-linux-<架构>.AppImage
部分发行版还需要 FUSE。不同发行版的安装方式见 Desktop 安装指南。
H5 访问
手机或另一台电脑无法连接 H5
依次确认：
- Desktop 的 H5 访问已经开启。
- 使用设置页当前显示或二维码生成的 Server URL，不要复用旧局域网 IP。
- 客户端填写了当前 H5 Token。
- 两台设备位于可互通的网络，系统防火墙允许当前端口。
- 经过反向代理时，已正确转发 HTTP 和 WebSocket，并配置允许的来源。
H5 是当前 Desktop 服务的远程入口，不等同于完整 Desktop。终端、原生预览、宠物窗口和部分系统能力只能在桌面应用中使用。
详细部署与安全边界见 H5 访问。
Git 分支与 Worktree
创建隔离 Worktree 失败
常见原因包括：
- 所选目录不是 Git 仓库
- 分支不存在，或已被另一个 Worktree 占用
- 当前工作树有未提交修改，无法安全执行预期操作
- 目标 Worktree 路径已存在或不可写
先阅读界面显示的具体错误。可以改用当前工作树、选择其他分支，或在 Git 中安全处理已有改动后重试。不要为了创建 Worktree 自动删除现有目录或丢弃未提交修改。
当前工作树和隔离 Worktree 应该选哪个？
- 当前工作树：适合继续处理当前目录里已经存在的修改。
- 隔离 Worktree：适合并行任务、独立分支，或希望与当前目录改动分开的工作。
如果不确定且当前目录已有重要的未提交修改，先查看 Git 状态并备份，再决定使用哪条路径。
Computer Use
Computer Use 不可用或无法控制应用
先打开 设置 → Computer Use，检查：
- 全局开关已经开启
- Python 环境和依赖检查通过
- macOS 或 Windows 所需的系统权限已经授予
- 目标应用已在允许控制的应用列表中
- 当前会话的权限请求已经明确批准
授予系统权限后，通常需要重新打开 Claude Code Haha 或目标应用。Linux 当前不支持 Computer Use；请不要把 Desktop 安装成功当成 Computer Use 已配置完成。
如果设置页仍显示错误，复制 Issue 报告，并附上设置页状态；不要上传包含其他应用内容的完整屏幕截图。
CLI
bun install 或 CLI 启动失败
确认已经进入仓库根目录，并使用项目支持的 Bun 版本：
bun --version
bun install
./bin/claude-haha --help
如果提示缺少 bun:bundle 等 Bun 内置模块，先升级 Bun。完整安装路径见 3 分钟上手，参数说明见 CLI 参考。