HiClaw 架构与设计思路分析

2026-05-15 · 来源：hiclaw-architecture-analysis.md

architecturek8s-operatormulti-agentai-infraagent-platformembedded-k8skinesupervisord

原文：raw/hiclaw-architecture-analysis.md · 仓库：agentscope-ai/HiClaw · 分析版本 v1.1.0 (HEAD e21ac83)

一句话定位

HiClaw 是把 k8s-operator 模式套到 AI Agent 运维上的多 Agent 协作平台——用 4 个 CRD（Worker / Team / Human / Manager）声明 Agent，controller 把每个 Agent 落成"容器 + Matrix IM 用户 + Higress consumer"三位一体；人类、Manager、Workers 全在同一组 Matrix 房间里协作；真实 LLM API key 永远不落到 Worker，只发 consumer key（凭据零暴露）。一行 curl | bash 装到 Docker，或 helm install 到 K8s，二者形态对齐。

核心架构图

flowchart TB subgraph USER["用户接入面 (IM-First)"] EW["Element Web (http://localhost:18088)"] MC["any Matrix client (mobile)"] end subgraph CTRL["控制平面 — hiclaw-controller (Go)"] direction TB App["cmd/controller/main.go → internal/app/App
initInfraClients · initBackends · initServiceLayer · initReconcilers
initFieldIndexers · initAuth · initHTTPServer"] subgraph REC["4 个 CRD Reconciler (controller-runtime)"] direction LR W["Worker"] T["Team"] H["Human"] M["Manager"] end Prov["internal/service/provisioner.go (1154 行)
· Matrix admin API (user / room / membership)
· Higress gateway auth (consumer key, MCP route)
· Credentials store (refresh, delete, bootstrap admin token)
· AccessResolver (object-storage / ai-gateway scope)"] Back["internal/backend/{docker,kubernetes}.go
WorkerBackend 接口"] HTTP["HTTP API (server/http.go) ← hiclaw CLI
运行模式: startEmbedded (kine etcd:2379, in-binary mgr)
或 startInCluster (KUBECONFIG)"] App --> REC --> Prov --> Back App --> HTTP end subgraph DATA["数据 / 执行平面 (容器层)"] direction TB Mgr["Manager 容器 (一个)
manager/agent/
· SOUL.md / TOOLS.md
· 12 个管理 skill
· workers-registry.json"] Wkr["Worker 容器 (N 个，按 CR 数量)
runtime 三选一: openclaw-base / copaw / hermes
共同套件:
· mcporter-servers.json (MCP 路由)
· soul / identity / skills (Worker 人格)
· bridge.py (Matrix sync, 仅 Python runtime)"] end subgraph INFRA["基础设施"] direction LR Tw["Tuwunel
(Matrix server)
房间 / 用户 / 消息"] Hi["Higress AI Gateway
(LLM/MCP/OSS 凭据全部托管)"] Mi["MinIO
(Worker 共享文件系统
跨 Agent 协作)"] end USER -- "Matrix 协议 (E2E)" --> CTRL CTRL -- "container exec" --> DATA Mgr -- "hiclaw CLI" --> HTTP DATA --> INFRA USER -.-> Tw classDef u fill:#1e3a8a,stroke:#1e40af,color:#fff classDef c fill:#7c2d12,stroke:#9a3412,color:#fff classDef d fill:#14532d,stroke:#166534,color:#fff classDef i fill:#5b21b6,stroke:#6d28d9,color:#fff class USER,EW,MC u class CTRL,App,REC,W,T,H,M,Prov,Back,HTTP c class DATA,Mgr,Wkr d class INFRA,Tw,Hi,Mi i

原 ASCII 图

┌──────────────────────────  用户接入面（IM-First）  ──────────────────────────┐
│                                                                                │
│       Element Web (http://localhost:18088)  ←──  any Matrix client (mobile)    │
│                              │                                                  │
└──────────────────────────────┼──────────────────────────────────────────────────┘
                               │ Matrix 协议（E2E）
                               ▼
┌────────────────────────  控制平面（hiclaw-controller, Go）  ─────────────────────┐
│  cmd/controller/main.go → internal/app/App                                       │
│  ┌─────────────────────────────────────────────────────────────────────────┐    │
│  │  initInfraClients  initBackends  initServiceLayer  initReconcilers       │    │
│  │  initFieldIndexers initAuth      initHTTPServer                          │    │
│  └─────────────────────────────────────────────────────────────────────────┘    │
│                                                                                  │
│  4 个 CRD Reconciler（controller-runtime）                                       │
│   ┌──────────┐ ┌────────┐ ┌──────────┐ ┌──────────┐                              │
│   │ Worker   │ │ Team   │ │ Human    │ │ Manager  │  (api/v1beta1/types.go)      │
│   └────┬─────┘ └────┬───┘ └────┬─────┘ └────┬─────┘                              │
│        └────────────┴──────────┴────────────┘                                    │
│                    │ ProvisionWorker / DeprovisionWorker                          │
│                    ▼                                                              │
│        internal/service/provisioner.go (1154 行)                                  │
│        ├─ Matrix admin API     (创建/删除 user, 创建/退出 room, 邀请成员)         │
│        ├─ Higress gateway auth (consumer key, MCP route)                          │
│        ├─ Credentials store    (refresh, delete, bootstrap admin token)           │
│        └─ AccessResolver       (object-storage / ai-gateway scope 解析)           │
│                    │                                                              │
│                    ▼                                                              │
│        internal/backend/{docker,kubernetes}.go  (WorkerBackend 接口)              │
│                    │                                                              │
│  HTTP API (server/http.go) ←─── hiclaw CLI (cmd/hiclaw/main.go)                  │
│  运行模式：startEmbedded(kine etcd:2379, in-binary mgr) 或 startInCluster(KUBECONFIG)│
└──────────────────────────────────────────────────────────────────────────────────┘
                               │ container exec
                               ▼
┌─────────────────────  数据/执行平面（容器层）  ───────────────────────────────────┐
│                                                                                    │
│  Manager 容器（一个）             Worker 容器（N 个，按 CR 数量）                  │
│  ┌──────────────────┐             ┌─────────────────────────────────────────────┐ │
│  │ manager/agent/   │  Matrix     │ runtime 三选一：                             │ │
│  │  SOUL.md /       │ ◀────────▶ │   • openclaw-base/  (Claude-Code 类)         │ │
│  │  TOOLS.md /      │             │   • copaw/   (QwenPaw, Python)              │ │
│  │  12 个管理 skill │             │   • hermes/  (autonomous coding, Python)     │ │
│  │  workers-        │             │ 共同套件：                                   │ │
│  │  registry.json   │             │   • mcporter-servers.json (MCP 路由)         │ │
│  └────────┬─────────┘             │   • soul/identity/skills (Worker 人格)       │ │
│           │ hiclaw CLI            │   • bridge.py (Matrix sync, 仅 Python runtime)│ │
│           ▼                       └────┬────────────────────────────────────────┘ │
│   controller HTTP API                  │                                          │
└────────────────────────────────────────┼──────────────────────────────────────────┘
                                         │
              ┌──────────────────────────┼──────────────────────────┐
              ▼                          ▼                          ▼
   ┌──────────────────┐       ┌────────────────────┐      ┌────────────────────┐
   │ Tuwunel          │       │ Higress AI Gateway │      │ MinIO              │
   │ (Matrix server)  │       │ (LLM/MCP/OSS 凭据  │      │ (Worker 共享文件   │
   │ 房间/用户/消息   │       │ 全部托管在网关侧)  │      │ 系统，跨 Agent 协作)│
   └──────────────────┘       └────────────────────┘      └────────────────────┘

           Helm chart (helm/hiclaw/) 在 K8s 上把上面 4 个组件一并部署
           install/hiclaw-install.sh / .ps1 在 Docker 单机上等价部署

四个 CRD

CRD	表达什么	关键 Spec 字段
`Worker`	单个 AI Agent	`model` · `runtime`（openclaw/copaw/hermes）· `image` · `soul` · `skills` · `mcpServers` · `package`（`file://` / `http(s)://` / `nacos://`）· `expose` · `accessEntries` · `state`（Running/Sleeping/Stopped）
`Team`	一组 Worker + Leader + 房间策略	`leader` · `workers` · `peerMentions` · `channelPolicy` · `admin`
`Manager`	系统唯一的管家 Agent	model / runtime / soul / skills（含 12 个管理 skill）
`Human`	管理员的 Matrix 身份	matrixUserID · channel scope

模块分层（简版）

层	职责
CRD 定义	`api/v1beta1/types.go`，仅依赖 `k8s.io/apimachinery`，不引用任何 internal 包
应用骨架	`internal/app/App` 用 7-step init 串行装配，扩展只需 append `{name, initFn}`
CR Reconciler	Worker / Team / Human / Manager 4 套，仅做编排，绝不直接调外部 API
服务编排	`internal/service/provisioner.go`（1154 行，脏活集中地，reconcile 的大半在这里）
容器后端	`WorkerBackend` 接口 + `docker.go` / `kubernetes.go` 两个实现，按 config 选
基础设施集成	`internal/{matrix,gateway,oss,credprovider,accessresolver}/` 分别封装 Tuwunel / Higress / MinIO / 阿里云凭据 / 模板解析
运行模式	`startEmbedded`（`k3s-io/kine` SQLite-backed etcd 在 127.0.0.1:2379 + 内嵌 mgr）或 `startInCluster`（标准 KUBECONFIG）
Manager Agent	`manager/agent/` 容器化 orchestrator，12 个管理 skill + `workers-registry.json`，通过 `hiclaw` CLI 操作 controller
Worker runtime	OpenClaw（claude-code 系，Dockerfile only）· QwenPaw（Python，`copaw/`）· Hermes（Python，autonomous coding）
部署	`helm/hiclaw/`（K8s）/ `install/hiclaw-install.{sh,ps1}`（Docker 单机），二者部署形态对齐

嵌入式模式（Docker 单机）容器内部结构

curl | bash 装出来的「Docker 模式」并不是一个容器，而是一个基础设施容器 + N 个被它创建的 Agent sibling 容器。两者镜像和职责完全不同：

容器	镜像 / Dockerfile	谁启动	包含什么
`hiclaw-controller`	`hiclaw-controller/Dockerfile.embedded`，基于 `higress/all-in-one`	用户 `docker run`（或安装脚本）	Higress + Tuwunel + MinIO + Element Web/nginx + `hiclaw-controller` Go 进程 + `kube-apiserver` 子进程 + kine（嵌在 controller 进程里）
`hiclaw-manager`	`manager/Dockerfile`，基于 `openclaw-base`	controller 的 `ManagerReconciler` 通过 `docker.sock` 创建	仅 Manager Agent 进程（OpenClaw / CoPaw）+ `hiclaw` CLI，不包含任何基础设施
`worker-*`	OpenClaw / CoPaw / Hermes 任一 worker 镜像	同上，由 `WorkerReconciler` 按 CR 创建	单个 Worker Agent，bridge.py 通过 consumer key 接入 Matrix

`hiclaw-controller` 内部进程树（supervisord 管理）

flowchart TB P["PID 1 — supervisord"] MinioP["minio
MinIO Server (:9000 / 控制台 :9001)"] Tuw["tuwunel
Matrix Homeserver"] APIs["start-apiserver.sh
Higress 自带 apiserver (file storage, :18443)
→ apiserver --storage file --file-root-dir /data"] HCtl["start-controller.sh
Higress Controller"] Pilot["start-pilot.sh
Istio Pilot (Higress 用)
→ pilot-discovery"] GW["start-gateway.sh
Higress Gateway
higress-proxy-start.sh
· supercronic
· pilot-agent → envoy
AI Gateway 数据面 (:8080)"] Con["start-console.sh
Higress Console (:8001)
java -jar higress-console.jar"] Nx["nginx (master/worker)
Element Web 静态文件 (:18088)"] Mc["start-mc-mirror.sh
MinIO Client 同步守护"] HCt["hiclaw-controller
Go controller 主进程 (:8090 HTTP API)
↳ kube-apiserver (由 controller fork, :6443)
　etcd 后端 = 进程内嵌 kine
　证书/token 在 /data/hiclaw-controller/pki/"] P --> MinioP & Tuw & APIs & HCtl & Pilot & GW & Con & Nx & Mc & HCt

原 ASCII 图

PID 1  supervisord
├── minio                                  ← MinIO Server (:9000 / 控制台 :9001)
├── tuwunel                                ← Matrix Homeserver
├── start-apiserver.sh                     ← Higress 自带 apiserver (file storage, :18443)
│   └── apiserver --storage file --file-root-dir /data
├── start-controller.sh                    ← Higress Controller
├── start-pilot.sh                         ← Istio Pilot (Higress 用)
│   └── pilot-discovery
├── start-gateway.sh                       ← Higress Gateway
│   └── higress-proxy-start.sh
│       ├── supercronic
│       └── pilot-agent ── envoy           ← AI Gateway 数据面 (:8080)
├── start-console.sh                       ← Higress Console (:8001)
│   └── java -jar higress-console.jar
├── nginx (master/worker)                  ← Element Web 静态文件 (:18088)
├── start-mc-mirror.sh                     ← MinIO Client 同步守护
└── hiclaw-controller                      ← Go controller 主进程 (:8090 HTTP API)
    └── kube-apiserver                     ← 由 controller fork (:6443)
                                             etcd 后端 = 进程内嵌 kine
                                             证书/token 在 /data/hiclaw-controller/pki/

关键点：kube-apiserver (PID = controller 的子进程) 与 Higress 自带的 apiserver（监听 18443，给 Istio Pilot 用的 file-storage 简易 apiserver）不是一个东西。前者是真 K8s API（用 6443），后者是 Higress 内部配置存储，互不读取对方数据。

嵌入式 K8s 的本质：只搬控制面，不搬节点

flowchart LR subgraph REAL["真 K8s 集群"] direction TB R1["kube-apiserver"] R2["etcd"] R3["kube-controller-mgr"] R4["kube-scheduler"] R5["kubelet / CNI / CRI"] end subgraph EMB["hiclaw-controller 容器内"] direction TB E1["kube-apiserver (:6443, --bind-address=127.0.0.1)"] E2["kine (SQLite, /data 落盘, 嵌在 hiclaw-controller 进程里)"] E3["hiclaw-controller 自己充当 4 个 CRD 的 reconciler"] E4["(无 Pod 概念)"] E5["workload 走宿主机 docker.sock 起 sibling 容器"] end R1 -- "✅ 搬" --> E1 R2 -- "✅ 搬" --> E2 R3 -- "❌ 不搬" --> E3 R4 -- "❌ 不搬" --> E4 R5 -- "❌ 不搬" --> E5 classDef real fill:#1e3a8a,stroke:#1e40af,color:#fff classDef emb fill:#7c2d12,stroke:#9a3412,color:#fff class REAL,R1,R2,R3,R4,R5 real class EMB,E1,E2,E3,E4,E5 emb

原 ASCII 图

真 K8s 集群                   hiclaw-controller 容器内
─────────────                ────────────────────────
kube-apiserver       ✅  →   kube-apiserver (:6443, --bind-address=127.0.0.1)
etcd                 ✅  →   kine (SQLite, /data 落盘，嵌在 hiclaw-controller 进程里)
kube-controller-mgr  ❌      ← hiclaw-controller 自己充当 4 个 CRD 的 reconciler
kube-scheduler       ❌      ← 没有 Pod 概念
kubelet / CNI / CRI  ❌      ← workload 走宿主机 docker.sock 起 sibling 容器

K8s 在这里只承担两件事：CRD 存储（Worker / Manager / Team / Human 当 K8s 资源写入 kine）+ 声明式 watch/reconcile 接口（controller-runtime 标准模式）。真正的 workload 容器不在 K8s 里跑，而是 backend.DockerBackend 通过宿主机 /var/run/docker.sock 直接 docker create——和 K8s 模式（HICLAW_RUNTIME=k8s）共用同一份 controller 代码、同一套 CRD，只切 backend 实现，零分叉。

为什么 `kubectl` 在容器外不通

读完上面就能理解三个限制：

kube-apiserver --bind-address=127.0.0.1（internal/apiserver/embedded.go:102），端口未对外暴露；
controller 直接构造 rest.Config 内存对象，不写 kubeconfig 文件（embedded.go:128-134）；
容器里没有装 kubectl，因为日常运维设计入口是 hiclaw CLI——controller 启动时 bootstrapAdminCLIToken 已经把长期 admin token 写入 /var/run/hiclaw/cli-token，docker exec hiclaw-controller hiclaw get worker 直接可用，省掉 TLS + token 链路。

要直接调 K8s API（应急场景），凭证在容器内的位置是：

/data/hiclaw-controller/admin-token       ← Bearer token（system:masters 组）
/data/hiclaw-controller/pki/ca.crt        ← API server CA
/data/hiclaw-controller/pki/token.csv     ← apiserver 的静态 token 表

curl 一行验证 CRD 数据存在：

TOKEN=$(docker exec hiclaw-controller cat /data/hiclaw-controller/admin-token)
docker exec hiclaw-controller curl -s --cacert /data/hiclaw-controller/pki/ca.crt \
  -H "Authorization: Bearer $TOKEN" \
  https://127.0.0.1:6443/apis/hiclaw.io/v1beta1/managers | jq '.items[].metadata.name'

关键数据流：建一个 Worker 端到端

flowchart TD Admin["管理员 (Element Web 中)
发送 Matrix 消息: '帮我建一个 Go 代码评审 Worker'"] Mgr["Manager Agent 容器 (manager/agent)
· 加载 worker-management skill (TOOLS.md 路由)
· 决定参数 (model / runtime / soul / skills / mcp-servers)
· 调 hiclaw CLI: hiclaw worker create --name go-review …"] CLI["hiclaw CLI (cmd/hiclaw/main.go) — HTTP POST → controller server/http.go"] Write["写入 Worker CR
(embedded: kine sqlite / in-cluster: etcd)"] Watch["controller-runtime watch 触发
worker_controller.Reconcile()"] P1["[1] Provisioner.ProvisionWorker(ctx, req)
· Matrix admin API → 创建 user @go-review:hiclaw.local
· Matrix admin API → 创建 1on1 房间，邀请管理员 + Manager
· Higress apig API → 注册 consumer + 颁发 consumer key
· AccessResolver → 解析 AccessEntries 模板 (${self.name}…)
　→ 调 credprovider 申请 MinIO 桶权限
· Credentials store → 写入 secret + 设 refresh 时刻"] P2["[2] WorkerBackend.CreateWorker(spec)
docker.go 或 kubernetes.go (依 config)
→ 挂载 PodTemplate + 环境变量 + soul/identity/skills 卷
→ 启动 Worker 容器"] P3["[3] member_reconcile.go
把 Worker Matrix user 加入相关 Team 房间 (如有)"] P4["[4] 更新 Worker.Status
Phase = Running
MatrixUserID = '@go-review:hiclaw.local'
RoomID = '!abc...:hiclaw.local'
ContainerState = 'running'
ExposedPorts = […] (若 Spec.Expose 有端口)"] Boot["Worker 容器启动后
· Python runtime (copaw/hermes): bridge.py 用 consumer key 登录 Matrix，订阅自己的房间
· OpenClaw runtime: 宿主 Claude Code 自带 hook 完成同等动作"] Done["管理员立刻在 Element Web 看到 @go-review 出现并打招呼
后续的代码评审请求可直接 @"] Admin --> Mgr --> CLI --> Write --> Watch Watch --> P1 --> P2 --> P3 --> P4 --> Boot --> Done

原 ASCII 图

管理员（Element Web 中）
      │ 发送 Matrix 消息："帮我建一个 Go 代码评审 Worker"
      ▼
Manager Agent 容器（manager/agent）
      │ 加载 worker-management skill (TOOLS.md 路由)
      │ 决定参数（model / runtime / soul / skills / mcp-servers）
      │ 调 hiclaw CLI: `hiclaw worker create --name go-review …`
      ▼
hiclaw CLI (cmd/hiclaw/main.go) ── HTTP POST ──▶ controller server/http.go
                                                       │
                                                       ▼
                                                 写入 Worker CR
                                          (embedded: kine sqlite / in-cluster: etcd)
      ┌─────────────── controller-runtime watch 触发 ───────────────┐
      ▼
worker_controller.Reconcile()
      │
      ├─[1] Provisioner.ProvisionWorker(ctx, req):
      │      Matrix admin API → 创建 user @go-review:hiclaw.local
      │      Matrix admin API → 创建 1on1 房间，邀请管理员 + Manager
      │      Higress apig API → 注册 consumer + 颁发 consumer key
      │      AccessResolver  → 解析 AccessEntries 模板（${self.name}…）
      │                       → 调 credprovider 申请 MinIO 桶权限
      │      Credentials store → 写入 secret + 设 refresh 时刻
      │
      ├─[2] WorkerBackend.CreateWorker(spec):
      │      docker.go 或 kubernetes.go（依 config）
      │      → 把 PodTemplate + 环境变量 + soul/identity/skills 卷挂上
      │      → 启动 Worker 容器
      │
      ├─[3] member_reconcile.go：
      │      把 Worker Matrix user 加入相关 Team 房间（如有）
      │
      └─[4] 更新 Worker.Status：
            Phase = Running
            MatrixUserID = "@go-review:hiclaw.local"
            RoomID       = "!abc...:hiclaw.local"
            ContainerState = "running"
            ExposedPorts   = [...]   ← 若 Spec.Expose 有端口
      │
      ▼
Worker 容器启动后：
   - Python runtime (copaw/hermes)：bridge.py 用 consumer key 登录 Matrix，订阅自己的房间
   - OpenClaw runtime：宿主 Claude Code 自带 hook 完成同等动作
      │
      ▼
管理员立刻在 Element Web 看到 @go-review 出现并打招呼；后续的代码评审请求可直接 @

稳态通信信道

flowchart LR W["Worker 容器"] HG["Higress AI Gateway
(凭据托管)"] LLM["LLM provider"] MCP["MCP server
(external 或 in-cluster)"] Tw["Tuwunel
(Matrix)"] Mi["MinIO
(大文件)"] Hu["Human (Element Web)"] Wo["其他 Worker"] Mg["Manager 容器
(内含 hiclaw CLI)"] Ctrl["controller"] KV["etcd / kine"] W -- "consumer key" --> HG -- "真实 API key" --> LLM W -- "consumer key → route" --> HG -- "route" --> MCP W <--> Tw Wo <--> Tw Hu <--> Tw W -- "大文件 (节省 token)" --> Mi Wo -- "大文件" --> Mi Mg -- "HTTP" --> Ctrl -- "CR write" --> KV

原 ASCII 图

Worker → LLM:    Worker 容器 ─consumer key→ Higress AI Gateway ─真实 API key→ LLM provider
Worker ↔ Worker: 双方都加入同一 Matrix 房间，消息走 Tuwunel；大文件落 MinIO（节省 token）
Worker ↔ Human:  Matrix 房间（管理员是房间成员，可以随时介入）
Worker → 工具:    Worker 容器 ─consumer key→ Higress ─route→ MCP server（external 或 in-cluster）
Manager → 控制器: Manager 容器内的 hiclaw CLI ─HTTP→ controller ─CR write→ etcd/kine

设计决策与哲学

声明式 Agent 运维：Agent 是 CR 不是对象。免费拿到 K8s 的 declarative / reconcile / self-healing / RBAC——这是 HiClaw 与 langgraph / autogen / crewai 这类「代码中编排 Agent」框架的根本不同。
IM 协议作为协作平面 lingua franca：选 Matrix 而非自研 Web UI/事件总线——每个 Agent 是 IM 用户，每场协作是 IM 房间，人类天然是房间成员，可观测性与人在回路同时拿到，避免两个大坑。代价：所有 Agent 都要做 Matrix 适配。
凭据零暴露：Worker 永远拿不到真实 API key / GitHub PAT / OSS AK，只持 Higress consumer key。结果：MCP 工具市场和 skills 市场可以大胆装载社区作品——即便 Worker 被 prompt injection 攻陷，攻击者拿到的也只是可被即时 revoke 的 consumer key。
运行时三选一可插：WorkerSpec.Runtime 字段切换 OpenClaw（claude-code 系）/ QwenPaw（Qwen Code 系，省钱）/ Hermes（autonomous coding agent，自主）。最近 commit d3e33e8 把默认 runtime 从 OpenClaw 切到 QwenPaw，价格敏感倾向明显。
容器后端双轨：WorkerBackend 接口 + docker.go / kubernetes.go 两实现，让"单机 Docker Desktop 跑 5 个 Worker"与"K8s 集群跑 500 个 Worker"共用同一 controller 二进制。
嵌入式 K8s（kine + 内嵌 controller-manager）：单机模式跑 kine（SQLite-backed etcd）+ 同进程的 controller-manager，于 127.0.0.1:2379。用户感觉装了 Docker，骨子里是 K8s API——CRD / Reconcile / Helm 在无真 K8s 环境也成立。
schema-less 模板字段：AccessEntry.Scope 用 *apiextensionsv1.JSON 而非严格 struct，支持 ${self.name} / ${self.kind} / ${self.namespace} 运行期变量。CRD 不绑死特定 cloud provider；解析延迟到 accessresolver。
hiclaw CLI 注入 Manager / Worker 容器：Manager Agent 不引用 Go SDK，通过 fork CLI 操作 controller HTTP API——让 skill（markdown 文档）可以直接生成 hiclaw worker create … 这种命令字符串。
MCP via Nacos 包市场：Worker 能力通过 WorkerSpec.Package 字段（nacos:// / http(s):// / file://）按需加载。Manager 侧的 hiclaw-find-worker skill 就是做 Nacos 搜索 + 导入。Worker 模板像 docker 镜像一样可分发。

关键组件深入：Provisioner

internal/service/provisioner.go（1154 行 / 29 公开方法）是 controller 的脏活集中地，可分三组：

Matrix 编排（ProvisionWorker / ProvisionTeamRooms / EnsureRoomMember / ReconcileRoomMembership …）——通过 Tuwunel admin API 完成 user / room / membership / alias 全生命周期；MatrixUserID(name) 与 roomAliasLocalpart(kind, name) 是命名规则集中点，保证幂等。
Higress 凭据（EnsureManagerGatewayAuth / EnsureWorkerGatewayAuth / RefreshCredentials / DeleteCredentials）——用 alibabacloud-go/apig-20240327/v6 在 Higress 上为每个 Agent 注册 consumer + key。
Manager 引导（IsManagerLLMAuthReady / IsManagerJoinedDM / SendManagerWelcomeMessage）——容器首启时检查 Manager 是否就绪 + 投递欢迎语（按 language / timezone 渲染）。

横向拆分时机已到：按 Matrix / Higress / Credentials / Manager-bootstrap 四个域拆到独立文件，Provisioner 退化为外观。

与同类对比

维度	HiClaw	autogen	langgraph	crewai
形态	K8s operator + 容器化	Python library	Python library	Python library
Agent 表达	CR (YAML)	Python class	StateGraph node	Crew/Agent class
部署单元	Pod / Container	进程	进程	进程
协作面	Matrix 房间	In-process bus	StateGraph 边	Crew 内调度
人在回路	默认（房间成员）	需自接 UI	需自接 UI	需自接 UI
凭据模型	网关托管	Agent 持真 key	Agent 持真 key	Agent 持真 key
跨 Agent 文件	MinIO 桶	自实现	自实现	自实现

最大差异：HiClaw 把 Agent 当 K8s 一等公民资源，所以是"可被 reconcile 自愈 / 可被 helm 上线 / 可被 RBAC 限定"的东西。其余框架本质是"在你进程里跑一段 Python"，做企业级运维要重头补。代价：学习曲线高、每 Worker 一个容器有 RAM / 镜像开销。

演进信号

近 30 天最活跃：install/hiclaw-install.sh（20）· internal/service/provisioner.go（12）· api/v1beta1/types.go（12）· internal/config/config.go（11）→ 主线是"装上 / 升级体验" + "controller 核心模型稳定"
关键 PR：#780 默认 runtime → QwenPaw · #749 --keep-all 升级 · #783 helm uninstall 残留清理 · #785 manager 容器 API 对齐 controller /api/v1 · #798 error() 多行安全
v1.0 → v1.1 阶段，下一步看点：Hermes runtime 主线化、多租户 RBAC、kine → 真 etcd 平滑迁移工具

HiClaw 架构与设计思路分析

一句话定位

核心架构图

四个 CRD

模块分层（简版）

嵌入式模式（Docker 单机）容器内部结构

hiclaw-controller 内部进程树（supervisord 管理）

嵌入式 K8s 的本质：只搬控制面，不搬节点

为什么 kubectl 在容器外不通

关键数据流：建一个 Worker 端到端

稳态通信信道

设计决策与哲学

关键组件深入：Provisioner

与同类对比

演进信号

相关页面

相关页面（来自 frontmatter）

`hiclaw-controller` 内部进程树（supervisord 管理）

为什么 `kubectl` 在容器外不通