HiClaw 是基于 OpenClaw 演进出来的本地多 Agent 协作环境，可以理解成 OpenClaw 的 Team 版。

OpenClaw 的核心体验是通过 IM（Instant Messaging，即时通讯）给 Agent 下指令，让它帮你写代码、查资料、操作 GitHub、执行定时任务或调用工具。这个交互方式很自然：用户像发消息一样描述目标，Agent 在背后调用 LLM（Large Language Model，大语言模型）、技能和外部工具完成任务。

但单 Agent 模式用久之后会遇到几个典型问题：

HiClaw 的关键变化是增加了 Manager Agent。Manager 不负责直接写代码或操作文件，而是负责管理 Worker Agent 团队：创建 Worker、拆分任务、分派任务、跟踪进度、汇总结果，并在需要时提醒用户介入。

整体结构可以这样理解：

flowchart TB
    User[用户] -->|自然语言指令| Manager[Manager Agent<br/>任务规划与协调]

    subgraph Local[本地 HiClaw 环境]
        Manager -->|创建与分派任务| Alice[Worker Alice<br/>前端开发]
        Manager -->|创建与分派任务| Bob[Worker Bob<br/>后端开发]
        Manager -->|创建与分派任务| Carol[Worker Carol<br/>文档 / 运营]

        Alice --> FS[(MinIO 共享文件系统)]
        Bob --> FS
        Carol --> FS

        Alice --> Gateway[Higress AI Gateway]
        Bob --> Gateway
        Carol --> Gateway
        Manager --> Gateway

        Matrix[Matrix 群聊房间] <--> Manager
        Matrix <--> Alice
        Matrix <--> Bob
        Matrix <--> Carol
    end

    User <-->|浏览器 / 手机客户端| Matrix

这种设计把“一个什么都干的 Agent”拆成“一个 Manager + 多个专业 Worker”。Manager 像项目负责人，Worker 像不同岗位的成员，每个 Worker 有自己的技能、记忆和工作目录。

两种工作模式

HiClaw 不要求所有任务都走多 Agent 协作。简单任务可以直接交给 Manager，复杂任务再让 Manager 拆给 Worker。

例如“帮我解释一下这段报错”可以直接给 Manager；“做一个 SaaS MVP，并完成产品定义、开发、验收、上线素材准备”更适合让 Manager 组织多个 Worker 协作。

安全设计：Worker 不直接持有真实凭证

原生 OpenClaw 的一个风险点是：Agent 往往直接持有真实 API Key。只要某个 Agent 被诱导输出环境变量、执行危险命令，凭证就可能泄露。

HiClaw 把真实凭证收敛到 Higress AI Gateway 中。Worker 调用模型或外部服务时，不直接拿 API Key，而是通过 Gateway 代理访问。

flowchart LR
    Worker[Worker Agent] -->|Consumer Token| Gateway[Higress AI Gateway]
    Gateway -->|真实 API Key| LLM[Qwen / OpenAI / Claude 等模型]
    Admin[用户 / 管理员] -->|配置一次凭证| Gateway

这个边界很重要：

Worker 看到的东西应该尽量少：

Worker 可以访问：
- 当前任务说明
- 自己的工作目录
- 相关代码仓库或任务文件
- Consumer Token

Worker 不应该访问：
- LLM API Key
- GitHub PAT
- 加密后的真实凭证
- 其他 Worker 的私有记忆

这种设计不是说 Agent 就完全没有风险，而是把风险半径缩小了。即使某个 Worker 执行了不可信技能或被提示注入攻击影响，攻击者也很难直接拿到真实凭证。

Skills 生态：让 Worker 按需安装能力

OpenClaw 生态里有大量技能，技能可以理解成 Agent 的“工具包”或“工作流模板”。例如生成 Changelog、做 PR Review、开发 Higress WASM（WebAssembly）插件，都可以通过技能降低操作成本。

但公开技能库也带来安全顾虑。一个 SKILL.md 文件如果没有完全审查，就有可能包含危险指令，比如诱导 Agent 打印凭证、执行不必要的 shell 命令，或者访问敏感路径。

HiClaw 的处理思路是：

1. Worker 运行在隔离环境里；
2. Worker 不持有真实凭证；
3. 技能安装和执行限制在 Worker 的任务上下文中；
4. 需要模型能力时统一走 Gateway。

当 Worker 发现自己缺少某类能力时，可以通过内置的 find-skills 能力查找并安装技能。一个典型流程如下：

