HexClaw Architecture Explained: One Person + Claude + Five Months, Building a Six-Repository Full-Stack Open-Source AI Agent Ecosystem in Go

Last year, I wanted to deploy an AI agent for myself.

There were plenty of AI agent products, and major vendors were entering the market, but the same problems kept appearing:

• Open-source products lacked safety: OpenClaw, the “lobster,” had the broadest feature set and largest community, but essentially no safety protections or cost controls. I did not dare use it in production.
• Safer products were not open source: commercial products handled compliance well, but were closed-source and cloud-hosted. Cross-border data flows were hard to control, and monthly subscriptions were expensive.
• Usable products did not support Chinese platforms: overseas products largely omitted Feishu, DingTalk, WeCom, and WeChat Official Accounts.

What I needed was the breadth of open-source functionality + commercial-grade safety + full coverage of Chinese platforms, with self-hosting and single-binary deployment. I could not find it, so I built it myself: one person paired with Claude, six repositories, and a full-stack AI agent. That is HexClaw, the crab.

This article lays out the complete architecture: technical decisions, implementation details, and the mistakes along the way.

Before we start, a few concepts to align on (skip these if you know them already):

LLM = a brilliant university student who has read every book: broadly knowledgeable, but with an expiration date on that knowledge and an occasional tendency to make things up (hallucinations). RAG = handing that student reference notes so they answer from sources rather than inventing things. MCP = a universal USB adapter connecting the brain to tools through plug-and-play interfaces. Agent = a versatile worker who can plan independently, call tools, and deliver results. Skills = professional skill certificates for that worker, loaded as needed. Agent Cluster = a team of workers dividing tasks and collaborating.

HexClaw turns these concepts into an engineered, runnable system.

Key Numbers

Overview: Six Repositories, Five Architectural Layers

                    hexclaw-desktop (Tauri desktop)
                    hexagon-ui (observability console)
                          │
                    ┌─────▼─────┐
                    │  hexclaw   │  Application: adapters, gateway, Skills, API
                    └─────┬─────┘
                          │
                    ┌─────▼─────┐
                    │  hexagon  │  AI agent engine: ReAct, Workflow,
                    │           │  Plugin, A2A, Graph, Compose
                    └──┬─────┬──┘
                       │     │
                 ┌─────▼──┐  │
                 │ai-core │  │  AI foundation: LLM providers,
                 │        │  │  Embedding, Function Calling
                 └────┬───┘  │
                      │      │
                 ┌────▼──────▼┐
                 │  toolkit   │  Foundation library (bottom layer, used by all Go modules)
                 └────────────┘

Dependencies between the six repositories flow strictly upward, with no reverse dependencies or cross-layer calls. This is the foundation for reusability, extensibility, and independent evolution:

• Any Go project can use toolkit / ai-core without depending on HexClaw.
• As a general-purpose AI agent engine, hexagon can be used independently of hexclaw to build entirely different agent applications.
• As the AI agent application backend, hexclaw only orchestrates application-level behavior. New capabilities belong in the corresponding lower layer rather than being implemented in place.

Why Go, and Why Build Our Own Framework?

The two questions belong together.

Language choice: agent bottlenecks are I/O: waiting for LLM responses, tools, and webhooks from 13 platforms. Goroutines are an order of magnitude more efficient than Python asyncio and have no GIL. For deployment, hexclaw serve runs everything in one command, without managing virtual environments.

Framework choice: on the Python side, I evaluated LangChain/LangGraph (the largest ecosystem, but limited by the GIL) and CrewAI (quick to learn, weaker orchestration); on the Go side, Eino (from ByteDance, but missing safety modules). I ultimately built my own because there was no ready-made combination of native Go + enterprise-grade safety + complete RAG + production-grade observability available.

