OpenClaw底层揭秘：打造私有化AI Agent团队的核心原理与实战解析！-港品优选

本文深入剖析了OpenClaw作为自托管多通道AI Agent网关的底层架构与核心原理。从简洁的Gateway进程设计、JSON over WebSocket的统一通信协议，到Agent循环处理消息的完整流程、多Agent路由的绑定机制，以及精细化的会话管理与独特的Markdown记忆系统，OpenClaw通过简单、隔离、可扩展的设计哲学，为用户提供了强大的本地AI Agent基础设施，实现数据自主与高度可控的智能体协作。

通过上一篇[OpenClaw 搭建多智能体团队：我的实战手记] 我们成功搭建了一套多智能体协作的龙虾团队，接下来我们将深度解析OpenClaw的底层原理。

从技术角度阐述 OpenClaw 是什么？

OpenClaw 是一个自托管的多通道 AI Agent 网关。用一句话概括：它是一个运行在你本地或服务器上的 Gateway 进程，把各种聊天应用（WhatsApp、Telegram、Discord、iMessage、QQ…）和 AI 编程助手（Pi、Claude Code、Codex 等）连接起来。

关键特点：

自托管：数据留在你自己的机器上，不依赖第三方云服务
多通道：一个 Gateway 同时服务多个聊天平台
Agent 原生：内置多 Agent 路由、会话管理、记忆系统和 Skill 扩展机制
开源：MIT 协议，社区驱动

核心架构：一切围绕 Gateway

OpenClaw 的架构极为简洁——一切围绕一个长期运行的 Gateway 进程展开。

Gateway 是唯一的"真相之源"

传统方案中，每个聊天平台可能需要各自独立的 Bot 程序。OpenClaw 反其道而行：只有一个 Gateway 进程，它负责所有聊天平台的连接管理。

WhatsApp 通过Baileys库连接
Telegram 通过grammY连接
Discord、Signal、iMessage 等各有对应实现

Gateway 维护所有 provider 连接，并暴露一个类型化的 WebSocket API，控制面板客户端（macOS App、CLI、Web UI）都通过这个 WS 端口与它通信。

协议设计：JSON over WebSocket

Gateway 与所有客户端之间的通信遵循统一协议：

客户端 → Gateway: { type: "req", id, method, params } Gateway → 客户端: { type: "res", id, ok, payload|error } Gateway → 客户端: { type: "event", event, payload, seq? }

关键设计原则：

第一次握手必须是connect，非法首帧直接关闭连接
具备副作用的方法（send、agent）需要幂等键，Gateway 维护短期去重缓存
Node（移动端/headless）以role: "node"声明身份，并携带自己的 capabilities
本地信任与设备配对

新设备第一次连接需要配对审批，Gateway 会颁发设备令牌供后续连接使用。本地回环地址（loopback/Tailscale）可自动审批，减少同主机上的繁琐确认流程。

Agent 循环：消息如何变成一次回复？

这是理解 OpenClaw 最核心的部分。当你在 QQ 上给 Bot 发一条消息，Gateway 内部发生了什么？

完整流程

用户消息 → Gateway → Agent Loop → 模型推理 → 工具执行 → 流式输出 →回复。

Agent RPC 的执行步骤：

验证参数，解析 session（按 sessionKey 或 sessionId）
持久化 session 元数据，立即返回{ runId, acceptedAt }（不阻塞）
加载 Skills 快照，注入环境变量和 prompt
调用runEmbeddedPiAgent
通过 per-session + global 队列序列化运行，防止 session 竞争
解析模型 + 认证 profile，构建 pi session
订阅 pi 事件，流式推送 assistant delta 和 tool events
subscribeEmbeddedPiSession：桥接 pi-agent-core 事件到 OpenClaw 流
stream: "tool" → 工具调用事件
stream: "assistant" → 模型输出片段
stream: "lifecycle" → 阶段事件（start / end / error）

队列与并发控制

OpenClaw 通过双层队列保证一致性：

