### Home Manager Configuration Example

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

This example shows a basic Home Manager configuration file, demonstrating how to manage user-specific settings and packages declaratively. Ensure Nix flakes are enabled.

```nix
# Example home.nix structure (conceptual)
{
  username = "your-user";
  homeDirectory = "/home/your-user";

  packages = with pkgs;
    [ 
      git 
      vim 
      wget 
      # Add other desired packages here
    ];

  programs.home-manager.enable = true;

  # Add other configurations for programs, services, etc.
  # Example: configure git
  programs.git = {
    enable = true;
    userName = "Your Name";
    userEmail = "your.email@example.com";
  };

  # Example: enable a service
  services.blueman.enable = true;

  # Link dotfiles
  home.file = {
    ".config/my-app/config.toml" = {
      source = ./my-app-config.toml;
      target = ".config/my-app/config.toml";
    };
  };

  # Apply changes
  home.stateVersion = "23.11"; # Or your NixOS/home-manager version
}
```

--------------------------------

### Agent-First Nix-OpenClaw Setup Prompt

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Use this prompt to instruct your coding agent to set up nix-openclaw. It details the repository, desired setup, and required information for the agent to gather.

```text
I want to set up nix-openclaw on my machine (Apple Silicon macOS or x86_64 Linux).

Repository: github:openclaw/nix-openclaw

What nix-openclaw is:
- Batteries-included Nix package for OpenClaw (AI assistant gateway)
- Installs the gateway everywhere; macOS app only on macOS
- Runs as a launchd service on macOS, systemd user service on Linux

What I need you to do:
1. Inspect my OS, CPU architecture, shell, Home Manager setup, and whether Nix with flakes is installed
2. Ask me only for missing choices: channel, bot/account secrets, allowed users, provider keys, and documents/identity preferences
3. Create a local flake at ~/code/openclaw-local using templates/agent-first/flake.nix
4. Create a docs dir next to the config (e.g., ~/code/openclaw-local/documents) with AGENTS.md, SOUL.md, TOOLS.md (optional: IDENTITY.md, USER.md, LORE.md, HEARTBEAT.md, PROMPTING-EXAMPLES.md)
   - If ~/.openclaw/workspace already has these files, adopt them into the documents dir first (use copy/rsync that dereferences symlinks, e.g. `cp -L`)
5. Help me create or connect the channel account I choose
6. Set up secrets (bot token, provider key) - plain files at ~/.secrets/ are fine unless I already have a secret manager
7. Ask whether I want local memory through QMD; if yes, set `memory.backend = "qmd"` in OpenClaw config
8. Fill in the template placeholders and run home-manager switch
9. Verify end-to-end: package builds, service is running, gateway health works, QMD works if enabled, and the bot/channel responds if configured

My setup:
- OS: [macOS / Linux]
- CPU: [arm64 / x86_64]
- System: [aarch64-darwin / x86_64-linux]
- Home Manager config name: [FILL IN or "I don't have Home Manager yet"]

Reference the README and templates/agent-first/flake.nix in the repo for the module options.
```

--------------------------------

### Voice-call Webhook Server Example

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/rfc/2026-01-11-plugin-system.md

Demonstrates the CLI commands to start a webhook server for voice-call functionality, initiate an agent call, and check call status. This pattern allows plugins to run background servers without direct agent knowledge.

```bash
voicecall expose --mode funnel    # Start webhook server
voicecall init --to +1... --message "..."  # Agent calls CLI
voicecall status --call-id abc123  # Check for responses
```

--------------------------------

### Nix Flake Configuration Example

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

This is a conceptual example of how a Nix flake might be structured to manage system configurations and dependencies. It's not directly executable but illustrates the declarative nature of Nix.

```nix
# Example flake.nix structure (conceptual)
{
  description = "My OpenClaw System";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, home-manager, ... }:
    {
      nixosConfigurations.my-machine = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./configuration.nix
          home-manager.nixosModules.home-manager
          { home-manager = { useGlobalPkgs = true; useUserPackages = true; extraSpecialArgs = { inherit self; }; }; }
        ];
      };
    };
}
```

--------------------------------

### Example Padel Court Booking Plugin Configuration

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Illustrates how to configure a custom plugin, specifying its source, environment variables for secrets, and user-defined settings.

```nix
customPlugins = [
  {
    source = "github:example/padel-cli?rev=<commit>&narHash=<narHash>";
    config = {
      env = {
        PADEL_AUTH_FILE = "~/.secrets/padel-auth";  # where your login token lives
      };
      settings = {
        default_city = "Barcelona";
        preferred_times = [ "18:00" "20:00" ];
      };
    };
  }
];
```

