Files
nixos-setup/OPENCLAW-SETUP.md
T
2026-06-26 16:07:47 -04:00

4.5 KiB

OpenClaw Integration Setup

✅ Integration Complete!

I've successfully added OpenClaw to your nixos-setup with a simple NixOS systemd service. No Home Manager required - it's a pure system service.

Changes Made

1. Updated flake.nix

  • Added nix-openclaw as a new input from github:openclaw/nix-openclaw
  • Configured it to follow your existing nixpkgs and home-manager versions
  • Added nix-openclaw to the outputs destructuring
  • Passed nix-openclaw through to specialArgs for access in modules

2. Created modules/nixos/server/services/openclaw.nix

A complete NixOS module that provides:

  • skyg.nixos.server.services.openclaw.enable - enable/disable the service
  • skyg.nixos.server.services.openclaw.port - gateway port (default: 18789)
  • skyg.nixos.server.services.openclaw.gatewayToken - authentication token
  • skyg.nixos.server.services.openclaw.user - service user (default: openclaw)
  • skyg.nixos.server.services.openclaw.logLevel - log level (debug/info/warn/error)
  • skyg.nixos.server.services.openclaw.package - custom OpenClaw package

Features:

  • ✅ Automatic user/group creation
  • ✅ Systemd service management (auto-restart on failure)
  • ✅ Security hardening (strict filesystem protection, no new privileges, private tmp)
  • ✅ Automatic firewall port opening
  • ✅ Journal logging integration

3. Updated modules/nixos/server/services/default.nix

  • Added ./openclaw.nix to the services imports so it's available system-wide

How to Use

1. Enable on a Host

In your host configuration (e.g., hosts/hl-minipc3.nix):

skyg.nixos.server.services.openclaw = {
  enable = true;
  port = 18789;
  gatewayToken = "your-secret-gateway-token";
  logLevel = "info";
};

2. Manage Configuration

Configuration happens via:

  • Environment variables: Set via the service environment config
  • Config file (optional): Point to /etc/openclaw/openclaw.json via the configFile option
  • Default behavior: Service auto-creates /var/lib/openclaw as its working directory

3. Apply Changes

# Rebuild the system
sudo nixos-rebuild switch

# Or if using home-manager:
home-manager switch --flake .#

4. Verify It's Running

# Check service status
systemctl status openclaw-gateway

# View logs
journalctl -u openclaw-gateway -f

# Test gateway locally
curl http://localhost:18789/health

Simple Example Configuration

# In hosts/hl-minipc3.nix or similar
skyg.nixos.server.services.openclaw = {
  enable = true;
  port = 18789;
  gatewayToken = "mySecretToken123";
};

That's it! The service will:

  • Run as the openclaw user
  • Listen on port 18789
  • Auto-restart if it crashes
  • Log to systemd journal
  • Protect filesystem access (strict sandbox)

Multiple Instances

If you want multiple OpenClaw gateways on the same host with different ports:

# You'd need to duplicate the service with different names
# This is currently not supported by the module but could be extended
# Just ask if you need this!

Debugging

View real-time logs:

journalctl -u openclaw-gateway -f

Check service details:

systemctl cat openclaw-gateway

View environment variables:

systemctl show -p Environment openclaw-gateway

Architecture

flake.nix (nix-openclaw input)
    ↓
modules/lib.nix (specialArgs)
    ↓
modules/nixos/server/services/openclaw.nix
    ↓
systemd.services.openclaw-gateway
    ↓
/var/lib/openclaw (working directory)

Next Steps

  1. Choose a host where you want OpenClaw (e.g., hl-minipc3, hl-bigbox1)
  2. Add the skyg.nixos.server.services.openclaw config to that host
  3. Set your gatewayToken (generate a secure token)
  4. Run nixos-rebuild switch
  5. Monitor with journalctl -u openclaw-gateway -f

Resources

Troubleshooting

Service won't start:

journalctl -u openclaw-gateway -n 50

Port already in use: Change the port in your config:

skyg.nixos.server.services.openclaw.port = 18790;

Package not found: The module defaults to pkgs.openclaw. If this doesn't exist in nixpkgs yet, use the nix-openclaw flake output:

skyg.nixos.server.services.openclaw.package = nix-openclaw.packages.${system}.openclaw;

(You'd need to pass it through specialArgs or adjust the module)