Codewhale 终端编码代理实战指南：安装、exec 非交互执行、审批模式与多模型接入

2026-09-05 23:39:03作者：钟日瑜

Codewhale 是一个用 Rust 编写的开源终端编码代理（coding agent），可在你的终端里读取仓库、编辑文件、执行命令并持续推进一个目标。本文基于项目官方德语 README 的全部核心内容展开，并结合当前仓库的源码实现，带你完整掌握 Codewhale 的安装与 Shell 补全、TUI 与 codewhale exec 两种使用方式、/model 模型切换与本地模型接入、Ask/Auto-Review/Full Access 审批模式及其底层实现、长任务组织手段（会话、/goal、Workflow）以及安全策略栈。读完后，你可以独立完成从安装 Codewhale 到配置审批行为、接入本地模型的全流程。

什么是 Codewhale

Codewhale 是一个与你共同在公开环境中持续演进的开源项目：它运行在你的机器上，以你授予的权限工作，提供商中立（provider-neutral），独立维护，不隶属于任何模型厂商。项目最初名为 deepseek-tui，至今仍保留其配置与会话的兼容性（即旧版 deepseek-tui 的配置和会话文件仍可被识别），如今已演进为可同时接入托管提供商或本地模型的通用编码代理。

项目的文档体系相当完整，入口都在 docs 目录：

许可协议为 MIT；从其他开源项目移植而来的部分统一记录在第三方组件声明中。

安装与 Shell 补全

最短的安装路径是 npm 全局安装：

npm install -g codewhale
codewhale

首次启动时，Codewhale 会引导你完成两件事之一：连接一个模型提供商，或保持离线状态。除 npm 之外，仓库文档还支持 Cargo、Docker、Nix、Scoop、预构建压缩包、Android/Termux 以及 CNB 镜像等多种安装路径，完整的平台支持矩阵（包括 Linux musl 静态构建、FreeBSD 源码编译等）以及常见安装失败排查见安装指南。

两个值得注意的安装事实（来自安装指南）：

已发布的 Linux x64/arm64 资产是 静态 musl 构建，无 glibc 依赖，SQLite 通过 rusqlite 内置，不需要系统 libsqlite3；
macOS/Linux 上最短的安装/升级路径是官网安装脚本，它还会顺带暴露 codew 便捷命令。

Tab 补全对每种 Shell 都是一条命令（codewhale completions 是其接受的别名）：

codewhale completion bash|zsh|fish|powershell|elvish

生成结果重定向到你所用 Shell 读取补全的目录即可，具体做法见 Shell 补全章节。

两种使用方式：TUI 会话与非交互 exec

Codewhale 的核心交互理念是"像对同事说话一样对代理说话"。在 TUI 里，你可以直接输入自然语言任务：

Fix the failing tests and explain what changed.

Codewhale 会读取你的仓库、编辑文件、运行命令、检查结果，并持续朝着目标工作；它获得多少访问权限，由你决定。

如果不希望打开 TUI，也可以用 exec 子命令在脚本或 CI 里非交互地执行任务：

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

从源码结构看，exec 是 CLI 层的一等公民子命令：参数解析与全局 flags 的处理集中在 CLI 库，其中明确识别 exec/eval 子命令并把后续参数按透传规则处理。这一行为有对应的单元测试约束，例如 exec 之后的 --provider 写法会被拒绝（exec_rejects_provider_after_subcommand），--provider 必须写在子命令之前；测试还覆盖了分隔符之后允许字面量 prompt flag 等边界（见 CLI 库中的 exec_* 系列测试函数）。这保证了 exec 在脚本化场景下参数语义稳定可预期。

在 TUI 中执行 /help 可查看当前可用的所有斜杠命令与快捷键。

使用你想要的模型：/model 与本地模型接入

Codewhale 提供商中立：既可以连接托管提供商，也可以通过 Ollama、vLLM 或 SGLang 接入本地模型。在 TUI 中用 /model 即可随时切换提供商和模型；模型命令的实现位于 TUI 命令组的 model.rs。

以 Ollama 为例，提供商文档给出的接入方式是：

ollama serve          # 如果尚未运行
ollama pull <model>   # 例如 deepseek-v4-flash，或任意你喜欢的 tag
codewhale --provider ollama --model <model>

本地 ollama 提供商默认走 http://localhost:11434/v1 的 OpenAI 兼容 Chat Completions 端点，OLLAMA_API_KEY 仅在需要认证的本地路由时可选；ollama-cloud 则是单独的托管提供商，使用独立的密钥配置。除 Ollama 外，文档还列出了 vllm、sglang、lm-studio、huggingface 等本地/自托管端点，完整的提供商清单、环境变量与配置写法见提供商文档。

保持控制权：审批模式、/undo 与 /restore

这是 Codewhale 与普通"自动改代码"工具最关键的差异点。它的控制模型分为三个正交概念（详见模式与权限姿态）：

TUI 模式：你当前处于哪种可见交互（Plan/Work/Operate）。其中 Plan 是只读的——不允许产生写副作用。
权限姿态（permission posture）：执行工具前 UI 以多激进的姿态请求批准，即 Ask、Auto-Review 和 Full Access 三档。
Workflow 叠加层：可选的长时编排层，运行在任何 TUI 模式之上。

TUI 里可用 Shift+Tab 在权限姿态之间循环切换。这个行为与姿态定义都沉淀在 execpolicy crate 中：ApprovalMode 枚举定义了 Suggest（默认）、Auto、Bypass、Never 四个变体，其中 Suggest → Auto → Bypass 正是 PERMISSION_CYCLE 常量（Shift+Tab 循环顺序）所定义的顺序，TUI 侧展示的芯片标签通过 permission_chip_label() 映射为文档中的 Ask / Auto-Review / Full Access / Never。

