HiClaw System Architecture

HiClaw is an all-in-one system that bundles an AI Gateway, Matrix messaging server, object storage, and an agent framework into a single deployable unit. This page explains how every component fits together.

Architecture Overview

The HiClaw architecture follows a layered design where a human interacts through an IM client, and the Manager Agent orchestrates Worker Agents behind a unified gateway.

Human (Browser / Mobile)
    |  (Element Web / Any Matrix Client)
    v
Higress AI Gateway (port 18080)
├── Tuwunel Matrix Server  (6167)
├── MinIO Object Storage   (9000)
├── Element Web            (8088)
└── LLM + MCP Server Routing

Manager Agent (OpenClaw)
├── Creates Workers
├── Manages Tasks
└── Monitors Health

Worker Agents (OpenClaw)
├── Pull config from MinIO
├── Communicate via Matrix
└── Execute tasks

Higress AI Gateway

The Higress all-in-one gateway is the single entry point for all HiClaw traffic. It handles:

• LLM Proxy — Routes requests to configured LLM providers (Alibaba Cloud Bailian, OpenAI-compatible, Qwen)
• MCP Server Hosting — Hosts and exposes MCP tool servers with permission control
• Consumer Authentication — Issues bearer tokens so Workers never touch real credentials
• Route Management — Dynamically adds routes for new workers and services

This design is central to the HiClaw security model — all sensitive credentials live inside the gateway, never in worker containers.

Tuwunel Matrix Server

HiClaw uses Tuwunel (a conduwuit fork) as its Matrix homeserver. Matrix provides:

• E2E encrypted messaging between humans and agents
• Room-based organization — each Worker gets a dedicated room; shared rooms for projects
• Federation-ready — can optionally connect to the wider Matrix network
• Client flexibility — Element Web (bundled), FluffyChat, Element Mobile, or any Matrix client

The Manager and Workers communicate exclusively through Matrix rooms, ensuring full transparency. Every message is visible to the human admin.

MinIO File Storage

HiClaw uses MinIO as a centralized HTTP file system for agent workspaces:

• Host path: ~/hiclaw-fs/ — synced to MinIO automatically
• Sync mechanism: mc mirror for real-time bidirectional sync
• Stateless Workers: Workers pull their workspace from MinIO on startup and push results back
• Contents: Agent configs, task specs, shared knowledge, and work products

OpenClaw Agent Framework

Both the Manager and Worker agents run on OpenClaw, a fork of an open-source agent framework enhanced with:

• Matrix plugin — native Matrix protocol integration
• Skills system — modular capabilities that can be pushed to agents at runtime
• Heartbeat mechanism — periodic health checks to detect stuck agents
• MCP tool access — via the mcporter CLI for calling MCP Server tools

Complete Tech Stack