小龙虾(OpenClaw)源码分析1：整体架构和源码地图
最近打算系统性地啃一下OpenClaw源码，顺手也开个系列记录一下自己的理解过程。
这一篇是第1篇，目标很简单：先把地图摊开，搞清楚这个项目大致由哪些模块组成，消息是怎么流动的，后面再按模块逐个击破。
先说明一下，本文基于openclaw当前最新源码（我本地拉取时间是写文当天），重点放在工程结构和运行链路，不会一上来就抠每一行实现。
OpenClaw到底是什么
如果只用一句话来概括，我觉得是：
一个自托管的AI助手网关（Gateway），把多种聊天渠道、Agent运行时、工具能力统一在一个控制平面里。
从官方README也能看出来，它不是单纯的聊天机器人，而是一个“中枢”：
- 一边连各种消息渠道（Telegram/Slack/Discord/WhatsApp等）
- 一边连Agent（模型、会话、工具）
- 中间通过Gateway做连接管理、路由、状态与安全控制
所以你可以把它想象成：聊天渠道适配层 + Agent运行编排层 + 控制平面。
读源码前先看主链路
很多同学读大项目容易卡住，不是因为代码难，而是因为没先抓住主链路。
我自己总结了一个“先粗后细”的阅读顺序：
- 入口在哪（程序怎么启动）
- 网关怎么起（核心服务怎么挂起来）
- 消息怎么流动（入站 -> 路由 -> Agent -> 出站）
- 会话和状态怎么存（上下文连续性）
只要这4个问题通了，后面看队列、插件、安全就顺很多。
一张图看整体架构
先画个非常简化的示意图（不是源码中的官方图，方便理解）：
聊天渠道(Discord/Slack/Telegram/...)
|
v
Gateway(控制平面)
|
+--------+--------+
| |
v v
会话/路由/队列 Agent运行时(模型+工具)
| |
+--------+--------+
|
v
响应回渠道
你会发现，Gateway是中间那层“总调度”，这也是后续系列里会反复出现的核心词。
源码目录地图（先记核心）
这个仓库很大，但第一阶段你只要盯住这几个目录就够了：
src/entry.ts：CLI入口之一，处理启动前置逻辑src/index.ts：兼容入口与库导出相关逻辑src/gateway/：网关核心实现（控制平面）src/agents/：Agent相关运行逻辑（上下文、模型、行为）src/channels/：渠道相关实现src/plugins/与extensions/：插件化能力和扩展实现docs/concepts/：架构和机制文档（读源码前后都很有帮助）
一句话：先读entry/index/gateway/agents，再扩展到channels/plugins。
从启动入口开始看
src/entry.ts里能看到启动前做了不少事情，比如：
- 环境归一化
- 参数预处理（比如profile/container相关）
- 快速路径（如版本和help）
- 最终进入CLI主流程
这种入口文件很典型：它并不承载业务本身，而是承载“把系统安全且可控地拉起来”的职责。
如果你之前读过一些CLI项目（例如kubectl、docker这类工具），会发现套路很像：
先保证启动姿势正确，再把活交给真正的命令执行层。
Gateway为什么是“控制平面”
docs/concepts/architecture.md里明确了一个核心点：Gateway是长期运行的中枢，客户端、节点、Web控制端都围绕它通信。
从工程角度看，这种设计有几个明显好处：
- 渠道接入统一，不会每个渠道都自己维护一套状态机
- 会话和路由统一，不会出现“同一个用户在不同入口上下文割裂”
- 安全策略统一（配对、鉴权、远程访问策略）
你可以理解为：消息面和控制面被清晰地收口到Gateway，后续无论接新渠道还是换模型，都更容易演进。
系列文章安排（含Python番外）
前面规划的系列我这里正式落成目录，方便后续连载时对齐：
- 总览：架构和源码地图（本文）
- CLI启动链路：从命令到主流程
- Gateway启动内幕：控制平面如何建立
- 消息主链路：入站到回复全过程
- Session机制：上下文如何持续
- 队列与并发：如何避免串台和拥塞
- 流式输出：回复体验如何做快做稳
- Agent工作空间：
AGENTS.md等文件如何影响行为 - 模型与上下文窗口：多Provider细节
- 插件机制：渠道和能力如何扩展
- 安全设计：权限边界与生产加固
- 可观测性：日志、健康检查与排障
- 番外：用Python实现一个迷你版OpenClaw（仅命令行交互）
第13篇会刻意保持“极简可运行”，只提供命令行交互接口，不做Web界面，目的是帮助大家从“读懂架构”走到“自己动手实现”。
本文小结
这一篇我们先完成了三件事：
- 明确了OpenClaw的定位：它是AI助手网关而不是单点机器人
- 画出了主链路：渠道 -> Gateway -> Agent -> 渠道
- 确定了源码阅读顺序和整个系列路线图
下一篇我们就正式进CLI启动链路，看看一条openclaw ...命令是如何一步步进入主执行逻辑的。
