Codewhale 终端编码智能体:安装、使用、审批模式与安全授权体系实战指南

Codewhale 是一个用 Rust 构建、运行在你自己终端里的开源编码智能体(coding agent),它提供交互式 TUI 与无界面 exec 两种工作形态。本文以仓库的官方 README 为主线,结合 安装指南、授权顺序文档 与 CLI/执行策略源码,完整讲解 Codewhale 的安装方式、日常用法、模式与审批体系,以及它的授权与安全边界,读完你可以直接在本地跑起这个智能体并理解它"允许做什么、何时停下来问人"的底层机制。

一、项目定位:一个 provider 中立的终端智能体

Codewhale 的官方定位是:"一个开源的终端编码智能体,用 Rust 编写,与使用者一起公开地持续改进"。它具备一个终端编码智能体的核心能力闭环:

• 读取你的仓库:浏览文件、理解项目结构;
• 编辑文件:对代码进行写入与修改;
• 执行命令:在 shell 中运行构建、测试等操作;
• 检查结果并持续推进目标:在获得授权后多轮工作直到目标达成。

README 特别强调的一点是"由你决定它拥有多少访问权限"——Codewhale 的所有能力都挂在显式的审批模式之上(见第四节)。

项目历史:从 deepseek-tui 演化而来

Codewhale 最初名为 deepseek-tui,并保留了该项目的配置与 session 兼容性(旧的 deepseek-tui 配置和会话仍可被识别)。如今它已转变为 provider 中立、独立维护的项目,与任何模型厂商均无隶属关系。这一历史解释了仓库中多处存在的遗留命名:例如 npm 包环境变量同时接受 DEEPSEEK_TUI_* / DEEPSEEK_* 作为旧别名,Homebrew tap 仍叫 Hmbown/deepseek-tui。贡献者名单记录在贡献者文档中。

二、安装:一条 npm 命令起步,多种渠道可选

2.1 快速安装(npm)

官方推荐的最小路径是:

npm install -g codewhale
codewhale

首次运行时,Codewhale 会引导你连接一个模型 provider,或选择离线模式继续。npm 包的 postinstall 会下载与你平台匹配的 codewhale 与 codew 两个二进制,并按 SHA-256 清单校验后放入 PATH。

一个值得注意的实现细节:虽然发布物里有两个命令名,但它们是同一个二进制。从 crates/cli/src/main.rs 可以看到,程序启动时通过检查 argv0 的文件名来区分 codew 与 codewhale,注释明确写道:"codew 现在是 codewhale 的别名,不产生第二个编译产物",从而把安装面收敛到单个文件,同时保留短命令名。

2.2 Shell 自动补全

Tab 补全为每个 shell 准备了一条命令,同时为 codewhale 和 codew 两个名字生成补全:

codewhale completion bash|zsh|fish|powershell|elvish

脚本输出到 stdout,重定向到 shell 的补全目录即可,例如 Bash:

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

codewhale completions 是同义别名。补全脚本是当前版本命令面的"快照",升级 Codewhale 后需要重新生成。各 shell(zsh、fish、PowerShell、elvish)的完整写法见 安装指南第 8 节。

2.3 其他安装渠道

README 指出,Codewhale 除 npm 外还支持 Cargo、Docker、Nix、Scoop、预编译归档、Android/Termux,以及 CNB 镜像。docs/INSTALL.md 给出了全部路径的细节,要点摘录如下:

渠道	命令/说明
网站一键脚本(macOS/Linux)	curl -fsSL https://codewhale.net/install.sh | sh,下载后校验 SHA-256,默认装入 ~/.local/bin
Cargo	cargo install codewhale-cli --locked,需 Rust 1.88+;Linux 需先装 build-essential pkg-config libdbus-1-dev
Nix	nix run github:Hmbown/CodeWhale,参数放 -- 之后
Scoop(Windows)	scoop install codewhale
winget(Windows,v0.9.5+)	winget install Hmbown.CodeWhale,清单见 packaging/winget/Hmbown.CodeWhale.yaml
Homebrew	brew tap Hmbown/deepseek-tui && brew install codewhale
AUR(Omarchy)	omarchy pkg aur add codewhale-bin,提供 codewhale 与 codew 两个命令
手动下载	从 Releases 下载裸二进制或带 install.sh 的平台归档,用 codewhale-artifacts-sha256.txt 校验
CNB 镜像	面向中国大陆网络;npm 包装器在 Linux x64 上会并行探测 GitHub 与 CNB 的清单,取先通过校验的来源,选择结果写入 <binary>.source,校验失败则失败关闭

