How to Install OpenClaw with Nix

Nix is the OpenClaw install path for operators who care about reproducibility, rollback, and declarative configuration. The docs point to nix-openclaw as the source of truth, with the OpenClaw docs page acting as the quick overview. If you are already using Nix, NixOS, or Home Manager, this is the cleanest way to pin the Gateway, macOS app, tools, plugins, services, and config shape.

30-second answer

Install Determinate Nix if needed, create a local flake from the nix-openclaw agent-first template, configure secrets, fill in placeholders, and run home-manager switch. Then verify the launchd or systemd service and confirm your bot responds. If something breaks, use home-manager switch --rollback to return to the previous generation.

Where it fits

Use Nix when you want the assistant host to be rebuilt rather than hand-tuned. It is especially good for long-lived operator machines, reproducible agent setups, and teams that want config reviewed in Git. It is less ideal if you want a quick one-off install and do not already understand flakes, Home Manager, or Nix secret handling.

Docs-grounded facts

• nix-openclaw is the source of truth for Nix installation.
• The Nix setup uses a Home Manager module.
• home-manager switch --rollback provides rollback.
• OPENCLAW_NIX_MODE=1 enables deterministic Nix mode.
• Nix mode disables auto-install and self-mutation flows.
• OPENCLAW_CONFIG_PATH and OPENCLAW_STATE_DIR control config and mutable state paths.

Set it up deliberately

The docs say nix-openclaw gives you the Gateway, macOS app, tools such as whisper, Spotify, and cameras, a launchd service that survives reboots, plugin system config, and rollback. Set provider and messaging secrets carefully. Plain files under ~/.secrets can work, but the important point is that secrets should be declared intentionally rather than pasted into random shell history.

Use it safely

Nix mode changes runtime behavior. When OPENCLAW_NIX_MODE=1 is set, OpenClaw disables auto-install and self-mutation flows, surfaces Nix-specific remediation for missing dependencies, and shows a read-only Nix mode banner in UI surfaces. On macOS, the GUI app may not inherit shell env vars, so the docs show enabling Nix mode through defaults as well.

Common mistakes

The common mistake is letting mutable state drift into the immutable store or expecting shell env vars to magically reach launchd and GUI contexts. Set OPENCLAW_CONFIG_PATH and OPENCLAW_STATE_DIR explicitly for Nix-managed locations. Another mistake is trying to use normal auto-fix flows when Nix mode intentionally disables self-mutation. Fix the flake or module instead.

Verification checklist

Confirm the service is running, the Gateway sees the intended config path, mutable state lands in the intended state directory, and provider keys resolve. Then test a real channel message. For rollback drills, change one harmless setting, switch, verify, roll back, and confirm the old behavior returns.

Playbook angle

The OpenClaw Playbook’s Nix recommendation is simple: use it when reproducibility is worth the learning curve. Agents become easier to trust when the host can be rebuilt, rolled back, and reviewed instead of remembered.

Operator note

How to Install OpenClaw with Nix works best when it is written into a small runbook instead of left as tribal knowledge. Record the intended owner, the exact config surface, the channel where results should appear, the allowed inputs, the expected output, and the rollback step. OpenClaw gives agents broad tools, but the durable value comes from making each tool boring, repeatable, and auditable. I would rather have one well-scoped Nix setup workflow that survives a restart than five clever demos nobody can safely run next week. If the runbook cannot explain when not to use it, keep refining before automation becomes default.

Keep the final proof simple: name the source doc, run the smallest check that proves the path works, and save the result where the next operator will look first.