mirror of
https://github.com/openclaw/openclaw.git
synced 2026-02-19 18:39:20 -05:00
db137dd65d
* fix(paths): respect OPENCLAW_HOME for all internal path resolution (#11995) Add home-dir module (src/infra/home-dir.ts) that centralizes home directory resolution with precedence: OPENCLAW_HOME > HOME > USERPROFILE > os.homedir(). Migrate all path-sensitive callsites: config IO, agent dirs, session transcripts, pairing store, cron store, doctor, CLI profiles. Add envHomedir() helper in config/paths.ts to reduce lambda noise. Document OPENCLAW_HOME in docs/help/environment.md. * fix(paths): handle OPENCLAW_HOME '~' fallback (#12091) (thanks @sebslight) * docs: mention OPENCLAW_HOME in install and getting started (#12091) (thanks @sebslight) * fix(status): show OPENCLAW_HOME in shortened paths (#12091) (thanks @sebslight) * docs(changelog): clarify OPENCLAW_HOME and HOME precedence (#12091) (thanks @sebslight)
99 lines
3.4 KiB
Markdown
99 lines
3.4 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
|
|
|
|
The recommended way to run OpenClaw with Nix is via **[nix-openclaw](https://github.com/openclaw/nix-openclaw)** — a batteries-included Home Manager module.
|
|
|
|
## Quick Start
|
|
|
|
Paste this to your AI agent (Claude, Cursor, etc.):
|
|
|
|
```text
|
|
I want to set up nix-openclaw on my Mac.
|
|
Repository: github:openclaw/nix-openclaw
|
|
|
|
What I need you to do:
|
|
1. Check if Determinate Nix is installed (if not, install it)
|
|
2. Create a local flake at ~/code/openclaw-local using templates/agent-first/flake.nix
|
|
3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
|
|
4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
|
|
5. Fill in the template placeholders and run home-manager switch
|
|
6. Verify: launchd running, bot responds to messages
|
|
|
|
Reference the nix-openclaw README for module options.
|
|
```
|
|
|
|
> **📦 Full guide: [github.com/openclaw/nix-openclaw](https://github.com/openclaw/nix-openclaw)**
|
|
>
|
|
> The nix-openclaw repo is the source of truth for Nix installation. This page is just 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`
|
|
|
|
---
|
|
|
|
## Nix Mode Runtime Behavior
|
|
|
|
When `OPENCLAW_NIX_MODE=1` is set (automatic with nix-openclaw):
|
|
|
|
OpenClaw supports a **Nix mode** that makes configuration deterministic and disables auto-install flows.
|
|
Enable it by exporting:
|
|
|
|
```bash
|
|
OPENCLAW_NIX_MODE=1
|
|
```
|
|
|
|
On macOS, the GUI app does not automatically inherit shell env vars. You can
|
|
also enable Nix mode via defaults:
|
|
|
|
```bash
|
|
defaults write bot.molt.mac openclaw.nixMode -bool true
|
|
```
|
|
|
|
### Config + state paths
|
|
|
|
OpenClaw reads JSON5 config from `OPENCLAW_CONFIG_PATH` and stores mutable data in `OPENCLAW_STATE_DIR`.
|
|
When needed, you can also set `OPENCLAW_HOME` to control the base home directory used for internal path resolution.
|
|
|
|
- `OPENCLAW_HOME` (default precedence: `HOME` / `USERPROFILE` / `os.homedir()`)
|
|
- `OPENCLAW_STATE_DIR` (default: `~/.openclaw`)
|
|
- `OPENCLAW_CONFIG_PATH` (default: `$OPENCLAW_STATE_DIR/openclaw.json`)
|
|
|
|
When running under Nix, set these explicitly to Nix-managed locations so runtime state and config
|
|
stay out of the immutable store.
|
|
|
|
### Runtime behavior 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 when present
|
|
|
|
## Packaging note (macOS)
|
|
|
|
The macOS packaging flow expects a stable Info.plist template at:
|
|
|
|
```
|
|
apps/macos/Sources/OpenClaw/Resources/Info.plist
|
|
```
|
|
|
|
[`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) copies this template into the app bundle and patches dynamic fields
|
|
(bundle ID, version/build, Git SHA, Sparkle keys). This keeps the plist deterministic for SwiftPM
|
|
packaging and Nix builds (which do not rely on a full Xcode toolchain).
|
|
|
|
## Related
|
|
|
|
- [nix-openclaw](https://github.com/openclaw/nix-openclaw) — full setup guide
|
|
- [Wizard](/start/wizard) — non-Nix CLI setup
|
|
- [Docker](/install/docker) — containerized setup
|