Install OpenClaw Declaratively with Nix and Home Manager

Install OpenClaw declaratively through nix-openclaw, the official Home Manager module that includes everything needed out of the box.

Info

The nix-openclaw repository serves as the authoritative reference for Nix-based installation. This page provides a brief summary.

What you get

• Gateway, macOS app, and tools (whisper, spotify, cameras) are all version-pinned
• A launchd service that persists across system restarts
• Plugin system configured declaratively
• Instant rollback capability via home-manager switch --rollback

Quick start

Install Determinate Nix

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

Create a local flake

Use the agent-first template located in 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 text files placed at ~/.secrets/ are sufficient.

Fill in template placeholders and switch

home-manager switch

Verify

Verify that the launchd service is active and that your bot responds to incoming messages.

For a complete list of module options and usage examples, refer to the nix-openclaw README.

Nix-mode runtime behavior

When OPENCLAW_NIX_MODE=1 is enabled (which happens automatically with nix-openclaw), OpenClaw enters a deterministic mode intended for Nix-managed installations. Other Nix packages can also enable this mode; nix-openclaw is the official reference implementation.

You can enable it manually as well:

export OPENCLAW_NIX_MODE=1

On macOS, the GUI application does not inherit environment variables from the shell. Use defaults to enable Nix mode instead:

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

What changes in Nix mode

• Automatic installation and self-update mechanisms are turned off.
• openclaw.json is considered immutable. Defaults derived at startup remain runtime-only, and configuration writers (setup, onboarding, mutating openclaw update, plugin install/update/uninstall/enable, doctor --fix, doctor --generate-gateway-token, openclaw config set) will refuse to modify the file.
• Make changes in the Nix source instead. With nix-openclaw, start from the agent-first Quick Start and place configuration under programs.openclaw.config or instances.<name>.config.
• Missing dependencies trigger Nix-specific remediation messages.
• The user interface displays a read-only Nix mode banner.

Config and state paths

OpenClaw reads JSON5 configuration from OPENCLAW_CONFIG_PATH and stores mutable data in OPENCLAW_STATE_DIR. Under Nix, set these explicitly to Nix-managed paths so that runtime state and configuration remain outside the immutable store.

Service PATH discovery

The launchd/systemd gateway service automatically detects Nix-profile binaries, enabling plugins and tools that call executables installed via nix to function without manual PATH configuration:

• When NIX_PROFILES is set, each entry is appended to the service PATH in right-to-left precedence (matching Nix shell precedence: the rightmost entry wins).
• When NIX_PROFILES is not set, ~/.nix-profile/bin is used as a fallback.

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

Related

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

• Setup wizard, A CLI-based setup walkthrough for non-Nix environments.

• Docker, A containerized setup option as an alternative to Nix.

• Updating, Instructions for updating Home Manager-managed installations together with the package.