Platform setup

How to Install OpenClaw with Nix

3 min read

Browse more in Platform setup.

All platform setup guides →

This guide shows you how to install and run OpenClaw with Nix using the nix-openclaw Home Manager module. You use a declarative flake plus Nix mode so your OpenClaw gateway, macOS app, and tools stay pinned and reproducible.

By the end, you have an agent-first OpenClaw setup managed by Nix with a launchd service that survives reboots.

Prerequisites

  • ✓A macOS machine where you can run Home Manager and launchd services.
  • ✓Nix installed (the OpenClaw docs recommend using the Determinate Nix installer from https://github.com/DeterminateSystems/nix-installer).
  • ✓Access to the nix-openclaw repository so you can copy the `templates/agent-first/flake.nix` file.
  • ✓Messaging bot credentials and a model provider API key that you can store as plain files under `~/.secrets/`.

Steps

  1. 1

    Create a local flake for your OpenClaw configuration

    Start by creating a dedicated directory for your OpenClaw Nix setup, then base it on the agent-first template from nix-openclaw. This flake becomes the single source of truth for your gateway, macOS app, tools, and plugins.

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

    Configure your messaging and model provider secrets

    secrets/`. This keeps secrets out of your flake while matching the expectations of the nix-openclaw templates.

    text
    ~/.secrets/
  3. 3

    Switch your Home Manager configuration to enable OpenClaw

    Apply your flake with Home Manager so it installs OpenClaw, configures the plugin system, and sets up the launchd service. You can roll back instantly if something goes wrong using Home Manager’s rollback feature.

    bash
    home-manager switch
  4. 4

    Enable Nix mode for deterministic OpenClaw runtime

    Turn on Nix mode so OpenClaw disables auto-install flows and behaves deterministically under Nix. In shells you export the environment variable directly, and on macOS you also enable Nix mode for the GUI app via `defaults` because it does not automatically inherit shell environment variables.

    bash
    export OPENCLAW_NIX_MODE=1

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

    Set explicit config and state paths under Nix

    When running under Nix, set the config and state paths explicitly so mutable data and JSON5 config stay out of the immutable Nix store. OpenClaw reads JSON5 config from `OPENCLAW_CONFIG_PATH` and stores mutable data in `OPENCLAW_STATE_DIR`, so point these at writable locations.

    bash
    OPENCLAW_STATE_DIR=~/.openclaw
OPENCLAW_CONFIG_PATH=$OPENCLAW_STATE_DIR/openclaw.json
  6. 6

    Verify the launchd service and bot behavior

    After switching, confirm that the launchd service is running and that your bot responds to messages. This validates that your secrets, Nix configuration, and OpenClaw runtime are wired together correctly.

Configuration

OptionDescriptionExample
OPENCLAW_NIX_MODEEnables deterministic Nix mode, which disables auto-install and self-mutation flows and surfaces Nix-specific remediation messages.1
OPENCLAW_STATE_DIRDirectory where OpenClaw stores mutable runtime data; under Nix you set this to a writable, Nix-managed location./Users/alex/.openclaw
OPENCLAW_CONFIG_PATHPath to the JSON5 config file that OpenClaw reads; under Nix you set this explicitly so config lives outside the immutable store./Users/alex/.openclaw/openclaw.json
OPENCLAW_HOMEBase directory OpenClaw uses as its home; by default it derives from the OS home but under Nix you can set it to a Nix-managed path./Users/alex

Troubleshooting

OpenClaw keeps trying to auto-install tools or mutate itself under Nix

Auto-install and self-mutation flows are disabled only when Nix mode is on. nixMode -bool true` so OpenClaw enters deterministic Nix mode.

bash
export OPENCLAW_NIX_MODE=1

OpenClaw writes config or state into unexpected locations inside the Nix store

Under Nix you need to set `OPENCLAW_STATE_DIR` and `OPENCLAW_CONFIG_PATH` explicitly so mutable data and JSON5 config stay out of the immutable store. Point both variables at writable paths such as a directory under your home folder.

bash
OPENCLAW_STATE_DIR=~/.openclaw
OPENCLAW_CONFIG_PATH=$OPENCLAW_STATE_DIR/openclaw.json

Frequently asked questions

Powered by Mem0

Add persistent memory to OpenClaw

Official Mem0 plugin for OpenClaw keeps context across chats and tools. Smaller prompts, lower cost, better continuity for your agents.

Read the official Mem0 guideOpen Mem0

More in Platform setup

Platform setup

How to Deploy OpenClaw on Northflank

Platform setup

How to Deploy OpenClaw on Render

Platform setup

How to Install OpenClaw on Linux

Platform setup

How to Run OpenClaw with Podman

Platform setup

How to Deploy OpenClaw on Kubernetes

Platform setup

How to Deploy OpenClaw on Google Cloud (GCP)