Skip to main content
ClawQL

ClawQL Learn

ClawQL Learn is the home for practical guides — from your first npx clawql-mcp through production deployment and optional tools.

Structured modules and hub links: Reference · Examples · Authentication · Security.

Start here

If you are new to ClawQL, follow this sequence:

  1. Quickstart — run the MCP server, install options, Streamable HTTP
  2. Agent setup — Desktop, Cursor iOS, local sandbox
  3. MCP clients — Cursor, Claude Desktop, and other MCP hosts
  4. Concepts — how search and execute fit together
  5. Using search and execute — inputs, args, fields, and pitfalls
  6. Tools — full tool surface and behavior

Learn modules

Curated walkthroughs under /learn— the same links as ClawQL Learn in the sidebar.

Using search & execute

`search` / `execute` inputs, args, response fields, and common pitfalls when calling loaded OpenAPI specs.

External ingest & knowledge lake

Import Markdown or a single URL into the vault with `ingest_external_knowledge`, dry runs, and vault pairing.

Onyx enterprise search

Optional `knowledge_search_onyx`: ACL-aware semantic search over your enterprise Onyx index.

Document pipeline

Seven-vendor IDP path: Nextcloud → Tika → Gotenberg → Stirling → archive → Onyx → Coneshare.

Payments & entitlements

Plan tiers, Stripe + x402 gates, WORM payment audit, and inference quota enforcement end-to-end.

Sandbox exec

Optional sandbox_exec MCP tool; pair with Local agent sandbox for full harness containment.

Optional MCP tools

When to enable cache, schedule, notify, audit, Onyx, and sandbox — flags, recipes, and deep-dive links.

Effect-TS in ClawQL

Why Effect-TS enforces the 7-layer architecture: Layers, Gateway composition, fail-closed errors, and optional plugins.

Ouroboros tools

`ouroboros_*`: seed from documents, evolutionary loop, Postgres lineage, and route hints vs raw infra.

Streams getting started

Hands-on labs: schedule, NATS, IDP overlay, agent bridge, celld v0.4.0 + Wrangler skeleton — plus DO/celld/cellrt/TEE reading order.

NATS IDP pipeline

Async document path: inbox webhooks, JetStream workers, KEDA scale, run_idp_pipeline, and agent bridge.

OpenClaw with ClawQL

Gateway wiring, `openclaw mcp set`, and a smoke path so agents use the same MCP surface as Cursor.

Schedule & notify workflows

`schedule` synthetics plus `notify` to Slack — threads, HITL hooks, and Label Studio handoff patterns.

Cache handoff between chats

Core `cache` tool: scratch state, TTL, namespacing, and carrying context into a new chat session.

clawql-memory (Memory 2.0)

Vault ingest/recall, wikilink graph, hybrid vectors, PageIndex, team sync, and the inference flywheel.

Audit tool & observability

Core `audit` ring buffer plus Prometheus, Grafana, and Loki — breadcrumbs without vault writes.

Panguard MCP enforcement

JWT ATR chokepoints: stdio wrap, in-process proxy plugin, Helm mcpProxy, and the MCP bridge image.

Install, specs, deployment, networking, and operations pages outside /learn that pair with the modules above.

Spec configuration

OpenAPI paths, URLs, Google Discovery, merged presets, and CLAWQL_* precedence for loaded specs.

Deployment

Docker, Streamable HTTP, Cloud Run, and links to Kubernetes and remote MCP endpoints.

Tailscale & Headscale

Private tailnets for MCP: MagicDNS, Serve, CLAWQL_MCP_URL, ACLs, and mesh vs cluster DNS.

Kubernetes

Helm install, gRPC and HTTP, auth, rebuilds, and Kustomize patterns for dev and prod clusters.

Helm

Chart at manifests/charts/clawql-mcp: values, GHCR image, optional Ingress, PVC, and upgrade notes.

Docker Desktop: Istio & observability

Prometheus, Grafana, Tempo, Kiali, and OTel Collector on Docker Desktop — beginner-oriented runbooks.

Authentication

Inbound vs outbound MCP auth — proactive OAuth refresh, API keys, EMA / ID-JAG.

Audit Trail

Append-only WORM trail — hash chain, Merkle batch roots, dual-ack replication.

Observability

LGTM+ runtime telemetry — Alloy ingest, governed provider registry, Faro JWT proxy.

Security

Golden image pipeline, Kyverno, Cosign keyless signing, Trivy/OSV gates, and supply-chain references.

Troubleshooting

Common MCP host failures, spec loading, auth, and where to look first when something breaks.

Examples & walkthroughs

Session narratives and postmortems — see all examples.

Example: Cloudflare docs deploy

MCP workflow for docs.clawql.com: search, execute, vault memory, and Worker runtime triage.

Example: Vault + GitHub session

memory_ingest at scale, issue triage, and shipping enterprise audit tooling with docs.

Example: Cross-thread vault recall

Repo search vs memory_recall — Obsidian graph, wikilinks, and session resume patterns.

Browse by stack topic

Use these hubs when you care about one slice of the product:

Modules and certifications

Hands-on modules above prepare you for production MCP usage. Security curriculum lives under Security best practices.