Codewhale：用 Rust 编写的终端编程 Agent——安装、审批模式与多模型路由全解

Codewhale 是一个开源的终端编程 Agent，用 Rust 编写，运行在你自己的机器上，可以读取仓库、编辑文件、执行命令并持续工作直到达成目标。本文基于仓库中官方西语（拉美）版 README（README.es-419.md）的完整内容，结合 crates/ 下的真实源码，带你掌握它的安装方式、交互与无头两种用法、四层审批模式的底层实现、42 家供应商的路由机制，以及安全边界与文档索引，读完即可在终端里完成从接入模型到管控权限的完整配置。

概览：Codewhale 是什么

一句话定义（继承自 README 首段）：

Codewhale es un agente de programación de código abierto para tu terminal, desarrollado en Rust y mejorado públicamente junto con las personas que lo usan.

即：一个为你终端打造的开源编程 Agent，用 Rust 开发，并随着使用者的反馈持续公开改进。它的定位有几个关键点：

• 本地运行：Agent 运行在你的设备上，你决定给它多大的访问权限；
• Rust 实现：整个运行时以 Rust crate 组织，核心逻辑分散在 crates/ 下的数十个子 crate（agent、tui、execpolicy、protocol、config 等）中；
• 供应商中立：不隶属于任何模型供应商，托管供应商与本地模型（Ollama、vLLM、SGLang）皆可接入；
• 社区驱动：Issues 和 PR 公开欢迎，贡献者保留被合入工作的署名。

npm 包 npm/codewhale/package.json 中对项目的自述也印证了这一点：“Terminal coding agent for supported hosted and local models. One runtime on your machine. Rust, MIT.”，当前版本为 0.9.11，并同时注册了 codewhale 与 codew 两个可执行命令，要求 Node.js >=18。

安装

最简路径：npm 全局安装

README 给出的标准安装命令：

npm install -g codewhale
codewhale

首次运行行为：第一次执行 codewhale 时，它会引导你连接一个模型供应商，或者选择离线模式（sin conexión）继续，不强制要求立即配置 API Key。

npm 包本质上是一个二进制分发包装器：包内 postinstall 钩子（node scripts/install.js --optional，见 npm/codewhale/package.json）负责按平台下载对应的预编译 codewhale 与 codew 二进制。

其他安装途径

README 明确列出：除 npm 外还支持 Cargo、Docker、Nix、Scoop、预编译文件、Android/Termux 以及 CNB 镜像，完整平台矩阵与故障排查见 安装指南。从 docs/INSTALL.md 中可以确认几个值得注意的实现细节：

平台	说明
Linux x64 / arm64	发布资产为静态 musl 构建，无 glibc 依赖，跨 Ubuntu、Debian、RHEL/CentOS、Alpine 均可运行；SQLite 通过 rusqlite 内嵌，无需单独安装 libsqlite3
macOS / Windows	x64 与 arm64 均有 codewhale + codew 预编译资产，npm 与 cargo install 双通道
Android / Termux	预览阶段（preview），需使用 Termux 专用的 Android 归档，不能误装 Linux arm64 版本
FreeBSD / OpenBSD	无预编译，走 cargo install codewhale-cli --locked 源码构建
musl（Alpine 等）	npm 安装时自动选择静态构建

macOS 与 Linux 上最短的安装/更新路径是官网安装脚本（下载二进制、校验 sha256 清单、默认装到 ~/.local/bin）；仓库内也提供了 Dockerfile、flake.nix 与 packaging/ 下的 AUR / winget / Docker 发布模板，供高级用户按需构建。

Tab 补全：每个 shell 一条命令

README 给出的补全配置方式：

codewhale completion bash|zsh|fish|powershell|elvish

命令会把补全脚本打印到 stdout，重定向到 shell 自动加载的路径即可。crates/cli/src/lib.rs 中的帮助文本给出了每个 shell 的具体写法，可以直接复制：

# Bash（macOS 即时生效）
source <(codewhale completion bash)

# Bash（Linux 持久化，需已安装 bash-completion）
mkdir -p ~/.local/share/bash-completion/completions
codewhale completion bash > ~/.local/share/bash-completion/completions/codewhale

# Zsh
codewhale completion zsh > ~/.zfunc/_codewhale

# Fish
mkdir -p ~/.config/fish/completions
codewhale completion fish > ~/.config/fish/completions/codewhale.fish

# PowerShell
codewhale completion powershell | Out-String | Invoke-Expression
# 或持久化：
codewhale completion powershell >> $PROFILE

# Elvish
codewhale completion elvish >> ~/.config/elvish/rc.elv

详见 安装指南第 8 节。

使用：交互式 TUI 与无头 exec

像对同事一样下指令

README 对交互方式的定义很直接——“Habla con Codewhale como hablarías con alguien de tu equipo”（像跟你团队里的某人说话一样跟它说话）：

