HiClaw FAQ

HiClaw is an open-source AI Agent Teams system that lets multiple AI agents collaborate through instant messaging (Matrix protocol) with built-in human oversight. It follows a Manager-Worker architecture where a Manager Agent orchestrates Worker Agents, and humans stay in control by communicating naturally in shared chat rooms.

Yes. HiClaw is released under the Apache License 2.0, which means you can use, modify, and distribute it freely — including for commercial purposes. The full source code is available on GitHub.

Three key differentiators:

• IM-native: All agent communication happens in Matrix chat rooms, not hidden behind APIs
• Security by design: Workers never hold real credentials — consumer tokens and gateway isolation protect your secrets
• One-command deploy: A single command installs the full stack (Gateway, Matrix, MinIO, Element Web, Manager Agent)

HiClaw supports Alibaba Cloud Bailian (default), OpenAI-compatible providers (DeepSeek, Claude, etc.), and Qwen models. You can switch providers at runtime using the Manager's model-switch skill. See the features page for details.

Minimum requirements:

• Docker Desktop or Docker Engine installed and running
• 2 CPU cores and 4 GB RAM
• macOS, Linux, or Windows (PowerShell 7+)
• AMD64 or ARM64 architecture

See the Quick Start guide for detailed installation steps.

Startup timeout is usually caused by:

• Slow image pull: The first run downloads ~2GB of Docker images. Wait for it to complete.
• Insufficient resources: Ensure Docker has at least 4 GB RAM allocated.
• Port conflicts: Check that port 18080 is not already in use.
• Docker not running: Make sure Docker Desktop is started before running the install command.

Yes. By default HiClaw binds to 0.0.0.0:18080, so other devices on your network can access it via http://YOUR_IP:18080. For production deployments, consider putting HiClaw behind a reverse proxy with TLS.

Run make uninstall from the HiClaw repository, or manually stop and remove the Docker containers. Your data in ~/hiclaw-fs/ and ~/hiclaw-manager/ will be preserved unless you delete them.

There's no hard limit in HiClaw itself. The practical limit depends on your system resources (CPU, RAM) and your LLM provider's rate limits. Each Worker is a lightweight Docker container, so modern machines can easily run 5-10+ workers.

Steps to diagnose:

1. Ask the Manager: Check the status of worker [name]
2. Check if the Worker container is running: docker ps
3. Check Worker logs: docker logs hiclaw-worker-[name]
4. If stuck, ask the Manager to reset it: Reset worker [name]

The Manager's heartbeat mechanism should detect unresponsive workers automatically.

Workers don't communicate directly. All coordination goes through the Manager Agent using the task-coordination and project-management skills. For collaborative projects, the Manager creates shared rooms where relevant Workers and the human admin can all see the conversation.

Tell the Manager in its room: Switch model to [provider/model]. The Manager uses the model-switch skill to reconfigure the Higress Gateway routing without any restart required.

Yes. The Higress Gateway routes each consumer token to a specific LLM provider. The Manager can configure different routes for different Workers using the higress-gateway-management skill.

Yes. Your real API keys (LLM, GitHub, etc.) are stored exclusively in the Higress Gateway, which runs inside the Manager container. Workers only receive consumer bearer tokens — they never see your actual credentials. See the full security model for details.

The blast radius is minimal. A compromised Worker only exposes its consumer token — not your real API keys. The Manager can immediately revoke the consumer token, cutting off all access. Workers are stateless, so destroying and recreating one costs nothing. Read more about the HiClaw security model.

Yes. HiClaw's skill system is modular. You can create custom skills by adding a skill directory in manager/agent/skills/ or manager/agent/worker-skills/. Additionally, Workers can discover and install skills from the skills.sh ecosystem with 80,000+ available capabilities. See HiClaw Features.

HiClaw welcomes contributions! The project uses a standard GitHub workflow: fork the repo, make your changes, and submit a pull request. Run make test to execute the integration test suite (13 test cases) before submitting. See the development documentation for details.

Yes. HiClaw uses GitHub Actions for CI/CD with workflows for building base images, Manager/Worker images, and running the test suite. You can use the replay-task.sh script to send tasks to the Manager from your CI pipeline.