OpenClaw on Nix

Nix users get a first-party route: nix-openclaw, the batteries-included Home Manager module the docs call the source of truth for Nix installation, with the docs page as a quick overview. Here is what the module gives you, the quick start, what Nix mode changes inside OpenClaw once the install is declarative, where config and state live, and how the service finds Nix-installed binaries.

What you get

• The Gateway, the macOS app and tools such as whisper, spotify and cameras, all pinned.
• A launchd service that survives reboots, and a plugin system with declarative config.
• Instant rollback with a single Home Manager switch back to the previous generation.
• The quick start: install Determinate Nix, copy the agent-first flake template from the repository into a local directory, put the bot token and the model provider key in plain files under your secrets directory, fill in the placeholders, switch, then confirm the launchd service is running and the bot answers.

openclaw.json is treated as immutable.

Nix mode

When the Nix mode variable is set, automatic with nix-openclaw, OpenClaw enters a deterministic mode for Nix-managed installs. Auto-install and self-mutation flows are disabled. The config file is immutable: startup-derived defaults stay runtime-only, and every config writer, setup, onboarding, a mutating update, plugin install, update, uninstall or enable, the doctor’s fix and token generation, and the config set command, refuses to edit it; you edit the Nix source instead, under the module’s config options. Missing dependencies surface Nix-specific remediation messages, and the UI shows a read-only Nix mode banner. On macOS the GUI app does not inherit shell variables, so Nix mode is enabled through a defaults write instead.

Paths and the service PATH

• OpenClaw reads JSON5 config from the config path variable and stores mutable data in the state directory; under Nix both are set explicitly to Nix-managed locations so state and config stay out of the immutable store.
• The defaults: the home variable falls back to the user’s home, the state directory to the .openclaw folder in it, and the config path to openclaw.json inside the state directory.
• The launchd or systemd service adds every entry of the Nix profiles variable to its PATH in right-to-left precedence, or the user profile’s bin directory when the variable is unset, so plugins and tools that shell out to Nix-installed executables work without manual setup.

OpenClaw config explains the file Nix mode freezes, and Updating OpenClaw the update path for a Home Manager-managed install.

Without Nix

The same immutable-config enforcement exists for any externally managed config: a read-only config variable applies it with generic messaging and none of the Nix-specific behavior, which is the docs’ suggestion for people who manage the file with something other than Nix. Install OpenClaw on a Mac is the conventional macOS install and OpenClaw on Docker the containerised alternative the page lists.

On Diali

Diali runs the same discipline without the flake: the config is generated for each assistant from the dashboard, validated before it is written and replaced on every release, so nothing edits it on the box. Hosted OpenClaw on Diali is the assistant.

• A Home Manager module, pinned end to end.
• Nix mode freezes the config and disables self-mutation.
• Rollback is one switch.