← System Design
System Design

AgenticSystem 架構全景：四個類別、五個系統的設計選擇與取捨

2026-05-28 · — views

五個系統的原始碼都讀過了，每次要設計新的 agentic system 時，我發現自己一直在問同一個問題：這個系統解的是哪一層的問題？

這不是多餘的問題。把 GenericAgent 的 while loop 和 NanoClaw 的 host delivery poll 放在同一個比較欄，就像把 HTTP server 的請求路由和 TCP 的 handshake 放在一行比——維度根本不對。

這篇文章的目的是建立一個有效的分類框架，讓你在做架構選型時先確認自己在哪一層，再決定要解決的問題。

五個系統，四個類別：

  • Agent Framework：GenericAgent、HermesAgent
  • AI Gateway：OpenClaw
  • Agent Service（Framework-hosted）：DeerFlow
  • Agent Hosting Platform：NanoClaw
AgenticSystem — Four-Layer Taxonomy
不同系統解的不是同一個問題，先確認你在哪一層
Hosting Platform
Multi-tenant · User ≠ Operator 不實作 agent loop，Host 其他 agent 作為 isolated unit 負責 credential isolation · session fault containment · recovery
NanoClaw
TypeScript · Node.js
Container-per-session · Two-DB IPC
Provider: claude / opencode / ollama
可 host ↓ agent framework 容器
AI Gateway
Single-user · Channel routing 多個訊息平台的統一入口，Agent harness 內嵌於 Gateway Plugin SDK boundary 隔離 extension 和 core
OpenClaw
TypeScript · ~530K LOC
Lane queue · Named-Method RPC
~100 channel/provider extensions
同層 · Framework-hosted service
Agent Service
Framework-hosted · Service 化部署 用 LangGraph 等 framework 定義 loop，取得 checkpoint / resume 免費 Loop 由 framework 擁有，開發者設計 state 和 tool
DeerFlow
Python · LangGraph · 3-process
StateGraph · 12-layer Middleware
LLM-driven MemoryUpdater
Framework 層 · 自己實作 loop
Agent Framework
Owns the agent loop · LLM call cycle 完全自控 直接定義 LLM call → tool dispatch → context management 最低抽象層，複雜度和自由度都最高
GenericAgent
Python · MIT · ~3K LOC
while loop ~100 LOC
5-layer text memory
Skill crystallization
HermesAgent
Python · NousResearch · ~12K LOC
run_conversation() loop
FTS5 SQLite + 8 providers
Skill nudge + Atropos RL
* NanoClaw 的 Provider 抽象讓任何 Agent Framework 都可以跑在其容器裡

Agent Framework：完全掌控 LLM Call Cycle 的代價與自由

這類系統自己實作 agent loop，完全擁有 LLM call cycle。開發者在這一層有最高的自由度，也要扛最多的工程責任。

Agent Framework 是最底層的抽象。它定義：LLM 怎麼被呼叫、tool 怎麼被 dispatch、context 怎麼被管理、session 怎麼被持久化。這些事情在 Framework 以上的層（Gateway / Service / Platform）都已經被解決或封裝，但在 Framework 層，你需要自己做。

