goclaw README

The project's README from github.com/nextlevelbuilder/goclaw. As one markdown file: README.md.

GoClaw

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

Go PostgreSQL Docker WebSocket OpenTelemetry Anthropic OpenAI License: CC BY-NC 4.0

🌐 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

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

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

Multi-Tenant Architecture

3-Tier Memory

8-Stage Agent Pipeline

4-Mode Prompt System

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

# If Postgres fails to start ("port 5432 already allocated"), set another host
# port in .env, e.g. POSTGRES_PORT=5433 (see .env.example).

# 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:

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

Agent Orchestration

Each agent runs with its own identity, tools, LLM provider, and context files. Agent Links define outbound, inbound, or bidirectional permission edges. Delegation can run synchronously or asynchronously and exchanges files through an isolated delegation workspace; validated outputs are published back under the caller's .delegations/<delegation-id>/ directory.

Details: Agent Teams docs

Knowledge Vault

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

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

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

DomainEventBus

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:

Category Tools Description
Filesystem read_file, write_file, edit_file, list_files, search, glob File operations with virtual FS routing
Runtime exec, browser Shell commands (approval workflow) + browser automation
Web web_search, web_fetch Search (Brave, DuckDuckGo) + content extraction
Memory memory_search, memory_get, knowledge_graph_search 3-tier memory + KG traversal
Media create_image, create_audio, create_video, read_*, tts Generation + analysis (multi-provider)
Skills skill_search, use_skill, skill_manage BM25 + semantic hybrid search
Teams team_tasks, spawn, delegate, message Task board + orchestration + messaging
Automation cron, heartbeat, sessions_* Scheduling + session management

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 for the full reference: auth, async callbacks, retry schedule, HMAC examples, channel matrix.

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 was originally inspired by the OpenClaw project architecture.

License

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

Star History

Star History Chart

goclaw (nextlevelbuilder/goclaw)

Searching Database…

3.7K ·GitHub
Goclaw
Что это?GoClaw — это мультиарендный шлюз/платформа для AI-агентов на Go, которая соединяет 20+ провайдеров LLM с 7 каналами обмена сообщениями, позволяя развертывать команды AI-агентов в масштабе и управлять ими с защитой производственного уровня.
Это библиотека для импорта или отдельный сервис для развертывания?Это отдельный сервер, который вы развертываете, а не библиотека: он поставляется в виде одного статического Go-бинарника ~25 МБ (рантайм Node.js не нужен) или Docker-сервиса со встроенной веб-панелью.
Как запустить GoClaw?Склонируйте репозиторий и выполните `make up` с Docker — он создаст сеть, соберет и запустит все сервисы и автоматически прогонит миграции базы данных; как вариант, соберите из исходников с Go напрямую под свой экземпляр PostgreSQL.
Что нужно установить перед запуском?Нужны Go 1.26+ и PostgreSQL 18 с расширением pgvector; Docker опционален, но рекомендуется для настройки одной командой.
Достаточно ли это стабильно для продакшена прямо сейчас?Ветка git по умолчанию — активная разработка (dev), поэтому для стабильного релиза нужно явно переключиться на ветку main; смотрите CHANGELOG.md, чтобы понять, какие функции реально проверены в продакшене, а какие еще в работе.
Как он изолирует и защищает данные тенантов?Каждый пользователь получает отдельное рабочее пространство и контекстные файлы в PostgreSQL, API-ключи шифруются с помощью AES-256-GCM, а доступ контролируется через RBAC с изолированными сессиями для каждого тенанта.
Можно ли использовать GoClaw в коммерческих целях?Нет — GoClaw распространяется по лицензии CC BY-NC 4.0 (Creative Commons Attribution-NonCommercial), которая явно ограничивает коммерческое использование.
В какие мессенджеры можно развертывать агентов?GoClaw из коробки поддерживает 7 каналов: Telegram, Discord, Slack, Zalo OA, Zalo Personal, Feishu/Lark и WhatsApp.
Что такое функция Knowledge Vault?Это реестр документов с [[wikilinks]] для двунаправленных ссылок, сочетающий полнотекстовый и семантический поиск через pgvector, с синхронизацией файловой системы, так что хранилище отражает документы на диске.
Что агенты реально могут менять благодаря 'Self-Evolution'?Агенты запускают конвейер с ограничителями — сбор метрик, анализ предложений и автоадаптацию, — чтобы оттачивать стиль общения и экспертизу в предметной области, но они никогда не могут менять собственную идентичность, имя или основное назначение.
Как несколько агентов координируют работу над задачами?Агенты делятся досками задач и могут передавать работу друг другу синхронно или асинхронно, с тремя режимами оркестрации: auto, explicit или manual.
What are similar projects?WeKnora, zilan, trueforge, production-agentic-rag-course, evenfire, hive, ruflo, hermes-agent
Which topics is it in?discord-bot, feishu, telegram-bot, ai-gateway, harness-engineering, event-driven, whatsapp, webhooks, rbac, slack, semantic-search, harness
Creator
nextlevelbuilder
Size
39.4 MB
Stars
3.7K
Updated
CommitOct 04Releasev3.14.0Jun 15
Age
7mo
Commits · 90 Days