夜雨聆风
【原理篇】OpenClaw 架构详解:Gateway + Agent + Skill 如何协同工作
【原理篇】OpenClaw 架构详解：Gateway + Agent + Skill 如何协同工作
前面几篇文章讲完了”是什么”和”怎么用”，这篇文章讲”是怎么跑起来的”。OpenClaw 的架构像一座分工明确的工厂：Gateway 是门卫，Agent 是工人，Skill 是工具箱，Channels 是不同的入口。理解了这套协作机制，你就能更自如地配置、扩展和排障。
一、先从一道面试题说起
有人问：OpenClaw 和普通 AI 对话有什么本质区别？
普通 AI 对话，模型直接输出回答，结束。
ounter(line用户 → AI模型 → 回答
OpenClaw 的运行链路要复杂得多：
ounter(line用户 → Channel → Gateway → Agent → Skill/工具 → 模型 → 回复
这中间多了几层：Channel 负责接收消息、Gateway 负责路由和安全、Agent 负责调度 Skill 和工具、Skill 提供专业能力、模型负责生成内容。
每层各司其职，分工协作。这就是它比普通 AI 更强大的原因。
帮忙点一下吧，非常感谢！\(≧▽≦)/
二、核心架构图：一张图看清全局
三、Gateway：永不关门的”门卫”
3.1 Gateway 是什么？
Gateway 是 OpenClaw 的 HTTP/WebSocket 服务器，运行在本地端口 28789。它像一栋大楼的门卫，负责：
-
接收消息：所有入口（微信、Telegram、Web）的消息都先到 Gateway -
路由分发：把消息转发给对应的 Agent -
身份验证：检查 Token，确保是合法请求 -
会话关联：把消息归到正确的会话 -
心跳监控：检测各 Channel 是否存活，断线自动重连
3.2 Gateway 的配置
从真实配置文件中提取关键参数：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line{"gateway": {"port": 28789, // 监听端口"mode": "local", // 本地模式（非远程代理）"bind": "loopback", // 仅监听本地（127.0.0.1）"auth": {"mode": "token", // Token 认证"token": "457f2c..." // 认证 Token},"controlUi": {"allowedOrigins": ["null", "file://"]},"tailscale": {"mode": "off" // 未使用 Tailscale}}}
bind 模式说明：
|
|
|
|
|---|---|---|
loopback |
|
|
lan |
|
|
tailnet |
|
|
auto |
|
|
⚠️ 重要：默认
loopback模式，Gateway 只在本地监听。即使别人知道你的端口，也无法从外部访问。这是安全设计，不是 bug。
3.3 Gateway 的心跳监控
Gateway 内置了通道健康检查机制：
ounter(lineounter(lineounter(lineounter(lineounter(line{"channelHealthCheckMinutes": 5, // 每 5 分钟检查一次"channelStaleEventThresholdMinutes": 30, // 30 分钟无活动视为断线"channelMaxRestartsPerHour": 10 // 每小时最多重启 10 次}
这意味着：
-
如果微信连接断了，Gateway 会自动重试 -
如果重试太频繁（>10次/小时），会暂停保护，防止死循环 -
你不需要手动监控，Gateway 会自己管自己
四、Agent：调度一切的”工人”
4.1 Agent 是什么？
如果说 Gateway 是门卫，那 Agent 就是工厂里的工人——它真正处理你的请求。
OpenClaw 支持同时运行多个 Agent。从配置文件可以看到：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line{"agents": {"defaults": {"model": { "primary": "qclaw/modelroute" },"workspace": "C:\\Users\\10696\\.qclaw\\workspace","timeoutSeconds": 72000,"maxConcurrent": 3},"list": [{ "id": "main", "name": "QClaw" },{ "id": "agent-eace0fdc", "name": "智能Agent" },{ "id": "agent-71cdf34c", "name": "无不言" }]}}
当前配置了三个 Agent：
-
main：默认 Agent（QClaw），就是你现在对话的这个 -
智能Agent：专门配置了 skills 的 Agent -
无不言：另一个专用 Agent
4.2 Agent 的工作流程
当你发一条消息，Agent 的处理过程如下：
收到消息│├── 1. 理解意图：这条消息想做什么？│├── 2. 加载上下文：│ - 读取 SOUL.md（人设）│ - 读取 USER.md（用户信息）│ - 读取 MEMORY.md（长期记忆）│ - 读取今日日志│├── 3. 匹配 Skill：根据 description 找到最合适的 Skill│├── 4. 调用工具：│ - 需要文件？→ read / write│ - 需要执行命令？→ exec│ - 需要发消息？→ message│ - 需要搜索？→ web_search│├── 5. 生成回复：综合所有信息，生成最终回答│└── 6. 更新记忆：把重要信息写入记忆文件
4.3 Sub-Agent：多线程并行工作
OpenClaw 支持”子 Agent”机制，主 Agent 可以派生多个子 Agent 同时处理不同任务：
{"defaults": {"maxConcurrent": 3, // 主 Agent 同时处理 3 个任务"subagents": {"maxConcurrent": 8 // 子 Agent 最多 8 个并行}}}
使用场景：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line你：帮我查一下这三家公司的最新股价，并整理成表格主 Agent 分解任务：├── 子 Agent 1：查 A 公司股价├── 子 Agent 2：查 B 公司股价└── 子 Agent 3：查 C 公司股价三个子 Agent 并行执行，主 Agent 汇总结果生成表格
五、Channel：OpenClaw 的”入口”
5.1 Channel 是什么？
Channel 是 OpenClaw 连接外部世界的方式，就像大楼的多个入口：正门、侧门、地下车库。
当前配置了以下 Channel：
{"channels": {"wechat-access": {"enabled": true,"token": "17521d4d...","wsUrl": "wss://mmgrcalltoken.3g.qq.com/agentwss","userId": "630346413"},"openclaw-weixin": {"enabled": true,"transport": "local"}}}
-
wechat-access：微信公众号接入，通过 WebSocket 连接到腾讯服务器 -
openclaw-weixin：OpenClaw 自带的微信通道
5.2 多 Channel 同时在线
OpenClaw 支持多个 Channel 同时在线，你在任何入口说话，它都能回应：
微信说：帮我写一篇文章→ Channel 识别：wechat-access→ 路由到 Agent→ 生成回复→ 从微信回复Telegram 说：继续写→ Channel 识别：telegram→ 路由到同一个 Session→ Agent 知道是同一个对话→ 继续生成
Session 的 dmScope 策略：
{"session": {"dmScope": "per-channel-peer"}}
per-channel-peer 意思是：同一个人的不同 Channel 消息，进入同一个会话上下文。这样你在微信说完，在 Telegram 继续，它还记得刚才说了什么。
六、Skill：Agent 的”工具箱”
6.1 Skill 的定位
Agent 是大脑，负责思考；Skill 是工具箱，负责执行具体任务。
当 Agent 遇到一个问题：
-
“处理 PDF” → 触发 pdfSkill -
“查天气” → 触发 weatherSkill -
“写公众号” → 触发 wechat-article-drafterSkill
Skill 提供了：
-
操作步骤（SKILL.md） -
可执行脚本（scripts/） -
参考文档（references/） -
输出模板（assets/）
6.2 Skill 的加载机制
Skill 从多个目录加载：
{"skills": {"load": {"extraDirs": ["D:\\application\\QClaw\\resources\\openclaw\\config\\skills", // 内置"~/.agents/skills", // 预留"C:\\Users\\10696\\.qclaw\\skills", // 用户安装"~/.openclaw/workspace/skills" // 工作区]},"entries": {"pdf": { "enabled": true }, // 启用的 Skill"xlsx": { "enabled": true },"online-search": { "enabled": true },"weiyun": { "enabled": false } // 禁用的 Skill}}}
三层存储：
|
|
|
|
|---|---|---|
|
|
|
|
~/.qclaw/skills/ |
|
|
~/.openclaw/workspace/skills/ |
|
|
💡 最佳实践：自己写的 Skill 放到
~/.qclaw/skills/，不要放到内置目录。
七、Plugin：扩展核心能力
7.1 Plugin 是什么？
Plugin 在比 Skill 更底层的位置，扩展 OpenClaw 的核心功能。
{"plugins": {"enabled": true,"allow": ["wechat-access", // 微信接入"qclaw-plugin", // QClaw 核心插件"browser", // 浏览器控制"openclaw-weixin", // 微信通道"lossless-claw" // 无损上下文（LCM）],"slots": {"contextEngine": "lossless-claw"},"entries": {"lossless-claw": {"config": {"dbPath": "C:\\Users\\10696\\.qclaw\\memory\\lossless\\lcm.db","contextThreshold": 0.6,"freshTailCount": 16,"incrementalMaxDepth": 5}}}}}
7.2 五个核心 Plugin 详解
Plugin 1：lossless-claw（无损上下文）
这是 OpenClaw 最核心的 Plugin 之一，负责”上下文压缩”。
当对话历史太长时，会触发压缩：
{"dbPath": "C:\\Users\\10696\\.qclaw\\memory\\lossless\\lcm.db","contextThreshold": 0.6, // 占用 60% 时触发压缩"freshTailCount": 16, // 保留最近 16 条消息不压缩"incrementalMaxDepth": 5 // 最多压缩 5 层深度}
压缩后的对话变成”摘要”，存入 SQLite 数据库（lcm.db），需要时可以通过搜索找回。
Plugin 2：browser（浏览器控制）
{"browser": {"enabled": true,"defaultProfile": "openclaw"}}
提供浏览器自动化能力：打开网页、点击、填表、截图、爬取。
Plugin 3：wechat-access / openclaw-weixin（微信接入）
两个 Plugin 都负责微信接入，只是方式不同：
-
wechat-access：通过腾讯 WebSocket 服务器接入（需要配置 token） -
openclaw-weixin：OpenClaw 自带的微信接入方式
Plugin 4：qclaw-plugin（QClaw 核心插件）
QClaw 平台的核心功能插件。
八、Model：OpenClaw 的”大脑”
8.1 模型配置
{"models": {"mode": "merge","providers": {"qclaw": {"baseUrl": "http://127.0.0.1:19000/proxy/llm","api": "openai-completions","models": [{"id": "modelroute","name": "modelroute","contextWindow": 200000,"maxTokens": 8192}]},"mimo-plan": {"baseUrl": "xxxx","apiKey": "tp-...","api": "openai-completions","models": [{"id": "xxxx"}]}}}}
8.2 模型路由
用户请求│▼qclaw 本地代理 (127.0.0.1:19000)│├──→ Hunyuan（腾讯混元，免费额度）├──→ Qwen（阿里通义，便宜好用）├──→ DeepSeek（性价比高）└──→ OpenRouter（聚合多模型）
本地代理负责智能路由，根据任务类型、负载、费用自动选择最优模型。
8.3 模型与 Agent 的关系
Agent（主逻辑）│├── 理解你的意图（用模型）├── 调度 Skill（纯逻辑）├── 生成回复（用模型）│└── 调用工具（read/write/exec）
Agent 和模型的关系：Agent 是调度者，模型是大脑。Agent 决定”做什么”，模型负责”怎么说”。
九、Session：对话的”容器”
9.1 Session 是什么？
Session 是对话的容器，每次你和 OpenClaw 的一次完整对话是一个 Session。
{"session": {"reset": {"mode": "idle","idleMinutes": 525600 // 约 1 年无活动才重置},"maintenance": {"pruneAfter": "365d", // 365 天后清理"maxEntries": 1000000, // 最多 100 万条记录"rotateBytes": "1gb" // 日志满 1GB 时轮转}}}
Session 的生命周期：
创建 Session│├── 对话进行中（积累上下文）│├── 上下文太满 → lossless-claw 压缩 → 存入 lcm.db│├── Session 长期不活跃（1 年）→ 自动重置│└── 365 天后 → 历史记录清理
9.2 Session 的消息队列
{"messages": {"queue": {"mode": "followup"}}}
followup 模式：消息按顺序处理，不会并发混乱。
十、工具集：Agent 的”手和脚”
10.1 内置工具
OpenClaw 提供了一系列内置工具，Agent 可以直接调用：
|
|
|
|---|---|
read |
|
write |
|
exec |
|
browser |
|
web_search |
|
web_fetch |
|
message |
|
cron |
|
gateway |
|
session_* |
|
nodes |
|
10.2 循环检测
为了防止 Agent 陷入死循环，系统内置了循环检测：
{"tools": {"loopDetection": {"enabled": true,"historySize": 30, // 检测最近 30 条"warningThreshold": 10, // 10 次重复 → 警告"criticalThreshold": 20, // 20 次重复 → 阻止"globalCircuitBreakerThreshold": 50,"detectors": {"genericRepeat": true, // 检测重复模式"knownPollNoProgress": true, // 检测无进展轮询"pingPong": true // 检测来回弹跳}}}}
这意味着：如果 Agent 陷入”说同样的话”的循环，系统会主动干预，防止资源浪费。
十一、数据流：一次完整请求的旅程
现在我们把整个架构串起来，看一次完整请求的旅程：
十二、实战：如何排查一个请求”卡在哪了”
理解了架构，排查问题就简单了。
问题：消息发出去没有回复
按层级排查：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line第 1 步：Channel 正常吗？→ 检查 wechat-access 是否在线→ Gateway 心跳监控应该在 5 分钟内检测第 2 步：Gateway 收到请求了吗？→ Gateway 日志有没有该消息的记录→ port 28789 是否正常监听第 3 步：Agent 在处理吗？→ 看 Session 是否在活跃状态→ 是否有 Skill 匹配→ 是否有工具调用卡住第 4 步：模型返回了吗？→ 本地代理 127.0.0.1:19000 是否响应→ 模型是否超时（默认 72000 秒很长）第 5 步：回复发出去了吗？→ Channel 心跳正常吗→ Session 消息队列状态
问题：回复”答非所问”
通常是因为：
-
Skill 匹配错误（触发了不相关的 Skill） -
上下文被错误压缩（lossless-claw 压缩掉了关键信息） -
Session 错乱（多 Channel 场景下 Session 混淆）
问题：Session 历史丢失
可能原因：
-
Session 超过 365 天被清理 -
手动 reset Session -
上下文压缩太激进（可以调低 contextThreshold）
十三、架构设计的哲学
设计原则一：分层解耦
Gateway、Agent、Skill、Model 每层独立，通过标准接口通信。这意味着你可以替换任意一层而不影响其他层——换模型不用动 Agent，换 Skill 不用动 Gateway。
设计原则二：本地优先
-
数据存在本地（~/.qclaw/workspace/） -
模型通过本地代理路由（127.0.0.1:19000） -
Gateway 默认监听 loopback -
记忆不上传云端
设计原则三：安全内置
-
Token 认证、IP 白名单、循环检测 -
Skill 有启用/禁用开关 -
Plugin 有 allowlist -
敏感信息在配置中被脱敏（ __OPENCLAW_REDACTED__）
设计原则四：可观测性
-
心跳监控自动检测断线 -
Session 维护有日志和阈值 -
LCM 提供搜索和压缩状态 -
循环检测防止死锁
写在最后
OpenClaw 的架构体现了几个核心理念：
-
分层解耦：每层各司其职，通过标准接口通信 -
本地优先：数据不离手，隐私有保障 -
安全内置：认证、检测、隔离，安全不是补丁而是设计 -
可扩展：Skill、Plugin、Agent 都支持扩展
理解了这套架构，你就从”会用”升级到了”会调”——遇到问题能定位，配置需求能实现，想加功能知道从哪下手。
系列文章预告：
-
进阶篇（待完成）：定时任务 + 子 Agent 自动化 -
实战篇（待完成）：用 OpenClaw 搭建你的”数字打工人”
👨💻 H先生出品 | 专注 AI 工具与效率提升