【原理篇】OpenClaw 架構詳解：Gateway + Agent + Skill 如何協同工作

作者：H先生出品

日期：2026年5月6日上午2:37

來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點高亮

OpenClaw 架構詳解：Gateway、Agent、Skill 三層分工，由「會用」升級到「會調」

整理版摘要

呢篇文章係 H 先生出品，專注 AI 工具與效率提升，係 OpenClaw 系列嘅原理篇。作者先後講咗「係咩」同「點用」，今次集中解釋成個系統「點樣跑起嚟」。佢用一座工廠做比喻：Gateway 係門衞、Agent 係工人、Skill 係工具箱、Channel 係唔同入口，成個協作機制令 OpenClaw 比普通 AI 對話更強大。整體結論係：只要理解咗呢套分層架構，你就能更自如地配置、擴展同排障，由單純嘅用家變成可以調校系統嘅高手。

文章詳細拆解每個零件嘅職責同互動方式，包括 Gateway 嘅路由同心跳監控、Agent 嘅工作流程同子 Agent 並行機制、Channel 嘅多入口支援同 Session 管理、Skill 嘅加載同三層存儲、Plugin 嘅核心擴展能力、Model 嘅路由同代理等。作者仲提供咗實戰排查方法，教你點樣逐層揾出請求卡住嘅位置，同埋常見問題如答非所問或歷史丟失嘅可能原因。

最後總結咗四個設計原則：分層解耦、本地優先、安全內置、可觀測性。呢啲原則唔單止令系統穩定可靠，仲令擴展同維護變得簡單。跟住呢篇文章，你可以由「識用」進化到「識調」，遇到問題有方向、想加功能知從邊度入手。

OpenClaw 同普通 AI 對話嘅本質差異在於多層架構：用戶 → Channel → Gateway → Agent → Skill/工具 → 模型 → 回覆，每層各司其職，分工協作。
Gateway 係永不關門嘅門衞，負責接收消息、路由分發、身份驗證、會話關聯同心跳監控；默認 loopback 模式令只有本機可以訪問，安全係設計一部分。
Agent 係調度一切嘅工人，收到消息後會理解意圖、加載上下文（SOUL.md、USER.md、MEMORY.md）、匹配 Skill、調用工具、生成回覆，仲可以派生子 Agent 並行處理多個任務。
Skill 係 Agent 嘅工具箱，提供操作步驟、可執行腳本同參考文檔；Skill 從內置目錄、用戶安裝目錄同自定義工作區三層加載，自己寫嘅 Skill 最好放喺 ~/.qclaw/skills/。
排查請求卡住嘅方法係逐層檢查：Channel 是否在線 → Gateway 日誌有冇記錄 → Agent 有冇處理 → 模型有冇回覆 → 回覆有冇發出；常見問題包括 Skill 匹配錯誤、上下文壓縮太激進、Session 錯亂等。

整理重點

核心架構：由普通對話到多層協作

普通 AI 對話嘅鏈路好簡單：用戶 → AI 模型 → 回答。但 OpenClaw 就複雜得多：用戶 → Channel → Gateway → Agent → Skill/工具 → 模型 → 回覆。中間多咗幾層，每層都有特定職責，令成個系統比普通 AI 更強大。

Gateway 係門衞、Agent 係工人、Skill 係工具箱、Channel 係唔同入口

作者用一座分工明確嘅工廠做比喻：Gateway 喺本地端口 28789 運行，接收所有入口嘅消息；Agent 真正處理請求，調度 Skill 同工具；Skill 提供專業能力；模型負責生成內容。呢種分層解耦嘅設計令你可以替換任何一層而唔影響其他層。

整理重點

Gateway 與 Agent：門衞同工人點樣協作

Gateway 係 HTTP/WebSocket 服務器，負責接收消息、路由分發、身份驗證、會話關聯同心跳監控。佢預設用 loopback 模式，只監聽本地 127.0.0.1，確保只有本機可以訪問。心跳監控每 5 分鐘檢查一次 Channel 狀態，30 分鐘冇活動就視為斷線，每小時最多重啟 10 次。

Gateway 配置範例 json

{
 "gateway": {
 "port": 28789,
 "mode": "local",
 "bind": "loopback",
 "auth": {
 "mode": "token",
 "token": "457f2c..."
 },
 "controlUi": {
 "allowedOrigins": ["null", "file://"]
 },
 "tailscale": {
 "mode": "off"
 }
 }
}

Agent 係真正嘅工人，收到消息後會理解意圖、加載上下文（SOUL.md、USER.md、MEMORY.md）、匹配 Skill、調用工具、生成回覆，最後更新記憶。

Agent 同時支持主 Agent 同子 Agent 並行工作，主 Agent 最多同時處理 3 個任務，子 Agent 最多 8 個並行

例如你叫佢查三間公司嘅股價，主 Agent 會拆分成三個子 Agent 並行執行，再彙總結果生成表格。

整理重點

Channel 同 Skill：多入口接入與專業工具箱

