CodeWhale:4 万 Star 的 Rust 终端编码 Agent,靠什么和 Claude Code 错位竞争
终端编码 Agent 这两年一窝蜂冒出来。大多数要么绑死单一云厂商,要么把审批逻辑藏在黑盒里。CodeWhale 的切入角度不太一样:模型中立 + 审批可观测。目标用户很清晰——想用开源模型,又想看清 Agent 边界的开发者。
GitHub 仓库:https://github.com/Hmbown/CodeWhale ,当前 40,828 Star,README 翻译了 18 种语言。
它解决什么问题
终端编码 Agent 这两年一窝蜂冒出来。大多数要么绑死单一云厂商,要么把审批逻辑藏在黑盒里——你按回车之前,根本不知道它下一步要碰哪些文件。
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 不需要改代码或重新部署。 - 审批分级不是 marketing 话术。文档里有完整的 AUTHORIZATION_ORDER 策略栈,每次操作有 snapshot 可回滚。从 Plan 到 Full Access 是连续可调的,不是 on/off 二选一。
- 多 agent 协作能保持 transcript 干净。docs/FLEET.md 里的协作模式,内部 sub-agent 的 prompt 不会污染用户的对话记录,这对调试很重要。
- Rust 单二进制 + 多渠道分发。Cargo 装的、npm 装的、docker 跑的都是同一份二进制,行为一致。
- 社区活跃。40,828 Star,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 生态贡献者,想看一个 4 万 Star 的 Rust Agent 项目长啥样,目录结构和模块划分值得翻一翻。
不适合:
- 只想装一个 IDE 插件、懒得读 5 份 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 客户端三块。