x00 概要

OpenClaw 应该有几十万行代码，阅读理解起来难度过大，因此，本系列通过Nanobot来学习 OpenClaw 的特色。

Nanobot是由香港大学数据科学实验室(HKUDS)开源的超轻量级个人 AI 助手框架，定位为"Ultra-Lightweight OpenClaw"。其核心定位如下，非常适合学习Agent架构：

  • 超轻量：核心代码仅约 4,000 行，比 Clawdbot 的 43 万行代码少 99%
  • 设计哲学：微内核架构 + 极致可读性
  • 功能定位：个人AI助手，支持多平台接入
  • 研究友好：代码清晰易读，易于理解、修改和扩展
  • 快速启动：最小化占用意味着更快的启动速度和更低的资源消耗
  • 即开即用：一键部署即可使用

注：本系列借鉴的文章过多，可能在参考文献中有遗漏的文章，如果有，还请大家指出。

0x01 OpenClaw 基础

我们首先来看看 OpenClaw 的基础概念，能让我们在后续利用 Nanobot 学习更加顺利。

OpenClaw 是 Harness，是面向个人与本地场景的、开箱即用的 Agent Harness 框架。它不生产模型，而是把模型 “套上马具”，让模型能稳定、安全、自主地在本地执行真实任务。或者说，OpenClaw 是 Agent 中"不是 AI 的部分"，而 Agent 的实际"聪明程度"完全取决于背后接入的语言模型。

1.1 Harness

智能体 = 模型 + 控制壳（Harness）。

Harness 是包裹在 LLM 之外、负责让 Agent 稳定、可控、可落地执行任务的全套基础设施层，模型提供智能，控制壳让智能变得可用。或者说，Harness 是 Agent 在特定领域工作所需要的一切：Harness = (推理·上下文·记忆·状态) + (工具·编排·闭环) + Knowledge + Observation + Action Interfaces + Permissions，即：智能管理层 + 执行调度层 + 领域知识层 + 反馈观测层 + 安全权限层：

  • Tools: 文件读写、Shell、网络、数据库、浏览器
  • Knowledge: 产品文档、领域资料、API 规范、风格指南
  • Observation: git diff、错误日志、浏览器状态、传感器数据
  • Action: CLI 命令、API 调用、UI 交互
  • Permissions: 沙箱隔离、审批流程、信任边界、安全护栏、权限控制、错误处理

1.2 OpenClaw

OpenClaw 的架构与能力完全符合 Harness 的定义，是 Harness 在个人场景的落地：

  • OpenClaw 是 Agent 中"不是 AI 的部分"。它负责记忆管理、任务调度、工具执行、信道路由，而 Agent 的实际"聪明程度"完全取决于背后接入的LLM。
  • 模型做决策。OpenClaw 执行。模型做推理。OpenClaw 提供上下文。模型是驾驶者。OpenClaw 是载具。
Harness 核心能力 OpenClaw 对应实现
模型无关的执行层 不绑定模型，统一接口对接各类 LLM
任务编排与执行闭环 自然语言→拆解→工具调用→反馈→持久化
工具 / 系统调用管控 本地 Shell、文件、浏览器、API 调用网关
上下文与记忆管理 会话记忆、长期偏好、跨会话状态持久化
安全与护栏 权限控制、操作审计、本地数据隔离
可扩展生态 ClawHub 技能市场、插件化扩展

1.3 OpenClaw 架构

OpenClaw 的架构可以概括为一个以Gateway(网关)为核心的控制平面的分布式系统，OpenClaw 的核心不是模型，而是网关（Gateway）。

OpenClaw 本质上是一个围绕集中式控制平面构建的、事件驱动的、会话隔离的单写入状态机，其整体架构是以网关为中心的星型拓扑：

  • Gateway 是流量调度器、唯一事实来源和控制平面，负责接收来自四面八方的各类事件并进行处理路由、排队、状态管理，然后才去调用 LLM。
  • 智能体运行时（agent runtime）是负责“思考与执行”的工作单元，能够执行“轮次操作”：调用大语言模型、使用工具、写入状态，并回复。

下面两个图可以展示其架构。

1.3.1 OpenClaw 精简架构 1

OpenClaw 精简架构-1

1.3.2 OpenClaw 精简架构 2

OpenClaw 精简架构-2

1.4 关键组件

