GoClaw Architecture Documentation

GoClaw is designed as a secure, high-performance cognitive multi-agent gateway. It is compiled into a single binary with zero external runtime dependencies.

Key Subsystems

• Cognitive Memory & RAG: Memory scopes and access, what goes into the prompt, hybrid search, fact extraction and the memory lifecycle.
• Memory Engine Architecture: The engine's internals: tables, ranking formulas, chunking, the session summarizer and memory flush, and the background job queue.
• Tools Engine: How tools and skills are registered, selected for a request (Tool and Skill RAG), cached and run, and the admin hooks and plugins around them.
• Ecosystem & Tech Stack: Explains the internal modules, databases, LLM providers, and the event-driven actor model.
• Secrets Vault: Secure credentials management using local AES-256 vault configurations and reference resolutions.
• Autonomy Levels & Security: Highlights the security boundaries of GoClaw, detailing the 5 levels of AI autonomy and the Zero-Trust execution model.
• Subagents & the Job Queue: How a parent agent delegates scoped tasks to child agents, the spawn policy, and the SQLite-backed job queue, EventBus, and workers behind async execution.

Agent Runtime

• Agent Runtime: The agent loop, providers, the system prompt, bootstrap files, the workspace and the canvas.
• Event-Driven Runtime: How the agent loop moved from blocking calls to event streams: the bounded tool worker pool, the single-writer WebSocket, cancellation, and one turn per session.
• LLM Providers: The chat and embedding providers and the OpenAI-compatible API.
• Gemini API Implementation: The native Gemini loop: request configuration, thinking, sampling, multimodal input, Google Search and tool schema conversion.
• Provider Fallback & Cooldown and Model Failover: When an agent's provider fails before the reply has used a tool, the request moves to the next provider of ai.fallback (or the agent's own list), with cooldowns for providers that keep failing.
• LLM Token Optimization: Where tokens go in the tool-call loop, and what Skill RAG, Tool RAG and result truncation save.
• Sessions: Session keys per channel, storage, lifecycle and how sessions are inspected.
• User Identity & Context: How the current user's name and role are resolved and shown to the agent.
• Identity & Memory: How one person is recognised across channels, and how their personal memory is kept.
• Memory Formation Policy: What the agent remembers from a message, and under whose authority.
• SOP Virtual Level: The model of delegated permissions a SOP runs under for a user.

Channels, Gateway & APIs

• Channel Router & Pairing: The Channel interface, inbound message metadata, agent routing priority, pairing, and how to add a channel.
• Multi-Agent Routing: Bindings that send a channel, server, team or role to an agent, and identity links.
• Protocol: The gateway's HTTP and WebSocket protocol and its endpoints, compared with OpenClaw's.
• OpenAI-Compatible API: How /v1/chat/completions maps onto an agent run.
• Media Pipeline: Attachments, uploads, the media store and canvas files.
• Web UI / Control Panel: The dashboard's pages and how it talks to the gateway.
• Apps: The voice and desktop features (built, and disabled) and the mobile and menubar apps (planned, not built).

Operations

• Debug & Observability: Debug logging, prompt capture, live agent traces, and the SRE tools (Graylog, Uptrace, Zabbix, Grafana, Wazuh).
• OpenTelemetry Logging Pipeline: Where the gateway's logs go: console, file, the Web UI and an OTLP exporter.
• Runtime Info & Ingress Metrics: The in-process status the Web UI and the CLI read: gateway, ingress, the access log and the webhook audit log.
• CLI & Daemon: The goclaw commands and how the gateway runs as an OS service.
• Distribution & Auto-Update: The single binary, Docker image, service templates and updates.
• Ecosystem: The Go plugin SDK, gateway hook events, the skills registry and the cron system.
• Minimal Dependency Strategy: Why GoClaw is one binary with no runtime dependencies, which tools need something from the OS, and the rules for contributors.
• Testing: How the test suite is organised.