mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-08-01 16:43:37 +08:00
154 lines
7.0 KiB
Markdown
154 lines
7.0 KiB
Markdown
# 常见问题与求助
|
||
|
||
## 遇到问题时，怎样最快获得帮助？
|
||
|
||
先确认正在使用 [GitHub Releases Latest](https://github.com/NanmiCoder/cc-haha/releases/latest)，并重试一次能稳定复现问题的最短步骤。
|
||
|
||
如果 Desktop 仍能打开：
|
||
|
||
1. 进入 **设置 → 诊断**。
|
||
2. 点击 **复制 Issue 报告**。
|
||
3. 在 [GitHub Issues](https://github.com/NanmiCoder/cc-haha/issues) 搜索相同问题；没有重复 Issue 时再新建。
|
||
4. 粘贴报告，并补充复现步骤、预期结果和实际结果。
|
||
|
||
如果仅凭报告无法定位，可以再点击 **导出诊断包**。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，依次检查：
|
||
|
||
1. Base URL 是否是服务商要求的 API 根地址，没有多写或漏写路径。
|
||
2. API 格式是否与服务商真实接口一致。
|
||
3. 认证方式是否正确：部分 Anthropic 兼容服务使用 Bearer Token，官方 Anthropic API 使用 `x-api-key`。
|
||
4. 主模型 ID 是否真实存在，并且当前 Key 有权访问。
|
||
5. 点击 **测试连接**，先处理第一步连通失败；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](https://github.com/NanmiCoder/cc-haha/releases/latest)，并选择了正确的 Intel 或 Apple Silicon 架构。正式签名和公证的版本通常只显示标准的下载来源确认。
|
||
|
||
旧版、draft 或临时 unsigned 包可能需要额外放行，见 [Desktop 安装指南](/desktop/04-installation#macos)。不要从不明镜像下载后绕过系统安全提示。
|
||
|
||
### Windows 出现 SmartScreen
|
||
|
||
确认安装包来自官方 Release。未签名的 Windows 安装包可能显示 SmartScreen，可以展开“更多信息”核对发布者和文件名后再决定是否运行。
|
||
|
||
覆盖升级前先完全退出 Claude Code Haha。如果安装器提示进程仍在运行，关闭对应窗口和后台进程后重试，不要先删除用户配置目录。
|
||
|
||
### Linux AppImage 无法启动
|
||
|
||
先赋予执行权限：
|
||
|
||
```bash
|
||
chmod +x Claude-Code-Haha-<版本>-linux-<架构>.AppImage
|
||
```
|
||
|
||
部分发行版还需要 FUSE。不同发行版的安装方式见 [Desktop 安装指南](/desktop/04-installation#linux)。
|
||
|
||
## H5 访问
|
||
|
||
### 手机或另一台电脑无法连接 H5
|
||
|
||
依次确认：
|
||
|
||
1. Desktop 的 **H5 访问**已经开启。
|
||
2. 使用设置页当前显示或二维码生成的 Server URL，不要复用旧局域网 IP。
|
||
3. 客户端填写了当前 H5 Token。
|
||
4. 两台设备位于可互通的网络，系统防火墙允许当前端口。
|
||
5. 经过反向代理时，已正确转发 HTTP 和 WebSocket，并配置允许的来源。
|
||
|
||
H5 是当前 Desktop 服务的远程入口，不等同于完整 Desktop。终端、原生预览、宠物窗口和部分系统能力只能在桌面应用中使用。
|
||
|
||
详细部署与安全边界见 [H5 访问](/desktop/06-h5-access)。
|
||
|
||
## 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 版本：
|
||
|
||
```bash
|
||
bun --version
|
||
bun install
|
||
./bin/claude-haha --help
|
||
```
|
||
|
||
如果提示缺少 `bun:bundle` 等 Bun 内置模块，先升级 Bun。完整安装路径见 [3 分钟上手](./quick-start.md#路径二从源码运行-cli)，参数说明见 [CLI 参考](./cli-reference.md)。
|