Setting up OpenClaw with Nix

I have spent too many hours fixing broken environments after a system update. You know the drill: you change one config file, forget about it, and weeks later nothing works because a dependency shifted. I prefer a setup that stays exactly how I left it, which is why I use Nix for my OpenClaw installation.

The best way to get this running is via nix-openclaw. It is a Home Manager module that handles the heavy lifting. It gives you a pinned gateway, the macOS app, and tools like Whisper or Spotify without the manual configuration headache.

What You’ll Need

Before starting, make sure you have these four items ready:

1. Determinate Nix installed on your machine.
2. A Telegram bot token from @BotFather.
3. Your Telegram chat ID from @userinfobot.
4. An Anthropic API key.

Quick Start

I find the fastest path is to let an AI agent handle the initial file creation. Copy and paste this prompt into Claude or Cursor:

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.

Once you run home-manager switch, you get a few specific benefits:

• A launchd service that survives reboots.
• A plugin system with declarative config.
• Instant rollbacks via home-manager switch --rollback.
• A pinned macOS app and tools.

Troubleshooting

If you run into issues, it is usually related to how macOS handles environment variables or where files are stored.

The macOS GUI app isn’t picking up Nix mode On macOS, the GUI app does not automatically inherit shell environment variables. If you need to enable Nix mode manually for the desktop app, run this command in your terminal:

defaults write bot.molt.mac openclaw.nixMode -bool true

Config and state paths When OPENCLAW_NIX_MODE=1 is active, OpenClaw disables auto-install flows to keep things deterministic. You should explicitly set these variables in your Nix config so state stays out of the immutable Nix store:

• OPENCLAW_STATE_DIR (defaults to ~/.openclaw)
• OPENCLAW_CONFIG_PATH (defaults to $OPENCLAW_STATE_DIR/openclaw.json)
• OPENCLAW_HOME (used for internal path resolution)

Missing dependencies If a dependency is missing while in Nix mode, the UI will surface a specific remediation message rather than trying to install it automatically.

If you hit a wall during the setup, you can ask the AI Setup Assistant for help with your specific config.

What’s Next

• nix-openclaw — The full setup guide and source of truth.
• Wizard — If you prefer a non-Nix CLI setup.
• Docker — For containerized installations.
• Configuration — Details on JSON5 configuration options.