上篇回顾

上一篇〖OpenClaw系列〗onboard新手引导全流程拆解，我们跟着onboard向导走了五步，生成了一套可用配置。你现在已经能10分钟搭起一个OpenClaw环境。

但配置写好了，Gateway到底是怎么跑起来的？ 输入 openclaw gateway start 之后，那几行启动日志背后发生了什么？消息从Telegram进来、到模型处理、再到回复回去——这条链路怎么走的？这篇把Gateway从按下回车到处理请求的全过程拆干净。

本文定位：Gateway内部机制的深度解析。读完这篇，你看到Gateway日志时能定位到对应阶段，遇到启动失败、热重载不生效、连接断开等问题能从原理层面排查。

阅读建议：本文偏底层原理，篇幅较长。如果你刚开始使用 OpenClaw，可以先跳过本篇，可以先收藏+关注，这个是系列文章。等你遇到 Gateway 启动异常或需要性能调优时，再回来读会更有收获。如果你只想快速了解 Gateway 做了什么，请直接跳到「总结」章节看三张表。

先上全景：理解Gateway需要三张图

Gateway的核心机制可以拆成三个层面，每张图讲一个：

1. 启动时序——从按下回车到服务就绪，中间经历了哪些阶段
2. 进程架构——运行起来后，哪些进程在协同工作
3. 请求处理——一条消息从进站到出站，经过了哪些环节

先看第一张：启动时序。

一、OpenClaw Gateway启动全流程

时序图：从回车到就绪

这张图从左到右展示了Gateway启动的六个阶段。蓝色区域（Step 1-2）是配置与密钥阶段，橙色区域（Step 3）是网络绑定阶段，紫色区域（Step 4-5）是渠道与Agent初始化阶段，绿色区域（Step 6）是启动完成的标志。每个阶段有对应的日志输出——下面会逐一对号入座。

阶段1：配置加载与校验

按下 openclaw gateway start，第一件事不是启动服务器，而是读配置、校验配置。

前置要求：Gateway需要 Node.js >= 18 运行环境。如果不确定，先用 node --version 检查。

$ openclaw gateway start

[INFO] Loading configuration from ~/.openclaw/openclaw.json
[INFO] Configuration loaded successfully (312 bytes)
[INFO] Validating schema... OK

Gateway做了三件事：

1. 读取 openclaw.json — 从 ~/.openclaw/ 目录读取主配置文件
2. 解析 JSON5（JSON的扩展超集，支持注释和尾逗号） — 解析为内部配置对象
3. Schema 校验（JSON Schema格式校验） — 逐字段检查类型和必要性，任何字段名拼写错误都直接报错退出

校验失败时你会看到类似输出（下面是故意拼错字段的错误示例）：

[ERROR] Schema validation failed:
  - agents.defualts.model: unknown field (did you mean "defaults"?)
  - channels.telegram.bot_token: expected string, got number
[ERROR] Gateway startup aborted. Fix the above errors and try again.

对应第3篇：配置文件的字段定义和校验规则，在第3篇《[配置文件 openclaw.json 详解](./第03篇-配置文件 openclaw.json 详解.md)》「五条彩色带」各章节有详细说明。

敏叔侃技术，公众号：敏叔侃技术〖OpenClaw系列〗配置文件 openclaw.json 详解

阶段2：Secret解析

配置校验通过后，Gateway把所有 ${VAR} 占位符替换为实际值。

[INFO] Resolving secrets...
[INFO]   ANTHROPIC_API_KEY: loaded from ~/.openclaw/.env
[INFO]   TELEGRAM_BOT_TOKEN: loaded from environment
[WARN]   OPENAI_API_KEY: not found (referenced in agents.defaults.model.fallbacks)

解析优先级：已有环境变量 > ~/.openclaw/.env > 当前目录 .env

如果某个变量不存在且该字段是必需的，Gateway直接退出。上面例子中 OPENAI_API_KEY 未找到，但因为它是 fallback 模型的Key（非必需），只输出警告而非报错。

阶段3：端口绑定与网络初始化