安装文档还给出了一组实用环境变量,如 CODEWHALE_RELEASE_BASE_URL(覆盖下载源)、CODEWHALE_USE_CNB_MIRROR=1(强制 CNB 镜像,仅限 Linux x64)、CODEWHALE_VERSION(钉住版本)等,旧的 DEEPSEEK_TUI_* 名称仍被接受为别名,但官方建议新脚本只使用 CODEWHALE_* 规范名。

几个从安装文档继承的重要事实:

• Linux x64/arm64 的发布二进制是 musl 静态构建,不依赖 glibc,SQLite 通过 rusqlite 内置,无需系统 libsqlite3;
• Android/Termux 与 Linux arm64 是不同目标,Termux 用户不能安装 Linux 的 arm64 归档,且该路径仍处于预览阶段;
• 回滚很简单:npm install -g codewhale@X.Y.Z 或 cargo install codewhale-cli --version X.Y.Z --locked --force;工作区内的 /restore 只回滚文件快照,不改变已安装的二进制版本。

三、使用:对话式 TUI 与 headless exec 两条路径

3.1 对话式:像对同事说话一样

在 TUI 里直接用自然语言下达任务,例如:

Fix the failing tests and explain what changed.

Codewhale 可以读仓库、改文件、跑命令、看结果,并朝着目标持续工作。在 TUI 内输入 /help 可以查看全部斜杠命令与快捷键。

TUI 还有三层可切换的概念(详见 docs/MODES.md):

• Tab 键在三种可见模式间循环:Plan → Work → Operate。Plan 是只读的设计/研究模式,运行时集中拒绝文件变更与 shell 执行;Work(内部值 agent)是常规多步执行,首轮工具箱为 read、write、edit、bash、agent、todo_write;Operate 是多任务指挥姿态,父会话负责把可并行的工作派发给后台 worker;
• Shift+Tab 循环权限姿态(Ask → Auto-Review → Full Access);
• Ctrl+T 循环推理力度(reasoning effort)。

3.2 Headless:不打开 TUI 执行任务

脚本化、CI、管道场景使用 exec:

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

从 crates/cli/src/lib.rs 中 Exec 子命令的帮助文本可以看到其约定:

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

Common forwarded flags:
  --auto                           启用带自动审批的工具智能体模式
  --json                           输出摘要 JSON
  --resume <SESSION_ID>            按 ID 或前缀恢复先前会话
  --session-id <SESSION_ID>        同上
  --continue                       继续本工作区最近一次会话
  --output-format <FORMAT>         输出格式: text 或 stream-json

帮助文本明确说明:不带 --auto 的裸 codewhale exec 是一次性的模型响应;要启用非交互的文件/ shell 工具使用,必须加 --auto。

3.3 CLI 命令面一览

同一个二进制还暴露了完整的子命令集(定义在 crates/cli/src/lib.rs 的 Commands 枚举中),与 README"长任务组织"一节的能力一一对应:

子命令	作用
run	交互式或非交互式任务
doctor	运行诊断
models	列出所选 provider 的在线模型
sessions / resume / fork	保存、恢复、分叉会话——对应 README 的"保存会话"能力
pod(别名 fleet)	管理持久化的 Agent Pod 运行,如 codewhale pod init、codewhale pod run tasks.json --max-workers 4、codewhale pod status
workflow	通过 Lane Runtime 执行签入仓库的 Workflow,例如 codewhale workflow run stopship --fleet stopship --runtime tmux
init	在当前目录创建默认 AGENTS.md
setup / remote-setup	引导 MCP 配置/技能目录;生成远程智能体部署包
rc	启动交互会话并移交给 Codewhale web 应用
speech(别名 tts)	用小米 MiMo TTS 模型生成语音

