HiClaw — Workflow

Deployment Phase

1. Install with curl | bash (Docker Compose) or helm install (Kubernetes)
2. All infrastructure containers start: Tuwunel, Element Web, Higress AI Gateway, MinIO, HiClaw controller
3. Human accesses Element Web at http://127.0.0.1:18088

Configuration Phase

1. Human writes YAML manifests declaring Worker, Team, and Human Kubernetes resources
2. hiclaw apply -f team.yaml — controller reconciles desired state
3. Controller creates Worker containers with assigned runtime (OpenClaw / QwenPaw / Hermes)
4. Controller configures Higress gateway with LLM provider credentials (workers never see raw keys)
5. Controller creates Matrix room(s) in Tuwunel, invites all participants

Execution Phase

1. Human sends task message to Matrix room via Element Web
2. Manager agent receives the message (connected to the room via Tuwunel)
3. Manager decomposes task and assigns subtasks to Workers (Matrix messages)
4. Each Worker receives its subtask via Matrix room message
5. Worker calls LLM through Higress AI Gateway (consumer token, not raw API key)
6. Workers pull skills from skills.sh on demand as needed
7. Workers exchange files through MinIO shared object storage
8. Workers post results back to Matrix room
9. Manager aggregates results and synthesizes final output
10. Human monitors all messages in real time; can intervene at any point

Human Intervention

• Human sees every message in the Matrix room (full visibility by design)
• Human can send correction messages at any time; Manager re-routes
• Human can modify YAML resources (add/remove Workers) mid-execution
• hiclaw CLI can be used to scale or restart workers

Lifecycle Management

File Exchange Pattern

Workers write outputs to MinIO; downstream workers read from MinIO. Matrix messages carry MinIO object references (URLs or keys) rather than raw file content, keeping Matrix messages lightweight.

HiClaw — Memory & Context

Shared File System (MinIO)

MinIO is the primary inter-agent memory store. Workers write intermediate artifacts (files, structured data) to MinIO buckets. Downstream Workers read from those buckets. This gives durable, cross-container shared memory without coupling Workers to each other directly.

• All Workers have the same MinIO endpoint and credentials
• Objects are addressable by key; Workers pass keys via Matrix messages
• Persists across Worker restarts (durable storage)

Matrix Room History (Tuwunel)

Every Matrix room maintained by Tuwunel stores a full message history. Workers and the Manager can scroll back through room history to recover context on task progress. Humans can also review room history.

• Room history is the implicit conversation log
• Workers joining mid-task can read prior messages to onboard
• No explicit summarization step; full history is always accessible

Kubernetes Resource State (etcd)

The HiClaw controller stores declarative state (Worker, Team, Human resource specs) in Kubernetes etcd. This is configuration state, not runtime memory — it records what should exist, not what agents said.

No Vector Store

HiClaw does not include a vector database or semantic search layer. Memory is flat: Matrix message history (time-ordered) + MinIO object storage (key-addressable). There is no RAG pipeline or embedding-based retrieval.

Context Window Management

Each Worker manages its own LLM context. When a Worker calls the LLM via Higress:

• The Worker constructs its own prompt from Matrix room messages + MinIO content
• The HiClaw platform does not manage context compression or summarization
• Workers running Hermes or OpenClaw may have their own internal context handling

Skills as Dynamic Context

Workers pull skills from skills.sh at runtime. A fetched skill injects additional text into the Worker's active context. This is the primary mechanism for extending Worker capability without modifying container images.

Cross-Session Continuity

• MinIO objects persist between sessions (unless explicitly deleted)
• Matrix room history persists in Tuwunel
• Kubernetes resource state persists in etcd
• Workers restart with fresh LLM context windows; they recover prior context by re-reading Matrix room history and MinIO

HiClaw — Orchestration

Manager-Workers Architecture

HiClaw uses a strict two-tier hierarchy:

Human
  └── Manager (1)
        ├── Worker A (OpenClaw)
        ├── Worker B (QwenPaw)
        └── Worker C (Hermes)

