工具

CodeWhale:四萬星 Rust 終端編碼 Agent,如何與 Claude Code 走差異化路線

同為 TUI 編碼 Agent,CodeWhale 把「分級審批 + 工作流可審查」當作核心賣點,背後是 Rust 單一二進位檔加上模型中立架構的設計選擇。

字級

終端編碼 Agent 這幾年如雨後春筍冒出來,但大多數不是綁死在單一雲端服務商,就是把審批邏輯藏在黑盒子裡。CodeWhale 的切入角度不太一樣:模型中立加上審批流程完全可觀察。目標族群很清楚——想用開源模型、又想看清楚 Agent 邊界在哪裡的開發者。

GitHub 倉庫:https://github.com/Hmbown/CodeWhale,目前 40,828 顆星,README 已翻譯成 18 種語言。

它解決什麼問題

終端編碼 Agent 這幾年一窩蜂冒出來。多數不是綁死單一雲端廠商,就是把審批邏輯藏進黑盒子——你按下 Enter 之前,根本不知道它下一步會動到哪些檔案。

CodeWhale 想解決的事情有兩件:

  1. 模型中立。本機的 Ollama、vLLM、SGLang,或是託管的 OpenAI 相容協議、Anthropic,全部都能接,運行階段隨時切換。
  2. 審批可觀察。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 與倉庫結構的靜態分析,我自己沒有真的跑過。建議按以下順序驗證:

  1. 安裝 codewhale,串接一個本機 Ollama 啟動的 qwen2.5-coder。
  2. 在一個 toy repo 裡跑 codewhale exec "給 src/foo.py 補單元測試",對比 Plan 檔位和 Full Access 檔位的輸出差異(Plan 應該幾乎不動檔案)。
  3. 用 /restore 回溯,確認 snapshot 是否完整、能不能精確還原到某一輪。
  4. 開兩個 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 客戶端三個面向。

來源: https://github.com/Hmbown/CodeWhale