How GoClaw Reimagines OpenClaw: A Go‑Powered AI Assistant Architecture

Overview

GoClaw is a personal AI assistant written in Go. It runs as a local server exposing WebSocket and HTTP endpoints and can be connected to multiple messaging channels such as Telegram, WhatsApp, Feishu, QQ, and Slack.

Core Positioning

Language : Go (single static‑linked binary)

Architecture : CLI application + gateway server

Deployment : Local process, exposes WebSocket/HTTP

Extensibility : Skill system compatible with OpenClaw

Reliability : Serial execution by default, fault‑tolerance, reflection mechanism

System Panorama

┌──────────────────────────────────────────────────────────────────────────────┐
│                     GoClaw System Architecture                           │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   │
│   │ InputChannel│──►│ Gateway Server│──►│ Agent Loop │──►│ LLM/Tool   │   │
│   └─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘   │
│        │                │                │                │                │
│        ▼                ▼                ▼                ▼                │
│ Telegram/WhatsApp   MessageBus   SessionManager   Providers (OpenAI, Anthropic…)│
└──────────────────────────────────────────────────────────────────────────────┘

Agent Loop Execution Engine

The Agent Loop is the brain of GoClaw. It follows the PI Agent concept – a minimal‑coding agent that lets the LLM do most of the work and adds only a thin wrapper.

"LLMs are already good at writing and executing code; they need little extra scaffolding."

Component Comparison

Loop model : Stream → Execute → Reflect → Continue (GoClaw) vs. Stream → Execute → Continue (PI) vs. Observe → Think → Act → Plan (traditional ReAct)

System prompt size : ~1.5 KB (GoClaw) vs. <1 KB (PI) vs. thousands of tokens (traditional)

Tool count : Core tools + extensible (GoClaw) vs. 4 core tools (PI) vs. many dedicated tools (traditional)

Max steps : 15 + reflection decision (GoClaw) vs. unlimited (PI) vs. fixed 20 (traditional)

Planning mode : Optional reflection mechanism (GoClaw) vs. file‑visible planning (PI) vs. built‑in planning stage (traditional)

Execution Flowchart

┌───────────────────────────────────────────────────────────────────┐
│                GoClaw Agent Loop                               │
├───────────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   │
│  │ Receive  │──►│ Build    │──►│ LLM Call │──►│ Execute   │   │
│  │ Message  │   │ Context  │   │          │   │ Tool      │   │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘   │
│                                   │                         │
│                                   ▼                         │
│                         ┌─────────────────┐                │
│                         │ Tool Result      │                │
│                         └─────────────────┘                │
│                                   │                         │
│                                   ▼                         │
│                         ┌─────────────────┐                │
│                         │ Reflection?     │ (optional)    │
│                         └─────────────────┘                │
│                                   │                         │
│                         ┌─────────────┴─────────────┐      │
│                         ▼                           ▼      │
│                 ┌─────────────┐               ┌─────────────┐│
│                 │ Continue    │               │ Return Resp ││
│                 └─────────────┘               └─────────────┘│
└───────────────────────────────────────────────────────────────────┘

Core Components

1. Context Builder (agent/context.go)

type ContextBuilder struct {
    memory       *MemoryStore
    workspace    string
    agentID      string
    defaultModel string
    provider     string
}

Responsibilities:

Dynamically assemble system prompts

Inject available tool definitions

Add session history from JSONL files

Integrate relevant memory entries

Compress the context window while protecting recent rounds

Context compression keeps the last 10 dialogue rounds and all system messages, discarding older history.

2. Tools Registry (agent/tools/registry.go)

Core tool set mirrors the four PI tools: read_file – read a file (line numbers, glob) – PI equivalent

read

write_file

– create/overwrite a file – PI equivalent

write

edit_file

– precise string replacement – PI equivalent

edit

run_shell

– execute a shell command – PI equivalent bash Additional extensible tools include: browser_* – Chrome DevTools operations smart_search – hybrid vector + FTS5 search spawn – sub‑agent management message – send a message to a channel

3. Reflector (agent/reflection.go)

type Reflector struct {
    config   *ReflectionConfig
    provider providers.Provider
    workspace string
}

type TaskReflection struct {
    Status          string   // "completed", "in_progress", "failed", "blocked"
    Confidence      float64  // 0.0‑1.0
    CompletedSteps []string
    RemainingSteps []string
    Reasoning      string
    NextAction     string
}

