HiClaw Security Model

Security is not an afterthought in HiClaw — it's a foundational design principle. Every Worker operates with minimal privileges, all credentials are centrally managed, and the human admin maintains full visibility and control.

Security Principles

Least Privilege

Workers only receive the minimum access needed. Consumer tokens replace real API keys.

Centralized Credentials

All sensitive secrets live in the Higress Gateway, never in agent containers.

Full Transparency

Every agent action is visible in Matrix rooms. The human admin can audit everything in real-time.

Defense in Depth

Multiple layers: token isolation, MCP permissions, gateway routing, and container sandboxing.

Credential Isolation

The core of HiClaw's security model is strict credential isolation between the Manager, Workers, and external services:

Credential Type	Stored In	Worker Access
LLM API Keys (OpenAI, Bailian, etc.)	Higress Gateway	Consumer bearer token
GitHub Personal Access Token	Higress Gateway	Proxied through gateway
MCP Server Credentials	Higress Gateway	Permission-gated access
Matrix Admin Token	Manager only	No access
MinIO Access Keys	Manager only	Read/write via file-sync skill

Key security guarantee: Even if a Worker container is compromised, the attacker only obtains a consumer bearer token — not your actual LLM API keys, GitHub tokens, or other sensitive credentials.

Consumer Token System

When the HiClaw Manager creates a new Worker, it registers a consumer in the Higress Gateway:

Manager calls the higress-gateway-management skill to create a consumer
Higress issues a unique bearer token for the consumer
The token is passed to the Worker container as an environment variable
The Worker uses this token for all LLM and MCP requests
Higress maps the consumer token to the real API keys internally

This means the Worker can make LLM calls and access tools without ever knowing the actual credentials. The Manager can revoke a consumer token at any time to immediately cut off a Worker's access.

MCP Server Permissions

HiClaw implements granular permission control for MCP (Model Context Protocol) Server access:

The Manager controls which MCP Servers each Worker can access via the mcp-server-management skill
Workers request MCP tool access through the gateway, which enforces permissions
Permissions can be granted or revoked at runtime without restarting Workers
All MCP tool calls are logged and visible in the Matrix room

Permission Flow

Worker calls MCP tool
    → Request hits Higress Gateway
    → Gateway checks consumer permissions
    → If allowed: forwards to MCP Server
    → If denied: returns permission error
    → Result returned to Worker

Communication Security

All inter-agent communication in HiClaw flows through the Matrix protocol:

Tuwunel server handles message routing within the HiClaw instance
Room-based isolation — each Worker has its own room; shared rooms are explicit
Human visibility — the admin is invited to all relevant rooms by default
Audit trail — all messages are persisted in the Matrix server's database

Security Best Practices

Review worker actions — Monitor shared rooms regularly, especially for tasks involving external services
Limit MCP access — Only grant Workers access to MCP Servers they actually need
Rotate consumer tokens — Periodically reset Workers to refresh their tokens
Use the heartbeat — The Manager's heartbeat detects stuck or misbehaving Workers early
Audit the Manager room — All Manager actions (worker creation, gateway changes) are logged here