Hexagon takes its name from the Chinese term for a “well-rounded warrior,” emphasizing balance across six dimensions: ease of use, performance, extensibility, orchestration, observability, and safety.

              Hexagon AI Agent Framework Architecture
              ========================================

  ┌─ Application Layer ────────────────────────────────────────┐
  │  ChatBot    RAG Agent    Workflow    Multi-Agent    Custom  │
  ├─ Orchestration Layer ──────────────────────────────────────┤
  │  Router   Planner   Scheduler   Executor   Graph   State   │
  ├─ Agent Core Layer ─────────────────────────────────────────┤
  │  Agent   Role   Team   Network   Handoff   Context   Msg   │
  ├─ Capability Layer ─────────────────────────────────────────┤
  │  LLM Provider    RAG Engine    Tool System    Memory    KB │
  │  (ai-core)                     (ai-core)      (ai-core)   │
  ├─ Infrastructure Layer ─────────────────────────────────────┤
  │  Tracer    Logger    Metrics    Config    Security   Plugin │
  ├─ Foundation Layer ─────────────────────────────────────────┤
  │  toolkit (lang | crypto | net | cache | util | collection) │
  └────────────────────────────────────────────────────────────┘

Start with three lines of code, progress to declarative configuration, and use graph orchestration for complex scenarios:

response, _ := hexagon.Chat(ctx, "What is Go?")         // 最简入门

agent := hexagon.QuickStart(                              // 带工具
    hexagon.WithTools(calculator),
    hexagon.WithSystemPrompt("你是一个数学助手"),
)

team := hexagon.NewTeam("research-team",                  // 多 Agent 团队
    hexagon.WithAgents(researcher, writer, reviewer),
    hexagon.WithMode(hexagon.TeamModeSequential),
)

Runnable[I,O]: One Interface for Everything

Python LangChain gives Agent, Tool, Chain, and Retriever different abstractions, requiring glue code to combine them. Hexagon takes a more radical approach: every component implements the same generic interface, supporting six execution paradigms (Invoke / Stream / Batch / Collect / Transform / BatchStream).

pipeline := core.Compose(tokenizer, model)    // 自由组合
adapted := core.InvokeToStream(r)              // 自动获得流式能力
fastest := core.Race(future1, future2)         // 竞速取最快

An agent can serve as another agent's tool, and a RAG pipeline can be embedded in a graph node, because they share the same interface.

Comparison with mainstream frameworks:

The core differentiator is safety. Eino has no built-in injection detection, PII redaction, RBAC, or cost control. If you build a user-facing agent with Eino, you need to build those protections yourself. Hexagon provides them as built-in framework capabilities, ready to use.

In one sentence: LangChain's interface ideas + LangGraph's orchestration + an enterprise safety stack, rewritten in Go. Perception (Agent) → Execution (Skills + MCP) → Knowledge (RAG + LLM + Memory): all three layers are built in.

Ten Agent Types and Multi-Agent Collaboration

Agent development progresses through four stages from simple to complex. Hexagon covers them with 10 agent types and collaboration protocols:

Nesting works naturally: a Supervisor's worker can be a ReActAgent, and a ReActAgent's tool can trigger a PlanExecuteAgent.

