GoClaw 调研笔记

January 1, 2020

本文为 GoClaw 开源项目的调研笔记。GoClaw 是用 Go 语言编写的多租户 AI Agent 网关，是 OpenClaw 的 Go 重写版，在安全性、性能和可运维性上做了深度改进。

开源地址：https://github.com/nextlevelbuilder/goclaw

官方网站：https://goclaw.sh / 文档：https://docs.goclaw.sh

当前版本：v0.5.0（2026 年 3 月）+ v3 架构重构（2026 年 4 月）

这篇文章说了什么

GoClaw 是 OpenClaw 的 Go 重写版——把原来基于 Node.js 的 AI Agent 网关用 Go 重写为 ~25MB 的单一静态二进制，启动 <1s，能在 $5 VPS 上运行。它连接 LLM 和真实世界：用户可以通过 Telegram、Discord、Slack、WhatsApp、飞书、Zalo 等 7 个即时通讯渠道跟 AI Agent 对话，Agent 背后能调用 30+ 内置工具。

GoClaw 最核心的差异化卖点是企业级安全：5 层安全防护（限流 → 注入检测 → SSRF 防护 → Shell 模式拦截 → AES-256-GCM 加密），PostgreSQL Row-Level Security 实现数据库层的多租户隔离，这是其他 Agent 框架很少做到的。

2026 年 4 月推出的 v3 架构重构引入了 8 阶段 Agent 流水线（context → history → prompt → think → act → observe → memory → summarize）、3 级记忆系统（工作记忆 → 情景记忆 → 语义记忆）、知识库（Wiki 链接 + 混合搜索）和自进化系统，把 GoClaw 从小型 Agent 网关升级为完整的企业 AI Agent 平台。

有意思的是，GoClaw 还提供 Desktop Lite 版——用 SQLite 替代 PostgreSQL，打包成原生桌面应用（Wails + React），不开 Docker 不开数据库就能在本地跑 Agent。

观后感

Go 语言做 Agent 网关是一个被低估的选择：单二进制、零依赖、启动 <1s、goroutine 原生并发——运维体验比 Python/Node.js 好太多
多租户是 AI Agent 平台化的前提：如果每个用户/组织的 agent 数据不能隔离，就永远只能做单用户玩具
v3 的 8 阶段流水线是成熟 Agent 架构的范本，每个阶段可插拔，值得学习
自进化（Self-Evolution）这个想法很大胆——Agent 收集自己的指标 → 分析改进建议 → 自动调整，虽然加了 guardrail 只允许改风格和能力描述，不改身份和核心目的
CC BY-NC 4.0 许可证意味着商用需要单独授权，这是一个需要注意的点
1500+ commits 但项目才 3 个月——迭代速度极快

一、项目背景与定位

1.1 从 OpenClaw 到 GoClaw

GoClaw 是 OpenClaw 的 Go 重写版。OpenClaw 基于 Node.js 生态，在 Agent 网关领域有一定知名度（支持 23+ 渠道、35+ 模型），但存在几个痛点：

Node.js 运行时依赖重，冷启动慢（>5s）
安全性不够精细（CVE-2026-25253 漏洞暴露了 40K+ 实例）
缺少原生的多租户支持
并发模型受限（单线程事件循环）

GoClaw 的解决方案：用 Go 重写并在安全性和多租户上做深度改进。

维度	OpenClaw	GoClaw
语言	TypeScript/Node.js	Go 1.26
二进制大小	28MB + Node 运行时	~25MB 单一静态二进制
启动时间	>5s	<1s
多租户	无	PostgreSQL RLS 原生隔离
安全	基础	5 层防护 + CVE 修复
并发	单线程事件循环	Goroutine 原生并发
许可证	开源	CC BY-NC 4.0（非商用）

1.2 定位

GoClaw 的定位是一个企业级 AI Agent 网关，它不是 Agent SDK（不像 DeepAgents），也不是 Agent 产品（不像 DeerFlow），而是一个连接 LLM 与通讯渠道的中间层——用户在 Telegram/Discord 里说话，GoClaw 路由给对应的 Agent，Agent 调 LLM 处理后再通过渠道返回。

它解决的核心问题是："我有一个 AI Agent，怎么让团队/客户通过日常用的通讯工具跟它交互，同时保证数据安全？"

二、8 阶段 Agent 流水线（v3）

v3 架构的核心创新：把 Agent 的执行过程标准化为 8 个可插拔的阶段：

context → history → prompt → think → act → observe → memory → summarize

2.1 各阶段职责

