Codewhale 终端编程 Agent：从安装、使用到审批模式与授权层的完整技术指南

Codewhale 是一个用 Rust 编写的开源终端编程 Agent，运行在你的本机上，可以读取仓库、编辑文件、执行命令并持续朝目标推进工作。本文基于仓库根目录的多语言 README 主体 README.ca.md（加泰罗尼亚语版）及其对应的英文原版 README.md 展开，结合安装指南 docs/INSTALL.md、授权顺序文档 docs/AUTHORIZATION_ORDER.md 与核心 crate 源码，完整覆盖 Codewhale 的安装方式、日常使用、审批模式、可扩展性与安全模型，帮助你在实际项目中把它部署起来并正确控制它对系统资源的访问边界。

一、Codewhale 是什么

Codewhale 的定位可以用 README 中的一句话概括：一个面向终端的开源编码 Agent，用 Rust 构建，并与社区公开地共同演进。它的核心能力包括：

• 读取你的代码仓库、编辑文件、执行 shell 命令、检查结果；
• 持续朝着你设定的目标推进（durable goal）；
• 支持托管模型与本地模型（Ollama、vLLM、SGLang 等）；
• 通过 MCP 服务器、skills、hooks 与可读的 Agent 角色文件进行扩展。

从源码结构看，整个产品是一个多 crate 的 Rust workspace：Cargo.toml 声明了 crates/cli、crates/tui、crates/core、crates/config、crates/execpolicy、crates/tools、crates/mcp、crates/workflow 等成员，当前 workspace 版本为 0.9.11，要求 Rust 1.88+（因为代码大量使用了 let_chains）。CLI 入口 crates/cli/src/main.rs 采用单二进制 argv0 分发——codew 只是 codewhale 的别名，不再编译第二个可执行文件，这使得发布物保持“一个二进制 + 便捷命令名”的轻量形态。

项目历史值得注意的一点：Codewhale 最初名为 deepseek-tui，至今仍保留旧配置与旧 session 的兼容；现在是中立的（provider-neutral）、独立维护的项目，不与任何模型提供商有隶属关系。相关兼容痕迹可以在 npm 目录 npm/deepseek-tui 中看到。

二、安装

2.1 最短路径：npm

README 给出的默认安装方式（Node 18+）：

npm install -g codewhale
codewhale

首次运行会引导你连接一个模型提供商，或者选择完全离线运行。npm 包的 postinstall 脚本会下载匹配的 codewhale 与 codew 二进制，对照来源的 SHA-256 清单校验，然后把两个命令暴露到 PATH 上。

2.2 其他安装渠道

安装指南 docs/INSTALL.md 覆盖了所有受支持的路径，README 中提到的渠道包括：

渠道	说明
Cargo	cargo install codewhale-cli --locked，安装 codewhale 命令；Linux 需先装 build-essential pkg-config libdbus-1-dev（凭据存储的 D-Bus secret-service 后端依赖 libdbus-1）
GitHub Releases 手动下载	裸二进制 codewhale-<platform> / codew-<platform>，配合 codewhale-artifacts-sha256.txt 校验
Nix	nix run github:Hmbown/CodeWhale，或把 flake 加进 flake.nix
Windows	Scoop 主桶、winget 包 Hmbown.CodeWhale（清单见 packaging/winget/Hmbown.CodeWhale.yaml）、NSIS 安装器
Android / Termux	独立的 arm64 归档（预览阶段），不能混用 Linux arm64 归档
CNB 镜像	面向中国大陆网络的 first-party 镜像，Linux x64 的 npm wrapper 会自动并行探测 GitHub 与 CNB 的校验清单，取先通过校验的源

几个平台相关的要点（来自 docs/INSTALL.md）：

