HexClaw 架构详解：一个人 + Claude + 5 个月，用 Go 从零构建六仓库全栈开源 AI Agent 生态

去年我想给自己部署一个 AI Agent。

市面上 AI Agent 产品不少，大厂也纷纷入场，但翻来覆去就是这几个问题：

• 开源的不安全——OpenClaw（龙虾）功能最全、社区最大，但安全基本裸奔，成本控制也没有，生产环境不敢上
• 安全的不开源——商业产品合规做得好，但闭源云托管，数据出境不可控，按月付费不便宜
• 能用的不支持国内平台——飞书、钉钉、企微、微信公众号，海外产品基本不覆盖

我需要的是：开源产品的功能广度 + 商业产品的安全等级 + 国内平台全覆盖，同时自托管、单二进制部署。找了一圈没有，就自己造了一个。一个人 + Claude 结对，六个仓库，全栈 AI Agent。这就是 HexClaw（河蟹）。

本文拆解完整架构——技术决策、实现细节、踩过的坑，摊开讲。

开始之前，先对齐几个概念（如果你已经很熟可以跳过）：

LLM = 读过所有书的天才大学生，啥都懂但知识有保质期，偶尔会编（幻觉） RAG = 给这个大学生递小抄，让他引经据典而不是胡编 MCP = 万能 USB 转接头，让大脑和各种工具即插即用 Agent = 全能打工人，能自主规划、调用工具、交付结果 Skills = 打工人的专业技能证书，按需加载 Agent 集群 = 一群打工人组成的团队，分工协作

HexClaw 做的事情，就是把这些概念工程化落地成一个能跑的系统。

关键数字

全景：六仓库、五层架构

                    hexclaw-desktop (Tauri 桌面端)
                    hexagon-ui (观测台)
                          │
                    ┌─────▼─────┐
                    │  hexclaw   │  应用层：适配器、网关、Skill、API
                    └─────┬─────┘
                          │
                    ┌─────▼─────┐
                    │  hexagon  │  AI Agent 框架引擎：ReAct、Workflow、
                    │           │  Plugin、A2A、Graph、Compose
                    └──┬─────┬──┘
                       │     │
                 ┌─────▼──┐  │
                 │ai-core │  │  AI 能力底座：LLM Provider、
                 │        │  │  Embedding、Function Calling
                 └────┬───┘  │
                      │      │
                 ┌────▼──────▼┐
                 │  toolkit   │  通用基础库（最底层，所有 Go 模块依赖）
                 └────────────┘

六个仓库，依赖严格单向自下而上，不允许反向依赖和跨层调用——这是整个生态可复用、可扩展、可独立演进的基础：

• toolkit / ai-core 可以被任何 Go 项目引用，不绑定 HexClaw
• hexagon 作为通用 AI Agent 引擎，可脱离 hexclaw 独立使用，构建完全不同的 Agent 应用
• hexclaw 作为 AI Agent 应用后端，只做应用层编排，新增能力下沉到对应层而非就地实现

为什么选 Go、为什么自研框架？

两个问题一起回答。

语言选择：Agent 的瓶颈是 I/O——等 LLM 响应、等工具执行、等 13 个平台 Webhook。goroutine 比 Python asyncio 高效一个数量级且没有 GIL。部署上，hexclaw serve 一条命令跑，不用折腾虚拟环境。

框架选择：Python 阵营评估过 LangChain/LangGraph（生态最大但受限于 GIL）、CrewAI（上手快但编排偏弱）；Go 阵营评估过 Eino（字节出品，但安全模块缺失）。最终自建——因为 Go 原生 + 企业级安全 + 完整 RAG + 生产级可观测 这个组合，确实没有现成的。

Hexagon 取名自「六边形战士」，聚焦六大维度均衡发展：易用性、性能、扩展性、编排、可观测性、安全。

              Hexagon AI Agent Framework Architecture
              ========================================

  ┌─ Application Layer ────────────────────────────────────────┐
  │  ChatBot    RAG Agent    Workflow    Multi-Agent    Custom  │
  ├─ Orchestration Layer ──────────────────────────────────────┤
  │  Router   Planner   Scheduler   Executor   Graph   State   │
  ├─ Agent Core Layer ─────────────────────────────────────────┤
  │  Agent   Role   Team   Network   Handoff   Context   Msg   │
  ├─ Capability Layer ─────────────────────────────────────────┤
  │  LLM Provider    RAG Engine    Tool System    Memory    KB │
  │  (ai-core)                     (ai-core)      (ai-core)   │
  ├─ Infrastructure Layer ─────────────────────────────────────┤
  │  Tracer    Logger    Metrics    Config    Security   Plugin │
  ├─ Foundation Layer ─────────────────────────────────────────┤
  │  toolkit (lang | crypto | net | cache | util | collection) │
  └────────────────────────────────────────────────────────────┘