该枚举的 from_config_value() 还揭示了配置层面的完整取值别名（见 approval_mode.rs），这对读懂旧配置很有用：

文档术语	配置取值（不区分大小写）
Auto-Review	`auto`、`auto-review`、`auto_review`
Full Access	`bypass`、`yolo`、`dontask`、`dont_ask`、`bypass-permissions`、`full-access`、`full_access`、`full`
Ask	`suggest`、`suggested`、`on-request`、`untrusted`、`ask`
Never	`never`、`deny`、`denied`

也就是说，ApprovalMode 是策略代码与 TUI 共享的唯一定义，TUI 只在其上叠加展示逻辑（文件头注释即如此说明）。

误操作回滚同样内置：/undo 撤销最后一次交互（turn），/restore 把整个工作区回滚到更早的快照。这让"让代理放手改代码"和"随时可以退回"成为一对配套能力。

让长任务保持有序：会话、/goal 与 Workflow

对多步骤、跨会话的工程任务，Codewhale 提供了三件工具（均来自 README 的"保持长任务有序"条目）：

保存与恢复会话：会话持久化后可以在重启后继续；
持久目标 /goal：设置一个跨多轮对话持续生效的目标，代理始终朝它收敛。该命令在源码中注册为项目命令组的 goal（见 goal.rs，其中 name: "goal"），并与底层 create_goal/update_goal 工具联动；
Workflow 预检与多代理协调：先审查 Workflow 再执行；协调多个代理时，它们的内部指令不会泄漏进你的对话记录。Workflow 与代理团队（Fleet）的完整用法见 Workflow 文档与 Fleet 文档。

扩展你已有的代理：MCP、Skills、Hooks 与代理角色

README 的第四个价值点是"扩展你已有的代理"，对应的机制是：

MCP 服务器：通过 Model Context Protocol 接入外部工具与数据源，见 MCP 文档；
Skills：以 Markdown 形式定义的可复用技能；
Hooks：在工具调用生命周期中的固定点插入自定义逻辑，见 Hooks 文档；
代理角色（agent roles）：以可读的纯文件形式维护，放在项目内或个人配置目录中，方便版本管理与审阅。

这些扩展点与审批模式是正交的：Hook 的裁决会进入统一策略栈（下面一节），而不是旁路安全机制。

安全模型：审批、仓库规则与 OS 沙箱

Codewhale 安全承诺的四句话值得原文保留：它运行在你的机器上，只使用你授予的权限；审批模式与仓库规则共同限定代理能做什么；可选的 OS 级沙箱在受支持的系统上提供更强的执行边界；未知模型价格保持"未知"，而不会被谎报为免费。

策略层之间的精确优先级记录在授权顺序文档中。该文档定义了交互式引擎对"模型请求的工具调用"的 9 层流水线（摘要如下）：

顺序	层	要点
1	有效配置与姿态	用户设置、命令行/运行时覆盖、项目 overlay 在轮次前解析；项目 overlay 只能收紧、不能放宽
2	模式与工具准入	Plan 模式限制、输入解析错误、每命令 deny/allow 列表；同时出现在两份列表中的工具被拒绝
3	准备与 `tool_call_before` hooks	前台 hooks 按 `deny > ask > allow` 折叠，无裁决的严格 hook 失败关闭
4	注册工具基线	工具的 `ApprovalRequirement` 建立常规审批需求；Plan 模式在此拦截写工具
5	`permissions.toml` 类型化规则	`deny` 阻断；`allow` 只能清除常规注册审批，不能清除 hook 的 `ask`
6	Auto-review 策略与内置安全底线	可追加提示或阻断，但不能移除先前层的保留；Full Access 下灾难性破坏性操作仍受保护
7	仓库法（repository law）	受保护路径不变量只能追加提示或阻断；Full Access 下 repo-law 提示直接变硬阻断
8	人工批准	拒绝即停止；批准仅授权"本次计划中的调用"
9	工具权限与执行沙箱	工作区权限包、原生路径检查、OS/外部沙箱在执行期继续生效

一个关键设计结论：该顺序在类型化权限层之后是单调收紧的——后层可以加提示或阻断，但永远不能撤销前层的阻断；某一层"批准"不是万能通行证。局部配置示例可参考仓库根目录的 config.example.toml，完整的本地设置说明见配置文档。

参与社区与项目历史

Codewhale 的质量依赖于使用者的反馈与修复：缺少某个提供商、某个 Workflow 操作别扭、或 TUI 挡住你的视线，都欢迎通过 Issue 反馈；知道如何改进则直接提 Pull Request，首次贡献同样欢迎，贡献者保留其合入工作的署名。维护者会在贡献者记录中记录每一份贡献，协作流程见 CONTRIBUTING.md。

最后回顾项目史：Codewhale 始于 deepseek-tui，并继续维护其配置与会话兼容层；今天它已经是提供商中立、独立维护的项目，与任何模型厂商无隶属关系。

小结

安装：npm install -g codewhale 起步，codewhale completion <shell> 一键补全，更多平台路径见安装指南；
使用：TUI 里自然语言驱动，codewhale exec "任务" 用于脚本化场景；
模型：/model 切换，Ollama/vLLM/SGLang 本地接入见提供商文档；
控制：Plan 只读 + Ask/Auto-Review/Full Access 三档姿态（源码见 ApprovalMode），/undo 与 /restore 兜底回滚；
安全：9 层单调收紧的策略栈（授权顺序），OS 沙箱可选加固；
扩展：MCP、Skills、Hooks 与文件化代理角色；
许可：MIT。