Secret搞定了，开始绑端口。

[INFO] Binding gateway to 127.0.0.1:18789
[INFO] Gateway listening on http://localhost:18789

这个阶段的行为受 gateway.bind 控制：

端口被占用时，Gateway不会静默失败：

[ERROR] Port 18789 is already in use by process 48291
[INFO]  Options:
[INFO]    1. Stop the other process: kill 48291
[INFO]    2. Change port in gateway.port configuration

阶段4：Channel初始化

端口绑好后，Gateway开始加载你配置的各个渠道。

[INFO] Initializing channels...
[INFO]   telegram: connecting... OK (polling mode)
[INFO]   discord: skipped (enabled: falsein config)
[WARN]   whatsapp: connection failed (invalid bot token)
[INFO] Channels initialized: 1/2 active

每个Channel独立初始化。一个渠道失败不影响其他渠道启动——这是设计上的容错策略。

术语说明：Channel初始化指Gateway与消息平台（如Telegram）建立连接的过程。不同渠道使用不同的连接方式——Telegram支持Polling（轮询）和Webhook（回调），Discord使用WebSocket长连接。

阶段5：Agent加载

渠道就绪后，加载Agent配置。

[INFO] Loading agents...
[INFO]   default: model=anthropic/claude-sonnet-4-6, workspace=~/.openclaw/workspace
[INFO]   Agents loaded: 1
[INFO] Workspace check: ~/.openclaw/workspace/SOUL.md found

Agent加载做了这些事：

• 读取 agents.defaults 和各Agent的独立配置
• 验证模型可用性（不会真正调用，只检查配置完整性）
• 扫描 workspace 目录，读取 SOUL.md 如果存在
• 初始化 tools 白名单

阶段6：就绪信号

全部初始化完成后，输出就绪标志：

[INFO] ══════════════════════════════════════
[INFO] Gateway ready on http://localhost:18789
[INFO] Control UI: http://localhost:18789
[INFO] Channels: telegram
[INFO] Agents: default
[INFO] ══════════════════════════════════════

看到 Gateway ready，说明六个阶段全部通过。如果卡在某个阶段没有后续输出，说明那个环节出了问题——对照上面的日志就能定位。

二、进程模型与Watchdog机制

Gateway不是一个单进程程序。它采用主进程 + 工作进程的双进程架构，配合Watchdog守护。

进程架构图

看这张图：左边蓝色区域是主进程（Main），右边绿色区域是工作进程（Worker），上方红色区域是Watchdog——三个角色各司其职。

主进程：守门人

主进程是Gateway的入口，职责很明确：

1. 绑定端口 — 监听18789（或你配的端口）
2. 接受连接 — WebSocket（全双工持久连接协议）握手、HTTP请求分流
3. 管理生命周期 — 启动工作进程、传递信号、触发重启

主进程不处理业务逻辑。消息进来后，它只负责把连接交给工作进程，自己做”交通指挥”。

为什么这样设计？因为主进程的逻辑越简单，它就越不容易崩溃。即使工作进程出了问题，主进程仍然可以接受新连接、重启工作进程——保证服务不中断。

工作进程：干活的人

工作进程处理所有实际业务：

• 消息路由 — 判断消息发给哪个Agent
• 模型调用 — 向LLM API发请求、接收流式响应
• 工具执行 — 运行Skill、执行shell命令
• 会话管理 — 维护上下文、处理重置

工作进程是Gateway最”忙碌”的部分，也是资源消耗最大的部分。

Watchdog：看门狗

术语说明：Watchdog（看门狗）是一种进程监控机制，定期检查工作进程的健康状态，发现异常时自动采取恢复措施。这个概念来自嵌入式系统——硬件看门狗定时器用于检测和恢复系统故障。

Watchdog独立于主进程和工作进程，持续做三件事：

1. 健康检查

每隔固定间隔（默认5秒），向工作进程发送心跳探测：

Watchdog → Worker: PING
Worker → Watchdog: PONG (within 2s)

如果工作进程在超时时间内没有响应，Watchdog判定它已”卡死”。

