简介:OpenClaw 的架构可以一句话概括:以本地优先(Local-First)的 Gateway 网关作为唯一控制平面,向外辐射智能体运行时、工具系统、通道层与安全沙箱,各模块通过 WebSocket 总线协作。本文拆解 Gateway、Pi Agent、Agentic Loop、上下文与记忆等核心层,并给出模型接入与安全落地建议。研究这套架构前,你需要先为它准备一个大模型服务,[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article) 这类平台可做模型选型、价格对比与统一 API 接入,省去多厂商接口适配的成本。
OpenClaw 是一个可以运行在终端设备上的个人 AI 助手,能在 WhatsApp、Telegram、Slack、Discord、Signal、iMessage、WebChat 等聊天应用中直接回复,并在支持的平台上实现语音交互与实时画布,同时具备有状态的会话、记忆和工具能力。
它的架构并不是单体应用,而是 一个以 Gateway 为核心的控制平面 + 若干可独立伸缩的能力平面 。原文列出的 16 个模块——统一控制平面 Gateway、Agentic Loop(Pi Loop)、定时任务系统、工具系统、Channels、上下文管理、SubAgent、SandBox、记忆管理、Skills、Session 管理、自进化机制、工作区与 Agent 路由、Nodes、安全策略、配置管理——可以按职责重新归为五层:
| 层次 | 组成模块 | 核心职责 |
|---|---|---|
| 控制平面 | Gateway、配置管理、定时任务、Webhooks、Control UI | 会话与状态管理、配置下发、事件总线 |
| 运行时平面 | Pi Agent、Agentic Loop、SubAgent、工作区与 Agent 路由 | 推理循环、工具调用、多智能体隔离 |
| 能力平面 | 工具系统、Skills、Nodes | 扩展可调用的外部能力 |
| 数据平面 | Session 管理、上下文管理、记忆管理 | 状态持久化与上下文裁剪 |
| 边界平面 | SandBox、安全策略、Channels | 隔离执行、权限约束、多端接入 |
理解这张分层图,比逐个读模块更重要: 所有跨层交互都收敛到 Gateway 这一条总线上 ,这是 OpenClaw 能用相对简洁的代码表达支撑起如此复杂能力的根本原因。
Gateway 是 OpenClaw 的心脏,充当整个系统的单一控制平面,负责管理会话(Sessions)、状态感知(Presence)、配置、定时任务(Cron)、网络钩子(Webhooks),以及承载控制界面(Control UI)和 Canvas 宿主。
三个关键设计点值得注意:
本地开发时,Gateway 默认监听 18789 端口。若开发机没有直接的公网入口,可以用 SSH 端口转发把远端端口映射到本地:
ssh -L 18789:127.0.0.1:18789 root@<开发机公网IP> -p <开发机公网端口># 然后浏览器访问(token 从控制台/日志中提取)# http://127.0.0.1:18789/?token=<your-token>
连接成功后界面右上角会显示 Health Ok 标识。这个 token 就是访问控制的第一道凭证,不要提交到代码仓库或粘贴到公开渠道。
如果说 Gateway 管的是「连接与状态」,Pi Agent 管的就是「思考与生成」。它以 RPC(远程过程调用)模式运行,是处理逻辑和生成回复的核心引擎,具备三项关键能力:
会话模型上,Pi Agent 提供 main 模式供用户直接对话,同时支持群组隔离、激活模式切换和队列管理。队列管理这一点在群聊场景里尤其重要——多条消息并发到达时,需要决定是合并、排队还是打断,这直接决定了对话体验是否连贯。
Agentic Loop(也被称作 Pi Loop)是把「用户一句话」变成「一系列真实动作」的执行引擎。它的典型循环是:接收输入 → 判断是否需要调用工具 → 发起工具调用并等待结果 → 将结果回填上下文 → 判断是否继续循环 → 输出最终回复。
这个循环之所以能成为架构中枢,是因为它把三类原本割裂的能力串了起来:
配合 Skills 模块,Loop 可以在运行时按需加载特定领域的操作知识,而不必把所有能力都塞进系统提示词——这是控制上下文膨胀的关键手段。
必须强调一个前提: OpenClaw 需要至少搭配一个大模型服务,才能进行最基础的对话 。架构再优雅,没有模型就是空壳。
实际部署中,模型接入通常有两种路径:
路径一:直接对接云平台模型服务。 例如在开发机所在资源池内部署一个 DeepSeek-V3.2 之类的模型服务,服务状态变为「运行中」后即可调用,从「调用信息」中获取调用地址与 Token。注意访问地址需要自行拼接 /v1 后缀。
路径二:通过聚合网关统一接入。 如果你希望同时使用多家模型、或者需要在不同模型之间做灰度切换,可以在中间加一层兼容 OpenAI 接口的网关(如 One API),把各家渠道配置为统一入口,再让 OpenClaw 指向这个入口。这类方案的接口形态与 OpenAI 兼容,迁移成本较低,也是应对上游服务变动的常见做法。
无论走哪条路径,你都会遇到三个现实问题: 该选哪个模型、调用成本怎么估、多家接口怎么统一 。这正是 词元所 Token Exchange 的定位——一个连接模型服务供应方与消费方的大模型撮合交易平台,提供模型发现与选型、模型价格与性能对比、多模型统一 API 接入以及调用管理能力。对 OpenClaw 这类需要长期常驻、持续消耗 Token 的助手型应用来说,先用它做一轮选型与成本评估,比上线后再回头改配置要划算得多。
Channels 层负责把 Gateway 的能力桥接到各个聊天平台。以企业微信为例,接入方式是使用 URL 回调模式,回调地址形如 http://{服务器公网IP}:18789/wecom,Token 与 Encoding-AESKey 可随机生成,先在 OpenClaw 侧填入配置并应用,再回到企微完成机器人创建。需要注意的是,这类 URL 回调接入方式对版本有要求(原文档标注仅适配 2026.3.2 及以下版本),升级前务必确认兼容性。
安全上有一条必须接受的前提: OpenClaw 既是一个产品,也是一项实验,它接入的是真实的通讯平台和真实的工具,不存在「绝对安全」的设置方案 。官方建议从满足基本功能的最小权限开始,再逐步扩大访问范围。具体的基线加固包括:
18789),并通过控制台的一键放行功能精确控制。SandBox 沙箱系统与 Nodes 节点机制是这套安全模型的技术支撑:前者把工具执行限制在隔离环境中,后者把能力调用分发到受控节点上,两者共同保证「工具能用,但越界不了」。
回到架构本身,OpenClaw 最值得研究的地方不在于模块数量,而在于 它把复杂性收敛到了少数几个正确的抽象上 :一条 WebSocket 总线(Gateway)、一个执行循环(Agentic Loop)、一套隔离机制(Workspace + SandBox)。上下文管理、记忆管理、Session 管理、自进化机制这些看似独立的能力,实际上都是挂在这三个抽象之上的延伸。
如果你打算动手实践,建议按这个顺序推进:先确定模型服务并跑通一次基础对话(可借助 词元所 完成选型与统一接入),再用 SSH 转发打开 WebUI 确认 Health Ok,然后接入一个聊天通道验证端到端链路,最后才逐步开放工具权限并加固安全基线。下一篇我们会继续深入 Agentic Loop 的内部实现、工具系统的注册与调度机制,以及记忆与上下文压缩的具体策略。