3 行代码入门，声明式配置进阶，图编排驾驭复杂场景：

response, _ := hexagon.Chat(ctx, "What is Go?")         // 最简入门

agent := hexagon.QuickStart(                              // 带工具
    hexagon.WithTools(calculator),
    hexagon.WithSystemPrompt("你是一个数学助手"),
)

team := hexagon.NewTeam("research-team",                  // 多 Agent 团队
    hexagon.WithAgents(researcher, writer, reviewer),
    hexagon.WithMode(hexagon.TeamModeSequential),
)

Runnable[I,O]：一个接口统一一切

Python LangChain 中 Agent、Tool、Chain、Retriever 是不同抽象，组合需要胶水代码。Hexagon 的做法更激进：所有组件实现同一个泛型接口，6 种执行范式（Invoke / Stream / Batch / Collect / Transform / BatchStream）。

pipeline := core.Compose(tokenizer, model)    // 自由组合
adapted := core.InvokeToStream(r)              // 自动获得流式能力
fastest := core.Race(future1, future2)         // 竞速取最快

Agent 可以作为另一个 Agent 的工具，RAG 管线可以嵌入图编排节点——因为它们是同一个接口。

与主流框架对比：

核心差异化在安全维度。Eino 在注入检测、PII 脱敏、RBAC、成本控制上完全空白——意味着如果你用 Eino 构建面向用户的 Agent，这些安全能力要自己从零搭建。Hexagon 把它们做成了框架内建能力，开箱即有。

一句话总结：LangChain 的接口思想 + LangGraph 的编排能力 + 企业级安全栈，用 Go 重写。感知层（Agent）→ 执行层（Skills + MCP）→ 知识层（RAG + LLM + Memory）三层全部内建。

十种 Agent + 多 Agent 协作

Agent 的演进从简单到复杂分四个阶段，Hexagon 用 10 种 Agent + 协作协议全部覆盖：

嵌套天然支持——Supervisor 的工人可以是 ReActAgent，ReActAgent 的工具可以触发 PlanExecuteAgent。

协作层面：Team（4 种模式）/ Handoff（Swarm 风格切换）/ Network（Mesh/Hub/Ring/Tree 拓扑）/ Consensus（投票决策）/ Registry（服务发现 + 负载均衡）/ A2A（Google Agent-to-Agent 协议，Go 生态少有）。四层状态管理 + Snapshot/Restore。

图编排引擎

g, _ := graph.NewGraph[MyState]("support").
    AddNode("classify", classifyIntent).
    AddNode("faq", handleFAQ).
    AddConditionalEdge("classify", routerFn, routeMap).
    SetEntryPoint("classify").Build()

条件路由 · 并行执行 · 检查点持久化 · Human-in-the-Loop · 时间旅行 · 子图嵌套 · Pregel BSP · 循环 + 屏障。另有链式编排、工作流引擎、确定性流程（Process，状态机驱动）。

  User ──→ Agent ──→ LLM ──→ Tool ──→ Result
              │
              ├──→ Memory (记忆存取)
              └──→ RAG (知识检索)

RAG 管线：7 环节可插拔

文档 → Loader → Splitter → Embedder → Indexer → Retriever → Reranker → Synthesizer

向量存储 8 后端：Qdrant / FAISS / PgVector / Redis / Milvus / Chroma / Pinecone / Weaviate。

安全体系 + 可观测性

钩子系统覆盖 Run / Tool / LLM / Retriever / Stream 五类事件，位掩码优化避免空调用。hexclaw 的预算控制、工具审批、自动记忆提取全部通过钩子实现，未侵入框架核心。

性能 + 更多能力

另有：OS 级沙箱 · 响应式流处理引擎 · 7 种记忆实现 · MCP Client+Server · 智能文档工作流（ADW）· 确定性流程（Process）。