--------------------------------

### Nix Configuration for gohome Plugin

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/rfc/2026-01-11-plugin-system.md

Example Nix configuration for the 'gohome' plugin, specifying its name, skills, packages, and noting no specific state directories or required environment variables.

```nix
openclawPlugin = {
  name = "gohome";
  skills = [ ./skills/gohome ];
  packages = [ self.packages.${system}.default ];
  needs = {
    stateDirs = [];
    requiredEnv = [];
  };
};
```

--------------------------------

### Nix Configuration for xuezh Plugin

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/rfc/2026-01-11-plugin-system.md

Example Nix configuration for the 'xuezh' plugin, specifying its name, skills, packages, required state directories, and environment variables.

```nix
openclawPlugin = {
  name = "xuezh";
  skills = [ ./skills/xuezh ];
  packages = [ self.packages.${system}.default ];
  needs = {
    stateDirs = [ ".config/xuezh" ];
    requiredEnv = [
      "XUEZH_AZURE_SPEECH_KEY_FILE"
      "XUEZH_AZURE_SPEECH_REGION"
    ];
  };
};
```

--------------------------------

### Nix Configuration for padel Plugin

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/rfc/2026-01-11-plugin-system.md

Example Nix configuration for the 'padel' plugin, detailing its name, skills, packages, required state directories, and environment variables for court booking.

```nix
openclawPlugin = {
  name = "padel";
  skills = [ ./skills/padel ];
  packages = [ self.packages.${system}.default ];
  needs = {
    stateDirs = [ ".config/padel" ];
    requiredEnv = [ "PADEL_AUTH_FILE" ];
  };
};
```

--------------------------------

### NixOS Configuration for OpenCLAW Gateway

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Example NixOS configuration snippet for enabling and configuring the OpenCLAW gateway service. This is typically used in a VPS setup.

```nix
services.openclaw-gateway = {
  enable         = true;
  environmentFile = "/run/secrets/openclaw-env";
  config = {
    gateway.mode        = "local";
    channels.telegram   = { tokenFile = "/run/secrets/tg-token"; allowFrom = [ 12345678 ]; };
  };
};

```

--------------------------------

### Markdown Skill Example for gohome

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/rfc/2026-01-11-plugin-system.md

Illustrates how the 'gohome' plugin's skill documentation teaches the agent to interact with home automation devices via CLI commands and media URLs.

```markdown
## Friendly CLI
gohome-cli roborock status
gohome-cli roborock clean kitchen
gohome-cli tado set living-room 20

## Sending maps to users
MEDIA:http://gohome:8080/roborock/map.png?labels=names
```

--------------------------------

### Configure OpenClaw with QMD Memory Backend

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Nix configuration to enable the QMD local memory backend for OpenClaw. This requires no separate installation of QMD.

```nix
programs.openclaw.config = {
  memory.backend = "qmd";
};
```

--------------------------------

### SKILL.md for AI Instruction

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

An example `SKILL.md` file that instructs the AI on how to use a plugin's CLI tool, including its name and a brief description of its function.

```markdown
---
name: hello-world
description: Prints hello world.
---

Use the `hello` CLI to print a greeting.
```

--------------------------------

### Voice-Call CLI Commands

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/rfc/2026-01-11-plugin-system.md

Example command-line interface commands for the voice-call plugin. These demonstrate initialization, continuation of calls, and exposure modes.

```bash
voicecall init --to +1... --mode conversation --message "..."
voicecall continue --call-id ... --message "..."
voicecall expose --mode funnel|serve|off
```

--------------------------------

### Configure Custom GitHub Plugin

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/plugins-maintainers.md

Example of enabling a custom plugin from GitHub with environment variables and settings. Ensure required environment variables point to files and settings are JSON-renderable.

```nix
programs.openclaw.customPlugins = [
  {
    source = "github:owner/repo?rev=<commit>&narHash=<narHash>";
    config = {
      env = { KEY = "/run/agenix/key"; EXTRA = "/path/to/file"; };
      settings = { foo = "bar"; retries = 3; };
    };
  }
];
```

--------------------------------

### Example Bot Interactions

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Illustrates typical interactions with the OpenClaw bot for tasks like screen description, music playback, and transcription.

```text
Me: "what's on my screen?"
Bot: *takes screenshot, describes it*

Me: "play some jazz"
Bot: *opens Spotify, plays jazz*

Me: "transcribe this voice note"
Bot: *runs whisper, sends you text*
```

