90 lines
3.1 KiB
Markdown
90 lines
3.1 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"
|
|
---
|
|
|
|
# Nix Installation
|
|
|
|
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` |
|
|
|
|
## Related
|
|
|
|
- [nix-openclaw](https://github.com/openclaw/nix-openclaw) -- full setup guide
|
|
- [Wizard](/start/wizard) -- non-Nix CLI setup
|
|
- [Docker](/install/docker) -- containerized setup
|