Agent Framework 內部架構比較
GenericAgent vs HermesAgent · 同類別深度對照
GenericAgent
Python · MIT · ~3K LOC
極簡自進化
HermesAgent
Python · NousResearch · ~12K LOC
Agent OS + RL loop
Interface
CLI TUI · Streamlit · Qt Telegram · Web API task_queue async 串流
CLI TUI (prompt_toolkit) Telegram / Discord Gateway ACP (VS Code / Zed) · Cron
Loop
while turn < 40 agent_runner_loop ~100 LOC StepOutcome → should_exit history 存 client.backend，loop 只送 delta
run_conversation() loop streaming · 4 種 api_mode context compress @75% threshold parent_session_id chain（不破壞 history）
Concurrency
task_queue + worker thread 每個 agent 一個 worker display_queue async 非同步輸出
parallel tool workers ×8 per-thread interrupt set[tid] credential pool round-robin · 429 → 1h cooldown
Memory
5-layer text files L0 sys_prompt（always injected） L1 global_mem_insight.txt（目錄 index） L2 跨任務事實（agent 主動 file_read） L3 task skills / SOPs L4 session archives（蒸餾摘要） context < 30K tokens
FTS5 SQLite sessions + messages 結構化 8 pluggable MemoryProvider backends <memory-context> fence tag（不持久化） system prompt 存 DB → 跨 turn 不變（prompt cache）
Tools
9 atomic tools code_run（Python / bash / PS） file_read · file_patch · file_write web_scan · web_execute_js（CDP 真實瀏覽器） update_working_ckpt · ask_user ADB（Android）· keyboard / mouse（ljqCtrl）
40+ builtin + MCP 6 execution environments local · Docker · SSH · Modal · Daytona · Singularity AST pre-screening（不污染 import） deterministic tool call ID（preserve prompt cache） Plugin tool registration via ABC
Evolution
Skill crystallization start_long_term_update（daemon thread） 執行路徑結晶 → L3 SOP / .py L1 index 同步更新 私有技能樹，每個用戶獨立
Skill nudge + Atropos RL 每 10 次 tool-call fork background review → 判斷是否值得寫 SKILL.md trajectory 以 ShareGPT 格式儲存 batch_runner → Atropos GRPO 訓練模型本身 唯一同時走知識層 + 權重層的系統
Deploy
pip install + API key --reflect 自主運行模式 BBS 多 worker 搶單模式
CLI 直接跑 · Gateway 模式 SOUL.md · AGENTS.md domain knowledge rl_cli.py 接入 Atropos
GA 選擇理由 代碼量最小，architecture 最易理解 · 記憶完全透明（文字，可 git 版控） 適合：個人自動化、私有技能累積、低成本部署
HA 選擇理由 工具生態最豐富 · 6 種執行環境 · 唯一有模型 RL 訓練整合 適合：research agent、training data pipeline、需要 plugin 生態

GenericAgent：極簡種子

GenericAgent 的設計哲學是「不預載技能，讓它進化」。核心 ~3K 行，agent_runner_loop 本身只有 ~100 行，9 個原子工具覆蓋完整的系統控制能力（Python/bash、文件操作、CDP 真實瀏覽器注入、ADB、鍵鼠控制）。

五層記憶系統是 GenericAgent 的核心設計。L0（sys_prompt）和 L1（global_mem_insight.txt）永遠注入 context。L1 是一個目錄 index，記錄「去哪讀什麼」——這讓 context window 維持在 30K 以下：agent 主動 file_read 需要的 L2/L3/L4，不需要的不進 context。

這個設計讓記憶完全透明：所有知識都是文字檔案，可以 git 版本控制，可以直接閱讀和編輯。代價是需要 agent 主動管理讀取行為，也沒有 structured query。

Skill crystallization 是進化機制：任務完成後，agent 呼叫 start_long_term_update，執行路徑被蒸餾為 L3 SOP，L1 index 同步更新。每個用戶長出完全不同的私有技能樹——GenericAgent 沒有社群生態，進化完全本地化。

# agent_runner_loop 核心結構（~100 行）
def agent_runner_loop(client, system_prompt, user_input, handler, tools_schema, max_turns=40):
    messages = [system, user_input]
    while turn < max_turns:
        response = client.chat(messages, tools)
        for tool_call in response.tool_calls:
            outcome = handler.dispatch(tool_name, args)
            if outcome.should_exit: break
        # messages 只放新一輪的 delta
        # 完整 history 在 client.backend.history
        messages = [{"role": "user", "content": next_prompt}]

messages 只傳當前輪的 delta 這個細節很重要：完整 history 在 client.backend.history 維護，讓 context 壓縮和 session 恢復獨立於 loop 本身操作，不破壞 loop 的簡潔性。

HermesAgent：Agent OS

HermesAgent 的定位是 Agent OS，而不只是 agent runner。run_agent.py 12K 行，40+ 工具，6 種執行環境（local / Docker / SSH / Modal / Daytona / Singularity）。

