---
title: "日志与诊断：运行系统诊断、导出报告、找到日志"
description: "Halo 出问题时怎样自查和收集信息：运行系统诊断和恢复操作，导出诊断报告，找到日志和崩溃报告，用开发者模式记录完整请求，以及反馈问题时附上什么。"
type: "how-to"
audience: ["admin", "office"]
platforms: ["macos", "windows", "linux"]
related: ["advanced/config-paths", "troubleshooting/common-errors", "advanced/security"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/troubleshooting/diagnostics.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# 日志与诊断

Halo 出问题时怎样自查和收集信息：运行系统诊断和恢复操作，导出诊断报告，找到日志和崩溃报告，用开发者模式记录完整请求，以及反馈问题时附上什么。

Halo 出问题时，先在 Halo 里自查和修复；要找人帮忙，再按这一页收集信息。日志、诊断报告和崩溃报告分别存放在哪个文件夹，见 [数据与配置位置](https://hello-halo.cc/docs/advanced/config-paths.html#logs)。

这一页的操作要你自己在设置里点，Halo 的 AI 不能替你运行诊断或导出报告。

## 开始之前 {#before-you-start}

- **系统诊断**、**日志文件**、**崩溃报告** 在 **设置 › 系统**，**开发者模式** 在 **设置 › 高级**。这两个分区只在桌面版里有 （仅桌面版），用远程访问的网页或安卓 App 时，请回到运行 Halo 的那台电脑上操作。
- Halo Server 没有窗口，看它的日志用 `docker logs`，见 [Docker 部署 › 验证](https://hello-halo.cc/docs/server/deployment-docker.html#verify)。

## 运行系统诊断 {#run-diagnostics}

1. 打开 **设置 › 系统**，找到 **系统诊断**（「检查系统健康状态并修复问题」）。
2. 点 **运行诊断**。按钮显示「运行中...」，几秒后出结果，详情自动展开。
3. 最上面是「系统健康」或「检测到问题」，后面是「上次检查」的时间。点这一行可以收起或展开详情。

| 部分 | 看什么 |
|---|---|
| 系统信息 | 版本、平台、系统内存、运行时间 |
| 健康指标 | 连续失败次数、恢复尝试次数、活跃进程、发现孤儿进程 |
| 进程状态 | **Claude (AI Sessions)**：正在运行的 AI 会话进程。**Cloudflared (Tunnel)**：互联网访问用的隧道进程，没启动隧道时显示「未运行」；公司版本禁用了隧道时不显示这一行 |
| 服务状态 | **OpenAI Router**：Halo 在本机转发模型请求的服务。**HTTP Server**：远程访问的服务，没打开远程访问时显示「未启动」。**子进程本地连接**：AI 引擎的进程能不能连上本机的转发服务 |
| 清理操作 | 诊断时顺手清掉的失效进程记录、发现的孤儿进程 |
| 最近错误 | 最近 5 条错误 |

服务的状态是「健康」「无响应」「未启动」或「失败」。有几行的名字只有英文，例如 **OpenAI Router**、**HTTP Server**。

「系统健康」只说明没有连续失败、孤儿进程和最近错误，不代表每一行都正常：再看一眼进程状态和服务状态，有没有「无响应」或「失败」。

::: done
「系统健康」，而且进程和服务的每一行都正常，说明 Halo 自己的进程和服务都没问题。问题还在的话，多半出在模型服务、网络或某个具体功能上，见 [模型 API 错误码](https://hello-halo.cc/docs/troubleshooting/api-errors.html) 和 [错误信息速查](https://hello-halo.cc/docs/troubleshooting/common-errors.html)。
:::

**子进程本地连接** 显示「失败」并提示「此计算机上的安全软件阻止了 Halo 的内部连接。请让 IT 团队允许此程序建立本地连接：…」时，对话和数字人的模型请求都会失败，但问题不在模型或账号。把提示里写的程序发给 IT，请他们放行。

## 修复：重置 AI 引擎或重启 {#recover}

**系统诊断** 展开后的 **恢复操作** 里有两个按钮，操作成功后会自动再诊断一次：

| 按钮 | 做什么 | 什么时候用 |
|---|---|---|
| **重置 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** 即可。这个对话框的语言跟随系统语言。

## 导出诊断报告 {#report}

要找人帮忙时，先给对方诊断报告，而不是日志或配置文件。

1. 在 **设置 › 系统 › 系统诊断** 点 **运行诊断**。
2. 点 **复制报告**，把一段文字报告复制到剪贴板，按钮短暂显示「已复制!」；或者点 **导出报告**，保存成文件，界面显示「报告已导出至」和完整路径。
3. 导出的文件在「下载」文件夹里，文件名是 `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。

## 找到日志 {#logs}

打开 **设置 › 系统 › 日志文件**，点 **打开文件夹**。Halo 打不开时，按 [数据与配置位置 › 日志](https://hello-halo.cc/docs/advanced/config-paths.html#logs) 里的路径直接去文件夹里找。

| 文件 | 什么时候看 |
|---|---|
| `main.log` | 几乎所有问题。Halo 的主日志，满 10 MB 轮转，保留 5 份旧的（`main.1.log` 到 `main.5.log`） |
| `halo-sdk.log` | 用 Halo SDK 引擎时的问题 |
| `http-raw.log` | 只在打开开发者模式后才有，见 [下一节](#developer-mode) |
| `auth-audit.log` | 远程访问的登录记录：成功、失败、锁定和来源 IP，不含密码。macOS 上它在应用数据文件夹的 `logs` 里，见 [日志](https://hello-halo.cc/docs/advanced/config-paths.html#logs) |

`main.log` 是给排查用的，不是为分享准备的：里面有文件和工作区的路径、对话和数字人的 ID、模型服务的地址、服务商返回的报错原文，还有代理地址。代理地址里写了用户名和密码的，也会原样记下来。Halo 会遮住它自己记录的 Key，但不保证日志里没有别的敏感内容。

::: warning 发日志之前
先看一遍内容；只发对方要的那一段，或者问题发生前后几分钟的部分，不要整个文件夹打包发出去。
:::

## 用开发者模式记录完整请求 {#developer-mode}

模型服务、公司网关或代理的问题，只看 `main.log` 找不到原因时，用开发者模式把完整的请求和响应记下来。

1. 打开 **设置 › 高级 › 开发者模式**，立即生效。界面提示「生成大量日志文件，可能影响性能。故障排查后请禁用。」
2. 回到对话，把出问题的操作再做一遍。
3. 关掉 **开发者模式**。
4. 打开日志文件夹，`http-raw.log` 里是这段时间完整的请求头和请求体；`main.log` 和 `halo-sdk.log` 也会多出调试信息。

::: danger http-raw.log 里有你的 Key 和完整对话
这个文件不做任何遮盖，原样记录 API Key、登录令牌和对话内容。不要把它直接发给别人，排查完就删掉。需要给别人看时，用 [诊断报告](#report)，或者只摘出相关的几行并删掉其中的 Key。
:::

## 崩溃报告 {#crash-reports}

Halo 崩溃时，系统会在应用数据文件夹的 `Crashpad/` 里留下崩溃转储。打开 **设置 › 系统 › 崩溃报告**，点 **打开文件夹** 就能找到。

- 「崩溃报告保存在本机。需要时可打开该文件夹，将其发送给支持团队。」Halo 不会上传它们。
- 只在对方需要时再发。

## 反馈问题时附上什么 {#bug-report}

1. 你做了什么、想要什么结果、实际看到了什么。能稳定重现的，写出步骤。
2. 报错原文：在思考过程里出错的那一步点 **复制**（提示「复制错误信息」）；没有报错的，截个图，截图里不要有 Key、账号和公司信息。
3. Halo 版本（**设置 › 关于**）和操作系统版本。
4. [诊断报告](#report)。
5. 对方需要时，再附上日志的相关部分。

然后在 [GitHub Issues](https://github.com/openkursar/hello-halo/issues) 用 **Bug Report** 模板提交问题，或者通过 [联系我们](https://hello-halo.cc/docs/contact.html) 里的方式找到我们。安全漏洞请不要发公开 Issue，在 GitHub 上[私下报告](https://github.com/openkursar/hello-halo/security/advisories/new)。

## 遇到问题 {#troubleshooting}

### 设置里找不到系统诊断

你可能在用远程访问的网页或安卓 App。**设置 › 系统** 只在桌面版里有，请在运行 Halo 的电脑上打开。

### 点了导出报告，找不到文件

看界面上「报告已导出至」后面的路径。默认在系统的「下载」文件夹里，文件名以 `halo-diagnostics-` 开头。

### 顶部提示「无法读取配置文件。为了保护您的数据，Halo 已暂停保存设置。」

Halo 读不了自己的配置文件 `config.json`，提示里会显示它的路径。比如文件被手动改坏了，或者正被同步盘、杀毒软件占用。这期间改的设置不会保存，会提示「未保存」。

1. 修好这个文件，或者等占用它的程序结束。
2. 点 **重新检查**。恢复正常后显示「设置已重新加载」。

文件里有明文的 Key，不要把它发给别人，见 [密钥和凭据](https://hello-halo.cc/docs/advanced/security.html#credentials)。

### 开发者模式忘了关

日志会越积越多，`http-raw.log` 也会一直记录完整请求。到 **设置 › 高级** 关掉 **开发者模式**，再删掉 `http-raw.log`。

## 下一步 {#next-steps}

- [数据与配置位置](https://hello-halo.cc/docs/advanced/config-paths.html)：日志、诊断报告和崩溃报告在每个系统上的具体路径。
- [错误信息速查](https://hello-halo.cc/docs/troubleshooting/common-errors.html)：按看到的那句话查意思和办法。
- [安全、隐私与数据流](https://hello-halo.cc/docs/advanced/security.html#logs)：日志里有什么，发给别人前要注意什么。