GoClaw Documentation

GoClaw is a high-performance Multi-Agent Orchestration Platform and AI Gateway implemented in Go. It provides a unified interface for multiple AI models, advanced agent routing, and a robust tool ecosystem, optimized for low-resource environments like home servers and NAS devices.

Key Capabilities

• Agent Router: Intelligent message routing based on channel, user, or group to specific specialized agents.
• Multi-Agent Orchestration: Run multiple isolated agents (e.g., Personal Assistant, Coding Expert, Family Bot) with unique personalities, models, and toolsets.
• Subagent Delegation: Primary agents can spawn temporary subagents for complex multi-step tasks.
• RAG & Long-term Memory: Integrated Retrieval-Augmented Generation for persistent memory and context-aware interactions.
• AI Gateway: A unified REST/WebSocket gateway compatible with major AI providers (Gemini, OpenAI, Claude, DeepSeek, Ollama, and any OpenAI-compatible endpoint).
• Built-in Tools: Shell, files, web, databases, observability and code analysis, compiled into the binary and selected per query by a RAG tool filter. A few wrap programs that must be installed (Chrome for the browser and PDF reports, linters and scanners).
• Model Context Protocol (MCP): Native support for MCP servers (stdio, SSE, HTTP) to extend agent capabilities dynamically.

Quick Navigation

Getting Started

• User Guide — Where to start: configuration, CLI, automation, observability and the fleet toolkit
• CLI Reference — goclaw setup, gateway runtime, and every subcommand
• Configuration — Comprehensive configuration guide
• Webhook Routes — webhooks: in config.yaml: which agent or SOP an outside system's POST to /goclaw/hook/<type>/<key> reaches
• Public Ingress — Exposing the gateway through ngrok, Cloudflare, or a reverse proxy
• Gateway Endpoints — WebSocket server and REST APIs

Multi-Agent & Routing

• Agent Architecture — How GoClaw manages multiple agents
• Agent Routing — Channel/role/tenant based agent resolution
• Routing Bindings — Configuring message-to-agent mapping
• Subagents — Spawning and managing task-specific agents
• Autonomy Levels — The guardrails between a chatbot and an AI employee

Channels

• Overview — All supported messaging platforms
• Telegram — Long polling by default, so no public URL is needed
• Discord — Bot token, guild overrides, threads and embeds; no public URL needed
• Microsoft Teams — Azure Bot registration and Teams packaging
• Facebook Messenger — Webhooks, page tokens, pairing
• Enterprise App API — Your own mobile app / intranet over REST, SSE and WebSocket
• Pairing — Access control and identity linking

Automation

• Automation Overview — How scheduled and event-driven work fits together
• Cron Jobs — Scheduled SOP runs and built-in commands
• Standard Operating Procedures (SOPs) — Autonomous multi-step workflows
• GitLab Webhook Integration — Receiving push/pipeline/MR events from GitLab. Set it up by asking the agent (gitlab_hook), with the goclaw gitlab hook wizard, or by hand
• SonarQube Quality Gates That Run a SOP — SonarQube's webhook after each analysis runs a SOP when the quality gate fails (or always). Set it up by asking the agent (sonarqube_hook) or by hand
• Zabbix Problems That Run a SOP — a Zabbix action calls the gateway when a problem starts on the host groups you choose, and runs a SOP. Set it up by asking the agent (zabbix_alert) or by hand
• Uptrace Monitors That Run a SOP — an Uptrace monitor's webhook channel calls the gateway when an alert opens, and runs a SOP. Set it up by asking the agent (uptrace_monitor) or by hand
• Wazuh Alerts That Run a SOP — a monitor in the Wazuh indexer calls the gateway with the Wazuh alerts it finds, and runs a SOP. Set it up by asking the agent (wazuh_alert) or by hand
• Grafana Alert Rules That Run a SOP — a Grafana alert rule calls the gateway when it fires, and runs a SOP. Set it up by asking the agent (grafana_alert_rule) or by hand
• Graylog Alerts That Run a SOP — Graylog alert webhook: Graylog calls the gateway's hook (/goclaw/hook/graylog/<key>) and each alert runs a SOP. Set it up by asking the agent, or by hand on the Webhooks page