sequenceDiagram
    participant M as Manager
    participant W as Worker
    participant S as Skills Registry

    M->>W: 开发一个 Higress WASM Go 插件
    W->>W: 判断当前技能不足
    W->>S: 搜索 higress wasm
    S-->>W: 返回匹配技能
    W->>W: 安装技能并加载工作流
    W-->>M: 开始执行插件开发任务

对应命令形式类似：

skills find higress wasm

skills add alibaba/higress@higress-wasm-go-plugin -g -y

技能生态的价值在于复用经验，但前提是执行环境要有边界。HiClaw 通过 Worker 隔离和 Gateway 凭证托管，让技能可以更安全地进入实际工作流。

多 Agent 协作：用 Matrix 群聊承载沟通

HiClaw 内置 Tuwunel Matrix Server，并提供 Element Web 客户端。Matrix 是一种开放的实时通信协议，适合用来承载群聊、消息同步和多端访问。

在 HiClaw 中，每个项目可以对应一个 Matrix Room。Manager、Worker 和用户都在这个房间里协作：

flowchart TB
    Room[Matrix 项目群]

    User[用户] <--> Room
    Manager[Manager] <--> Room
    Alice[Worker Alice] <--> Room
    Bob[Worker Bob] <--> Room
    Taylor[Worker Taylor] <--> Room

    Room --> Log[决策记录 / 进度汇报 / 任务状态]

这种方式有几个好处：

为了避免“惊群”，HiClaw 采用按需唤醒策略：Agent 只有在被 @ 时才触发 LLM 调用。

普通群聊消息：不触发所有 Agent
@alex：只唤醒 alex
@manager：只唤醒 Manager

如果每条消息都让所有 Agent 调一次模型，成本和延迟都会迅速上升。按需唤醒让群聊既能保持透明，又不会让无关 Agent 频繁消耗 token。

Human in the Loop：人负责决策，Agent 负责推进

多 Agent 系统不能只追求自动化。项目执行过程中经常会出现需求不清、结果偏离、验收不通过、需要权衡方案等情况，这些节点适合让人介入。

HiClaw 的交互方式是 Human in the Loop，也就是人在关键节点参与：

sequenceDiagram
    participant U as 用户
    participant M as Manager
    participant W as Worker

    U->>M: 启动项目并说明目标
    M->>U: 输出计划，请确认
    U->>M: 确认计划
    M->>W: 分派任务
    W-->>M: 汇报结果
    M->>M: 检查状态
    M-->>U: 汇总结果或请求决策
    U->>M: 通过 / 修改 / 终止

Manager 可以承担的管理工作包括：

记忆管理：把沟通和中间产物分开

单 Agent 容易出现记忆爆炸，原因通常不是“记忆功能不好”，而是不同类型的信息被塞进了同一个上下文里：

• 前端实现细节；
• 后端接口约定；
• 竞品调研材料；
• 临时代码片段；
• 运行日志；
• 产品决策；
• 历史任务总结。

这些信息如果全部写进一个 MEMORY.md，模型每次加载都会带入大量无关上下文，既浪费 token，也容易干扰当前任务。

HiClaw 做了两个拆分。

第一个拆分是按 Worker 隔离记忆：

workers/
  alice/
    skills/
    MEMORY.md
    workspace/
  bob/
    skills/
    MEMORY.md
    workspace/
  taylor/
    skills/
    MEMORY.md
    workspace/

前端 Worker 不需要长期记住运营素材的细节，数据分析 Worker 也不需要加载所有 UI 实现过程。每个 Worker 只维护和自己职责相关的技能与记忆。

第二个拆分是把群聊和文件系统分开：

flowchart TB
    Matrix[Matrix 群聊房间<br/>保存有意义的沟通、决策、状态变化]
    MinIO[(MinIO 共享文件系统<br/>保存代码、文档、日志、临时文件、任务产物)]

    Manager[Manager] --> Matrix
    WorkerA[Worker A] --> Matrix
    WorkerB[Worker B] --> Matrix

    Manager --> MinIO
    WorkerA --> MinIO
    WorkerB --> MinIO

Matrix 群聊只放有意义的沟通和状态，例如：

@manager task-001 已完成，结果在：
~/hiclaw-fs/shared/tasks/task-001/result.md

大量代码、文档、日志、临时数据放到 MinIO 共享文件系统中。这样群聊上下文不会因为文件交换而膨胀，Agent 需要详细材料时再读取对应路径。

