Codewhale：Rust 终端编程 Agent 的安装、使用与权限控制实战指南

2026-09-05 19:11:49作者：宣海椒Queenly

Codewhale 是一个以 Rust 编写的开源终端编程 Agent，本文围绕项目 README 的核心内容展开：从 npm/Cargo/Nix 等多种安装路径，到 TUI 交互与 codewhale exec 无界面运行方式，再到 Plan/Work/Operate 模式、Ask/Auto-Review/Full Access 权限档位与 /undo、/restore 等回滚机制。读完后你将掌握 Codewhale 的完整落地流程，并能结合源码理解其权限控制与安全边界的实际实现。

项目定位

Codewhale 是一个运行在终端里的开源编程 Agent。它用 Rust 编写，并以开放的方式与用户社区共同演进。它的核心能力是像对待队友一样对待它——用自然语言下达任务（例如 Fix the failing tests and explain what changed.），它会读取你的仓库、编辑文件、执行命令、验证结果，并围绕目标持续推进工作。与此同时，你能给它多大权限完全由你自己决定。

项目前身是 deepseek-tui，目前仍保持与其配置与会话的兼容性，但现在已经是中性的、可对接多家模型供应商的独立项目，不再绑定任何单一模型提供商。完整的更名映射关系（旧命令 deepseek / deepseek-tui → 新命令 codewhale / codew，npm 包、crates.io 包名、Release 资产名的变化）见 REBRAND.md。

安装

快速安装（npm）

npm 是推荐的安装方式：

npm install -g codewhale
codewhale

首次启动时，Codewhale 会引导你连接一个模型供应商（provider），或者选择保持离线/自主模式运行。npm 包的 postinstall 阶段会下载与你的平台匹配的 codewhale 与 codew 两个二进制文件，并用随发布附带的 SHA-256 清单校验后再暴露到 PATH 上；codew 只是同一运行时二进制的一个便捷别名。

其他安装路径

Codewhale 同时支持 Cargo、Docker、Nix、Scoop、预编译归档下载、Android/Termux 以及 CNB 镜像。完整平台支持矩阵、校验流程与故障排查见安装指南，常用路径摘要如下：

方式	命令
Cargo（需 Rust 1.88+）	`cargo install codewhale-cli --locked`
Nix（flake）	`nix run github:Hmbown/CodeWhale`
Windows Scoop	`scoop install codewhale`
Windows winget	`winget install Hmbown.CodeWhale`
手动下载	从 Releases 获取 `codewhale-<platform>` / `codew-<platform>` 二进制放入 `PATH`

在 INSTALL.md 中还值得注意几点：

Linux x64 与 arm64 的发布产物是静态 musl 构建，不依赖 glibc，内置 SQLite，在 Ubuntu、Debian、RHEL、Alpine 上均可运行；
Linux x64 上 npm 包装器会并行探测 GitHub Releases 与 CNB 第一方镜像的校验清单，选择第一个校验通过的来源下载二进制，失败即中止（fail closed）；CODEWHALE_RELEASE_BASE_URL、CODEWHALE_USE_CNB_MIRROR=1 等环境变量可覆盖下载源与超时预算；
验证安装是否正常：codewhale --version 与 codewhale doctor（后者检查 API Key、供应商配置、运行时与 PATH 完整性，发现问题时以非零码退出并输出结构化修复建议，--json 可输出机器可读结果）。

Shell 自动补全

每种 Shell 只需一条命令生成补全脚本（codewhale completions 为等价别名），脚本同时覆盖 codewhale 与 codew 两个命令名：

codewhale completion <bash|zsh|fish|powershell|elvish>

例如 Bash：

mkdir -p ~/.local/share/bash-completion/completions
codewhale completion bash > ~/.local/share/bash-completion/completions/codewhale

脚本写入 stdout，重定向到对应 Shell 加载补全的目录即可。注意：升级 Codewhale 后应重新生成脚本，因为它生成时的命令面快照不会自动更新。各 Shell 的具体安装步骤见安装指南第 8 节。

使用方式

TUI 交互

直接运行 codewhale 进入全屏 TUI。像对同事说话一样给它任务：

Fix the failing tests and explain what changed.

TUI 中有三个可见的交互模式，空输入框时按 Tab 循环切换 Plan → Work → Operate → Plan：

Plan：设计优先的只读模式。运行时集中拒绝文件修改与 Shell 执行，只保留只读检查与策略允许的研究类操作；
Work（内部名 agent）：常规多步执行。首轮小工具箱为 read、write、edit、bash、agent、todo_write，实际可执行什么仍由审批、沙箱与仓库策略共同裁定；
Operate：多任务调度姿态。权限与 Work 相同，但对独立/可并行的子任务默认派发后台 worker，父会话作为 operator 做汇总。

权限档位是独立于模式的另一根轴：Shift+Tab 在 Ask → Auto-Review → Full Access 之间循环，决定 UI 在执行工具前询问的激进程度；Ctrl+T 循环切换推理强度。模式选择器可通过 /mode（或 /mode work、/mode plan、/mode operate）打开。各模式下的工具可用性与完整语义见 MODES.md。