阶段	职责	关键技术
context	组装上下文：加载 System prompt、Bootstrap 文件（SOUL.md、IDENTITY.md、USER.md）、当前会话信息	多文件拼接，字符限制截断
history	加载对话历史，区分不同 session，处理多轮对话	Session key 路由
prompt	构建最终发给 LLM 的完整 prompt，支持 4 种模式	Section gating + Cache boundary 优化
think	LLM 推理调用，支持 extended thinking / reasoning	Anthropic 原生 SSE + Prompt Caching
act	执行 LLM 返回的 tool calls	30+ 工具 + MCP + 自定义工具
observe	观察工具执行结果，决定是否继续 think-act 循环	结果注入 context
memory	从对话中提取记忆，3 级记忆更新	内存刷新 + Consolidation worker
summarize	对话过长时自动压缩历史	Mid-loop compaction（>75% 触发）

2.2 四种 Prompt 模式

Full Mode（完整模式）     → 加载所有 bootstrap 文件 + 完整历史
Task Mode（任务模式）     → 精简 prompt，聚焦当前任务
Minimal Mode（最小模式）  → 仅必要的上下文
None Mode（无 prompt 模式） → 不注入 system prompt

支持 per-agent 和 per-session 粒度切换，自动根据上下文窗口使用率动态降级。

2.3 Prompt Caching

利用 Anthropic 的 prompt caching 机制，在重复调用时缓存 system prompt 和 bootstrap 文件，最高可节省 90% 的 API 成本。

v3 新增了 cache-boundary markers，精确控制哪些内容进缓存、哪些不进——system prompt 天然可缓存，对话历史不可缓存。

三、3 级记忆系统

3.1 记忆层级

L0 — 工作记忆（Working Memory）
    │  当前会话的对话历史，实时读写
    ▼
L1 — 情景记忆（Episodic Memory）
    │  会话摘要，由 consolidation worker 异步生成
    ▼
L2 — 语义记忆（Semantic Memory）
    │  知识图谱，实体-关系抽取 + pgvector 向量搜索
    ▼
  持久化存储（PostgreSQL）

3.2 Consolidation Workers

后台异步运行的 Worker 负责把对话"消化"成结构化记忆：

Episodic Worker：生成会话摘要
Semantic Worker：从对话中提取实体和关系，构建知识图谱
Dreaming Worker：从记忆中提炼更抽象的洞察（类似"回顾和反思"）
Dedup Worker：去重，避免记忆冗余

3.3 记忆刷新（Memory Flush）

当会话 token 使用率超过阈值（默认 75%）时，自动触发：

把近期对话冲洗到记忆系统
调用 LLM 生成压缩摘要
用摘要替换原始对话历史（保留最后几条消息）

四、知识库（Knowledge Vault）

4.1 核心概念

GoClaw 的 Knowledge Vault 是一个文档注册中心 + 双向链接 + 混合搜索系统：

文档（Document）
  ├── [[wikilink]] 双向链接，形成文档网络
  ├── LLM 自动摘要（每个文档入库时自动生成）
  ├── 语义自动链接（vault enrich worker 自动发现相关文档）
  └── FTS（全文搜索）+ pgvector（语义搜索）混合检索

4.2 文件系统同步

Vault 与磁盘文件保持同步，修改磁盘上的 Markdown 文件后 Agent 自动感知。这让 Agent 可以：

把研究成果持久化到 Vault
通过 [[wikilinks]] 在文档间建立关联
后续对话中检索之前积累的知识

五、Agent 团队与编排

5.1 Agent 类型

类型	说明	适用场景
Open Agent	每个用户有独立的对话历史和 USER.md	个人助手
Predefined Agent	所有用户共享核心 personality，仅 USER_PREDEFINED.md 按用户区分	固定角色的 Bot（FAQ、客服）

5.2 委托（Delegation）机制

三种委托模式：

模式	行为	适用场景
Sync	父 Agent 等待子 Agent 完成后继续	需要结果的任务
Async	父 Agent 派发任务后不等待	通知、日志类任务
Bidirectional	父子之间可以双向通信	复杂协作

委托通过 Agent Link（显式的权限链接）建立，配合 BatchQueue[T] 实现并行任务等待。

5.3 编排模式

Auto（自动）    → Agent 自己决定何时 delegation（默认）
Explicit（显式） → 用户显式指定 delegation 策略
Manual（手动）  → 用户在 Dashboard 手动管理任务

5.4 Summoning（召唤）

一个有趣的创新：用 LLM 根据一段自然语言描述自动生成一个新 Agent 的 personality 文件（SOUL.md、IDENTITY.md、USER.md）。

流程：

用户输入 Agent 描述（比如"一个擅长 Python 代码审查的 Agent"）
后台触发 Summoning → Agent 状态变为 summoning
LLM 生成 personality 文件
Agent 状态变为 active

