Codewhale 终端编程 Agent 实战指南：安装、模型路由、审批控制与安全边界

2026-09-05 21:46:57作者：董宙帆

Codewhale 是一个用 Rust 编写的开源终端编程 Agent：它以 TUI 交互为主、codewhale exec 无头模式为辅，允许你接入任意托管或本地模型，并通过多层层级化的审批与沙箱机制约束 Agent 的行为边界。读完本文，你将掌握 Codewhale 的完整安装路径、两种使用方式、模型路由配置方法、审批模式（Ask / Auto-Review / Full Access）的底层实现，以及 OS 沙箱与权限规则组成的安全体系。

一、项目定位与仓库结构

Codewhale 自我定位是"为你的终端构建的开源编程 Agent"（an open source coding agent for your terminal），用 Rust 构建，并在社区公开协作中持续演进。从仓库根目录的工作区清单可以确认当前源码版本为 v0.9.11，要求 Rust 1.88+（rust-version = "1.88"，注释说明 1.88 稳定了 let_chains，代码库大量依赖该特性），许可证为 MIT，并包含 21 个成员 crate：

crate	职责
`crates/cli`	命令行入口（`codewhale` / `codew`），命令分发
`crates/tui`	终端 UI 主体（Ratatui）
`crates/config`	配置解析、Provider 注册表、模型目录
`crates/execpolicy`	审批模式与执行策略引擎
`crates/agent` / `crates/core`	Agent 运行时与单轮循环
`crates/mcp`	MCP stdio 客户端
`crates/workflow` / `crates/workflow-js`	工作流执行（基于 rquickjs 的 JS VM）
`crates/secrets` / `crates/telemetry` / `crates/state`	密钥存储、遥测、持久化状态

工作区根清单中还有一处值得注意的细节：通过 [patch.crates-io] 补丁了 unicode-width 0.2.2，让 width() 在 CJK 终端下使用正确的宽度表，修复了圈数字、方框字母等模糊宽度字符的渲染错位（见 Cargo.toml 补丁注释）。

二、安装：从 npm 一行命令到全平台路径

2.1 最简安装

官方 README 给出的最短路径是 npm：

npm install -g codewhale
codewhale

首次启动时，Codewhale 会引导你连接一个模型 Provider，或选择保持离线（local-only）运行。

2.2 完整安装矩阵

除 npm 外，项目还支持 Cargo、Docker、Nix、Scoop、预构建归档、Android/Termux 和 CNB 镜像。完整平台矩阵、校验和验证流程与各平台注意事项详见安装指南。其中有几个从仓库可确认的事实：

Linux x64/arm64 的发布产物是 musl 静态构建（无 glibc 依赖），SQLite 通过 rusqlite bundled 特性内嵌，无需单独的 libsqlite3；
每个发布包含 codewhale 与 codew 两个二进制，并附带 codewhale-artifacts-sha256.txt / codewhale-bundles-sha256.txt 校验清单；
Android/Termux 是独立的 Rust target，不能复用 Linux arm64 归档。

从源码看，codew 并不是第二个编译产物：CLI 入口通过检测 argv[0] 的 basename 实现单二进制双名称分发，"six-keystroke save"（少敲六个键）只是别名行为，安装面始终只有一个文件。

2.3 Shell 补全

Tab 补全每种 Shell 一条命令生成，codewhale completion 同时注册 completions 别名（见 CLI 定义中的长帮助文本）：

codewhale completion bash      # > ~/.local/share/bash-completion/completions/codewhale
codewhale completion zsh
codewhale completion fish     # > ~/.config/fish/completions/codewhale.fish
codewhale completion powershell
codewhale completion elvish

补全脚本注册的是 codewhale 名称，而非仓库内的 crate 名——这一点有专门的回归测试（issue #5526，防止 completions 子命令泄漏内部 crate 名）。更多细节见 docs/INSTALL.md 的 Shell completions 一节。

三、使用方式：自然语言对话与无头执行

3.1 TUI 对话

README 的用法哲学是"像对团队成员说话一样对 Codewhale 说话"。在 TUI 输入框中直接描述目标：

Fix the failing tests and explain what changed.

Codewhale 随后会读取仓库、编辑文件、运行命令、检查输出，并持续向目标推进——它能做多少，由你授予的访问范围决定（见第五节）。

3.2 无头模式

不打开 TUI 直接跑任务：

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

exec 在 CLI 命令树中对应 Commands::Exec，它接收 TUI 透传参数（TuiPassthroughArgs）。多 Agent 场景下，Pod（Agent 团队）的成员正是以无头 codewhale exec 的形式被委派协调器拉起，并由 Runtime 持久跟踪（见 FLEET.md）。Android/Termux 等 TUI 渲染受限的环境也建议优先使用 codewhale exec。

3.3 常用 TUI 命令

/model — 切换 Provider 与模型；
/undo — 回退上一轮（turn）的改动；
/restore — 将工作区恢复到某个早期快照；
/goal — 设置一个持久的长目标；
/help — 查看全部命令与键盘快捷键。

