HiClaw 源码 × 部署 全景图

01 这次怎么部的

用户的需求是部署到 VPS 但不能影响其他线上应用(同一台 VPS 跑着 Coolify + 10 个生产服务)。HiClaw 默认安装会挂载宿主 /var/run/docker.sock,等于宿主 root 权限 —— 直接装风险极大。

最终方案:LXC 系统容器隔离 + Coolify Traefik 反代 + nginx 路径改写

公网 https://hiclaw.kang-kang.com (Let's Encrypt)
        │
        ▼
┌─────────────────────────────────────────────────┐
│  VPS 76.13.31.179  Ubuntu 24.04 / 内核 6.8       │
│                                                  │
│  ┌──────────────────┐  ┌──────────────────┐    │
│  │  宿主 Docker      │  │  LXC 容器 hiclaw  │    │
│  │  (root)           │  │  (10.5.64.46)    │    │
│  │                   │  │  4 核 / 8GB      │    │
│  │ Coolify Traefik   │  │ nesting=true     │    │
│  │   ↓ labels        │  │                  │    │
│  │ hiclaw-traefik-   │  │ 内部 Docker 29.4 │    │
│  │   proxy (nginx)   │──┼─→ hiclaw-manager │    │
│  │                   │  │   (单镜像全家桶)  │    │
│  │ Gitea / SmartFile │  │   ├ Higress      │    │
│  │ Metabase / 等 9 个│  │   ├ Tuwunel      │    │
│  └──────────────────┘  │   ├ Element Web  │    │
│                         │   ├ MinIO        │    │
│                         │   └ OpenClaw     │    │
│                         │     ↓ docker.sock│    │
│                         │   worker-* (动态) │    │
│                         └──────────────────┘    │
└─────────────────────────────────────────────────┘
  

nginx 路径路由(让单域名同时承载 Element Web + Matrix Server)

HiClaw 的 Element Web config.json 把 homeserver 硬编码成 http://matrix-local.hiclaw.io:18080 —— 公网无法解析。我们用 nginx 在传输层"现场改写":

location = /config.json {
    proxy_pass http://10.5.64.46:18088;
    sub_filter_types application/json;
    sub_filter "http://matrix-local.hiclaw.io:18080"
               "https://hiclaw.kang-kang.com";
    sub_filter_once off;
}

# Matrix 服务器路径 -> Higress 网关(带原始 Host 头)
location ~ ^/(_matrix|_synapse) {
    proxy_pass http://10.5.64.46:18080;
    proxy_set_header Host matrix-local.hiclaw.io;
}

# .well-known matrix 服务发现 -> nginx 直接返回公网域名
location = /.well-known/matrix/client {
    return 200 '{"m.homeserver":{"base_url":"https://hiclaw.kang-kang.com"}}';
}

# 其他 -> Element Web
location / {
    proxy_pass http://10.5.64.46:18088;
}

关键:不需要新增 DNS 子域名,单 hiclaw.kang-kang.com 同时承载 Element Web 前端 + Matrix Server 后端 + Synapse 兼容路径 + 服务发现。

关键命令

# 1. 创建 LXC 容器(限资源 + 允许嵌套 Docker)
lxc launch ubuntu:24.04 hiclaw \
  -c security.nesting=true \
  -c limits.cpu=4 -c limits.memory=8GB

# 2. 容器内装 Docker
lxc exec hiclaw -- bash -c "curl -fsSL https://get.docker.com | sh"

# 3. 非交互式安装 HiClaw(必须强制 us-west-1 registry)
lxc exec hiclaw -- bash -c "
  HICLAW_NON_INTERACTIVE=1 \
  HICLAW_REGISTRY=higress-registry.us-west-1.cr.aliyuncs.com \
  HICLAW_LLM_PROVIDER=openai-compat \
  HICLAW_OPENAI_BASE_URL=https://api.poe.com/v1 \
  HICLAW_LLM_API_KEY=sk-poe-... \
  HICLAW_DEFAULT_MODEL=Claude-Sonnet-4.5 \
  HICLAW_LOCAL_ONLY=0 \
  bash hiclaw-install.sh manager
"

# 4. 立即打 clean-install 快照(随时回滚)
lxc snapshot hiclaw clean-install

# 5. 任何时候出问题,5 秒回滚
lxc restore hiclaw clean-install

02 安全模型 · 影响半径

为什么坚持 LXC 而不是直接装到宿主 Docker?因为 HiClaw 的 Worker 是动态创建的代码执行沙箱,Manager Agent 又是 LLM 驱动的 —— 一旦被 prompt 注入或 Worker 沙箱漏掉,挂载 docker.sock 等于把宿主 root 双手奉上。