应用层编排，框架层实现。 hexclaw 不写 Agent 推理——组装 Hexagon 的；不写安全检查——编排 Guard Chain；不写 RAG——配置 RAG Engine。

hexclaw：hexagon 是引擎，hexclaw 是整辆车

【图：HexClaw 应用六层架构】

                    HexClaw Application Architecture
                    ================================

  ┌─ Platform Adapter ──────────────────────────────────────────────┐
  │  Web  飞书  Telegram  钉钉  Discord  Slack  企微  微信          │
  │  WhatsApp  LINE  Matrix  Email  REST API          (共 13 种)    │
  ├─ Security Gateway (6-Layer Pipeline) ───────────────────────────┤
  │  Auth → RateLimit → CostCheck → InputSafety → Permission → Audit│
  ├─ Agent Engine ──────────────────────────────────────────────────┤
  │  ReAct Loop        3D Budget Control     Tool Executor + Hooks  │
  │  Session Manager   Context Compaction    Multi-Agent Router     │
  │  Two-Pass Stream   Tool Approval Gate    Auto Memory Extract    │
  ├─ Capability Layer ──────────────────────────────────────────────┤
  │  Skill System       Knowledge (RAG)      LLM Router             │
  │  (Builtin+Mkt+MCP)  (FTS5+Vector+MMR)   (Cost/Quality/Latency) │
  │  Memory (4-Layer)   Semantic Cache (Singleflight+LRU+TTL)      │
  ├─ Infrastructure ────────────────────────────────────────────────┤
  │  OS Sandbox          MCP Client         Cron + Webhook          │
  │  (Seatbelt/NS/Win)  (stdio/SSE/HTTP)   REST API (71 端点)      │
  │  Canvas (8 组件)     Voice (STT/TTS)    WebSocket 实时流        │
  ├─ Storage & Config ──────────────────────────────────────────────┤
  │  SQLite (WAL)   FTS5 全文搜索   YAML+ENV   Audit JSONL   .md   │
  └─────────────────────────────────────────────────────────────────┘
            Powered by: Hexagon ← ai-core ← toolkit

核心数据流

用户消息 (飞书/Telegram/Discord/微信/...)
  → 平台适配 (Adapter) → 安全网关 (6层) → 会话路由 (Router)
  → Agent 引擎 (ReAct)
      ├─ 快速路径: Skill.Match() → 毫秒级，零 LLM 消耗
      └─ 主路径: ReAct 循环 → 沙箱执行 → 同步/流式返回

六层安全网关

请求 → [Auth] → [RateLimit] → [CostCheck] → [InputSafety] → [Permission] → [Audit] → 引擎

第 3、4 层异常时直接拒绝——宁可给用户看个”服务暂时不可用”，也不能让一个失控的 ReAct 循环把你的 API 余额刷到零。

十三平台适配

统一消息模型 + 4 方法 Adapter 接口，每个适配器 ~150 行。

值得关注的平台特定实现： - 企微：AES-256-CBC 加解密 + 双检锁 Token 缓存 - 微信：5 秒被动回复 + 超时自动切客服异步推送 - Discord：Gateway WebSocket 心跳 + 流式消息编辑 - Web：Origin 白名单仅允许 localhost 和 tauri://localhost

ReAct 引擎

引擎在 Hexagon ReActAgent 之上增加应用层编排（单文件 47KB）：

LoadContext → InjectContext(RAG+记忆) → InjectTools(Skill+MCP, 上限40)
→ ReAct 循环: LLM 推理 → ToolApproval → ToolExecutor → BudgetUpdate
→ AutoMemory → SaveHistory → 返回

3D 原子预算：用三个 atomic.Int64 分别追踪 Token、时长、成本。为什么成本不用 float64？因为 Go 的 atomic 包不支持浮点原子操作，而 Agent 的工具调用是高并发的。解法是把美元乘以一百万存成整数（微美元精度），$0.00004 变成 40——整数原子操作，零锁开销。内置 20+ 模型定价表，支持子 Agent 预算分配与回收。

Two-Pass Streaming：中间轮 Complete()（检测 tool_calls），最终轮 Stream()（打字机效果）。避免为不可见步骤建流连接。流式 goroutine 使用独立 context.Background() 保存消息，防用户关闭页面丢数据。

