[English](./README.md) | [中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md)

**HiClaw 是一个开源的协作多智能体运行时平台。它支持多个 Agent 在受控且可审计的房间中进行协作，并在整个过程中提供完全的人类可见性和干预能力。** 基于 **Manager-Workers 架构** 构建，HiClaw 采用 Manager 集中编排多个 Workers，专注于企业环境中人与 Agent 以及 Agent 之间的协作场景。 HiClaw 不与其他 xxClaw 项目竞争。它不自行实现 Agent 逻辑，而是编排和管理多个 Agent 容器（包括 Manager 和多个 Workers）。 ## 核心特性 - 🧬 **Manager-Workers 架构**：通过 Agent 管理其他 Agent，无需人工监督各个 Worker Claw。 - 🤝 **多运行时协作**：OpenClaw、QwenPaw 和 Hermes Workers 可以在同一个 IM 房间中共存。使用确定性 Agent (OpenClaw/QwenPaw) 作为 Leader 来编排任务，使用 Hermes Workers 进行自主代码执行——让每个运行时各司其职。 - 📦 **MinIO 共享文件系统**：引入共享文件系统用于 Agent 间的信息交换，显著降低多 Agent 协作场景下的 token 消耗。 - 🔐 **Higress AI 网关**：集中流量管理并降低凭据相关风险，免除用户对原生 Lobster 框架中安全漏洞的担忧。 - ☎️ **Element IM 客户端 + Tuwunel IM 服务器（均基于 Matrix 协议）**：免去钉钉/飞书的集成开销和企业审批流程。实现用户快速上手，在 IM 环境中体验模型服务的“乐趣”，同时保持与原生 OpenClaw IM 集成的兼容性。 ## 新闻 - **2026-04-24**: [English](blog/hiclaw-1.1.0-release.md) | [中文](blog/zh-cn/hiclaw-1.1.0-release.md) — HiClaw v1.1.0：Kubernetes 原生控制平面，Hermes 自主编码 Agent 运行时，镜像体积缩减 1.7 GB，hiclaw CLI 替代 shell 脚本。 - **2026-04-14**: [English](blog/hiclaw-k8s-native-multi-agent-collaboration.md) | [中文](blog/zh-cn/hiclaw-k8s-native-multi-agent-collaboration.zh-CN.md) — 深入解析：HiClaw 作为 Kubernetes 原生多 Agent 协作编排系统。 - **2026-04-03**: [English](docs/declarative-resource-management.md) | [中文](docs/zh-cn/declarative-resource-management.md) — HiClaw 1.0.9：Kubernetes 风格的声明式资源管理（Worker、Team、Human 使用 YAML 定义）；Worker 模板市场；Manager CoPaw 运行时；Nacos Skills Registry 及更多功能。 - **2026-03-14**: [English](blog/hiclaw-1.0.6-release.md) | [中文](blog/zh-cn/hiclaw-1.0.6-release.md) — HiClaw 1.0.6：企业级 MCP Server 管理，凭据零暴露。 - **2026-03-10**: [English](blog/hiclaw-1.0.4-release.md) | [中文](blog/zh-cn/hiclaw-1.0.4-release.md) — HiClaw 1.0.4：支持 CoPaw Worker，内存占用减少 80%。 - **2026-03-04**: [English](blog/hiclaw-announcement.md) | [中文](blog/zh-cn/hiclaw-announcement.md) — HiClaw 开源。 ## 为什么选择 HiClaw - **企业级安全性**：Worker Agent 仅使用 consumer token 运行。真实凭据（API keys、GitHub PATs）保留在网关中——Workers 看不到它们，攻击者也看不到。 - **完全私有化**：Matrix 是一个去中心化的开放协议。自行托管，如有需要也可与其他服务器联合。没有供应商锁定，没有数据收割。 - **默认人在回路**：每个 Matrix 房间都包含你、Manager 和相关的 Workers。你可以观察一切，随时介入，没有黑盒。 - **零配置 IM**：内置 Matrix 服务器意味着无需机器人应用、无需 API 审批、无需等待。只需打开 Element Web 即可开始聊天。 - **一条命令设置**：`curl | bash` 即可全部搞定——AI 网关、Matrix 服务器、文件存储、Web 客户端和 Manager Agent。 - **技能生态系统**：Workers 按需从 [skills.sh](https://skills.sh)（超过 80,000 个社区技能）中拉取资源。由于 Workers 无法访问真实凭据，因此非常安全。 ## 快速开始 **前置条件**：Docker Desktop (Windows/macOS) 或 Docker Engine (Linux)。 **资源要求**：最低 2 CPU 核心 + 4 GB 内存。对于多个 Workers，建议 4 核心 + 8 GB 内存。 ### 安装 **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') ``` 安装程序将引导你完成以下步骤： 1. 选择你的 LLM 提供商（支持 OpenAI 兼容 API） 2. 输入你的 API key 3. 选择网络模式（仅限本地或外部访问） 4. 等待设置完成 ### 访问 在浏览器中打开 http://127.0.0.1:18088 并登录 Element Web。Manager 会向你打招呼并解释如何创建你的第一个 Worker。 **移动端**：使用任何 Matrix 客户端（Element、FluffyChat）并连接到你的服务器地址。 **大功告成。** 无需机器人应用。无需外部服务。你的 AI 团队完全在你的机器上运行。 ## 升级 ``` # 升级到最新版本（保留所有数据） bash <(curl -sSL https://higress.ai/hiclaw/install.sh) # 升级到特定版本 HICLAW_VERSION=v1.0.5 bash <(curl -sSL https://higress.ai/hiclaw/install.sh) ``` ## 卸载 **macOS / Linux:** ``` bash <(curl -fsSL https://raw.githubusercontent.com/higress-group/hiclaw/main/install/hiclaw-install.sh) uninstall ``` **Windows (PowerShell):** ``` Set-ExecutionPolicy Bypass -Scope Process -Force; $wc=New-Object Net.WebClient; $wc.Encoding=[Text.Encoding]::UTF8; $s=$wc.DownloadString('https://raw.githubusercontent.com/higress-group/hiclaw/main/install/hiclaw-install.ps1'); & ([scriptblock]::Create($s)) uninstall ``` 这将删除所有 HiClaw 容器（Manager、Workers、docker-proxy）、Docker 卷、网络、环境变量文件、工作区目录和安装日志。 ## 在 Kubernetes 上安装 (Helm) 对于共享/生产部署，你可以通过官方 Helm chart 将 HiClaw 安装在任何 Kubernetes 集群上。默认配置集成了 Higress AI 网关、Tuwunel (Matrix)、MinIO 和 HiClaw controller——无需外部依赖。 **前置条件** - Kubernetes 1.24+ (kind / minikube / k3s / 托管 K8s —— 均可) - Helm 3.7+ - 一个默认的 StorageClass（用于 Tuwunel + MinIO 的 PVC） **安装** ``` helm repo add higress.io https://higress.io/helm-charts helm repo update helm install hiclaw higress.io/hiclaw \ -n hiclaw-system --create-namespace \ --render-subchart-notes \ --set credentials.llmApiKey= \ --set credentials.adminPassword= \ --set gateway.publicURL=http://localhost:18080 ``` 对于暴露 OpenAI 兼容 API 的非 OpenAI 提供商，还需设置 `llmBaseUrl`： ``` helm install hiclaw higress.io/hiclaw \ -n hiclaw-system --create-namespace \ --render-subchart-notes \ --set credentials.llmApiKey= \ --set credentials.llmBaseUrl=https://your-provider.example.com/v1 \ --set credentials.defaultModel=your-model-name \ --set credentials.adminPassword= \ --set gateway.publicURL=http://localhost:18080 ```