Fix the failing tests and explain what changed.

无头执行：codewhale exec

不打开 TUI 也能跑任务：

codewhale exec "fix the failing tests and explain what changed"

从 CLI 的帮助文本（crates/cli/src/lib.rs）可以看到更多实战形态：

codewhale exec "explain this function"
codewhale exec --auto "list crates/ with ls"
codewhale exec --auto --output-format stream-json "fix the failing test"

要点：

• 裸 codewhale exec 是一次性的模型响应；
• 加 --auto 才会进入自动审批（Auto）执行工具调用；
• --output-format stream-json 便于把流式输出接入脚本或 CI；
• 会话续接：codewhale exec --continue <PROMPT> 继续最近会话，codewhale exec --session-id <id> <PROMPT> 指定会话；交互式侧则对应 codewhale --continue 与 codewhale --resume <session_id>（同一组语义在 crates/cli/src/lib.rs 的参数提示文案中都有明确区分）。

能力边界由你划定

README 原文：“Codewhale puede leer tu repositorio, editar archivos, ejecutar comandos, revisar los resultados y seguir trabajando para alcanzar un objetivo. Tú decides cuánto acceso darle.”——它可以读仓库、改文件、跑命令、检查结果并持续迭代直到达成目标，访问范围由你决定。这一点在下一章的审批模式中有源码级的落实。

核心特性一：模型自由——托管供应商 + 本地模型

README 的卖点第一条：“Usa el modelo que prefieras”（用你偏好的模型）。托管供应商或本地模型（Ollama、vLLM、SGLang）皆可接入，运行中用 /model 切换供应商与模型。

这条能力在源码中有非常完整的落实。docs/PROVIDERS.md 记录了供应商注册表：

• 规范供应商 ID 共 42 个，即 ProviderKind::ALL（定义于 crates/config/src/provider_kind.rs），覆盖 deepseek、openai、anthropic、google、openrouter，以及本地运行时 sglang、vllm、ollama、ollama-cloud 等；
• DeepSeek 仍是默认供应商，但每个 ID 都是一等公民的可选路由；
• 四种选择途径，任选其一：

codewhale --provider <id>          # CLI
/provider <id>                     # TUI 斜杠命令 / 选择器
CODEWHALE_PROVIDER=<id>            # 环境变量（DEEPSEEK_PROVIDER 为旧别名）
provider = "<id>"                  # config.toml

• 兼容性别名受支持：deepseek-cn、deepseek_china 等旧写法都被映射回 deepseek（DeepSeek 全球使用同一官方 API 主机，别名并不切换主机）。

从源码结构看，静态模型目录由 crates/agent/src/lib.rs 的 ModelRegistry 维护，支撑 codewhale model list 与 codewhale model resolve 子命令；仓库还配有 scripts/check-provider-registry.py 做漂移检查，保证文档、TUI、TOML 表名与静态注册表一致——这是“多供应商支持”背后可持续性的工程保障。

核心特性二：审批模式与操作控制

README 的卖点第二条：“Mantén el control”（保持掌控）。README 原文列出了完整的行为集合：

Plan 是只读模式。Ask、Auto-Review 与 Full Access 让审批行为可见。/undo 回退最后一轮，/restore 把工作区恢复到某个早期快照。

这段话在 crates/execpolicy/src/approval_mode.rs 中有逐字对应的枚举实现，是整个权限体系的公共定义（策略代码与 TUI 共用，TUI 只在其上叠加展示层）：

pub enum ApprovalMode {
    /// Automatically review risky tool calls before deciding whether to ask.
    Auto,
    /// Bypass approvals entirely (YOLO mode / --yolo flag).
    Bypass,
    /// Suggest approval for non-safe tools (non-YOLO modes)
    #[default]
    Suggest,
    /// Never execute tools requiring approval
    Never,
}

四个枚举值与 README 的用户可见名称一一对应（见 permission_chip_label）：

枚举	用户可见名称	语义
Suggest（默认）	Ask	对非安全工具发起审批询问
Auto	Auto-Review	自动审查风险工具调用后再决定是否询问
Bypass	Full Access	完全绕过审批（即 --yolo）
Never	Never	永不执行需要审批的工具

几个从源码确认的实用细节：

• Shift+Tab 循环切换：PERMISSION_CYCLE: [Self; 3] = [Suggest, Auto, Bypass] 定义了权限三档循环（Never 不在 Tab 循环内），cycle_permission_next 实现轮换；
• 配置别名宽容解析：from_config_value 接受 auto / auto-review / auto_review、bypass / yolo / full-access / full、suggest / ask / on-request 等多种写法，降低配置出错率；
• 权限不只是模式开关，还有规则集分层。crates/execpolicy/src/lib.rs 定义了 RulesetLayer（BuiltinDefault < Agent < User，序号越大优先级越高）与 Ruleset 结构，后者包含 trusted_prefixes（免审批的命令前缀）、denied_prefixes（无论信任规则如何都拦截的前缀）和 ask_rules（针对具体工具调用的类型化审批规则）——这正是 README 所说“repositorio 规则限制 Agent 能做什么”的落点，且用户层规则可覆盖 Agent 层规则。

