goclaw/README.md

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

A Go port of OpenClaw with enhanced security, multi-tenant PostgreSQL, and production-grade observability.

🌐 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

What Makes It Different

• Agent Teams & Orchestration — Teams with shared task boards, inter-agent delegation (sync/async), and hybrid agent discovery
• Multi-Tenant PostgreSQL — Per-user workspaces, per-user context files, encrypted API keys (AES-256-GCM), isolated sessions
• Single Binary — ~25 MB static Go binary, no Node.js runtime, <1s startup, runs on a $5 VPS
• Production Security — 5-layer permission system (gateway auth → global tool policy → per-agent → per-channel → owner-only) plus rate limiting, prompt injection detection, SSRF protection, shell deny patterns, and AES-256-GCM encryption
• 20+ LLM Providers — Anthropic (native HTTP+SSE with prompt caching), OpenAI, OpenRouter, Groq, DeepSeek, Gemini, Mistral, xAI, MiniMax, Cohere, Perplexity, DashScope, Bailian, Zai, Ollama, Ollama Cloud, Claude CLI, Codex, ACP, and any OpenAI-compatible endpoint
• 7 Messaging Channels — Telegram, Discord, Slack, Zalo OA, Zalo Personal, Feishu/Lark, WhatsApp
• Extended Thinking — Per-provider thinking mode (Anthropic budget tokens, OpenAI reasoning effort, DashScope thinking budget) with streaming support
• Heartbeat System — Periodic agent check-ins via HEARTBEAT.md checklists with suppress-on-OK, active hours, retry logic, and channel delivery
• Scheduling & Cron — at, every, and cron expressions for automated agent tasks with lane-based concurrency
• Observability — Built-in LLM call tracing with spans and prompt cache metrics, optional OpenTelemetry OTLP export

Claw Ecosystem

	OpenClaw	ZeroClaw	PicoClaw	GoClaw
Language	TypeScript	Rust	Go	Go
Binary size	28 MB + Node.js	3.4 MB	~8 MB	~25 MB (base) / ~36 MB (+ OTel)
Docker image	—	—	—	~50 MB (Alpine)
RAM (idle)	> 1 GB	< 5 MB	< 10 MB	~35 MB
Startup	> 5 s	< 10 ms	< 1 s	< 1 s
Target hardware	$599+ Mac Mini	$10 edge	$10 edge	$5 VPS+

Feature	OpenClaw	ZeroClaw	PicoClaw	GoClaw
Multi-tenant (PostgreSQL)	—	—	—	✅
MCP integration	— (uses ACP)	—	—	✅ (stdio/SSE/streamable-http)
Agent teams	—	—	—	✅ Task board + mailbox
Security hardening	✅ (SSRF, path traversal, injection)	✅ (sandbox, rate limit, injection, pairing)	Basic (workspace restrict, exec deny)	✅ 5-layer defense
OTel observability	✅ (opt-in extension)	✅ (Prometheus + OTLP)	—	✅ OTLP (opt-in build tag)
Prompt caching	—	—	—	✅ Anthropic + OpenAI-compat
Knowledge graph	—	—	—	✅ LLM extraction + traversal
Skill system	✅ Embeddings/semantic	✅ SKILL.md + TOML	✅ Basic	✅ BM25 + pgvector hybrid
Lane-based scheduler	✅	Bounded concurrency	—	✅ (main/subagent/team/cron)
Messaging channels	37+	15+	10+	7+
Companion apps	macOS, iOS, Android	Python SDK	—	Web dashboard + Desktop app
Live Canvas / Voice	✅ (A2UI + TTS/STT)	—	Voice transcription	TTS (4 providers)
LLM providers	10+	8 native + 29 compat	13+	20+
Per-user workspaces	✅ (file-based)	—	—	✅ (PostgreSQL)
Encrypted secrets	— (env vars only)	✅ ChaCha20-Poly1305	— (plaintext JSON)	✅ AES-256-GCM in DB

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

