Codewhale 终端编码智能体：安装、运行模式与权限体系完整指南

2026-09-05 18:37:48作者：丁柯新Fawn

Codewhale 是一个用 Rust 编写的开源终端编码智能体（coding agent），运行在你自己的机器上，通过交互式 TUI 或无界面 CLI 驱动模型完成读代码、改文件、跑命令等任务。本文基于项目法语版 README（README.fr.md）及其关联文档、源码，完整覆盖安装与首次配置、模型/供应商接入、运行模式与审批权限、长期任务组织和安全边界等实战主题，并给出仓库内的源码与测试位置供深入验证。读完后你将能够独立完成 Codewhale 的安装、供应商接入，并根据任务风险选择合适的模式与审批级别。

定位与代码组织

Codewhale 自我定位是"开源的、为终端打造的编码智能体，用 Rust 编写，与使用者共同公开迭代"。当前仓库的版本号为 0.9.11，见 Cargo.toml 中的 version = "0.9.11"，Rust 工具链要求 rust-version = "1.88"（代码大量使用 let_chains，CI 以 -Dwarnings 编译）。

从源码结构看，整个项目是一个多 crate 的 Cargo workspace，核心构件包括：

Crate	职责
crates/cli	对外二进制 `codewhale` 入口，负责命令分发（`dispatch.rs`）
crates/tui	交互式终端界面、斜杠命令（100+ 命令实现位于 `src/commands/`）、工具执行
crates/config	供应商注册表、模型目录、认证来源、`permissions.toml` 相关解析
crates/core	会话/日志/单轮循环等核心运行时
crates/execpolicy	执行策略引擎：审批模式、bash 命令前缀匹配
crates/protocol	事件、操作、Agent 通信等协议定义
crates/mcp、crates/hooks	MCP 客户端与生命周期 hooks

npm 包（npm/codewhale/package.json）只是二进制分发器：bin/codewhale.js 与 bin/codew.js 两个入口负责按平台下载对应预编译资产（见 scripts/artifacts.js 中 codewhale-linux-x64、codew-macos-arm64 等资产名），并额外暴露 codew 便捷命令。

安装

最短路径：npm 全局安装

npm install -g codewhale
codewhale

首次启动时 Codewhale 会引导你连接一个模型供应商，或者选择保持离线模式（不接入任何供应商也能使用本地部分功能）。

其他安装渠道

法语 README 指出 Codewhale 同时支持 Cargo、Docker、Nix、Scoop、预编译归档、Android/Termux 与 CNB 镜像，完整平台矩阵与故障排查见 docs/INSTALL.md。从该文档可确认的关键事实：

支持 Linux x64/arm64（musl 静态构建，无 glibc 依赖、无需单独安装 libsqlite3）、macOS x64/arm64、Windows x64/arm64、Alpine musl、FreeBSD/OpenBSD（cargo install）；Android/Termux 为预览版。
Linux x64/arm64 发布资产是静态 musl 构建，SQLite 通过 rusqlite bundled 编译，跨 Ubuntu/Debian/RHEL/Alpine 均可运行（见 Cargo.toml 中 rusqlite = { version = "0.40.2", features = ["bundled"] }）。
手工下载二进制时必须用 codewhale-artifacts-sha256.txt（裸二进制）或 codewhale-bundles-sha256.txt（tar.gz/zip 归档）校验和验证。

Shell 自动补全

每个 shell 一条命令即可开启 Tab 补全：

codewhale completion bash|zsh|fish|powershell|elvish

详细说明见 docs/INSTALL.md 的 Shell Completions 一节。

基本使用

像对队友说话一样对 Codewhale 下达任务：

Fix the failing tests and explain what changed.

也可以不打开 TUI，直接无界面执行任务：

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

Codewhale 能够读取你的仓库、修改文件、执行命令、检查执行结果，并持续朝着目标推进——你决定授予它多少权限。CLI 入口在 crates/cli/src/main.rs，子命令到具体运行的分发逻辑见 crates/cli/src/dispatch.rs。

模型与供应商：选择权在你

README 的核心主张之一是"用你想用的模型"：既支持托管供应商，也支持通过 Ollama、vLLM、SGLang 接入本地模型；用 /model 命令随时切换供应商和模型。

仓库中的供应商注册表（docs/PROVIDERS.md）把 ProviderKind::ALL 的全部 42 个供应商 ID 列为一等公民，包括 deepseek（默认）、openai、anthropic、ollama、vllm、sglang、huggingface、openrouter 等。选择供应商有四个等价的入口：

codewhale --provider <id>          # CLI 参数
/provider <id>                    # TUI 命令（或打开供应商选择器）
CODEWHALE_PROVIDER=<id>           # 环境变量（DEEPSEEK_PROVIDER 为遗留别名）
provider = "<id>"                 # config.toml

模型与端点则由 CODEWHALE_MODEL、CODEWHALE_BASE_URL 或 [providers.<table>] 配置段指定；认证通过 codewhale auth set --provider <id>、[providers.<table>].api_key 或各供应商环境变量完成。从源码结构看，供应商 ID、默认值与环境变量优先级共享定义在 crates/config/src/lib.rs，TUI 侧的供应商元数据在 crates/tui/src/config.rs，静态模型注册表供 codewhale model list / codewhale model resolve 使用则位于 crates/agent/src/lib.rs；仓库还提供 scripts/check-provider-registry.py 做注册表漂移检查，确保文档、代码与配置示例三者一致。

新配置写入 ~/.codewhale/config.toml；已存在的 ~/.deepseek/config.toml 仍会被读取以兼容旧用户（与项目历史相关，见下文）。

模式与审批权限：保持控制

