RAG Claw

May 27, 2026 · View on GitHub

NVIDIA RAG Blueprint agent for OpenClaw. Provides skills covering the full RAG lifecycle: prerequisites and deployment, configuration, troubleshooting, RAGAS evaluation, and performance benchmarking.

Prerequisites

OpenClaw host

Requirement	Notes
Node.js	≥ 22.19.0 (required by OpenClaw and this plugin). System Node 20/21 is not supported.
npm	Bundled with Node; used for global OpenClaw CLI and local plugin build.
nvm (recommended)	Installs Node in your home directory so `npm install -g` works without `sudo`.

Install Node 22 with nvm, then use it in every shell:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.nvm/nvm.sh
nvm install 22
nvm alias default 22
node -v   # v22.x.x

RAG deployment

The following should be in place before deploying RAG containers. The agent checks and guides you through each step via the rag-blueprint skill — this is a quick reference.

Requirement	Notes	Install guide
NVIDIA GPU driver	See `docs/support-matrix.md` for minimum version	nvidia.com/drivers — reboot after install
Docker Engine	Required for Docker Compose deployments	docs.docker.com/engine/install/ubuntu
Docker Compose	v2.x	Included with Docker Desktop / Engine
NVIDIA Container Toolkit	Required for self-hosted NIMs	Container Toolkit install guide
NGC API key	`NGC_API_KEY` or `NVIDIA_API_KEY`	org.ngc.nvidia.com/setup/api-keys

Post-Docker install: add your user to the docker group so containers run without sudo:

sudo usermod -aG docker $USER && newgrp docker

1. Install OpenClaw

Use the nvm Node 22 shell (see above), then install the CLI globally:

npm install -g openclaw
openclaw --version

Run guided setup once (models, API keys, workspace, gateway):

openclaw onboard

For NVIDIA API Catalog models, you can pass --auth-choice nvidia-api-key during onboard, or set NVIDIA_API_KEY / NGC_API_KEY in your environment and configure later with openclaw configure.

2. Install the RAG Claw Plugin

OpenClaw loads compiled JavaScript from dist/. Build the plugin from the RAG repo, then install with --link so OpenClaw uses your checkout in place (recommended for development and for machines where a copy install fails peer-dependency linking).

From the cloned RAG repo:

cd /path/to/rag/.openclaw
npm install
npm run build
openclaw plugins install --link /path/to/rag/.openclaw/

Use an absolute path to .openclaw/ (as above). npm run build compiles index.ts → dist/index.js and copies skills from the repo-root skills/ into .openclaw/skills/.

Do not use a bare copy install (openclaw plugins install /path/to/rag/.openclaw/ or openclaw plugins install ./ from inside .openclaw/) unless you are using a packaged OpenClaw install that can symlink the openclaw peer dependency. On many systems that fails with:

Installed plugin openclaw-rag declares openclaw as a peer dependency, but OpenClaw could not create a plugin-local node_modules/openclaw link.

@nvidia/openclaw-rag is not published to npm yet. Do not run openclaw plugins install @nvidia/openclaw-rag until the package is available on the registry.

Restart the gateway after install so the plugin loads:

# foreground gateway: stop and run again
openclaw gateway run

# or systemd user service
systemctl --user restart openclaw-gateway

On first gateway start, the plugin copies workspace templates (BOOTSTRAP.md, IDENTITY.md, SOUL.md, AGENTS.md, TOOLS.md) to ~/.openclaw/workspace/. If Docker is present, it may write a systemd drop-in for gateway Docker socket access — apply it with:

systemctl --user daemon-reload
systemctl --user restart openclaw-gateway

3. Verify

openclaw skills list | grep -E "rag-blueprint|rag-eval|rag-perf"

Expected output:

rag-blueprint  Deploy, configure, troubleshoot, and manage the NVIDIA RAG Blueprint
rag-eval       Filesystem RAG benchmarks (corpus/, train.json, RAGAS via evaluate_rag.py)
rag-perf       Performance benchmarking (aiperf load tests) for a deployed RAG server

4. Run and interact

Start the gateway (required for chat and the web UI):

# foreground (good for first try)
openclaw gateway run

# or install and start a user service
openclaw gateway install
systemctl --user start openclaw-gateway

Add a long agent timeout for RAG deploys and evals (merge into ~/.openclaw/openclaw.json):

{
  "agents": {
    "defaults": {
      "timeoutSeconds": 3600
    }
  }
}

In another terminal, use any of these:

Interface	Command
Terminal chat (gateway)	`openclaw tui --timeout-ms 3600000`
Terminal chat (local)	`openclaw chat --timeout-ms 3600000`
Web Control UI	`openclaw dashboard` → `http://127.0.0.1:18789/`
One-shot turn	`openclaw agent --message "check prerequisites"`

Prefer gateway-backed openclaw tui (not openclaw chat) for end-to-end RAG Docker deploys: the gateway keeps the run alive while the terminal UI may show idle after ~30s without streamed text. If you see "This response is taking longer than expected", wait for the run to finish or send a short follow-up (for example "status update"); avoid starting a new deploy request until the prior turn completes. Inside the TUI, /verbose full shows tool progress during long shell work.

Check status:

openclaw status
openclaw health

First session: start openclaw tui (with the gateway running). The BOOTSTRAP flow runs automatically and the agent introduces itself and walks through initial RAG configuration.

Example prompts:

"check prerequisites"
"deploy RAG with NVIDIA-hosted NIMs"
"RAG server is unhealthy"
"run RAGAS eval on my benchmark dataset"

Optional: install the browser skill into the workspace (used for RAG UI automation):

cd ~/.openclaw/workspace
npx --yes skills add vercel-labs/agent-browser --yes

OpenClaw CLI reference: docs.openclaw.ai/cli

Skills Reference

Skill	Trigger phrases
`rag-blueprint`	"deploy RAG", "enable VLM", "configure reranker", "RAG is unhealthy", "stop RAG"
`rag-eval`	"run RAGAS eval", "evaluate_rag", "benchmark dataset", "parse eval results"
`rag-perf`	"rag perf", "aiperf", "latency benchmark", "throughput test"

Skill source of truth: skills/ at the repo root.

Default service ports

Service	Port
RAG server API	8081
Ingestor API	8082
Web UI	8090

See docs/service-port-gpu-reference.md for the full port and GPU map.

Troubleshooting plugin install

Error	Cause	Fix
`could not create a plugin-local node_modules/openclaw link`	Copy install (`plugins install` without `--link`)	`openclaw plugins install --link /path/to/rag/.openclaw/` after `npm run build`
`Package not found on npm: @nvidia/openclaw-rag`	Package not published	Install from the repo with `--link` (see above)
`package.json missing openclaw.hooks`	OpenClaw also tried hook-pack install	Ignore if the native plugin install succeeded; use `--link` on the `.openclaw/` directory
Skills missing after install	`dist/` or `skills/` not built	`cd /path/to/rag/.openclaw && npm install && npm run build`, then reinstall with `--link`

OpenClaw plugin install reference: docs.openclaw.ai/tools/plugin (local checkouts: openclaw plugins install --link ./my-plugin).