OpenHuman FAQ — Common Problems, Solutions, and Everything You Need to Know

📦 Installation

App won't open after installation

Solution: Check system requirements (Windows 10+ / macOS 12+ / Linux Kernel 5.x+). On macOS, check Security & Privacy → General → Allow apps from identified developers. If using the script install, try the Homebrew approach instead: brew tap tinyhumansai/openhuman && brew install openhuman.

Command line install fails

Solution: Ensure curl is installed. Try: curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | sudo bash. For source builds, you need Node.js 24+, pnpm 10.10+, and Rust 1.93+. Check the Installation Guide for full details.

AppImage crashes on Linux (Wayland)

Known issue: AppImage may crash under Wayland (see GitHub Issue #2463). Use the apt repo or DEB package instead.

macOS says "OpenHuman is damaged and can't be opened"

Solution: Run xattr -cr /Applications/OpenHuman.app to clear quarantine attributes, then try opening again.

How do I update OpenHuman?

Check for updates in Settings → About. Or re-run your install method (brew upgrade, apt upgrade, or script). On macOS, the built-in auto-updater handles it.

🔌 Connection & Integrations

OAuth integration fails (Gmail/GitHub/Notion)

Solution: Disable ad-blockers and VPNs during the authorization flow. Make sure you're logged into the correct account. Try using a different browser for the OAuth popup. If still failing, revoke the app in your Google/GitHub settings and try again.

Auto-Fetch not syncing

Solution: Verify the integration is enabled in Settings → Integrations. Check that the sync interval in config.toml is reasonable (default is 20 minutes). Ensure your internet connection is stable. Check the logs for provider errors in the Subconscious activity log.

Web search returns nothing

Solution: By default, web search uses OpenHuman's managed proxy. If you configured a custom SearXNG instance, verify it's running and accessible. Check that the [web_search] section in config.toml is set up correctly.

🤖 Models & API

Model not responding / API error

Solution: Verify your API key is correct in Settings. Check the provider's base_url endpoint (e.g., for DeepSeek it's https://api.deepseek.com/v1). Ensure your account has available credits. For Ollama, confirm the service is running: ollama serve.

Slow responses

Solution: Try a smaller model (gpt-4o-mini instead of gpt-4o, or a 3B local model instead of 8B). Check model routing config — make sure simple queries use hint:fast. For cloud APIs, check your internet speed. Enable TokenJuice compression for tool outputs.

High API costs

Solution: Switch to cheaper providers (DeepSeek costs 90% less than OpenAI). Enable TokenJuice to compress tool output before it reaches the model. Use model routing to direct simple queries to fast/cheap models. With Ollama local models, API costs are zero.

How do I use a local model?

Install Ollama, pull a model (e.g., ollama pull llama3.2), then configure it in OpenHuman: [models.local] provider = "ollama" model = "llama3.2". Set all route hints to use the local provider for full offline usage.

🧠 Memory & Data

Memory Tree not growing

Solution: Ensure Memory Tree is enabled: [memory_tree] enabled = true in config. Be more specific in conversations — detailed discussions produce richer memories. Check that your integrations are working (data from Gmail/GitHub feeds the tree).

Can't find old memories

Solution: Check if auto-prune is too aggressive in config. Try asking with more specific context. Memories are organized hierarchically — try broader queries first, then narrow down.

How to back up my data?

See the Backup & Restore Guide. Your Memory Tree and config files are stored locally. Just copy the ~/.openhuman (Linux/macOS) or %LOCALAPPDATA%\openhuman (Windows) directory.

🎤 Voice & Mascot

Mascot not responding to voice

Solution: Check mic permissions in your OS settings. Ensure the mascot is enabled (Settings → Mascot). Verify TTS/STT is configured in Settings → Voice. Test with text first before troubleshooting voice.

Google Meet agent won't join

Solution: Grant camera and mic permissions to OpenHuman. Ensure the mascot is enabled. Check that the Meet link is valid and you have access to the meeting. The agent joins via the embedded webview — make sure your firewall isn't blocking CEF processes.

💰 Subscription & Pricing

Is OpenHuman really free?

Yes! OpenHuman itself is free and open source (GPL-3.0). The subscription covers hosted model access and cloud services. You can use it completely free by bringing your own API keys or running local models with Ollama.

What does the subscription include?

One subscription gives you access to 30+ model providers (Anthropic, OpenAI, Google, Groq, etc.) through the router system. You don't hold separate API keys. See the Subscription Guide (Chinese) for details.

Can I use OpenHuman without internet?

Yes, if you use local models (Ollama). All features except cloud API calls and live web search work offline.