OpenClaw 的关键组件如下：

  • Channels(频道 / 用户接入层)：

    • OpenClaw 不构建自己的 UI，而是把现有通讯渠道（WhatsApp、Telegram、Slack、Discord）作为交互层。每个渠道有不同的能力和约束，Agent 的行为要适应渠道特性。
    • OpenClaw 把每个平台（Telegram/Discord/Signal 等）都抽象成同一套 ChannelPlugin 适配器合同。核心系统不需要知道“某个平台的私有细节”，只要按统一接口调用即可。账号生命周期由 ChannelManager 统一管理。
    • Channels 负责多渠道统一接入,消息格式转换，核心功能是：监听各渠道消息，统一消息格式，用户身份识别，消息路由分发。消息从各个Channel进入时不会被同步阻塞，而是通过回调把事件推送进系统。Channel接入层只负责把“新消息、连接变化、错误”等信号变成统一的异步事件，再交给后续处理链路，从源头保证高并发和低耦合。
    • Channels是OpenClaw进行社交生态连接最重要的设计，它将AI能力真正注入到了用户的社交与工作动线中。这对产品设计的影响是深远的：AI 功能的入口，将越来越多地迁移到用户已经存在的工作流里，而不是要求用户打开一个新应用。 "让 AI 功能在用户已在的地方运作"将成为设计决策的起点，而不是"让用户来找 AI"。

  • Gateway（控制平面 / 信息调度中心）：

    • OpenClaw 运行着一个持续在线的网关守护进程，负责维持所有连接并协调整个系统，这是坐在用户指令和模型调用之间的控制层。
    • OpenClaw 能够支持多种界面（CLI、Web UI、桌面应用、移动节点）的一个重要原因是，它将网关视为一个真正的控制平面。Gateway 连接各种聊天平台和控制界面，把收到的消息派发给 Agent 运行器处理。
    • Gateway 关键设计思想是： 把消息通信、接口层和AI 怎么思考和执行（Agent）彻底分开。它采用调度中心架构，所有消息都经过一个中央塔台进行分发。Gateway 是"总机" → Agent 是"接线员+执行者"。 Gateway 关注: 谁发来的？发到哪？ Agent 关注: 什么意思？怎么做？做完回什么？
    • Gateway 核心就是一个HTTP和WebSocket服务。其启动时与注册的Channel（比如Telegram机器人）建立WebSocket连接，随时准备接收消息。
    • Gateway 是持久运行的控制平面，负责保持与所有消息渠道的长连接、所有组件的调度与交互，管理会话状态、响应客户端请求、处理定时任务，以及Agent调度。同时还要负责监控各Channel和Node的联通状况（health check）。

  • 智能体运行时（agent runtime / 思考核心）:

    • 智能体运行时具体负责：多模型统一接口，工具调用和执行，技能系统管理，会话上下文维护，记忆系统(短期+长期)；
    • 一旦网关决定了由哪个 agent 和哪个会话来处理输入，智能体运行时会执行这样一个常规循环：1）加载上下文（会话历史 + 工作区上下文）；2）调用模型；3）执行工具调用（浏览器、文件系统、shell、节点、插件）；4）持久化更新；5）响应（或故意保持沉默）。
    • OpenClaw并没有从0构造Agent核心，而是使用开源的Pi-Agent框架。Pi Agent构成整个系统执行的大脑思考核心，是处理逻辑和生成回复的核心引擎。系统中所有的运行逻辑都由推理循环架构来控制，也就是AgenticLoop。
    • AgentLoop 是 OpenClaw 最关键的执行循环。每次收到用户消息，都会进入这个循环。OpenClaw的推理循环是一个事件驱动的架构：主循环 (run.ts) 负责错误处理、重试、profile轮换；尝试层 (attempt.ts) 负责单次LLM调用的完整生命周期；事件订阅 (subscribe.ts) 处理流式响应和工具调用。

  • Nodes & Apps：

    • 通过将不同设备定义为“节点”，OpenClaw 实现了跨设备的硬件控制；
    • Channel是基于不同IM的开放平台能力，让OpenClaw与不同的IM的开放平台服务通信。可以说Channel是针对不同的IM程序的适配器。相对的，Node则是针对iOS、Android、macOS这种操作系统的适配器。
    • Node是一种实际运行在iOS、Android和macOS上的程序，并与运行在用户电脑上的OpenClaw主程序进行远程通信。用户将自己的设备的权限开放给Node，这样OpenClaw就可以通过Node来远程控制用户的设备，如执行任务，打开摄像头，屏幕截图，获取地理位置等。

0x02 Nanobot 基础

Nanobot遵循两条核心原则：

  1. "当有疑问时，留白" ：拒绝功能膨胀、保持核心精简、按需扩展
  2. "代理逻辑不应埋藏在层层抽象之下"：代码可读性优先、单一职责原则、模块边界清晰

因此，Nanobot的核心特色如下：

2.1 核心功能 / 特色

  • 轻量级架构：无冗余设计，仅保留 Agent 核心能力。
  • 异步非阻塞：全异步设计，支持并发任务处理，避免单任务阻塞整个引擎
  • 多通道适配：支持 CLI、系统消息、自定义通道等多场景消息处理
  • 消息驱动的 Agent 主循环：接收消息 → 构建上下文 → 调用 LLM → 执行工具 → 返回结果
  • 完整的工具生态：支持文件操作、命令执行、网页搜索 / 爬取、子 Agent 生成、定时任务、消息发送等核心工具
  • 可扩展：插件化工具注册机制，支持自定义工具 / MCP 扩展，适配不同场景
  • 会话管理与记忆 Consolidation：自动管理会话历史，自动 Consolidate 长会话记忆，支持大窗口记忆压缩，避免上下文溢出，平衡上下文长度与记忆完整性
  • 安全隔离：可限制 Agent 操作范围到指定工作区，防止越权访问
  • 可中断性：支持 /stop 指令终止当前任务，保证 Agent 响应性

