> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/zhi-nan/guides/recover-failed-installation.md).

# 从失败的安装中恢复

**目标：** 应用无法安装、无法启动，或者启动后出现故障，你希望它恢复正常运行 **而不清除你的数据**.

本指南的指导原则是： **你的配置和记忆默认都会被保留。** 恢复的意思是修复数据周围的运行环境，而不是删除数据。只有在明确说明、并且已做好备份的最后手段下，我们才会动你的数据文件夹。

***

## 前提条件

* 没什么特别的。你可以仅用应用程序、文件管理器，偶尔再加一个终端来完成所有操作。
* 先知道你的数据存放在哪里。 **OpenHuman 保存的一切都在一个文件夹中：**

  | 平台            | 数据文件夹                       |
  | ------------- | --------------------------- |
  | macOS / Linux | `~/.openhuman/`             |
  | Windows       | `%USERPROFILE%\.openhuman\` |

  除非这里的某一步明确要求，否则不要动那个文件夹。

## 隐私影响

* 恢复是本地操作。你是在重启或重新安装软件；你的记忆不会因此被上传。
* 如果你提交 bug 报告， **请遮盖机密信息**。附上状态码、应用版本、操作系统和日志行，绝不要附带 token 或 JWT。

***

## 首先：查看日志

几乎每一种故障都会在日志里写明原因。先看日志，就能把猜测变成修复。

* **在应用中（如果它能打开）：** **设置 → 关于 → 应用日志文件夹**。那里有一个按钮可以在你的文件管理器中打开该文件夹。
* **在磁盘上：** 日志位于你的数据文件夹下，例如 `~/.openhuman/logs/openhuman.<date>.log` （Windows： `%USERPROFILE%\.openhuman\logs\openhuman.*.log`）。它们会按天轮换。

打开最新的日志，查看最后的错误行。将消息与下面的表格对应起来。

***

## 恢复阶梯

按从上到下的顺序操作。 **一旦能正常工作就停止。** 每一级都比前一级更有影响，而前几级绝不会动到你的数据。

### 第 1 级：干净重启

* 完全退出 OpenHuman（确保没有残留进程在运行），然后重新打开。
* 只应同时运行 **一个** 实例。第二个副本可能会占用第一个实例需要的锁。

### 第 2 级：在你的数据之上重新安装应用

重新安装 **应用** 不会删除你的 **数据文件夹**；它们是分开的。这可以修复损坏或不完整的安装，同时保留所有内容。

* 从 [tinyhumans.ai/openhuman](https://tinyhumans.ai/openhuman) 下载当前版本并覆盖安装。
* 在 macOS 上，请安装真正的 `.app` 捆绑包（某些功能需要捆绑包，而不是开发版）。
* 重新打开。你的记忆、角色和设置仍然在，因为它们存放在 `~/.openhuman/`中，而你并没有动它。

### 第 3 级：修复具体错误

将你的症状对号入座：

| 日志 / 界面中的症状                                                     | 原因                          | 修复方法                                                                                                     |
| --------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------- |
| 在提供方步骤之后登录卡住；日志提到 `openhuman://` scheme **未注册** （Windows）       | URL 处理程序没有注册，或者安装在首次启动后被移动过 | 按照 [登录故障排查](/openhuman/zh/gai-lan/troubleshooting-sign-in.md#windows-openhuman-handler-not-registered)   |
| 应用无法渲染 / 启动时崩溃，并提到 **CEF / 缓存锁** (`SingletonLock`，缓存“被另一个实例占用”） | 上一个实例的浏览器缓存仍然被锁定            | 确保没有其他 OpenHuman 正在运行；如果问题仍然存在，请关闭所有实例后重新启动                                                              |
| 启动时出现本地 AI / Ollama 错误                                          | 本地模型运行时无法访问                 | 这不会 **不** 阻止应用运行；参见 [将 OpenHuman 与本地模型一起使用](/openhuman/zh/zhi-nan/guides/local-model.md#common-failures) |
| “磁盘空间不足”警告，或写入失败                                                | 工作区无法写入                     | 释放一些空间（应用希望留有健康余量，至少几百 MB）并重启                                                                            |

### 第 4 级：把数据文件夹移到一边（非破坏性重置）

如果应用仍然无法启动，而且你怀疑 **数据文件夹** 问题出在它本身， **请重命名** 它，而不是删除它。这样你就能获得一个干净的起点，同时保留一个完整的备份，以便恢复。

{% hint style="warning" %}
在移动文件夹之前，请彻底退出 OpenHuman。
{% endhint %}

```bash
# macOS / Linux
mv ~/.openhuman ~/.openhuman.backup-$(date +%Y%m%d)
```

```powershell
# Windows（PowerShell）
Rename-Item "$env:USERPROFILE\.openhuman" ".openhuman.backup"
```

重新启动。OpenHuman 会重新创建一个新的数据文件夹，你需要再次登录。

* 如果这个全新启动 **成功**，说明旧文件夹就是问题所在，但你的数据在备份中是安全的。你可以把特定内容复制回来（你的记忆数据库和保险库），并在每一步后进行测试。
* 如果它 **仍然失败**，那就说明数据文件夹不是原因。 **恢复你的备份** 方法是把它重命名回去，这样你不会丢失任何东西，然后继续升级处理（见下文）。

***

## 成功检查

当满足以下条件时，就算恢复完成：

* [ ] 应用能启动到登录或聊天界面，而不会崩溃。
* [ ] 你可以登录并进入主页/聊天视图。
* [ ] 你的 **记忆** 标签页仍显示你现有的摘要（这说明你的数据幸存了下来）。
* [ ] 最新的日志文件显示启动正常，没有重复出现错误。

## 这里“默认保留”是什么意思

在第 1 至第 3 级过程中，你不会删除任何东西。第 4 级只是 **重命名** 你的数据文件夹；它从不删除它。即使最激进的步骤也完全可逆。重新安装应用和重新安装系统级运行时都不会针对你的 `~/.openhuman/` 数据。

## 如果你仍然卡住

收集这些信息，并在 [GitHub](https://github.com/tinyhumansai/openhuman) 上提交 issue，或者去 [Discord](https://discord.tinyhumans.ai):

* 应用版本和操作系统。
* 日志中最后的错误行（**已遮盖 token/JWT**).
* 你到了哪一级，以及发生了什么。
* 把数据文件夹移到一边是否带来了变化。

## 另请参阅

* [登录故障排查](/openhuman/zh/gai-lan/troubleshooting-sign-in.md)：用于特定身份验证失败的深入排查。
* [将 OpenHuman 迁移到新电脑](/openhuman/zh/zhi-nan/guides/move-to-new-pc.md)：你需要迁移的就是同一个数据文件夹。