四、模型路由：Provider 中立与本地模型

Codewhale 的一个核心卖点是"用你想用的模型"：既可以接托管 Provider，也可以经 Ollama、vLLM、SGLang 接本地模型。它在 2026 年之前以 deepseek-tui 之名起步，如今是 Provider 中立、独立维护 的项目，与任何模型厂商无隶属关系，同时保留了对旧 deepseek-tui 配置与会话的兼容（~/.deepseek/ 在 ~/.codewhale/ 对应文件缺失时仍会作为兼容回退被读取，见 config.example.toml 路径注释）。

4.1 配置结构

仓库提供了高度注释化的 config.example.toml 作为配置事实来源。顶层关键字段：

# 顶层三件套：选 Provider、给密钥、定端点
provider = "deepseek"
api_key = "YOUR_DEEPSEEK_API_KEY"
base_url = "https://api.deepseek.com/beta"

# 默认模型；auto 会按任务复杂度在 flash/pro 间自动选择
default_text_model = "deepseek-v4-pro"

# 思考强度：off | low | medium | high | max（TUI 中 Ctrl+T 循环切换）
reasoning_effort = "max"

provider 的可选值是一个长枚举，涵盖 deepseek、nvidia-nim、openai、openrouter、moonshot、zai、anthropic、xai、sglang、vllm、ollama、huggingface 等数十个路由。每个 Provider 在 [providers.*] 表中独立存密钥，可以同时保存多个，用 /provider 或 --provider 随时切换而无需重输密钥；环境变量（如 OPENAI_API_KEY、OLLAMA_BASE_URL）优先级高于配置文件。

4.2 本地模型与通用兼容网关

接本地推理服务时，三个 Provider 表开箱即用（引自 config.example.toml）：

[providers.sglang]
base_url = "http://localhost:30000/v1"
model = "deepseek-ai/DeepSeek-V4-Pro"

[providers.vllm]
base_url = "http://localhost:8000/v1"
model = "deepseek-ai/DeepSeek-V4-Pro"

[providers.ollama]
base_url = "http://localhost:11434/v1"
model = "deepseek-v4-flash"

对于任意 OpenAI 兼容网关，用 provider = "openai" 配 [providers.openai] 表即可，不要自造 Provider 名——Provider 是"路由/账户/端点"，model 是该路由上的模型 ID。完整的 Provider 行为注册表（ID、配置键、认证路径、Base URL、模型解析）见 PROVIDERS.md，其底层实现在 crates/config/src/provider_kind.rs。

4.3 其他值得留意的配置

config.example.toml 还承载了大量默认值事实，例如：

更新检查：[update] check_for_updates 默认 true，结果缓存在 ~/.codewhale/update-check.json，check_interval_hours 控制周期；CI 环境下自动跳过；
原生记忆：[memory] enabled（默认 false，DEEPSEEK_MEMORY=on 可覆盖），开启后 TUI 加载 ~/.codewhale/memory/global/MEMORY.md 派生的存储并注册 remember / memory_search / memory_get 工具（docs/MEMORY.md）；
遥测：默认关闭，且需要"配置文件 telemetry = true + 首次运行通知回答 Enable"双因子才生效；telemetry = false 会删除安装 ID 并清空缓冲事件；
子 Agent 调优：max_subagents（默认 64，钳制在 1–128）、[subagents] max_depth（默认 3，硬上限 8，且是代码强制而非提示词约束）。

五、审批模式与可控性

README 强调"Plan 模式只读；Ask、Auto-Review、Full Access 让审批行为显式可见"。这四种姿态在源码中是一个共享枚举：crates/execpolicy/src/approval_mode.rs 定义了 ApprovalMode，TUI 层只叠加展示，策略引擎与 UI 共用同一份定义：

pub enum ApprovalMode {
    Auto,        // 自动审查危险调用（TUI 显示 "Auto-Review"）
    Bypass,      // 完全绕过审批（YOLO / Full Access）
    Suggest,    // 默认：非安全工具建议审批（TUI 显示 "Ask"）
    Never,      // 从不执行需要审批的工具
}

两个可验证的实现细节：

Shift+Tab 循环只覆盖三种模式。PERMISSION_CYCLE = [Suggest, Auto, Bypass]，即 Ask → Auto-Review → Full Access 循环；Never 不在热键循环里。这与 config.example.toml 的注释一致：Ctrl+T 切思考强度，Shift+Tab 切权限姿态。
配置值容错解析。from_config_value 接受 auto-review、yolo、full-access、on-request、untrusted 等多种拼写别名，统一映射回四个枚举；解析失败返回 None 而不是猜测。

配合 /undo（撤销上一轮）与 /restore（恢复到早期快照），你可以把大部分日常工作保持在可回滚的状态。完整的策略层叠顺序——从有效配置、工具准入、hooks、注册表基线、permissions.toml 类型化规则、自动审查、仓库法到人工审批与执行沙箱——记录在 AUTHORIZATION_ORDER.md，核心原则是：任何一层的批准都不是全局通行证，后序安全层仍可拦截。