2.2 🛠️ 技术栈

以下是 Nanobot 的技术栈。

组件 技术/库
核心语言 Python ≥ 3.11
CLI 工具 Typer
LLM 接入 LiteLLM (支持多个提供商)
配置管理 Pydantic 2.x
日志 Loguru
WebSocket websockets, websocket-client
HTTP 客户端 httpx
OAuth oauth-cli-kit
Telegram python-telegram-bot
Discord Discord.py (通过 Slack SDK)
飞书 lark-oapi
钉钉 dingtalk-stream
Slack slack-sdk
QQ 机器人 qq-botpy
定时任务 croniter
WhatsApp Bridge Node.js + TypeScript + Baileys
MCP 支持 mcp (Model Context Protocol)
Markdown 渲染 rich
代码规范 Ruff

2.3 📁 主要目录结构

以下是 Nanobot 的主要目录结构。

nanobot-main/
├── nanobot/                 # 核心包目录
│   ├── agent/              # 🧠 核心代理逻辑
│   │   ├── loop.py         #    代理循环 (LLM ↔ 工具执行)
│   │   ├── context.py      #    提示构建器
│   │   ├── memory.py       #    持久化记忆
│   │   ├── skills.py       #    技能加载器
│   │   ├── subagent.py     #    后台任务执行
│   │   └── tools/          #    内置工具
│   ├── skills/             # 🎯 捆绑技能 (github, weather, tmux...)
│   │   ├── clawhub/
│   │   ├── cron/
│   │   ├── github/
│   │   ├── memory/
│   │   ├── skill-creator/
│   │   ├── summarize/
│   │   ├── tmux/
│   │   └── weather/
│   ├── channels/           # 📱 聊天渠道集成
│   ├── bus/                # 🚌 消息路由
│   ├── cron/               # ⏰ 定时任务
│   ├── heartbeat/          # 💓 主动唤醒
│   ├── providers/          # 🤖 LLM 提供商配置
│   ├── session/            # 💬 会话管理
│   ├── config/             # ⚙️ 配置处理
│   └── cli/                # 🖥️ 命令行界面
├── bridge/                 # Node.js WhatsApp 桥接器
│   ├── package.json
│   └── tsconfig.json
├── tests/                  # 测试目录
├── case/                   # 案例展示 (GIF)
├── pyproject.toml          # Python 项目配置
├── Dockerfile              # Docker 镜像配置
├── docker-compose.yml      # Docker Compose 配置
├── README.md               # 项目文档
└── SECURITY.md             # 安全文档

2.4🌐 支持的平台

以下是 Nanobot 支持的平台。

聊天渠道：Telegram、Discord、WhatsApp、飞书、Mochat、钉钉、Slack、Email、QQ、Matrix

LLM 提供商：OpenRouter、Anthropic (Claude)、OpenAI (GPT)、DeepSeek、Groq、Gemini、MiniMax、AiHubMix、SiliconFlow、VolcEngine、通义千问 (Dashscope)、Moonshot (Kimi)、智谱 (Zhipu)、vLLM、OpenAI Codex、GitHub Copilot

0x03 Nanobot 总体架构

3.1 架构特点

Nanobot 的架构特点如下：

  1. 消息驱动架构：通过 MessageBus 实现渠道与 Agent 的解耦
  2. 核心引擎：AgentLoop是核心处理引擎，负责 LLM 与工具执行的循环
  3. 多渠道支持：通过 ChannelManager 统一管理 10+ 种聊天平台
  4. 可扩展性：
    • 工具通过 ToolRegistry 注册
    • LLM 提供商通过 Provider Registry 统一管理
    • 支持技能插件系统和 MCP 协议
  5. 持久化：SessionManager和 MemoryStore 负责会话和记忆的持久化
  6. 后台任务：CronService 和 Heartbeat提供定时任务和主动唤醒功能

3.2 架构图

Nanobot 的架构图如下：

nanobot_arch

对应各组件职责为：

  • Gateway:
    • 系统入口，协调各组件启动和运行
    • 启动MessageBus、AgentLoop、ChannelManager
    • 协调 CronService 和 HeartbeatService
  • Channel（如QQchannel）：
    • 接收外部消息
    • 将消息发布到.MessageBus
    • 发送响应消息回外部平台
  • AgentLoop:
    • 从MessageBus消费消息
    • 执行 AI 推理和工具调用
    • 将响应发布到 MessageBu
# 学习 # 架构
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

装修小白自救指南：我让 WorkBuddy 刷了 500 篇小红书，帮我选完 5 万块的全屋家电

avatar 龙虾开发者社区

图解Skill读书笔记（六）：Skill开发工程化发布流程

本文为 CSDN 导读版，完整原文已发布在个人网站。

avatar 龙虾开发者社区
cover

Skill 技能系统完全指南（八）：进阶技巧——条件触发、多语言支持与 Agent/Workflow 配合

avatar 龙虾开发者社区