【原理篇】OpenClaw 架构详解：Gateway + Agent + Skill 如何协同工作

前面几篇文章讲完了"是什么"和"怎么用"，这篇文章讲"是怎么跑起来的"。OpenClaw 的架构像一座分工明确的工厂：Gateway 是门卫，Agent 是工人，Skill 是工具箱，Channels 是不同的入口。理解了这套协作机制，你就能更自如地配置、扩展和排障。

常威正在打来福

476人浏览 · 2026-05-06 10:42:23

常威正在打来福 · 2026-05-06 10:42:23 发布

前面几篇文章讲完了"是什么"和"怎么用"，这篇文章讲"是怎么跑起来的"。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” → 触发 pdf Skill
“查天气” → 触发 weather Skill
“写公众号” → 触发 wechat-article-drafter Skill

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 消息队列状态