最坏情况下:LXC 内部全炸 → lxc restore hiclaw clean-install → 5 秒回滚到干净状态,VPS 上其他 9 个应用毫无察觉。

HiClaw 自己的安全设计(也不弱)

• docker-proxy sidecar:Manager 不直接碰 docker.sock,所有 Docker API 调用走 hiclaw-docker-proxy Go 中间层,镜像必须命中白名单(higress-registry.*.aliyuncs.com、hiclaw/*)、容器名必须 hiclaw-worker-* 前缀、禁止 privileged 和 host 路径挂载 docker-proxy/security.go:1-100
• Higress key-auth:每个 Worker 一个 consumer + bearer token,Higress 强制路由级权限,Worker 看不到主 LLM API key manager/scripts/lib/gateway-api.sh:166-200
• Matrix 房间是唯一通信通道:Manager 和 Worker 之间没有任何"私下"对话,人类全程在房间里围观
• Registration token:Matrix 服务器注册需要 64 位随机 token,虽然端点公网可达但实际无法被陌生人注册

03 install.sh · 19 步状态机

官方安装脚本 install/hiclaw-install.sh 2819 行,核心是个 19 步状态机,支持按 b 回退到上一步。每一步既收集配置又即时验证。

非交互模式 HICLAW_NON_INTERACTIVE=1 下,所有 step 跳过询问直接用 env 变量,适合 CI / 自动化部署。install/hiclaw-install.sh:2071-2167

04 整体架构

HiClaw 由 5 个核心组件构成,Manager 是单镜像全家桶(由 supervisord 编排 5 类进程),Workers 是动态拉起的轻量沙箱。

        ┌───── 人类(Element Web)
        │
        ▼ Matrix 协议
┌────────────────────────────────────────────────────┐
│  Manager 容器(单镜像,supervisord 编排)              │
│                                                     │
│  ┌──基础设施层────┐  ┌──网关层────────┐            │
│  │ Tuwunel :6167 │  │ Higress :8080  │ ◀─── LLM 出站│
│  │ MinIO :9000   │  │ apiserver :8001│             │
│  └────────────────┘  │ controller    │             │
│         ▲             │ pilot         │             │
│         │             │ console       │             │
│  ┌──应用层───────┐  └────────────────┘            │
│  │ Element Web   │         ▲                       │
│  │   :8088       │         │                       │
│  │ mc-mirror     │  ┌────────────┐                 │
│  │ hiclaw-       │  │ OpenClaw / │                 │
│  │   controller  │  │ CoPaw      │                 │
│  └────────────────┘  │ Agent      │                 │
│                      └────────────┘                 │
│                            │ docker.sock           │
└────────────────────────────┼───────────────────────┘
                             │ via docker-proxy
                             ▼
        ┌────────────┐  ┌────────────┐  ┌────────────┐
        │ worker-    │  │ worker-bob │  │ worker-... │
        │ alice      │  │            │  │            │
        │ (无状态)    │  │            │  │            │
        └────────────┘  └────────────┘  └────────────┘
                ▲               ▲
                │ MinIO mc mirror(双向)
                ▼
        ┌──────────────────────────┐
        │ MinIO bucket: hiclaw-fs/ │
        │  agents//...       │
        │  shared/tasks/...        │
        │  shared/projects/...     │
        └──────────────────────────┘
  

05 Manager 一体化容器

看见"Manager 容器内同时跑 Higress + Tuwunel + Element Web + MinIO + Agent"第一反应:这违反 Docker "一个容器一个进程"原则。但 HiClaw 选择这么做有道理:对单机部署用户来说,这是开箱即用 vs 编排 5 个 service的取舍。

supervisord 编排 5 个层次

boot 顺序由 priority 字段控制 manager/supervisord.conf:1-143:

对外只暴露 4 个端口:18080(网关)、18001(控制台)、18088(Element Web)、18888(Manager 控制台,本地),通过 install.sh 的 step_ports 配置 install/hiclaw-install.sh:2491-2514。

OpenClaw 镜像构建(关键源码)

# openclaw-base/Dockerfile:54-67
RUN git clone --depth 1 -b hiclaw-v1 \
    https://github.com/johnlanni/openclaw.git /opt/openclaw && \
    cd /opt/openclaw && \
    pnpm install && pnpm build && \
    # 验证 matrix-sdk-crypto 原生模块
    test -f packages/clawdbot/node_modules/@matrix-org/matrix-sdk-crypto-nodejs/matrix-sdk-crypto.linux-x64.node

OpenClaw 是 HiClaw 的 fork(johnlanni/openclaw#hiclaw-v1),不是原版。HiClaw 通过 shell skill 框架扩展其能力,避免了 fork 维护负担。

06 OpenClaw vs CoPaw · 双运行时

HiClaw 支持两种 Agent 运行时,功能和资源各有取舍 manager/scripts/init/start-manager-agent.sh:1-150:

07 hiclaw-controller · K8s 风格声明式

这是 HiClaw 最有意思的组件之一:把整个 Kubernetes 控制平面塞进单个 Go 二进制,然后用它来 watch YAML 文件管理 Worker。

架构

• kine:把 SQLite 包装成 etcd(无需真 etcd 集群)
• 嵌入式 kube-apiserver:127.0.0.1:6443,提供标准 K8s API
• controller-runtime:watch → reconcile 循环
• file watcher:监听 /root/hiclaw-fs/hiclaw-config/ 下的 YAML,自动 import 到 etcd

3 个 CRD

// hiclaw-controller/api/v1beta1/types.go:15-75
type Worker struct {
    Spec WorkerSpec  // model, runtime, image, skills, mcp-servers, expose ports
    Status WorkerStatus  // phase, matrix-user-id, room-id, container-state
}
type Team struct {
    Leader string
    Members []string
    TeamAdmin string
    ChannelPolicy ChannelPolicy
}
type Human struct {
    MatrixID string
    Level int  // L1: DM 权限, L2: group room 权限
}

工作流

1. 用户在 /root/hiclaw-fs/hiclaw-config/workers/alice.yaml 写 YAML
2. file watcher 检测变化 → 解析 → import 到嵌入式 etcd
3. controller-runtime reconcile loop 触发
4. 调用 shell executor(本质是 create-worker.sh 等技能脚本)
5. 结果写回 Worker.status

这相当于把 GitOps 工作流压缩到单容器内 —— 你可以用 kubectl get workers.hiclaw.io 操作 hiclaw-controller,完全跟操作真 K8s 集群一样。hiclaw-controller/cmd/controller/main.go:25-140

08 docker-proxy · 安全隔离层

Manager Agent 是 LLM 驱动的,理论上可被 prompt 注入。如果它直接 docker.sock,等于"恶意 prompt → 任意宿主命令"。docker-proxy 是 Go 写的 Docker API 中间层,做白名单和策略检查。

POST/DELETE 白名单 docker-proxy/main.go:18-25

• POST /containers/create — 允许,但镜像和挂载要过校验
• POST /containers/{id}/{start|stop|kill|restart} — 允许
• POST /exec/{id}/start — 允许
• DELETE /containers/{id} — 允许
• 其他全部拒绝(不能拉任意镜像、不能改 Docker 守护进程配置)

镜像白名单 docker-proxy/security.go:1-100

isHigressRegistry(image)  // higress-registry-*.cr.aliyuncs.com/*
isLocalImage(image)       // hiclaw/*, hiclaw:latest
isLocalhostImage(image)   // localhost/*, 127.0.0.1/*
HICLAW_PROXY_ALLOWED_REGISTRIES // 用户自定义额外白名单

容器策略

• 容器名必须以 hiclaw-worker- 开头
• 禁止 privileged、net_admin、sys_admin 等危险 capability
• 禁止挂载宿主任意路径(防逃逸)

设计哲学:既不信任 Manager Agent(可能被 prompt 注入),也不暴露完整 Docker API。安全验证在代理层,不依赖 Agent 的"诚实"。

09 Worker 生命周期 · 全程拆解

Worker 是完全无状态的容器,所有配置和记忆存在 MinIO,启动时拉取,运行时同步。这让 Worker 可以随时被销毁、重建、跨机迁移,代价是启动慢一点(要 mc mirror)。

worker-entrypoint.sh 6 步启动 worker/scripts/worker-entrypoint.sh:1-150

1. 设置时区(从 TZ env 读)
2. 配置 mc 别名:本地模式直接 mc alias set,云模式调用 ensure_mc_credentials 刷新阿里云 STS 临时凭证
3. 拉取 Worker 配置(重试 6 次,每次 5s):

   mc mirror "${HICLAW_STORAGE_PREFIX}/agents/${WORKER_NAME}/" \
             "${WORKSPACE}/" \
             --exclude ".openclaw/matrix/**" \
             --exclude ".openclaw/canvas/**"

4. 符号链接:把 workspace 目录链接成 HOME,让 OpenClaw 读 ~/.openclaw/openclaw.json
5. 启动 file-sync 后台进程:周期性双向 mc cp(增量)
6. 启动 OpenClaw / CoPaw

MinIO 文件架构

HICLAW_STORAGE_PREFIX/
├── agents/<WORKER_NAME>/
│   ├── openclaw.json        ← Manager 写,Worker 读
│   ├── SOUL.md              ← Worker 身份
│   ├── AGENTS.md            ← 行为指导
│   ├── skills/              ← 双向同步
│   ├── memory/YYYY-MM-DD.md ← Worker 写日记
│   ├── .openclaw/           ← session 状态(不同步)
│   └── credentials/         ← 凭证(不同步)
└── shared/
    ├── tasks/<id>/          ← Manager 和 worker 共享
    ├── knowledge/           ← 知识库
    └── projects/<id>/       ← 项目状态(plan.md 等)

10 Matrix 集成

HiClaw 用 Tuwunel(conduwuit fork,Rust 写的 Matrix 服务器)而不是 Synapse —— 性能更好、单二进制、无 Python 依赖。Manager 容器内嵌一个 Tuwunel 实例,所有 Agent 都注册在这里。

账户和房间

• Manager:@manager:matrix-local.hiclaw.io(管理员账户,自动注册)
• Worker:@<name>:matrix-local.hiclaw.io(create-worker.sh 时通过 registration token 注册)
• 每个 Worker 一个私房间:成员 = Human + Manager + Worker(三方可见,Manager 和 Worker 之间没有"私聊")
• 项目房间:多 Worker 协作时创建,Human + Manager + 团队成员

OpenClaw 的 Matrix 集成

来自 @matrix-org/matrix-sdk-crypto-nodejs 原生模块(支持 E2EE)。openclaw-base 镜像构建时验证原生模块存在 openclaw-base/Dockerfile:54-67。OpenClaw 内置 Matrix channel,自动同步加入房间、接收 @mention 消息触发 agent loop。

CoPaw 的 Matrix 集成(替代实现)

CoPaw 没有原生 Matrix 支持,通过自定义 channel 类继承 BaseChannel,使用 matrix-nio[e2e] 库 copaw/src/copaw_worker/matrix_channel.py:1-100。支持 markdown → HTML 转换、斜杠命令(/message /history /new /clear)。

设计洞察:用 Matrix 协议而不是自建 IM 协议,极大降低维护成本 —— Element Web 直接用,移动端可用 FluffyChat / Element Mobile,联邦/E2EE 全免费。

11 LLM 调用全链路

用户在 Element Web 输入 → Manager 回复,中间 LLM 调用走的是 Higress AI Gateway(不是直接 OpenAI API)。

10 步调用链 manager/scripts/lib/gateway-api.sh:166-200

1. 用户 Element Web 输入消息 → POST /_matrix/client/v3/sync
2. Tuwunel 把消息广播到 Manager 所在 room
3. OpenClaw 在 sync() 轮询里检测到 @manager mention
4. 触发 agent loop:读 SOUL.md 构造 system prompt
5. POST http://127.0.0.1:8080/v1/chat/completions
   Header:Authorization: Bearer ${HICLAW_MANAGER_GATEWAY_KEY}
6. Higress 网关拦截 → 验证 key-auth → 查询 consumer → 检查路由权限
7. 转发到配置的后端(Qwen/OpenAI/Anthropic/Poe...)
8. 响应流式返回给 OpenClaw
9. Agent 解析响应,可能调用 skill 脚本(如 create-worker.sh)
10. 把结果作为新消息发回 Matrix room

多 provider 路由

# manager/scripts/lib/gateway-api.sh:129-147
# 列出所有 AI 路由
curl http://127.0.0.1:8001/v1/ai/routes -b ${HIGRESS_COOKIE_FILE}

# 给每个路由的 allowedConsumers 加白名单
curl -X PUT http://127.0.0.1:8001/v1/ai/routes/{route} \
  -d '{"authConfig": {"allowedConsumers": ["worker-alice", ...]}}'

关键:LLM provider 可以在不改 Agent 代码的前提下动态切换 —— 通过 Higress 控制台改路由配置即可。本次部署我们选 openai-compat + https://api.poe.com/v1,model = Claude-Sonnet-4.5,Higress 把 OpenAI 协议透传给 Poe,工作得很好。

12 MinIO · 单一数据源(SSOT)

HiClaw 把 MinIO 当成整个集群的唯一真相。Manager 和 Worker 之间不直接共享文件,全部通过 MinIO 中转,这是 Worker 无状态的前提。

同步策略

• Manager 主动推:配置文件、技能、共享知识库 → MinIO,每 10s 一次 mc mirror manager/scripts/init/start-mc-mirror.sh
• Worker 启动拉:全量 mc mirror 拉自己 agents/<name>/ 下的所有文件
• Worker 运行同步:后台 file-sync 进程,增量 mc cp,定时把 skills/memory 推回 MinIO
• 排除项:.openclaw/matrix/**(session 缓存)、.openclaw/canvas/**(本地草稿)、credentials/(凭证不同步)

跨容器/跨机部署的关键

因为 MinIO 是唯一真相,理论上你可以把 Manager 跑在一台机器,Workers 跑在另外几台,只要它们都能访问同一个 MinIO 端点 —— 这是 HiClaw 支持云模式(SAE/Aliyun)的基础。本地模式下 MinIO 直接跑在 Manager 容器内。

13 技能系统 · 19 个 shell 技能

HiClaw Agent 的"工具"不是 LLM function calling 那种,而是一堆 shell 脚本。每个技能一个目录,带 SKILL.md(给 Agent 看)和 scripts/(给 shell 跑)。

典型技能目录

skills/worker-management/
├── SKILL.md              # 给 Agent 看:何时调用、参数、陷阱
├── skill.json            # 元数据(名称、描述、参数 schema)
├── scripts/
│   ├── create-worker.sh     # 创建 worker 全流程
│   ├── lifecycle-worker.sh  # 启停/空闲检测
│   └── push-worker-skills.sh
└── references/              # 长篇文档
    ├── create-worker.md
    └── lifecycle.md

核心 19 个技能 manager/agent/skills/

为什么是 shell 而不是 TypeScript/Python?
降低运维门槛 —— 任何会写 bash 的人都能加技能,不需要碰 Node.js 包管理器。SKILL.md 文档化 API 和陷阱,Agent 通过自然语言匹配 description 字段决定调用哪个技能。

14 心跳 · 自动停启 Worker

Manager 定期跑心跳检查 manager/agent/HEARTBEAT.md:1-195,7 步流程,核心是检测空闲 Worker 并自动停止以省内存,任务来时自动重启。

7 步心跳

1. 初始化 state.json — 读 active_tasks 列表
2. 检查 finite tasks — 对每个有限任务,lifecycle-worker.sh --action ensure-ready,Worker 没起就拉起,起好后 @mention 询问进度
3. 检查 infinite tasks — 定时执行类(如"每小时检查邮件"),按 next_scheduled_at 触发
4. 项目进度监控 — 遍历 plan.md,找出标 [~](进行中)的任务,Worker 没动就跟进
5. 容量评估 — 计数 finite 任务数,识别空 Worker,建议 admin 创建新 Worker
6. 容器生命周期 — 同步 Docker 状态到 lifecycle.json,空闲超时 → 自动 stop
7. 汇总报告 — 把所有发现 DM 给 admin

空闲检测核心代码 manager/agent/skills/worker-management/scripts/lifecycle-worker.sh:200-300

_worker_has_finite_tasks() {
    # 查询 state.json,计 .active_tasks[] 中 assigned_to=worker 的有限任务数
}

# 无任务则记 idle_since,超时停止
if [ $idle_duration -gt $idle_timeout_minutes ]; then
    worker_backend_stop "$worker"
    _set_worker_field "$worker" "container_status" "stopped"
    _set_worker_field "$worker" "auto_stopped_at" "$(_ts)"
fi

空闲超时由 HICLAW_WORKER_IDLE_TIMEOUT 控制,默认 720 分钟(12 小时)。下次任务分配时,ensure-ready 会先 docker start 把停掉的 worker 拉回来,对用户透明。

15 凭证 · 入口 · 管理命令

常用运维命令

# SSH 进 VPS
ssh root@76.13.31.179

# 进 LXC
lxc exec hiclaw -- bash

# 看 HiClaw 内部容器状态
lxc exec hiclaw -- docker ps

# 看 Manager 日志
lxc exec hiclaw -- docker logs -f hiclaw-manager

# 重启 LXC(包括内部所有 HiClaw 容器)
lxc restart hiclaw

# 改 nginx 反代配置后必须 down/up(bind mount inode 问题)
cd /opt/hiclaw-proxy && docker compose down && docker compose up -d

# 一键回滚到干净状态
lxc restore hiclaw clean-install

16 源码地图

所有引证都对应 github.com/agentscope-ai/HiClaw 仓库。