--------------------------------

### Enable Bundled OpenClaw Plugins

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Configure which bundled plugins to enable in your OpenClaw setup. Some plugins may require additional configuration, such as API keys.

```nix
programs.openclaw.bundledPlugins = {
  summarize.enable = true;   # Summarize web pages, PDFs, videos
  discrawl.enable = false;    # Discord archive/search
  wacrawl.enable = false;     # WhatsApp archive/search
  peekaboo.enable = true;    # Take screenshots
  poltergeist.enable = false; # File watching and automation
  sag.enable = false;        # Text-to-speech
  camsnap.enable = false;    # Camera snapshots
  gogcli.enable = false;     # Google Calendar
  goplaces.enable = true;    # Google Places API
  sonoscli.enable = false;   # Sonos control
  imsg.enable = false;       # iMessage
};

# Optional config for bundled plugins
programs.openclaw.bundledPlugins.goplaces = {
  enable = true;
  config.env.GOOGLE_PLACES_API_KEY = "/run/agenix/google-places-api-key";
};
```

--------------------------------

### Enable Community Xuezh Plugin

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/plugins-maintainers.md

Example of enabling the 'xuezh' community plugin with specific environment variables and settings. Host behavior includes creating config files and exporting envs, failing if pointed files are missing.

```nix
programs.openclaw.customPlugins = [
  {
    source = "github:joshp123/xuezh?rev=<commit>&narHash=<narHash>";
    config = {
      env = {
        # Required envs (guarded as files):
        XUEZH_AZURE_SPEECH_KEY_FILE = "/run/agenix/xuezh-azure-speech-key";
        XUEZH_AZURE_SPEECH_REGION   = "/run/agenix/xuezh-azure-speech-region"; # file containing e.g. "westeurope"
      };
      settings = {
        audio = {
          backend_global        = "azure.speech";
          process_voice_backend = "azure.speech";
          convert_backend       = "ffmpeg";
          tts_backend           = "edge-tts";
          inline_max_bytes      = 200000;
        };
        azure = {
          speech = {
            key_file = "/run/agenix/xuezh-azure-speech-key";
            region   = "westeurope";
          };
        };
      };
    };
  }
];
```

--------------------------------

### Nix-OpenClaw Plugin Installation Configuration

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/rfc/2026-01-11-plugin-system.md

Shows how to configure custom plugins in a user's Nix flake. This includes specifying remote GitHub sources and local development paths, as well as enabling bundled plugins.

```nix
# User's flake.nix
programs.openclaw.customPlugins = [
  # Remote: point at GitHub repo
  { source = "github:joshp123/xuezh"; }
  { source = "github:joshp123/padel-cli"; }

  # Local dev: point at directory
  { source = "path:/home/user/code/my-plugin"; }
];

# Or enable bundled plugins (pinned in nix-openclaw):
programs.openclaw.bundledPlugins.summarize.enable = true;
programs.openclaw.bundledPlugins.oracle.enable = true;
```

--------------------------------

### Configure OpenClaw Packages Overlay

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Use the Pkgs overlay to inject openclaw, openclaw-gateway, and openclaw-app into a nixpkgs instance. This example shows how to use the overlay to define default packages and build custom tool sets.

```nix
# Using the overlay in a custom flake
{
  inputs.nix-openclaw.url = "github:openclaw/nix-openclaw";
  inputs.nixpkgs.url      = "github:NixOS/nixpkgs/nixos-unstable";

  outputs = { self, nix-openclaw, nixpkgs }:
    let
      system = "x86_64-linux";
      pkgs   = import nixpkgs {
        inherit system;
        overlays = [ nix-openclaw.overlays.default ];
      };
    in {
      # pkgs.openclaw          — batteries-included default package
      # pkgs.openclaw-gateway  — gateway binary only
      # pkgs.openclawPackages.toolNames — list of bundled runtime tool names

      packages.${system}.default = pkgs.openclaw;

      # Build a custom batteries bundle with a reduced tool set
      packages.${system}.slim = pkgs.openclawPackages.withTools {
        tools = with pkgs; [ nodejs git jq curl ];
      };
    };
}
```

--------------------------------

### Configure Custom NPM Plugin

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/plugins-maintainers.md

Example of enabling a custom plugin from an npm registry. An `id` is required for the Home Manager module to enable the plugin at eval time, and a `hash` is needed for immutability.

```nix
programs.openclaw.customPlugins = [
  {
    source = "npm:@scope/openclaw-plugin@1.2.3";
    id = "openclaw-plugin";
    hash = lib.fakeHash; # replace with the sha256 Nix reports
  }
];
```