2. 自动重启

发现工作进程异常后的处理流程：

[WARN] Watchdog: worker unresponsive (last pong 15s ago)
[INFO] Watchdog: sending SIGTERM to worker (pid 49823)  // SIGTERM=请求终止信号，进程可捕获
[INFO] Watchdog: worker terminated
[INFO] Watchdog: spawning new worker (pid 50107)
[INFO] Watchdog: worker healthy (pong received in 0.3s)

从检测到异常到新进程就绪，通常在3秒内完成。

3. 优雅退出

当你按 Ctrl+C 或执行 openclaw gateway stop 时：

Main → Watchdog: SHUTDOWN
Watchdog → Worker: SIGTERM (graceful, 可捕获的终止信号)
[等待 10s]
Watchdog → Worker: SIGKILL (forced, 不可捕获的强杀信号)
Main: exit 0

先给工作进程10秒窗口完成进行中的请求，超时才强杀——这就是”优雅退出”。

进程间通信

主进程和工作进程之间通过IPC通道（Inter-Process Communication，进程间通信）通信：

对应第1篇：第1篇《AI网关是什么、能做什么》讲的”Gateway是路由枢纽”，在进程模型层面就是主进程做路由分发、工作进程做实际处理。

三、OpenClaw热重载配置与底层实现

第3篇提到热重载的概念——改了配置不用重启。现在来看它底层怎么实现。

文件监听：改了立刻知道

Gateway启动后，主进程启动一个文件监听器（File Watcher），盯着 openclaw.json 和 $include 引用的所有子文件：

File Watcher 盯着这些文件：
  ~/.openclaw/openclaw.json          ← 主配置
  ~/.openclaw/agents.json5           ← $include 引用
  ~/.openclaw/channels/telegram.json5 ← $include 引用
  ...

文件一有变动（保存、创建、删除），监听器立刻捕获事件。

防抖策略：等一下再处理

编辑器保存文件时经常触发多次写入事件（尤其是自动保存）。Gateway用300ms防抖窗口避免重复处理：

t=0ms    文件变动事件1（编辑器写入）
t=50ms   文件变动事件2（编辑器写入）
t=200ms  文件变动事件3（编辑器写入）
t=300ms  无新事件 → 触发重载

这个300ms就是 gateway.reload.debounceMs 的默认值。

配置校验与Diff检测

防抖窗口结束后，Gateway做三步：

1. 读取新配置文件

[INFO] Hot reload: configuration change detected
[INFO] Hot reload: reading new configuration...

2. Schema校验

新配置必须通过Schema校验。校验失败怎么办？不打断现有服务，只打警告：

[WARN] Hot reload: schema validation failed
[WARN]   - channels.telegram.dmPolciy: unknown field (did you mean "dmPolicy"?)
[WARN] Hot reload: skipped (current configuration unchanged)

这是热重载的一个重要设计原则：宁可忽略新配置，也不能让错误配置中断正在运行的服务。

3. Diff检测

即使校验通过，也不一定需要重载。Gateway对比新旧配置，只有真正变化的字段才触发更新：

[INFO] Hot reload: diff detected
[INFO]   changed: agents.defaults.heartbeat.every (30m → 1h)
[INFO]   changed: channels.telegram.dmPolicy (pairing → open)
[INFO]   unchanged: gateway.port, gateway.bind, models, session

热加载 vs 重启决策

配置变化分为两类：可热加载的和必须重启的。

在 hybrid 模式（默认）下，Gateway自动判断：可热加载的立即生效，需重启的自动重启工作进程。在 hot 模式下，需重启的变更不会自动执行，只记录一条警告日志。

零中断更新：进行中的请求怎么办

热加载时，工作进程可能正在处理消息。Gateway的处理方式：

1. 已完成握手的长连接 — 不中断，下次请求使用新配置
2. 正在处理中的请求 — 等待其自然完成，超时则丢弃
3. 新建连接 — 立即使用新配置

Channel的热加载稍有不同。以Telegram为例：

