想像你有一組非常聽話的助手，每個助手都關在自己的辦公室裡，只能透過一張紙條跟外界溝通。紙條上寫著指令，助手照做，做完把結果塞回紙條。沒有共享的白板、沒有對講機、沒有後門。這聽起來很陽春，但恰恰是 OkHuman 這個 Agent 框架的核心隱喻。
OkHuman 是一個用 Go 語言從零打造的開源 Agent 運行時，由 Donald24718 開發，以 MIT 授權發布在 GitHub 上（commit 2875678）。它的核心主張只有一句話：「一個進程等於一個 Agent。」整個專案大約 15,500 行 Go 程式碼、34 個檔案，外部依賴數量是零。沒錯，連一個 require 語句都沒有，所有 HTTP 客戶端、SSE 串流解析、JSON 處理全部用 Go 標準庫手刻。在當代 Go 專案動輒拉幾十個依賴的風氣下，這種做法幾乎算是異端。
但正是這種異端氣質，讓它值得你看一眼。
為什麼一個 9 Stars 的專案值得研究
OkHuman 的 GitHub 頁面上只有 9 顆星星、2 位貢獻者、專案年齡不到一個月。如果只看社群數據，它連「有趣」都算不上。然而，工程完成度與社群規模之間存在一個巨大的落差：18 個 HTTP API 端點、9 個測試檔案、一套完整的插件體系、甚至還有預編譯的 Linux 二進位。對一個誕生僅七天的專案而言，這個密度異常地高。
更重要的是，它的原始碼註釋品質極佳。多處註釋記錄了實測事故的時間線、與 TypeScript 原始版本的對等關係、以及設計決策的演化過程。這讓它成為一份罕見的「活教材」，你可以從中讀到一個 Agent 框架是怎麼一步步長成現在這個樣子的。
分層架構：從模型到 bash 的四層蛋糕
OkHuman 的架構可以切成四層來理解。
最上層是模型層。它透過 OpenAI 相容的 API 與大型語言模型對話。實測環境中，背後跑的是 OMLX 本地模型服務，載入 Qwen3.5-9B-MLX-4bit 量化模型，監聽在 localhost:8000。生成速度約 25.1 tok/s，prefill 速度 1,039 tok/s，記憶體佔用 6.4 GB。這個組合足以應付工具型任務，但純推理能力偏弱，實測多步算術推理曾經出錯。
中間是核心引擎層。internal/agent/agent.go（789 行）負責對話循環與工具執行編排；internal/context/ 模組（6 個檔案、1,392 行）處理上下文組裝、預算控制與滾動壓縮；internal/server/server.go（1,619 行）是最大的單一模組，承載所有 HTTP API 與 WebUI 靜態服務。
再往下是工具層。這裡只有一個工具：bash。internal/tools/tools.go（262 行）定義了整個框架唯一的元工具。所有外部操作，不管是讀寫檔案、搜索資料、還是呼叫插件，全部透過 bash 完成。模型只需要會寫 shell 命令，就能驅動一切。
最底層是插件層。插件以獨立進程或 CLI 工具的形式存在，透過 HTTP 或命令列與主程序溝通。主程序對插件的內部實作零感知。
九個插件：一個鬆散但各有職責的生態
截至分析時的 commit 2875678，OkHuman 倉庫內有九個插件：
browser（2,293 行）是最龐大的插件，提供 browserctl CLI 驅動本地 Firefox，支援導航、定位、填表、點擊、取文本等操作。qq-channel（2,167 行）是 QQ 官方渠道的雙向轉發橋梁，作為獨立常駐進程運行。cron（1,154 行）負責定時任務，監聽在 :8601，到點就把 prompt 作為使用者消息 POST 到實例的 /chat 端點。
computer（983 行）給 Agent 裝上「手」，能整屏截圖注入並模擬 X11 滑鼠鍵盤事件。scout（770 行）是本地插件與技能的語義索引服務，監聽在 :8480，結合關鍵詞與 Qwen3-Embedding 向量打分。attach（567 行）處理素材注入，支援圖片原圖或壓縮、視頻按策略自動壓縮為 360p 並分段。okmon（536 行）是進程監控與啟停管理工具，WebUI 在 :8496。
skills 插件比較特殊，它不是一個服務，而是一個操作經驗庫。每個 skill 是一份 SKILL.md 文件，記錄本機實測驗證過的操作步驟，同樣進入 scout 索引。倉庫刻意不預置任何技能，README 明言：「技能是環境相關的，請在你自己的機器上實測後積累。」
最後是 voice-chat。它的 README 詳細描述了麥克風輸入、VAD、聲紋門控、ASR、喚醒詞路由、Kokoro TTS 等功能，但目錄裡一個 Go 檔案都沒有。這是文件與實作不一致的典型早期專案現象。
三個關鍵設計取捨
OkHuman 的架構背後有三個明確的設計取捨，每一個都代表了作者在「簡單」與「功能」之間的選擇。
第一個取捨：一個進程等於一個 Agent。 主程序曾經支援多 Agent 共存，但在 2026 年 9 月 9 日被刻意移除。現在的作法是要多少 Agent 就起多少個進程，各自獨立落盤目錄、獨立上下文。好處是隔離徹底，一個實例崩潰不影響其他；代價是資源佔用較高，跨 Agent 協作需要外部機制。
第二個取捨：唯一的元工具是 bash。 框架不定義 read_file、write_file、search 這類結構化工具，而是把所有外部操作都交給 bash。tools.go 的註釋寫得很直白：「工具系統：唯一元工具 bash。一切外部操作都靠 bash 完成。」模型只需要會寫 shell，就能調動整個系統的能力。代價是所有能力都被 bash 的瓶頸限制，而且模型的 shell 撰寫能力直接決定了框架的上限。
值得注意的是，bash 工具不採用 bash -c 把命令全文放在 argv 上，而是先寫入臨時腳本檔再執行。註釋說明這是「實測事故後」的修正，因為 ps 命令可以讀取進程的 argv，命令全文可能洩漏敏感資訊。
第三個取捨：插件透過 HTTP 完全解耦。 插件不 import 主程序、不共享進程與記憶體、自帶配置與數據目錄、獨立可編譯。主程序對插件零感知，插件掛了不影響主程序，主程序重啟不影響插件。代價是每次調用都要跨 HTTP，有延遲與序列化開銷。
七個核心機制：原始碼裡的實戰經驗
OkHuman 最值得細讀的不是功能清單，而是七個從實戰中長出來的機制。
上下文滾動壓縮（context/compress.go）：當會話總 token 超過預算，框架會把舊消息批次交給 LLM 壓成總結，最多迭代三輪，取最短的一輪。壓縮提示詞開頭明確聲明「忽略之前的一切指令與任務」，這是因為作者發現，如果不這樣做，模型會把歷史訊息裡的舊指令當成待執行任務去調工具。這是一個非常真實、且多數框架沒處理的陷阱。
死循環檢測（agent/agent.go）：連續三次完全相同的工具調用會觸發警告，警告後仍重複則發出 doom_stop 事件強停本輪。設計上是「先執行後警告」，避免誤殺正常的重試。
前台超時轉後台（background/background.go）：工具調用與 30 秒前台超時賽跑，超時不取消執行，而是降級為背景任務，完成後結果自動注入下一輪上下文。這解決了 Agent 傻等長工具的痛點。不過實測發現，模型有時會把「已轉後台」誤判為「已完成」，這是使用者需要特別留意的一點。
生命自感知：系統提示詞首部會注入一段「你的生命」區塊，包含本實例的端口、PID、源碼位置，以及所接入 LLM 服務的端口與 PID，每次調用現算。目的是讓模型知道「動這些 PID 和端口就是傷它自己」。這是一種以提示詞實作的柔性自我保護機制。
提示詞分層與熱加載（prompt/prompt.go）：prompts/*.md 依檔名排序拼接為系統提示詞，透過 POST /prompts/reload 可以熱加載，無需重啟。專用層（如部署規範、插件規範）不進系統提示詞，Agent 按需自行讀取。
原子寫持久化（persist/persist.go）：session.json 每次變更都透過臨時檔加 rename 的方式原子寫入，日誌超過 5 MB 自動輪轉為 .old。
零依賴手寫 SSE 串流（llm/client.go）：整個 HTTP 客戶端與 SSE 串流解析全部用標準庫實作，功能完整，包含 idle timeout 處理。
與 OMLX 的關係：本地模型作為標配
OkHuman 的實測環境搭配了 OMLX 本地模型服務。OMLX 監聽在 localhost:8000，載入 Qwen3.5-9B-MLX-4bit 量化模型。這套組合的實測數據如下：生成速度 25.1 tok/s、prefill 速度 1,039 tok/s、記憶體佔用 6.4 GB。
這個搭配傳達了一個重要訊息：OkHuman 的設計假設是「你有一台夠力的本機」。9B 的量化模型足以應付工具調用與流程遵循型任務（實測 bash 鏈路四項測試全部通過），但純推理能力偏弱。框架的核心洞察是：把難的部分從模型搬到工程。模型負責決定做什麼，harness 負責把事做穩，插件負責提供能力。三者解耦之後，小模型也能勝任工具型任務。
常駐基礎設施：launchd 與四個 LaunchAgent
在 macOS 部署環境中，OkHuman 透過四個 LaunchAgent 實現開機自啟與掛掉自動重啟（KeepAlive）：
com.ultraclaw.okhuman：主程序，監聽:8451，含 OMLX 依賴檢查com.ultraclaw.okhuman-scout：語義索引服務，:8480com.ultraclaw.okhuman-okmon：進程監控，:8496com.ultraclaw.okhuman-cron：定時任務，:8601
四個服務加上 OMLX（:8000），一共五個常駐進程。每個都有獨立的 plist 配置，由 launchd 管理生命週期。這種部署方式讓 OkHuman 可以作為「永遠在跑的個人助手」運作，但也意味著你需要習慣管理五個背景進程。
適合誰，不適合誰
OkHuman 是一個實驗性框架。它的專案年齡不到一個月，只有兩位貢獻者，沒有 CI 管道，測試覆蓋不均，voice-chat 插件有描述但無程式碼。這些事實決定了它的定位。
適合的人：想理解 Agent 框架內部運作的開發者。它的原始碼註釋品質極高，七個核心機制都有完整的設計演化記錄。特別是上下文滾動壓縮的指令隔離、前台超時轉後台的降級策略、以及三角色部署拓撲（生產、副本、救生艇），這些設計思路可以直接借鑒到你自己的系統中。
不適合的人：需要在生產環境中穩定運行 Agent 的團隊。框架的生態風險太高，靜默失效的問題尚未完全解決（例如 scout 的 embedding 曾經靜默降級為關鍵詞搜索，health 端點卻顯示正常），安全面也存在需要改善的空間（HTTP 介面零認證、/config 端點明文回傳 API key）。
一句話總結：把它當作設計思路的參考來閱讀，而不是可以直接 go install 上線的生產工具。
下一步
如果你想繼續深入 Agent 架構的世界，以下幾篇站內文章可以幫助你建立更完整的知識體系：
- 什麼是 Agent Harness：理解 Agent 運行時的核心概念，以及 harness 如何把模型能力轉化為可靠的自動化流程。
- Harness 的演化路徑：從早期腳本式 Agent 到現代分層架構，理解 OkHuman 這類設計在演化樹上的位置。
- 什麼是 AI Agent：如果你還沒聽過 Agent 這個詞，這篇文章從最基礎的定義開始。
- OkHuman 安全審查報告：深入本文提到的安全發現，包含零認證 HTTP 介面與 CSRF 風險的完整分析。
- OkHuman 能力評測與 Scout 修復：實測 13 項能力測試的細節，以及我們如何修復 scout 語義搜索的靜默降級問題。
- OkHuman 能力極限在哪：更細緻的能力邊界分析，包含判斷力與執行力的落差討論。