• Linux x64 / arm64 的发布资产是 musl 静态构建（x64 自 v0.8.65 起，arm64 自 v0.9.6 起），没有 glibc 版本下限，跨 Ubuntu、Debian、RHEL、Alpine 均可运行；SQLite 通过 rusqlite bundled 方式内嵌（见 Cargo.toml 中 rusqlite = { features = ["bundled"] }），不需要单独安装 libsqlite3；
• npm wrapper 的行为可以通过 CODEWHALE_RELEASE_BASE_URL、CODEWHALE_USE_CNB_MIRROR=1、CODEWHALE_VERSION、CODEWHALE_FORCE_DOWNLOAD=1 等环境变量控制，旧的 DEEPSEEK_TUI_* 变量名仍作为遗留别名被接受；
• 源码构建（cargo install --path crates/cli --locked）是覆盖 FreeBSD、musl 非 x64 等长尾平台的兜底方案。

2.3 Shell 自动补全

Tab 补全每个 shell 只需一条命令，脚本同时覆盖 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

Zsh、Fish、PowerShell、Elvish 的安装方式见 docs/INSTALL.md 第 8 节。注意：脚本是该版本命令面的静态快照，升级 Codewhale 后需要重新生成。

三、日常使用

与 Codewhale 对话的方式和与队友沟通一样直接。在 TUI 中直接输入自然语言任务：

Fix the failing tests and explain what changed.

也可以不打开 TUI、以无头方式运行任务：

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

Agent 会读取仓库、编辑文件、执行命令、检查结果，并持续朝目标推进——而你决定给它多少访问权限。TUI 中运行 /help 可以查看全部命令与键盘快捷键。

四、审批模式：Plan、Ask、Auto-Review、Full Access

这是 Codewhale 最核心的可控性设计。README 承诺：Plan 模式只读；Ask、Auto-Review、Full Access 让审批行为可见；/undo 回退上一轮，/restore 把工作区还原到先前的快照。

在源码层面，用户可见的审批姿态定义在 crates/execpolicy/src/approval_mode.rs：

pub enum ApprovalMode {
    Auto,      // 先自动评审有风险的工具调用，再决定是否询问
    Bypass,    // 完全绕过审批（YOLO / --yolo）
    Suggest,   // 默认值：对非安全工具建议审批
    Never,     // 永不执行需要审批的工具
}

几个值得注意的实现细节：

• 配置值接受大量别名：from_config_value 会把 "auto" | "auto-review" | "auto_review" 统一解析为 Auto，"bypass" | "yolo" | "full-access" | "full" 等统一解析为 Bypass，"ask" | "untrusted" | "suggest" 等解析为 Suggest——这意味着旧配置（如 approval_policy = "untrusted"）无需迁移；
• Shift+Tab 权限循环：PERMISSION_CYCLE = [Suggest, Auto, Bypass]，在 TUI 中按 Shift+Tab 即可在三档之间循环，Never 不进入热键循环；
• 展示层与策略层解耦：permission_chip_label 给出 TUI 上显示的 "Ask" / "Auto-Review" / "Full Access" / "Never" 标签，而策略判定共享同一枚举定义，TUI 只在其上叠加展示。

授权顺序：一次工具调用要过几道门

docs/AUTHORIZATION_ORDER.md 记录了交互式引擎对模型请求的工具调用的完整评估管线，共 9 层，顺序是：

1. 有效配置与姿态：用户设置、命令/运行时覆盖、项目叠加层在回合开始前解析；项目叠加层只能收紧 approval_policy、sandbox_mode 与 shell 可用性，不能放松；
2. 模式与工具准入：Plan 模式限制、输入解析错误、每命令工具 deny/allow 列表、调用方限制——工具同时出现在两个列表中即被拒绝；
3. 准备 + tool_call_before hooks：注册表准备无副作用；前台 hooks 按 deny > ask > allow 折叠，最后一条 updatedInput 生效；
4. 注册工具的基线：工具自带的 ApprovalRequirement 决定常规审批需求；Plan 模式在此层拦截可写工具；
5. 类型化 permissions.toml 规则：匹配的 deny 直接阻断；allow 只能清除常规注册审批，清不掉 hook 的 ask 或不可绕过的注册持有；
6. 自动评审策略与内置安全底线：配置的阻断规则先于内置底线执行；Full Access 有意跳过交互式发布持有，但灾难性的破坏性后台/无头动作仍受保护；
7. 仓库法则（repository law）：受保护路径不变量只能追加提示或阻断；在 Full Access 下，repo-law 提示直接升级为硬阻断；
8. 人工审批：剩余提示送到审批通道，拒绝即停止；
9. 工具权限与执行沙箱：worker 权限包络、原生工具路径检查、操作系统或外部沙箱在执行期间仍然生效。