Channel 係 OpenClaw 連接外部世界嘅方式，好似大樓嘅多個入口。目前支援微信公眾號（透過 WebSocket 連接騰訊伺服器）同 OpenClaw 自帶嘅微信通道。多個 Channel 可以同時在線，而且 Session 嘅 dmScope 策略係 per-channel-peer，即係同一個人喺唔同 Channel 講嘅話會進入同一個會話，記得之前講過嘅內容。

Channel 嘅心跳監控同自動重連機制確保連線穩定

Skill 係 Agent 嘅工具箱，負責執行具體任務。當 Agent 遇到「處理 PDF」就會觸發 pdf Skill，「查天氣」就觸發 weather Skill。每個 Skill 包含操作步驟（SKILL.md）、可執行腳本（scripts/）、參考文檔（references/）同輸出模板（assets/）。

Skill 加載目錄層級 json

{
 "skills": {
 "load": {
 "extraDirs": [
 "D:\\application\\QClaw\\resources\\openclaw\\config\\skills",
 "~/.agents/skills",
 "C:\\Users\\10696\\.qclaw\\skills",
 "~/.openclaw/workspace/skills"
 ]
 },
 "entries": {
 "pdf": { "enabled": true },
 "xlsx": { "enabled": true },
 "online-search": { "enabled": true },
 "weiyun": { "enabled": false }
 }
 }
}

Skill 從三層目錄加載：內置目錄（應用自帶）、用戶安裝目錄（~/.qclaw/skills/）同自定義工作區。最佳做法係自己寫嘅 Skill 放喺 ~/.qclaw/skills/，咁樣更新時唔會被覆蓋。

整理重點

Plugin、Model 同工具集：擴展核心能力

Plugin 喺比 Skill 更底層嘅位置，擴展 OpenClaw 嘅核心功能。最核心嘅 Plugin 係 lossless-claw（無損上下文），當對話歷史太長時會觸發壓縮，將舊對話變成摘要存入 SQLite 數據庫，需要時可以搜索找回。

lossless-claw 嘅 contextThreshold 設為 0.6，即係佔用 60% 上下文時就開始壓縮，保留最近 16 條消息唔壓縮

其他重要 Plugin 包括 browser（瀏覽器自動化）、wechat-access（微信接入）、qclaw-plugin（核心插件）。Model 方面，OpenClaw 透過本地代理（127.0.0.1:19000）智能路由到 Hunyuan、Qwen、DeepSeek 或 OpenRouter，根據任務類型同負載自動揀選最優模型。

Agent 係調度者，模型係大腦；Agent 決定「做咩」，模型負責「點講」

工具集方面，內置咗 read、write、exec、browser、web_search、message、cron 等十幾種工具。為咗防止 Agent 陷入死循環，系統有循環檢測機制：檢測最近 30 條消息，10 次重複就警告，20 次重複就阻止，仲有 globalCircuitBreakerThreshold 做最終保護。

整理重點

實戰排查與設計哲學：由識用到識調

理解咗架構之後，排查問題就好簡單。例如消息發出去冇回覆，可以逐層檢查：Channel 係咪在線？Gateway 日誌有冇記錄？Agent 有冇處理？模型有冇回覆？回覆有冇發出？常見問題包括 Skill 匹配錯誤（觸發咗唔相關嘅 Skill）、上下文壓縮太激進（lossless-claw 壓縮咗關鍵信息）、Session 錯亂（多 Channel 場景下混淆）。

OpenClaw 嘅設計體現咗四個核心理念：分層解耦（每層獨立，可替換）、本地優先（數據喺本地，記憶唔上雲端）、安全內置（Token 認證、IP 白名單、循環檢測）、可觀測性（心跳監控、日誌、壓縮狀態）。呢啲原則令系統穩定可靠，同時方便擴展。

理解架構之後，你就可以由「識用」升級到「識調」——遇到問題能定位，想加功能知從邊度入手

【原理篇】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`	只監聽本地 127.0.0.1	本機用，最安全
`lan`	監聽局域網 IP	同局域網裝置用
`tailnet`	經 Tailscale 露出去	遠端存取，安全隧道
`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 嘅工作流程

當你 send 一條消息，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」 → 觸發 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 陷入「講同一番話」嘅循環，系統會主動介入，防止曬資源。

十一、數據流：一次完整請求嘅旅程

而家我哋成個架構串埋，睇一次完整請求嘅旅程：

十二、實戰：點樣排查一個請求「卡咗喺邊」

明咗個架構，排查問題就簡單啦。

問題：消息 send 出去冇回覆

按層級排查：

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 工具同效率提升

【原理篇】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`	僅監聽本地 127.0.0.1	本機使用，最安全
`lan`	監聽局域網 IP	同局域網設備訪問
`tailnet`	通過 Tailscale 暴露	遠程訪問，安全隧道
`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" → 觸發 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 陷入"說同樣的話"的循環，系統會主動干預，防止資源浪費。

十一、數據流：一次完整請求的旅程

現在我們把整個架構串起來，看一次完整請求的旅程：

十二、實戰：如何排查一個請求"卡在哪了"

理解了架構，排查問題就簡單了。

問題：消息發出去沒有回覆

按層級排查：

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 工具與效率提升