GoClaw is a lightweight, high-performance Autonomous AI Agent Gateway and Multi-Agent Orchestrator compiled as a single binary. It is engineered to run on consumer hardware, local home servers, and NAS environments.
GoClaw is organized into several logical system boundaries that separate user interactions, agent execution, and system state:
flowchart LR
CH["<b>Chat Channels</b><br/>Discord, MS Teams, Web, …"] --> GW["<b>AI Gateway</b><br/>WebSocket / REST"]
GW --> RT["<b>Agent Router</b><br/>Orchestrator"]
GW --> DB["<b>Session State</b><br/>SQLite / Postgres / MySQL / ClickHouse"]
RT --> POOL["<b>Agent Pools</b><br/>Isolated Soul / Workspace"]
/v1/chat/completions). Enforces API rate limiting and authenticates requests.config.yaml refers to are not kept there: they are in the encrypted vault (credentials/secrets.enc in the state directory), and pairings in JSON files. A webhook route made on the Webhooks page keeps its secret and token in the database, as typed (a ${secret:NAME} reference keeps the value in the vault).GoClaw includes built-in driver layers for both internal state persistence (GORM) and external agent query datasources:
GoClaw's tools are compiled directly into the binary; goclaw tools list lists them. Agents dynamically request access to these tools depending on their allowed roles and current tasks:
| Category | Description | Primary Tools |
|---|---|---|
| File Operations | Read, write, search, and patch files in sandboxed workspaces. | file_read, file_write, apply_patch, glob_files |
| Code Analysis | Generate AST structure maps and analyze source code files. | repo_map, ast_declarations_search, dependency_map |
| Version Control | Execute local Git actions and review repository states. | git, auto_commit, diff |
| Collaboration | Call GitLab APIs to read issues, pipeline status, and MRs. | gitlab |
| Databases | Securely query PostgreSQL, MySQL, ClickHouse, and MongoDB. | db_query, mongo_query |
| Communication | Route outgoing messages, alerts, emails, and notifications. | message, email, notify |
| Memory & RAG | Read and write from scoped long-term memory. | memory_search, memory_write, memory_consolidate |
| Web & Automation | SSRF-safe HTTP calls and headless Chrome browser control. | http_request, browser (actions: navigate, screenshot, content, click, type, …) |
| Observability | Search system logs, traces, APM alerts, and inventory data. | grafana_alerts, graylog_query, uptrace_query, zabbix_query, netbox |
| Media & Documents | Speech-to-text and text-to-speech, read PDFs, and analyze images. | voice_input (speech-to-text), voice_output (text-to-speech), pdf, image |
| Scheduling | Define and manage automated workflows and periodic jobs. | cron, sop_run, sop_save, sop_list, … |
To safeguard the host server from resource depletion, GoClaw implements bounded concurrency pools and loop detection parameters:
| Parameter | Configuration Key | Default Value | Description |
|---|---|---|---|
| Tool Worker Pool | tools.worker_pool_size |
8 |
Maximum number of concurrent tool executions across all sessions. |
| Backpressure Queue | tools.worker_queue_size |
64 |
Depth of the queue holding pending tool executions. |
| Output Writer | - | 1 |
Single-writer pump per WebSocket connection to guarantee message order. |
| Parameter | Configuration Key | Default Value | Description |
|---|---|---|---|
| Max Tool Iterations | tools.max_tool_iterations |
20 |
Maximum number of continuous tool runs permitted in a single chat turn. Prevents infinite loops. |
| Result Spill | tools.max_result_chars |
8000 |
A tool result longer than this is not passed to the model whole: the full result is kept in the output store for 1 hour and the model gets a preview with a data_ref, which it reads further with read_output. db_query results are always stored this way. |
| Full Result Rounds | tools.full_result_rounds |
4 |
Within one turn, the results of this many newest tool rounds are sent to the model whole; an older result over 2,000 characters is cut to its start and the read_output ref that reads it whole. -1 keeps every result whole. |
| Dynamic Tools (RAG) | tools.rag.top_k |
12 |
Maximum number of dynamically matched tools injected into the prompt. |
| RAG Threshold | tools.rag.min_score |
0.15 |
Minimum matching confidence score required to auto-enable a tool for a query. |
GoClaw is highly flexible and can be deployed in multiple environments:
docker-compose.yaml. It mounts ./config.yaml at /app/config.yaml and a named volume, goclaw-state, on the state directory /home/goclaw/.goclaw (database, vault, workspace, logs). The mounted config.yaml must set gateway.bind: lan, or the gateway listens on the container's loopback and the port mapping reaches nothing. Set GOCLAW_SECRET_KEY before the vault is first written: without it the vault key is derived from values that are the same in every container of the image, so anyone with the image can derive it./ansible for multi-node setups.