終端編碼 Agent 這幾年如雨後春筍冒出來,但大多數不是綁死在單一雲端服務商,就是把審批邏輯藏在黑盒子裡。CodeWhale 的切入角度不太一樣:模型中立加上審批流程完全可觀察。目標族群很清楚——想用開源模型、又想看清楚 Agent 邊界在哪裡的開發者。
GitHub 倉庫:https://github.com/Hmbown/CodeWhale,目前 40,828 顆星,README 已翻譯成 18 種語言。
它解決什麼問題
終端編碼 Agent 這幾年一窩蜂冒出來。多數不是綁死單一雲端廠商,就是把審批邏輯藏進黑盒子——你按下 Enter 之前,根本不知道它下一步會動到哪些檔案。
CodeWhale 想解決的事情有兩件:
- 模型中立。本機的 Ollama、vLLM、SGLang,或是託管的 OpenAI 相容協議、Anthropic,全部都能接,運行階段隨時切換。
- 審批可觀察。Agent 能做什麼、做到哪一步,全部拆成使用者可見的檔位(Plan / Ask / Auto-Review / Full Access),以及可回溯的快照紀錄。
目標使用者是那些想用開源本機模型跑編碼 Agent、又不放心讓 Agent 亂改檔案的人。
怎麼使用
三行指令就能起步:
# 三步起步
npm install -g codewhale # 也可用 cargo / docker / nix
codewhale # 啟動 TUI,首次執行會引導接 provider 或維持離線
# 不開 TUI 直接跑任務
codewhale exec "fix the failing tests and explain what changed"
# TUI 內常用指令
# /model 切換 provider 和模型
# /undo 撤回上一輪操作
# /restore 回溯到某個 workspace snapshot
# /goal 設定持久目標
# /help 檢視所有快捷鍵
# 想用本機模型?起一個 Ollama 後 /model 選 Ollama 即可,
# vLLM、SGLang 同理(OpenAI 相容協議)
安裝管道對中文使用者相當友善——除了 npm、Cargo、Docker、Nix、Scoop、Termux,還支援 CNB 鏡像。
運作原理(架構)
CodeWhale 把系統拆成四層,每層都對應 README 裡的一份 docs 入口,方便挑著讀。
- 入口層:TUI(預設)+
codewhale exec(headless,單次任務用)+ 本機 Web 客戶端(docs/WEB.md),三套入口共用同一套 agent runtime。 - Provider 抽象層:把 OpenAI 相容協議、Anthropic、Ollama、vLLM、SGLang 統一封裝成內部的 Model trait。未知模型的價格不會硬報成 0 元,而是直接留空,讓使用者自行維護成本表。
- 審批策略堆疊:四級檔位——Plan(唯讀,不改檔案)/ Ask(每步詢問)/ Auto-Review(自動執行但可回溯)/ Full Access。搭配
/undo+/restore構成可觀察的安全邊界。完整策略定義在 docs/AUTHORIZATION_ORDER.md。 - 擴充層:MCP server、技能檔、hooks、agent role 檔(可放在專案內或全域 settings)。多 agent 協作時(docs/FLEET.md),內部 prompt 不會灌進使用者 transcript。
關鍵流程很短:使用者輸入 → 解析成 goal/turn → 載入 MCP + skills + hooks → 呼叫 Model → 依當前審批檔位決定是否執行工具呼叫 → 寫入 session snapshot → 渲染結果。
它的優勢
- 模型中立不是說說而已。Ollama、vLLM、SGLang 全部支援,
/model一鍵切換。換 provider 不必改程式或重新部署。 - 審批分級不是行銷話術。文件裡有完整的 AUTHORIZATION_ORDER 策略堆疊,每次操作都有 snapshot 可回溯。從 Plan 到 Full Access 是連續可調的,不是 on/off 二選一。
- 多 agent 協作能保持 transcript 乾淨。docs/FLEET.md 裡的協作模式,內部 sub-agent 的 prompt 不會污染使用者的對話紀錄,這對除錯來說很重要。
- Rust 單一二進位檔加上多通路發布。Cargo 裝的、npm 裝的、docker 跑的都是同一份二進位檔,行為一致。
- 社群活躍。40,828 顆星,README 有 18 種語言翻譯,issue 區回應也算積極。
它的不足
- 命名容易和 Claude Code 混淆。CodeWhale 這個名字在社群討論時需要額外補充上下文,搜尋時也容易被雜訊淹沒。
- 文件量明顯大於程式量。對只想「裝了就用」的使用者,門檻偏高。docs/AUTHORIZATION_ORDER.md、docs/FLEET.md、docs/WEB.md 加起來份量不輕。
- 未知模型價格直接留空。對成本敏感的團隊需要自己維護價格表,系統不會幫你估算。
- 專案從
deepseek-tui改名而來。舊設定和舊 session 的相容性是隱形成本,遷移時可能得手動調整。
我沒實際跑過——但建議這樣驗證
這是一篇基於 README 與倉庫結構的靜態分析,我自己沒有真的跑過。建議按以下順序驗證:
- 安裝
codewhale,串接一個本機 Ollama 啟動的qwen2.5-coder。 - 在一個 toy repo 裡跑
codewhale exec "給 src/foo.py 補單元測試",對比 Plan 檔位和 Full Access 檔位的輸出差異(Plan 應該幾乎不動檔案)。 - 用
/restore回溯,確認 snapshot 是否完整、能不能精確還原到某一輪。 - 開兩個 agent 角色跑 docs/FLEET.md 的範例,檢查 transcript 是否真的乾淨(內部 sub-agent 的思考應該看不到)。
跑完可以把數據(本機模型下的 token/s、審批延遲、snapshot 體積)貼到留言區一起對照。
誰適合用
適合:
- 想用開源本機模型(Ollama/vLLM)跑編碼 Agent、又不放心讓 Agent 亂改檔案的人。
- 需要在團隊裡審核 Agent 操作紀錄、把審批流程做成可觀察而非黑盒的工程團隊。
- Rust 生態貢獻者,想看一個四萬星的 Rust Agent 專案長什麼樣,目錄結構和模組劃分值得翻一翻。
不適合:
- 只想裝一個 IDE 插件、得讀五份 docs 的人。
- 依賴 Claude Code 或 Cursor 那種「開箱即用最強模型」體驗、且不在乎鎖定的使用者——CodeWhale 不會幫你選模型,切換的判斷成本在你身上。
- 對終端 UI 過敏、需要完整 GUI 的團隊。CodeWhale 有本機 Web 客戶端(docs/WEB.md),但主戰場還是 TUI。
參考:CodeWhale 倉庫 https://github.com/Hmbown/CodeWhale,docs/AUTHORIZATION_ORDER.md、docs/FLEET.md、docs/WEB.md 分別涵蓋審批策略、多 agent 協作、Web 客戶端三個面向。