[INFO] Hot reload: re-configuring channel telegram
[INFO]   Old connection: polling (pairing mode)
[INFO]   New connection: polling (open mode)
[INFO]   Transitioning: new messages use new policy, existing sessions preserved

旧的Webhook/Polling连接切断，新的建立。进行中的对话上下文保留，只是新消息使用新策略。

四、请求处理：一条消息的完整旅程

了解启动和进程模型后，来看最核心的部分——消息怎么被处理。

请求处理流程图

这张图从上到下展示了一条消息的完整旅程。上半部分蓝色区域是进站阶段，中间绿色区域是处理阶段，下半部分紫色区域是出站阶段。

进站：消息到达Gateway

以Telegram为例，一条消息到达Gateway的路径：

用户在Telegram发消息
  → Telegram服务器推送Webhook
  → Gateway主进程接收HTTP POST
  → 主进程转交工作进程

如果是Polling模式，则是Gateway主动拉取：

工作进程定时调用 Telegram getUpdates API
  → 拉到新消息
  → 放入处理队列

无论哪种模式，消息到达工作进程后，第一步是标准化——把不同渠道的消息格式统一为内部格式：

{
  channel: "telegram",
  peerId: "telegram:123456789",
  content: "帮我查一下今天的天气",
  timestamp: 1716480000,
  metadata: {
    chatType: "private",  // private | group
    messageId: 4242,
  },
}

路由：决定谁来处理

标准化后，Gateway需要决定这条消息交给哪个Agent处理。路由规则：

大多数场景只有一个默认Agent，路由直接命中。

会话加载：恢复上下文

确定Agent后，加载该用户的会话上下文：

1. 根据 session.dmScope（Direct Message Scope，私信作用域）查找会话ID
   - "per-channel-peer" → 会话ID = "{channel}:{peerId}"
   - "main" → 会话ID = "main"

2. 从存储中加载历史消息
3. 检查 session.reset 是否触发重置
   - daily: 检查是否跨过重置时间点
   - idle: 检查距离上次活动是否超时

对应第3篇：dmScope 和 reset 的配置含义，在第3篇《[配置文件 openclaw.json 详解](./第03篇-配置文件 openclaw.json 详解.md)》「第四条橙带：session」章节有详解。

敏叔侃技术，公众号：敏叔侃技术〖OpenClaw系列〗配置文件 openclaw.json 详解

模型调用：把消息发给AI

上下文准备好后，构造请求发给模型API：

{
  model: "anthropic/claude-sonnet-4-6",
  messages: [
    { role: "system", content: "/* SOUL.md 内容 */" },
    { role: "user", content: "帮我查一下今天的天气" },
    // ... 历史对话
  ],
  tools: ["exec", "read", "write"],  // tools.allow 定义的工具列表
  stream: true,
}

模型调用的三个关键机制：

流式响应（Streaming）

Gateway默认使用流式请求。模型生成第一个token后，Gateway就开始向下传递——不等待完整响应。用户在Telegram上能看到AI”逐字打字”的效果，就是流式传输的体现。

超时控制

每个模型请求有 timeoutSeconds 上限（默认600秒）。超时后：

[WARN] Model request timed out after 600s (agent: default)
[INFO] Sending timeout message to peer: "请求超时，请稍后重试"

故障切换（Fallback，即降级备选模型）

如果主模型调用失败，且配置了 fallbacks：

主模型 anthropic/claude-sonnet-4-6 → 调用失败（503）
  ↓
备用模型 openai/gpt-5.2 → 调用成功
  ↓
返回GPT-5.2的响应给用户

用户无感知，只会在日志里看到切换记录。

工具调用：AI要干活

模型响应可能包含工具调用请求（tool_use）。这是AI说”我需要执行某个操作”的方式。

AI: "我需要执行天气查询命令"
  → Gateway: 执行 exec 工具，调用 curl wttr.in
  → 工具结果返回给 AI
  → AI: "北京今天晴，25度"

工具调用可能发生多轮——AI可能先执行一个命令，看到结果后决定再执行另一个。Gateway会持续执行直到AI给出最终文本回复，或达到工具调用次数上限。

