cc-haha/docs/desktop/05-FAQ.md

Desktop 常见问题

先确认你使用的是 GitHub Releases 中的最新正式版本。下面的排查顺序尽量避免直接修改 ~/.claude、删除会话或重装应用。

服务商与模型

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

• 已有 Claude.ai、ChatGPT 或 Grok 账号，并希望使用官方账号授权：选择对应的官方登录。
• 已有 API Key、企业网关、本地模型或第三方兼容服务：选择内置预设或 Custom。
• 服务只支持 OpenAI 协议：在桌面端选择 OpenAI Chat Completions 或 OpenAI Responses，不必先假设必须部署 LiteLLM。
• 从源码使用 CLI 环境变量：参见第三方模型指南，不要把 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 访问。

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

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

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

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

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

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

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

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

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

两者都为空时默认拒绝访问。五个平台的差异见IM 接入总览。

Agent、技能与宠物

桌面宠物的完整开启与导入步骤见桌面宠物指南。

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

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

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

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

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

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

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

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

不能。透明 PNG / WebP 单图只会在本地添加呼吸、漂浮和状态等轻动画。完整逐帧动作需要符合规格的 v2 动画图集；AI 生成路径需要单独的图片生成服务，不会调用当前聊天模型。

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

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

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

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

宠物为什么不动？

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

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

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

逐项检查：

• 单图必须是 PNG 或 WebP，单边为 32–4096 像素，文件不超过 8 MB，总像素不超过 16,777,216。
• v2 动画图集必须恰好为 1536×2288 像素，并符合 8 列 × 11 行的帧布局。
• 宠物 ID 最多 73 个字符，只能包含小写字母、数字和单个连字符，且不能与已有 ID 重复。
• 显示名称与描述不能为空。

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

关闭宠物后如何恢复？

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

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

如何删除自定义宠物？

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

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

为什么“AI 生成完整动画”不可用？

该入口需要单独配置图片生成服务，当前聊天模型不会被拿来生成宠物图片或动作帧。未配置对应服务时，入口会明确显示不可用。

现在可以使用推荐的单图轻动画，或导入已经制作好的 v2 动画图集。

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

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

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

诊断与求助

应该提供哪些信息？

在「设置 → 诊断」中：

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

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

Doctor 会修改什么？

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

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