github.com/nextlevelbuilder/goclaw @v3.14.0 sqlite

Multi-Tenant AI Agent Platform

Multi-agent AI gateway built in Go. 20+ LLM providers. 7 channels. Multi-tenant PostgreSQL.

Single binary. Production-tested. Agents that orchestrate for you.

Documentation • Quick Start • Twitter / X

🌐 Languages: 🇨🇳 简体中文 · 🇯🇵 日本語 · 🇰🇷 한국어 · 🇻🇳 Tiếng Việt · 🇵🇭 Tagalog · 🇪🇸 Español · 🇧🇷 Português · 🇮🇹 Italiano · 🇩🇪 Deutsch · 🇫🇷 Français · 🇸🇦 العربية · 🇮🇳 हिन्दी · 🇷🇺 Русский · 🇧🇩 বাংলা · 🇮🇱 עברית · 🇵🇱 Polski · 🇨🇿 Čeština · 🇳🇱 Nederlands · 🇹🇷 Türkçe · 🇺🇦 Українська · 🇮🇩 Bahasa Indonesia · 🇹🇭 ไทย · 🇵🇰 اردو · 🇷🇴 Română · 🇸🇪 Svenska · 🇬🇷 Ελληνικά · 🇭🇺 Magyar · 🇫🇮 Suomi · 🇩🇰 Dansk · 🇳🇴 Norsk

Core Features

• 8-Stage Agent Pipeline — context → history → prompt → think → act → observe → memory → summarize. Pluggable stages, always-on execution
• 4-Mode Prompt System — Full / Task / Minimal / None with section gating, cache boundary optimization, and per-session mode resolution
• 3-Tier Memory — Working (conversation) → Episodic (session summaries) → Semantic (knowledge graph). Progressive loading L0/L1/L2
• Knowledge Vault — Document registry with [[wikilinks]], hybrid search (FTS + pgvector), filesystem sync
• Agent Teams & Orchestration — Shared task boards, inter-agent delegation (sync/async), 3 orchestration modes (auto/explicit/manual)
• Self-Evolution — Metrics → suggestions → auto-adapt with guardrails. Agents refine their own communication style
• Multi-Tenant PostgreSQL — Per-user workspaces, per-user context files, encrypted API keys (AES-256-GCM), RBAC, isolated sessions
• 20+ LLM Providers — Anthropic (native HTTP+SSE with prompt caching), OpenAI, OpenRouter, Groq, DeepSeek, Gemini, Mistral, xAI, MiniMax, DashScope, Claude CLI, Codex, ACP, and any OpenAI-compatible endpoint
• 7 Messaging Channels — Telegram, Discord, Slack, Zalo OA, Zalo Personal, Feishu/Lark, WhatsApp
• Production Security — 5-layer permission system, rate limiting, prompt injection detection, SSRF protection, AES-256-GCM encryption
• Single Binary — ~25 MB static Go binary, no Node.js runtime, <1s startup, runs on a $5 VPS
• Observability — Built-in LLM call tracing with spans and prompt cache metrics, optional OpenTelemetry OTLP export

Desktop Edition (GoClaw Lite)

A native desktop app for local AI agents — no Docker, no PostgreSQL, no infrastructure.

macOS:

curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install-lite.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install-lite.ps1 | iex

What's Included

• Single native app (Wails v2 + React), ~30 MB
• SQLite database (zero setup)
• Chat with agents (streaming, tools, media, file attachments)
• Agent management (max 5), provider config, MCP servers, skills, cron
• Team tasks with Kanban board and real-time updates
• Auto-update from GitHub Releases

Lite vs Standard

Building from Source

# Prerequisites: Go 1.26+, pnpm, Wails CLI (go install github.com/wailsapp/wails/v2/cmd/wails@latest)
make desktop-build                    # Build .app (macOS) or .exe (Windows)
make desktop-dmg VERSION=0.1.0        # Create .dmg installer (macOS only)
make desktop-dev                      # Dev mode with hot reload

Desktop Releases

Desktop uses independent versioning with lite-v* tags:

git tag lite-v0.1.0 && git push origin lite-v0.1.0
# → GitHub Actions builds macOS (.dmg + .tar.gz) + Windows (.zip)
# → Creates GitHub Release with all assets

Architecture

Quick Start

Prerequisites: Go 1.26+, PostgreSQL 18 with pgvector, Docker (optional)

From Source

git clone -b main https://github.com/nextlevelbuilder/goclaw.git && cd goclaw
make build
./goclaw onboard        # Interactive setup wizard
source .env.local && ./goclaw