六、长任务的组织与多 Agent 协作

针对长任务，README 列出的能力与仓库对应关系如下：

保存会话：会话状态持久化在 crates/state 与 crates/secrets（账户/密钥）中；
持久目标：/goal 为长任务锚定一个不随上下文压缩丢失的目标；
工作流先审后跑：工作流是项目内可读的 JS 文件（如 workflows/stopship.workflow.js），执行前可以审阅内容；运行时由 crates/workflow-js 中的单线程 QuickJS VM 承载，经 channel 桥接多线程引擎；
多 Agent 协调：Pod（旧称 Fleet）是本地优先的名册与成员选择层，codewhale pod 与 codewhale fleet 两个拼写等价；它不直接执行或授权工作，而是解析参与者后以无头 codewhale exec 委派执行（docs/FLEET.md）。

README 特别指出：Agent 团队协作"不会把它们内部指令变成你对话记录的一部分"——子 Agent 的系统提示不泄漏进主会话 transcript。

七、扩展已有的 Agent

MCP 服务器：支持本地 stdio 进程与远程 Streamable HTTP（含 SSE 回退）两类服务器；~/.codewhale/mcp.json 是默认配置路径。另有服务端模式：codewhale serve --mcp 运行 MCP stdio 服务器，codewhale mcp-server 是等价的 stdio 入口（docs/MCP.md）；
技能（Skills）：默认技能目录 ~/.codewhale/skills，技能以 Markdown 文件组织，仓库内自带大量内置技能（如 docs/skills 下的 GitHub 工作流技能）；
钩子（Hooks）：生命周期钩子在审批管线的第 3 层执行，判定折叠顺序为 deny > ask > allow（docs/HOOKS.md，实现见 crates/hooks/src/lifecycle_outbox.rs）；
Agent 角色文件：Agent 角色是可读文件，存放在项目或用户配置目录，而非二进制里。Codewhale 默认读取跨 Agent 标准 AGENTS.md 与 .codewhale/instructions.md；CLAUDE.md、.cursorrules 等外部工具文件不会被当作法规，除非通过 project_instruction_imports 显式导入。

八、安全边界：审批、仓库规则与 OS 沙箱

README 的安全模型可以概括为一句话："Codewhale 在你的机器上以你授予的权限运行；审批模式与仓库规则限制 Agent 能做什么，可选的 OS 沙箱在支持的地方加上更强的执行边界。" 对应的配置项在 config.example.toml 安全段：

allow_shell = true
approval_policy = "on-request"    # on-request | untrusted | never
sandbox_mode = "workspace-write"  # read-only | workspace-write | danger-full-access | external-sandbox

值得展开的机制：

网络访问与写权限解耦。sandbox_network_access 默认 false：被允许编辑本仓库不意味着被允许建立出站连接，curl、包安装、git fetch 会被 OS 沙箱拒绝，除非单次升级授权或整会话放行；
Linux 双沙箱后端。默认使用 Landlock；设置 prefer_bwrap = true 且存在 /usr/bin/bwrap 时改走 bubblewrap，获得只读根文件系统 + 工作目录可写的更强隔离，默认附带私有 /dev、/proc 与可写隔离 /tmp；
类型化权限规则。permissions.toml（与用户 config.toml 同级）中的 [[rules]] 支持 deny / ask / allow 三种动作，优先级 deny > ask > allow，且 deny 不可被任何后置 allow 清除；
网络策略。[network] 段可按域名 allow/deny fetch_url、web_search 与 MCP HTTP 传输的出站调用，deny 永远胜出，默认（不配置该段）不施加策略；
价格诚实性。README 明确：未知模型的定价保持"未知"，而不是被报告为免费——这避免了成本面板产生虚假的零成本观感。

另有一条边界值得注意：项目级配置（.codewhale/config.toml）可以收紧 approval_policy、sandbox_mode 与 shell 可用性，但不能放宽；provider/api_key/base_url 也禁止由项目覆盖层设置（config.example.toml 注释）——别人的仓库无法替你打开权限或换端点。

九、文档索引、社区与项目历史

官方文档索引（均位于 docs 目录）：

PROVIDERS.md — Provider 与本地模型注册表；
FLEET.md — Agent 团队（Pod）；
MCP.md、HOOKS.md、CONFIGURATION.md — 扩展与本地配置；
WEB.md — 本地浏览器客户端（codewhale web 绑定 127.0.0.1，不可重绑 LAN）；
AUTHORIZATION_ORDER.md — 审批管线的精确层序。

项目历史：Codewhale 始于 deepseek-tui，保留其配置与会话兼容性，现已 Provider 中立并独立维护。社区渠道为 Discord 与微信（Whale Brothers 群）；问题走 issue，改进走 pull request（见 CONTRIBUTING.md），贡献者保留其被合并工作的署名（docs/CONTRIBUTORS.md）。