10 KiB
Claude Code Haha Desktop 快速上手
这篇指南从安装后的第一次打开开始，带你完成服务商配置、创建会话、审阅代码和查看后台任务。建议先用「询问权限」完成一轮小任务，再逐步启用 Auto、H5 或 Computer Use。
一、首次启动：先让一个模型可用
打开「设置 → 服务商」。桌面端提供两类接入方式。
官方登录
不想手动填写 API Key 时，可以选择：
- Claude 官方：浏览器登录 Claude.ai。
- ChatGPT 官方：通过 OpenAI OAuth 登录。
- Grok 官方：通过 xAI OAuth 登录。
授权完成后回到桌面端，再从模型选择器中选择账号实际开放的模型。模型目录会随账号和服务端能力变化；文档中出现某个模型名称，不代表所有账号都一定可用。
API 服务商
使用 API Key 时：
- 从内置预设中选择服务商；常用预设随桌面端提供，不依赖临时的远程列表。
- 填写 API Key 和 Base URL。
- 确认 API 格式与鉴权方式：
- Anthropic Messages
- OpenAI Chat Completions
- OpenAI Responses
- 核对主模型及 Haiku、Sonnet、Opus 等角色模型映射。
- 先测试连接，成功后再保存并设为默认服务商。
不在预设中的服务可以使用 Custom。不要把 API Key、OAuth 凭证或完整设置文件贴到公开 Issue。
当前内置能力包括 Claude 官方模型目录、OpenAI GPT-5.6 系列、Grok 官方模型，以及 Kimi Code K3 等预设。它们的上下文、thinking 和 effort 支持以当前服务商返回的能力为准。
二、创建第一条会话
-
点击侧边栏的新建按钮，或按
Ctrl/Cmd + N。 -
选择真实的项目目录。Agent 的文件搜索、Git 状态、Diff 和工具操作都会以它为边界。
-
选择模型、思考强度和权限模式。
-
输入一个结果可验证的小任务，例如：
先阅读这个项目的 README 和 package.json，告诉我本地开发如何启动。不要修改文件。 -
观察流式回复、工具调用和权限请求。需要停止时按
Ctrl/Cmd + .。
每个标签对应一个会话。正在运行、失败和空闲状态会显示在标签或会话列表中；关闭仍在运行的标签前，桌面端会要求确认。
三、选择正确的权限模式
桌面端提供五种会话权限模式。
| 模式 | 行为 | 建议场景 |
|---|---|---|
询问权限 (default) |
工具执行前逐项询问 | 第一次进入项目、陌生仓库、风险不明确 |
接受编辑 (acceptEdits) |
自动允许文件编辑，其他操作仍询问 | 已确认修改范围，仍希望审查命令 |
自动模式 (auto) |
Claude 审查工具调用，执行其认为安全的操作并阻止高风险操作 | 熟悉项目后减少重复审批 |
计划模式 (plan) |
只研究和规划，不执行修改 | 先评审方案、做只读调查 |
跳过全部 (bypassPermissions) |
跳过所有权限检查 | 仅限完全可信、可恢复的隔离环境 |
第一次启用自动模式会显示风险确认。Auto 能减少权限询问，但分类并不等于绝对安全；仍应限制工作目录、检查 Diff，并保留版本控制或备份。
跳过全部的风险高于 Auto。不要在含生产凭证、个人资料或不可恢复数据的目录中使用。
活跃任务运行期间不能切换权限模式。请先等待当前轮结束或主动停止，再修改模式。
四、对话、附件与长内容定位
输入与附件
Enter默认发送，Shift + Enter换行；也可以在通用设置中改为Ctrl/Cmd + Enter发送。- 输入
/打开斜杠命令。 - 输入
@搜索并引用工作区文件。 - 可粘贴图片、拖入文件或通过文件选择器添加文件、目录和 PDF。
- 聊天中的本地附件可以用系统默认应用打开，或从「打开方式」中选择外部应用。
附件内容会随会话恢复。若原文件已经移动、删除或当前系统无法访问，打开操作会给出失败提示；这不代表历史消息被删除。
查找与导航
Ctrl/Cmd + F：在当前页面或长对话中查找，并在匹配项之间跳转。- 对话导航：从用户消息和 AI 回复生成目录，适合快速回到长任务的关键节点。
- 消息操作：复制或从某条消息分叉，触屏 H5 中也会保持可发现。
侧边栏的会话搜索、对话内查找和工作区文件搜索是三种不同入口：一个找会话，一个找当前对话内容，一个找项目文件。
五、在工作区审阅改动
打开右侧工作区后，可以：
- 浏览 Git 工作区与变更文件。
- 搜索尚未在目录树中展开的文件；正式桌面安装包已内置对应平台的 ripgrep。
- 预览文本、图片和常见文件。
- 在 Diff 中切换文件，查看旧行、新行和语法高亮。
- 点击单行添加评论，或按住
Shift选择同一侧的连续行。 - 把评论和代码引用带回聊天输入框，让 Agent 根据明确位置继续修改。
被拒绝的 Write/Edit 不会因为工具“尝试过”就算作真实文件变更。最终仍应以磁盘内容和 Git Diff 为准。
六、查看任务、SubAgent 与团队
当会话启动 Task、后台任务、SubAgent 或 Agent Team 后，活动面板会集中展示状态。
- 运行中的 SubAgent 可以立即打开，不必等到结束。
- 详情会继续刷新运行记录和工具调用。
- 后台任务支持停止，并区分完成、失败与已停止。
- 完全退出再启动后，已经持久化的终态不会被简单恢复成“进行中”。
短暂的轮询失败可能只影响面板刷新，不等于任务数据已经丢失。遇到持续异常时，先刷新，再到「设置 → 诊断」收集信息。
七、安装技能与管理 Agent
技能市场
从技能市场可以搜索、筛选、查看来源与安全提示，并安装支持的第三方技能。安装前应阅读技能内容、来源和免责声明；技能本质上可能扩大 Agent 可执行的工作流。
Agent 管理
进入「设置 → Agents」可以：
- 查看内置、用户、项目、插件、策略和 CLI 参数等来源。
- 判断同名 Agent 当前哪个定义生效、哪个被覆盖。
- 创建、编辑或删除用户级和项目级 Agent。
- 为每个 Agent 分别配置模型、思考强度、允许工具和系统提示词。
用户 Agent 写入 ~/.claude/agents/，项目 Agent 写入当前项目的 .claude/agents/。内置、插件与策略来源保持只读。
模型和 effort 可以继承主会话，也可以单独指定；不受所选模型支持的 effort 可能被降低或忽略。完整规则见多 Agent 使用指南。
八、使用桌面宠物
按下面的顺序即可开始使用：
- 进入「设置 → 宠物」。
- 从搭搭 Dada、弧弧 Huhu、补补 Bubu、回回 Huihui 中选择一个内置角色。
- 打开「显示桌面宠物」，透明悬浮窗口会立即出现。
- 按需要调整 96–192px 大小、动画和「显示运行中的任务面板」。
- 在桌面上拖动宠物调整位置；单击宠物会唤起主窗口，单击任务行会返回对应会话，右键可以关闭宠物。
任务面板只显示正在工作、等待处理或失败的活跃任务；没有活跃任务时会自动隐藏。右键关闭宠物不会停止正在执行的任务，下次可以回到「设置 → 宠物」重新开启。
还可以通过「添加宠物」导入透明 PNG / WebP 单图，或导入符合规格的 v2 动画图集。导入在本地完成，不会调用当前聊天模型；AI 生成完整动画目前不可用。图片要求、创建步骤、存储位置和故障排查见桌面宠物使用指南。
宠物仅在 Electron 桌面端运行，不会出现在 H5 页面中。窗口置顶、拖动与多显示器行为仍受操作系统窗口管理影响。
九、从手机或 IM 继续使用
H5
在「设置 → H5 访问」开启后，桌面服务会提供带 Token 的二维码和连接地址。普通局域网访问使用同一个 H5 页面、REST API 和 WebSocket 服务；需要稳定书签或反向代理时可固定端口。
H5 会暴露当前桌面服务的核心能力，只应在可信网络和自己的代理中使用。详细步骤见H5 访问。
IM
「设置 → IM 接入」支持：
- 微信
- 钉钉
- Telegram
- 飞书
扫码绑定平台账号并不等于授权所有联系人。用户仍需发送一次性配对码，或被加入允许列表。详见IM 接入总览。
十、快捷键
| 快捷键 | 功能 |
|---|---|
Ctrl/Cmd + N |
新建会话 |
Ctrl/Cmd + F |
当前页面或对话内查找 |
Ctrl/Cmd + K |
打开全局会话搜索 |
Ctrl/Cmd + . |
停止当前生成 |
Enter |
按当前发送设置发送 |
Shift + Enter |
默认设置下换行 |
/ |
打开斜杠命令 |
@ |
搜索工作区文件 |
Escape |
关闭当前弹层 |