Nix / Home Manager

Declarative install via nix-openclaw Home Manager module. Pinned dependencies, instant rollback, launchd service.

The Nix/Home Manager method provides a fully declarative, reproducible installation of OpenClaw. Using the `nix-openclaw` flake module, you define your entire OpenClaw setup — gateway, tools, plugins, channels — in a single `flake.nix` file. Every dependency is pinned to exact versions, and you get instant rollback with `home-manager switch --rollback` if anything goes wrong. The nix-openclaw module is batteries-included: it packages the gateway, the macOS companion app, and supporting tools (whisper for transcription, spotify integration, camera access) as Nix derivations. On macOS, it creates a launchd service that survives reboots. On Linux, it can set up a systemd user service. The plugin system is also declarative — you declare which plugins you want in your flake, and Nix handles fetching and linking them. When `OPENCLAW_NIX_MODE=1` is set (automatic with nix-openclaw), OpenClaw enters a deterministic mode. Auto-install flows are disabled, missing dependencies surface Nix-specific remediation messages, and the Control UI shows a read-only Nix mode banner. This prevents the gateway from modifying itself at runtime — all changes must go through your flake definition, which is exactly what Nix users expect. This method is for people who are already in the Nix ecosystem. If you don't know what Nix is, this is not the right install method — use the installer script or npm instead. But for Nix users, this is the gold standard: fully reproducible builds, atomic upgrades, instant rollback, and declarative configuration that you can version-control alongside your other dotfiles.

Tags: nix, declarative, reproducible, rollback

Use Cases

  • NixOS users who want OpenClaw managed declaratively alongside their system configuration
  • macOS developers using Home Manager who want reproducible AI tooling with launchd integration
  • Teams that need identical OpenClaw setups across multiple machines with version-pinned dependencies
  • Users who value instant rollback and atomic upgrades over ease of initial setup

Tips

  • Use the agent-first template: nix flake init --template github:openclaw/nix-openclaw#agent-first for the fastest start
  • Store your flake in a git repo alongside your other dotfiles for version-controlled OpenClaw configuration
  • Use home-manager switch --rollback immediately if an upgrade breaks something — it's instant
  • Pin the nix-openclaw input to a specific commit for maximum reproducibility across machines
  • On macOS, run defaults write ai.openclaw.mac openclaw.nixMode -bool true for the GUI app
  • Check the nix-openclaw repo README for the full list of module options — it exposes more config than the docs page

Known Issues & Gotchas

  • Requires familiarity with Nix flakes and Home Manager — this is not a beginner-friendly install method
  • Secrets (API keys, bot tokens) should be managed separately in ~/.secrets/ or via sops-nix — don't put them in your flake
  • The macOS GUI app doesn't inherit shell environment variables — enable Nix mode via defaults write instead
  • OPENCLAW_NIX_MODE disables auto-install flows, so any missing tools must be added to your flake definition
  • Nix builds can be slow on first run as it fetches and builds all dependencies — subsequent builds are cached
  • The Determinate Nix installer is recommended over the official Nix installer for macOS compatibility

Alternatives

  • npm / pnpm
  • Docker
  • Installer Script
  • From Source

Community Feedback

The nix-openclaw flake is one of the better Home Manager modules I've seen. Declarative config for an AI agent just makes sense — you want reproducibility.

— Reddit r/NixOS

Instant rollback is the killer feature. Broke my config, ran home-manager switch --rollback, back to working in seconds.

— GitHub nix-openclaw

If you're not already a Nix user, do not start here. The learning curve is steep. Use npm or Docker and come back to Nix later.

— Reddit r/selfhosted

Frequently Asked Questions

Do I need NixOS to use nix-openclaw?

No. nix-openclaw works with Home Manager on any OS that supports Nix — including macOS and non-NixOS Linux distros. You just need Nix and Home Manager installed.

What does Nix mode disable?

Nix mode (OPENCLAW_NIX_MODE=1) disables auto-install flows and self-mutation. If a dependency is missing, you get a Nix-specific message telling you to add it to your flake instead of the gateway trying to install it itself.

How do I update OpenClaw with Nix?

Run nix flake update to pull the latest nix-openclaw input, then home-manager switch --flake . to apply. If it breaks, home-manager switch --rollback takes you back instantly.

Where should I store API keys and secrets?

Don't put secrets in your flake.nix — it may end up in the Nix store which is world-readable. Use plain files in ~/.secrets/ or a secrets manager like sops-nix or agenix.

Can I use nix-openclaw with Nix Darwin?

Yes, nix-openclaw integrates with Home Manager which works alongside nix-darwin on macOS. The module creates a launchd service that manages the gateway process.

How long does the first build take?

The initial nix build can take 5-15 minutes as it fetches and builds all dependencies. Subsequent builds are cached and near-instant. Binary caches can speed up the first build if available.