改用 Qwen (通义千问)

``` helm install hiclaw higress.io/hiclaw \ -n hiclaw-system --create-namespace \ --render-subchart-notes \ --set credentials.llmApiKey= \ --set credentials.llmProvider=qwen \ --set credentials.defaultModel=qwen3.5-plus \ --set credentials.adminPassword= \ --set gateway.publicURL=http://localhost:18080 ```

| 值 | 必需 | 描述 | |---|---|---| | `credentials.llmApiKey` | 是 | 你的 LLM 提供商的 API key | | `gateway.publicURL` | 是 | 用户访问 Element Web 的公共 URL（例如端口转发使用 `http://localhost:18080`，或通过 Ingress 使用 `https://hiclaw.example.com`） | | `credentials.adminPassword` | 推荐 | Matrix 管理员密码；如果留空将自动生成（你需要从 Secret 中读取） | | `credentials.llmProvider` | 否 | LLM 提供商名称，默认为 `openai-compat` | | `credentials.defaultModel` | 否 | 默认模型，默认为 `gpt-5.4` | | `credentials.llmBaseUrl` | 否 | OpenAI 兼容的 base URL（例如 `https://api.deepseek.com/v1`）。使用官方 OpenAI API 时请留空 | | `manager.runtime` | 否 | Manager Agent 运行时：`openclaw`（默认）、`copaw` 或 `hermes` | | `worker.defaultRuntime` | 否 | 默认 Worker 运行时：`openclaw`（默认）、`copaw` 或 `hermes` |