Hook Chain：TruncateHook 保留 60% 头部 + 20% 尾部 · SanitizeHook 只清洗外部来源 · AuditHook 即使失败也运行。工具缓存 SHA256 key，破坏性工具自动跳过。

Skill 生态（ClawHub）：37 Skill + 38 MCP Server。格式 Markdown + YAML frontmatter，来源：18 原创 + 12 社区适配 + 7 个 OpenClaw playbook 移植。MCP 覆盖 18 品类（文件系统 / GitHub / 搜索 / 浏览器 / 数据库 / Slack / Docker / K8s / AWS 等）。

Go 原生三平台沙箱：2713 行替代 Docker

OpenClaw 等绝大多数竞品的代码执行依赖 Docker。hexclaw 用 2713 行纯 Go 实现内核级隔离：

macOS Seatbelt（与 Claude Code / Codex 同底层）——动态 SBPL 策略，(deny default) 默认拒绝。Docker 容器默认拥有大部分 syscall 权限做不到这一点。

Windows 五层纵深——① Restricted Token（UNTRUSTED_RID 0x0000）→ ② ACL 文件系统隔离 → ③ Job Object（512MB / 10 进程）→ ④ Low Box Token 内核级断网 → ⑤ Alternate Desktop（防 Shatter Attack）。启动 ~50ms / ~5MB，对比 Docker Desktop 500ms-2s。

Linux 五层隔离——① Namespace → ② pivot_root → ③ seccomp → ④ 进程加固 → ⑤ 两阶段 re-exec。不兼容系统自动降级：CLONE_NEWUSER 失败 → Landlock → 兜底 seccomp。

三平台共享 NetPolicy 引擎：黑名单优先 → 端口 → 模式，不可绕过。

沙箱实测对比（Linux）：

知识库 · LLM 路由 · 记忆

知识库：Recursive Split → FTS5 + 向量嵌入 → 混合评分（0.7v + 0.3t）→ 时间衰减 → MMR 去重（3×TopK 候选再筛）→ TopK=3。Embedder 不可用时自动退化为纯 FTS5。

LLM 路由：多 Provider 按策略路由（cost / quality / latency），故障自动降级。语义缓存：Singleflight 防击穿 · TTL ± 10% 抖动防雪崩 · 空值缓存防穿透。

四层记忆：会话上下文 → 每日日记 → MEMORY.md → 语义向量。自动提取：关键词预过滤 → 异步 LLM（15s 超时）→ 注入已有记忆避免重复。超 50 条自动 LLM 压缩。Markdown 格式，人类可读，可 Git 版本控制。

多 Agent 路由 · 自主行为

四种选择机制：UI 直选 · @mention 语法 · 模式自动绑定 · 平台路由规则（UserID +100 > ChatID +50 > Platform +10），兜底 LLM 语义分类。

会议模式：≥2 Agent 围绕结构化话题多轮圆桌讨论——适合竞品分析、头脑风暴、专家辩论。

自主行为：Heartbeat 巡查 + Cron 定时 + Webhook 事件驱动。默认 SQLite WAL，四种部署：桌面 / Docker / systemd / K8s。

hexclaw-desktop：让 AI Agent 像 Docker Desktop 一样”双击即用”

Tauri 壳管理 Go Sidecar

【图：HexClaw Desktop 分层架构】

                  HexClaw Desktop Architecture
                  ============================

  ┌─ Tauri Shell (Rust) ───────────────────────────────────────┐
  │  窗口管理   系统托盘   全局快捷键 ⌘⇧H   单实例   自动更新   │
  │  API 代理 (CORS bypass)          Sidecar 进程生命周期管理   │
  ├─ Vue 3 Frontend (WebView) ─────────────────────────────────┤
  │  ┌──────┬──────┬───────┬──────┬──────┬───────┬──────┐      │
  │  │ 概览 │ 对话 │ Agent │ 知识 │自动化│  集成  │ 日志 │      │
  │  └──────┴──────┴───────┴──────┴──────┴───────┴──────┘      │
  │  Pinia Store       Vue Router       Tauri invoke (IPC)      │
  ├─ Tauri Commands (Rust → Go) ───────────────────────────────┤
  │  proxy_api_request    stream_chat    check_engine_health    │
  ├─────────────────────────────────────────────────────────────┤
  │              HTTP / WebSocket ←→ localhost:16060             │
  ├─ hexclaw serve (Go Sidecar) ───────────────────────────────┤
  │  Agent 引擎 · 安全网关 · LLM 路由 · RAG · MCP · 沙箱       │
  │  ┌─────────────────────────────────────────────────────┐   │
  │  │    Hexagon  ←  ai-core  ←  toolkit                  │   │
  │  └─────────────────────────────────────────────────────┘   │
  └─────────────────────────────────────────────────────────────┘

