mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-07 00:10:43 +00:00
b59ba1dc8e
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.
100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
---
|
|
summary: "Install OpenClaw declaratively with Nix"
|
|
read_when:
|
|
- You want reproducible, rollback-able installs
|
|
- You're already using Nix/NixOS/Home Manager
|
|
- You want everything pinned and managed declaratively
|
|
title: "Nix"
|
|
---
|
|
|
|
Install OpenClaw declaratively with **[nix-openclaw](https://github.com/openclaw/nix-openclaw)** — a batteries-included Home Manager module.
|
|
|
|
<Info>
|
|
The [nix-openclaw](https://github.com/openclaw/nix-openclaw) repo is the source of truth for Nix installation. This page is a quick overview.
|
|
</Info>
|
|
|
|
## 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
|
|
|
|
<Steps>
|
|
<Step title="Install Determinate Nix">
|
|
If Nix is not already installed, follow the [Determinate Nix installer](https://github.com/DeterminateSystems/nix-installer) instructions.
|
|
</Step>
|
|
<Step title="Create a local flake">
|
|
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
|
|
```
|
|
</Step>
|
|
<Step title="Configure secrets">
|
|
Set up your messaging bot token and model provider API key. Plain files at `~/.secrets/` work fine.
|
|
</Step>
|
|
<Step title="Fill in template placeholders and switch">
|
|
```bash
|
|
home-manager switch
|
|
```
|
|
</Step>
|
|
<Step title="Verify">
|
|
Confirm the launchd service is running and your bot responds to messages.
|
|
</Step>
|
|
</Steps>
|
|
|
|
See the [nix-openclaw README](https://github.com/openclaw/nix-openclaw) 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:
|
|
|
|
```bash
|
|
export OPENCLAW_NIX_MODE=1
|
|
```
|
|
|
|
On macOS, the GUI app does not automatically inherit shell environment variables. Enable Nix mode via defaults instead:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Related
|
|
|
|
- [nix-openclaw](https://github.com/openclaw/nix-openclaw) -- full setup guide
|
|
- [Wizard](/start/wizard) -- non-Nix CLI setup
|
|
- [Docker](/install/docker) -- containerized setup
|