System prompt 穩定性是 run_conversation 的一個關鍵設計：system prompt 存 DB，跨 turn 不重新組裝，保持字面不變，讓 Anthropic 的 prompt cache 能 hit——在大量對話的場景下，這是直接的成本節省。

Context compression 閾值是 75%：超過後不是截斷，而是建立 child session，把壓縮前的 history 用 parent_session_id 串接起來，讓知識的連續性在 session 之間傳遞。

進化雙軌是 HermesAgent 最獨特的地方：

  1. Skill nudge：每 10 次 tool-call 後，fork background daemon thread，呼叫 LLM 判斷這段對話是否值得寫進 SKILL.md，如果值得就自動寫入。
  2. Atropos RL：trajectory 以 ShareGPT 格式儲存，batch_runner.py 批次生成，接入 Atropos GRPO 更新模型本身的權重。

這是本次比較的五個系統中，唯一同時走「知識層（SKILL.md）」和「權重層（模型 GRPO 更新）」的系統。代價是基礎設施複雜度：你需要一個 Atropos 環境。

Framework 層的核心 Trade-off

決策GenericAgentHermesAgent
代碼量~3K LOC，易讀~12K LOC，功能完整
記憶透明度文字檔案，git-friendlySQLite + 抽象 providers
Context 策略分層 on-demand，<30K壓縮 + session chain
工具廣度9 個原子，覆蓋系統控制40+，6 種執行環境
進化路徑私有技能樹（文字結晶）技能 + 模型雙軌學習
部署門檻pip installCLI 可用；RL 需要 Atropos

選 GenericAgent：你要的是一個你能完全理解、修改的 agent，記憶要透明，成本要低。 選 HermesAgent：你要豐富的工具生態、多種執行環境，或者你在做 research，想要 training data pipeline。

AI Gateway：多 Channel 統一入口，Agent Harness 內嵌執行

Gateway 不是 agent framework，它是在 agent 之上的一層。核心職責是多 channel 的統一入口，agent harness 是內嵌的執行引擎，而不是設計的重心。

OpenClaw：單用戶 AI Gateway

OpenClaw 的定位是「AI that actually does things — on your devices, in your channels, with your rules」。它不只是跑 agent，它接管了你所有的訊息平台：Telegram、Discord、WhatsApp、Slack、Signal、iMessage、Email… ~100 個 extension，全部住在 pnpm workspace。

架構分成兩個平面：

Gateway（控制平面）
  WebSocket RPC（Named-Method）
  Channel lifecycle manager（exponential backoff restart）
  Config loader（Zod schema + env substitution）
  Session store · Cron · Hooks runner · Model catalog
        ↓ Named-Method RPC
Agent Harness（執行引擎）
  runEmbeddedPiAgent()
  Session Lane + Global Lane（雙層隊列）
  Model resolution → auth profile rotation
  Compaction → Context Engine
  LLM call + tool execution loop

