Codewhale：从零搭建 Rust 开源终端编程代理——安装、日常使用与安全控制模型全解

2026-09-05 18:41:47作者：魏侃纯Zoe

本文以 Codewhale 项目仓库中的繁体中文 README（README.zh-TW.md）为主体，系统讲解这款以 Rust 打造的开源终端编程代理：从多平台安装与 shell 补全、TUI 交互与非交互 exec 两种使用方式，到 /model 自由切换托管/本地模型、Plan / Ask / Auto-Review / Full Access 四级审批姿态、/undo 与 /restore 快照回滚，再到 MCP、技能与钩子扩展。读完后你可以独立完成安装配置、把 Codewhale 接入自己的模型供应商，并理解它「审批模式 + 仓库规则 + 可选操作系统沙箱」三层安全边界在源码中的真实落点。

项目定位：一个不偏向任何供应商的 Rust 终端代理

Codewhale 是一款在终端机中使用的开源程序设计代理，以 Rust 打造，并透过公开协作持续改进。它运行在你自己的电脑上，只拥有你授予的存取权限——读取代码库、编辑文件、执行指令、检查结果，然后朝目标持续推进。

从工作区清单（Cargo.toml）可以看到，当前源码版本为 0.9.11，Rust edition 为 2024、最低工具链要求 rust-version = "1.88"，工作区由 agent、core、tui、cli、execpolicy、mcp、sandbox 等约 20 个 crate 组成，default-members 指向 crates/cli。值得注意的是单二进制设计：crates/cli/src/main.rs 中通过 argv0 基名判断，codew 与 codewhale 是同一个编译产物——安装面保持一个文件，同时保留了 codew 这个更短的命令名。

项目最初名为 deepseek-tui，至今仍保留与其设定及工作阶段的相容性（配置目录 ~/.deepseek/、DEEPSEEK_* 环境变量等均有遗留兼容）。现在它不偏向任何供应商，由社群独立维护，也不隸属于任何模型供应商，授权条款为 MIT。

安装：npm 一条命令起步，多平台路径齐全

npm 快速安装

npm install -g codewhale
codewhale

第一次执行时，系统会协助你连线至供应商，也可以选择不连线（保持离线）使用。这是 README 给出的最短路径。

其他安装途径

Codewhale 亦支援 Cargo、Docker、Nix、Scoop、预建置封存档、Android/Termux 与 CNB 映像。完整矩阵、校验和验证、FreeBSD/Termux 细节、Windows NSIS/winget 打包与故障排查都写在 docs/INSTALL.md，关键要点包括：

Cargo：cargo install codewhale-cli --locked，适用于任何 Tier-1 Rust 目标，Linux 上需先装 build-essential pkg-config libdbus-1-dev（凭证存取依赖 D-Bus secret-service 后端）；
Nix：nix run github:Hmbown/CodeWhale -- <args>，flakes 直接可消费（对应仓库根目录的 flake.nix）；
Windows：Scoop 主桶、winget（Hmbown.CodeWhale，清单见 packaging/winget/Hmbown.CodeWhale.yaml）以及 NSIS 静默安装（scripts/installer/codewhale.nsi）；
Android/Termux：属于 preview 状态，需使用 Termux 专属 Android arm64 封存档，不能套用 Linux arm64 资产。

Shell 补全：每条 shell 一行命令

每种 shell 只需一个指令即可启用 Tab 自动完成：

codewhale completion bash|zsh|fish|powershell|elvish

脚本写到 stdout，重定向到 shell 的补全目录即可（如 codewhale completion zsh > ~/.zfunc/_codewhale）；codewhale completions 是同一命令的别名。详见 docs/INSTALL.md。

使用：像和队友交谈一样下达任务

TUI 交互模式

启动后像和队友交談一樣告訴 Codewhale 你的需求：

Fix the failing tests and explain what changed.

Codewhale 可以讀取你的程式碼儲存庫、編輯檔案、執行指令、檢查結果，並持續朝目標推進。在 TUI 中执行 /help 可查看完整指令与键盘快速键。

`codewhale exec` 非交互模式