Tools & Memory

• Tools, Skills & MCP — Shell, File, Web, MCP, and more
• Tool Offline Testing — Direct tool execution without an LLM
• Memory & Context Guide — How the agent remembers and summarizes
• Token Budgeting — Keeping prompt cost predictable
• Memory & RAG Architecture — Scopes, access, prompt context and the memory lifecycle
• Memory Engine Architecture — Internal RAG and summarization details
• Tools Engine — Tool and skill selection, caching, hooks and plugins
• User Identity — Cross-platform identity and personal memory
• MCP Setup — Connecting to Model Context Protocol servers

Observability & Monitoring

• Observability Overview — Multi-source monitoring, incident workflow, config
• SRE Tools — Grafana, Graylog (log search, and allow_write for alerts that run a SOP), Uptrace, Zabbix, Wazuh
• NetBox IPAM/DCIM — IP, rack, server, VLAN, VM management
• Metrics Store — Token and runtime metrics retention
• Fleet Toolkit — Status, logs, reports, upgrades and restarts across many agents over SSH

Security

• Security Model — Trust boundaries, sandboxing and tool permissions
• Secrets Vault — AES-256 encrypted credential storage
• Audit Logging — What gets recorded and where
• Enterprise Security Matrix — Ports, egress allowlist, OS hardening and InfoSec controls
• SBOM & Supply Chain — CycloneDX/SPDX inventories and how to obtain them
• Vulnerability Management & VEX — govulncheck reports and OpenVEX advisories

API Reference

• Gateway Endpoints — REST and WebSocket surface
• OpenAI Compatibility — Drop-in /v1/chat/completions

Vision

• Vision Overview — Where GoClaw is heading
• Level 4: AI Employees
• Level 5 Vision
• GoClaw Appliance

Architecture

flowchart TD
    subgraph CH["Channels"]
        C1["Telegram"]
        C2["Discord"]
        C3["MS Teams"]
        C4["Messenger"]
        C5["App API / Web"]
    end

    GW["<b>AI Gateway</b><br/>REST · WebSocket · SSE · Webhooks"]

    ROUTER["<b>Agent Router</b><br/>channel / role / tenant → agent"]

    subgraph ENGINE["Execution Engine"]
        direction LR
        MA["<b>Multi-Agent Orchestrator</b><br/>Isolated contexts · Subagents · SOPs"]
        TOOLS["<b>Tools & MCP</b><br/>Built-in tools · RAG-filtered · Security"]
    end

    subgraph STORE["Persistence & Memory"]
        direction LR
        MEM["<b>Memory & Sessions</b><br/>SQLite (gc_state) · Embeddings · Replay"]
        KG["<b>Knowledge Graph</b><br/>SQLite (kg) · Entity Relations"]
    end

    CH --> GW
    GW --> ROUTER
    ROUTER --> MA
    ROUTER --> TOOLS
    MA <--> TOOLS
    MA --> STORE

State Directory

Default: ~/.goclaw/ (override with GOCLAW_STATE_DIR)

~/.goclaw/
├── config.yaml           # Unified configuration (hot-reloaded)
├── gc_state.sqlite       # Sessions, long-term memory, SOPs, cron jobs
├── kg.sqlite             # Knowledge graph store
├── workspace/            # IDENTITY.md, USER.md, Memory.md, memory/
├── agents/               # Isolated agent environments
│   └── <agent_id>/
│       └── workspace/    # Agent-scoped files and memory
├── memory/personal/      # Per-user private memory (user_<id>.md)
├── credentials/          # AES-256 encrypted secrets and channel credentials
├── skills/               # Global skills
├── plugins/              # Installed plugins (subagents, instructions, skills, hooks, MCP servers)
├── media/                # Uploaded and generated media
├── canvas/               # Diagram and screenshot artifacts
├── cache/                # Transient caches
├── traces/archive/       # Nightly trace dumps (JSONL.gz)
└── logs/                 # System and agent logs