对应第3篇：工具白名单 tools.allow 和 tools.deny 的配置，在第3篇《[配置文件 openclaw.json 详解](./第03篇-配置文件 openclaw.json 详解.md)》「第五条红带：tools」章节有详解。

敏叔侃技术，公众号：敏叔侃技术〖OpenClaw系列〗配置文件 openclaw.json 详解

出站：回复到达用户

最终文本响应生成后，流回用户的路径：

Gateway工作进程
  → 主进程转发
  → Channel Adapter（Telegram Bot API）
  → Telegram服务器
  → 用户看到回复

对于流式响应，每个token片段都实时推送，用户看到的是”打字机效果”。

五、内存与性能特征

理解了启动、进程和请求处理，最后看Gateway在生产环境的资源表现。

内存模型

Gateway的内存占用由三部分组成：

一个典型配置（1个Agent + Telegram + WhatsApp + 50个活跃会话）的内存占用：

基础: 50MB
+ Telegram: 5MB
+ WhatsApp: 10MB
+ 会话: 50 × 1MB = 50MB
= 总计 ~115MB

内存泄漏排查

如果内存持续增长不回落，最常见的原因是会话上下文无限增长：

# 查看当前会话数量和总大小
openclaw session stats

# 输出示例：
# Sessions: 127 (total 203MB, avg 1.6MB)
# Top 5 by size:
#   telegram:123456789  12.4MB  (2,847 messages)
#   telegram:987654321   8.2MB  (1,923 messages)
#   whatsapp:15555550123 6.1MB  (1,521 messages)

解决办法：

1. 启用会话重置 — 配置 session.reset.mode: "daily" 或 "idle"
2. 限制上下文窗口 — 在Agent配置中设置 maxContextTokens
3. 手动清理 — openclaw session clear <sessionId>

性能调优参数

并发模型

Gateway使用异步事件循环（Node.js的event loop，单线程非阻塞I/O模型）处理并发，而不是多线程。这意味着：

• 单个模型请求是异步等待的，不阻塞其他请求
• 100个并发用户不会创建100个线程
• maxConcurrent 限制的是同时进行的模型API调用数，不是WebSocket连接数

当并发请求数超过 maxConcurrent，额外的请求进入队列等待：

[INFO] Request queued (agent: default, active: 3/3, queue: 1)

队列中的请求按先进先出（FIFO，First In First Out）处理。

踩坑

坑1：Gateway启动后立即崩溃，日志只有一行

现象：

$ openclaw gateway start
[INFO] Loading configuration...
[ERROR] Gateway exited unexpectedly (code 1)

原因：最常见的三种——

1. 端口被占用（另一实例或其他服务占用了18789）
2. 配置文件语法错误（JSON5解析失败）
3. Node.js版本不兼容

解决：

# 检查端口占用
lsof -i :18789

# 验证配置语法
openclaw doctor

# 检查Node.js版本（需要 >= 18）
node --version

坑2：改了配置但没生效

现象：修改 openclaw.json 后保存，Gateway日志没有重载信息

原因排查：

1. gateway.reload.mode 设为了 off — 完全关闭了热重载
2. 修改的是 $include 子文件但文件监听器未覆盖
3. 编辑器自动保存触发了多次写入，每次都重置了防抖窗口，导致迟迟不触发重载

解决：

# 检查热重载配置
openclaw config get gateway.reload.mode

# 手动触发重载
openclaw gateway reload

# 如果 reload.mode 是 off，改为 hybrid
openclaw config set gateway.reload.mode hybrid

坑3：WebSocket连接频繁断开

现象：Control UI或Channel的WebSocket每隔几分钟断开重连

原因：

1. 反向代理超时设置太短（Nginx默认60秒）
2. 网络中间设备（防火墙/负载均衡）清理空闲连接
3. 代理未正确转发WebSocket协议

解决：

Nginx配置示例：

location / {
    proxy_pass http://127.0.0.1:18789;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;  # 关键：延长超时
    proxy_send_timeout 3600s;
}

坑4：内存持续增长不回落