README 的第二条主张是"保持控制"。Codewhale 把"审批行为"做成显式、可见的三档权限姿态（permission posture）：

Plan（只读）：设计优先，运行时中央拒绝一切文件变更与 shell 执行；
Ask / Auto-Review / Full Access：审批从"逐次询问"到"自动审查"再到"完全访问"逐级放宽；
回滚保障：/undo 撤销上一轮，/restore 把工作区恢复到更早的快照。

在 TUI 中：Tab 循环 TUI 模式（Plan → Work → Operate → Plan），Shift+Tab 循环审批姿态（Ask → Auto-Review → Full Access），/mode 打开模式选择器，/help 查看全部命令与快捷键。docs/MODES.md 给出了各模式下的工具可用性矩阵，例如：

工具族	Plan	Work	Operate
`read` 等只读/研究工具	可用	可用	可用
`write` / `edit`	可见但执行被拒	受审批与策略门控	同 Work
`bash`	可见但执行被拒	受审批与策略门控	同 Work，鼓励委派并行
`agent`（子智能体）	受子深度权限约束	同左	同左

Operate 模式是"多任务指挥"姿态：父会话作为 operator，把可并行的工作派发给后台 worker，"dispatch 不等于完成"——有写能力的子任务必须返回真实验证证据（VERDICT PASS/FAIL 加证据）。

审批姿态的底层实现见 crates/execpolicy：approval_mode.rs 定义审批模式，bash_arity.rs 与 shell_expand.rs 处理命令拆分与 shell 展开，回归测试 crates/execpolicy/tests/authorization_order.rs 验证"授权顺序"契约。

组织长期工作

README 的第三、四条主张对应长期任务组织与扩展能力：

保存会话、设定持久 /goal：/goal <objective> 设置一个带可选 token 预算的会话目标，/goal pause|resume|complete|blocked|clear 管理其生命周期；目标状态不改变当前 TUI 模式、审批姿态或模型路由（详见 docs/MODES.md）。
Workflow 先行审查：重复性、有编排需求的大任务可在执行前以 workflow 形式审查；仓库根目录的 workflows/ 目录包含 stopship.workflow.js、operate_staged_fix.workflow.js 等可运行示例。
扩展智能体：接入 MCP 服务器与技能（skills）、配置 hooks，并把"智能体角色"保存为项目或个人配置中可读的文件。相关文档为 docs/MCP.md、docs/HOOKS.md；MCP stdio 客户端实现见 crates/mcp/src/stdio_client.rs。
智能体团队：多智能体协调见 docs/FLEET.md，本地 Web 客户端见 docs/WEB.md。

安全与授权顺序

Codewhale 运行在你的机器上，只拥有你授予的访问权。审批模式与仓库规则限制智能体可执行的动作；系统级可选沙箱（sandbox）在支持的平台提供更强执行边界。一个细节值得注意：价格未知的模型会保持"未知"状态，而不是被误报为免费。

完整的策略栈见 docs/AUTHORIZATION_ORDER.md。交互式引擎对模型请求的工具调用按 9 层顺序评估：

生效配置与姿态（项目覆盖层只能收紧，不能放宽）；
模式与工具准入（Plan 模式限制、输入解析、deny/allow 清单）；
准备阶段与 tool_call_before hooks（前向 hooks 按 deny > ask > allow 折叠）；
注册工具的基线 ApprovalRequirement；
类型化 permissions.toml 规则（deny 阻断、allow 仅清除普通审批）；
Auto-Review 策略与内置安全底线；
仓库法（repo law：受保护路径不变量只能加提示或阻断）;
人工审批；
工具权限与执行沙箱（沙箱拒绝即为拒绝）。

排序刻意保持单调：后层策略只能收紧前层结果，不能把此前的阻断变成未审查执行。类型化规则的选择优先级为 来源层（User > Agent > BuiltinDefault）→ 动作强度（deny > ask > allow）→ 匹配器特异性；硬命令前缀拒绝（denied prefixes）在类型化选择之前检查，任何 typed allow 都无法覆盖它。这些契约由测试固化，例如：

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

本地配置（供应商、审批策略、沙箱、hooks 等）见 docs/CONFIGURATION.md，项目根的配置示例见 config.example.toml。配置系统同时管理"宪法"分层：内置全局宪法、用户宪法（~/.codewhale/constitution.json）、仓库宪法（.codewhale/constitution.json）与跨智能体项目说明 AGENTS.md（兼容读取 CLAUDE.md）——指令面与安全控制面刻意分离，宪法不能改变运行时审批策略。

项目历史与许可

Codewhale 的前身是 deepseek-tui，并且保留其配置与会话兼容性——这就是上文提到的 ~/.deepseek/config.toml 仍然被读取的原因。项目如今与任何模型供应商解耦（provider-neutral），独立维护、不隶属于任何供应商；从源码结构看，仓库内同时保留 deepseek-tui 的 npm 包目录（npm/deepseek-tui/）与 dsh（DeepSeek Harness）凭据互认路径（crates/config/src/harness.rs），均服务于平滑迁移。

许可为 MIT（LICENSE），改编自其他开源项目的部分列于 docs/THIRD_PARTY_NOTICES.md；贡献者记录见 docs/CONTRIBUTORS.md。

继续深入：文档地图

主题	入口
安装与平台矩阵	docs/INSTALL.md
供应商与本地模型	docs/PROVIDERS.md
模式与权限姿态	docs/MODES.md
授权顺序（策略栈）	docs/AUTHORIZATION_ORDER.md
配置参考	docs/CONFIGURATION.md
智能体团队	docs/FLEET.md
MCP / Hooks	docs/MCP.md、docs/HOOKS.md
本地 Web 客户端	docs/WEB.md
全部文档	docs/