The reflector decides whether another iteration is needed, solving the classic "when to stop" problem of fixed‑iteration agents.

reflection, err := l.reflector.Reflect(ctx, userRequest, history)
if l.reflector.ShouldContinueIteration(reflection, iteration, l.maxIteration) {
    continuePrompt = l.reflector.GenerateContinuePrompt(reflection)
    continue
}

Compared with a static max‑iteration limit, this provides a dynamic termination condition.

4. Error Classifier (agent/error_classifier.go)

type ErrorClassifier struct {
    authPatterns      []string
    rateLimitPatterns []string
    timeoutPatterns   []string
    billingPatterns   []string
}

Classifications: auth – authentication errors (trigger provider failover) rate_limit – rate‑limit errors (require cooldown) timeout – timeout errors (retryable) billing – billing errors (trigger failover) tool – tool execution errors (return to LLM for self‑correction)

The classifier feeds a three‑layer fault‑tolerance strategy: tool‑level retry, iteration‑level fallback, and provider‑level failover.

GoClaw vs OpenClaw PI Agent

Architecture Comparison

// OpenClaw PI (TypeScript) – minimal loop
while (true) {
    const response = await streamCompletion(model, context);
    if (!response.toolCalls?.length) break;
    for (const call of response.toolCalls) {
        const result = await executeToolCall(call, context);
        context.messages.push(result);
    }
}

// GoClaw (Go) – enhanced loop
for iteration < l.maxIteration {
    response, err := l.provider.Chat(ctx, messages, tools)
    if len(response.ToolCalls) > 0 {
        for _, tc := range response.ToolCalls {
            result, err := l.executeToolWithRetry(ctx, tc.Name, tc.Params)
        }
        continue
    }
    if response.Content == "" && l.reflector != nil {
        reflection := l.reflector.Reflect(ctx, userRequest, history)
        if !l.reflector.ShouldContinueIteration(reflection, iteration, l.maxIteration) {
            break
        }
        continue
    }
    break
}

Session Storage Comparison

Format : OpenClaw uses an append‑only DAG; GoClaw stores a linear JSONL file (one object per line).

Cross‑model support : Both expose an abstraction layer (pi‑ai for OpenClaw, Provider for GoClaw).

Persistence : OpenClaw keeps a single file; GoClaw writes JSONL per session.

Branching : OpenClaw moves a leaf pointer efficiently; GoClaw creates a new session object for branching.

Extension System Comparison

OpenClaw PI – TypeScript hooks

hooks: {
  onSessionStart: async (session) => { ... },
  onBeforeTurn: async (session) => { ... },
  onToolCall: async (tool, params) => { ... },
  // 20+ lifecycle hooks
}

GoClaw – Skills system

type Skill struct {
    Name        string
    Description string
    Triggers    []string // keywords
    Content     string   // Markdown command
    Requires    []string // gating dependencies
}

Design Philosophy Comparison

Core principle : OpenClaw – "LLMs know how to code"; GoClaw – "Reliability over complexity".

System prompt size : <1 KB (OpenClaw PI) vs. ~1.5 KB (GoClaw).

Tool philosophy : Minimal set of 4 (OpenClaw PI) vs. core + extensible (GoClaw).

Error handling : Return to model for self‑correction (OpenClaw) vs. classification + retry + degradation (GoClaw).

Termination condition : Natural stop (OpenClaw) vs. reflection + max iterations (GoClaw).

Observability : Transparent plan files (OpenClaw) vs. structured logs + session persistence (GoClaw).

GoClaw Unique Innovations

Reflection mechanism – dynamic decision on whether to continue an iteration.

Error classification with three‑layer fault tolerance.

Hybrid search – vector similarity (SQLite + embeddings) combined with FTS5 keyword search.

Skill gating – automatic loading of skills based on environment detection.

Context compression – retains recent 10 rounds and all system messages while discarding early history.

Gateway Server (gateway/server.go)

type Server struct {
    config      *config.GatewayConfig
    wsConfig    *WebSocketConfig
    bus         *bus.MessageBus
    channelMgr  *channels.Manager
    sessionMgr  *session.Manager
    connections map[string]*Connection
}

Key functions:

Handles overlapping requests.

Message bus with a serial default queue.

WebSocket connection support.

