夜雨聆风从一个进程说起
你第一次运行 openclaw gateway start，终端里出现一行日志：
Gateway listening on ws://127.0.0.1:18789就这一行。没有什么微服务群，没有消息队列，没有数据库进程，没有服务发现组件。整个 OpenClaw 的核心，就是一个 Node.js 进程。
这不是偷懒，而是有意为之。
个人 AI 助手的第一优先级是可以在你自己的机器上跑起来——一台普通的 MacBook、一台 Linux 小主机、一个 $6/月的 VPS。多进程架构确实更"工程范儿"，但它带来了部署复杂度、进程间通信的延迟、以及"启动顺序不对就全挂"的运维噩梦。OpenClaw 的选择是把复杂度内化到单进程里，对外呈现一个极简的安装体验。
整个系统的架构，可以划分为四层。
四层架构速览
┌──────────────────────────────────────────────┐│ 第四层：Intelligence（智能层） ││ LLM Models · Memory System · Skills │├──────────────────────────────────────────────┤│ 第三层：Execution（执行层） ││ Pi Agent Core · Tool System │├──────────────────────────────────────────────┤│ 第二层：Integration（接入层） ││ Channel Monitors · Session Management │├──────────────────────────────────────────────┤│ 第一层：Infrastructure（基础层） ││ Gateway · CLI · Config System │└──────────────────────────────────────────────┘
这四层不是独立运行的服务，而是同一个进程内不同职责模块的概念划分。从上到下，是"更聪明"到"更基础"；从下到上，是数据在系统里流动的方向。
第一层：基础设施
Gateway——一切的中枢
Gateway 是 OpenClaw 的核心控制平面，以一个长期运行的 WebSocket 服务器形式存在，协调所有客户端、消息通道与 Agent 运行时之间的通信。
它的入口是 src/gateway/server.impl.ts 里的 startGatewayServer() 函数。启动后，Gateway 在单一端口（默认 18789）上同时提供 WebSocket 和 HTTP 两种接口服务。
Gateway 具体负责五件事：
- 接受连接
：CLI、Web UI、macOS/iOS/Android 原生 App 都通过 WebSocket 连入这同一个端口。 - 通道生命周期管理
：WhatsApp、Telegram、Discord 等适配器的启动、监控、自动重连，都由 Gateway 统一调度。 - 消息路由
：把从各通道收到的消息，派发给对应的 Agent Session 处理，再把回复路由回正确的通道。 - 配置热重载
：你修改 ~/.openclaw/openclaw.json，Gateway 通过gateway/config-reloader.ts监听文件变化，无需重启即可生效。 - 健康监控
：定期探测通道连接状态，发现断线自动重连（配置项 gateway.channelHealthCheckMinutes）。
这个端口号 18789 在整个项目里是个高频常量，你会在日志、AGENTS.md 的调试建议、CLI 的状态探测命令里反复看到它：
ss -ltnp |rg 18789# 检查 Gateway 是否在监听
CLI——Gateway 的远程控制器
openclaw 这个命令行工具，本质上是一个远程控制器。绝大多数 CLI 命令——比如 openclaw channels status、openclaw agent list、openclaw config set——并不直接操作进程内的数据，而是通过 WebSocket 连上 Gateway，发送 JSON-RPC 请求，Gateway 处理后把结果返回来。
这个设计的好处是：Gateway 以 daemon 方式常驻后台，你可以在任何终端窗口里通过 CLI 对它发出指令，就像用 kubectl 操控 Kubernetes 一样。命令的注册体系由 Commander.js 搭建，入口是 src/cli/program.ts，按功能分组注册在 src/commands/ 目录下。
配置系统
所有配置集中在 ~/.openclaw/openclaw.json，格式是 JSON5（允许注释，方便人阅读）。配置的 Schema 定义在 src/config/zod-schema.ts 里，用 Zod 库在运行时做类型校验，配置写错了会有清晰的错误提示。
值得一提的是 SecretRef 系统：API Key 这类敏感字段不直接写进配置文件，而是以 {"env": "ANTHROPIC_API_KEY"} 或 {"file": "~/.secrets/token"} 的形式引用外部来源，避免凭证明文出现在配置文件里被误提交或误备份。
第二层：接入层
Channel Monitor——平台适配器
Channel Monitor 是连接外部消息平台的适配器层，负责把各平台的消息格式规范化为 OpenClaw 内部的统一格式。
每个平台的通信机制都不一样：Telegram 用 Bot API 的长轮询，WhatsApp 用 Baileys 库的 WebSocket，Discord 用官方事件流。Channel Monitor 把这些差异全部封装起来，向上只暴露一套统一接口。OpenClaw 目前支持 20 多个平台，包括 WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Microsoft Teams、Matrix 等。其中主流平台是内置实现，小众平台以插件形式发布，通过在 package.json 里声明特定字段被 Gateway 自动发现和加载。
同一个平台可以配置多个账号，各自独立监控。访问控制通过 dmPolicy 字段控制，支持 pairing（设备配对白名单）、allowlist、open、disabled 四种模式，决定哪些人发来的消息才会触发 AI 回复。
Session Management——对话的隔离边界
消息进来以后，不是直接扔给 Agent，而是先确定它属于哪个 Session。Session 不只是一个对话 ID，它是安全边界、工具权限范围、历史记录存储的综合容器。
主会话（main）、私信会话（dm:telegram:12345678）、群组会话（group:discord:987654321）各自独立，互不干扰。每个 Session 的历史对话以 JSONL 格式持久化到磁盘——每行一条消息记录，格式简单，崩溃恢复也不会丢失。Session 的并发写入通过文件锁保护，具体实现在 src/agents/session-write-lock.ts。
第三层：执行层
Pi Agent Core——Agent Loop 的本体
这里是整个系统最关键的地方，也是最值得单独说的一个架构决策。
OpenClaw 没有自己实现 Agent Loop，而是复用了由社区贡献者 Mario Zechner 开发的 @mariozechner/pi-agent-core npm 包。
为什么不自己实现？这是一个把"复杂但通用"的部分外包出去的成熟决策。Agent Loop 的核心逻辑——调用模型 API、解析工具调用指令、执行工具、把执行结果反馈给模型、判断何时停止——这套循环各家实现大同小异。OpenClaw 把这个"难但标准"的部分委托出去，自己只负责"不难但很重要"的外围：系统提示词组装、工具策略控制、Session 持久化、流式响应转发。
src/agents/piembeddedrunner.ts 里的 PiEmbeddedRunner 就是 Pi 框架与 OpenClaw 之间的适配层，是执行层最核心的文件。
Tool System——Agent 的手脚
工具是 Agent 能够调用来执行真实动作的函数。OpenClaw 把工具分为两类：Pi 内置的编码类工具（文件读写、代码执行、进程管理），以及 OpenClaw 专属工具（浏览器自动化、跨通道发消息、定时任务、子 Agent 管理等）。两类工具通过 createOpenClawCodingTools() 合并注册给 Agent。
工具的调用权限由策略管道管控，支持 allow/deny 规则，也支持 group:fs、group:runtime 这样的快捷权限组。沙箱模式下，敏感工具可以限制在 Docker 容器内执行。
第四层：智能层
LLM 模型层
OpenClaw 不绑定任何一家模型厂商。Claude、GPT、Gemini、DeepSeek、本地 Ollama 模型都在支持范围内，模型定义统一注册在 openclaw-models.json 里，每条记录包含 API 类型、上下文窗口大小、支持的输入模态等信息。
同一个 Agent 可以配置主模型和备用模型：当主模型遭遇速率限制或认证失败时，系统自动标记冷却时间并切换到备用配置，整个过程对用户透明。
Memory System——跨 Session 的长期记忆
记忆系统支持两种后端：builtin（基于 SQLite 的向量存储，开箱即用）和 qmd（Quick Markdown，Markdown 文件加向量索引的混合检索）。每次 Agent 执行前，记忆系统会被查询，把与当前对话语义相关的历史片段注入到 System Prompt 里，实现跨 Session 的长期记忆。
Skills——用 Markdown 写的能力扩展
Skills 是 OpenClaw 里最有创意的设计之一。它不是代码插件，而是一份写给 Agent 看的说明书——SKILL.md 格式，用自然语言描述某项能力的使用方法和注意事项。安装后，相关 Skill 的内容会在 Prompt 组装阶段被动态注入，让 Agent 获得新的能力，比如"如何用 Gmail API 查邮件"、"如何操作这台机器上的 Docker"。
一条消息的完整旅程
把四层架构串在一起，最直观的方式是跟着一条消息走一遍。
你在 Telegram 里发出："帮我把昨天的邮件总结一下。"
首先，接入层的 Telegram Channel Monitor 收到这条消息，把它规范化为内部格式，识别出对应的 SessionKey 是 dm:telegram:你的ID，推送给 Gateway。
然后，基础层的 Gateway 收到通道推入的消息事件，查找对应的 Session，将任务放入执行队列。
接下来，执行层的 PiEmbeddedRunner 取出这条任务，依次完成：查询 Memory System 检索你近期提到过邮件的相关记忆片段；按优先级拼装 System Prompt（SOUL.md + USER.md + 记忆片段 + Gmail Skill）；调用模型 API；模型决定调用 gmail_fetch 工具；Tool System 执行工具拿回邮件列表；把邮件内容反馈给模型；模型生成最终总结。
最后，基础层的 Gateway 把流式生成的回复转发回 Telegram Channel Monitor，你的对话框里出现了答复。
整个过程，全部发生在你自己的机器上，不经过任何第三方服务器。
项目目录一眼看懂
理解了四层架构，再看目录结构就清晰很多。src/gateway/ 是第一层的核心；src/channels/ 是第二层的通道适配器；src/agents/ 是第三层的执行运行时；src/memory/ 是第四层的记忆系统。根目录下的 extensions/ 放内置扩展，packages/ 放共享 SDK，apps/ 放 iOS / Android / macOS 的原生客户端，skills/ 放内置 Skills 集合。
openclaw/├── src/ # 核心源码│ ├── gateway/ # Gateway 控制平面（第一层）│ ├── commands/ # CLI 命令实现（第一层）│ ├── config/ # 配置系统（第一层）│ ├── channels/ # 内置通道适配器（第二层）│ ├── agents/ # Agent 运行时适配层（第三层）│ └── memory/ # 记忆系统（第四层）├── extensions/ # 内置扩展（memory-core 等）├── packages/ # 共享包（Schema、SDK）├── apps/ # 原生客户端（iOS/Android/macOS）├── skills/ # 内置 Skills 集合└── docs/ # 官方文档
技术栈选型
最后简单交代一下技术选型，这些选择在贡献者指南 AGENTS.md 里都有明确记载。
项目使用 TypeScript ESM，要求严格类型，禁止使用 any，代码格式化和 Lint 由 Oxlint 和 Oxfmt 负责。运行时以 Node.js 22+ 为基准，同时保持对 Bun 的兼容——日常开发和测试优先用 Bun 执行，生产构建产物用 Node 运行。包管理器是 pnpm，工作区（workspace）结构管理 monorepo 下的多个子包。
这个"Node 跑生产，Bun 跑开发"的双轨策略，是 OpenClaw 在生态兼容性（Node.js 生态成熟）和开发体验（Bun 启动快、天然支持 TypeScript）之间做出的务实平衡。
小结
OpenClaw 的架构本质是一个单进程的 WebSocket 中枢，把消息平台接入、Agent 执行、长期记忆、工具调用这四个过去需要单独产品来解决的问题，整合进同一个可以在普通硬件上运行的进程里。
它的设计哲学不是"功能最多"，而是"刚好够用，并且你能自己掌控"。
从下一篇开始，我们进入具体代码：先从最外层的入口 openclaw.mjs 开始，一路追进去看整个 CLI 是怎么组织起来的。
源码参考：src/gateway/server.impl.ts · src/agents/piembeddedrunner.ts · src/index.ts · AGENTS.md基于 commit bf6ec64f 版本
