Neura Market Logo

Install OpenClaw Declaratively with Nix

This page covers how to install OpenClaw using the nix-openclaw Home Manager module, including setup, secrets, and verification. It is intended for users who want a declarative, rollback-capable installation on Nix systems.

Read this when

  • You want reproducible, rollback-able installs
  • You're already using Nix/NixOS/Home Manager
  • You want everything pinned and managed declaratively

Install OpenClaw declaratively with nix-openclaw, the official Home Manager module that includes everything you need.

Info

The nix-openclaw repository is the authoritative source for Nix installation. This page provides a quick summary.

What you get

  • Gateway, macOS app, and tools (whisper, spotify, cameras), all pinned
  • Launchd service persists across reboots
  • Plugin system configured declaratively
  • Instant rollback: home-manager switch --rollback

Quick start

Install Determinate Nix

If you do not already have Nix installed, follow the Determinate Nix installer instructions.

Create a local flake

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

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

Configure secrets

Configure your messaging bot token and model provider API key. Plain files at ~/.secrets/ work fine.

Fill in template placeholders and switch

home-manager switch

Verify

Verify 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 for Nix-managed installations. Other Nix packages can also enable this mode; nix-openclaw is the official reference.

You can also set it manually:

export OPENCLAW_NIX_MODE=1

On macOS, the GUI app does not 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.
  • openclaw.json is treated as immutable. Startup-derived defaults remain runtime-only, and config writers (setup, onboarding, mutating openclaw update, plugin install/update/uninstall/enable, doctor --fix, doctor --generate-gateway-token, openclaw config set) refuse to modify the file.
  • Edit the Nix source instead. For nix-openclaw, use the agent-first Quick Start and set config under programs.openclaw.config or instances.<name>.config.
  • Missing dependencies show Nix-specific remediation messages.
  • The UI displays 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. Under Nix, set these explicitly to Nix-managed locations so runtime state and config stay out of the immutable store.

VariableDefault
OPENCLAW_HOMEHOME / USERPROFILE / os.homedir()
OPENCLAW_STATE_DIR~/.openclaw
OPENCLAW_CONFIG_PATH$OPENCLAW_STATE_DIR/openclaw.json

Service PATH discovery

The launchd/systemd gateway service automatically discovers Nix-profile binaries so plugins and tools that shell out to nix-installed executables work without manual PATH setup:

  • When NIX_PROFILES is set, every entry is added to the service PATH in right-to-left precedence (matches Nix shell precedence: rightmost wins).
  • When NIX_PROFILES is unset, ~/.nix-profile/bin is added as a fallback.

This applies to both macOS launchd and Linux systemd service environments.

  • nix-openclaw, The authoritative Home Manager module and full setup guide.

  • Setup wizard, Non-Nix CLI setup walkthrough.

  • Docker, Containerized setup as a non-Nix alternative.

  • Updating, Updating Home Manager-managed installs alongside the package.