六、安全体系

GoClaw 的核心卖点，5 层防护：

Layer 1: Rate Limiting（限流）
    │  IP 级别 + API key 级别 + 全局限流
    ▼
Layer 2: Injection Detection（注入检测）
    │  Prompt injection + SQL injection 检测
    ▼
Layer 3: SSRF Protection（SSRF 防护）
    │  防止 Agent 通过 web_fetch 访问内网资源
    ▼
Layer 4: Shell Deny Patterns（Shell 拦截）
    │  禁止 Agent 执行危险的 Shell 命令
    ▼
Layer 5: AES-256-GCM Encryption（加密）
    │  API key、敏感配置加密存储
    ▼
  PostgreSQL Row-Level Security（数据库级隔离）

6.1 多租户隔离

PostgreSQL RLS 策略确保每个 tenant 的数据（会话、记忆、Agent 配置、API key）在数据库层面隔离，不是应用层判断，而是数据库强制执行。

6.2 API Key 管理

两种认证方式：

Gateway Token：配置在 config.json 中，拥有完整管理员权限
API Key：格式 goclaw_ + 32 个十六进制字符，存储在数据库中（SHA-256 哈希 + AES-256-GCM 加密），支持权限范围控制

6.3 凭据擦除

Agent 的工具输出中包含服务器 IP、API key 等敏感信息时，自动擦除（credential scrubbing）。这是一个很多 Agent 框架忽略的细节——工具返回的错误信息可能泄露基础设施信息。

七、渠道系统

7.1 支持的渠道

渠道	特点
Telegram	Forum topics 支持、STT 语音转文字、Bot 命令、群聊
Discord	多服务器、频道管理
Slack	企业 IM 集成
飞书/Lark	流式消息、媒体附件（图片/文件）、@mention 解析
Zalo OA	越南主流 IM 的公众号模式
Zalo Personal	Zalo 个人号模式
WhatsApp	原生（非 Business API）
WebSocket	自定义客户端，支持 v3 RPC 协议

7.2 配对（Pairing）系统

多用户、多群组场景下的 Agent 绑定管理：

一个 Agent 可以绑定到多个 Telegram 群组
不同群组可以有不同的话题（topic）设置
Per-channel workspace isolation（每个渠道独立的工作空间）

八、工具系统

8.1 内置工具（30+）

类别	工具	说明
文件系统	`read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`	虚拟 FS 路由
运行时	`exec`, `browser`	Shell 执行 + 浏览器自动化
网页	`web_search`, `web_fetch`	Brave/DuckDuckGo 搜索 + 内容提取
记忆	`memory_search`, `memory_get`, `knowledge_graph_search`	3 级记忆 + 知识图谱遍历
媒体	`create_image`, `create_audio`, `tts`	多提供商图片/音频生成
Skills	`skill_search`, `use_skill`	BM25 + 语义混合搜索
团队	`spawn`, `delegate`, `team_tasks`	子 Agent + 任务板
自动化	`cron`, `heartbeat`	定时任务 + 心跳监控

8.2 MCP 集成

支持 Model Context Protocol，可以把外部 MCP Server 暴露的工具桥接为 Agent 的工具。支持 stdio、SSE、HTTP 三种传输方式。

8.3 自定义工具

运行时加载自定义工具——不需要改源代码或重新编译。工具定义通过命令行模板渲染，支持加密的环境变量。

九、自进化系统（Self-Evolution）

GoClaw v3 的一个创新特性——Agent 能自我优化：

指标收集（Metrics Collection）
    │  收集 Agent 的对话质量、用户反馈、任务完成率
    ▼
建议分析（Suggestion Analysis）
    │  分析指标，生成改进建议（"沟通风格太正式了"、"技术解释可以更深入"）
    ▼
自动调整（Auto-Adaptation）
    │  在 guardrails 限制下自动修改 SOUL.md / CAPABILITIES.md
    ▼
  不能改的：Agent 的身份、名称、核心目的
  可以改的：沟通风格、专业知识描述

这个设计让预定义 Agent 在长期运行中越用越好（前提是 guardrails 足够严格）。

十、Desktop Lite 版

GoClaw 还提供了一个桌面版本，面向单用户场景：

维度	Lite（Desktop）	Standard（Server）
数据库	SQLite	PostgreSQL
Agent 数量	最多 5	无限制
Teams	最多 1 个（5 人）	无限制
记忆搜索	FTS5 文本	pgvector 语义
通讯渠道	无	7 个
知识图谱	无	完整
多租户	无	完整
安装方式	curl 一键脚本	Docker / 源码

桌面版使用 Wails v2 + React 构建为原生 .app/.exe，~30MB，SQLite 数据库零配置。