无界面执行（exec）

不开 TUI 也能直接跑任务，这很适合 CI 或脚本：

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

从源码结构看，exec 在 CLI 层被解析为 Commands::Exec(TuiPassthroughArgs)，随后通过 run_tui_in_process 在当前进程内运行 TUI 运行时——即当前版本是单一二进制、TUI 在进程内运行，不再需要额外的伴随可执行文件。参数解析与派发逻辑位于 CLI 入口，其中还处理了 --provider 顶层覆盖：自定义 provider 只被 exec 与 pod 命令接受，其余命令只认内置供应商名。

在支持操作系统的沙箱里执行时，Codewhale 的 opt-in bubblewrap 子进程沙箱仅构建于 Linux 目标（Android/Termux 上不可用），这在 INSTALL.md 的已知限制一节中有说明。

会话与长期目标

会话可以保存与恢复，跨终端重启继续工作；
/goal <objective> 设置一个贯穿多轮的会话目标（可带 token 预算），/goal pause、/goal resume、/goal clear 控制其生命周期，无参数裸调用 /goal 展示当前进度；
工作流（Workflow）可以作为任何 TUI 模式之上的叠加层运行，用于可重复的顺序编排与大规模 fan-out，详见 AUTOMATIC_WORKFLOWS.md。

为什么选择 Codewhale

README 列出了四条核心卖点，这里逐一结合仓库实现展开。

1. 使用你需要的模型

可以接入云端供应商，也可以通过 Ollama、vLLM 或 SGLang 使用本地模型，随时用 /model 切换供应商与模型。供应商配置体系（内置供应商清单、[providers.*] 自定义段、default_text_model 默认值、环境变量覆盖）在 CONFIGURATION.md 中有完整说明，供应商选型与本地模型接入见 PROVIDERS.md。仓库根目录提供了可直接参照的 config.example.toml，内置供应商描述则存放在 provider_descriptors.json 与 models_dev.bundled.json 等打包资产中。

2. 保持控制权

Plan 模式只读：设计期不会误改文件；
权限档位可见：Ask、Auto-Review、Full Access 三档的确认顺序直观可辨。从源码看，这些档位对应 ApprovalMode 枚举中的 Suggest（Ask）、Auto（Auto-Review）、Bypass（Full Access）与 Never，策略代码与 TUI 共享同一枚举，避免两套命名漂移；
回滚能力：/undo 撤销上一步，/restore <N> 把工作区文件恢复到更早的快照（/restore list [N] 列出 side-git 文件快照）。快照机制实现在 snapshot 模块，/undo 命令处理器位于 undo.rs。

3. 组织长时间任务

保存会话、设置持久 /goal、运行前先审查工作流（workflow 文件以 .workflow.js 形式存放在项目内，例如 stopship.workflow.js），并以协调多个 Agent 的方式推进工作——各 Agent 的内部指令不会泄漏到你的对话记录中。多 Agent 编排语义见 FLEET.md。

4. 扩展已配置的 Agent

MCP 服务器：接入 Model Context Protocol 服务器扩展工具面，见 MCP.md；stdio 客户端实现在 stdio_client.rs；
技能（Skills）：以 Markdown 描述的可复用能力包，TUI 内置技能资产位于 crates/tui/assets/skills/，写法见 SKILLS.md；
Hooks：生命周期钩子用于在事件发生时执行自定义逻辑，见 HOOKS.md；
Agent 角色文件：以项目内或个人配置中清晰可读的文件形式定义 Agent 角色。

想查看完整的命令与快捷键清单，在 TUI 中执行 /help 即可。

安全模型

Codewhale 以你授予的权限运行在你自己的机器上。其安全边界是分层叠加的：

审批模式与仓库规则：权限档位决定哪些工具执行前需要确认，仓库级策略（repository law）进一步收窄行为；
操作系统沙箱：在支持的平台（Linux，bubblewrap）上追加一层更严格的执行边界；
策略求值顺序：多个来源的策略如何按序叠加与短路，完整顺序定义在 AUTHORIZATION_ORDER.md；
透明的成本显示：未知价格的模型显示为"未知"而非 0，避免对账单产生误导——这一行为在 CONFIGURATION.md 的计费相关章节中有对应说明。

本地配置的完整参考（文件位置、config/profile/home 路径、provider/model/base-URL 路由）见 CONFIGURATION.md。需要注意的适用前提：沙箱能力与密钥管理后端随平台而异（例如 Termux 构建回退到 0600 权限的明文文件存储，无操作系统密钥环集成），详见 INSTALL.md 的 Android/Termux 一节。

项目结构与许可证

从 crate 组织看，代码分层清晰：crates/cli（CLI 分发与参数解析）、crates/tui（终端界面与运行时）、crates/core（会话、回合循环、工具解析）、crates/execpolicy（审批与执行策略）、crates/config（供应商目录与配置解析）、crates/mcp、crates/hooks、crates/protocol、crates/telemetry 等，工作区定义在根 Cargo.toml，各 crate 可独立浏览。

Codewhale 以 MIT 许可证发布（LICENSE），适配自其他开源项目的部分在第三方组件声明中逐一注明。