第八章：设置、应用商店与排障
本章带你逐项了解 Halo 设置页面里的每个选项，学会安装商店里的数字人，以及在遇到问题时自己动手排查。
8.1 设置页面在哪里
不管你在 Halo 的主页还是聊天界面，顶部栏最右边都有一个看起来像齿轮形状的小图标 ⚙️。
操作： 把鼠标移到齿轮图标上，单击一次。
做完后你会看到： 整个页面切换到设置界面。顶部栏变成左边一个向左箭头 ← 加上 Settings 文字（点箭头可以回到之前的页面）。下方分为左右两栏——左侧是设置菜单列表，右侧显示当前选中的设置内容。
┌──────────────────────────────────────────────┐
│ ← Settings │
├────────────┬─────────────────────────────────┤
│ AI Model │ │
│ Message │ ← 右侧是当前选中菜单的 │
│ App Store │ 设置内容区 │
│ Appearance │ │
│ System │ │
│ Advanced │ │
│ Remote │ │
│ Recommend │ │
│ About │ │
└────────────┴─────────────────────────────────┘💡 菜单中 System、Advanced、Remote Access 三项只在电脑端显示，手机端看不到。
第零章已介绍过第一次打开时的 AI Model 配置，第一章介绍了 Message Channels，第七章介绍了 Remote Access。本章覆盖其余页面。
8.2 外观设置（Appearance）
在设置页面左侧菜单中，找到 Appearance（外观），单击它。右侧会显示三个设置项。
主题（Theme）
第一个设置项是「Theme」，下面有三个按钮并排：
| 按钮 | 含义 |
|---|---|
| Light | 亮色主题，白色背景 + 深色文字，像白天看报纸 |
| Dark | 暗色主题，深色背景 + 浅色文字，在光线较暗的环境下看着不刺眼 |
| Follow System | 跟随你电脑系统的设置。如果你的电脑设了「深色模式」，Halo 也变深色 |
操作： 用鼠标单击你想要的按钮。当前选中的按钮会高亮显示（有彩色边框）。
做完后你会看到： 界面颜色立刻切换。不需要重启。
语言（Language）
第二个设置项是「Language」，下面有一个下拉选择框。
操作： 单击下拉框，在弹出的列表中选择你想要的语言（如「简体中文」或「English」）。
做完后你会看到： 界面上的所有文字立刻切换为你选的语言。
发送键（Send Key）
第三个设置项是「Send Key」，下面有两个按钮并排：
| 按钮 | 含义 |
|---|---|
| Enter | 按回车键发送消息，按 Shift+回车换行 |
| Ctrl+Enter | 按 Ctrl+回车发送消息，按回车换行 |
操作： 单击你习惯的方式。
⚠️ 如果你经常需要在消息里换行（比如写多段文字），建议选 Ctrl+Enter，这样按回车就是换行，不会意外发出去。
8.3 系统设置（System）
在设置页面左侧菜单中，找到 System，单击它。右侧会出现多个设置项，从上到下依次是：
权限模式（Permissions）
最上方有一个标题写着「Permissions」的区域。你会看到一个绿色小标签写着 Full Permission Mode（完整权限模式），下面有一个说明：「We recommend full trust mode - use natural language to control Halo.」
这表示 Halo 会自动执行 AI 决定的所有操作，不需要你逐个批准。这个开关是固定打开的，你不需要（也无法）修改它。
开机自启动（Auto Launch on Startup）
操作： 在「Auto Launch on Startup」右侧，你会看到一个滑动开关。
- 开关向右（彩色） = 开启：每次你的电脑开机后，Halo 会自动启动
- 开关向左（灰色） = 关闭：需要手动双击 Halo 图标才能启动
单击开关可以切换状态。
如果你需要数字人全天候工作（比如绑定了企微机器人），建议打开这个开关，这样即使电脑重启后 Halo 也会自动恢复运行。
任务通知（Task Notifications）
操作： 在「Task Notifications」右侧，你会看到一个滑动开关。
- 开启：当数字人在后台完成任务时，系统会弹出桌面通知提醒你
- 关闭：数字人完成任务不会弹出通知
代理服务器（Proxy）
代理服务器就像一个「中转站」——如果你的公司网络需要通过特定通道才能访问外部网站，就需要在这里填写代理地址。本手册后面说「代理」或「Proxy」，就是指这个中转站。
你会看到一个文本输入框，里面有灰色提示文字 http://127.0.0.1:1087。
如果你不知道这是什么： 保持输入框空白即可。Halo 会自动使用你电脑系统的网络设置。
如果公司 IT 告诉你需要填代理： 把 IT 给你的代理地址粘贴到输入框里，然后单击右侧的 Save 按钮。
支持的代理格式：http://、https://、socks4://、socks5://
做完后你会看到： Save 按钮短暂变成绿色对勾，表示保存成功。
⚠️ 注意：填完代理地址后，必须点击 Save 按钮才能生效。这里不是自动保存。
填写代理后，下方会多出一个小开关「Also apply to AI Browser」（也应用到 AI 浏览器）。默认关闭，表示 AI 浏览器使用系统代理。如果你需要 AI 浏览器也走这个代理，再打开它。
日志文件（Log Files）
操作： 找到「Log Files」旁边的 Open Folder 按钮，单击它。
做完后你会看到： 你电脑上的文件管理器（Windows 的资源管理器 / Mac 的 Finder）会自动打开一个文件夹，里面是 Halo 的运行日志文件。
这些日志文件在你遇到问题需要联系开发者时非常有用。日志里不包含你的对话内容或 API 密钥，可以放心发送。
系统诊断（System Diagnostics）
当 Halo 出现异常（AI 不响应、卡住等），可以使用诊断功能。
操作： 找到「System Diagnostics」旁边的蓝色 Run Diagnostics 按钮，单击它。
做完后你会看到： 按钮变成「Running...」并转圈，等待几秒后下方展开一个诊断报告面板，里面包含：
- 健康状态摘要（绿色 = 正常，黄色 = 有问题）
- 系统信息（版本号、平台、内存、运行时间）
- 进程状态（Claude AI 会话和 Cloudflared 隧道的运行情况）
- 服务状态（OpenAI Router 和 HTTP Server 是否正常响应）
- 恢复操作按钮：
- Reset AI Engine（重置 AI 引擎）：终止所有 AI 会话并重新启动。大部分问题可以通过这个操作解决
- Restart App（重启应用）：完全重启 Halo 程序。如果重置 AI 引擎无效，再试这个
┌───────────────────────────────────────────┐
│ System Diagnostics │
│ │
│ ✅ System Healthy │
│ Last check: 2026/4/29 11:30 │
│ │
│ ┌─ System Info ─────────────────────────┐ │
│ │ Version: 1.2.3 Platform: darwin │ │
│ │ Memory: 4GB/16GB Uptime: 2h 30m │ │
│ └───────────────────────────────────────┘ │
│ │
│ ┌─ Recovery Actions ────────────────────┐ │
│ │ [🔄 Reset AI Engine] [🔄 Restart App]│ │
│ └───────────────────────────────────────┘ │
│ │
│ [📋 Copy Report] [📄 Export Report] │
└───────────────────────────────────────────┘排障建议： 遇到 AI 无反应时，按以下顺序操作：
- 先点 Reset AI Engine，等待几秒
- 再试一次发消息。如果恢复了，问题解决
- 如果还是不行，点 Restart App，Halo 会自动重启
- 如果重启后问题依旧，点 Copy Report 或 Export Report，把诊断报告发给开发者
8.4 管理 AI 模型源（AI Model）
在设置页面左侧菜单中，找到 AI Model，单击它。
在第零章（0.8 节），我们已经学习了第一次打开时如何添加 AI 模型。这里介绍日常管理：切换、编辑、新增、删除。
右侧会显示你当前已配置的 AI 来源列表。每个来源是一张卡片，显示提供商名称和状态。
切换当前使用的来源
如果你配置了多个 AI 来源（比如一个 Claude、一个 OpenAI），可以在列表中单击想切换到的来源卡片。当前激活的来源旁边会有一个绿色对勾标记。
新增 AI 来源
操作： 在来源列表下方，找到带有 + 号的按钮（可能显示为「Add Source」），单击它。
做完后你会看到： 出现一个选择面板，和第一次打开 Halo 时看到的界面类似——你可以选择 Claude OAuth、GitHub Copilot 或自定义 API。填写方式和第零章（0.6-0.8 节）完全一样。
编辑已有来源
操作： 把鼠标移到某个来源卡片上，卡片右上角会出现一个铅笔图标（编辑按钮）。单击铅笔图标。
做完后你会看到： 该来源的配置信息展开，你可以修改 API Key、Base URL、模型名称等。修改完后信息会自动保存。
删除 AI 来源
操作： 把鼠标移到某个来源卡片上，卡片右上角会出现一个垃圾桶图标（删除按钮）。单击垃圾桶图标。
做完后你会看到： 出现确认提示。确认后该来源从列表中消失。
⚠️ 注意：删除 AI 来源后，如果它是当前正在使用的来源，Halo 会自动切换到列表中的下一个来源。如果只剩一个来源，不要删除它，否则 Halo 将无法使用。
8.5 应用商店（App Store）
应用商店是 Halo 内置的「数字人市场」。别人调教好的数字人打包上架到这里，你只需要一键安装，就像手机上装 App 一样。本手册后面说「商店」或「App Store」，就是指这个数字人市场。
打开应用商店
在设置页面左侧菜单中，找到 App Store，单击它。
做完后你会看到： 右侧显示应用商店页面。你可以看到各种预制的数字人和 MCP 工具，每个都有名称、描述和安装按钮。
浏览和搜索
商店里的应用按用途分类。你可以：
- 上下滚动浏览列表
- 使用搜索框输入关键词（如「舆情」「日报」「监控」）来筛选
安装应用
操作： 找到你想安装的应用，单击它的「安装」按钮。
做完后你会看到： 弹出一个安装对话框，要求你填写少量配置信息（比如收件邮箱、目标关键词等）。填好后点击确认。
安装完成后，你可以在主页的 Digital Humans 标签下看到新安装的数字人。启动它，它就会按预设的方式自动运行。
商店来源管理
商店页面底部有一个 Registry（注册源）区域，显示当前商店数据的来源。默认使用 Halo 官方源。
普通用户不需要修改注册源。如果你的公司有内部应用仓库，IT 管理员会告诉你如何添加。
8.6 个人微信连接
除了企业微信（第一章），Halo 还支持绑定个人微信。绑定后，你可以用个人微信和数字人对话。
个人微信 vs 企业微信
| 个人微信 | 企业微信 | |
|---|---|---|
| 需要什么账号 | 普通微信号 | 需要企业微信组织 |
| 支持群聊吗 | 不支持，只能私聊 | 支持私聊和群聊 |
| 适合什么场景 | 个人助理、个人工具 | 团队协作、公司部署 |
| 配置难度 | 扫码即可 | 需要在企微后台申请 |
配置步骤
第一步： 打开设置 → Message Channels（消息通道）。在右侧找到 WeChat Bot 卡片（注意不是「WeCom Intelligent Bot」，那个是企业微信）。WeChat Bot 卡片的图标是一个手机形状。
第二步： 单击卡片上的 Connect WeChat 按钮。
做完后你会看到： 界面上出现一个二维码。
第三步： 拿出你的手机，打开微信，使用微信的「扫一扫」功能扫描这个二维码，然后在手机上点击「确认」。
做完后你会看到： 界面上的状态会依次变化：等待扫码 → 已扫描 → 连接成功。
第四步： 连接成功后，在同一卡片中找到 Digital Human 下拉菜单，选择一个数字人来负责回复微信消息。
⚠️ 注意：扫码绑定的微信号就是数字人用来收发消息的账号。数字人会以这个微信号的身份回复消息。
第五步测试： 用另一个微信号给绑定的账号发一条私信，看看数字人是否自动回复。
断开连接
在 WeChat Bot 卡片中单击 Disconnect 按钮即可断开。下次连接需要重新扫码。
8.7 进阶设置（Advanced）
⚠️ 这个页面是给有一定经验的用户使用的。如果你刚开始使用 Halo，可以跳过本节。修改这里的设置会影响 AI 的行为。
在设置页面左侧菜单中，找到 Advanced，单击它。
页面顶部有一个黄色警告条：「Changes here affect all AI agent behavior. New settings take effect on the next conversation.」（此处的修改会影响所有 AI 代理的行为，新设置在下一次对话时生效。）
系统提示词模板（System Prompt Profile）
你会看到两个可选项：
| 选项 | 含义 |
|---|---|
| Official | 使用 Claude Code 的原始提示词，没有 Halo 的额外优化 |
| Halo Optimized | 使用 Halo 团队优化过的提示词，包含网络搜索策略等增强功能（推荐） |
操作： 单击你想用的选项。当前选中的选项会有彩色边框高亮。默认是「Halo Optimized」，大多数情况下不需要修改。
内置 MCP 扩展（Built-in MCP Extensions）
MCP（Model Context Protocol）可以理解为「AI 的工具箱」。这里列出了 Halo 内置的一些扩展能力，你可以按需开关。
操作： 单击 Built-in MCP Extensions 这个折叠面板，它会展开显示 6 个能力开关：
| 扩展能力 | 含义 | 默认状态 |
|---|---|---|
| Agent Teams | 多个 AI 代理协作工作 | 关闭 |
| Plan Mode | 先列计划再执行，每步需要你批准 | 关闭 |
| Git Worktree | 使用 Git 分支隔离（程序员用的） | 关闭 |
| Scheduled Tasks | 内置定时任务（Halo 已有数字人系统） | 关闭 |
| Notebook Editing | 编辑 Jupyter 笔记本（数据分析用的） | 关闭 |
| Digital Humans | 允许 AI 在对话中创建和管理数字人 | 开启 |
操作： 单击每行右侧的滑动开关即可切换。开启的扩展会消耗更多 Token（可以理解为「AI 的工作耗材」），所以只开你需要的。
⚠️ 修改后需要新开一个对话或重启 Halo 才能生效。
每条消息最大回合数（Max Turns per Message）
这个数字控制 AI 在回复一条消息时，最多可以「来回操作」多少次。
你会看到一个数字输入框，默认值是 50。
- 数字越大，AI 可以做更复杂的任务（但也可能花更长时间和更多费用）
- 数字越小，AI 会更快完成但可能中途停下
普通用户建议： 保持默认值 50 不变。
开发者模式（Developer Mode）
这是一个带有黄色「Dev」标签的开关。打开后 Halo 会输出详细的调试日志，方便排查技术问题。
普通用户建议： 保持关闭。只在开发者或技术支持人员要求时打开。
⚠️ 开发者模式会生成大量日志文件，可能影响性能。排查完问题后记得关闭。
8.8 关于和推荐（About & Recommend）
关于（About）
在设置页面左侧菜单中，单击 About。这里显示：
- 当前版本号（例如 v1.2.3）
- 检查更新按钮：单击后 Halo 会检查是否有新版本可用
- 如果有更新，会提示你下载安装
- 如果已是最新版本，会显示「已是最新」
- 帮助链接：跳转到官方文档和 GitHub 反馈页面
推荐 Halo（Recommend Halo）
在设置页面左侧菜单中，单击 Recommend Halo。这里可以：
- 给 GitHub 项目点 Star（好评）
- 一键复制分享文案，方便你在微信、小红书、B 站等平台推荐给同事朋友
8.9 常见错误与排障指南
当你在使用 Halo 时遇到问题，可以先按照下面的分类找到对应情况，自己尝试解决。
问题一：AI 突然停止回复了
现象： 你发了消息，AI 回复到一半突然停住，没有报错提示。
原因： AI 底层引擎（Claude Code）在遇到某些异常时会中断，尤其是使用第三方模型时。
解决方法：
- 看界面上是否有一个「继续」按钮，有的话单击它
- 或者在输入框里直接输入「继续」并发送
- 如果还是不行，新开一个对话重试
问题二：出现「Prompt is too long」（提示词过长）
现象： 界面上弹出红色错误信息，写着 Prompt is too long。
原因： 你和 AI 的对话太长了，超出了 AI 模型能处理的上限。就像一个笔记本写满了，写不下新内容了。
解决方法：
- 在输入框里输入
/compact并发送——AI 会自动把之前的对话「压缩」成摘要，腾出空间 - 如果
/compact也不管用，用鼠标选中重要的对话内容复制下来，新开一个对话，把复制的内容粘贴进去，然后说：「上面是之前的对话记录，请继续」
问题三：上传图片后报错，后续消息也发不出去
现象： 上传了图片后 AI 报错，而且之后发的纯文字消息也报错。
原因： 你当前使用的 AI 模型不支持看图片。这时对话的内部数据已经被图片「污染」了。
解决方法：
- 必须新开一个对话（旧的对话已经无法修复）
- 在新对话中，先到右上角切换一个支持看图片的模型（如 Claude 4.5 Sonnet、GPT-4o 等多模态模型），然后再上传图片
问题四：Windows 上 AI 执行命令失败
现象： 在 Windows 电脑上，你让 AI 执行某个操作，它报错说命令执行失败。
原因： Halo 在 Windows 上需要 Git Bash 来执行命令。如果你没安装 Git，命令就跑不起来。
解决方法：
- 下载并安装 Git for Windows（下载地址：https://git-scm.com/download/win）
- 安装完成后重启 Halo
如果你在公司内网无法下载，请联系 IT 部门协助安装。
问题五：出现红色错误码（429、401、500 等）
这些错误来自你的 AI 模型服务商（如 Anthropic、OpenAI），不是 Halo 自身的问题。
| 错误信息 | 含义 | 怎么办 |
|---|---|---|
429 Too Many Requests 或 rate limit | 请求太频繁，被限速了 | 等几分钟再发送 |
401 Unauthorized 或 invalid api key | API 密钥无效或过期 | 去设置 → AI Model 检查密钥是否正确 |
insufficient quota / 余额不足 | API 额度用完了 | 去服务商官网充值或更换密钥 |
model not found | 模型名称写错了，或你的账号没权限用这个模型 | 去设置 → AI Model 检查模型名称 |
500 Internal Server Error 或 overloaded | 服务商那边出了问题 | 等一会儿再试 |
context length exceeded | 对话太长 | 发送 /compact，或新开对话 |
通用处理思路：
- 等一等再试： 429、500、overloaded 这类错误通常是暂时的
- 新开对话： context length exceeded 和图片相关的错误，必须新开对话
- 检查配置： 401、invalid api key、model not found，去设置 → AI Model 核实你的密钥和模型名称
问题六：AI 无响应 / 界面卡住
完整排查步骤：
- Check 1： 等待 30 秒。有时 AI 正在执行复杂任务，需要时间
- Check 2： 看输入框上方是否有「停止」按钮。如果有，说明 AI 还在工作，只是比较慢
- Check 3： 打开设置 → System → 单击 Run Diagnostics，查看系统健康状态
- Check 4： 单击 Reset AI Engine，等待几秒后重试
- Check 5： 单击 Restart App，Halo 完全重启后重试
- Check 6： 如果以上都无效，单击 Copy Report 复制诊断报告，到 GitHub Issues（https://github.com/openkursar/hello-halo/issues）提交问题并附上诊断报告
常见问题
Q1：修改了设置，为什么没有生效？
不同设置的生效方式不同：
- Appearance（主题、语言、发送键）：立刻生效
- System（开机自启动、通知）：立刻生效
- System → Proxy：需要点击 Save 按钮后生效
- Advanced（提示词模板、MCP 扩展、Max Turns）：需要新开对话或重启 Halo 才能生效
Q2：个人微信扫码后一直连不上怎么办？
按以下顺序排查：
- 确认你扫码后在手机上点了「确认」
- 确认电脑和手机都连着网络
- 尝试断开后重新点击 Connect WeChat 生成新的二维码
- 如果反复失败，可能是微信账号被风控限制，建议换一个微信号尝试
Q3：应用商店里没有我想要的数字人怎么办？
你可以自己创建！回到第二章，按照 2.3 和 2.4 的步骤手动创建一个数字人，自定义它的提示词和运行计划。
Q4：诊断报告里的信息安全吗？可以发给别人吗？
诊断报告包含的是系统运行状态信息（如版本号、内存、进程状态），不包含你的对话内容、API 密钥或个人隐私信息。可以安全地发送给开发者或技术支持人员。
Q5：代理设置填了之后网络反而不通了？
代理地址填错会导致 Halo 无法联网。解决方法：
- 清空 Proxy 输入框
- 单击 Save 按钮
- Halo 会恢复使用系统默认的网络设置
Q6：进阶设置里的 MCP 扩展，我该打开哪些？
对于本手册的目标读者（非技术岗位），默认设置就够用了。只有 Digital Humans 需要保持开启（默认已开启），其余扩展是给程序员或高级用户用的。
Q7：应用商店的注册源（Registry）是什么？普通用户需要管吗？
注册源是商店获取应用列表的数据来源。默认使用 Halo 官方源，里面有经过审核的数字人。普通用户不需要修改。只有当你的公司 IT 部门提供了内部应用源时，才需要添加。