成本控制：不同任务用不同模型

不是所有任务都需要最强模型。代码生成、架构设计、复杂推理通常更适合能力更强的模型；信息收集、简单分类、格式整理可以用成本更低的模型。

HiClaw 通过 Higress AI Gateway 做模型入口管理，可以按任务或 Worker 分配不同模型。

假设一个项目包含：

• 3 次代码开发任务，每次 50k tokens；
• 10 次信息收集任务，每次 100k tokens。

如果所有任务都使用同一个较贵模型，成本可能是：

代码任务：3 × 50k × $3/M = $0.45
信息任务：10 × 100k × $3/M = $3.00
总计：$3.45

如果代码任务使用较强模型，信息收集任务使用更便宜的模型：

代码任务：3 × 50k × $3/M = $0.45
信息任务：10 × 100k × $0.25/M = $0.25
总计：$0.70

这里的核心不是固定某个模型价格，而是把“模型选择”从 Agent 内部配置中抽出来，交给 Gateway 统一管理。这样既方便切换供应商，也方便针对不同任务做成本控制。

All-in-One 架构：把网关、通信和存储打包到本地

OpenClaw 原生形态更像一个可组装框架：LLM Provider、消息渠道、存储、客户端都可以接，但需要用户自己配置。

HiClaw 走 All-in-One 路线，把常用组件打包到本地容器环境中：

flowchart TB
    subgraph H[HiClaw All-in-One]
        OC[OpenClaw / pi-mono<br/>Agent 运行核心]

        Gateway[Higress AI Gateway<br/>模型接入、路由、凭证管理]
        Matrix[Tuwunel Matrix Server<br/>消息服务器]
        Element[Element Web<br/>浏览器聊天客户端]
        Mobile[FluffyChat / Element Mobile<br/>移动端客户端]
        MinIO[(MinIO<br/>共享文件系统)]

        OC --> Gateway
        OC --> Matrix
        OC --> MinIO
        Element --> Matrix
        Mobile --> Matrix
    end

    Gateway --> Models[Qwen / OpenAI / Claude 等模型]

主要组件分工如下：

本地安装

安装前需要准备：

• macOS、Linux 或 Windows；
• Docker 环境；
• 至少一个可用的 LLM API Key；
• PowerShell 7+，仅 Windows 安装方式需要。

macOS / Linux 使用：

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

Windows 使用 PowerShell 7+：

Set-ExecutionPolicy Bypass -Scope Process -Force; Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://higress.ai/hiclaw/install.ps1'))

脚本会完成容器拉起、默认配置生成、访问地址和账号密码输出。执行远程安装脚本前，如果环境要求较高，建议先下载脚本检查内容再运行：

curl -sSL https://higress.ai/hiclaw/install.sh -o install.sh
less install.sh
bash install.sh

安装完成后，常见服务如下，实际端口以安装输出为准：

登录流程：

1. 打开安装脚本输出的 Element Web 地址，通常类似 http://127.0.0.1:18088；
2. 使用安装完成时显示的用户名和密码登录；
3. 找到 Manager 对话；
4. 配置 LLM API Key；
5. 给 Manager 发消息，创建第一个 Worker。

可以这样创建 Worker：

帮我创建两个 Worker：

- alice：前端开发，熟悉 React、Next.js、Tailwind CSS
- bob：后端开发，熟悉 Node.js、PostgreSQL、API 设计

Manager 创建完成后，可以直接分派任务：

启动一个任务：做一个简单的 AI 写作助手 MVP。

要求：
- 支持用户输入主题
- 调用模型生成文章草稿
- 保存历史记录
- 提供模型切换入口

请拆分任务，并分配给合适的 Worker。

手机端访问

HiClaw 使用 Matrix 协议，因此不依赖特定企业 IM 平台。手机端可以使用 FluffyChat 或 Element Mobile。

配置步骤：

1. 安装 FluffyChat 或 Element Mobile；
2. 登录时选择自定义服务器；
3. 填入本地或公网可访问的 Matrix Server 地址；
4. 使用 HiClaw 安装时生成的账号登录；
5. 进入项目群查看进度，必要时 @manager 或 @worker 介入。

如果只在本机使用，浏览器访问就够了；如果希望在手机上随时查看，需要确保 Matrix Server 地址能被手机访问。局域网内可以使用电脑的局域网 IP，公网访问则需要额外处理端口暴露、HTTPS 和访问控制。