使用替代运行时 (CoPaw Manager + Hermes Workers)

``` helm install hiclaw higress.io/hiclaw \ -n hiclaw-system --create-namespace --devel \ --set manager.runtime=copaw \ --set worker.defaultRuntime=hermes \ --set credentials.llmApiKey= \ --set credentials.llmBaseUrl=https://your-provider.example.com/v1 \ --set credentials.defaultModel=your-model-name \ --set credentials.adminPassword= \ --set gateway.publicURL=http://localhost:18080 ``` 每个组件的镜像会根据运行时自动选择（Manager 使用 `hiclaw-manager` / `hiclaw-manager-copaw`；Workers 使用 `hiclaw-worker` / `hiclaw-copaw-worker` / `hiclaw-hermes-worker`）。

**多区域镜像仓库** 默认的 `global.imageRegistry` 指向中国区域 (`higress-registry.cn-hangzhou.cr.aliyuncs.com/higress`)。如果你在中国以外的地区部署，请覆盖该设置以加速镜像拉取： | 区域 | 镜像仓库 | |---|---| | 中国 (默认) | `higress-registry.cn-hangzhou.cr.aliyuncs.com/higress` | | 北美 | `higress-registry.us-west-1.cr.aliyuncs.com/higress` | | 东南亚 | `higress-registry.ap-southeast-7.cr.aliyuncs.com/higress` | ``` # 示例：从 North America registry 部署 helm install hiclaw higress.io/hiclaw \ -n hiclaw-system --create-namespace \ --render-subchart-notes \ --set global.imageRegistry=higress-registry.us-west-1.cr.aliyuncs.com/higress \ --set credentials.llmApiKey= \ --set credentials.adminPassword= \ --set gateway.publicURL=http://localhost:18080 ``` 有关所有可配置的值（网关/存储提供商、镜像标签、资源、持久化等），请参见 [`helm/hiclaw/values.yaml`](helm/hiclaw/values.yaml)。 **访问** ``` kubectl port-forward -n hiclaw-system svc/higress-gateway 18080:80 ``` 然后在浏览器中打开 http://localhost:18080 并登录 Element Web。对于实际的集群，请配置指向 `svc/higress-gateway` 的 Ingress / LoadBalancer / DNS 记录，并相应地设置 `gateway.publicURL`。 **升级** ``` helm repo update helm upgrade hiclaw higress.io/hiclaw -n hiclaw-system --reuse-values ``` **卸载** ``` helm uninstall hiclaw -n hiclaw-system kubectl delete namespace hiclaw-system ``` 有关 Kubernetes 原生架构（CRDs、controller、声明式的 `Worker` / `Team` / `Human` 资源），请参见 [docs/k8s-native-agent-orch.md](docs/k8s-native-agent-orch.md)。 ## 工作原理 ### Manager 作为你的 AI 幕僚长 ``` You: Create a Worker named alice for frontend development Manager: Done. Worker alice is ready. Room: Worker: Alice Tell alice what to build. You: @alice implement a login page with React Alice: On it... [a few minutes later] Done. PR submitted: https://github.com/xxx/pull/1 ```

    

_{① Manager creates a Worker and assigns tasks                    ② You can also direct Workers directly in the room}

