每個軟體專案都有那麼一個頓悟的時刻：你意識到自己一直在做錯誤的事。你花了好幾週寫訊息路由器、工具執行引擎、對話狀態管理器和重試系統——然後你發現 AI 供應商早就把這些全部處理好了，而且比你做得更好，只需要一個 API 呼叫。
這個頓悟就是 NanoClaw 架構的起源。整個核心——把一條 WhatsApp 訊息轉變成一個具備工具使用、網頁瀏覽、檔案存取和多輪對話能力的 AI agent 回應——大約只有 500 行 TypeScript。不是 500 行膠水程式碼去引入 50,000 行的框架。就是 500 行，全部，建立在 Anthropic 的 Claude Agent SDK 之上。
第一次閱讀原始碼的開發者通常先是不敢置信，接著問出那個關鍵問題：「其餘的部分在哪裡？」
Claude Agent SDK 到底做了什麼
大多數 AI agent 框架之所以存在，是因為在過去，語言模型 API 是無狀態且簡單的。你送出一個 prompt，得到一個回應。如果你想要工具使用，你得自己建構工具執行迴圈。如果你想要多輪對話，你得自己管理訊息歷史。如果你想讓模型在多個工具之間做選擇，你得自己建構路由邏輯。
Claude Agent SDK 從根本上改變了這個等式。SDK 不只是呼叫 Claude API——它運行一個 agent 迴圈。你給它一個系統提示、一組工具和一條使用者訊息。SDK 處理其餘的一切：它把訊息送給 Claude、接收回應、檢查 Claude 是否想使用工具、執行工具、把結果送回 Claude，然後重複直到 Claude 產生最終回應。整個工具使用迴圈——大多數框架花數千行來實作的東西——就是一個函式呼叫。
這不是一個薄薄的包裝層。SDK 處理串流、重試邏輯、token 計數和對話狀態。它管理 Claude 和工具之間跨多個回合的來回互動，處理工具執行失敗和 context window 限制等邊界情況。NanoClaw 不需要實作的那些複雜度並沒有消失——它被推到了一個由 Anthropic 自家工程團隊維護的、經過充分測試的 SDK 中。
NanoClaw 實際上建構了什麼
如果 SDK 處理了 agent 迴圈，那 NanoClaw 的 500 行到底在做什麼？答案是迴圈周圍的一切——那些專屬於運行個人 AI 助理而非僅僅呼叫 API 的部分。 第一個職責是頻道整合。NanoClaw 透過 Baileys 函式庫連接 WhatsApp、接收訊息，並將它們路由到正確的 agent 容器。這是「有人在 WhatsApp 上發了一條訊息」和「一個 agent 需要處理這條訊息」之間的黏合劑。這不是複雜的程式碼，但卻是不可或缺的——沒有它，agent 就無法在使用者已經在的地方觸及他們。
第二個職責是容器編排。每個 agent 對話都在自己的 Linux 容器中運行——macOS 上用 Apple Container，Linux 上用 Docker。NanoClaw 啟動容器、掛載正確的目錄、透過 stdin 傳遞機密，並收集回應。這就是防止被入侵的 agent 存取沙箱外任何東西的安全邊界。容器生命週期管理大約 80 行程式碼，但這 80 行就是一個可以被信任處理真實憑證的 agent 和一個不能被信任的 agent 之間的差別。
第三個職責是持久化記憶。NanoClaw 維護一個 SQLite 資料庫來儲存對話、群組狀態和排程任務。每個 WhatsApp 群組都有自己的 CLAUDE.md 檔案，作為 agent 對該群組的長期記憶。記憶系統很簡單——這是刻意的——因為記憶的複雜部分（決定什麼是相關的、要回想什麼、如何使用上下文）是由 Claude 本身處理的。
第四個職責是排程任務。使用者可以要求 agent 在特定時間做事——「下午 3 點提醒我」或「每天早上檢查這個網站」。NanoClaw 的類 cron 排程器在正確的時間觸發 agent 容器，這是一個小但真正實用的功能，把一個被動的聊天機器人變成一個主動的助理。
為什麼 500 行很重要
行數不是虛榮指標。它直接衡量了維護面、bug 面，以及理解系統所需的認知負擔。
當 NanoClaw 核心出現 bug 時，它可能存在的範圍只有 500 行。一個開發者可以在一小時內讀完整個程式碼庫，理解每一個決策。相比之下，核心程式碼有 50,000 行的框架——找一個 bug 意味著要穿越抽象層、理解外掛系統，並追蹤執行路徑通過層層間接引用，而這些間接引用是為了支援你可能根本用不到的功能。
安全性的影響同樣具體。每一行程式碼都是潛在的漏洞。NanoClaw 500 行的核心，攻擊面比大多數框架的設定檔解析器還小。容器隔離、stdin 機密傳遞、掛載白名單——這些安全功能的實作程式碼小到可以在一個下午完整審計完畢。
而升級的故事也很簡單。當 Anthropic 發布新版 Claude Agent SDK，帶來更好的工具使用、更快的串流或新功能時，NanoClaw 只需更新一個依賴就能獲得這些改進。不需要更新框架抽象層來暴露新的 SDK 功能。SDK 就是框架。
不建構的哲學
NanoClaw 架構中最困難的部分不是建構它——而是決定什麼不要建構。自訂工具執行引擎、精密的記憶檢索系統、多供應商抽象層、外掛市集——這些都是其他框架已經建構的東西，也都是 NanoClaw 刻意不做的。 每一個這樣的功能都會增加數千行程式碼、數十個潛在 bug，以及數週的維護負擔。而且每一個都會重複 Claude Agent SDK 已經提供的功能，或是 Claude 本身比任何手寫程式碼都處理得更好的功能。
結果是一個專案，其中有趣的決策是架構性的，而非實作性的。容器應該如何隔離？機密應該如何傳遞？記憶應該如何按群組劃分？這些才是對個人 AI 助理真正重要的問題，也是 NanoClaw 這 500 行程式碼致力於回答的問題。
下次你評估 AI agent 框架時，不要數功能，數行數。行數最少的框架不是最沒能力的——它可能是那個對問題理解得夠深，知道該讓 AI 供應商來做重活的框架。