Plugin SDK boundary 是 OpenClaw 的核心架構決策：所有 ~100 個 extension 只能透過 openclaw/plugin-sdk/* subpaths 進入 core，不能直接 import core 的任何內部模組。這個邊界讓：

  • Extension 開發者無法意外破壞 core 狀態
  • Core 可以在不通知所有 extension 的情況下重構內部
  • Plugin 的依賴邊界清晰可審計

Lane queue 解決單用戶下多 channel 的並發問題：

  • Session Lane：同一 session 的請求序列化，不並發
  • Global Lane：全局序列化閥門，可在維護時用於全暫停

這不像 NanoClaw 的 container 隔離——crash 仍然在同一個 process 裡，但 Lane 確保了請求的有序性。

Auth Profile Rotation：多個 API key round-robin，lastUsed/lastGood 排序，429 自動 cooldown，不需要手動管理 key 輪換。

執行安全：ExecApproval flow 讓 bash 執行需要 iOS push notification 確認（owner-only gating），Tool Policy 支援 allow/deny list。

OpenClaw 的設計假設是單用戶、自托管。Extension 生態非常豐富，但 multi-tenant 不是它的設計目標——Lane 系統可以序列化請求，但無法做 session 級別的 crash isolation。

Agent Service：把 Loop 所有權交給 Framework，換取什麼？

這類系統用現有 framework（LangGraph 等）定義 agent loop，把 agent 邏輯包裝成 service 部署。Loop 的所有權在 framework，開發者設計 state 和 tool，framework 負責執行。

DeerFlow：LangGraph 企業 Agent Service

DeerFlow 選擇把 LangGraph 作為執行引擎，讓 agent loop 的所有權交給 LangGraph，換取一批免費功能：ThreadState checkpoint（每 step 自動存檔）、SSE streaming（前端即時接收 token）、interrupt/resume（ClarificationMiddleware 可以暫停 graph 等待用戶輸入）。

三進程部署架構：

Nginx (port 2026)
  /api/langgraph/* → LangGraph Server (port 2024)
  /api/*           → Gateway API (port 8001, FastAPI)

LangGraph Server:
  StateGraph: call_model ↔ tools_node
  ThreadState checkpointing
  SSE streaming

Gateway API:
  Assistants CRUD · Threads management
  RunManager · MCP hot-reload
  Skills CRUD · Memory CRUD

12 層 Middleware 鏈是 DeerFlow 的 observability 和 policy enforcement 層：

Logging → Tracing → ContextInjection → RateLimit → Guardrail
→ Memory → LoopDetection → Summarization → TodoList
→ SubagentLimit → ImageContext → Clarification（最後執行）

每個 Middleware 實作兩種 hook：

  • wrap_tool_call：攔截工具呼叫前後（Guardrail、Logging）
  • after_model：模型輸出後執行（LoopDetection、Clarification）

ClarificationMiddleware 的 Command(goto=END) 是 LangGraph 的 human-in-the-loop 機制：graph 暫停，checkpoint 保存當前狀態，用戶下次輸入後 resume，而不是重新開始。

LLM-driven MemoryUpdater：不是 rule-based 更新記憶，是讓 LLM 分析每次對話後 async 更新。記憶分三區：user（用戶偏好）/ history（互動歷史）/ facts（知識事實）。每條 fact 有 confidence score，correction 信號會強制更新，reinforcement 信號提升信心值，超過 100 條後驅逐低信心 fact。

MCP Hot-reload：ExtensionsConfig 監聽 mtime 變化，配置更新後自動 reinit MCP client，不需要重啟 service。

選擇 DeerFlow 意味著：你接受 LangGraph 的 framework coupling（升級風險、bundle 大小、import overhead），換取 checkpoint/resume/SSE 不用自己實作，以及 12 層 Middleware 鏈帶來的立即可用的 observability。適合需要快速落地企業 conversational AI 的場景，不適合需要深度定制 loop 行為的場景。

Agent Hosting Platform：不實作 Loop，解決多租戶隔離問題

Platform 不實作 agent loop，它 host 其他 agent 作為 isolated unit。核心職責是：credential isolation、session fault containment、recovery。

NanoClaw：Multi-Tenant Agent Hosting Platform

NanoClaw 的問題定義和前三類完全不同：它不問「agent 怎麼更強」，而是問「一個有 bash 能力的 agent，怎麼安全地活在不信任的多租戶環境裡」。

用戶不是操作者是整個設計的前提。Alice 的 agent 在 Telegram 群組裡 crash，不應該影響 Bob 的對話。operator 通常不在值守，agent 要自己恢復。API key 不能讓有 bash 能力的 agent 拿到。

Container-per-session 實現真正的 session 隔離：

Host Process (Node.js)          Container (Bun + Claude SDK)
────────────────────            ────────────────────────────
inbound.db (RW)                 inbound.db (RO)
  messages_in ────────────────→  poll pending rows
  delivered                      mark processing

outbound.db (RO)                outbound.db (RW)
  messages_out ←───────────────  write AI responses
  deliver to channel             heartbeat touch

Single writer per file 原則消除寫入競爭：host 只寫 inbound.db，container 只寫 outbound.db。容器 crash 從「系統失敗」變成「可調度事件」——訊息留在 DB，host sweep 按 exponential backoff 重試，不影響其他 container。

Credential isolation：ANTHROPIC_API_KEY 永遠不進容器 env，OneCLI HTTPS Proxy 在請求層注入。env | grep ANTHROPIC 在容器內找不到任何東西。沒有 OneCLI gateway 直接拒絕 spawn，不是 fallback，是硬停。

Session persistence + Continuation：容器 ephemeral，session 狀態在 DB。init event 收到的瞬間就寫入 continuation ID（不等 result），讓 mid-turn crash 後能從中斷點 resume，不是重新開始一個全新的 Claude session。

Provider 抽象：resolveProviderName() → 'claude' | 'opencode' | 'ollama'，per-agent-group 設定。同一個 NanoClaw 安裝，Alice 的 agent 用 Claude，Bob 的用 OpenCode，Carol 的用本地 Ollama。

Self-Mod + Approval Flow 讓能力邊界由人控制：agent 透過 MCP tool 提案（install_packages / add_mcp_server），host 發 approval card 到 channel，admin 點 approve 後 host 執行 docker build 或 config update，kill 舊 container，下次訊息用新 image 啟動。agent 有能力，但沒有執行的權力。

五個系統的共通架構決策（ADR）

ADR-001：Session 隔離層次

不同的隔離層次有不同的代價：

隔離層次機制crash 影響範圍代價
Process-bound共享 process，無隔離整個 process零 overhead
Thread-leveltask_queue worker同 process 內最小 overhead
Lane queueper-session 序列化同 process，請求有序Queue management
LangGraph ThreadStateGraph checkpoint可 resume，但同 processFramework overhead
Docker container完全 process 隔離只有該 containerSpawn latency + poll latency

選擇原則：personal use → 任何方式都夠。multi-tenant shared server → 需要 container 隔離，否則一個 unhandled exception 殃及所有 session。

ADR-002：Loop 所有權

選擇代表系統得到什麼失去什麼
自己寫 while loopGA, HA完全控制自己處理 context 壓縮、session 持久化、error recovery
LangGraph StateGraphDeerFlowcheckpoint/resume/SSE 免費Framework coupling，升級風險
Lane-queued harnessOpenClaw序列化保護 + Plugin 生態單用戶限制，需要 Gateway 架構
Container poll loopNanoClawsession 隔離Spawn latency，File IPC complexity

ADR-003：記憶模型

模型代表系統特點限制
5-layer text filesGenericAgent透明，git-friendly，agent 主動讀無結構化查詢，需 agent 管理讀取
SQL + FTS5 + pluginsHermesAgent結構化，FTS 全文搜尋，可插拔 backends較複雜的 schema 管理
LLM-driven JSONDeerFlowLLM 判斷記憶品質，confidence-scored每次對話後 LLM call（成本）
MEMORY.md + ContextEngineOpenClawMarkdown 可讀，Context Engine 可替換無自動更新機制
Two-DB IPCNanoClawIPC 穩定性設計，不是知識豐富性設計Per-session state，不是跨 session 知識庫

ADR-004：自我進化策略

進化自主程度

高 ──────────────────────────────────────────────────────── 低
  │                                                          │
  │  HermesAgent               DeerFlow          NanoClaw   │
  │  Skill nudge + GRPO        LLM fact update   Self-mod   │
  │  全自動（每10 tool-call）   全自動（每次對話）  需人工approve│
  │                                                          │
  │  GenericAgent              OpenClaw                     │
  │  agent 主動呼叫            手動安裝 ClawHub              │
  │  start_long_term_update    skills_install               │
  └──────────────────────────────────────────────────────────

自主進化適合個人場景：越用越懂你，進化方向不需要嚴格控制。 Human approve gate（NanoClaw）適合 shared server：capability 擴展有紀錄，admin 永遠在控制路徑上。 靜態 / 社群（OpenClaw ClawHub）適合穩定性優先的場景：能力是社群驗證過的，不會在運行中長出未知行為。

ADR-005：Extensibility 邊界設計

系統邊界設計意涵
GenericAgent無邊界，直接加 do_method()簡單但無保護，core 和 extension 完全耦合
HermesAgentPlugin ABC（13 hook points）+ 各元件 ABCHook-based，實作抽象介面才能注入
OpenClawPlugin SDK boundary（subpath 限制）最嚴格的邊界，extension 無法觸及 core internals
DeerFlowMiddleware ABC + Strategy ABCChain of Responsibility，新 middleware 只需實作 hook
NanoClawModule hook points + null = allow-all最小侵入，無 module 時系統跑 allow-all 模式

十個場景的選型矩陣

Scenario推薦系統關鍵理由
個人自動化，想累積專屬操作技能GenericAgent私有技能樹，<30K context，部署最簡單
Research agent + LLM training data pipelineHermesAgenttrajectory 儲存 + Atropos RL 整合，唯一走權重層的系統
自托管多 channel 個人助手（Telegram+Discord+…）OpenClaw~100 channel extensions，Plugin SDK 生態最完整
企業多輪對話 AI，需要 interrupt/resumeDeerFlowLangGraph checkpoint 免費，12-layer middleware，LLM-driven memory
團隊共用 agent server，multi-tenant，24/7NanoClawcontainer-per-session，session crash 不影響其他人
高安全要求（agent 有 bash，多用戶環境）NanoClawOneCLI credential injection，RO mount，human-approve self-mod
需要 agent 跑在 GPU cluster / remote serverHermesAgent6 種執行環境，SSH / Modal / Daytona backend
想快速 prototype，framework overhead 最低GenericAgent3K LOC，9 個原子工具，pip install 就跑
需要完全自訂 context 壓縮策略HermesAgent 或 OpenClaw兩者都有 ContextEngine ABC 可繼承替換
現有 coding agent 想加多 channel 部署NanoClawopencode 已是 built-in provider，直接用

設計選擇的 Trade-off 總覽

設計選擇換來的代價
Container isolation（NanoClaw）真正的 session 隔離，crash-safe，multi-tenantSpawn latency + poll latency + file IPC complexity
LangGraph StateGraph（DeerFlow）checkpoint / resume / SSE 免費Framework coupling，LangGraph 升級破壞風險
Plugin SDK boundary（OpenClaw）Core 不受 extension 破壞，邊界可審計Extension 開發多一層抽象
While loop 自己寫（GA / HA）最低延遲，最高控制度，架構最簡單自己處理所有 resilience，不適合 multi-tenant
5-layer text memory（GA）完全透明，git-friendly，無 DB 依賴Agent 需主動管理讀取，無結構化查詢
Atropos RL weight update（HA）模型本身在學習，不只是知識層需要 Atropos 訓練基礎設施
Human approve gate（NanoClaw）Capability 擴展有記錄，人類在控制路徑上自動化程度降低，無法全自動 self-improve
LLM-driven memory update（DeerFlow）高品質記憶更新，confidence-scored eviction每次對話後 LLM call，額外成本
9 atomic tools（GA）每個工具語意清晰，組合靈活，代碼量最小無高階抽象，需要 LLM 更多步驟完成複合任務
Lane queue（OpenClaw）Per-session 請求有序，避免並發衝突單 process，無法做 session 級 crash isolation

一句話確認你在哪一層

系統你是在問…
GenericAgent「我要一個能越用越懂我的個人 agent，架構要簡單，記憶要透明」
HermesAgent「我要一個可以訓練、工具最豐富的 Agent OS，我不介意複雜度」
OpenClaw「我要一個入口接管我所有的訊息平台，Plugin 生態要夠豐富」
DeerFlow「我要把 agent 服務化部署，要有 checkpoint 和企業級 middleware」
NanoClaw「我要在 server 上為多個人跑 agent，一個人 crash 不能影響別人」
System Design Agentic System

相關文章

Source Code
不訓練神經網路也能打出理論最高分：Heuristic Learning 的設計邏輯
2026-05-29
Implement
用 RPG 架構評估 SRE Agent：Kube Arena 設計紀錄
2026-05-28
Source Code
NanoClaw 原始碼：Multi-Tenant Agent Hosting Platform 的設計邏輯
2026-05-28