HiClaw 完整部署教程：5分钟搭建你的 AI 开发团队（Team 版 OpenClaw）

HiClaw 完整部署教程：5分钟搭建你的 AI 开发团队（Team 版 OpenClaw）

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

一、HiClaw 是什么？

1.1 一句话定义

HiClaw = Team 版 OpenClaw。

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

1.2 为什么需要 HiClaw？

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

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 硬件要求

3.2 软件依赖

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

3.3 API Key 准备

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

推荐选项：

四、安装方式一：交互式脚本（推荐新手）

4.1 macOS / Linux 安装

打开终端，执行一行命令：

bash<(curl-sSLhttps://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-ExecutionPolicyBypass-ScopeProcess-Force;$wc=New-ObjectNet.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 克隆仓库

gitclone https://github.com/higress-group/hiclaw.gitcdhiclaw

5.2 最简安装（必须提供 API Key）

HICLAW_LLM_API_KEY="sk-你的APIKey"makeinstall

5.3 非交互式安装（适合自动化脚本）

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

# 最基础配置HICLAW_NON_INTERACTIVE=1\HICLAW_LLM_API_KEY="sk-xxx"\makeinstall# 完整自定义配置示例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"\makeinstall

5.4 完整环境变量参考

六、安装方式三：阿里云计算巢（云端 3 分钟部署）

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

6.1 进入部署页面

访问：HiClaw 计算巢社区版

6.2 填写部署参数

6.3 确认并创建

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

6.4 获取访问地址

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

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

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

7.1 配置 hosts 文件（本地部署必须）

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

macOS / Linux：

sudotee-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$hostsPathWrite-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 访问管理控制台

各服务的管理界面：

八、核心功能：创建与管理 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"# 前端 Workerbackend:"qwen3.5-plus"# 通义千问（便宜）-match:"/v1/chat/completions"consumer:"worker-bob"# 后端 Workerbackend:"gpt-4o"# GPT-4o（强代码）

9.3 Token 用量监控

Higress 控制台内置 Token 用量统计，可以查看：

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

十、升级与卸载

10.1 升级到最新版本

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

# macOS/Linuxbash<(curl-sSLhttps://higress.ai/hiclaw/install.sh)# Windows PowerShell 7Set-ExecutionPolicy Bypass-ScopeProcess -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.5bash<(curl-sSLhttps://higress.ai/hiclaw/install.sh)

10.3 日常运维命令（源码安装）

cdhiclaw# 发送任务给 Manager（命令行方式）makereplayTASK="帮我分析 /workspace/src 目录的代码结构"# 查看对话日志makereplay-log# 重启所有容器dockercompose restart# 查看容器运行状态dockercomposeps# 查看某个容器的实时日志dockerlogs-fhiclaw-manager-agent# 卸载 HiClaw（保留数据）makeuninstall# 完全清理（删除容器和镜像）makeclean

十一、常见问题排查

Q1：容器无法启动

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

排查步骤：

# 查看所有容器状态dockerps-a|grephiclaw# 查看 Manager Agent 日志dockerlogs hiclaw-manager-agent# 查看详细内部日志dockerexec-ithiclaw-manager-agentcat/var/log/hiclaw/manager-agent.log

Q2：Element Web 无法访问

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

排查步骤：

# 1. 确认 hosts 配置正确cat/etc/hosts|grephiclaw# macOS/LinuxGet-Content"C:\Windows\System32\drivers\etc\hosts"|Select-String"hiclaw"# Windows# 2. 检查端口是否被占用lsof-i:18088# macOS/Linuxnetstat-ano|findstr :18088# Windows# 3. 确认容器正常运行dockerps|grepelement

Q3：Manager 不回复消息

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

原因和排查：

# 最常见原因 1：API Key 无效或余额不足# → 进入 Higress 控制台测试 API Key 连通性curl-XPOST"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 容器崩溃dockerlogs hiclaw-manager-agent--tail50# 尝试重启 Managerdockerrestart hiclaw-manager-agent

Q4：Windows 下安装卡住或乱码

解决方案：

# 确认使用 PowerShell 7（不是 5.x）$PSVersionTable.PSVersion# 确认 Docker Desktop 在运行docker info# 如果 WSL 版本太低wsl--update# 或手动下载最新 MSI 安装

Q5：Worker 创建失败

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

# 检查 Worker 运行时日志dockerlogs hiclaw-openclaw# OpenClaw 运行时dockerlogs hiclaw-copaw# CoPaw 运行时# 检查内存是否不足（Worker 创建需要额外内存）dockerstats --no-stream

Q6：文件无法同步到 MinIO

# 检查 MinIO 容器状态dockerlogs hiclaw-minio# 验证 MinIO 可访问curlhttp://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 分钟）

12.4 成果

游戏地址：http://localhost:9999 功能清单： ✅ 键盘方向键控制（↑↓←→） ✅ 触摸滑动支持（移动端） ✅ 数字合并动画效果 ✅ 分数实时统计 ✅ 游戏结束检测 人工预估时间：7.5 小时 实际完成时间：46 分钟 效率提升：~90%

十三、与 OpenClaw 对比：什么时候选 HiClaw？

选 HiClaw 的核心理由：

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

十四、总结

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

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

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

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

参考资料

• HiClaw 官方文档
• HiClaw GitHub 仓库
• HiClaw 快速入门
• 阿里云计算巢部署
• Higress AI Gateway 文档
• OpenClaw 官方文档

Tags：HiClawOpenClaw多智能体Multi-AgentAI开发团队HigressMatrixDocker部署教程

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