现象：Gateway运行几天后，内存从100MB涨到500MB+

原因：会话上下文无限增长，没有配置重置策略

解决：

{
  session: {
    dmScope: "per-channel-peer",
    reset: {
      mode: "idle",        // 空闲时自动重置
      idleMinutes: 120,    // 2小时无活动
    },
  },
}

同时检查是否有异常大的会话：

openclaw session stats --top 10

坑5：多实例部署时配置隔离不彻底

现象：启动两个Gateway实例（不同端口），修改一个的配置，另一个也受影响

原因：两个实例共享了 ~/.openclaw/ 目录

解决：用 OPENCLAW_STATE_DIR 隔离状态目录：

# 实例1
OPENCLAW_STATE_DIR=~/.openclaw-instance1 openclaw gateway start

# 实例2
OPENCLAW_STATE_DIR=~/.openclaw-instance2 openclaw gateway start

对应第4篇：onboard向导在环境诊断阶段也会检查 OPENCLAW_STATE_DIR 的设置，详见《[onboard新手引导全流程拆解](./第04篇-onboard 新手引导全流程拆解.md)》。

FAQ

Q：Gateway是单进程还是多进程？

A：正常运行时是双进程——主进程 + 工作进程。加上Watchdog，看起来是三个进程。在 ps 中你会看到：

$ ps aux | grep openclaw
user  48290  ... openclaw gateway start     ← 主进程
user  48291  ... openclaw gateway worker     ← 工作进程
user  48292  ... openclaw gateway watchdog   ← Watchdog

Q：热重载期间正在处理的请求会丢失吗？

A：不会。热加载时，进行中的请求会自然完成。只有 gateway.port/bind/auth 变更需要重启工作进程——这时候进行中的请求有10秒的优雅退出窗口。

Q：Gateway的并发上限是多少？

A：WebSocket连接数没有硬上限（受系统资源限制）。并发模型调用数受 maxConcurrent 控制，默认是3。如果用户量较大，建议调到CPU核心数的2倍。

Q：如何监控Gateway的运行状态？

A：三种方式：

1. 日志 — openclaw logs 查看实时日志
2. Control UI — 浏览器打开 http://localhost:18789
3. 健康接口 — curl http://localhost:18789/health

Q：Gateway崩溃后对话记录会丢吗？

A：不会。会话数据在每次模型响应完成后持久化到磁盘。崩溃只会丢失当前正在处理的那一条请求——已有对话和完成的消息不受影响。

总结

回顾Gateway的三大机制：

再看请求处理的六个环节：

这三个层面（启动→运行→请求），构成了Gateway从按下回车到处理消息的完整链路。

回顾开篇的三张图：

• 启动时序图（第一章）：六个阶段，对照日志定位问题
• 进程架构图（第二章）：主进程守门、工作进程干活、Watchdog看门
• 请求处理流程图（第四章）：进站→路由→会话→模型→工具→出站

运维速查：Gateway 常见故障 SOP

生产环境遇到问题时直接查这张表，按步骤操作。

下一篇预告

〖OpenClaw系列〗Control UI与WebChat使用指南

Gateway跑起来了，但还只会看日志。下一篇带你走进Control UI——这个Web界面能做什么、怎么用好它，以及和直接在Telegram聊天有什么区别。

延伸阅读：想了解 Gateway 的生产级部署方案，请看后续篇目——第56篇（性能基准测试与优化指南）、第57篇（Kubernetes 生产部署实战）、第62篇（高可用架构：多区域部署与故障转移）。

本文是系列文章第5篇，前序文章

〖OpenClaw系列〗AI网关是什么、能做什么

〖OpenClaw系列〗三种方式安装和启动OpenClaw

〖OpenClaw系列〗配置文件 openclaw.json 详解

〖OpenClaw系列〗onboard新手引导全流程拆解

📌 觉得有用？点个「在看」 👇 👨‍💻 关注「敏叔侃技术」，每周更新 OpenClaw 实战干货 ⭐ 收藏这篇文章，遇到Gateway启动问题随时翻出来对照日志排查