--------------------------------

### Dual-Instance OpenClaw Nix Configuration (Prod + Dev)

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Configure two local OpenClaw gateways using named instances. This setup is useful for maintaining separate production and development environments. The default package is recommended unless actively debugging a local gateway checkout.

```nix
programs.openclaw = {
  documents = ./documents;

  instances = {
    prod = {
      enable = true;
      gatewayPort = 18789;
      config.channels.telegram = {
        tokenFile = "/run/agenix/telegram-prod";
        allowFrom = [ 12345678 ];
      };
      plugins = [
        { source = "github:owner/your-plugin?rev=<commit>&narHash=<narHash>"; }
      ];
    };

    dev = {
      enable = true;
      gatewayPort = 18790;
      gatewayPath = "/Users/you/code/openclaw";
      config.channels.telegram = {
        tokenFile = "/run/agenix/telegram-dev";
        allowFrom = [ 12345678 ];
      };
      plugins = [
        { source = "path:/Users/you/code/your-plugin"; }
      ];
    };
  };
};

```

--------------------------------

### Full Plugin Authoring Prompt for AI Agent

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

A comprehensive prompt to guide an AI agent in transforming a repository into a compliant OpenClaw plugin, detailing the contract, configuration, and deliverables.

```text
Goal: Make this repo a nix-openclaw-native plugin with the standard contract.

Contract to implement:
1) Add openclawPlugin output in flake.nix:
   - name
   - skills (paths to SKILL.md dirs)
   - packages (CLI packages to put on the OpenClaw runtime PATH)
   - needs (stateDirs + requiredEnv)

Example:
openclawPlugin = {
  name = "my-plugin";
  skills = [ ./skills/my-plugin ];
  packages = [ self.packages.${system}.default ];
  needs = {
    stateDirs = [ ".config/my-plugin" ];
    requiredEnv = [ "MYPLUGIN_AUTH_FILE" ];
  };
};

2) Make the CLI explicitly configurable by env (no magic defaults):
   - Support an auth file env (e.g., MYPLUGIN_AUTH_FILE)
   - Honor XDG_CONFIG_HOME or a plugin-specific config dir env

3) Provide AGENTS.md in the plugin repo:
   - Plain-English explanation of knobs + values
   - Generic placeholders only (no real secrets)
   - Explain where credentials live (e.g., /run/agenix/...)

4) Update SKILL.md to call the CLI by its PATH name.

Standard plugin config shape (Nix-native, no JSON strings):

customPlugins = [
  {
    source = "github:owner/my-plugin?rev=<commit>&narHash=<narHash>";
    config = {
      env = {
        MYPLUGIN_AUTH_FILE = "/run/agenix/myplugin-auth";
      };
      settings = {
        name = "EXAMPLE_NAME";
        enabled = true;
        retries = 3;
        tags = [ "alpha" "beta" ];
        window = { start = "08:00"; end = "18:00"; };
        options = { mode = "fast"; level = 2; };
      };
    };
  }
];

Config flags the host will use:
- `config.env` for required env vars (e.g., MYPLUGIN_AUTH_FILE)
- `config.settings` for typed config keys (rendered to config.json in the first stateDir)

CI note:
- If the repo uses Garnix, add the plugin build to its `garnix.yaml` (or equivalent) so CI verifies it.

Why: explicit, minimal, fail-fast, no inline JSON strings.
Deliverables: flake output, env overrides, AGENTS.md, skill update.
```

--------------------------------

### Extending OpenClaw with a Plugin Declaration in Nix

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/plugins-maintainers.md

Example of how to extend the `openclawPlugin` in Nix to include an OpenClaw plugin artifact, specifying its ID, path, and enabled status.

```nix
plugins = [ { id = "openclaw-weixin"; path = "${pkg}/lib/openclaw/plugins/openclaw-weixin"; enabled = true; } ];
```

--------------------------------

### Create an OpenClaw Plugin with `openclawPlugin`

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Export an `openclawPlugin` attribute in your Nix flake to make it compatible with OpenClaw. The host module handles package installation, state directory creation, environment injection, and skill symlinks.

```nix

```

--------------------------------

### Scaffold and Apply OpenClaw Configuration with Agent-First Template

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Initialize a new OpenClaw project using the `agent-first` flake template. After filling in placeholders in `flake.nix` and `home.nix`, apply the configuration using `home-manager switch`. Includes commands to verify the service status on macOS and Linux.