Note: The default branch is dev (active development). Use -b main to clone the stable release branch.

With Docker

# Generate .env with auto-generated secrets
chmod +x prepare-env.sh && ./prepare-env.sh

# Add at least one GOCLAW_*_API_KEY to .env, then:
make up

# Web Dashboard at http://localhost:18790 (built-in)
# Health check: curl http://localhost:18790/health

# Optional: separate nginx for custom SSL/reverse proxy
# make up WITH_WEB_NGINX=1  → Dashboard at http://localhost:3000

make up creates a Docker network, embeds the correct version from git tags, builds and starts all services, and runs database migrations automatically.

Common commands:

make up                # Start all services (build + migrate)
make down              # Stop all services
make logs              # Tail logs (goclaw service)
make reset             # Wipe volumes and rebuild from scratch

Operator CLI:

The main goclaw binary can also inspect local or remote gateways:

goclaw traces list --status error
goclaw traces get <trace-id> -o json
goclaw --server https://goclaw.example.com --token "$GOCLAW_GATEWAY_TOKEN" traces follow --session <session-key>

Optional services — enable with WITH_* flags:

Flags can be combined and work with all commands:

# Start with browser automation and tracing
make up WITH_BROWSER=1 WITH_OTEL=1

# Stop everything including optional services
make down WITH_BROWSER=1 WITH_OTEL=1

When GOCLAW_*_API_KEY environment variables are set, the gateway auto-onboards without interactive prompts — detects provider, runs migrations, and seeds default data.

Docker image variants: | Image | Description | |-------|-------------| | latest | Backend + embedded web UI + Python (recommended) | | latest-base | Backend API-only, no web UI, no runtimes | | latest-full | All runtimes + skill dependencies pre-installed | | latest-otel | Latest + OpenTelemetry tracing | | goclaw-web | Standalone nginx + React SPA (for custom reverse proxy) |

For custom builds (Tailscale, Redis): docker build --build-arg ENABLE_TSNET=true ... See the Deployment Guide for details.

Updating

Docker

docker compose pull && docker compose up -d

Binary (with embedded web UI)

goclaw update --apply    # Downloads, verifies SHA256, swaps binary, restarts

Web Dashboard

Open About dialog → click Update Now (admin only). The update includes both backend and web dashboard when using the default latest image.

Multi-Agent Orchestration

Each agent runs with its own identity, tools, LLM provider, and context files. Three delegation modes — sync (wait), async (fire-and-forget), bidirectional — connected through explicit permission links with concurrency limits.

Details: Agent Teams docs

Knowledge Vault

Document registry with [[wikilinks]] for bidirectional linking. Hybrid search combines full-text (BM25) and semantic (pgvector) for precise retrieval. Filesystem sync keeps vault in sync with on-disk files.

Self-Evolution

Agents improve themselves through a 3-stage guardrailed pipeline: metrics collection → suggestion analysis → auto-adaptation. Can refine communication style and domain expertise (CAPABILITIES.md) — but never change identity, name, or core purpose.

Provider Adapters

20+ LLM providers unified through a single adapter interface. Capability-based routing, encrypted API keys (AES-256-GCM), extended thinking support per-provider, and prompt caching for Anthropic + OpenAI.

Event-Driven Architecture

Typed domain events power the consolidation pipeline — session summaries, knowledge graph extraction, and dreaming promotion all run asynchronously via worker pools with dedup and retry.

Built-in Tools

30+ tools across 8 categories:

Full tool reference at docs.goclaw.sh

Webhook API

Trigger agents or send channel messages from external systems without the gateway token.

# Bearer auth — sync LLM call
curl -X POST https://example.com/v1/webhooks/llm \
  -H "Authorization: Bearer wh_..." \
  -H "Content-Type: application/json" \
  -d '{"input":"Summarize today metrics","mode":"sync"}'

# HMAC auth — sign with hmac_signing_key from create response
TS=$(date +%s); BODY='{"input":"hi","mode":"sync"}'
SIG=$(echo -n "${TS}.${BODY}" | openssl dgst -sha256 -mac HMAC \
      -macopt "hexkey:${WEBHOOK_HMAC_KEY}" | awk '{print $2}')
curl -X POST https://example.com/v1/webhooks/llm \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Id: ${WEBHOOK_ID}" \
  -H "X-GoClaw-Signature: t=${TS},v1=${SIG}" \
  -d "$BODY"

See **[docs/webhooks.md](docs/webhooks.md