db137dd65d
* fix(paths): respect OPENCLAW_HOME for all internal path resolution (#11995) Add home-dir module (src/infra/home-dir.ts) that centralizes home directory resolution with precedence: OPENCLAW_HOME > HOME > USERPROFILE > os.homedir(). Migrate all path-sensitive callsites: config IO, agent dirs, session transcripts, pairing store, cron store, doctor, CLI profiles. Add envHomedir() helper in config/paths.ts to reduce lambda noise. Document OPENCLAW_HOME in docs/help/environment.md. * fix(paths): handle OPENCLAW_HOME '~' fallback (#12091) (thanks @sebslight) * docs: mention OPENCLAW_HOME in install and getting started (#12091) (thanks @sebslight) * fix(status): show OPENCLAW_HOME in shortened paths (#12091) (thanks @sebslight) * docs(changelog): clarify OPENCLAW_HOME and HOME precedence (#12091) (thanks @sebslight)
3.4 KiB
summary, read_when, title
| summary | read_when | title | |||
|---|---|---|---|---|---|
| Install OpenClaw declaratively with Nix |
|
Nix |
Nix Installation
The recommended way to run OpenClaw with Nix is via nix-openclaw — a batteries-included Home Manager module.
Quick Start
Paste this to your AI agent (Claude, Cursor, etc.):
I want to set up nix-openclaw on my Mac.
Repository: github:openclaw/nix-openclaw
What I need you to do:
1. Check if Determinate Nix is installed (if not, install it)
2. Create a local flake at ~/code/openclaw-local using templates/agent-first/flake.nix
3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
5. Fill in the template placeholders and run home-manager switch
6. Verify: launchd running, bot responds to messages
Reference the nix-openclaw README for module options.
📦 Full guide: github.com/openclaw/nix-openclaw
The nix-openclaw repo is the source of truth for Nix installation. This page is just a quick overview.
What you get
- Gateway + macOS app + tools (whisper, spotify, cameras) — all pinned
- Launchd service that survives reboots
- Plugin system with declarative config
- Instant rollback:
home-manager switch --rollback
Nix Mode Runtime Behavior
When OPENCLAW_NIX_MODE=1 is set (automatic with nix-openclaw):
OpenClaw supports a Nix mode that makes configuration deterministic and disables auto-install flows. Enable it by exporting:
OPENCLAW_NIX_MODE=1
On macOS, the GUI app does not automatically inherit shell env vars. You can also enable Nix mode via defaults:
defaults write bot.molt.mac openclaw.nixMode -bool true
Config + state paths
OpenClaw reads JSON5 config from OPENCLAW_CONFIG_PATH and stores mutable data in OPENCLAW_STATE_DIR.
When needed, you can also set OPENCLAW_HOME to control the base home directory used for internal path resolution.
OPENCLAW_HOME(default precedence:HOME/USERPROFILE/os.homedir())OPENCLAW_STATE_DIR(default:~/.openclaw)OPENCLAW_CONFIG_PATH(default:$OPENCLAW_STATE_DIR/openclaw.json)
When running under Nix, set these explicitly to Nix-managed locations so runtime state and config stay out of the immutable store.
Runtime behavior in Nix mode
- Auto-install and self-mutation flows are disabled
- Missing dependencies surface Nix-specific remediation messages
- UI surfaces a read-only Nix mode banner when present
Packaging note (macOS)
The macOS packaging flow expects a stable Info.plist template at:
apps/macos/Sources/OpenClaw/Resources/Info.plist
scripts/package-mac-app.sh copies this template into the app bundle and patches dynamic fields
(bundle ID, version/build, Git SHA, Sparkle keys). This keeps the plist deterministic for SwiftPM
packaging and Nix builds (which do not rely on a full Xcode toolchain).
Related
- nix-openclaw — full setup guide
- Wizard — non-Nix CLI setup
- Docker — containerized setup