```nix
# Scaffold a new local OpenClaw configuration
mkdir -p ~/code/openclaw-local && cd ~/code/openclaw-local
nix flake init -t github:openclaw/nix-openclaw#agent-first

# Resulting flake.nix after filling in placeholders:
{
  description = "My OpenClaw configuration";

  inputs = {
    nix-openclaw.url = "github:openclaw/nix-openclaw";
    nixpkgs.follows = "nix-openclaw/nixpkgs";
    home-manager.follows = "nix-openclaw/home-manager";
  };

  outputs = { self, nix-openclaw, nixpkgs, home-manager }:
    let
      system = "aarch64-darwin"; # or "x86_64-linux"
      pkgs = import nixpkgs { inherit system; overlays = [ nix-openclaw.overlays.default ]; };
    in {
      homeConfigurations.alice = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;
        modules = [ nix-openclaw.homeManagerModules.openclaw ./home.nix ];
        extraSpecialArgs = { inherit nix-openclaw; };
      };
    };
}

# Apply configuration
home-manager switch --flake .#alice

# Verify service is running (macOS)
launchctl print gui/$UID/com.steipete.openclaw.gateway | grep state

# Verify service is running (Linux)
systemctl --user status openclaw-gateway
journalctl --user -u openclaw-gateway -f
```

--------------------------------

### List and Build Nix Flake Outputs

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Use `nix flake show` to list available outputs and `nix build` to construct specific packages like the default OpenClaw bundle, the gateway binary, or the macOS app. Also includes commands for dogfood builds and CI checks.

```nix
# List all flake outputs for the current system
# nix flake show github:openclaw/nix-openclaw

# Build the batteries-included default package (gateway + runtime tools + optional QMD + macOS app)
nix build github:openclaw/nix-openclaw#openclaw

# Build only the gateway binary (no runtime tool wrappers)
nix build github:openclaw/nix-openclaw#openclaw-gateway

# Build the macOS app bundle (Darwin only)
nix build github:openclaw/nix-openclaw#openclaw-app

# Run the dogfood (internal dev) build
nix build github:openclaw/nix-openclaw#openclaw-dogfood

# Run the CI aggregator check (gateway + all validation checks)
nix build github:openclaw/nix-openclaw#checks.x86_64-linux.ci
nix build github:openclaw/nix-openclaw#checks.aarch64-darwin.ci
```

--------------------------------

### Build npm Runtime Plugin with Nix

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Builds an immutable JavaScript OpenClaw plugin from an npm package at derivation time. This avoids runtime `npm install` operations.

```nix
# Using the npm runtime plugin builder directly
{ pkgs, nix-openclaw }:
let
  buildNpmRuntimePlugin = pkgs.callPackage "${nix-openclaw}/nix/lib/npm-runtime-plugin.nix" {};
in
buildNpmRuntimePlugin {
  source  = "npm:@acme/openclaw-summarizer@2.1.0";
  id      = "acme-summarizer";
  hash    = "sha256-EEEE..."; # sha256 of the unpacked npm package
}

# In Home Manager config — equivalent declarative form:
programs.openclaw.customPlugins = [
  {
    source = "npm:@acme/openclaw-summarizer@2.1.0";
    id     = "acme-summarizer";
    hash   = "sha256-EEEE...";
  }
];

```

--------------------------------

### Enable QMD Local Memory with Home Manager

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Opt-in to the QMD local vector-search memory backend within your Home Manager configuration. This snippet shows how to set the memory backend and optionally prewarm GGUF models.

```nix
programs.openclaw = {
  enable = true;

  config = {
    memory.backend = "qmd"; # opt in to local memory

    # Other config...
    gateway.mode   = "local";
    gateway.auth.token = "my-token";
    channels.telegram  = { tokenFile = "/run/agenix/telegram"; allowFrom = [ 12345678 ]; };
  };

  # Optional: warm GGUF models during activation (one-time download, ~2.25 GB)
  qmd.prewarmModels.enable = true;
};

# After home-manager switch, query the gateway smoke endpoint to confirm QMD
# curl -s -H "Authorization: Bearer my-token" http://localhost:18788/health | jq .
# Expected: { "status": "ok", "memory": { "backend": "qmd" } }
```

--------------------------------

### Enable OpenCLAW with Basic Configuration

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Enables the OpenCLAW service and configures the local gateway and Telegram channel. Ensure the token file is readable and the Telegram user ID is correct.

