嗨，我是小华同学，专注解锁高效工作与前沿AI工具！每日精选开源技术、实战技巧，助你省时50%、领先他人一步。👉免费订阅，与10万+技术人共享升级秘籍！
你以为 AI 写代码最怕不会写？真正危险的是它写得很快，却没人知道它凭什么这样改。
普通聊天模型会给建议，Coding Agent 会读文件、跑命令、修改仓库；工具越多，责任和权限越不能靠模型“记得住”。
这篇用 3 分钟讲清 CodeWhale：它先给 Agent 定身份、定规则、定证据和审批，再让它开始施工。
CodeWhale 是什么
CodeWhale 不是一个“换个模型就能聊天”的壳，而是一套开源的 terminal coding agent harness。你可以把它理解成：给代码 Agent 配了一套施工现场、操作规程和留痕系统。
截至 2026 年 7 月，项目 GitHub 已超过 4 万 Star，最新 release 为 v0.9.1，使用 Rust 编写，采用 MIT 许可证。它能在本地读取代码、编辑文件、运行命令、检查结果，并在需要时停下来请求人类介入。
| 方式 | 主要能力 | 风险边界 |
|---|---|---|
| 普通模型 | 解释代码、给出建议 | 通常不直接操作仓库 |
| Coding Agent | 读取文件、改代码、跑命令 | 需要权限与验证机制 |
| CodeWhale harness | 任务、模式、审批、证据、回滚、会话 | 把治理能力放进运行时 |
为什么 AI 写代码需要一部“宪法”
Agent 一旦拥有工具，问题就从“它会不会写”变成了“它凭什么这么做”。CodeWhale 的思路很直接：先定义 Agent 在本地工作区里的身份与边界，再允许它行动。
项目把这套规则概括成几条原则：
- 身份要明确：Agent 是当前终端和工作区里的执行者，不是一个只存在于模型卡上的名字。
- 证据高于叙述：命令输出、测试结果和实际 diff，比“我已经完成了”更可信。
- 用户意图优先：过期的提示词、记忆和交接信息，不能压过用户当前的要求。
- 本地规则可落地：项目可以通过
.codewhale/constitution.json写下持久化约束、保护项、分支策略和验证规则。 - 运行时必须执行：模式、审批、沙箱、回滚和工具权限，不能只停留在文档里。
它把哪些“规矩”写进运行时
1. 默认先观察，再允许修改
Plan 模式不会直接改文件；需要真正执行时，再根据权限切换到 Ask、Auto-Review 或 Full Access。高风险动作仍然可以触发审批。
2. 工具操作要经过门禁
文件、Shell、Git、Web、MCP 和子 Agent 等能力，都有明确的调用边界。macOS 可使用 Seatbelt，Linux 可选择 bubblewrap，目标是让“能做什么”变成显式策略，而不是模型临场发挥。
3. 每一步都要留下证据
修改后可以接收语言服务器的实时诊断；失败的命令就报告失败，不用一句“看起来没问题”把它盖过去。对工程团队来说，这个习惯比多一句漂亮的解释更重要。
4. 做错了要能回去
CodeWhale 通过 side-git 快照支持 /restore，而且不依赖直接污染项目仓库的 .git。会话、fork、relay handoff 和 fleet ledger，则让长任务可以中断、复盘、继续。
一条任务是怎么走完的
把它压缩成一句话就是：任务先进入工作区，Agent 先读上下文，再计划与审批，然后修改和执行，最后用日志、输出、测试和可回滚状态完成交付。
这也是 CodeWhale 和“直接把代码生成出来”的工具的区别：它关心的不只是结果，还关心过程能不能解释、失败能不能定位、改动能不能撤回。
不只支持 DeepSeek
CodeWhale 最初带有 DeepSeek 原生体验，但现在已经扩展成 BYOM 的多提供商 harness。README 中列出的路线包括 Claude、GPT、Kimi、GLM，以及 30 多个提供商；也可以接入 vLLM、SGLang、Ollama 等自托管服务。
在任务过程中，还可以用 /model 切换模型。比如规划阶段使用更擅长分析的模型，执行阶段换成成本更合适的模型，模型变化不必把整个工作流推倒重来。
Fleet：从一个 Agent 到一群 worker
如果一个任务适合拆分，/fleet 可以运行一组 worker。重点不在“多开几个聊天窗口”，而在于每一步都会写入追加式 ledger，之后可以用 fleet resume 接着工作。
这对长时间重构、代码审查、测试修复比较有价值：任务被拆开了，但过程仍然可追踪，失败也不会只剩下一段无法复盘的对话。
适合谁，不适合谁
| 人群 | 适合度 | 原因 |
|---|---|---|
| 想在终端里使用 AI 改代码的开发者 | 很适合 | TUI、exec、本地工作区和多模型路由都比较直接 |
| 做团队工程规范和 Agent 平台的人 | 很适合 | Constitution、审批、证据和回滚可以成为治理底座 |
| 只想问几个代码问题的新手 | 一般 | 普通聊天工具上手成本可能更低 |
| 需要完全无人值守、任意修改生产环境的人 | 不建议 | 权限门禁和验证机制本来就是为了限制盲目执行 |
3 分钟启动
npm install -g codewhale
codewhale auth set --provider deepseek
codewhale
也可以直接执行一个任务：
codewhale exec "fix the failing test"
如果想从浏览器访问本地客户端，可以运行 codewhale web，默认监听 127.0.0.1。模型密钥和具体提供商配置，建议按官方文档填写，不要直接提交进仓库。
小华的判断
CodeWhale 真正值得关注的地方，不是它又接了多少模型，而是它把 权限、证据、规则、回滚和持续工作 放到了同一条 Agent 执行链路里。
当 AI 只负责回答问题时，聪明很重要；当 AI 开始修改真实仓库时，可验证、可恢复、知道何时停下来，往往比“更会猜”更重要。
下一步最值得继续拆开的，是 .codewhale/constitution.json 如何写项目规则，以及 Fleet 如何组织多 Agent 协作。关注公众号，后面继续用真实开源项目把这些机制讲明白。
