# Desktop 常见问题

先确认你使用的是 [GitHub Releases](https://github.com/NanmiCoder/cc-haha/releases) 中的最新正式版本。下面的排查顺序尽量避免直接修改 `~/.claude`、删除会话或重装应用。

## 服务商与模型

### 应该选择官方登录还是 API Provider？

- 已有 Claude.ai、ChatGPT 或 Grok 账号，并希望使用官方账号授权：选择对应的官方登录。
- 已有 API Key、企业网关、本地模型或第三方兼容服务：选择内置预设或 Custom。
- 服务只支持 OpenAI 协议：在桌面端选择 OpenAI Chat Completions 或 OpenAI Responses，不必先假设必须部署 LiteLLM。
- 从源码使用 CLI 环境变量：参见[第三方模型指南](../guide/third-party-models.md)，不要把 CLI 配置步骤和桌面 Provider 设置混在一起。

### Provider 返回 401 或 “API Key invalid” 怎么办？

不要先编辑原始 `settings.json`。在「设置 → 服务商」依次检查：

1. Base URL 是否是 API 根地址，而不是网页地址。
2. API 格式是否与服务商一致。
3. 鉴权方式是否正确：
   - `x-api-key` 常用于 Anthropic 官方 API。
   - `Authorization: Bearer` 常用于第三方兼容服务。
   - OpenRouter / Ollama 等场景可能需要避免回退到 Anthropic API Key。
4. API Key 前后是否包含空格或已失效。
5. 当前模型 ID 是否确实存在。
6. 保存后重新测试连接，并新建一条测试会话。

Kimi Code 当前预设使用 K3 Coding API 和 API Key 鉴权。旧文档中手动把某个环境变量替换为另一个变量的修复方法，针对的是历史版本，不应作为当前首选步骤。

### 登录成功，为什么看不到文档里提到的模型？

模型目录受账号权限、地区、套餐和服务商动态配置影响。桌面端能识别 GPT、Grok 以及 Fable、Opus、Sonnet、Haiku 等模型，不代表每个账号都能调用全部条目。

先刷新服务商状态，再重新打开模型选择器。仍缺失时，请以账号官方控制台或 Provider 返回结果为准。

### 为什么 effort 被降低或没有效果？

`low`、`medium`、`high`、`xhigh`、`max` 不是所有模型都支持。运行时会按模型能力规范化；某些组合会向下调整或忽略，required/adaptive thinking 也可能覆盖通用选择。

逐 Agent effort 同样遵守这个边界。它不是固定的 thinking token 预算。

## 会话、任务与权限

### 对话一直显示运行中，应该直接重启吗？

先按顺序尝试：

1. 等待短暂网络波动恢复。
2. 点击停止，或按 `Ctrl/Cmd + .`。
3. 查看活动面板中 Task、后台任务和 SubAgent 的实际状态。
4. 切换到其他会话再返回，排除单次界面刷新问题。
5. 完全退出并重新打开应用。
6. 在「设置 → 诊断」复制错误摘要。

当前版本会持久化完成、失败和停止等终态，但永不完成的网络握手或持续异常的 sidecar 仍可能需要人工重启。不要只根据一个加载动画判断服务端状态。

### 为什么运行中不能切换权限模式？

活跃轮次期间切换会造成界面选择与实际工具权限不一致，因此选择器会锁定。先等待当前轮结束或停止，再切换模式。

### Auto 与“跳过全部”有什么区别？

Auto 会让 Claude 审查工具调用，并执行其认为安全的操作；它会减少审批，但不能保证绝对安全。

“跳过全部”不会进行这种逐项权限检查，风险更高。二者都不适合包含生产密钥、个人资料或不可恢复数据的陌生目录。

### 拒绝 Write/Edit 后为什么要检查 Git Diff？

当前版本会尽量避免把未落盘的拒绝操作显示成变更，但磁盘和 Git 才是最终事实源。遇到中断、外部编辑器并发修改或工具异常时，交付前仍应检查真实 Diff。

## 搜索、工作区与附件

### 会话搜索、`Ctrl/Cmd + F` 和文件搜索有什么区别？

| 入口 | 搜索范围 |
|------|----------|
| 侧边栏搜索 | 历史会话 |
| `Ctrl/Cmd + F` | 当前页面或当前长对话 |
| `@` 菜单 | 引用工作区文件 |
| 右侧工作区搜索 | 整个工作目录，包括未展开的目录 |

正式桌面安装包已内置 ripgrep。源码开发环境的依赖问题不等于正式安装包也缺少文件搜索。

### 历史会话突然不在列表里了，数据丢了吗？

不一定。本地 SQLite 只是一份可重建的派生索引，原始会话仍以 JSON / JSONL 文件为准。

1. 打开「设置 → 诊断」。
2. 查看本地索引是否正在构建或处于降级状态。
3. 先等待后台构建完成。
4. 必要时点击「重建本地索引」。

重建索引不会删除原始对话和设置。不要为了恢复列表先删除 `~/.claude`。

### 附件恢复后只看到路径，或无法打开怎么办？

当前版本会恢复已经提交的文件、目录、图片和 PDF 上下文。若打开失败：

- 检查原文件是否移动、重命名或删除。
- 检查当前系统是否有可打开该格式的应用。
- Windows 路径与另一个系统上的路径不能自动互换。
- 使用「打开方式」选择合适的本地应用。

历史消息存在不代表原始文件仍在磁盘。

### Diff 中如何评论连续多行？

先点击起始行，再按住 `Shift` 选择同一侧的结束行。评论会带着文件路径、行号和引用回到聊天输入框。

不要跨旧文件侧和新文件侧连续选择；折叠或切换文件后需要重新确认当前选区。

## 安装与更新

### Windows 安装器说应用仍在运行

1. 退出主窗口。
2. 检查系统托盘并退出应用。
3. 等待 sidecar、终端和 IM adapter 结束。
4. 必要时在任务管理器中结束相关进程。
5. 重新双击安装器，以当前用户运行。

不要主动选择「以管理员身份运行」，也不要先删除旧安装目录中的数据。

### Windows 显示 SmartScreen

Windows 签名不是当前 Release 的强制发布条件。确认安装包来自本仓库官方 Release 后，未签名版本可选择「更多信息 → 仍要运行」。

来源不明、文件名或校验异常时不要绕过 SmartScreen。

### 覆盖升级会删除 Provider、会话或 Skills 吗？

正常用户目录中的 Provider、会话、Skills、Agents、记忆和自定义宠物应被保留。Windows 安装器也会保护旧安装目录中可确认归属的历史数据。

但安装器恢复不是备份。遇到来源歧义、进程占用或复制失败时，它会中止；重要数据仍应自行备份。

### 更新后会话列表为空

先检查本地索引，不要立即重装：

1. 打开「设置 → 诊断」。
2. 等待索引构建。
3. 查看降级来源与错误代码。
4. 重建派生索引。
5. 若仍失败，导出诊断包后求助。

## H5 与 IM

### 手机扫码后打不开 H5

检查：

1. 手机和电脑是否在同一可信网络，或反向代理是否可达。
2. H5 页面显示的“访问主机 / IP”是否仍属于电脑当前网卡。
3. 二维码中的端口是否等于“当前端口”。
4. 修改固定端口后是否重启了应用。
5. 防火墙是否允许当前端口。
6. Token 是否被重新生成；重新生成后旧二维码立即失效。

源码同源部署默认可使用 `http://<主机>:3456/`。详细步骤见[H5 访问](./06-h5-access.md)。

### 手机锁屏会停止正在运行的任务吗？

短暂断连不会直接停止正在执行的任务；它会在后台完成，重连后可以看到结果。只有任务已经空闲且无人连接时，才会按“断连保活”设置停止对应 CLI，默认值为 30 秒。

这不等于移动网络下永远不会断开。系统休眠、进程退出、代理故障或服务重启仍会终止连接。

### H5 可以直接暴露到公网吗？

不建议裸露公网。H5 不是公开 SaaS，也没有多租户账号体系。拿到有效 Token 的设备可以访问桌面服务暴露的核心能力。

需要远程访问时，应使用自己的 HTTPS 反向代理或 VPN，保留正确的 Host / 代理头，并保护 Token。

### IM 已扫码，为什么联系人仍不能聊天？

扫码只绑定微信、钉钉或 WhatsApp 的平台账号。实际 IM 用户仍需：

- 发送桌面端生成的一次性配对码；或
- 被加入允许列表。

两者都为空时默认拒绝访问。五个平台的差异见[IM 接入总览](../im/index.md)。

## Agent、技能与宠物

桌面宠物的完整开启与导入步骤见[桌面宠物指南](./pets.md)。

### Agent 已保存，但当前会话没有使用新配置

保存 Agent 文件和刷新运行时是两个步骤。刷新失败时文件仍可能已经保存，桌面端会给出非阻塞警告。

先打开 Agent 详情确认生效来源和覆盖关系，再新建会话或重启应用。项目 Agent 需要当前会话绑定正确的项目目录。

### 为什么内置或插件 Agent 不能编辑？

桌面端只负责用户级和项目级 Agent 文件。内置、插件、策略与 CLI 参数来源保持只读，避免误改不属于桌面端的事实源。

### 技能市场的技能都安全吗？

不是。市场会展示来源、安装状态和安全提示，但第三方技能仍可能包含脚本、依赖或外部访问。安装前应阅读内容并确认来源。

### 单张图片能生成完整宠物动画吗？

不能。透明 PNG / WebP 单图只会在本地添加呼吸、漂浮和状态等轻动画。完整逐帧动作需要一张 8 列 × 9 行的动作表——可以用「用 AI 画一只会跑会跳的」路径，按弹窗里的提示词让任意画图 AI 生成，再选进来；导入时会自动切格对齐。

宠物只运行在 Electron 桌面端，不显示在 H5。

### 已经打开任务面板，为什么看不到任务？

任务面板只列出正在运行、等待处理或失败等非空闲会话。所有任务都已完成或处于空闲状态时，面板会自动隐藏；「显示进行中的任务区域」不会让历史任务一直常驻。

先确认「设置 → 宠物 → 显示进行中的任务区域」已开启，再启动一条真实任务。状态会定时刷新；等待几秒仍未出现时，关闭并重新显示宠物。

### 宠物为什么不动？

先确认「设置 → 宠物 → 播放动画」已开启。系统启用“减少动态效果”时，应用也会尊重该设置并降低或关闭动画。

单图自定义宠物只有呼吸、漂浮和任务状态等轻动画；它不会像 v2 图集宠物一样播放完整逐帧动作。鼠标悬停或单击宠物可以触发跳跃、挥手等互动。

### 为什么自定义宠物导入失败？

逐项检查：

- 单图必须是 PNG 或 WebP，单边为 32–4096 像素，文件不超过 8 MB，总像素不超过 16,777,216。
- 动作表必须是 8 列 × 9 行的布局；尺寸不必精确，导入时会自动切格缩放。已经是 1536×2288 的成品图集会原样保留。
- 动作表必须有透明背景。白底或彩底会被拒绝，因为宠物会在桌面上显示成一个方块。
- 宠物 ID 最多 73 个字符，只能包含小写字母、数字和单个连字符，且不能与已有 ID 重复。
- 显示名称与描述不能为空。

导入只读取你在系统文件选择器中确认的本地文件。失败后不要直接编辑清单文件，先按提示修正源图片，再重新创建。

### 关闭宠物后如何恢复？

右键宠物并选择关闭，或关闭「设置 → 宠物 → 显示桌面宠物」，都会保存关闭状态。需要恢复时，重新打开这个开关即可；不需要重装应用。

如果宠物曾被拖到另一块屏幕，关闭并重新显示时，保存的位置会被限制在当前可见工作区。

### 如何删除自定义宠物？

当前版本没有“删除”按钮。先切换到一个内置宠物，再点击「设置 → 宠物 → 打开文件夹」，删除目标自定义宠物对应的文件夹，最后返回设置点击「刷新」。

只删除 `${CLAUDE_CONFIG_DIR:-~/.claude}/cc-haha/pets` 下确认属于该宠物的目录，不要删除整个 `~/.claude`。内置宠物随应用提供，不在这里删除。

### 「用 AI 画一只会跑会跳的」会消耗我的对话额度吗？

不会。这条路径不调用当前会话选择的聊天模型，应用也不会替你请求任何图片生成服务。它给你的是一段提示词和一张对照模板，图由你自己在任意画图工具里生成，再把文件选进来；整理和导入都在本机完成。

### 能在宠物窗口里批准权限或直接回复吗？

不能。宠物窗口用于展示任务状态、切回主窗口和定位对应会话，不提供消息输入框，也不会批准文件、命令或 Computer Use 权限。

看到“等待你处理”时，点击对应任务返回主窗口，再在完整会话界面中阅读上下文、批准或拒绝权限并继续回复。宠物不会绕过当前权限模式。

## 诊断与求助

### 应该提供哪些信息？

在「设置 → 诊断」中：

1. 刷新并记录最近事件 ID。
2. 复制错误摘要或 Issue 报告。
3. 需要时导出诊断包。
4. 补充应用版本、操作系统、CPU 架构、服务商类型和最短复现步骤。
5. 明确问题是安装、界面、模型请求、H5、IM 还是某个 Agent 工作流。

诊断报告会尽力省略聊天、文件正文、完整环境变量和 API Key，但分享前仍需人工检查是否含私密路径、账号信息或其他元数据。

### Doctor 会修改什么？

Doctor 默认检查受保护的用户与项目状态。只有你明确确认“重置安全 UI 状态”时，它才会移除允许重新生成的桌面界面键。

聊天历史、模型配置、Skills、MCP、IM 和 OAuth 不属于自动修复范围。不要根据旧教程手动删除这些目录。