OpenHuman 常见问题与故障排除 — 安装/连接/模型/记忆全攻略

📦 安装问题

安装后打不开应用

解决方案： 检查系统要求（Windows 10+ / macOS 12+ / Linux Kernel 5.x+）。macOS 用户检查安全性与隐私 → 通用 → 允许来自已识别开发者的应用。如果脚本安装失败，尝试用 Homebrew：brew tap tinyhumansai/openhuman && brew install openhuman。

命令行安装失败

解决方案： 确保安装了 curl。试试：curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | sudo bash。源码编译需要 Node.js 24+、pnpm 10.10+、Rust 1.93+。详见安装指南。

macOS 提示"损坏"无法打开

解决方案： 终端执行 xattr -cr /Applications/OpenHuman.app 清除隔离属性，然后重新打开。

Linux AppImage 在 Wayland 下崩溃

已知问题： AppImage 可能在 Wayland 下崩溃（见 Issue #2463）。建议使用 apt 源或 DEB 包安装。

如何更新 OpenHuman？

在桌面端 Settings → About 中检查更新。或者重新执行安装命令（brew upgrade、apt upgrade 或重跑安装脚本）。macOS 内置自动更新功能。

🔌 连接与集成问题

OAuth 授权失败（Gmail/GitHub）

解决方案： 在授权过程中关闭广告拦截插件和 VPN。确保登录了正确的账号。尝试换一个浏览器完成授权。如果仍然失败，在 Google/GitHub 设置中撤销应用授权后重试。

Auto-fetch 不同步

解决方案： 确保在 Settings → Integrations 中启用了相应集成。检查 config.toml 中的 sync_interval 设置（默认 20 分钟）。检查网络连接。查看子意识循环的活动日志是否有错误信息。

网页搜索返回空结果

解决方案： 默认使用 OpenHuman 托管的搜索代理。如果你配置了自托管 SearXNG，请确认服务正在运行。检查 config.toml 中 [web_search] 节配置是否正确。

🤖 模型与 API

模型无响应 / API 报错

解决方案： 确认 Settings 中 API Key 正确。检查提供商的基础 URL（例如 DeepSeek 的 https://api.deepseek.com/v1）。确认账户有可用额度。使用 Ollama 时确保服务在运行：ollama serve。

响应速度慢

解决方案： 尝试更小的模型（gpt-4o-mini 替代 gpt-4o，或 3B 本地模型替代 8B）。检查模型路由配置，确保简单查询使用 hint:fast。云端模型检查网络速度。启用 TokenJuice 压缩工具输出。

API 费用太高

解决方案： 切换到更便宜的提供商（DeepSeek 比 OpenAI 便宜 90%）。启用 TokenJuice 压缩工具输出。使用模型路由将简单查询分到便宜模型。使用 Ollama 本地模型的 API 费用为 0。

如何配置本地模型？

安装 Ollama，下载模型（如 ollama pull qwen2.5:7b），然后配置 OpenHuman：[models.local] provider = "ollama" model = "qwen2.5:7b"。将所有路由提示设为本地提供商即可完全离线使用。

🧠 记忆与数据

记忆树不增长

解决方案： 确保配置中 [memory_tree] enabled = true。在对话中更具体地描述——详细讨论会产生更丰富的记忆。检查集成是否正常工作（Gmail、GitHub 等提供的数据会喂养记忆树）。

找不到旧记忆

解决方案： 检查 auto-prune 设置是否太激进。尝试用更具体的上下文提问。记忆按层级组织——先试宽泛的查询，再逐步缩小范围。

如何备份数据？

见备份与迁移指南。记忆树和配置文件存在本地，复制 ~/.openhuman（Linux/macOS）或 %LOCALAPPDATA%\openhuman（Windows）目录即可。

🎤 语音与 Mascot

Mascot 对语音没有反应

解决方案： 检查操作系统的麦克风权限。确保 Mascot 已启用（Settings → Mascot）。确认 Settings → Voice 中 TTS/STT 已配置。先用文字测试聊天功能，排除语音问题。

Google Meet 助手无法加入会议

解决方案： 授予 OpenHuman 摄像头和麦克风权限。确保 Mascot 已启用。确认会议链接有效且你有访问权限。助手通过内置浏览器加入——检查防火墙是否阻止了 CEF 进程。

💰 订阅与定价

OpenHuman 真的是免费的吗？

是的！OpenHuman 本身是免费开源的（GPL-3.0）。订阅主要涵盖托管模型访问和云端服务。你可以通过自带 API Key 或使用 Ollama 本地模型完全免费使用。

订阅包含什么？

一个订阅即可通过路由器系统访问 30+ 模型提供商（Anthropic、OpenAI、Google、Groq 等），无需持有多组 API Key。详见订阅详解。

没有网络能用 OpenHuman 吗？

可以，只要使用 Ollama 本地模型。除云端 API 调用和实时搜索外，所有功能均可离线使用。