nix-openclaw: plugins declared in Nix instead of installed at runtime

One flake replaces the manual OpenClaw install

OpenClaw is a chat-driven agent that you talk to over Telegram while it acts on the machine it runs on. The examples in the README are small: ask what is on the screen and it takes a screenshot and describes it, ask for jazz and it opens Spotify, send a voice note and it runs whisper and returns text. nix-openclaw is the packaging layer that makes that agent installable as a Nix flake, with the stated goal of "One flake, everything works." The Gateway is available everywhere, runtime dependencies are bundled, and the macOS app is provided on macOS.

Two boundaries are stated up front. The supported platforms are macOS and headless Linux, and Windows is out of scope for now. The other is a deployment policy: the project publishes a Golden Paths document and says there should be one obvious way to deploy, preferably only one. That document lives in the repository at docs/golden-paths.md, and the intended workflow is to pick a path and follow it rather than assemble a custom configuration. The top-level layout is conventional enough to orient yourself: flake.nix and flake.lock at the root, with nix/, scripts/, templates/, docs/, examples/, maintainers/ and an AGENTS.md beside them.

Plugin installs move out of the OpenClaw CLI and into Nix

With a regular OpenClaw installation, plugin code is fetched by the OpenClaw CLI at runtime. The upstream commands cover the npm and ClawHub registries, tarball artifacts, git references, local links and marketplaces:

openclaw plugins install @openclaw/discord
openclaw plugins install npm:<package>
openclaw plugins install --link ./my-plugin

With nix-openclaw the same outcome is expressed as a list in your Nix configuration, and the build does the wiring for you:

programs.openclaw.runtimePlugins = [ "discord" ];

Each tool plugin declares its own CLI tools in Nix, so enabling a plugin is the point at which its build and wiring happen. This is the core difference between the two projects: upstream resolves and installs at the moment you run a command, while this packaging resolves at build time. The Nix gateway also omits the upstream npm CLI and its private dependency bundle, and build-time package managers come from the pinned Nix toolchain rather than from a system Node installation. Plugin roots are JavaScript directories loaded by the OpenClaw Gateway, and the catalogue covers Discord, Slack, WhatsApp, GitHub Copilot, memory providers and model providers.

OPENCLAW_NIX_MODE=1 turns five plugin commands into errors

The packaging runs OpenClaw with OPENCLAW_NIX_MODE=1 set. The documented effect is that five commands fail rather than mutating the state directory in your home directory: plugins install, plugins update, plugins uninstall, plugins enable and plugins disable. They fail on purpose, because a mutable write to ~/.openclaw is exactly what a declarative configuration is meant to prevent.

This is the part of the project that will surprise you first. If you are used to treating an agent's plugin set as runtime state, you will reach for the install command and get an error instead of a plugin. The answer given in the documentation is to change your Nix configuration and rebuild. That answer is correct but it also means the normal loop of trying a plugin and keeping it no longer exists; every attempt, including the failed ones, is a configuration edit and a rebuild.

Plugin Control UI assets and manifest reloads do support Nix-store hardlinks when running in Nix mode, including on stores optimized with auto-optimise-store, but mutable plugin roots keep the upstream hardlink restrictions. So the hardlink story applies to the immutable parts of the plugin tree, not to the parts the plugin itself writes to.

Reproducible plugins need published lock evidence

Regular OpenClaw can resolve npm dependencies during openclaw plugins install. nix-openclaw cannot run a mutable dependency solve during a home-manager switch, so the dependency evidence has to exist before the build. A plugin qualifies if it publishes bundled node_modules, an npm-shrinkwrap.json, or, for supported OpenClaw catalogue plugins, upstream npm package-lock.json release evidence bound to the pinned release SHA. Without one of those three, there is no reproducible Nix package for it.

The project describes three ways forward. If a package has an npm-shrinkwrap.json, the dependency graph can be replayed with npmDepsHash. For lockless catalogue plugins, the pin updater can select the exact package name and version from the upstream openclaw-<version>-dependency-evidence.zip asset, record the lock and the hashes, and replay that during the Nix build. If a plugin bundles node_modules, the bundled dependencies are validated and copied. Plugin authors outside the catalogue fall back to publishing a shrinkwrap or bundled runtime dependencies.