Collaboration includes Team (four modes), Handoff (Swarm-style transfers), Network (Mesh/Hub/Ring/Tree topologies), Consensus (voting), Registry (service discovery + load balancing), and A2A (Google's Agent-to-Agent protocol, uncommon in the Go ecosystem). Four-layer state management plus Snapshot/Restore.

The Graph Orchestration Engine

g, _ := graph.NewGraph[MyState]("support").
    AddNode("classify", classifyIntent).
    AddNode("faq", handleFAQ).
    AddConditionalEdge("classify", routerFn, routeMap).
    SetEntryPoint("classify").Build()

Conditional routing · parallel execution · checkpoint persistence · Human-in-the-Loop · time travel · nested subgraphs · Pregel BSP · loops and barriers. Chain composition, a workflow engine, and deterministic processes (Process, driven by state machines) are also available.

  User ──→ Agent ──→ LLM ──→ Tool ──→ Result
              │
              ├──→ Memory (memory access)
              └──→ RAG (knowledge retrieval)

RAG Pipeline: Seven Pluggable Stages

Documents → Loader → Splitter → Embedder → Indexer → Retriever → Reranker → Synthesizer

Eight vector-storage backends: Qdrant / FAISS / PgVector / Redis / Milvus / Chroma / Pinecone / Weaviate.

Safety and Observability

The hook system covers five event categories: Run / Tool / LLM / Retriever / Stream. Bitmask optimization avoids empty calls. Hexclaw's budget control, tool approvals, and automatic memory extraction all use hooks without intruding into the framework core.

Performance and More Capabilities

Also included: OS-level sandboxing · reactive stream-processing engine · seven memory implementations · MCP client and server · Agentic Document Workflows (ADW) · deterministic processes (Process).

The application orchestrates; the framework implements. Hexclaw does not implement agent reasoning: it assembles Hexagon's. It does not write safety checks: it orchestrates the Guard Chain. It does not write RAG: it configures the RAG Engine.

hexclaw: Hexagon Is the Engine, HexClaw Is the Whole Vehicle

[Diagram: HexClaw's six-layer application architecture]

                    HexClaw Application Architecture
                    ================================

  ┌─ Platform Adapter ─────────────────────────────────────────────────────────────────┐
  │ Web  Feishu  Telegram  DingTalk  Discord  Slack  WeCom  WeChat                     │
  │ WhatsApp  LINE  Matrix  Email  REST API  (13 types)                                │
  ├─ Security Gateway (6-Layer Pipeline) ──────────────────────────────────────────────┤
  │ Auth → RateLimit → CostCheck → InputSafety → Permission → Audit                    │
  ├─ Agent Engine ─────────────────────────────────────────────────────────────────────┤
  │ ReAct Loop        3D Budget Control     Tool Executor + Hooks                      │
  │ Session Manager   Context Compaction    Multi-Agent Router                         │
  │ Two-Pass Stream   Tool Approval Gate    Auto Memory Extract                        │
  ├─ Capability Layer ─────────────────────────────────────────────────────────────────┤
  │ Skill System       Knowledge (RAG)        LLM Router                               │
  │ (Builtin+Mkt+MCP)  (FTS5+Vector+MMR)      (Cost/Quality/Latency)                   │
  │ Memory (4-Layer)   Semantic Cache (Singleflight+LRU+TTL)                           │
  ├─ Infrastructure ───────────────────────────────────────────────────────────────────┤
  │ OS Sandbox          MCP Client          Cron + Webhook                             │
  │ (Seatbelt/NS/Win)    (stdio/SSE/HTTP)     REST API (71 endpoints)                  │
  │ Canvas (8 components)   Voice (STT/TTS)   WebSocket streaming                      │
  ├─ Storage & Config ─────────────────────────────────────────────────────────────────┤
  │ SQLite (WAL)   FTS5 full-text search   YAML+ENV   Audit JSONL   .md                │
  └────────────────────────────────────────────────────────────────────────────────────┘
            Powered by: Hexagon ← ai-core ← toolkit

Core Data Flow

User message (Feishu/Telegram/Discord/WeChat/...)
  → Platform adapter (Adapter) → Security gateway (6 layers) → Session routing (Router)
  → Agent engine (ReAct)
      ├─ Fast path: Skill.Match() → milliseconds, zero LLM usage
      └─ Main path: ReAct loop → sandbox execution → synchronous/streamed response

The Six-Layer Security Gateway

Request → [Auth] → [RateLimit] → [CostCheck] → [InputSafety] → [Permission] → [Audit] → Engine

Layers three and four reject requests directly on failure. Better to show “Service temporarily unavailable” than let an uncontrolled ReAct loop drain the API balance.

Thirteen Platform Adapters

A unified message model and a four-method Adapter interface, with each adapter around 150 lines.

Platform-specific implementations worth examining: - WeCom: AES-256-CBC encryption/decryption and a double-checked locking token cache - WeChat: a five-second passive reply window, automatically switching to asynchronous customer-service delivery on timeout - Discord: Gateway WebSocket heartbeats and streaming message edits - Web: an Origin allowlist permitting only localhost and tauri://localhost

The ReAct Engine

The engine adds application-level orchestration on top of Hexagon ReActAgent (a single 47 KB file):

LoadContext → InjectContext(RAG+Memory) → InjectTools(Skill+MCP, max 40)
→ ReAct loop: LLM reasoning → ToolApproval → ToolExecutor → BudgetUpdate
→ AutoMemory → SaveHistory → Return

Three-Dimensional Atomic Budgets: three atomic.Int64 values track tokens, duration, and cost separately. Why not float64 for cost? Go's atomic package has no floating-point atomic operations, while agent tools are called concurrently. The solution multiplies dollar amounts by one million and stores integers at microdollar precision: $0.00004 becomes 40. Integer atomic operations require no locks. Built-in pricing tables cover more than 20 models, with child-agent budget allocation and reclamation.

Two-Pass Streaming: intermediate rounds use Complete() to detect tool_calls; the final round uses Stream() for the typewriter effect. This avoids opening streaming connections for invisible steps. Streaming goroutines use an independent context.Background() to save messages so closing the page does not lose data.

Hook Chain: TruncateHook retains 60% of the beginning and 20% of the end; SanitizeHook cleans only external sources; AuditHook runs even on failure. Tool caching uses SHA256 keys and automatically skips destructive tools.

The Skill Ecosystem (ClawHub): 37 Skills and 38 MCP servers, in Markdown with YAML frontmatter. Sources include 18 original skills, 12 community adaptations, and seven OpenClaw playbook ports. MCP spans 18 categories, including filesystems, GitHub, search, browsers, databases, Slack, Docker, Kubernetes, and AWS.

Native Go Sandbox on Three Platforms: 2,713 Lines Instead of Docker

Most competitors, including OpenClaw, rely on Docker for code execution. HexClaw implements kernel-level isolation with 2,713 lines of pure Go :

macOS Seatbelt (the same underlying facility as Claude Code / Codex): dynamic SBPL policies, with (deny default) denying by default. Docker containers, which allow most syscalls by default, do not provide this behavior.

Five-Layer Defense on Windows: ① Restricted Token (UNTRUSTED_RID 0x0000) → ② ACL filesystem isolation → ③ Job Object (512 MB / 10 processes) → ④ Low Box Token for kernel-level network denial → ⑤ Alternate Desktop to prevent Shatter Attacks. Startup is about 50 ms / 5 MB, compared with Docker Desktop's 500 ms–2 s.

Five-Layer Isolation on Linux: ① Namespace → ② pivot_root → ③ seccomp → ④ process hardening → ⑤ two-stage re-exec. Incompatible systems fall back automatically: CLONE_NEWUSER failure → Landlock → fallback seccomp.

All three platforms share the NetPolicy engine: denylist first → port → mode, with no bypass.

Measured sandbox comparison (Linux):

Knowledge Base, LLM Routing, and Memory

Knowledge base: Recursive Split → FTS5 + vector embeddings → hybrid scoring (0.7v + 0.3t) → time decay → MMR deduplication (filter from 3×TopK candidates) → TopK=3. Automatically degrades to pure FTS5 when the embedder is unavailable.

LLM routing: policy-based routing across providers (cost / quality / latency), with automatic fallback on failure. Semantic caching uses Singleflight against stampedes, ±10% TTL jitter against synchronized expiry, and negative caching against cache penetration.

Four-layer memory: conversation context → daily journal → MEMORY.md → semantic vectors. Automatic extraction: keyword prefilter → asynchronous LLM (15-second timeout) → existing memories injected to prevent duplicates. More than 50 entries trigger automatic LLM compression. Markdown is human-readable and can be versioned in Git.

Multi-Agent Routing and Autonomous Behavior

Four selection mechanisms: direct UI selection · @mention syntax · automatic mode binding · platform routing rules (UserID +100 > ChatID +50 > Platform +10), with LLM semantic classification as fallback.

Meeting mode: two or more agents conduct a multi-round roundtable around a structured topic, suitable for competitor analysis, brainstorming, and expert debate.

Autonomous behavior: Heartbeat inspections + Cron schedules + webhook events. SQLite WAL by default, with four deployment options: desktop / Docker / systemd / Kubernetes.

hexclaw-desktop: Making an AI Agent as Easy to Launch as Docker Desktop

A Tauri Shell Managing a Go Sidecar

[Diagram: HexClaw Desktop layered architecture]

                  HexClaw Desktop Architecture
                  ============================

  ┌─ Tauri Shell (Rust) ───────────────────────────────────────────────────────────────┐
  │ Window management   Tray   Global shortcut ⌘⇧H   Single instance   Auto-updates    │
  │ API proxy (CORS bypass)          Sidecar process lifecycle management              │
  ├─ Vue 3 Frontend (WebView) ─────────────────────────────────────────────────────────┤
  │ Overview | Chat | Agent | Knowledge | Automation | Integrations | Logs             │
  │ Pinia Store       Vue Router       Tauri invoke (IPC)                              │
  ├─ Tauri Commands (Rust → Go) ───────────────────────────────────────────────────────┤
  │ proxy_api_request    stream_chat    check_engine_health                            │
  │ HTTP / WebSocket ←→ localhost:16060                                                │
  ├─ hexclaw serve (Go Sidecar) ───────────────────────────────────────────────────────┤
  │ Agent engine · Security gateway · LLM routing · RAG · MCP · Sandbox                │
  │ Hexagon ← ai-core ← toolkit                                                        │
  └────────────────────────────────────────────────────────────────────────────────────┘

Framework selection:

Package size: 8 MB versus Electron's 150 MB (19x); memory: 25 MB versus 200 MB (8x).

Feature Modules

Native Capabilities

⌘⇧H global activation · system tray · native notifications · clipboard interaction · drag-and-drop file uploads · three-step onboarding · Tauri Updater. The same codebase supports Desktop and Headless. Installation: curl | bash / Homebrew / DMG / MSI / DEB / AppImage.

Where Does It Stand Against Competitors?

Since late 2025, vendors have been rapidly releasing AI agent products, mostly closed-source, cloud-hosted, and aimed at enterprises. HexClaw takes a different path: open source, self-hosted, for developers and technical teams. The table compares categories:

Mistakes and Architectural Trade-Offs

Mistake 1: Docker Sandboxing — “I Need Docker Just to Install a Chat Assistant?”

Early Skill execution depended on Docker. Typical MacBook configurations worked fine, but Docker Desktop consumed another 2–4 GB of memory on macOS. Making a user install Docker for a weather query was unreasonable.

Rewriting native sandboxes for three platforms using Go syscalls took one week: 2,713 lines, zero dependencies, and <10 ms startup. Isolation is weaker than a full container, but sufficient for Skill execution scenarios.

Mistake 2: Wails → Tauri — Recovering from a Bad Framework Choice

The desktop client initially used Wails, for solid reasons: native Go, zero integration cost. At 60% completion, three critical limitations emerged: no multi-window support (so no Quick Chat floating window), a third-party dependency for the system tray, and no automatic updater.

I cut the losses and switched to Tauri v2. The Go backend became a sidecar, adding an HTTP layer, but it reused the existing 71 APIs and actually reduced development cost.

Mistake 3: The Security Gateway Started as an “Optional Setting”

The first safety layer was middleware, disabled by setting enabled: false in the configuration. During a code review, we found that disabling CostCheck let an uncontrolled ReAct loop call the LLM indefinitely until the bill exploded: a deterministic disaster, not a theoretical risk.

That day it was refactored into a six-layer pipeline with no bypass. Rate limits are frequently triggered during development, but that beats an API bill arriving in the middle of the night.

Trade-off summary:

What Comes Next

In 2026, AI agents are moving from proof of concept to engineered deployment. The MCP + A2A protocol stack is maturing, and safety and determinism are replacing the “a working demo is enough” mindset. HexClaw is currently on v0.2.x: the core is stable, but important gaps remain before it is production-grade:

• Streaming upgrade: currently simulated streaming (synchronous intermediate rounds); planned integration with Hexagon Agent's native Stream
• Embedding integration: the knowledge-base Embedder interface is defined and needs connecting to an LLM provider
• Test coverage > 80%: 93 test files, with coverage still needing improvement
• Hub ecosystem expansion: 37 Skills → 100+, 38 MCP servers → 80+, adding code review, data analysis, and project management
• Cross-platform desktop refinement: Mac first; Windows MSI and Linux AppImage need more testing

An open question: how can agents become more autonomous without sacrificing safety? Tool Approval protects safety but limits autonomy. We are exploring adaptive approval policies based on past behavior. This is a central tension for AI agents in 2026: on the path from a working demo to production trust, where is the balance between safety and autonomy?

Technology Stack

This project was developed by one person paired with Claude. The original goal was simple: an AI agent for myself that was safe, useful, and affordable. If you want the same thing, search GitHub for hexclaw and join in with issues or pull requests.

One final question: what bothers you most when using an AI agent: safety and trust, cost control, or platform support? Tell us in the comments. Those real pain points directly affect HexClaw's priorities.

HexClaw
Deploy locally or in the cloud · Control your data · Free and open-source software
Website: hexclaw.net  |  GitHub: hexagon-codes
Weibo: @HexClaw  |  X: @hexclawapp
Email: [email protected]