### 安全模型 ``` Worker (consumer token only) → Higress AI Gateway (holds real API keys, GitHub PAT) → LLM API / GitHub API / MCP Servers ``` Workers 只能看到它们的 consumer token。网关处理所有真实凭据。Manager 知道 Workers 在做什么，但从不触碰实际的密钥。 ### 人在回路 每个 Matrix 房间都包括你、Manager 和相关的 Workers： ``` You: @bob wait, change the password rule to minimum 8 chars Bob: Got it, updated. Alice: Frontend validation updated too. ``` 没有隐藏的 Agent 间调用。一切都是可见且可干预的。 ## 多运行时协作 HiClaw 支持三种可以**在同一 IM 房间中共存**并协作完成任务的 Worker 运行时： - **OpenClaw** (Node.js) — 通用型 Agent，拥有丰富的技能生态系统，非常适合任务编排和工具调用 - **QwenPaw** (Python) — 轻量级运行时，适合浏览器自动化和快速任务 - **Hermes** ([hermes-agent](https://github.com/NousResearch/hermes-agent)) — 自主编码 Agent，具备终端沙箱、自我改进的技能和持久化记忆 每种运行时都有各自擅长的任务。一种常见的模式是：使用确定性 Agent (OpenClaw/QwenPaw) 作为 Leader 来分解和分配工作，并使用 Hermes Workers 进行自主代码执行。所有运行时都在同一个房间中通过 Matrix `m.mentions` 进行通信——完全可见，完全可干预。 ``` # 就地切换任何 worker 的 runtime hiclaw update worker --runtime hermes ``` ## 架构 ``` ┌───────────────────────────────────────────────┐ │ hiclaw-controller │ │ Higress │ Tuwunel │ MinIO │ Element Web │ └──────────────────┬────────────────────────────┘ │ Matrix + HTTP Files ┌──────────────────┴──────────┐ │ hiclaw-manager-agent │ │ Manager (OpenClaw/ │ │ QwenPaw) │ └──────────────────┬──────────┘ │ ┌──────────────────┼────────────────────────────┐ │ │ │ ▼ ▼ ▼ Worker Alice Worker Bob Worker Charlie (OpenClaw) (QwenPaw) (Hermes) ``` | 组件 | 角色 | |-----------|------| | hiclaw-controller | Kubernetes 原生控制平面，协调 Worker/Team/Manager CRs | | Higress AI 网关 | LLM 代理、MCP Server 托管、凭据管理 | | Tuwunel (Matrix) | 自托管 IM 服务器，用于所有 Agent + 人类交流 | | Element Web | 浏览器客户端，零配置 | | MinIO | 集中式文件存储，Workers 为无状态 | ## HiClaw 与原生 OpenClaw 对比 | | 原生 OpenClaw | HiClaw | |---|---|---| | 部署方式 | 单进程 | 分布式容器 | | Agent 创建 | 手动配置 + 重启 | 对话式 | | 凭据管理 | 每个 Agent 持有真实密钥 | Workers 仅持有 consumer token | | 人类可见性 | 可选 | 内置 (Matrix 房间) | | 移动端访问 | 取决于渠道设置 | 任何 Matrix 客户端，零配置 | | 监控 | 无 | Manager 心跳，在房间中可见 | ## 文档 | | | |---|---| | [docs/quickstart.md](docs/quickstart.md) | 逐步指南 | | [docs/architecture.md](docs/architecture.md) | 系统架构深度解析 | | [docs/manager-guide.md](docs/manager-guide.md) | Manager 配置说明 | | [docs/worker-guide.md](docs/worker-guide.md) | Worker 部署说明 | | [docs/development.md](docs/development.md) | 贡献与本地开发 | ## 故障排除 ``` docker exec -it hiclaw-manager cat /var/log/hiclaw/manager-agent.log ``` 有关常见问题，请参见 [docs/zh-cn/faq.md](docs/zh-cn/faq.md)。 ### 报告 Bug 导出你的 Matrix 消息日志，并在提交 issue 之前让 AI 工具根据代码库——这有助于我们更快地修复 bug。 ``` # 导出 debug logs（Matrix 消息 + agent sessions，PII 自动脱敏） python scripts/export-debug-log.py --range 1h ``` 然后在 Cursor、Claude Code 或类似 AI 工具中打开 HiClaw 代码库并提问： 将 AI 的分析结果包含在你的 [Bug 报告](https://github.com/alibaba/hiclaw/issues/new?template=bug_report.yml)中。 你还可以让 AI 工具直接提交 issue 或 PR。安装 [GitHub CLI](https://cli.github.com/)，运行 `gh auth login` 在浏览器中进行身份验证，然后将 [OpenClaw GitHub 技能](https://github.com/openclaw/openclaw/blob/main/skills/github/SKILL.md) 添加到你的 AI 编码工具（Cursor、Claude Code 等）中。之后，只需要求它根据其分析结果提交 issue 或发起 PR 即可。 ## 构建与测试 ``` make build # Build all images make test # Build + run all integration tests make test-quick # Smoke test only ``` ## 其他命令 ``` make replay TASK="Create a Worker named alice for frontend development" make uninstall make help ``` ## 社区 - [Discord](https://discord.gg/NVjNA4BAVw) - [GitHub Issues](https://github.com/alibaba/hiclaw/issues) ## 许可证 Apache License 2.0

标签：Agent, AI开发框架, EVTX分析, HiClaw, LangChain, MITM代理, PyRIT, 中间件, 事件驱动, 人工智能, 人机协同, 任务编排, 分布式系统, 协同办公, 协同计算, 可审计, 响应大小分析, 多智能体系统, 子域名突变, 工作流自动化, 开源, 技术栈, 提示词工程, 搜索语句（dork）, 数字取证, 日志审计, 用户模式Hook绕过, 矩阵协议, 策略决策点, 网络信息收集, 群聊管理, 自动化脚本, 请求拦截, 轻量级, 运行时平台, 逆向工具, 透明度, 通信协议, 项目协作