十一、Hooks 系统

7 个生命周期事件，支持同步和异步 HTTP 回调：

Hook 事件	触发时机
`SessionStart`	新会话开始
`UserPromptSubmit`	用户提交消息
`PreToolUse`	工具执行前
`PostToolUse`	工具执行后
`Stop`	Agent 停止
`SubagentStart`	子 Agent 启动
`SubagentStop`	子 Agent 完成

每个 Hook 都有独立的超时、重试和 SSRF 防护，支持审计日志。Hooks 可以用来做 Quality Gates——比如 PreToolUse 检查工具参数是否合法，不合法就拦截。

十二、部署与运维

12.1 部署方式

# 方式 1：Docker Compose（推荐生产）
git clone https://github.com/nextlevelbuilder/goclaw.git
./prepare-env.sh
make up    # 启动所有服务

# 方式 2：单二进制
go install github.com/nextlevelbuilder/goclaw@latest
goclaw onboard    # 交互式配置向导
./goclaw

# 方式 3：Desktop Lite（Mac）
curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install-lite.sh | bash

12.2 可选服务

服务	Flag	用途
Headless Chrome	`WITH_BROWSER=1`	浏览器自动化、截图
OpenTelemetry	`WITH_OTEL=1`	LLM 调用追踪
Docker Sandbox	`WITH_SANDBOX=1`	隔离的代码执行环境
Redis	`WITH_REDIS=1`	缓存
Tailscale	`WITH_TAILSCALE=1`	私有网络暴露

12.3 可观测性

内置 LLM 调用追踪（spans + prompt cache 指标）
OpenTelemetry OTLP 导出
Web Dashboard 可视化 Agent、渠道、Vault、追踪

十三、与其他 Agent 网关的对比

维度	GoClaw	DeepAgents	DeerFlow
定位	AI Agent 网关（连接 LLM + 渠道）	Agent Harness SDK	Agent 产品平台
语言	Go	Python	Python + Node.js
二进制	单二进制 ~25MB	pip install	Docker / 本地
通讯渠道	7 个（IM 集成）	无	无
多租户	✅ PostgreSQL RLS	❌	❌
安全	5 层 + CVE 修复	基础权限控制	沙箱隔离
部署难度	低（单二进制）	中（LangSmith 部署）	中（Docker）
许可证	CC BY-NC 4.0	MIT	MIT

十四、核心经验总结

Go 语言是做 Agent 网关的理想选择：单二进制部署、零运行时依赖、goroutine 原生并发——运维复杂度降了一个数量级
多租户要从数据库层做起：应用层的 if user_id == x 判断不靠谱，PostgreSQL RLS 才是真正隔离
8 阶段流水线是 Agent 架构的成熟范本：把 context→think→act→observe→memory→summarize 标准化为可插拔阶段，每个阶段独立优化
Agent 的记忆不应该是简单的聊天记录：3 级记忆（工作→情景→语义）更接近人类的记忆模型，能让 Agent 真正"学到东西"
安全性不能是事后补丁：5 层安全防护 + 凭据自动擦除 + 数据库隔离——这些应该在设计阶段就考虑
CC BY-NC 许可证是双刃剑：阻止了商用滥用，但也限制了企业采用。如果需要商用，需要联系官方获取授权
Desktop Lite 版降低了体验门槛：不开 Docker、不配数据库就能跑 Agent，对个人用户和评估者非常友好

这篇文章说了什么​

观后感​

一、项目背景与定位​

1.1 从 OpenClaw 到 GoClaw​

1.2 定位​

二、8 阶段 Agent 流水线（v3）​

2.1 各阶段职责​

2.2 四种 Prompt 模式​

2.3 Prompt Caching​

三、3 级记忆系统​

3.1 记忆层级​

3.2 Consolidation Workers​

3.3 记忆刷新（Memory Flush）​

四、知识库（Knowledge Vault）​

4.1 核心概念​

4.2 文件系统同步​

五、Agent 团队与编排​

5.1 Agent 类型​

5.2 委托（Delegation）机制​

5.3 编排模式​

5.4 Summoning（召唤）​

六、安全体系​

6.1 多租户隔离​

6.2 API Key 管理​

6.3 凭据擦除​

七、渠道系统​

7.1 支持的渠道​

7.2 配对（Pairing）系统​

八、工具系统​

8.1 内置工具（30+）​

8.2 MCP 集成​

8.3 自定义工具​

九、自进化系统（Self-Evolution）​

十、Desktop Lite 版​

十一、Hooks 系统​

十二、部署与运维​

12.1 部署方式​

12.2 可选服务​

12.3 可观测性​

十三、与其他 Agent 网关的对比​

十四、核心经验总结​