🦞 Clawdbot / Moltbot 深度技術研究報告

研究目標：從工程、架構與實務應用角度，全面解析 Clawdbot / Moltbot 的設計理念、系統機制與定位價值，協助 AI / DevOps / 架構師等技術讀者理解其在 AI Agent / 自動化生態系中的角色與限制。

🎯 1️⃣ 產品定位與問題定義分析

核心問題

Clawdbot（Moltbot）致力於解決傳統 AI 助手「只能聊天，無法動手」的問題。它強調：

• 持久記憶能力
• 任務執行能力（非僅回答）
• 在本地部署、自主管理的環境中持續運作

其核心宗旨：打造一位能夠執行真實任務的本地 AI 助理（The AI That Actually Does Things）。

目標使用者族群

• 技術導向用戶：AI/ML 工程師、DevOps、自動化愛好者
• 注重隱私或自託管需求者
• 開發團隊成員 / 系統整合開發者

對非技術背景使用者門檻相對偏高。

設計哲學與核心概念

定位與邊界

• 定位為 自託管 AI 中樞
• 聚焦 個人 / 小團隊級應用
• 不適合作為開放式公開 AI chatbot 平台

🧠 2️⃣ 系統架構深度拆解

模組拆解

• Gateway（控制平面）：中心協調器，負責任務排程、記憶管理、平台接入
• Agent Runtime（Pi Agent）：與 LLM 溝通，負責推理與指令輸出
• Tool Adapter（技能系統）：插件式行動層，實作真實操作
• Memory / Knowledge 層：本地 SQLite + Markdown 文檔 + 向量資料庫
• 多介面支援：CLI, Web UI, Telegram/Slack, macOS/iOS 前端

架構圖（Mermaid）

flowchart LR
    subgraph UserDevices [使用者的裝置與平台]
        WA[WhatsApp] & TG[Telegram] & DC[Discord] & SL[Slack] & SI[Signal] & IM[iMessage]
    end
    WA & TG & DC & SL & SI & IM --> Gateway["Gateway 服務(控制平面)"]
    subgraph LocalHost [使用者主機]
        Gateway <-- RPC --> PiAgent["Pi Agent (AI 推理模組)"]
        Gateway --> Tools["技能/工具庫"]
        Gateway --> MemoryDB["記憶儲存"]
        Gateway --> UI["控制介面"]
    end
    subgraph CompanionApps [配套 App]
        MB[macOS Menu Bar App] & iOS[iOS App] & Android[Android App]
    end
    Gateway <-- WebSocket --> CompanionApps
    PiAgent -->|LLM API| CloudLLM[雲端 LLM 服務]
    Tools -->|系統動作| OS[主機作業系統]
    Tools -->|API存取| External["外部雲端 API"]

控制 vs 執行平面

• Gateway = 控制平面（Orchestration）
• Tool / LLM API / Shell = 執行平面（Execution）

State 管理

• 有狀態系統（Stateful）
• 維護 Session 狀態、Agent 記憶、會話歷程

擴充性設計

• 工具模組支援熱插拔（Plugin）
• 支援多 Agent 協作
• 多平台支援（Telegram / Discord / CLI）

🤖 3️⃣ Agent 與工作流模型

Agent 模型設計

• 支援單 / 多 Agent 架構
• 每 Agent 擁有獨立記憶與人格
• Agent 間訊息可透過 Gateway 傳遞

溝通與工作流特性

• 串行執行為主（Queue 模型）
• 支援條件分支、錯誤重試、人類審批
• 可進行多輪思考與多工具鏈式呼叫

任務流程圖（Mermaid）

sequenceDiagram
    participant User as 使用者
    participant Gateway as Gateway
    participant Agent as AI Agent
    participant Tool as 技能工具
    User->>Gateway: 發送訊息 / 任務指令
    Gateway->>Agent: 傳遞上下文與任務
    Agent-->>Gateway: 查詢記憶 / 工具列表
    Agent->>Agent: LLM 推理
    alt 需要工具
        Agent->>Tool: 發出工具呼叫
        Tool-->>Agent: 回傳執行結果
    end
    Agent->>Gateway: 返回最終回覆內容
    Gateway-->>User: 將回覆傳送回使用者

🧠 4️⃣ 記憶與知識系統設計

記憶體層級分類

技術實作

• 本地 Markdown 檔（如 memory/YYYY-MM-DD.md、MEMORY.md）
• 嵌入模型產生向量（預設使用本地 embedding）
• SQLite + FTS5 + sqlite-vec 實作混合檢索（向量 + 關鍵詞）
• 檢索 API：memory_search("query")
• 寫入 API：自動或手動將資訊寫回 MEMORY.md

記憶檢索流程圖（Mermaid）

flowchart TD
    A[每日對話紀錄Markdown 檔] --> B[長期記憶 MEMORY.md]
    B --> C[Embedding 向量生成 + SQLite]
    C -->|查詢| D[[檢索結果 Snippets]]
    D --> E(組入 Prompt)
    E --> F[LLM 回應]
    F -->|需要儲存| B

🔧 5️⃣ LLM 與 Tool 整合

LLM 支援類型

• Claude (Anthropic) – 官方推薦
• GPT (OpenAI)
• 本地模型：Ollama、LocalAI、GGUF 等
• 自定義 Endpoint 介接

Prompt 管理抽象

• 工具定義格式列入 System Prompt
• Agent 輸出格式為 <<tool: "toolname", args: {...}>>
• Gateway 解析並觸發對應工具程式碼
• 分層組裝 Prompt：Identity、Tools、Memory

Tool 呼叫機制

• Gateway 中控驗證與執行
• 子進程 / HTTP API / Plugin 函數執行
• 工具結果回饋回 LLM 決策循環
• Sandbox 支援、可限制高風險指令

安全與錯誤處理

• 工具錯誤自動回饋給 LLM 分析
• 支援重試與錯誤提示
• 可啟用 Human-in-the-loop 審批
• Prompt injection 防禦 / API Key 安全封裝

💡 6️⃣ 實務應用情境

🧱 7️⃣ 成熟度與風險分析

專案成熟度

• GitHub 星數 80k+、社群活躍
• 頻繁更新但變動大（追 release 節奏需注意）
• 單開發者為主（已組織化，Bus factor 正在改善）

技術限制與風險

• 多用戶同時支援尚不成熟
• 缺乏高可用 / 多節點協作模式
• 安全風險需由部署者自行管理
  • Prompt Injection
  • Shell 權限 / API Key 洩露
  • 外部 webhook / channel 安全性

✅ 總結：Moltbot 適合與不適合的情境

適合：

• 技術使用者打造私有化 AI 助理
• DevOps / 自動化高度整合場景
• 有記憶需求的任務執行型 AI

不適合：

• 追求即開即用的大眾使用者
• 對系統穩定性與安全要求極高的企業
• 無自維護能力者（需熟悉 CLI / 系統配置）

Moltbot 並非萬能，但對於具備技術能力並想打造「會動手」AI 助手的使用者來說，它是現階段最完整、最開放的自託管選擇之一。