不开启 TUI 也可以直接执行任务：

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

从 CLI 子命令定义（crates/cli/src/lib.rs）可以看到 exec 的完整能力面：

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

其中 --auto 启用带自动批准的工具代理模式（非交互文件系统/shell 工具使用），--json 输出摘要 JSON，--resume <SESSION_ID> / --continue 可续接先前会话，--output-format stream-json 供外部自动化包装器消费。源码中的说明明确：不带 --auto 的 codewhale exec 只是单次模型回应。

让长时间工作井然有序

README 提到的会话管理要点：

储存工作阶段（session）：--continue 续接最近会话、--resume <id> 按 ID 或唯一前缀恢复；
持久的 /goal：为长任务设定目标锚点；
工作流预审查：在执行前审查 workflow；
多代理协调：/goal、子代理并发由 max_subagents 控制（config.example.toml 中默认 64、夹紧到 1–128），且子代理的内部指示不会混入你的对话记录；
撤销与快照：/undo 可复现上一轮操作，/restore 可将工作区还原至较早的快照（快照为 side-git 文件快照，/restore list 可列出）。

模型自由：托管供应商或本地推理，`/model` 随时切换

「使用你想要的模型」是 Codewhale 的核心卖点之一：连线至託管供應商，或透過 Ollama、vLLM、SGLang 使用本機模型，TUI 内 /model 即可切换供應商與模型。

仓库的 config.example.toml 给出了完整的配置骨架，关键结构：

# 顶层：选择默认供应商 + DeepSeek 兼容凭据/端点
provider = "deepseek"
api_key = "YOUR_DEEPSEEK_API_KEY"
base_url = "https://api.deepseek.com/beta"
default_text_model = "deepseek-v4-pro"

# 每个供应商一张表，凭据并存、随时切换而无需重输 key
[providers.deepseek]
api_key = "YOUR_DEEPSEEK_API_KEY"
base_url = "https://api.deepseek.com/beta"
model = "deepseek-v4-pro"

[providers.openai]      # 通用 OpenAI 兼容网关
base_url = "https://gateway.example/v1"

[providers.ollama]     # 本地自托管，默认免 key
base_url = "http://localhost:11434/v1"
model = "deepseek-v4-flash"

要点：provider 是路由/账户/端点，model 是路由上的模型 ID；SGLang、vLLM、Ollama 等自托管供应商默认可不带 API key 运行。每个供应商的接线协议、认证变量、默认 base URL 与能力元数据，完整注册表见 docs/PROVIDERS.md；本机的 TOML 配置加载规则（配置文件位置、环境变量覆盖、按工作区叠加）见 docs/CONFIGURATION.md。

掌控权始终在你手中：审批姿态与安全边界

四种审批模式，源码中只有一个枚举

README 写道：Plan 模式为只读；Ask、Auto-Review 与 Full Access 会清楚呈现核准行为。这些姿态在源码中定义于 crates/execpolicy/src/approval_mode.rs：

pub enum ApprovalMode {
    Auto,      // Auto-Review：先自动审查高风险工具调用再决定是否询问
    Bypass,    // Full Access / YOLO：跳过审批
    #[default]
    Suggest,   // Ask：对非安全工具建议审批（默认值）
    Never,     // 从不执行需要审批的工具
}

同一文件里的 PERMISSION_CYCLE = [Suggest, Auto, Bypass] 就是 TUI 中 Shift+Tab 循环切换三种权限姿态的实现基础。对应地，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

九层授权顺序：一次批准不是万能通行证

docs/AUTHORIZATION_ORDER.md 记录了交互引擎对模型请求的工具调用所做的评估顺序，这是理解「安全」二字最直接的入口：

有效配置与姿态（项目叠加层只能收紧、不能放松 approval_policy/sandbox_mode/shell 可用性）；
模式与工具准入（Plan 模式限制、deny/allow 清单、输入解析错误）；
工具准备与 tool_call_before 钩子（裁决按 deny > ask > allow 折叠）；
注册工具的基线审批需求；
类型化 permissions.toml 规则（deny 永远胜、allow 只能清除普通注册审批）；
自动审查策略与内建安全底线；
仓库法（repo law：受保护路径不变式只能加锁，不能解锁）；
人工审批（拒绝即停止；批准只授权本次计划调用）；
工具权限与执行沙箱（OS 或外部沙箱在执行期间仍然生效）。