```nix
programs.openclaw = {
  enable   = true;
  documents = ./documents; # directory with AGENTS.md, SOUL.md, TOOLS.md

  config = {
    gateway = {
      mode = "local";
      auth.token = "my-gateway-token"; # or set OPENCLAW_GATEWAY_TOKEN env var
    };
    channels.telegram = {
      tokenFile  = "/run/agenix/telegram-bot-token"; # any readable file path
      allowFrom  = [ 12345678 ]; # your Telegram user ID (from @userinfobot) 
    };
  };

  # Enable local memory backend (downloads ~2.25 GB of GGUF models)
  # programs.openclaw.config.memory.backend = "qmd";
};

```

--------------------------------

### Expose Plugin Packages

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Nix configuration to expose plugin CLIs to the user's login shell PATH. This is typically only needed when managing `node-llama-cpp` separately.

```nix
programs.openclaw.exposePluginPackages = true;
```

--------------------------------

### Initialize Local Nix-OpenClaw Flake

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Use this command to initialize a new local Nix flake for OpenClaw using the agent-first template. Ensure you are in the desired directory before running.

```bash
mkdir -p ~/code/openclaw-local && cd ~/code/openclaw-local
nix flake init -t github:openclaw/nix-openclaw#agent-first
```

--------------------------------

### Enable Bundled Summarize Plugin

Source: https://github.com/openclaw/nix-openclaw/blob/main/docs/plugins-maintainers.md

Enables the bundled 'summarize' plugin on the host side.

```nix
programs.openclaw.bundledPlugins.summarize.enable = true;
```

--------------------------------

### Configure System-Level Gateway Service on NixOS

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Run openclaw-gateway as a systemd service on NixOS for headless servers. Configuration and state are managed under /etc/openclaw and /var/lib/openclaw. Secrets should be managed via environment files.

```nix
# /etc/nixos/configuration.nix
{
  imports = [
    (builtins.fetchTarball "github:openclaw/nix-openclaw").nixosModules.openclaw-gateway
  ];

  services.openclaw-gateway = {
    enable      = true;
    stateDir    = "/var/lib/openclaw"; # default
    configPath  = "/etc/openclaw/openclaw.json";

    # Config is deep-merged; secrets live in environmentFile, never in the Nix store
    environmentFile = "/run/secrets/openclaw-env"; # contains OPENCLAW_GATEWAY_TOKEN=...

    config = {
      gateway = {
        mode = "local";
        auth.token = ""; # override via OPENCLAW_GATEWAY_TOKEN in environmentFile
      };
      channels.telegram = {
        tokenFile = "/run/secrets/telegram-bot-token";
        allowFrom = [ 12345678 ];
      };
    };
  };
}

# Check service status
# systemctl status openclaw-gateway
# journalctl -u openclaw-gateway -f
```

--------------------------------

### Run Full CI Aggregator

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Execute the complete CI process, which builds the gateway once and then validates all checks. This is useful for a comprehensive test run.

```bash
nix build .#checks.x86_64-linux.ci
nix build .#checks.aarch64-darwin.ci
```

--------------------------------

### Enable Optional Model Prewarming

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Nix configuration to enable optional model prewarming for QMD. This process uses `qmd update`, `qmd embed`, and `qmd query` during Home Manager activation and is expected to use approximately 2.25GB of cache space.

```nix
programs.openclaw.qmd.prewarmModels.enable = true;
```

--------------------------------

### Configure Multi-Instance OpenCLAW

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Sets up multiple independent OpenCLAW instances with distinct ports, state directories, and plugin sets. Useful for running production and development versions side-by-side. Local source checkouts and paths can be specified for development instances.

```nix
programs.openclaw = {
  documents = ./documents;

  instances = {
    prod = {
      enable      = true;
      gatewayPort = 18789;
      config.channels.telegram = {
        tokenFile = "/run/agenix/telegram-prod";
        allowFrom = [ 12345678 ];
      };
      plugins = [
        { source = "github:owner/stable-plugin?rev=abc&narHash=sha256-..."; }
      ];
    };

    dev = {
      enable          = true;
      gatewayPort     = 18790;
      gatewayPath     = "/Users/alice/code/openclaw";       # local source checkout
      gatewayPnpmDepsHash = "sha256-DDDD...";               # set to lib.fakeHash to discover
      config.channels.telegram = {
        tokenFile = "/run/agenix/telegram-dev";
        allowFrom = [ 12345678 ];
      };
      plugins = [
        { source = "path:/Users/alice/code/my-plugin"; }   # live local path
      ];
    };
  };
};

```

--------------------------------

### Minimal OpenClaw Nix Configuration

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Use this minimal configuration for a single OpenClaw instance. Ensure your gateway token is set either in the config or as an environment variable.

