Nix

Nix Installation

Install OpenClaw declaratively with nix-openclaw — a batteries-included Home Manager module.

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

Quick Start

Install Determinate Nix
If Nix is not already installed, follow the Determinate Nix installer instructions.

Create a local flake

Use the agent-first template from the nix-openclaw repo:

mkdir -p ~/code/openclaw-local
# Copy templates/agent-first/flake.nix from the nix-openclaw repo

Configure secrets
Set up your messaging bot token and model provider API key. Plain files at ~/.secrets/ work fine.
Fill in template placeholders and switch
Terminal window
```
home-manager switch
```
Verify
Confirm the launchd service is running and your bot responds to messages.

See the nix-openclaw README for full module options and examples.

Nix Mode Runtime Behavior

When OPENCLAW_NIX_MODE=1 is set (automatic with nix-openclaw), OpenClaw enters a deterministic mode that disables auto-install flows.

You can also set it manually:

export OPENCLAW_NIX_MODE=1

On macOS, the GUI app does not automatically inherit shell environment variables. Enable Nix mode via defaults instead:

defaults write ai.openclaw.mac openclaw.nixMode -bool true

What changes 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

Config and state paths

OpenClaw reads JSON5 config from OPENCLAW_CONFIG_PATH and stores mutable data in OPENCLAW_STATE_DIR. When running under Nix, set these explicitly to Nix-managed locations so runtime state and config stay out of the immutable store.

Variable	Default
`OPENCLAW_HOME`	`HOME` / `USERPROFILE` / `os.homedir()`
`OPENCLAW_STATE_DIR`	`~/.openclaw`
`OPENCLAW_CONFIG_PATH`	`$OPENCLAW_STATE_DIR/openclaw.json`

nix-openclaw — full setup guide
Wizard — non-Nix CLI setup
Docker — containerized setup