pod 与 fleet 的关系值得注意:源码注释说明 pod 是规范拼写,fleet 是兼容别名,而持久账本 .codewhale/fleet.jsonl、保存的名册 fleets/<name>.toml、[fleet] 配置表等数据格式保留 Fleet 名称,保证跨版本可读。

3.4 扩展能力:MCP、Skills 与 Hooks

README"扩展你已有的智能体"一节指出,你可以:

• 连接 MCP 服务器与技能(skills);
• 配置 hooks(生命周期钩子);
• 把"agent 角色"维护成项目内或个人配置里可读的文件。

对应文档分别是 MCP、hooks 与 配置;仓库内的 config.example.toml 是完整的带注释配置样例,例如 [providers.*] 段允许同时保存多个 provider 的凭据,这样 /provider ollama、/provider vllm、/provider openai 等切换时不必重填密钥。

四、审批模式与安全边界

这是 README 中最值得展开的一节,因为它直接决定了"你决定它有多少访问权限"这句话如何落地。

4.1 源码层面的四种审批姿态

ApprovalMode 枚举定义在 crates/execpolicy/src/approval_mode.rs,执行策略代码与 TUI 共享这一定义,TUI 只在其上叠加展示:

pub enum ApprovalMode {
    Auto,      // 先自动审查风险工具调用,再决定是否询问(AUTO)
    Bypass,    // 完全绕过审批(YOLO 模式 / --yolo 标志)
    Suggest,   // 对非安全工具建议审批(默认值)
    Never,     // 从不执行需要审批的工具
}

permission_chip_label 方法给出了 TUI 界面上用户看到的名称映射:Suggest → Ask、Auto → Auto-Review、Bypass → Full Access、Never → Never。PERMISSION_CYCLE 常量定义了 Shift+Tab 的循环顺序 [Ask, Auto-Review, Full Access],与 docs/MODES.md 中"按 Shift+Tab 循环权限姿态"的描述一致。配置解析 from_config_value 还接受大量同义值(yolo、full-access、on-request、ask、deny 等),方便迁移自其他工具的配置。

README 提到的"Plan 是只读的"在 docs/MODES.md 中有精确表述:Plan 模式下"运行时集中拒绝文件变更与 shell 执行,只读检查与策略允许的研究仍然可用"。而 /undo 回退上一轮、/restore 把工作区恢复到更早的快照,对应 TUI 中的 undo 与 restore 命令实现。

4.2 授权顺序:9 层管线,后层只能收紧

README 把"安全"浓缩为一段话:

Codewhale 运行在你的机器上,只拥有你授予的访问权限。审批模式与仓库规则限制智能体能做什么;在受支持的环境中,可选的操作系统沙箱提供更强的执行边界。未知模型的价格保持"未知",而不会被报告为免费。

完整的策略栈记录在 docs/AUTHORIZATION_ORDER.md。其核心是一张交互引擎对模型请求的工具调用求值顺序表,共 9 层:

顺序	层	结果要点
1	有效配置与姿态	用户设置、命令/运行时覆盖、项目覆盖在回合前解析;项目覆盖只能收紧审批策略、沙箱模式或 shell 可用性,不能放松
2	模式与工具准入	Plan 模式限制、解析错误、逐命令工具 deny/allow 列表先行;同时出现在两个命令列表里的工具被拒绝
3	准备与 tool_call_before hooks	前台 hooks 按 deny > ask > allow 折叠;严格匹配的 hook 未产生裁决时失败关闭;最后一个 updatedInput 生效
4	注册工具基线	工具的 ApprovalRequirement 建立常规审批需求;Plan 模式在此拦截写能力工具
5	permissions.toml 类型化规则	deny 阻断;allow 只能清除常规注册审批,不能清除 hook ask 或不可绕过的注册保留;Full Access 不会把自动审批降级为弹窗
6	自动审查策略与内置安全底线	配置的阻断规则先于内置底线运行;可加提示或阻断,但不能移除更早的保留
7	仓库法(repo law)	受保护路径不变式只能追加提示或阻断;在 Full Access 下,仓库法提示变成硬阻断
8	人工审批	拒绝即停止;会话/持久化选择影响后续匹配调用,但不清除本次调用中后门的关卡
9	工具权限与执行沙箱	执行期间的 worker 权限、原生路径检查、OS/外部沙箱仍然生效;沙箱拒绝就是拒绝