文档强调顺序是「单调」的：后续层只能把结果收紧，不能把先前的阻止或询问变成未经审查的执行。这份契约有回归测试覆盖（如 authorization_order_contract_matches_documented_precedence），保证文档与实现一致。

可选的操作系统沙箱

在支援的平台上，选用的作业系统沙箱可提供更强的执行边界：config.example.toml 显示 Linux 上可启用 bubblewrap（prefer_bwrap = true 且 /usr/bin/bwrap 存在时，exec_shell 走 bwrap 的只读根 + 工作区可写视图），也支援 sandbox_backend = "opensandbox" 外接 HTTP 沙箱；sandbox_network_access 控制 workspace-write 沙箱内的出站网络。没有沙箱后端的平台（默认无 bwrap 的 Linux、Windows）不会被假装有强制——/status 与 codewhale doctor 都会如实说明。

另外两条细节值得注意：未知的模型价格会维持显示为未知，而不会被误报为免费（价格数据见 docs/CONFIGURATION.md 与 docs/PROVIDERS.md）；凭证读取有明确的优先级顺序（路由认证契约 > CLI key > 配置文件 > api_key_env > 密钥库 > 环境变数 > 免密钥回退），可用 codewhale auth status 检视当前生效来源而不打印 key 本体。

扩展你已有的代理：MCP、技能与钩子

README 的第四点特性是把 Codewhale 当作「你已有代理的扩展点」：

MCP 伺服器：连接外部 MCP 工具，配置与本地网页客户端说明见 docs/MCP.md、docs/WEB.md；
技能（skills）：默认目录为 ~/.codewhale/skills，仓库内 crates/tui/assets/skills 内置了一批技能定义（Markdown 驱动）；
钩子（hooks）：生命周期事件挂接，行为契约见 docs/HOOKS.md 与 RFC docs/rfcs/1364-hooks-lifecycle.md；
代理角色文件：将代理角色以可读档案保存在专案或个人设定中，多代理团队协调见 docs/FLEET.md。

文档生态、社群与项目历史

README 给出的文件入口（均已转换为仓库根目录相对路径）：

docs/PROVIDERS.md：供应商与本機模型注册表；
docs/FLEET.md：代理团队（fleet/pod 持久任务）；
docs/MCP.md、docs/HOOKS.md 与 docs/CONFIGURATION.md：MCP、挂鉤与本机设定；
docs/WEB.md：本機網頁用戶端；
docs/AUTHORIZATION_ORDER.md：确切的政策层级；
其余所有文件见 docs/ 目录。

Codewhale 的改进依赖公开协作：缺少某个供应商、工作流程操作不便，或 TUI 妨碍了使用，都可以提出 issue；知道如何改善的可以直接提 PR（贡献规范见 CONTRIBUTING.md），首次贡献被欢迎，贡献者会保留已合并工作的署名；也可以加入 Discord 社群（入口见仓库 README 徽章）。贡献者记录见 docs/CONTRIBUTORS.md，从其他开放原始码专案改編的部分记录于 docs/THIRD_PARTY_NOTICES.md。

小结

安装：npm install -g codewhale（或 Cargo/Nix/Scoop/Termux），codewhale completion <shell> 一行启用补全，codewhale doctor 验证环境；
使用：TUI 里像和队友对话一样下达任务；自动化场景用 codewhale exec --auto；
模型：provider + [providers.*] 表 + /model 切换，托管与 Ollama/vLLM/SGLang 本地推理一视同仁；
安全：approval_policy × sandbox_mode × permissions.toml 三层可控，Shift+Tab 在 Ask/Auto-Review/Full Access 间循环，九层授权顺序保证「后层只收紧、不放松」；
扩展：MCP、技能、钩子与 fleet 多代理协调，让 Codewhale 成为既有代理工作流的一部分。