Feature	Lite (Desktop)	Standard (Server)
Agents	Max 5	Unlimited
Teams	Max 1 (5 members)	Unlimited
Database	SQLite (local)	PostgreSQL
Memory	FTS5 text search	pgvector semantic
Channels	—	Telegram, Discord, Slack, Zalo, Feishu, WhatsApp
Knowledge Graph	—	Full
RBAC / Multi-tenant	—	Full
Auto-update	GitHub Releases	Docker / binary

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:

Flag	Service	What it does
WITH_BROWSER=1	Headless Chrome	Enables browser tool for web scraping, screenshots, automation
WITH_OTEL=1	Jaeger	OpenTelemetry tracing UI for debugging LLM calls and latency
WITH_SANDBOX=1	Docker sandbox	Isolated container for running untrusted code from agents
WITH_TAILSCALE=1	Tailscale	Expose gateway over Tailscale private network
WITH_REDIS=1	Redis	Redis-backed caching layer

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

GoClaw supports agent teams and inter-agent delegation — each agent runs with its own identity, tools, LLM provider, and context files.

Agent Delegation

Mode	How it works	Best for
Sync	Agent A asks Agent B and waits for the answer	Quick lookups, fact checks
Async	Agent A asks Agent B and moves on. B announces later	Long tasks, reports, deep analysis

Agents communicate through explicit permission links with direction control (outbound, inbound, bidirectional) and concurrency limits at both per-link and per-agent levels.

Agent Teams

• Shared task board — Create, claim, complete, search tasks with blocked_by dependencies
• Tools: team_tasks for task management, spawn for subagent orchestration

For delegation details, permission links, and concurrency control, see the Agent Teams docs.

Built-in Tools

Tool	Group	Description
read_file	fs	Read file contents (with virtual FS routing)
write_file	fs	Write/create files
edit_file	fs	Apply targeted edits to existing files
list_files	fs	List directory contents
search	fs	Search file contents by pattern
glob	fs	Find files by glob pattern
exec	runtime	Execute shell commands (with approval workflow)
web_search	web	Search the web (Brave, DuckDuckGo)
web_fetch	web	Fetch and parse web content
memory_search	memory	Search long-term memory (FTS + vector)
memory_get	memory	Retrieve memory entries
skill_search	—	Search skills (BM25 + embedding hybrid)
knowledge_graph_search	memory	Search entities and traverse knowledge graph relationships
create_image	media	Image generation (DashScope, MiniMax)
create_audio	media	Audio generation (OpenAI, ElevenLabs, MiniMax, Suno)
create_video	media	Video generation (MiniMax, Veo)
read_document	media	Document reading (Gemini File API, provider chain)
read_image	media	Image analysis
read_audio	media	Audio transcription and analysis
read_video	media	Video analysis
message	messaging	Send messages to channels
tts	—	Text-to-Speech synthesis
spawn	—	Spawn a subagent
subagents	sessions	Control running subagents
team_tasks	teams	Shared task board (list, create, claim, complete, search)
sessions_list	sessions	List active sessions
sessions_history	sessions	View session history
sessions_send	sessions	Send message to a session
sessions_spawn	sessions	Spawn a new session
session_status	sessions	Check session status
cron	automation	Schedule and manage cron jobs
gateway	automation	Gateway administration
browser	ui	Browser automation (navigate, click, type, screenshot)
announce_queue	automation	Async result announcement (for async delegations)

Documentation

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

Section	Topics
Getting Started	Installation, Quick Start, Configuration, Web Dashboard Tour
Core Concepts	Agent Loop, Sessions, Tools, Memory, Multi-Tenancy
Agents	Creating Agents, Context Files, Personality, Sharing & Access
Providers	Anthropic, OpenAI, OpenRouter, Gemini, DeepSeek, +15 more
Channels	Telegram, Discord, Slack, Feishu, Zalo, WhatsApp, WebSocket
Agent Teams	Teams, Task Board, Messaging, Delegation & Handoff
Advanced	Custom Tools, MCP, Skills, Cron, Sandbox, Hooks, RBAC
Deployment	Docker Compose, Database, Security, Observability, Tailscale
Reference	CLI Commands, REST API, WebSocket Protocol, Environment Variables

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 is built upon the original OpenClaw project. We are grateful for the architecture and vision that inspired this Go port.

License

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

Star History