```nix
{ 
  programs.openclaw = {
    enable = true;
    config = {
      gateway = {
        mode = "local";
        auth = {
          token = "<gatewayToken>"; # or set OPENCLAW_GATEWAY_TOKEN
        };
      };

      channels.telegram = {
        tokenFile = "/run/agenix/telegram-bot-token"; # any file path works
        allowFrom = [ 12345678 ];  # your Telegram user ID
      };
    };

    bundledPlugins.summarize.enable = true;
  };
}

```

--------------------------------

### Configure OpenClaw Gateway Node

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Enable the OpenClaw module and configure it as a gateway node. This registers the machine as a capability node and sets the authentication token.

```nix
programs.openclaw = {
  enable = true;
  config = {
    gateway.mode = "node";   # registers this machine as a capability node
    gateway.auth.token = "shared-cluster-token";
  };
  bundledPlugins = { peekaboo.enable = true; imsg.enable = true; };
};

```

--------------------------------

### Add Community OpenClaw Plugins (NPM)

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Configure OpenClaw to use plugins published to npm. Nix will build and cache the plugin root, making it available to the gateway at runtime.

```nix
customPlugins = [
  {
    source = "npm:@scope/openclaw-plugin@1.2.3";
    id = "openclaw-plugin";
    hash = lib.fakeHash; # replace with the sha256 Nix reports
  }
];
```

--------------------------------

### Apply Home Manager Configuration (macOS)

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Apply the Home Manager configuration for OpenClaw on macOS. Replace `<user>` with your actual username.

```bash
home-manager switch --flake .#<user>
```

--------------------------------

### Sensible Defaults OpenClaw Nix Configuration

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

This configuration uses sensible defaults and enables per-group mention rules for Telegram. If 'instances' is set, 'programs.openclaw.enable' is not required.

```nix
{ 
  programs.openclaw = {
    documents = ./documents;
    config = {
      gateway = {
        mode = "local";
        auth = {
          token = "<gatewayToken>"; # or set OPENCLAW_GATEWAY_TOKEN
        };
      };

      channels.telegram = {
        tokenFile = "/run/agenix/telegram-bot-token";
        allowFrom = [
          12345678         # you (DM)
          -1001234567890   # couples group (no @mention required)
          -1002345678901   # noisy group (require @mention)
        ];
        groups = {
          "*" = { requireMention = true; };
          "-1001234567890" = { requireMention = false; }; # couples group
          "-1002345678901" = { requireMention = true; };  # noisy group
        };
      };
    };

    bundledPlugins.peekaboo.enable = true;
    customPlugins = [
      { source = "github:joshp123/xuezh?rev=<commit>&narHash=<narHash>"; }
      {
        source = "github:joshp123/padel-cli?rev=<commit>&narHash=<narHash>";
        config = {
          env = { PADEL_AUTH_FILE = "/run/agenix/padel-auth"; };
          settings = {
            default_location = "CITY_NAME";
            preferred_times = [ "18:00" "20:00" ];
            preferred_duration = 90;
            venues = [
              {
                id = "VENUE_ID";
                alias = "VENUE_ALIAS";
                name = "VENUE_NAME";
                indoor = true;
                timezone = "TIMEZONE";
              }
            ];
          };
        };
      }
    ];

    instances.default = {
      enable = true;
      package = pkgs.openclaw; # batteries-included
      stateDir = "~/.openclaw";
      workspaceDir = "~/.openclaw/workspace";
      launchd.enable = true;
    };
  };
}

```

--------------------------------

### Enable OpenCLAW Bundled Plugins

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Enables specific first-party OpenCLAW plugins. Some plugins like 'peekaboo' and 'poltergeist' are macOS-only. Configuration for plugins like 'goplaces' requires an API key.

```nix
programs.openclaw = {
  enable = true;
  config = { /* gateway + channels config */ };

  bundledPlugins = {
    summarize.enable  = true;   # Summarize URLs, PDFs, YouTube videos
    peekaboo.enable   = true;   # Screenshot your screen (macOS only)
    discrawl.enable   = false;  # Archive and search Discord history
    wacrawl.enable    = false;  # Archive and search WhatsApp Desktop history
    poltergeist.enable = false; # File watching and automation (macOS only)
    sag.enable        = false;  # Text-to-speech
    camsnap.enable    = false;  # Photos from connected cameras
    gogcli.enable     = false;  # Google Calendar integration
    goplaces.enable   = true;   # Google Places API — enabled by default
    sonoscli.enable   = false;  # Control Sonos speakers
    imsg.enable       = false;  # Send/read iMessages (macOS only)
  };

  # Plugin-specific configuration (secrets + typed settings)
  bundledPlugins.goplaces = {
    enable = true;
    config.env.GOOGLE_PLACES_API_KEY = "/run/agenix/google-places-api-key";
  };
};

```

