日志与诊断
Halo 出问题时怎样自查和收集信息：运行系统诊断和恢复操作，导出诊断报告，找到日志和崩溃报告，用开发者模式记录完整请求，以及反馈问题时附上什么。
Halo 出问题时，先在 Halo 里自查和修复；要找人帮忙，再按这一页收集信息。日志、诊断报告和崩溃报告分别存放在哪个文件夹，见 数据与配置位置。
这一页的操作要你自己在设置里点，Halo 的 AI 不能替你运行诊断或导出报告。
开始之前
- 系统诊断、日志文件、崩溃报告 在 设置 › 系统，开发者模式 在 设置 › 高级。这两个分区只在桌面版里有 仅桌面版，用远程访问的网页或安卓 App 时，请回到运行 Halo 的那台电脑上操作。
- Halo Server 没有窗口，看它的日志用
docker logs，见 Docker 部署 › 验证。
运行系统诊断
- 打开 设置 › 系统，找到 系统诊断（「检查系统健康状态并修复问题」）。
- 点 运行诊断。按钮显示「运行中...」，几秒后出结果，详情自动展开。
- 最上面是「系统健康」或「检测到问题」，后面是「上次检查」的时间。点这一行可以收起或展开详情。
| 部分 | 看什么 |
|---|---|
| 系统信息 | 版本、平台、系统内存、运行时间 |
| 健康指标 | 连续失败次数、恢复尝试次数、活跃进程、发现孤儿进程 |
| 进程状态 | Claude (AI Sessions)：正在运行的 AI 会话进程。Cloudflared (Tunnel)：互联网访问用的隧道进程，没启动隧道时显示「未运行」；公司版本禁用了隧道时不显示这一行 |
| 服务状态 | OpenAI Router：Halo 在本机转发模型请求的服务。HTTP Server：远程访问的服务，没打开远程访问时显示「未启动」。子进程本地连接：AI 引擎的进程能不能连上本机的转发服务 |
| 清理操作 | 诊断时顺手清掉的失效进程记录、发现的孤儿进程 |
| 最近错误 | 最近 5 条错误 |
服务的状态是「健康」「无响应」「未启动」或「失败」。有几行的名字只有英文，例如 OpenAI Router、HTTP Server。
「系统健康」只说明没有连续失败、孤儿进程和最近错误，不代表每一行都正常：再看一眼进程状态和服务状态，有没有「无响应」或「失败」。
完成
「系统健康」，而且进程和服务的每一行都正常，说明 Halo 自己的进程和服务都没问题。问题还在的话，多半出在模型服务、网络或某个具体功能上，见 模型 API 错误码 和 错误信息速查。
子进程本地连接 显示「失败」并提示「此计算机上的安全软件阻止了 Halo 的内部连接。请让 IT 团队允许此程序建立本地连接：…」时，对话和数字人的模型请求都会失败，但问题不在模型或账号。把提示里写的程序发给 IT，请他们放行。
修复：重置 AI 引擎或重启
系统诊断 展开后的 恢复操作 里有两个按钮，操作成功后会自动再诊断一次：
| 按钮 | 做什么 | 什么时候用 |
|---|---|---|
| 重置 AI 引擎 | 「终止所有 AI 会话并重启 - 修复大多数问题」。正在进行的回复会被打断，会话记录都还在 | 回复一直卡住、所有会话都报同样的错 |
| 重启应用 | 重启整个 Halo | 重置 AI 引擎后还不行 |
也可以在 设置 › 系统 › 重启 Halo 点 重启。确认框会提醒「所有活跃的对话和后台任务都将被中断。」
Halo 自己也会处理一部分问题：
- AI 引擎连续出错：连续出错 3 次，Halo 会自动重置 AI 引擎；到 5 次，会弹出英文对话框 「Halo is having trouble」，可以选 Restart App（重启）、Try to Fix（重置 AI 引擎）或 Ignore（忽略），勾选「Don't show again this session」可以在这次运行期间不再弹出。
- 窗口崩溃：窗口崩溃后 Halo 会自动重新加载，一分钟内最多 3 次。再崩溃，它就停止重新加载，弹出「Halo 窗口已停止」，按钮是 重启 Halo 和 稍后。数字人和后台任务照常在运行，方便时点 重启 Halo 即可。这个对话框的语言跟随系统语言。
导出诊断报告
要找人帮忙时，先给对方诊断报告，而不是日志或配置文件。
- 在 设置 › 系统 › 系统诊断 点 运行诊断。
- 点 复制报告，把一段文字报告复制到剪贴板，按钮短暂显示「已复制!」；或者点 导出报告，保存成文件，界面显示「报告已导出至」和完整路径。
- 导出的文件在「下载」文件夹里，文件名是
halo-diagnostics-<时间戳>.json。
报告里有：
- Halo 版本、操作系统和芯片架构、内存、运行时间；
- 当前用的模型服务商类型、有没有配置 Key（只写「是」或「否」）、MCP 服务器的数量；导出的文件里还有当前模型服务的域名；
- 进程和健康计数，以及最近 10 条错误和警告。
报告不含 Key 本身。错误信息里的 Bearer 令牌、JWT 和部分 sk- 开头的 Key 会被遮盖，但 Anthropic（sk-ant-…）和 OpenAI 项目 Key（sk-proj-…）这类格式不会。macOS 和 Linux 路径里的用户名会被隐去，Windows 路径（C:\Users\…）里的不会。发出前先通读一遍，删掉看到的 Key。
找到日志
打开 设置 › 系统 › 日志文件，点 打开文件夹。Halo 打不开时，按 数据与配置位置 › 日志 里的路径直接去文件夹里找。
| 文件 | 什么时候看 |
|---|---|
main.log | 几乎所有问题。Halo 的主日志，满 10 MB 轮转，保留 5 份旧的（main.1.log 到 main.5.log） |
halo-sdk.log | 用 Halo SDK 引擎时的问题 |
http-raw.log | 只在打开开发者模式后才有，见 下一节 |
auth-audit.log | 远程访问的登录记录：成功、失败、锁定和来源 IP，不含密码。macOS 上它在应用数据文件夹的 logs 里，见 日志 |
main.log 是给排查用的，不是为分享准备的：里面有文件和工作区的路径、对话和数字人的 ID、模型服务的地址、服务商返回的报错原文，还有代理地址。代理地址里写了用户名和密码的，也会原样记下来。Halo 会遮住它自己记录的 Key，但不保证日志里没有别的敏感内容。
发日志之前
先看一遍内容；只发对方要的那一段，或者问题发生前后几分钟的部分，不要整个文件夹打包发出去。
用开发者模式记录完整请求
模型服务、公司网关或代理的问题，只看 main.log 找不到原因时，用开发者模式把完整的请求和响应记下来。
- 打开 设置 › 高级 › 开发者模式，立即生效。界面提示「生成大量日志文件，可能影响性能。故障排查后请禁用。」
- 回到对话，把出问题的操作再做一遍。
- 关掉 开发者模式。
- 打开日志文件夹，
http-raw.log里是这段时间完整的请求头和请求体；main.log和halo-sdk.log也会多出调试信息。
http-raw.log 里有你的 Key 和完整对话
这个文件不做任何遮盖，原样记录 API Key、登录令牌和对话内容。不要把它直接发给别人，排查完就删掉。需要给别人看时，用 诊断报告，或者只摘出相关的几行并删掉其中的 Key。
崩溃报告
Halo 崩溃时，系统会在应用数据文件夹的 Crashpad/ 里留下崩溃转储。打开 设置 › 系统 › 崩溃报告，点 打开文件夹 就能找到。
- 「崩溃报告保存在本机。需要时可打开该文件夹，将其发送给支持团队。」Halo 不会上传它们。
- 只在对方需要时再发。
反馈问题时附上什么
- 你做了什么、想要什么结果、实际看到了什么。能稳定重现的，写出步骤。
- 报错原文：在思考过程里出错的那一步点 复制（提示「复制错误信息」）；没有报错的，截个图，截图里不要有 Key、账号和公司信息。
- Halo 版本（设置 › 关于）和操作系统版本。
- 诊断报告。
- 对方需要时，再附上日志的相关部分。
然后在 GitHub Issues 用 Bug Report 模板提交问题，或者通过 联系我们 里的方式找到我们。安全漏洞请不要发公开 Issue，在 GitHub 上私下报告。
遇到问题
设置里找不到系统诊断
你可能在用远程访问的网页或安卓 App。设置 › 系统 只在桌面版里有，请在运行 Halo 的电脑上打开。
点了导出报告，找不到文件
看界面上「报告已导出至」后面的路径。默认在系统的「下载」文件夹里，文件名以 halo-diagnostics- 开头。
顶部提示「无法读取配置文件。为了保护您的数据，Halo 已暂停保存设置。」
Halo 读不了自己的配置文件 config.json，提示里会显示它的路径。比如文件被手动改坏了，或者正被同步盘、杀毒软件占用。这期间改的设置不会保存，会提示「未保存」。
- 修好这个文件，或者等占用它的程序结束。
- 点 重新检查。恢复正常后显示「设置已重新加载」。
文件里有明文的 Key，不要把它发给别人，见 密钥和凭据。
开发者模式忘了关
日志会越积越多，http-raw.log 也会一直记录完整请求。到 设置 › 高级 关掉 开发者模式，再删掉 http-raw.log。