OpenHuman 安装失败或无法启动怎么恢复：按故障阶梯修复而不丢失记忆数据
【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman
OpenHuman 是一款运行在 macOS、Windows 和 Linux 上的开源个人 AI 应用，本地优先保存你的记忆、人格与设置。当它装不上、起不来，或者启动后处于损坏状态时，官方给出的恢复路径是一条自上而下执行的"恢复阶梯"（Recovery ladder）：围绕你的数据修复运行时环境，而不是删掉数据。阶梯的前三级永远不会动你的数据目录，只有最后一级会把数据目录改名挪到一边（而不是删除），并且完全可逆。
适用环境：macOS / Windows / Linux 桌面应用。准备条件不高——应用本身、一个文件管理器，偶尔用到终端即可。
先定位两样东西：数据目录和日志
OpenHuman 持久化的所有内容都在一个目录里：
| 平台 | 数据目录 |
|---|---|
| macOS / Linux | ~/.openhuman/ |
| Windows | %USERPROFILE%\.openhuman\ |
后续步骤中，除非某一步明确说要动它，否则不要碰这个目录。
几乎每个故障都会在日志里"自报家门"，先读日志可以把猜测变成定位：
- 应用能打开时：Settings → About → App Logs Folder，界面上有按钮直接在文件管理器中打开该目录。
- 打不开时：直接到磁盘上找。日志位于数据目录下，例如
~/.openhuman/logs/openhuman.<date>.log（Windows 为%USERPROFILE%\.openhuman\logs\openhuman.*.log），按天滚动。
打开最新的日志，读最后几行错误信息，再对照下面的阶梯逐级处理。
恢复阶梯：从上到下执行，能用就停
每一级都比上一级更有侵入性，且早期几级都不触碰数据。
第一级：干净地重启
- 彻底退出 OpenHuman（确认没有残留进程），再重新打开。
- 同一时间只应有一个实例在运行：第二份副本可能持有第一个实例需要的锁。
第二级：在现有数据之上重装应用
重装应用不会删除数据目录，两者是分开的。这一级修复损坏或不完整的安装，同时保留全部数据。
从项目官方下载页获取当前构建版本覆盖安装（各平台的下载来源与安装命令见 INSTALL.md）：
# macOS（Homebrew Cask） brew install --cask openhuman# Linux（Debian/Ubuntu）：先下载 OpenHuman_<version>_amd64.deb # （<version> 为发布版本号；arm64 机器改用 arm64 后缀的包） # 需要 sudo 权限，会通过 apt 安装系统包 sudo apt-get install -y --no-install-recommends ./OpenHuman_*_amd64.deb- Windows：下载带签名的
.msi并运行。 - macOS 注意：要安装真正的
.appbundle（部分功能依赖 bundle，开发构建不行）。
重装后重新打开应用：你的记忆、人格（personas）和设置都还在，因为它们存放在你没动过的~/.openhuman/（Windows 为%USERPROFILE%\.openhuman\）里。
第三级：按具体错误对症修
日志读完后，把症状对号入座：
| 日志 / 界面中的症状 | 原因 | 修复 |
|---|---|---|
登录在 provider 步骤后卡住，日志提到openhuman://协议未注册（Windows） | URL 处理器未注册，或首次启动后安装目录被移动 | 按下面的 Windows 处理器修复步骤操作（另见 Troubleshooting Sign-In） |
应用不渲染 / 启动崩溃，报错提到CEF / 缓存锁（SingletonLock、缓存 "held by another instance"） | 上一个实例的浏览器缓存仍被锁定 | 确认没有其他 OpenHuman 在运行；若持续出现，关闭所有实例后重新启动 |
| 启动时的 Local AI / Ollama 报错 | 本地模型运行时不可达 | 不阻塞应用本身运行；处理见 Use OpenHuman with a local model |
| "Low disk space" 警告，或写入失败 | 工作区无法写入 | 腾出磁盘空间（应用要求至少几百 MB 的余量）后重启 |
Windows：openhuman://处理器未注册
启动时如果注册失败，Tauri 外壳会在日志里打印错误行，形如（文档示例，…为占位省略）：
[deep-link] openhuman:// scheme registration unhealthy — OAuth callbacks may never reach the app. register_all_error=…, hkcu_status=NotRegistered|MissingCommand|Stale { … }|ReadError(…)原因：Windows 在首次启动时把openhuman://URL 协议注册到HKEY_CURRENT_USER\Software\Classes\openhuman\shell\open\command；如果这次注册静默失败，或安装目录在首次启动之后被移动/复制过，浏览器就无法把 OAuth 回调交还给应用，登录就会卡在 provider 步骤。
手动修复：用运行 OpenHuman 的同一个用户打开 PowerShell（不需要管理员权限，HKCU 是每用户范围的），把$exe替换为OpenHuman.exe的实际安装路径后执行：
$exe = 'C:\Path\To\OpenHuman.exe' # 替换为你的实际安装路径 New-Item -Path 'HKCU:\Software\Classes\openhuman' -Force | Out-Null Set-ItemProperty -Path 'HKCU:\Software\Classes\openhuman' -Name '(Default)' -Value 'URL:OpenHuman Protocol' New-ItemProperty -Path 'HKCU:\Software\Classes\openhuman' -Name 'URL Protocol' -Value '' -Force | Out-Null New-Item -Path 'HKCU:\Software\Classes\openhuman\shell\open\command' -Force | Out-Null Set-ItemProperty -Path 'HKCU:\Software\Classes\openhuman\shell\open\command' -Name '(Default)' -Value ('"' + $exe + '" "%1"')该脚本只写当前用户的注册表项，不触碰数据目录。执行完重启 OpenHuman 再重试登录。如果日志里register_all_error不是None（例如杀毒软件或受锁定的镜像在阻止对HKCU\Software\Classes的写入），需要先解除该策略限制——上面的手动脚本会撞上同一道墙。
启动时的 Local AI / Ollama 报错
这类错误不阻塞应用启动本身，只是本地模型运行时不可达。如果你启用了本地模型，先确认 Ollama 可达：
curl http://localhost:11434/api/tags返回 JSON 模型列表（即使为空列表）即说明 Ollama 服务器可达。具体故障状态与修复对照表见 Use OpenHuman with a local model 的 "Common failures" 一节。
第四级：把数据目录改名挪到一边（非破坏性重置）
如果应用仍然无法启动，而你怀疑问题出在数据目录本身：把它改名，而不是删除。这样你既得到一个干净起点，又保留一份可以回滚的完整备份。
移动目录前，先彻底退出 OpenHuman。
# macOS / Linux mv ~/.openhuman ~/.openhuman.backup-$(date +%Y%m%d)# Windows（PowerShell） Rename-Item "$env:USERPROFILE\.openhuman" ".openhuman.backup"然后重启应用。OpenHuman 会重建一个全新的数据目录，你再次登录。之后按结果分两条路：
- 新启动能正常工作：说明问题就在旧目录里，而你的数据安全地留在备份中。可以把数据按需拷回并每拷一项测一次——至少拷回记忆数据库（
memory_tree/chunks.db）和 Obsidian 记忆库（wiki/），两项在数据目录中的具体位置见 Move OpenHuman to a new PC。 - 仍然失败：说明数据目录不是原因。把备份改回原名
.openhuman还原，你不会损失任何东西，然后按下一节升级处理。
验证：怎么判断已经恢复
满足以下四项即视为恢复完成：
- 应用能启动到登录页或聊天界面，没有崩溃；
- 你能登录并进入主页/聊天视图；
- Memory标签页仍显示你原有的摘要（确认数据幸存）；
- 最新的日志文件显示干净启动，没有重复出现的错误。
关于"默认保留数据"的边界，官方文档说得很明确：第一到第三级没有任何删除动作；第四级只是改名数据目录，从不删除它。重装应用（以及重装操作系统层面的运行时）都永远不会针对你的~/.openhuman/数据目录。
仍然卡住时
恢复过程本身全部是本地操作，记忆不会因此被上传。需要求助时，先收集以下信息，再到项目仓库提 issue 或在社区提问：
- 应用版本和操作系统；
- 日志最后的错误行（必须抹掉 tokens/JWTs；只附状态码、应用版本、操作系统和相关日志行）；
- 你执行到阶梯的哪一级、发生了什么；
- 把数据目录挪到一边是否改变了什么。
相关文档：
- Recover from a failed installation：本文依据的官方恢复指南原文。
- Troubleshooting Sign-In：登录类故障的深入排查（后端可达性、deep-link 回调等）。
- Move OpenHuman to a new PC：同一个数据目录也是换机迁移时你要携带的全部内容。
【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