框架选型：

包体积 8MB vs Electron 150MB（19x），内存 25MB vs 200MB（8x）。

功能模块

原生能力

⌘⇧H 全局唤起 · 系统托盘 · 原生通知 · 剪贴板交互 · 文件拖放上传 · 3 步引导 · Tauri Updater。同一套代码支持 Desktop 和 Headless。安装：curl | bash / Homebrew / DMG / MSI / DEB / AppImage。

和竞品比，到底强在哪？

2025 年底以来，各家密集发布自己的 AI Agent 产品，但大多是云端闭源、面向企业客户。HexClaw 走的是另一条路——开源、自托管、面向开发者和技术团队。下表按品类对比：

踩过的坑和架构取舍

坑 1：Docker 沙箱——“装个聊天助手还要装 Docker？”

早期 Skill 执行依赖 Docker。一般MacBook配置没问题，但 macOS 上 Docker Desktop 额外吃 2-4GB 内存——让用户为了跑个天气查询装 Docker，这不合理。

花一星期 用 Go syscall 重写三平台原生沙箱。2713 行、零依赖、<10ms 启动。隔离强度不如完整容器，但 Skill 执行场景够了。

坑 2：Wails → Tauri——选型翻车的正确姿势

桌面端最初选了 Wails，理由很充分：Go 原生，零集成成本。开发到 60% 发现三个致命问题：不支持多窗口（Quick Chat 浮窗做不了）、系统托盘要第三方库、没有自动更新。

止损切 Tauri v2。Go 后端改为 sidecar，多了一层 HTTP，但恰好复用已有 71 个 API，实际开发成本反而更低。

坑 3：安全网关本来是个”可选配置”

第一版安全层做成中间件，配置文件里 enabled: false 就能关掉。某次 code review 发现：CostCheck 关掉后，失控的 ReAct 循环会无限调 LLM 直到账单爆炸——这不是理论风险，是确定性灾难。

当天重构为 6 层不可绕过管道。开发期经常触发限流，但总比半夜收到 API 账单好。

取舍总结：

接下来做什么

2026 年，AI Agent 赛道从”技术验证”进入”工程化落地”——MCP + A2A 双协议栈成熟，安全与确定性取代了”Demo 跑通就行”的心态。HexClaw 目前 v0.2.x，核心稳定，离”生产级”还有关键缺口：

• 流式升级：当前伪流式（中间轮同步），计划对接 Hexagon Agent 原生 Stream
• Embedding 集成：知识库 Embedder 接口已定义，需对接 LLM Provider
• 测试覆盖率 > 80%：93 个测试文件，覆盖率待提升
• Hub 生态扩充：37 Skill → 100+、38 MCP Server → 80+，补齐代码审查 / 数据分析 / 项目管理
• 多平台桌面打磨：Mac 优先，Windows MSI 和 Linux AppImage 需更多测试

一个开放问题：如何在不牺牲安全的前提下让 Agent 更自主？ Tool Approval 保证了安全但限制了自主性——正在探索基于历史行为的自适应审批策略。这也是整个 AI Agent 行业 2026 年的核心矛盾：从”Demo 跑通”到”生产可信”，安全与自主性的平衡点在哪里？

技术栈

这个项目是我一个人 + Claude 结对开发的，初衷很简单：想给自己用一个安全、好用、不贵的 AI Agent。如果你也有同样的需求，欢迎在 GitHub 搜索 hexclaw 提 Issue / PR，一起玩。

最后一个问题： 你在用 AI Agent 时最头疼的是什么——安全信任、成本控制、还是平台适配？评论区聊聊，这些真实痛点会直接影响 HexClaw 的优先级。

HexClaw 河蟹 AI
本地云端均可部署 · 数据自主掌控 · 软件开源免费
官网 hexclaw.net  |  GitHub hexagon-codes
微博 @HexClaw  |  X @hexclawapp
邮箱：[email protected]