This rule is the sharpest constraint in the whole project. It means the set of plugins you can install is decided by what upstream publishers happen to ship, and a plugin that installs cleanly on a normal OpenClaw machine may have no Nix package at all.

runtimePluginSources covers plugins the supported list misses

The supported list is a convenient starting point but not the only input. The repository keeps a generated report of what the current build supports, and you can read it directly:

jq -r '.supported[] | "\(.id)\t\(.label)\t\(.selectedSource)\t\(.dependencyMode)"' \
  nix/generated/openclaw-runtime-plugins/report.json

For anything outside that list, or when you want to override the selected source, runtimePluginSources takes an entry with an id and a spec. The schemes cover npm specs, clawhub specs, and fixed HTTPS npm-pack tarball artifacts. Git references, local paths and marketplace installs have no direct runtimePluginSources input today, so the documented workaround is to package the plugin as a fixed Nix source or to use the raw plugins.load.paths setting.

The id is not free text. It is the OpenClaw plugin id taken from the plugin's openclaw.plugin.json and it has to match the package you fetch. The distinction bites people: runtimePlugins takes ids such as discord, whatsapp, googlechat, msteams or copilot, while runtimePluginSources must not receive bare package names or unprefixed @scope/package strings, only exact npm: or clawhub: specs.

Home Manager generations do not rewind the agent's mutable state

The pinning story has one limit that is worth stating plainly. Nix locks dependencies, and Home Manager records configuration generations, but those generations do not back up or rewind OpenClaw's mutable state. Anything the agent writes at runtime, such as conversation data, logs or generated files under the state directory, is outside the reach of a rollback.

In practice this means a rollback of your Home Manager configuration returns you to the previous set of pinned packages and plugins, not to a previous snapshot of everything the agent did. A configuration that worked yesterday can fail today because the agent accumulated state, and a version rollback will not clear that. If you rely on the agent's history, plan for that state separately, because the project does not describe any mechanism that covers it.

The plugin story is similarly one-way in practice. Because the plugin commands fail under OPENCLAW_NIX_MODE=1, there is no supported path for removing a plugin's runtime footprint short of editing the configuration and rebuilding, which means the plugin set you declare becomes the plugin set you keep.

Discord instead of pull requests, a custom licence, and dated releases

The contribution policy is unusual enough to affect whether you can participate. The project is not accepting pull requests at the moment, and the stated reason is that async agent-to-agent review is too slow and low-signal. Agents that are not listed as maintainers are told explicitly that a pull request will be rejected. The recommended channel is the OpenClaw Discord, in the channel #golden-path-deployments, and GitHub Issues are described as not actively monitored either. For a wrapper whose value is upstream compatibility, that means a bug in plugin handling is unlikely to be fixed by the community quickly.

Licensing is likewise not a simple lookup. The license is recorded as Other, a custom licence that GitHub cannot classify, and the LICENSE file in the repository is the authority. Anyone considering a redistribution or commercial deployment has to read that file directly rather than assume a permissive license from the repository listing.

Maintenance itself looks current. The last push was on 2026-10-19, and recent releases include v2026.10.4 on 2026-10-16, v2026.9.5 on 2026-09-23 and v2026.9.4 on 2026-09-12. The release names track the OpenClaw version they package, which is what you need in order to know which upstream plugin behaviour your pinned build will have.

Editorial conclusion

Adopt nix-openclaw if you already run Nix and Home Manager and want OpenClaw's plugin set pinned in a flake, and expect to add plugins by editing configuration rather than by running install commands. Do not adopt it if Windows support, an actively maintained plugin marketplace, or an install flow that does not touch the Nix store matters to you. Before switching, check the release notes for the pinned OpenClaw version, confirm the plugins you rely on appear in the supported list reported under nix/generated/openclaw-runtime-plugins/report.json, and read the LICENSE file, since the project uses a custom licence that GitHub could not classify.

Frequently asked questions

Official sources

1. Issues
2. openclaw/nix-openclaw on GitHub
3. README
4. Releases