Goclaw

🌐 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

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

Documentation

Full documentation at docs.goclaw.sh — or browse the source in goclaw-docs/

Testing

go test ./...                                    # Unit tests
go test -v ./tests/integration/ -timeout 120s    # Integration tests (requires running gateway)

Project Status

See CHANGELOG.md for detailed feature status including what's been tested in production and what's still in progress.

Acknowledgments

GoClaw was originally inspired by the OpenClaw project architecture.

License

CC BY-NC 4.0 — Creative Commons Attribution-NonCommercial 4.0 International

Star History