mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-08 11:30:43 +00:00
9671a91590
docs/install/clawdock.md: renamed '## Related pages' to '## Related' for consistency with sibling install docs and converted the 3-bullet list into a CardGroup linking docker, docker-vm-runtime, and updating. docs/install/nix.md: replaced 2 typography characters with ASCII equivalents and converted the 3-bullet Related list into a CardGroup, adding an Updating card so readers wiring nix-openclaw next to a managed install see the upgrade path. docs/concepts/features.md: converted the 2-bullet Related list into a CardGroup, adding cross-links to channels and plugins so the page now points readers at both deeper concepts (experimental features, agent runtime) and direct surfaces (channels, plugins). docs/tools/pdf.md: replaced 2 typography characters with ASCII equivalents.
111 lines
4.0 KiB
Markdown
111 lines
4.0 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
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="nix-openclaw" href="https://github.com/openclaw/nix-openclaw" icon="arrow-up-right-from-square">
|
|
Source-of-truth Home Manager module and full setup guide.
|
|
</Card>
|
|
<Card title="Setup wizard" href="/start/wizard" icon="wand-magic-sparkles">
|
|
Non-Nix CLI setup walkthrough.
|
|
</Card>
|
|
<Card title="Docker" href="/install/docker" icon="docker">
|
|
Containerized setup as a non-Nix alternative.
|
|
</Card>
|
|
<Card title="Updating" href="/install/updating" icon="arrow-up-right-from-square">
|
|
Updating Home Manager-managed installs alongside the package.
|
|
</Card>
|
|
</CardGroup>
|