per-session 队列：同一会话内的请求串行执行，保证上下文不乱
global 队列：跨 session 的全局序列化（可选）

这解决了两个问题：

避免同一 session 内多条消息同时处理导致历史记录交错
防止工具调用竞争（tool/session races）
Prompt 组装与系统提示词

系统 prompt 不是静态的，而是动态构建的：最终 Prompt = OpenClaw 基础提示词 + Skills 提示词片段 + Bootstrap 上下文文件 + per-run 覆盖参数。

OpenClaw 还会在每次 compaction（上下文压缩）前自动触发一次静默的记忆回写——提醒 Agent 把重要信息写入 MEMORY.md，避免上下文被截断后丢失关键记忆。

多 Agent 路由：一人多用，各司其职

OpenClaw 支持在同一 Gateway 中运行多个完全隔离的 Agent。

什么是"一个 Agent"？

每个 Agent 有自己独立的：

-Workspace：文件系统中的工作目录（含 `SOUL.md`、`AGENTS.md`、`USER.md` 等人格定义文件） -State 目录（`agentDir`）：认证凭证、模型注册表、per-agent 配置 -Session 存储：聊天历史，按 `~/.openclaw/agents/<agentId>/sessions/` 组织

绑定（Binding）机制

Inbound 消息如何路由到正确的 Agent？

靠的是绑定规则：

{ "bindings": [ { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } }, { "agentId": "work", "match": { "channel": "whatsapp", "accountId": "biz" } } ] }

匹配优先级：最具体者优先（peer > parentPeer > guildId > accountId > channel > fallback）

实际场景示例
场景一：WhatsApp + Telegram 分流
- WhatsApp → 快速日常助手（Sonnet 模型）
- Telegram → 深度工作助手（Opus 模型）
场景二：家庭共享一个 Gateway
- 爸爸的 DM → Agent A（家庭助手 persona）
- 妈妈的 DM → Agent B（家庭助手 persona，但独立记忆）
- 家庭群组 → 专用 Family Bot（限制工具权限）

会话管理：Session 的艺术

OpenClaw 的会话管理非常精细，可通过dmScope配置 DM 的隔离级别：

四种隔离模式

模式	行为	适用场景
`main（默认）`	所有 DM 共享一个主会话，延续性最好	单人使用
`per-peer`	按发送者 ID 隔离（跨通道）	跨平台同一用户
`per-channel-peer`	按「通道 + 发送者」隔离（推荐）	多用户场景
`per-account-channel-peer`	按「账号 + 通道 + 发送者」隔离	多账号最优

安全陷阱与修复

⚠️安全提醒：如果你的 Bot 接收多人的 DM，默认的main模式会让所有人共享同一个上下文！建议切换到per-channel-peer。

问题场景：

Alice 刚和 Agent 聊了私人医疗预约
Bob 接着问 Agent：“我们刚才聊什么呢？”
由于共享 session，Agent 可能用 Alice 的上下文回答 Bob

修复方案：

修改：// ~/.openclaw/openclaw.json 文件配置 {session: {dmScope: "per-channel-peer"}}

会话生命周期管理

OpenClaw 支持灵活的会话重置策略：

-每日重置：默认每天凌晨 4 点（Gateway 主机本地时间）重置会话

-空闲重置：idleMinutes配置滑动空闲窗口，两者都配置时以先到期的为准

-手动重置：/new或/reset命令强制开启新会话