The Manager is itself a Worker container running a specific runtime (OpenClaw preferred for determinism). The Manager's role is to decompose tasks and delegate subtasks to Workers.

Communication via Matrix Protocol

All orchestration happens through Matrix room messages (Tuwunel server). This is the defining pattern: the orchestration bus is a real IM protocol, not an in-process message queue or API call.

• Manager sends subtask messages to Workers in the shared room
• Workers post results back to the same room
• Manager reads results and synthesizes the final response
• Human observes every message; can inject corrections at any point

Kubernetes Controller (hiclaw-controller)

The Go controller manages the lifecycle of Worker, Team, and Human resources:

• Reconciler loop: continuously ensures desired state (YAML spec) matches actual state (running containers)
• Worker creation: spawns Worker containers with correct runtime image and config
• Team management: groups Workers for scoped task routing
• Human registration: creates Matrix room invites for human participants

Controller uses controller-runtime (same pattern as Kubernetes operators).

Higress AI Gateway as Orchestration Boundary

The Higress gateway enforces credential isolation. Each Worker has a consumer token scoped to specific LLM models. The gateway:

• Routes Worker LLM calls to the correct provider
• Enforces rate limits and quotas per Worker
• Hides real API keys (enterprise security boundary)

Workers cannot directly call LLM APIs — all LLM traffic flows through Higress.

Multi-Runtime Collaboration

A single Team can mix runtimes:

• OpenClaw Worker for deterministic reasoning tasks
• QwenPaw Worker for tasks that benefit from Qwen's strengths
• Hermes Worker for autonomous coding tasks

The Manager decides which Worker to route each subtask to based on capability.

Concurrency Model

• Workers run as separate containers (parallel by default)
• Matrix room messages are async; Workers can work concurrently
• Manager waits for Worker responses before synthesizing
• No explicit barrier/checkpoint primitives; Manager implements its own sequencing via message logic

Skills Registry

Workers can dynamically pull capabilities from skills.sh (80,000+ community skills). Skills expand what a Worker can do without requiring a new container image or controller restart. The Manager can instruct a Worker to fetch a specific skill before executing a subtask.

HiClaw — UI & CLI Surface

Element Web (Matrix Client) — Primary Human Interface

• URL: http://127.0.0.1:18088
• Technology: Element Web (standard Matrix web client)
• Protocol: Matrix protocol via Tuwunel self-hosted server

Element Web is the human-agent interaction surface. The human joins the same Matrix room as the Manager and Workers. Every agent message appears as a chat message. Human participation is first-class — not an observer panel or separate dashboard but a full participant in the shared room.

Features available through Element Web:

• Real-time message stream from all agents + human
• Full room history scrollback
• Human can type and send messages at any time (interventions, corrections, new tasks)
• File sharing via Matrix file attachment (alongside MinIO for inter-agent files)
• Standard Matrix features: reactions, threads, read receipts

This is the most distinctive UI pattern in the batch: the human-agent UI is a real Matrix IM client, not a custom-built web dashboard.

hiclaw CLI — Cluster Lifecycle Management

The hiclaw binary is a Go CLI for managing the Kubernetes control plane:

The CLI is infrastructure-facing (kubectl-like), not task-facing. Users don't interact with agent tasks through the CLI — that happens in Element Web.

Install Script

curl -fsSL https://install.hiclaw.io | bash

One-liner that deploys: Tuwunel, Element Web, Higress AI Gateway, MinIO, HiClaw controller. Docker Compose variant for local; Helm chart for production Kubernetes.

No Custom Dashboard

HiClaw deliberately reuses Element Web as its UI rather than building a custom dashboard. There is no separate monitoring panel, no workflow visualization, no progress bars. All visibility into agent activity is through the Matrix room message stream.

Comparison to Batch Peers

HiClaw is the only framework in this batch that uses a pre-existing IM client (Element Web) as its primary UI rather than a custom-built web or desktop app. This is architecturally significant: the UI is decoupled from the platform — any Matrix client can be used to interact with HiClaw agents.