OpenClaw

【人工智能】OpenClaw源代码解析 | 本地网关时代 | TypeScript | Pi SDK | Agent Loop执行循环 | 消息路由 | 提示词构建 | 自动化任务分发 | 会话持久化

這份摘要將為您拆解 AI 領域熱門框架 OpenClaw 的核心運作邏輯，從原始碼的角度分析一條訊息如何從用戶端發出，最終轉化為智慧回覆的全過程。

⓵ 【容易懂 Easy Know】

想像 OpenClaw 是一個超級專業的「機器人秘書辦公室」。當你傳一句「你好」給它時，這封信並不是直接丟給後台的大老闆（AI 模型）。首先，門口的收發員會檢查你有沒有寫錯字、是不是重複寄信；接著，導覽員會根據你的身份，把你帶到專門負責的專員辦公桌前。在專員開口說話前，助理會先把你們過去所有的聊天紀錄、你寄來的圖片通通擺在桌上，甚至準備好放大鏡和筆記本。最後，專員（AI）才會根據桌上所有的資料，一字一句地寫下回覆並傳回給你。這個過程雖然不到幾秒，但背後其實經過了非常精密的專業分工！

⓶ 【總結 Overall Summary】

本影片深入剖析了 OpenClaw 的原始碼運作機制，揭示了其作為「本地優先網關平台」的本質。整個流程可歸納為以下幾個關鍵階段：

網關與監聽階段：系統啟動後，首先載入 openclaw.json 設定檔，建立與 WhatsApp 或 Telegram 等渠道的連接。透過監聽器捕捉新訊息，並執行去重、高頻合併及初步的權限過濾。
訊息標準化與路由：將混亂的原始訊息封裝成標準的 WebInboundMessage 對象。系統會根據預設的綁定規則（Bindings），決定將訊息派發給哪一個特定的智能體（Agent），並生成唯一的歷史記錄鍵值以關聯上下文。
環境裝配與前置處理：在正式呼叫 AI 前，系統會為智能體準備獨立的工作目錄，解析訊息中的圖片或連結內容。最重要的是，它會將歷史對話完整加載，並處理如 reset 或 model 等特殊指令。
執行與容錯機制：系統內建了完善的失敗重試與模型降級（Fallback）機制，並透過 API 金鑰輪詢確保服務穩定性。此外，它還會自動壓縮長對話以防止 Token 溢出。
智能體循環（Agent Loop）：透過 Pi SDK 建立流式請求。系統會構建極其詳盡的結構化提示詞（System Prompt），賦予智能體讀寫文件、執行命令等工具能力。
流式輸出與回傳：AI 生成的片段內容透過事件訂閱機制，即時推送至用戶端，形成「打字機」效果，完成整個閉環。

⓷ 【觀點 Viewpoints】

網關才是核心控制面：OpenClaw 的價值不在於 AI 本身，而是在於它構建了一套強大的網關系統，處理了鑑權、渠道適配、工具管理等「髒活累活」。
極致的提示詞工程：OpenClaw 將所有運行時資訊（環境、文件、記憶）全部結構化地塞入系統提示詞。這雖然提高了精準度，但也是導致 Token 消耗過快與潛在幻覺的主因。
生產環境的穩定性考量：原始碼中展現了多層次的容錯設計，如多密鑰輪詢、模型備援機制，這對於構建可商用的 AI 服務至關重要。
本地優先的隱私策略：所有的訊息處理、文件緩存與記憶管理均優先在本地執行，這與雲端 AI 服務有顯著的架構差異。

⓸ 【摘要 Abstract】

✅ 網關先行：OpenClaw 首先是一個統一會話與渠道管理的網關，而非單純的 AI 介面。
⚠️ 雜訊過濾：進入核心流程前，會先進行訊息去重、權限檢查與媒體文件預下載。
📌 精準路由：透過 resolveAgentRoute 實現不同用戶、不同任務的自動分流。
🧠 記憶機制：AI 的「記憶」來自於推理前將歷史對話重新載入上下文。
🛡️ 容錯體系：內建失敗重試、模型降級與多組 API Key 自動切換功能。
📂 工作區隔離：為每個智能體提供獨立目錄，確保文件操作的安全與條理。
🛠️ 工具賦能：集成代碼操作、終端執行等工具，讓 AI 具備實際解決問題的能力。
📡 流式分發：利用事件訂閱機制，實現訊息的逐段、即時回覆。
💰 成本監控：系統會自動計算每輪對話消耗的 Token 與預估美元成本。

⓹ 【FAQ 測驗】

1. 在 OpenClaw 中，訊息進入系統後的第一步重要處理是什麼？
A. 直接傳送給 GPT 模型
B. 進行訊息去重與格式標準化
C. 立即回覆用戶「正在處理中」
D. 刪除所有歷史對話
正確答案：B。系統會先進行去重、權限檢查，並將訊息標準化為內部物件。