{ session: { reset: { mode: "daily", atHour: 4, idleMinutes: 120, // 空闲2小时也重置 }, resetTriggers: ["/new", "/reset"], }, }

会话存储结构

~/.openclaw/agents/<agentId>/ ├── sessions/ │ ├── sessions.json # 会话索引（key → 元数据） │ └── <SessionId>.jsonl # 逐条聊天记录（可人类阅读） └── agent/ └── auth-profiles.json # per-agent 认证凭证

💡提示：JSONL 格式的会话记录可以直接用文本编辑器打开查看，方便调试和复盘。

会话维护与清理

OpenClaw 会话存储支持自动维护，防止磁盘空间无限膨胀：

参数	默认值	说明
`mode`	`warn`	`warn`报告 /`enforce`执行
`pruneAfter`	`30d`	超过此时间的会话标记为可清理
`maxEntries`	`500`	最大会话条目数上限
`rotateBytes`	`10mb`	sessions.json 超过此大小则轮转

生产环境建议开启强制模式：

{ session: { maintenance: { mode: "enforce", pruneAfter: "45d", maxEntries: 800, }, }, }

记忆系统：Markdown 即记忆

OpenClaw 的记忆方案非常独特——直接用 Markdown 文件作为记忆载体，而不是依赖向量数据库或黑盒存储。

双层记忆架构

Workspace（工作空间） ├── MEMORY.md ← 长期记忆（ curated，精简持久） └── memory/ ├── 2026-03-30.md ← 每日日志（ 当天 + 昨天，自动读取） ├── 2026-03-29.md └── 2026-03-28.md

MEMORY.md——长期记忆

人工筛选后的核心信息：身份、偏好、重大决策
只在**私人主会话**中加载（安全考虑，不在群聊中泄露）
需要持久化的内容应该**主动要求写入**这里

memory/YYYY-MM-DD.md——每日日志**

追加写入，当天发生了什么、做了什么
每次启动时自动读取「今天 + 昨天」两份日志
轻量，不需要刻意维护

记忆工具

OpenClaw 暴露两个记忆工具：

-memory_search：语义搜索，跨日期检索相关内容

-memory_get：精确读取某个文件的指定行范围

两个工具都优雅处理文件不存在的情况——比如当天日志第一天写，不会报错。

Compaction 前的自动记忆回写

当会话上下文快要触发自动压缩（compaction）时，OpenClaw 会静默触发一次 agentic turn，提醒模型把重要信息写入磁盘：

{ agents: { defaults: { compaction: { reserveTokensFloor: 20000, memoryFlush: { enabled: true, softThresholdTokens: 4000, prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.", }, }, }, }, }

这保证了上下文可以被压缩，但记忆不会丢失。

向量语义搜索（可选）

OpenClaw 支持对记忆文件构建向量索引，实现语义搜索：

默认 provider：Remote embeddings（OpenAI / Gemini / Voyage / Mistral 等）
本地模式：使用node-llama-cpp加载 GGUF 模型，无需 API key
支持 **混合搜索**：向量相似度 + BM25 关键词双路召回，结果更准确

混合搜索的典型场景：

向量：「Mac Studio 网关主机」≈「运行 Gateway 的机器」（语义相似）
BM25：精确命中memorySearch.query.hybrid等代码符号或 ID

时间衰减（Temporal Decay）：近期记忆得分更高，半衰期默认 30 天。防止半年前写的笔记因为语义匹配好而一直排在前面。

记忆设计的哲学

为什么用 Markdown 而不是向量数据库？

1.人类可读：随时打开文件看 AI 记住了什么，没有黑盒

2.可控：Agent 可以主动读写，不需要额外的索引维护

3.持久化：文件在，记忆就在；删了文件，记忆就消失——符合直觉

4.安全：不在群聊中泄露私人记忆（MEMORY.md只在主会话加载）

工具生态：Skills 与 Hooks

OpenClaw 的扩展性通过两套机制实现：

Skills（技能包）

Skills 是预置的能力模板，位于 workspace 的skills/目录或全局~/.openclaw/skills/。

每个 Skill 有一个SKILL.md定义使用场景和工具接口。

内置 Skills 包括：

-github：GitHub 操作（Issues、PRs、CI）

-weather：天气查询

-coding-agent：代理编码任务到 Codex/Claude Code

-qqbot-channel/qqbot-cron：QQ 频道管理

Hooks（钩子）

OpenClaw 支持在 Agent 循环的多个节点插入自定义逻辑：

Hook	时机
`before_model_resolve`	模型解析之前
`before_prompt_build`	Prompt 构建之前（可注入上下文）
`before/after_tool_call`	工具调用前后
`agent_end`	Agent 运行结束（可审查/修改结果）
`session_start/end`	会话生命周期边界

最后唠两句

为什么AI大模型成为越来越多程序员转行就业、升职加薪的首选

很简单，这些岗位缺人且高薪

智联招聘的最新数据给出了最直观的印证：2025年2月，AI领域求职人数同比增幅突破200% ，远超其他行业平均水平；整个人工智能行业的求职增速达到33.4%，位居各行业榜首，其中人工智能工程师岗位的求职热度更是飙升69.6%。

AI产业的快速扩张，也让人才供需矛盾愈发突出。麦肯锡报告明确预测，到2030年中国AI专业人才需求将达600万人，人才缺口可能高达400万人，这一缺口不仅存在于核心技术领域，更蔓延至产业应用的各个环节。

那0基础普通人如何学习大模型？

深耕科技一线十二载，亲历技术浪潮变迁。我见证那些率先拥抱AI的同行，如何建立起效率与薪资的代际优势。如今，我将积累的大模型面试真题、独家资料、技术报告与实战路线系统整理，分享于此，为你扫清学习困惑，共赴AI时代新程。

我整理出这套 AI 大模型突围资料包【允许白嫖】：

✅从入门到精通的全套视频教程
✅AI大模型学习路线图（0基础到项目实战仅需90天）
✅大模型书籍与技术文档PDF
✅各大厂大模型面试题目详解
✅640套AI大模型报告合集
✅大模型入门实战训练

这份完整版的大模型 AI 学习和面试资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】

①从入门到精通的全套视频教程

包含提示词工程、RAG、Agent等技术点

② AI大模型学习路线图（0基础到项目实战仅需90天）

全过程AI大模型学习路线

③学习电子书籍和技术文档

市面上的大模型书籍确实太多了，这些是我精选出来的

④各大厂大模型面试题目详解

⑤640套AI大模型报告合集

⑥大模型入门实战训练

如果说你是以下人群中的其中一类，都可以来智泊AI学习人工智能，找到高薪工作，一次小小的“投资”换来的是终身受益！

应届毕业生‌：无工作经验但想要系统学习AI大模型技术，期待通过实战项目掌握核心技术。

零基础转型‌：非技术背景但关注AI应用场景，计划通过低代码工具实现“AI+行业”跨界‌。

业务赋能 ‌突破瓶颈：传统开发者（Java/前端等）学习Transformer架构与LangChain框架，向AI全栈工程师转型‌。

👉获取方式：
有需要的小伙伴，可以保存图片到wx扫描二v码免费领取【保证100%免费】🆓

企业官网建设流程全解析

Gateway 是唯一的"真相之源"

协议设计：JSON over WebSocket

最后唠两句

那0基础普通人如何学习大模型？

①从入门到精通的全套视频教程

② AI大模型学习路线图（0基础到项目实战仅需90天）

③学习电子书籍和技术文档

④各大厂大模型面试题目详解

⑤640套AI大模型报告合集

⑥大模型入门实战训练

热门文章

文章分类

标签云

需要专业的网站建设服务？

企业官网建设流程全解析

Gateway 是唯一的"真相之源"

协议设计：JSON over WebSocket

最后唠两句

那0基础普通人如何学习大模型 ？

①从入门到精通的全套视频教程

② AI大模型学习路线图（0基础到项目实战仅需90天）

③学习电子书籍和技术文档

④各大厂大模型面试题目详解

⑤640套AI大模型报告合集

⑥大模型入门实战训练

热门文章

文章分类

标签云

相关文章

Keil中sprintf和自定义Serial_Printf，哪个更适合你的串口打印需求？

【AI Agent数据分析实战指南】：20年专家亲授5大落地场景、3类避坑红线与实时决策增效方案

用STM32F103C8T6+L298N+蓝牙，手把手教你做个带PID调速的智能小车电机驱动（附完整代码）

需要专业的网站建设服务？

那0基础普通人如何学习大模型？