# 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](user-guide/index.md) — Where to start: configuration, CLI, automation, observability and the fleet toolkit
- [CLI Reference](user-guide/cli-reference.md) — `goclaw setup`, gateway runtime, and every subcommand
- [Configuration](user-guide/configuration.md) — Comprehensive configuration guide
- [Webhook Routes](user-guide/configuration.md#webhook-routes) — `webhooks:` in `config.yaml`: which agent or SOP an outside system's POST to `/goclaw/hook/<type>/<key>` reaches
- [Public Ingress](user-guide/ingress.md) — Exposing the gateway through ngrok, Cloudflare, or a reverse proxy
- [Gateway Endpoints](api-reference/gateway_endpoints.md) — WebSocket server and REST APIs

### Multi-Agent & Routing

- [Agent Architecture](architecture/concepts/agent.md) — How GoClaw manages multiple agents
- [Agent Routing](architecture/routing.md) — Channel/role/tenant based agent resolution
- [Routing Bindings](user-guide/configuration.md#routing-bindings) — Configuring message-to-agent mapping
- [Subagents](architecture/subagents_and_jobs.md) — Spawning and managing task-specific agents
- [Autonomy Levels](architecture/autonomy_levels.md) — The guardrails between a chatbot and an AI employee

### Channels

- [Overview](user-guide/channels/index.md) — All supported messaging platforms
- [Telegram](user-guide/channels/telegram.md) — Long polling by default, so no public URL is needed
- [Discord](user-guide/channels/discord.md) — Bot token, guild overrides, threads and embeds; no public URL needed
- [Microsoft Teams](user-guide/channels/msteams.md) — Azure Bot registration and Teams packaging
- [Facebook Messenger](user-guide/channels/facebook.md) — Webhooks, page tokens, pairing
- [Enterprise App API](user-guide/channels/app-api.md) — Your own mobile app / intranet over REST, SSE and WebSocket
- [Pairing](user-guide/channels/pairing.md) — Access control and identity linking

### Automation

- [Automation Overview](user-guide/automation/index.md) — How scheduled and event-driven work fits together
- [Cron Jobs](user-guide/automation/cron-jobs.md) — Scheduled SOP runs and built-in commands
- [Standard Operating Procedures (SOPs)](user-guide/automation/sop.md) — Autonomous multi-step workflows
- [GitLab Webhook Integration](user-guide/automation/gitlab-webhook.md) — 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](user-guide/automation/sonarqube-hooks.md) — 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](user-guide/automation/zabbix-alerts.md) — 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](user-guide/automation/uptrace-monitors.md) — 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](user-guide/automation/wazuh-alerts.md) — 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](user-guide/automation/grafana-alert-rules.md) — 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](user-guide/automation/graylog-alerts.md) — 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](user-guide/tools_and_mcp.md) — Shell, File, Web, MCP, and more
- [Tool Offline Testing](user-guide/tool-exec-reference.md) — Direct tool execution without an LLM
- [Memory & Context Guide](user-guide/memory_and_context.md) — How the agent remembers and summarizes
- [Token Budgeting](user-guide/token-budgeting.md) — Keeping prompt cost predictable
- [Memory & RAG Architecture](architecture/memory.md) — Scopes, access, prompt context and the memory lifecycle
- [Memory Engine Architecture](architecture/memory_engine.md) — Internal RAG and summarization details
- [Tools Engine](architecture/tools_engine.md) — Tool and skill selection, caching, hooks and plugins
- [User Identity](architecture/concepts/identity_and_memory.md) — Cross-platform identity and personal memory
- [MCP Setup](user-guide/configuration.md#mcp-setup-model-context-protocol) — Connecting to Model Context Protocol servers

### Observability & Monitoring

- [Observability Overview](user-guide/observability/index.md) — Multi-source monitoring, incident workflow, config
- [SRE Tools](user-guide/observability/sre-tools.md) — Grafana, Graylog (log search, and `allow_write` for alerts that run a SOP), Uptrace, Zabbix, Wazuh
- [NetBox IPAM/DCIM](user-guide/observability/netbox.md) — IP, rack, server, VLAN, VM management
- [Metrics Store](user-guide/metrics-store.md) — Token and runtime metrics retention
- [Fleet Toolkit](user-guide/fleet.md) — Status, logs, reports, upgrades and restarts across many agents over SSH

### Security

- [Security Model](architecture/security.md) — Trust boundaries, sandboxing and tool permissions
- [Secrets Vault](architecture/secrets.md) — AES-256 encrypted credential storage
- [Audit Logging](architecture/audit_logging.md) — What gets recorded and where
- [Enterprise Security Matrix](architecture/enterprise-security-matrix.md) — Ports, egress allowlist, OS hardening and InfoSec controls
- [SBOM & Supply Chain](architecture/sbom.md) — CycloneDX/SPDX inventories and how to obtain them
- [Vulnerability Management & VEX](architecture/vulnerability-management.md) — govulncheck reports and OpenVEX advisories

### API Reference

- [Gateway Endpoints](api-reference/gateway_endpoints.md) — REST and WebSocket surface
- [OpenAI Compatibility](api-reference/openai_compatibility.md) — Drop-in `/v1/chat/completions`

### Vision

- [Vision Overview](vision/index.md) — Where GoClaw is heading
- [Level 4: AI Employees](vision/level4_final.md)
- [Level 5 Vision](vision/level5.md)
- [GoClaw Appliance](vision/goclaw-appliance.md)

## Architecture

```mermaid
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
```