关键设计原则是单调收紧：类型化权限层之后的 auto-review 与仓库法则只能让结果更严，不能把前面的阻断或提示变成未审查的执行。这套契约有明确的回归测试覆盖，例如 authorization_order_contract_matches_documented_precedence（位于 crates/execpolicy/tests/authorization_order.rs）、full_access_permission_allow_cannot_bypass_repo_law 等，可以用文档中给出的聚焦命令复现：

cargo test -p codewhale-execpolicy --test authorization_order --locked

permissions.toml 的规则选择遵循“来源层 → 动作强度 → 匹配器具体度”的字典序优先级（User > Agent > BuiltinDefault；deny > ask > allow；同级同动作下更具体的匹配器胜出），且硬性命令前缀 deny 在任何类型化 allow 之前检查、不可被覆盖。

五、长任务组织与扩展

README 的“Why Codewhale”一节列出的四类能力，对应仓库中的具体模块：

• 会话与目标：保存会话、设置持久 /goal、在执行前审查 workflow。workflow 由 crates/workflow 与 crates/workflow-js（基于 rquickjs 的单线程 JS VM，通过 channel 桥接到多线程引擎）驱动，仓库自带 workflows/stopship.workflow.js 等示例；
• Agent 团队（Fleet）：协调多个 Agent，同时不让它们的内部指令污染你的会话记录，设计见 docs/FLEET.md；
• 扩展点：MCP 服务器（crates/mcp，文档 docs/MCP.md）、skills、hooks（crates/hooks，文档 docs/HOOKS.md），以及把 Agent 角色保持为项目或个人配置中可读的文件；
• 本地 Web 客户端：文档见 docs/WEB.md。

模型侧保持中立：crates/config/src/lib.rs 中 ConfigToml 内建了 ollama 与 ollama_cloud 等 provider 配置槽位，docs/PROVIDERS.md 覆盖托管与本地模型的完整配置；TUI 中用 /model 切换提供商与模型。

六、安全模型

Codewhale 在你自己的机器上、以你授予的访问权限运行，安全设计分三层：

1. 审批模式 + 仓库规则：限制 Agent 能做什么，即上文第九层管线的 1–8 层；
2. 可选的操作系统级沙箱：在受支持的平台追加更强的执行边界（威胁模型见 docs/SANDBOX.md）。注意沙箱拒绝仍然是否决，除非用户单独授权受支持的提升路径；
3. 诚实的计费展示：模型价格未知时保持“未知”，不会被呈现为免费——这一策略由 crates/config/src/pricing.rs 与 docs/CONFIGURATION.md 的配置共同支撑。

另外，工作区级的 /restore list [N] / /restore <N> 提供 side-git 文件快照的回滚，这与安装的二进制版本无关、也不会改写会话历史。

七、文档地图与项目约定

README 给出的文档入口（均以仓库根目录为基准）：

• docs/PROVIDERS.md — 提供商与本地模型；
• docs/FLEET.md — Agent 团队；
• docs/MCP.md、docs/HOOKS.md、docs/CONFIGURATION.md — MCP、hooks 与本地配置；
• docs/WEB.md — 本地 Web 客户端；
• docs/AUTHORIZATION_ORDER.md — 精确的策略层级。

多语言方面，仓库维护了 18 种语言的 README（README.md 中列出的语言导航与 README.ca.md 的页眉导航一致），TUI 界面本地化见 crates/tui/locales（含中文简体 zh-Hans.json）。项目以 MIT 协议发布（LICENSE），改编自其他开源项目的部分记录在 docs/THIRD_PARTY_NOTICES.md；贡献流程见 CONTRIBUTING.md，贡献者记录见 docs/CONTRIBUTORS.md。