回退能力：/undo 回退最后一轮对话，/restore 将工作区恢复到早期快照，二者配合让“放手让 Agent 干活”具备了安全网。

核心特性三：长时程工作管理

README 的卖点第三条：“Mantén organizado el trabajo de larga duración”（保持长时程工作有序），包含四个具体能力：

• 保存会话：任务可跨终端会话续接（对应前述 --continue / --session-id / --resume 三组参数）；
• /goal 持久目标：设定一个贯穿多轮的目标，Agent 围绕它持续迭代；
• 工作流先审后跑：审查工作流定义后再执行。仓库根目录的 workflows/ 即官方工作流示例（如 stopship.workflow.js、issue_audit.workflow.js），编写规范见 docs/WORKFLOW_AUTHORING.md；
• Agent 协同不污染对话：协调子 Agent 时，其内部指令不会泄漏进你的主对话上下文。

核心特性四：可扩展的 Agent

README 的卖点第四条：“Amplía el agente que ya tienes”（扩展你已有的 Agent）：

• MCP 服务器：连接 Model Context Protocol 服务器扩展工具面（docs/MCP.md）；
• 技能（Skills）：以 Markdown 文件形式挂载技能（docs/SKILLS.md）；
• Hooks：生命周期钩子拦截关键节点（docs/HOOKS.md，对应 crates/hooks crate）；
• Agent 角色即文件：Agent 角色以可读文件保存在项目或个人配置中，可审阅、可版本化。

在 TUI 中随时执行 /help 可查看全部命令与键位。

安全模型：权限分层 + 可选系统级隔离

README 的安全章节给出四条原则（继承全文）：

1. 本机运行，权限自授：Codewhale 运行在你的设备上，只有你授予的访问范围；
2. 审批模式 + 仓库规则双重约束 Agent 行为（即上文 ApprovalMode 四层模式 + Ruleset 前缀规则）；
3. 可选的操作系统级隔离：在平台支持时，追加一道更强的执行边界（详见 docs/SANDBOX.md）；
4. 未知价格保持未知：模型定价未知时保持“未知”状态，而不是显示为免费。

完整的策略优先级（哪种规则覆盖哪种规则、系统策略与仓库规则如何裁决）请阅读 授权顺序；本地配置项（含环境变量参考）见 配置文档 与示例文件 config.example.toml。

文档索引

README 的文档导航区（已转换为仓库根相对路径）：

• 供应商与本地模型
• Agent 编队（Fleet）
• MCP、Hooks 与 配置
• 本地 Web 客户端
• 全部文档

补充两个高频入口：docs/INSTALL.md 覆盖所有安装路径与常见失败（含 Linux ARM64），docs/ARCHITECTURE.md 描述整体架构，docs/CODEWHALE_AGENT.md 面向以 Codewhale 本身为开发对象的贡献者。

项目历史与社区

从 deepseek-tui 演进而来：README “Historia del proyecto” 一节说明，Codewhale 最初名为 deepseek-tui，至今仍保留对其配置与会话的向后兼容（这也是 docs/PROVIDERS.md 中“新配置写入 ~/.codewhale/config.toml，旧的 ~/.deepseek/config.toml 仍会被读取”这一行为的由来）。如今它在供应商上中立，独立维护，不隶属于任何模型供应商。npm 侧保留了这一历史痕迹：包名 codewhale 之外，仓库内仍有独立的 npm/deepseek-tui/ 包装器。

社区参与：缺少某个供应商、工作流体验不佳、或终端界面碍事，都可以开 Issue；知道怎么改进就开 PR（流程见 CONTRIBUTING.md），首次贡献被欢迎，贡献者保留被合入工作的署名。官方社区入口为 Discord，以及通过 WeChat（hunterbown）申请加入 Whale Brothers 群。贡献者名录见 docs/CONTRIBUTORS.md。

许可

MIT 协议（LICENSE）；从其他开源项目改编的部分登记在 第三方声明（仓库根目录另有 THIRD_PARTY_NOTICES.md 与之对应）。

小结

Codewhale 的价值主张可以收敛为三句话：模型随便选（42 家供应商 + Ollama/vLLM/SGLang 本地运行时，/model 随时切换）、行为可管控（Ask/Auto-Review/Full Access/Plan 四档审批 + 规则前缀 + /undo、/restore 安全网）、长任务可持续（会话续接、/goal、工作流、子 Agent 协同）。全部能力在源码层面都有对应 crate 支撑——crates/execpolicy 管审批、crates/config 管供应商路由、crates/tui 管交互——这意味着本文所述行为不是文档承诺，而是可以逐文件验证的实现事实。