前面几篇文章讲完了"是什么"和"怎么用"，这篇文章讲"是怎么跑起来的"。OpenClaw 的架构像一座分工明确的工厂：Gateway 是门卫，Agent 是工人，Skill 是工具箱，Channels 是不同的入口。理解了这套协作机制，你就能更自如地配置、扩展和排障。
帮忙点个关注吧，涨粉太难了(┬_┬)
一、先从一道面试题说起
有人问：OpenClaw 和普通 AI 对话有什么本质区别？
普通 AI 对话，模型直接输出回答，结束。
用户 → AI模型 → 回答
OpenClaw 的运行链路要复杂得多：
用户 → 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 的配置
从真实配置文件中提取关键参数：
{
"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 | 仅监听本地 127.0.0.1 | 本机使用，最安全 |
lan | 监听局域网 IP | 同局域网设备访问 |
tailnet | 通过 Tailscale 暴露 | 远程访问，安全隧道 |
auto | 自动选择 | 按需调整 |
⚠️ 重要：默认
loopback模式，Gateway 只在本地监听。即使别人知道你的端口，也无法从外部访问。这是安全设计，不是 bug。
3.3 Gateway 的心跳监控
Gateway 内置了通道健康检查机制：
{
"channelHealthCheckMinutes": 5, // 每 5 分钟检查一次
"channelStaleEventThresholdMinutes": 30, // 30 分钟无活动视为断线
"channelMaxRestartsPerHour": 10 // 每小时最多重启 10 次
}
这意味着：
- 如果微信连接断了，Gateway 会自动重试
- 如果重试太频繁（>10次/小时），会暂停保护，防止死循环
- 你不需要手动监控，Gateway 会自己管自己
四、Agent：调度一切的"工人"
4.1 Agent 是什么？
如果说 Gateway 是门卫，那 Agent 就是工厂里的工人——它真正处理你的请求。
OpenClaw 支持同时运行多个 Agent。从配置文件可以看到：
{
"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 个并行
}
}
}
使用场景：
你：帮我查一下这三家公司的最新股价，并整理成表格
主 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 陷入"说同样的话"的循环，系统会主动干预，防止资源浪费。
十一、数据流：一次完整请求的旅程
现在我们把整个架构串起来，看一次完整请求的旅程：
十二、实战：如何排查一个请求"卡在哪了"
理解了架构，排查问题就简单了。
问题：消息发出去没有回复
按层级排查：
第 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 工具与效率提升
