# 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.md)**: Memory scopes and access, what goes into the prompt, hybrid search, fact extraction and the memory lifecycle.
- **[Memory Engine Architecture](memory_engine.md)**: The engine's internals: tables, ranking formulas, chunking, the session summarizer and memory flush, and the background job queue.
- **[Tools Engine](tools_engine.md)**: 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](techstack.md)**: Explains the internal modules, databases, LLM providers, and the event-driven actor model.
- **[Secrets Vault](secrets.md)**: Secure credentials management using local AES-256 vault configurations and reference resolutions.
- **[Autonomy Levels & Security](autonomy_levels.md)**: Highlights the security boundaries of GoClaw, detailing the 5 levels of AI autonomy and the Zero-Trust execution model.
- **[Subagents & the Job Queue](subagents_and_jobs.md)**: 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](concepts/agent.md)**: The agent loop, providers, the system prompt, bootstrap files, the workspace and the canvas.
- **[Event-Driven Runtime](event_driven_actor.md)**: 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](providers.md)**: The chat and embedding providers and the OpenAI-compatible API.
- **[Gemini API Implementation](gemini_implementation.md)**: The native Gemini loop: request configuration, thinking, sampling, multimodal input, Google Search and tool schema conversion.
- **[Provider Fallback & Cooldown](provider_fallback.md)** and **[Model Failover](concepts/model-failover.md)**: 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](llm_optimization.md)**: Where tokens go in the tool-call loop, and what Skill RAG, Tool RAG and result truncation save.
- **[Sessions](concepts/sessions.md)**: Session keys per channel, storage, lifecycle and how sessions are inspected.
- **[User Identity & Context](user_identity.md)**: How the current user's name and role are resolved and shown to the agent.
- **[Identity & Memory](concepts/identity_and_memory.md)**: How one person is recognised across channels, and how their personal memory is kept.
- **[Memory Formation Policy](memory_policy.md)**: What the agent remembers from a message, and under whose authority.
- **[SOP Virtual Level](sop-virtual-level.md)**: The model of delegated permissions a SOP runs under for a user.

## Channels, Gateway & APIs

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

## Operations

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