Webhook callbacks.

HTTP health‑check endpoint.

Memory System

Dual‑Memory Architecture

Session records (JSONL) – each line is a JSON object containing user messages, tool calls, results, and responses. This provides persistent session memory.

Memory files (Markdown) – generated by the agent via the standard file‑write tool (e.g., MEMORY.md or a memory/ folder). No special API is required.

Hybrid Search

Vector search – semantic similarity using SQLite with embedded vectors.

Keyword search (FTS5) – exact phrase matching via the SQLite FTS5 extension.

type MemoryManager struct {
    store    Store
    provider EmbeddingProvider
    cache    map[string]*VectorEmbedding
}

Shell Execution

Sandbox (default) – runs inside a Docker container.

Host – executes directly on the host.

Remote device – executes on a remote machine.

File System Tools

read_file

– read a file. write_file – write/overwrite a file. edit_file – edit a file. list_files – list directory contents.

Browser Tools (Chrome DevTools Protocol)

browser_navigate

– navigate to a URL. browser_screenshot – capture a page screenshot. browser_execute_script – run JavaScript. browser_click – click an element. browser_get_text – extract page text.

type BrowserTool struct {
    headless  bool
    timeout   time.Duration
    outputDir string
}

Security Mechanisms

Allowlist

{
    "agents": {
        "main": {
            "allowlist": [
                {"pattern": "/usr/bin/npm", "lastUsedAt": 1706644800},
                {"pattern": "/opt/homebrew/bin/git", "lastUsedAt": 1706644900}
            ]
        }
    }
}

Pre‑approved Safe Commands

Allowed utilities include jq, grep, cut, sort, uniq, head, tail, tr, and wc.

Dangerous Construct Blocking

# These patterns are rejected before execution:
npm install $(cat /etc/passwd)   # command substitution
cat file > /etc/hosts           # redirection
rm -rf / || echo "failed"      # logical OR chaining
(sudo rm -rf /)                 # subshell

LLM Providers & Failover

Supported providers: OpenAI (compatible API), Anthropic, OpenRouter.

type FailoverProvider struct {
    primary          Provider
    fallback         Provider
    circuitBreaker   *CircuitBreaker
    errorClassifier  types.ErrorClassifier
}

Features:

Circuit‑breaker mode – prevents repeated calls to a failing provider.

Error classification – distinguishes retryable vs. non‑retryable errors.

Automatic switch – falls back to the secondary provider on primary failure.

Skill System

Skills are prompt‑driven command sets injected into the system prompt. They are fully compatible with OpenClaw’s skill ecosystem and support automatic gating based on environment detection.

Skill Loading Order

Custom directory supplied by the user.

workspace/skills/

workspace/.goclaw/skills/

Executable path /skills/ Current directory ./skills/ (highest priority).

Project Structure

goclaw/
├── agent/               # Core agent logic
│   ├── loop.go          # Agent loop with retry logic
│   ├── context.go       # Context builder
│   ├── memory.go        # Memory system
│   ├── skills.go        # Skill loader
│   ├── reflection.go    # Reflection mechanism
│   ├── error_classifier.go
│   └── tools/           # Tool implementations
├── channels/            # Message channel adapters
├── bus/                 # Message bus
├── config/              # Configuration management
├── providers/           # LLM providers (failover, circuit breaker)
├── session/             # Session management
├── memory/              # Persistent memory storage
├── cli/                 # Command‑line interface
└── gateway/             # Gateway server

Quick Start

# Build the binary
go build -o goclaw .

# Example config.json
{
  "agents": {
    "defaults": {
      "model": "openrouter:anthropic/claude-opus-4-5",
      "max_iterations": 15
    }
  },
  "providers": {
    "openrouter": {"api_key": "your-key"}
  },
  "channels": {
    "telegram": {"enabled": true, "token": "your-bot-token"}
  }
}

# Run the server
./goclaw start

Conclusion

GoClaw inherits OpenClaw’s core design while leveraging Go’s static typing, goroutine concurrency, and compiled binary delivery to provide a more robust, high‑performance AI assistant.

Minimal core with extensible skills.

Serial execution by default; explicit parallelism when needed.

Reliability prioritized over complexity.

Full observability through structured logs and session persistence.

"This simplicity can be an advantage or a trap, depending on perspective. I always favor explainable simplicity over tangled spaghetti code."