文档特别强调一个设计原则:类型化权限层之后的顺序是单调的——自动审查和仓库法只能收紧结果,不能把前面的阻断或提示变成未经审查的执行。permissions.toml 的选取算法(源层 User > Agent > BuiltinDefault → 同层内动作 deny > ask > allow → 更具体的匹配器决胜)也一并记录在案,且有对应的回归测试(如 cargo test -p codewhale-execpolicy --test authorization_order --locked)。

项目级覆盖(<workspace>/.codewhale/config.toml)不是权限规则层,它只能把姿态向更严格方向移动:审批 auto → on-request/untrusted → never、沙箱 danger-full-access → workspace-write → read-only、shell 可用 true → false(不可反向),且不能添加凭据、hooks 或项目级 permissions.toml。

4.3 沙箱与价格诚实

README 还提到两点值得记住:

1. 可选的 OS 沙箱(在 Linux 上为 bubblewrap 子进程沙箱)是比审批更强的执行边界,受支持平台才可用;审批不等于 OS 沙箱授权;
2. 价格诚实:模型价格未知时,界面显示"未知"而绝不误报为免费——这一点在配置示例的定价段与 config.example.toml 的模型目录机制中都有呼应。

五、文档地图:从 README 出发的深入路径

README 末尾给出的官方文档入口(全部位于仓库 docs/ 目录)建议按如下顺序阅读:

• Provedores e modelos locais / Providers and local models —— provider 与本地模型(Ollama、vLLM、SGLang);
• Equipes de agentes / Agent teams —— 多智能体协作与 codewhale pod 的完整语义;
• MCP、hooks 与 configuração / configuration —— 扩展与本地设置;
• Cliente web local / Local web client —— 本地 web 客户端(即 codewhale rc 指向的 web 应用);
• 安全专题:授权顺序、沙箱威胁模型、模式与权限姿态。

README 中"用任何你想要的模型"这一点,在配置样例中表现为一个庞大的 provider 列表:deepseek、openai、anthropic、openrouter、ollama、vllm、sglang、fireworks、moonshot、qianfan、xai 等,配合 default_text_model 与 /model 命令随时切换;auto 值可在 flash/pro 之间按任务复杂度自动路由。

六、社区参与、许可与适用前提

• 社区:Codewhale 在公开使用中改进——缺失的 provider、不顺的工作流、碍事的 TUI 都可以通过 issue 上报;知道如何改进可以直接提 PR(流程见 CONTRIBUTING.md),首次贡献被欢迎,且贡献者保留对其合入工作的署名。
• 许可:项目以 MIT 协议 发布;从其他开源项目改编的部分记录在第三方声明中。
• 适用前提与限制:安装路径依赖当前发布的发布物;latest 解析到的是已发布版本,可能与源码分支的候选版本存在差距;npm 路径要求 Node 18+;Cargo 路径要求 Rust 1.88+;Android/Termux 仍为预览,FreeBSD 无预编译产物需源码构建。具体平台矩阵与故障排查(如 Unsupported architecture、MISSING_COMPANION_BINARY、中国大陆网络下的镜像方案)均以 docs/INSTALL.md 的现行版本为准。

七、小结

Codewhale 的核心价值可以概括为三点:provider 中立(任何托管或本地模型都能接入)、权限显式(Ask/Auto-Review/Full Access 三档可见姿态 + 9 层单调收紧的授权管线 + 可选 OS 沙箱)、形态完整(对话 TUI、headless exec、会话管理、Pod 多智能体、Workflow、MCP/技能/hooks 扩展)。安装只需一条 npm install -g codewhale,而安全边界从 crates/execpolicy/src/approval_mode.rs 的策略定义到 docs/AUTHORIZATION_ORDER.md 的文档契约都有源码级对应,这使得"给多少权限"始终是一个可检查、可回滚(/undo、/restore)的决定,而不是黑箱。