2. OpenClaw 是如何讓 AI 擁有「長期記憶」的？
A. AI 腦袋裡天生就記得所有事情
B. 系統會在每次推理前，將存儲的歷史記錄重新加載到提示詞上下文中
C. 透過雲端資料庫直接與模型大腦同步
D. AI 不需要記憶，它會猜測用戶想說什麼
正確答案：B。AI 本身無記憶，是靠系統在推理前將歷史對話餵給模型。

3. 為什麼有些用戶反應 OpenClaw 的 Token 消耗非常快？
A. 因為模型會故意多寫廢話
B. 因為系統會將大量的運行環境、技能文檔、記憶文件都塞進系統提示詞中
C. 因為系統會重複發送相同的訊息三次
D. 因為後台在偷偷進行挖礦
正確答案：B。極致的提示詞工程雖然讓 AI 更強，但巨量的背景資訊會消耗大量 Token。

⓺ 【關鍵標籤 Hashtags】

#OpenClaw #AI智能體 #原始碼拆解 #提示詞工程 #網關系統

✡ Oli小濃縮 Summary bot 為您濃縮重點 ✡

▶

這段影片詳細解析了熱門 AI 專案 OpenClaw 的原始碼架構與運作流程。OpenClaw 不僅是一個聊天框，其核心定位是一個本地優先的智慧網關（Gateway），負責處理從訊息接入到 AI 推理的繁雜中間層工作。
以下為您整理的重點、解讀與流程總結：
核心重點整理

定位：本地優先的網關平台
- OpenClaw 的核心價值在於其控制平面（Control Plane），負責管理會話、管道、工具及事件分發，而非僅僅是調用大模型 [00:32]。
標準化流程（Normalization）
- 系統會將來自不同平台（如 WhatsApp、Telegram）的非標準訊息，統一轉換為內部可識別的 web inbound message 對象 [03:31]。
極致的提示詞工程（Prompt Engineering）
- 系統會將執行時的環境、文件、記憶、工具說明等全部結構化地拼接到「系統提示詞」中，讓模型擁有完整的上下文意識 [22:16]。
智慧體與工具調度
- 透過 Pi SDK 管理 Agent Loop，支援文件讀寫、終端命令執行、代碼編輯等複雜工具調用（Tool Use）[23:56]。
穩定性與容錯機制
- 內置了失敗重試、模型降級（Fallback）、多 API Key 輪詢以及會話持久化（記憶壓縮）機制，確保生產環境的穩定性 [13:28]。
  OpenClaw 運作流程解讀（從收到訊息到回覆）
  影片將整個過程拆解為多個關鍵階段，如下表所示：
  | 階段 | 核心功能 | 關鍵技術 / 文件 | 說明 |
  |---|---|---|---|
  | 1. 網關啟動 | 環境初始化 | automonitor.ts | 載入配置、檢查網路、建立渠道監聽（如 WhatsApp 帳號連接）[00:51]。 |
  | 2. 訊息接入 | 去重與預處理 | inbound-monitor.ts | 訊息去重、合併高頻訊息、下載媒體附件、權限檢查 [01:50]。 |
  | 3. 訊息路由 | 任務分發 | unmessage.ts | 根據規則判斷該訊息由哪個 Agent（智能體）處理，並生成唯一會話 ID [04:15]。 |
  | 4. 會話初始化 | 環境準備 | getreply.ts | 準備 Agent 獨立工作區、載入歷史對話、解析特殊指令（如 /reset）[08:02]。 |
  | 5. 執行準備 | 參數打包 | getrun.ts | 將會話上下文、模型選擇、工具環境打包成模型可執行的配置 [10:33]。 |
  | 6. 生命週期管理 | 任務調度 | agentrunner.ts | 管理 Agent 隊列，處理記憶壓縮與持久化，防止上下文溢出 [12:19]。 |
  | 7. 執行與容錯 | 容錯佈署 | execution.ts | 負責失敗重試、模型降級（Fallback）及 CLI/嵌入式模式切換 [15:12]。 |
  | 8. 核心推理 | 發起請求 | runattempts.ts | 調用 Pi SDK，正式向大模型發起請求並進入 Agent Loop（思考、行動、觀察）[20:42]。 |
  | 9. 回覆分發 | 結果輸出 | processmessage.ts | 接收流式回覆（Streaming），將訊息即時推送到原通訊平台 [25:05]。 |
  深入解讀：為什麼 OpenClaw 能「養龍蝦」？
髒活累活全包了：OpenClaw 本身不生產智能，它負責的是健全校驗、文件管理、上下文裝配、異常處理等開發者最頭痛的工程細節 [27:00]。
「龍蝦」的運作核心：透過 Agent Loop（執行循環），模型不只是在說話，而是在不斷嘗試：生成內容 -> 觸發工具（如寫代碼） -> 獲取結果 -> 繼續推理，直到任務完成 [23:56]。
效能與代價：由於它將所有環境信息都塞進提示詞，雖然讓 AI 變得很強（有完整背景知識），但也導致 Token 消耗極快，且上下文過長時偶爾會產生幻覺 [23:08]。
這部影片對於想要深入二次開發或是理解 AI Agent 落地工程實踐的開發者來說非常有價值。如需觀看原片，請點擊：OpenClaw 原始碼解析