HiClaw Worker Agent

HiClaw Workers are lightweight, stateless task executors that can be dynamically created and destroyed by the Manager Agent. Each worker runs in its own Docker container with minimal privileges.

Overview

Key characteristics of HiClaw Worker Agents:

Lightweight — Minimal container based on the openclaw-base image
Stateless — All persistent data lives in MinIO; workers can be recreated without data loss
Dynamic skills — Skills are pushed from the Manager at creation time
Consumer tokens only — Workers never hold real API keys (see Security)
Matrix-native — Communicate through dedicated Matrix rooms

Worker Creation Process

When you tell the HiClaw Manager to create a worker, the following steps occur:

A new Docker container is launched from the worker image
The worker-entrypoint.sh script initializes the environment
The Manager registers a consumer token in the Higress Gateway
A Matrix account and room are created on the Tuwunel server
Relevant skills are pushed to the worker based on its role
The human admin is invited to the worker's shared room

Worker container structure: worker/Dockerfile builds on openclaw-base and includes the worker agent config, file-sync skill, and the entrypoint script.

Worker Skills (5 Default)

HiClaw Workers receive these skills by default, pushed from the Manager at creation time:

github-operations

Manage GitHub pull requests and issues. Create PRs, review code, comment on issues — all through the secure gateway.

git-delegation

Request git operations (clone, commit, push) from the Manager, which executes them with proper credentials.

coding-cli

Request AI coding CLI execution (Gemini CLI, Claude Code, Qoder) from the Manager for complex coding tasks.

find-skills

Browse and discover additional skills from the skills.sh ecosystem with 80,000+ available capabilities.

file-sync

Real-time workspace synchronization with MinIO. Push work products and pull shared resources automatically.

File Synchronization

HiClaw Workers are stateless — their workspace is synchronized with MinIO centralized storage:

On startup: Worker pulls its workspace from MinIO via mc mirror
During work: Changes are periodically synced back to MinIO
On completion: Final work products are pushed to the shared storage
Host path: ~/hiclaw-fs/ on the host machine maps to MinIO

This design means workers can be safely destroyed and recreated without losing data. Learn more in the HiClaw Architecture documentation.

Worker Security Model

HiClaw Workers operate with minimal privileges by design:

Aspect	Worker Access
LLM API Keys	Consumer bearer token only — real keys in Higress
GitHub PAT	Routed through gateway — worker never sees the token
MCP Servers	Permission-controlled access via gateway
Git Operations	Delegated to Manager — worker requests, Manager executes
File System	MinIO workspace only — no host filesystem access

For a complete security analysis, see the HiClaw Security Model.

Troubleshooting

Worker Not Responding

The Manager's heartbeat should detect this automatically. If not, you can manually ask the Manager:

Check the status of worker alice

Worker Stuck on a Task

Intervene directly in the worker's room:

alice, stop current task and report your status

Reset a Worker

Ask the Manager to reset the worker's state:

Reset worker alice

For more troubleshooting tips, see the HiClaw FAQ.