一个 SaaS MVP 的协作流程示例

假设目标是做一个 AI 写作助手 MVP，团队角色可以拆成：

任务推进可以这样组织：

flowchart TB
    Start[用户提出目标<br/>AI 写作助手 MVP] --> Plan[Manager 制定项目计划]
    Plan --> Confirm{用户确认?}
    Confirm -->|否| Revise[修改计划]
    Revise --> Confirm
    Confirm -->|是| T1[alex: 竞品调研与 PRD]

    T1 --> T2[sam: 技术选型与架构]
    T1 --> T5[taylor: 发布素材准备]
    T2 --> T3[sam: 核心功能开发]
    T3 --> T4[alex: 产品验收]

    T4 --> Check{验收通过?}
    Check -->|否| Fix[sam: 修复问题]
    Fix --> T4
    Check -->|是| Launch[上线准备]

    Launch --> Data[jordan: 配置埋点和数据看板]
    Data --> Report[Manager 汇总日报与建议]

项目过程中，Worker 不需要把大段文档直接贴进群聊，而是把结果写入共享文件系统：

~/hiclaw-fs/shared/tasks/task-001/result.md
~/hiclaw-fs/shared/tasks/task-002/result.md
~/hiclaw-fs/shared/projects/proj-ai-writer/plan.md

群聊中只保留状态和关键结论：

alex: @manager task-001 完成，PRD 已输出。
结果路径：~/hiclaw-fs/shared/tasks/task-001/result.md

manager: 已读取 task-001 结果。
@sam 开始 task-002：技术选型与架构。
PRD 参考：~/hiclaw-fs/shared/tasks/task-001/result.md

如果验收发现问题，也可以自然回退：

alex: @manager task-004 需要修改。
问题：多模型切换入口缺少说明，用户不知道如何选择。
状态：REVISION_NEEDED
反馈路径：~/hiclaw-fs/shared/tasks/task-004/result.md

manager: @sam 创建修订任务 task-006。
目标：增加模型选择引导页。

这种流程的关键不是“让 AI 完全替代人”，而是把拆任务、同步进度、读取结果、提醒下一步这些管理动作自动化。人仍然负责目标定义、计划确认、关键验收和方向调整。

适合与不适合的场景

使用时要注意的坑

1. 远程安装脚本要审查

curl | bash 很方便，但在安全要求高的机器上不应该盲目执行。更稳妥的方式是先下载、检查，再运行。

curl -sSL https://higress.ai/hiclaw/install.sh -o install.sh
less install.sh
bash install.sh

2. 端口冲突要提前处理

如果本机已经运行了其他服务，18080、18001、18088、9000、9001 等端口可能冲突。安装失败时先检查端口占用：

lsof -i :18080
lsof -i :18088
lsof -i :9000

Linux 也可以使用：

ss -lntp | grep 18080

3. Worker 角色不要设得太宽

一个 Worker 最好对应一个相对明确的职责。比如：

好的角色：
- 前端开发
- 后端开发
- 产品经理
- 数据分析
- 技术文档

不好的角色：
- 什么都能干的全能助手
- 负责整个项目所有事情

角色越清晰，技能和记忆越容易保持干净。

4. 群聊里少贴大文件

群聊适合放决策、状态和关键结论，不适合直接粘贴几万行日志或整份代码。大文件应放进共享文件系统，再在群聊中引用路径。

5. 模型路由要按任务分层

代码任务、方案设计、复杂调试可以使用能力更强的模型；信息收集、摘要整理、格式转换可以使用便宜模型。所有 Worker 都用同一个高价模型，会让成本失控。

项目信息

HiClaw 是 Apache 2.0 协议的开源项目，主要由 OpenClaw、Higress AI Gateway、Element Web、Tuwunel Matrix Server 和 MinIO 组合而成。

常用入口：

GitHub: https://github.com/higress-group/hiclaw
Docs:   https://github.com/higress-group/hiclaw/tree/main/docs
Site:   https://www.hiclaw.io/

HiClaw 的核心价值在于把单 Agent 助手升级成可管理的本地 AI 团队：Manager 负责规划和协调，Worker 负责执行具体任务，Gateway 负责凭证与模型路由，Matrix 负责透明沟通，MinIO 负责承载任务产物。对于需要长期推进、多角色协作、又希望本地可控的 Agent 工作流，这种架构比单 Agent 更容易维护。