Codewhale 是一个跑在终端里的开源编码 Agent，用 Rust 写，MIT 协议，约 4.1 万 stars。给它一个任务，它会读仓库、改文件、跑命令，直到任务完成或需要你输入。它跟编辑器插件类的编码助手不是一路——它是终端优先、可脚本化的，这决定了它在 CI 和批处理场景里的独特价值。这篇讲它解决什么问题、怎么上手、哪些设计值得抄。

解决什么问题

它的定位是一句话：终端里的编码 Agent，任何模型都能用。多数编码助手绑死在某个编辑器或某个模型上，Codewhale 把两件事都解耦了——内置 40 多个 provider（Anthropic、OpenAI、DeepSeek、Google、Mistral、Moonshot、OpenRouter、xAI 等），任何 OpenAI 兼容端点都能接，本地模型走 Ollama、vLLM、SGLang；默认用 DeepSeek 的 deepseek-flash，没有 key 时自动落到本地。交互形态也很灵活：交互式终端、单任务 exec、本地 web UI、PR 评审、Runtime API、ACP 协议，共用同一个引擎。

上手

安装一行命令，macOS 和 Linux 通用：

curl -fsSL https://codewhale.net/install.sh | sh

装完把 codewhale 和它的短别名 codew 放进 ~/.local/bin。然后在 git 仓库根目录跑 codewhale，/provider 选一个 provider 填 key 选模型，直接输入任务就行。它对只读命令直接放行，其他 shell 命令会先问：y 跑一次、a 允许同类命令、n 拒绝。/undo 撤回上一次请求和它的文件改动。

脚本化与 CI

对脚本和 CI，codewhale exec 跑单个任务、不带界面。默认 --auto 走 Full Access（工具不问、shell 无沙箱、信任模式让文件工具能写工作区之外），加 --sandbox workspace-write 则保留 shell 沙箱和工作区限制、关信任模式：

codewhale exec --auto --sandbox workspace-write "fix the failing tests and explain what changed"

这条命令的价值在于：你可以把编码 Agent 嵌进流水线，用最小权限跑完一个明确任务，而不是开一个交互式会话。

三模式三权限

它的权限模型值得单独说。三个模式：Plan 只读搜索不改东西，Work 改文件跑命令，Operate 把请求当目标、一直推进到目标验证完成或需要你输入。三个权限档：Ask 在仓库内改文件不先问、非只读 shell 命令先问；Auto-Review 让规则和一个 reviewer 模型批准常规调用、拒绝高危调用；Full Access 从不问、关沙箱，但仓库规则和托管策略仍生效。这个「模式 × 权限」的组合，让你能按任务风险精确调档，而不是一开就全放开。

receipts 留痕

它最值得抄的设计是 receipts。/receipts（或退出后 codewhale receipts --last）会列出它改了哪些文件、跑了哪些命令、做了哪些 web 和 MCP 调用、启动了哪些 agent、批准是谁给的、以及失败项。这在 Agent 时代特别重要：编码 Agent 是替你动手的，你得能事后审计它到底干了什么。/undo 一步撤回上次请求和文件改动，/restore 把工作区回滚到更早快照。留痕加可回滚，是把信任建立在机制上而不是祈祷上。

配置与本地模型

配置文件是 TOML，几个常用项自写示意：

# ~/.config/codewhale/config.toml
[search]
provider = "deepseek"        # web_search 走 DeepSeek 新 Search API

telemetry = false            # 关闭遥测
project_instruction_imports = ["claude"]   # 读 CLAUDE.md 这类指令文件

它还支持 MCP 服务器、skills、plugins、hooks，能读 AGENTS.md，/import-claude 帮你迁移 Claude Code 的配置和 MCP。

局限

几点要清楚。一是它终端优先，IDE 深度集成不是主线，VS Code 扩展是社区维护的，重度 IDE 用户可能觉得不如原生插件顺手。二是 Full Access 会关掉沙箱，Windows 目前还没有 OS 级沙箱（macOS 用 Seatbelt、Linux 用 bubblewrap），所以 Windows 上默认少一层防护。三是遥测默认开，虽然只发聚合计数、不发对话代码，介意的话要手动关。四是它独立维护、和 DeepSeek 无关，别把它当成官方工具。综合看，Codewhale 把「终端里跑一个能审计、能回滚、能脚本化的编码 Agent」这件事做得相当完整，适合喜欢命令行、想把 Agent 接进流水线的团队。