openclaw/docs/install/nix.md at main

mirror of https://github.com/openclaw/openclaw.git synced 2026-04-28 06:31:11 +00:00

docs: cover new contextInjection 'never' mode and Nix daemon PATH support

Two recent code changes lacked or had only partial doc coverage:

- contextInjection 'never' (#65006, xDarkicex): the new mode is now
  documented under agents.defaults.contextInjection, alongside the
  existing 'continuation-skip' mode, with guidance on when to use it
  (custom context engines, native runtimes that own their prompt).
- Nix Home Manager daemon PATH (#44402, jerome.benoit): document the
  service PATH auto-discovery (NIX_PROFILES right-to-left precedence
  and ~/.nix-profile/bin fallback) under the Nix install page.

Also sentence-case three Title-Cased headings on the Nix page ('What
You Get', 'Quick Start', 'Nix Mode Runtime Behavior') and drop a
duplicate body H1 that restated the frontmatter title.

2026-04-24 23:19:06 -07:00

3.6 KiB

Raw Permalink Blame History

summary

read_when

title

Install OpenClaw declaratively with Nix

You want reproducible, rollback-able installs

You're already using Nix/NixOS/Home Manager

You want everything pinned and managed declaratively

Nix

Install OpenClaw declaratively with nix-openclaw — a batteries-included Home Manager module.

The [nix-openclaw](https://github.com/openclaw/nix-openclaw) repo is the source of truth for Nix installation. This page is a quick overview.

What you get

Gateway + macOS app + tools (whisper, spotify, cameras) -- all pinned
Launchd service that survives reboots
Plugin system with declarative config
Instant rollback: home-manager switch --rollback

Quick start

If Nix is not already installed, follow the [Determinate Nix installer](https://github.com/DeterminateSystems/nix-installer) instructions. Use the agent-first template from the nix-openclaw repo: ```bash mkdir -p ~/code/openclaw-local # Copy templates/agent-first/flake.nix from the nix-openclaw repo ``` Set up your messaging bot token and model provider API key. Plain files at `~/.secrets/` work fine. ```bash home-manager switch ``` Confirm the launchd service is running and your bot responds to messages.

See the nix-openclaw README for full module options and examples.

Nix-mode runtime behavior

When OPENCLAW_NIX_MODE=1 is set (automatic with nix-openclaw), OpenClaw enters a deterministic mode that disables auto-install flows.

You can also set it manually:

export OPENCLAW_NIX_MODE=1

On macOS, the GUI app does not automatically inherit shell environment variables. Enable Nix mode via defaults instead:

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

What changes in Nix mode

Auto-install and self-mutation flows are disabled
Missing dependencies surface Nix-specific remediation messages
UI surfaces a read-only Nix mode banner

Config and state paths

OpenClaw reads JSON5 config from OPENCLAW_CONFIG_PATH and stores mutable data in OPENCLAW_STATE_DIR. When running under Nix, set these explicitly to Nix-managed locations so runtime state and config stay out of the immutable store.

Variable	Default
`OPENCLAW_HOME`	`HOME` / `USERPROFILE` / `os.homedir()`
`OPENCLAW_STATE_DIR`	`~/.openclaw`
`OPENCLAW_CONFIG_PATH`	`$OPENCLAW_STATE_DIR/openclaw.json`

Service PATH discovery

The launchd/systemd gateway service auto-discovers Nix-profile binaries so plugins and tools that shell out to nix-installed executables work without manual PATH setup:

When NIX_PROFILES is set, every entry is added to the service PATH in right-to-left precedence (matches Nix shell precedence — rightmost wins).
When NIX_PROFILES is unset, ~/.nix-profile/bin is added as a fallback.

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

nix-openclaw -- full setup guide
Wizard -- non-Nix CLI setup
Docker -- containerized setup

3.6 KiB Raw Permalink Blame History