From 4ed579792e4d9a8a722d29842ef5a962d24b7e3f Mon Sep 17 00:00:00 2001 From: joshp123 Date: Wed, 6 May 2026 16:37:21 +0200 Subject: [PATCH] docs: record OpenClaw plugin investigations What: - document the QMD/mcporter packaging decision for maintainers - capture the native OpenClaw plugin gap and proposed nix-openclaw fix Why: - preserve the Discord investigation so the feature work can resume later - distinguish PR #81's bundled manifest fix from external native plugin support Tests: - git diff --check: pass - nix build .#checks.aarch64-darwin.package-contents --no-link: pass Co-authored-by: Codex --- docs/plugins-maintainers.md | 16 ++++++++++++++++ maintainers/packaging.md | 9 +++++++++ 2 files changed, 25 insertions(+) diff --git a/docs/plugins-maintainers.md b/docs/plugins-maintainers.md index 7532501..5fda909 100644 --- a/docs/plugins-maintainers.md +++ b/docs/plugins-maintainers.md @@ -7,6 +7,22 @@ Purpose: extend OpenClaw capabilities without bloating core; ship tools + skills - **Not:** new transports/providers; model plumbing; secrets baked in; inline scripts or ad-hoc package-manager installs; a place for random config outside its scope. - Why not skills-only: skills without binaries can hallucinate capability. Plugins ground skills in real tools and deliver versioned, reproducible functionality. +## Native OpenClaw Plugin Gap + +OpenClaw also has native runtime plugins: a plugin directory with `openclaw.plugin.json` plus a JS/TS entry loaded by the gateway. Channel plugins such as `openclaw-weixin` live in this layer. + +Current nix-openclaw `customPlugins` only implements the Nix-native capability bundle contract: package binaries on the gateway PATH, materialize skills, create state dirs, validate env files, and render optional tool settings. It does not yet tell OpenClaw to load a native plugin directory or enable the matching `plugins.entries.` entry. + +PR #81 (`fix: copy plugin manifests into dist/extensions`) was related but not the missing external-plugin feature. It fixed bundled upstream plugin manifests missing from the packaged gateway `dist/extensions/*/openclaw.plugin.json` tree. Current packaging already copies those manifests and checks them in `openclaw-package-contents`. + +The next feature slice should bridge the existing Nix contract to OpenClaw native plugins: + +- Extend `openclawPlugin` with an optional native plugin declaration, for example `nativePlugins = [ { id = "openclaw-weixin"; path = "${pkg}/lib/openclaw/plugins/openclaw-weixin"; enable = true; } ];`. +- For each enabled instance, append those paths to generated `plugins.load.paths`. +- Add default `plugins.entries..enabled = true`, with user config still able to override it. +- Keep native plugin config in `programs.openclaw.config` / `instances..config` so upstream schema validation remains the source of truth. +- Add a fixture shaped like `openclaw-weixin` so `customPlugins = [{ source = ...; }]` proves both package/skill wiring and native plugin load wiring. + ## Interface Contract (reference implementation: nix-openclaw) Every plugin artifact exposes the same fields (flake output `openclawPlugin` today, but the shape is host-agnostic): diff --git a/maintainers/packaging.md b/maintainers/packaging.md index 88e3dd5..00ca791 100644 --- a/maintainers/packaging.md +++ b/maintainers/packaging.md @@ -29,3 +29,12 @@ This repo ships a working Nix package for OpenClaw users, not just a pin mirror. - Keep runtime tools internal to the `openclaw` wrapper unless they are intentionally part of the public package surface. - QMD is the Nix-supported batteries-included local memory backend. Keep `qmd` internal to the `openclaw` wrapper PATH; users opt in with upstream config. - Keep files under 400 lines unless a maintainer explicitly accepts the larger file. + +## Investigations + +### mcporter and QMD + +- `mcporter` is an OpenClaw-owned optional MCP/CLI bridge, not a QMD requirement. +- OpenClaw defaults to direct `qmd` CLI execution. Keep that as the Nix-supported baseline until measured startup or per-query overhead proves otherwise. +- Package `mcporter` in `nix-openclaw-tools` as an optional tool when needed, but do not add it to the default `openclaw` runtime PATH just because QMD is bundled. +- If `memory.qmd.mcporter.enabled = true`, nix-openclaw should make `mcporter` visible to that instance and require the matching mcporter server config for `qmd mcp`.