OpenClaw + ClawQL

OpenClaw is a separate npm product (openclaw) — a multi-channel AI gateway with its own CLI, agents, and openclaw mcp commands. ClawQL (this repo, npm clawql-mcp) is an MCP server that exposes search, execute, audit, cache, vault memory, the document stack, and other optional tools over stdio or Streamable HTTP (…/mcp). You register ClawQL inside OpenClaw so agents running behind OpenClaw can call real APIs through ClawQL's merged OpenAPI surface rather than pasting large specs into every prompt.

Canonical deep dive: using-openclaw-with-clawql.md. Bootstrap + smoke: clawql-bootstrap.md (#226). IDP skill profile: openclaw-idp-skill-profile.md (#227). Umbrella: #128.

OpenClaw and ClawQL MCP — what each one is

Package name to use: openclaw-mcp on npm is a different package (a bridge for hosts like Claude Desktop toward an OpenClaw gateway). To attach ClawQL to OpenClaw, use clawql-mcp, node …/dist/server.js, or an HTTP url — see using-openclaw-with-clawql.md § 1.

Why run OpenClaw with ClawQL

Agents use search then execute with small payloads rather than large specs in context (Using search and execute). OpenClaw's MCP JSON mirrors .cursor/mcp.json.example field shapes, so the same configuration works across clients (MCP clients). The full optional stack — vault memory_*, ingest_external_knowledge, knowledge_search_onyx, notify, schedule, ouroboros_* — is configurable via CLAWQL_* env (Tools, Concepts).

Prerequisites

• Node.js 20+ (repo development targets 22+).
• ClawQL installed or built (npm install clawql-mcp, npx -y clawql-mcp, or git clone + npm run build).
• OpenClaw CLI: npm install -g openclaw, then openclaw --version.
• Optional: gh auth login or CLAWQL_BEARER_TOKEN / GITHUB_TOKEN for live GitHub execute smokes.

Install the OpenClaw CLI

npm install -g openclaw@latest
openclaw --version
openclaw mcp --help

Gateway onboarding (openclaw configure, channels, upstream product docs) is outside this repo — follow your installed openclaw version. Registering ClawQL below is enough for MCP-backed agents to reach APIs.

Run ClawQL MCP — HTTP or stdio

Streamable HTTP:

PORT=8080 npm run start:http

From a published package:

PORT=8080 npx -p clawql-mcp clawql-mcp-http

• Health: GET http://127.0.0.1:8080/healthz
• MCP endpoint: http://127.0.0.1:8080/mcp — path must be /mcp.

Stdio:

npx -y clawql-mcp

See Deployment for PORT, MCP_PATH, TLS, and reverse proxies.

Register ClawQL in OpenClaw

OpenClaw 2026.x stores config under ~/.openclaw/openclaw.json. Use:

openclaw mcp set <server-name> '<json>'

HTTP (ClawQL on localhost):

openclaw mcp set clawql '{"url":"http://127.0.0.1:8080/mcp"}'
openclaw mcp show clawql
openclaw mcp list

Stdio (published package):

openclaw mcp set clawql '{"command":"npx","args":["-y","clawql-mcp"]}'

Stdio (dev build from clone):

openclaw mcp set clawql-dev "{\"command\":\"node\",\"args\":[\"/absolute/path/to/ClawQL/dist/server.js\"]}"

Remove with openclaw mcp unset clawql.

Validate with smoke tests

From the ClawQL repo (after npm run build):

CLAWQL_OPENCLAW_BOOTSTRAP_TOOLS_ONLY=1 npm run smoke:openclaw-bootstrap

Expect OK (tools-only). Full search → execute (GitHub list commits) needs network + token:

npm run smoke:openclaw-bootstrap

Then in OpenClaw: confirm openclaw mcp show clawql, drive a prompt that searches then executes (e.g. GitHub commits) with tight fields. If tools are missing, verify listTools on ClawQL alone before debugging OpenClaw routing (clawql-bootstrap.md).

Worked example — vault recall from agent chat: OpenClaw → memory_recall case study (verbatim transcript, clawql__memory_recall tool trace, cross-session notes).

Environment variables and remote MCP

• Stdio: add an env object inside the same JSON as command / args — same pattern as Cursor mcp.json (using-openclaw-with-clawql.md § 5.4).
• HTTP: set CLAWQL_* in the shell (or process manager) that starts clawql-mcp-http, not inside OpenClaw's URL JSON.
• Remote: point url at https://clawql.example.com/mcp (Ingress), or a Tailscale HTTPS URL — Tailscale & Headscale, Helm.

Next steps — document IDP workflows

After search / execute is green, use openclaw-idp-skill-profile.md for ingest → transform → archive → share patterns: optional convert_document (anydoc), inspect_pdf (pdf-inspector), Docling, classify_document, extract_document (LangExtract), Nextcloud, Paperless, Onyx, Coneshare, vault memory_*, optional notify. For the full document stack (anydoc/pdf-inspector route + eight vendors), see Document pipeline.

Troubleshooting and related links

© Copyright 2026. All rights reserved. · ClawQL on GitHub