--------------------------------

### Home Manager Rollback

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Commands to list Home Manager generations and revert to a previous configuration.

```bash
# Rollback
home-manager generations  # list
home-manager switch --rollback  # revert
```

--------------------------------

### Home Manager Rollback and Generation Management

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Manage Home Manager configurations and perform rollbacks on both macOS and Linux. This allows reverting to previous states instantly.

```bash
# List generations
home-manager generations
```

```bash
# Revert to previous generation
home-manager switch --rollback
```

```bash
# Activate a specific past generation
/nix/store/<hash>-home-manager-generation/activate
```

--------------------------------

### OpenClaw Configuration Requirements

Source: https://github.com/openclaw/nix-openclaw/blob/main/README.md

Lists the minimum requirements for configuring OpenClaw, including Telegram bot token, user ID, gateway auth token, and provider API keys.

```nix
# 1. Telegram bot token file - create via [@BotFather](https://t.me/BotFather), set `channels.telegram.tokenFile`
# 2. Your Telegram user ID - get from [@userinfobot](https://t.me/userinfobot), set `channels.telegram.allowFrom`
# 3. Gateway auth token - set `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) for the local gateway
# 4. Provider API keys - set via environment (e.g., `ANTHROPIC_API_KEY`) or `config.env.vars` (avoid secrets in store)
```

--------------------------------

### Add Custom Community Plugins

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Integrates custom OpenCLAW plugins from GitHub repositories or npm. Ensure correct 'rev' and 'narHash' for reproducibility. For npm packages, provide the 'hash' after the first build.

```nix
programs.openclaw.customPlugins = [
  # Minimal Nix capability plugin (CLI tools + skill files)
  {
    source = "github:joshp123/xuezh?rev=abc123&narHash=sha256-AAAA...";
  }

  # Plugin with secrets and typed settings (rendered to config.json in stateDir)
  {
    source = "github:example/padel-cli?rev=def456&narHash=sha256-BBBB...";
    config = {
      env = {
        PADEL_AUTH_FILE = "/run/agenix/padel-auth";
      };
      settings = {
        default_location  = "Barcelona";
        preferred_times   = [ "18:00" "20:00" ];
        preferred_duration = 90;
        venues = [
          { id = "VENUE_ID"; alias = "main"; name = "Club Padel"; indoor = true; timezone = "Europe/Madrid"; }
        ];
      };
    };
  }

  # OpenCLAW runtime plugin distributed on npm (builds plugin root at nix build time; no runtime npm)
  {
    source = "npm:@scope/openclaw-plugin@1.2.3";
    id     = "openclaw-plugin";
    hash   = "sha256-CCCC..."; # replace with sha256 Nix reports on first build
  }
];

```

--------------------------------

### Define a Nix OpenClaw Plugin

Source: https://context7.com/openclaw/nix-openclaw/llms.txt

Defines a Go-based OpenClaw plugin with its package, required state, and environment variables. The plugin contract specifies its name, skills, packages, and dependencies.

```nix
{ description = "hello-world nix-openclaw plugin";

  inputs = {
    nixpkgs.url     = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let pkgs = import nixpkgs { inherit system; }; in
      {
        packages.default = pkgs.buildGoModule {
          pname   = "hello-world";
          version = "0.1.0";
          src     = ./.;
          vendorHash = null;
        };
      }
    )
    // {
      # The plugin contract — consumed by nix-openclaw Home Manager module
      openclawPlugin = {
        name     = "hello-world";
        skills   = [ ./skills/hello-world ];      # directory containing SKILL.md
        packages = [ self.packages.x86_64-linux.default ]; # CLI tools put on PATH
        needs = {
          stateDirs   = [ ".config/hello-world" ]; # dirs created under $HOME
          requiredEnv = [ "HELLO_AUTH_FILE" ];      # activation fails if file missing
        };
        # Optional: load OpenClaw runtime JavaScript plugins
        # plugins = [ { path = ./runtime-plugin; } ];
      };
    };
}

# skills/hello-world/SKILL.md
# --- 
# name: hello-world
# description: Greets the user by name.
# --- 
# 
# Run `hello-world` to print a greeting. The user's name is in OPENCLAW_USER.

```