HiClaw 完整部署教程:5分钟搭建你的 AI 开发团队(Team 版 OpenClaw)

导语:你用过 OpenClaw 的单 Agent 模式?HiClaw 就是它的团队升级版——Manager 负责派活,Worker 负责干活,你只需要给需求。本文从架构原理到全平台部署,手把手带你搭建一套开箱即用的 AI 多智能体协作系统。

目录


一、HiClaw 是什么?

1.1 一句话定义

HiClaw = Team 版 OpenClaw

如果说 OpenClaw 是一名"万能员工",那 HiClaw 就是一个"分工明确的开发团队"——有人管项目、有人写代码、有人跑测试,你只需要做决策。

1.2 为什么需要 HiClaw?

用过 OpenClaw 的同学可能有这些感受:

痛点 表现
单 Agent 上下文膨胀 任务越来越长,Token 消耗爆炸
无法并行工作 写代码和跑测试只能串行
凭证安全隐患 API Key 直接暴露给 Agent,有泄漏风险
配置门槛高 从安装到用起来可能要半天,某鱼甚至有付费安装服务

HiClaw 一次性解决了上面所有问题。

1.3 核心技术栈

HiClaw 是一个开源的协作式多智能体运行平台。让多个 Agent 在一个受控、可审计的房间中协作,人类全程可见、随时可介入。 采用 Manager-Workers 架构,Manager 统一调度多个 Workers,专注于企业内的人和 Agent、Agents 之间的协作场景。

HiClaw 并不和其他 xxClaw 对标,自己不实现 Agent 逻辑,而是编排和管理多个 Agent 容器(Manager 和众多 Workers)。

🧑‍💻 设计了 Manger-Workers 架构:不用真人去管理每个干活的 Worker Claw,实现由 Agent 管理 Agents。
🦞 每个 Agent 支持自定义:OpenClaw、Copaw、NanoClaw、ZeroClaw 以及企业自建的 Agent,从养虾到开虾场,提供 worker 和 Team 模板市场。
📚 引入 MinIO 共享文件系统:用于 Agent 之间的信息共享,大幅降低多 Agent 协作带来的 Token 消耗。
⛑️ 引入 Higress AI Gateway:流量入口和各类凭证风险降低了,减少了用户对原生龙虾在安全上的顾虑。
🎨 使用 Element IM 客户端+Tuwunel IM 服务器(均基于 Matrix 实时通信协议):节省钉钉、飞书 IM 的接入和企业内的审批成本,方便用户快速体验在 IM 的交互环境中体验模型服务的"爽感",同时支持以 OpenClaw 原生的方式接入 IM。
在这里插入图片描述


二、架构深度解析

理解架构是高效使用和排查问题的前提,花 3 分钟值得。

2.1 Manager + Worker 团队模型

用户
  │
  ▼ 自然语言指令
┌─────────────────────────────────┐
│         Manager Agent           │
│   (项目管理 + 任务调度 + 监控)    │
└─────────────────────────────────┘
         │            │
         ▼            ▼
  ┌────────────┐  ┌────────────┐
  │  Worker A  │  │  Worker B  │  ...更多 Worker
  │ (前端开发)  │  │ (后端开发)  │
  └────────────┘  └────────────┘
         │            │
         └─────┬──────┘
               ▼
     Matrix 群聊(共享上下文)
               │
               ▼
       MinIO(共享文件系统)

Manager 核心职责

  • 接收用户需求,自动拆解为子任务
  • 创建并管理 Worker 生命周期
  • Heartbeat 监控:定期检查 Worker 状态,卡顿自动告警
  • 防惊群设计:只有被 @ 的 Worker 才触发 LLM 调用,节省 Token

Worker 核心职责

  • 专注执行具体任务(代码/测试/文档/部署…)
  • 通过 Higress 网关调用外部服务,不持有真实 API Key
  • 在 Matrix 群聊中接收任务、上报进度

2.2 Higress AI 网关:安全的关键

这是 HiClaw 相比普通 OpenClaw 最重要的安全升级:

传统 OpenClaw:
用户 API Key → 直接写入 Agent 配置 → 存在泄漏风险

HiClaw:
用户 API Key → 统一存储在 Higress 网关
                        │
                        ▼
Worker 持有"消费令牌" → 通过网关代理调用 LLM
(消费令牌有时效、有权限限制、不暴露真实 Key)

即便 Worker 被攻击,攻击者拿到的也只是消费令牌,无法获取真实 API Key。

2.3 Matrix 群聊协作机制

HiClaw 用 Matrix 协议(而不是专有 IM)实现多 Agent 协作:

  • 所有 Worker 和 Manager 在同一 Matrix 房间,信息自动同步
  • @ 机制:只有被提及的 Worker 才会被激活,避免无效 LLM 调用
  • 多端兼容:Element Web、FluffyChat 等客户端均可访问
  • 自建服务:无需依赖第三方 IM 平台,数据完全自主可控

三、环境准备

3.1 硬件要求

配置 最低 推荐(多 Worker 场景)
CPU 2 核 4 核+
内存 4 GB 8 GB+(OpenClaw 运行时内存较高)
磁盘 20 GB 50 GB+(存储 Docker 镜像 + MinIO 数据)
网络 可访问 Docker Hub 同左

3.2 软件依赖

工具 版本要求 说明
Docker Desktop / Docker Engine 最新稳定版 所有服务都跑在容器里
PowerShell 7.5+ (Windows) 运行安装脚本
WSL 2 2.6+ (Windows) Windows 下 Docker 底层依赖

⚠️ 重要提醒:官方镜像不支持虚拟机(ECS/云桌面)上的 Windows 系统。如果在虚拟机中部署,请使用 Linux(推荐带图形界面的 Ubuntu)。

3.3 API Key 准备

HiClaw 支持任何 OpenAPI 协议兼容的大模型,不支持 Anthropic 协议

推荐选项:

提供商 推荐模型 获取地址 适用场景
阿里云百炼 qwen3.5-plus(CodingPlan) bailian.aliyun.com 首选,快速安装模式默认支持
DeepSeek deepseek-chat platform.deepseek.com 性价比极高,兼容 OpenAPI
OpenAI gpt-4o platform.openai.com 最强代码能力
本地模型 Ollama + qwen2.5 ollama.ai 完全内网,无 Token 费用

四、安装方式一:交互式脚本(推荐新手)

4.1 macOS / Linux 安装

打开终端,执行一行命令:

bash <(curl -sSL https://higress.ai/hiclaw/install.sh)

4.2 Windows 11 安装

Windows 需先确保 Docker Desktop、PowerShell 7、WSL 2 已安装。

Step 1:安装 Docker Desktop

官网下载 Docker Desktop for Windows,安装时勾选 “使用 WSL 2 而不是 Hyper-V”,安装完成后重启电脑。

Step 2:升级 WSL

不要用系统自带的 wsl --update(很慢),直接下载最新 MSI 包安装:

# 检查当前 WSL 版本
wsl --version

# 如果版本低于 2.6,手动下载并安装 wsl.2.x.x.x64.msi
# https://github.com/microsoft/WSL/releases

Step 3:安装 PowerShell 7

PowerShell 5.x 执行脚本可能有编码问题,建议升级到 PowerShell 7:

下载地址:https://github.com/PowerShell/PowerShell/releases
安装包:PowerShell-7.x.x-win-x64.msi
安装完成后,桌面搜索"PowerShell 7"打开

Step 4:运行 HiClaw 安装脚本

管理员身份打开 PowerShell 7,执行:

Set-ExecutionPolicy Bypass -Scope Process -Force; $wc=New-Object Net.WebClient; $wc.Encoding=[Text.Encoding]::UTF8; iex $wc.DownloadString('https://higress.ai/hiclaw/install.ps1')

4.3 交互式配置选项详解

脚本会依次询问以下选项,以下是推荐配置:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  HiClaw 安装向导
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[1] 语言选择
    → 选 1(中文),直接回车确认

[2] 安装模式
    → 选 1(快速开始 - 阿里云百炼)
    → 推荐所有新手,一键搞定默认配置

[3] LLM 提供商
    → 选 1(阿里云百炼)
    → 也可选 Other(填写兼容 OpenAPI 协议的自定义 Base URL)

[4] 模型接口(百炼专属)
    → 选 1(CodingPlan 接口)
    → 专为编程和 Agent 任务优化,强烈推荐

[5] 模型系列
    → 选 1(qwen3.5-plus)
    → 默认值,后续可在 Matrix 房间中动态切换

[6] API Key
    → 输入你的阿里云百炼 API Key
    → 脚本会自动测试连通性

[7] 网络访问模式
    → 选 1(Local Use Only,仅本机)
    → 如需团队共用,选 2(Allow External Access)

[8] GitHub 集成 / 技能库 / 数据持久化
    → 均直接回车(使用默认值)

[9] Worker 运行时
    → 选 1(OpenClaw):功能最全
    → 选 2(CoPaw):内存占用更低,推荐内存不足时使用

4.4 安装成功标志

安装完成后,终端会输出类似以下信息:

✅ HiClaw Manager 已启动!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  访问信息
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  主界面(Element Web):
  http://matrix-client-local.hiclaw.io:8080
  或  http://127.0.0.1:18088/#/login

  管理员账号:admin
  管理员密码:xxxxxxxxxx(请妥善保存)

  Higress 控制台:http://localhost:8001(或 18001)
  MinIO 控制台:http://localhost:9001

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📌 密码务必保存!后续可通过 Higress 控制台修改,但首次登录必须用安装时生成的密码。


五、安装方式二:源码克隆(高级用户)

适合需要自定义配置、二次开发或 CI/CD 集成的场景。

5.1 克隆仓库

git clone https://github.com/higress-group/hiclaw.git
cd hiclaw

5.2 最简安装(必须提供 API Key)

HICLAW_LLM_API_KEY="sk-你的APIKey" make install

5.3 非交互式安装(适合自动化脚本)

通过环境变量预设所有参数,实现真正的一键部署:

# 最基础配置
HICLAW_NON_INTERACTIVE=1 \
HICLAW_LLM_API_KEY="sk-xxx" \
make install

# 完整自定义配置示例
HICLAW_NON_INTERACTIVE=1 \
HICLAW_LLM_PROVIDER="qwen" \
HICLAW_DEFAULT_MODEL="qwen3.5-plus" \
HICLAW_LLM_API_KEY="sk-xxx" \
HICLAW_ADMIN_USER="myadmin" \
HICLAW_ADMIN_PASSWORD="MySecurePass123" \
HICLAW_PORT_GATEWAY=8080 \
HICLAW_PORT_CONSOLE=8001 \
HICLAW_DATA_DIR="/data/hiclaw" \
make install

5.4 完整环境变量参考

环境变量 说明 默认值
HICLAW_LLM_PROVIDER LLM 提供商 qwen
HICLAW_DEFAULT_MODEL 默认模型名 qwen3.5-plus
HICLAW_LLM_API_KEY LLM API Key (必填)
HICLAW_LLM_BASE_URL 自定义 API Base URL 由 Provider 自动推断
HICLAW_ADMIN_USER 管理员用户名 admin
HICLAW_ADMIN_PASSWORD 管理员密码 自动随机生成
HICLAW_PORT_GATEWAY AI 网关端口 8080
HICLAW_PORT_CONSOLE Higress 控制台端口 8001
HICLAW_PORT_MATRIX Matrix 服务端口 18080
HICLAW_PORT_WEB Element Web 端口 18088
HICLAW_DATA_DIR 数据持久化目录 ~/hiclaw-manager
HICLAW_VERSION 指定安装版本 最新版
HICLAW_NON_INTERACTIVE 非交互模式 0

六、安装方式三:阿里云计算巢(云端 3 分钟部署)

不想折腾本地环境?阿里云计算巢提供一键云端部署,3 分钟即可完成。

6.1 进入部署页面

访问:HiClaw 计算巢社区版

6.2 填写部署参数

参数 说明 推荐值
地域 选择离用户近的区域 华东 1(杭州)
实例规格 ECS 规格 ecs.c7.xlarge(4 核 8G)
实例密码 ECS 登录密码 复杂密码
VPC 网络 选择已有 VPC 或新建 默认新建
AI 模型类型 大模型接口类型 DashScope(百炼)
API Key 大模型 API Key 你的百炼 AK
Manager 配置 Manager Agent 的模型 同网关配置
技能库地址 OpenClaw 技能注册中心 https://skills.sh(默认)

6.3 确认并创建

确认费用估算后点击立即创建,等待 3-5 分钟,系统自动完成所有容器部署。

6.4 获取访问地址

在计算巢服务实例详情页查看:

  • Element Web 客户端地址
  • Higress AI 网关地址
  • 管理员初始密码

七、首次登录与初始化配置

7.1 配置 hosts 文件(本地部署必须)

本地部署后,需要配置本地 DNS 解析,否则 Matrix 服务相互调用会失败。

macOS / Linux

sudo tee -a /etc/hosts <<EOF
127.0.0.1  matrix-local.hiclaw.io
127.0.0.1  matrix-client-local.hiclaw.io
127.0.0.1  aigw-local.hiclaw.io
127.0.0.1  fs-local.hiclaw.io
EOF

Windows(以管理员身份打开 PowerShell):

$hostsPath = "C:\Windows\System32\drivers\etc\hosts"
$entries = @(
    "127.0.0.1  matrix-local.hiclaw.io",
    "127.0.0.1  matrix-client-local.hiclaw.io",
    "127.0.0.1  aigw-local.hiclaw.io",
    "127.0.0.1  fs-local.hiclaw.io"
)
$entries | Add-Content -Path $hostsPath
Write-Host "hosts 配置完成"

7.2 登录 Element Web

浏览器打开:

http://matrix-client-local.hiclaw.io:8080
# 或者
http://127.0.0.1:18088/#/login

输入安装时生成的 admin 账号密码登录。

7.3 确认 Manager 已在线

登录后你会看到 Matrix 聊天界面。找到名为 Manager 的对话(或房间),直接发消息测试:

你好,请介绍一下你自己

如果 Manager 正常回复,说明部署成功 🎉

7.4 访问管理控制台

各服务的管理界面:

控制台 地址 用途
Element Web(主界面) http://127.0.0.1:18088 与 AI 团队对话
Higress 控制台 http://localhost:8001 管理 API Key、路由、限流
MinIO 控制台 http://localhost:9001 查看 Worker 生成的文件

八、核心功能:创建与管理 Worker 团队

8.1 创建第一个 Worker

在 Matrix 房间向 Manager 发送指令:

帮我创建一个名叫 Alice 的 Worker,她是一名前端开发工程师,
擅长 React 和 TypeScript,工作目录为 /workspace/frontend

Manager 会自动创建 Worker 并将 Alice 加入当前房间。

8.2 创建多 Worker 协作团队

一次性建立完整开发团队:

帮我组建一个完整的开发团队:
- Bob:后端工程师,Python + FastAPI,负责 API 开发
- Alice:前端工程师,React + TypeScript,负责 UI 实现
- Charlie:测试工程师,pytest + Playwright,负责质量保障
- Dave:DevOps 工程师,Docker + Nginx,负责部署上线

8.3 下达任务

@Bob @Alice 我需要一个用户登录功能:
- 后端:Python FastAPI,支持邮箱+密码,JWT Token 认证,bcrypt 加密
- 前端:React 实现登录页面,包含表单验证和错误提示
- 两人协调好接口设计,完成后汇报

Manager 会自动:

  1. 拆解任务到子任务
  2. 分配给 Bob 和 Alice
  3. 在群聊中协调接口定义
  4. 监控进度,发现卡顿自动告警

8.4 查看工作成果

# 进入 MinIO 控制台查看文件
http://localhost:9001
# 账号/密码:安装时自动配置,可在 docker-compose.yml 中查看

所有 Worker 生成的代码、文档、测试报告都会同步到 MinIO,可以直接下载。


九、进阶:Higress 控制台配置

9.1 管理 API Key

进入 Higress 控制台(http://localhost:8001),在 AI 消费者 模块:

  1. 添加真实 API Key(如百炼 sk-xxx
  2. 系统自动生成对应的消费令牌分配给 Worker
  3. Worker 持有消费令牌调用 LLM,真实 Key 不外露

9.2 多模型路由

在 Higress 控制台配置多个 LLM 提供商,实现按任务分配模型:

# 示例:为不同 Worker 配置不同模型
routes:
  - match: "/v1/chat/completions"
    consumer: "worker-alice"    # 前端 Worker
    backend: "qwen3.5-plus"     # 通义千问(便宜)

  - match: "/v1/chat/completions"
    consumer: "worker-bob"      # 后端 Worker
    backend: "gpt-4o"           # GPT-4o(强代码)

9.3 Token 用量监控

Higress 控制台内置 Token 用量统计,可以查看:

  • 各 Worker 的 Token 消耗
  • 每日/每月总用量
  • 费用估算

十、升级与卸载

10.1 升级到最新版本

运行与安装相同的命令,脚本会自动检测到已安装并询问升级方式:

# macOS/Linux
bash <(curl -sSL https://higress.ai/hiclaw/install.sh)

# Windows PowerShell 7
Set-ExecutionPolicy Bypass -Scope Process -Force; $wc=New-Object Net.WebClient; $wc.Encoding=[Text.Encoding]::UTF8; iex $wc.DownloadString('https://higress.ai/hiclaw/install.ps1')

升级选项:

  • 原地升级 (In-place Upgrade):保留所有数据和配置
  • 全新重装 (Fresh Re-installation):删除所有数据,全新安装

10.2 升级到指定版本

HICLAW_VERSION=v1.0.5 bash <(curl -sSL https://higress.ai/hiclaw/install.sh)

10.3 日常运维命令(源码安装)

cd hiclaw

# 发送任务给 Manager(命令行方式)
make replay TASK="帮我分析 /workspace/src 目录的代码结构"

# 查看对话日志
make replay-log

# 重启所有容器
docker compose restart

# 查看容器运行状态
docker compose ps

# 查看某个容器的实时日志
docker logs -f hiclaw-manager-agent

# 卸载 HiClaw(保留数据)
make uninstall

# 完全清理(删除容器和镜像)
make clean

十一、常见问题排查

Q1:容器无法启动

症状docker compose ps 显示某个容器 Exit

排查步骤

# 查看所有容器状态
docker ps -a | grep hiclaw

# 查看 Manager Agent 日志
docker logs hiclaw-manager-agent

# 查看详细内部日志
docker exec -it hiclaw-manager-agent cat /var/log/hiclaw/manager-agent.log

Q2:Element Web 无法访问

症状:浏览器打开 http://127.0.0.1:18088 提示连接失败

排查步骤

# 1. 确认 hosts 配置正确
cat /etc/hosts | grep hiclaw   # macOS/Linux
Get-Content "C:\Windows\System32\drivers\etc\hosts" | Select-String "hiclaw"  # Windows

# 2. 检查端口是否被占用
lsof -i :18088   # macOS/Linux
netstat -ano | findstr :18088  # Windows

# 3. 确认容器正常运行
docker ps | grep element

Q3:Manager 不回复消息

症状:在 Matrix 房间发消息,Manager 没有任何响应

原因和排查

# 最常见原因 1:API Key 无效或余额不足
# → 进入 Higress 控制台测试 API Key 连通性
curl -X POST "http://localhost:8080/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-consumer-token" \
  -d '{"model":"qwen3.5-plus","messages":[{"role":"user","content":"hello"}]}'

# 最常见原因 2:Manager 容器崩溃
docker logs hiclaw-manager-agent --tail 50

# 尝试重启 Manager
docker restart hiclaw-manager-agent

Q4:Windows 下安装卡住或乱码

解决方案

# 确认使用 PowerShell 7(不是 5.x)
$PSVersionTable.PSVersion

# 确认 Docker Desktop 在运行
docker info

# 如果 WSL 版本太低
wsl --update   # 或手动下载最新 MSI 安装

Q5:Worker 创建失败

症状:告诉 Manager 创建 Worker,但房间里没有新成员出现

# 检查 Worker 运行时日志
docker logs hiclaw-openclaw   # OpenClaw 运行时
docker logs hiclaw-copaw      # CoPaw 运行时

# 检查内存是否不足(Worker 创建需要额外内存)
docker stats --no-stream

Q6:文件无法同步到 MinIO

# 检查 MinIO 容器状态
docker logs hiclaw-minio

# 验证 MinIO 可访问
curl http://localhost:9001/minio/health/live

十二、实战演练:46分钟零代码开发一个网页游戏

以下是 HiClaw 真实使用记录,展示 AI 团队自动完成完整开发流程。

12.1 任务描述

向 Manager 发送:
开发一个 1024 网页游戏,完成后部署到服务器的 9999 端口,
确保可以用键盘方向键和触摸操作,支持移动端。

12.2 Manager 自动拆解任务

Manager 接收需求后,自动:

1. 创建 web-dev Worker(前端开发)
2. 创建 devops Worker(运维部署)
3. 给 web-dev 分配游戏开发任务
4. 给 devops 分配部署任务(等 web-dev 完成后)
5. 协调两个 Worker 的工作交接

12.3 执行过程(约 46 分钟)

阶段 执行者 耗时 产出
需求拆解 Manager 2 分钟 任务分配方案
核心逻辑开发 web-dev 20 分钟 game.js(移动逻辑+合并算法)
UI 实现 web-dev 10 分钟 index.html + style.css
触摸/键盘优化 web-dev 5 分钟 事件监听完善
服务器部署 devops 8 分钟 Nginx 配置 + 端口验证
最终验证 Manager 1 分钟 访问测试报告

12.4 成果

游戏地址:http://localhost:9999

功能清单:
✅ 键盘方向键控制(↑↓←→)
✅ 触摸滑动支持(移动端)
✅ 数字合并动画效果
✅ 分数实时统计
✅ 游戏结束检测

人工预估时间:7.5 小时
实际完成时间:46 分钟
效率提升:~90%

十三、与 OpenClaw 对比:什么时候选 HiClaw?

场景 OpenClaw HiClaw
单人使用,简单任务 ✅ 更轻量 杀鸡用牛刀
复杂项目,多任务并行 受限 ✅ Manager 自动调度
团队共用同一套 AI 需自行搭建 ✅ 开箱支持多用户
API Key 安全管理 ⚠️ 需自行处理 ✅ Higress 统一管理
企业内网私有化部署 ✅ 支持 ✅ 支持
5 分钟快速上手 ⚠️ 配置繁琐 ✅ 一键安装

选 HiClaw 的核心理由

  1. 任务复杂度超过单 Agent 能处理的范围
  2. 需要多 Worker 并行工作,缩短完成时间
  3. 有 API Key 安全合规要求
  4. 团队多人共用,需要权限管理

十四、总结

HiClaw 的核心价值在三个字:降门槛

  • 部署门槛:从半天配置到 5 分钟一键安装
  • 使用门槛:从写复杂 Prompt 到自然语言下指令
  • 安全门槛:从 API Key 裸露到 Higress 统一管理

对于想把 AI 真正用于生产的团队来说,HiClaw 提供了一个已经把底层复杂度封装好的起点——你不需要懂 Matrix 协议,不需要手写 Docker Compose,不需要搭 MinIO。这些都在那个 install.sh 里帮你做了。

剩下的,就是想清楚你的 AI 团队要做什么。


参考资料


TagsHiClaw OpenClaw 多智能体 Multi-Agent AI开发团队 Higress Matrix Docker 部署教程

作者:圣殿骑士 | 更新时间:2026-04-09

Logo

Agent 垂直技术社区,欢迎活跃、内容共建。

更多推荐