Codewhale：开源 Rust 终端编码智能体（Coding Agent）的安装、使用与安全模型全指南

Codewhale 是一款用 Rust 编写的开源终端编码智能体，以"像与队友对话一样与终端里的 Agent 协作"为核心体验，支持接入云端或本地模型、审批驱动的工具调用、会话/工作流管理与 MCP 扩展。本篇指南以仓库根目录的 README.md 为主体，结合 crates/cli 的 CLI 实现、crates/execpolicy 的审批引擎与 docs/INSTALL.md 等官方文档展开，帮你完整掌握它的安装升级、首次配置、TUI 与无头（headless）执行、安全授权层级以及生态扩展方式。

Codewhale 的典型终端会话界面（图片来自 assets/screenshot.webp）

项目概览：运行在终端里的开源编码智能体

Codewhale 是一个 open source coding agent for your terminal：它不是 IDE 插件或网页助手，而是直接跑在终端里的自主编程代理，能够阅读你的仓库、编辑文件、运行命令、检查结果，并持续朝目标推进。项目有三个关键词：

• Built in Rust：核心与 CLI 全部用 Rust 实现。仓库以 Cargo workspace 组织（见 Cargo.toml），核心可执行 crate 是 crates/cli。
• Improved in public：项目公开演进、欢迎社区参与，issue 与 PR 均开放，详见 CONTRIBUTING.md。
• 以用户为中心：你可以自行决定 Agent 拥有多大的访问权限（access）。

从源码入口 crates/cli/src/main.rs 可以看到两个有意思的实现细节：入口先重置 SIGPIPE 信号，确保把输出管道给提前退出的命令（例如 codewhale doctor | head）时进程能以标准 141 退出码干净结束而不是 panic；同时通过 argv0 分发实现单二进制 codew 别名——codewhale 与 codew 指向同一份编译产物，无需第二个可执行文件。

核心能力一览

能力	说明
仓库理解	读取项目结构、源码与文档上下文
文件编辑	修改既有文件并遵循项目约定
命令执行	运行 shell 命令并检查输出结果
目标持续推进	一次对话/一次 exec 内持续工作直到目标达成
权限可控	审批模式 + 仓库规则限制 Agent 行为，可选 OS 沙箱

安装与升级：官方渠道与辅助渠道

macOS / Linux：官方安装脚本（推荐）

README 推荐的 macOS/Linux 全新安装方式是直接执行官方安装脚本：

curl -fsSL https://codewhale.net/install.sh | sh
"$HOME/.local/bin/codewhale"

按照 docs/INSTALL.md 的说明，该脚本会下载匹配平台的 codewhale 与 codew 两个发布二进制，自动校验 sha256 清单后默认安装到 ~/.local/bin，并暴露便捷命令 codew。脚本不使用 npm、不调用 Cargo 编译；面对已存在且内容不同的文件、符号链接目标、受管理目录等情况会直接拒绝，也不会擅自使用 sudo。

Windows

Windows 用户从官方 GitHub Releases 页面下载匹配的安装器（NSIS 的 CodeWhaleSetup.exe）或便携归档（ZIP）。安装器把 codewhale.exe 与 codew.exe 并排装入 %LOCALAPPDATA%\Programs\CodeWhale\bin，注册到当前用户 PATH，并附带了优先启动 Windows Terminal 的 codewhale.bat 启动器，详见 docs/INSTALL.md 的 Windows 章节与 packaging/winget/Hmbown.CodeWhale.yaml。也可以使用包管理器：

winget install Hmbown.CodeWhale
# 或
scoop install codewhale

既有安装的升级：codewhale update

对于直接二进制安装，升级用内置更新器：

codewhale update --check   # 只检查，不替换
codewhale update           # 执行升级

update 会打印它将改动的可执行文件路径，优先从 GitHub 获取清单（Linux x64 在 GitHub 清单失败或无法覆盖平台时，可回退到一方 CNB 镜像），每次清单请求 10 秒超时、最多三次尝试，校验失败绝不会替换文件。使用独立目录才能实现有意的版本回退。

升级到 npm、Cargo、Homebrew 等包管理器管理的安装时，codewhale update 不会覆盖其文件，而是给出迁移指引——包管理器仍持有自己的文件所有权。

辅助打包渠道

README 明确将 npm 与 Cargo 定位为"secondary packaging routes"，此外还支持 Docker、Nix、Scoop、Android/Termux 以及可选的 CNB 镜像：

# npm（postinstall 自动下载并校验匹配的二进制）
npm install -g codewhale

# Cargo（任意 Tier-1 Rust 目标，需要 Rust 1.88+）
cargo install codewhale-cli --locked

# Nix flake 试运行
nix run github:Hmbown/CodeWhale

需要说明的限制：Cargo 安装只提供 codewhale 命令（不会自动创建 codew 别名）；codewhale-cli 在 Linux 上源码编译时会链接 libdbus-1（用于 D-Bus secret-service 凭据后端），需先装好编译期系统包（Debian/Ubuntu 为 build-essential pkg-config libdbus-1-dev，Fedora/RHEL 为 gcc make pkgconf-pkg-config dbus-devel）；而使用 npm 包装或下载预编译二进制则不需要这些编译期依赖。

国内网络环境可通过环境变量走镜像：CODEWHALE_USE_CNB_MIRROR=1（Linux x64/OpenHarmony x64 强制一方 CNB 镜像）、CODEWHALE_RELEASE_BASE_URL（覆盖下载根路径）、CODEWHALE_VERSION（钉住版本）。nix 包定义见 nix/package.nix，Docker 镜像构建见 Dockerfile 与 packaging/docker/Dockerfile.release。

Shell 补全：一条命令一种 shell

补全脚本由 CLI 根据自身的 clap 命令树自动生成（实现见 crates/cli/src/lib.rs 附近，它还会为 codew 短命令追加注册），一次性同时补全 codewhale 与 codew 两个名字：

codewhale completion bash|zsh|fish|powershell|elvish

codewhale completions 是同命令的别名。脚本输出到 stdout，重定向即可安装。以 zsh 为例：

mkdir -p ~/.zfunc
codewhale completion zsh > ~/.zfunc/_codewhale
# 若 ~/.zfunc 不在 fpath 中，追加到 ~/.zshrc：
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

注意升级后需要重新生成补全脚本——它是"生成时版本命令面的快照"而非实时查询。完整各 shell 安装示例见 docs/INSTALL.md#8-shell-completions。

首次运行：接入提供商或保持离线

首次运行会引导你二选一：连接一个模型提供商，或者保持离线。连接提供商的具体指引在 docs/PROVIDERS.md，其中覆盖了托管提供商与本地模型（Ollama、vLLM、SGLang）两条路线。本地配置存储采用"无损 config.toml 变更"策略——每次写入都经由共享写锁、读后增量持久化（见 crates/config/src/config_document.rs 的 mutate_config_document），从而避免并发进程用陈旧快照覆盖掉已撤销的凭据。仓库根目录的 config.example.toml 提供了可参考的完整配置骨架。

日常使用：像对队友说话一样下指令

Codewhale 的使用方式与一般 CLI 很不一样——你用自然语言、以"与队友协作"的口吻直接交代任务：

Fix the failing tests and explain what changed.

TUI 交互模式

不追加子命令直接运行 codewhale 即进入全屏 TUI，可进行多轮会话。TUI 内运行 /help 可查看全部斜杠命令与快捷键。README 中提到的常用斜杠命令包括：

• /model —— 切换提供商与模型；
• /undo —— 撤销上一轮（last turn）改动；
• /restore —— 将工作区恢复到此前的快照（/restore list [N] 列出、/restore <N> 恢复）；
• /goal —— 设定跨轮次持久的任务目标。

无头（headless）执行：codewhale exec

不打开 TUI 也可以一次性跑任务，这正适合脚本化与 CI 集成：

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

从 CLI 定义（crates/cli/src/lib.rs）可以看到 exec 的常见用法与转发参数：

# 仅一次单轮模型回答
codewhale exec "explain this function"

# 开启工具型 Agent 模式并自动审批（自动化路径）
codewhale exec --auto "list crates/ with ls"

# 流式 JSON 输出，便于被外部包装器消费
codewhale exec --auto --output-format stream-json "fix the failing test"

# 恢复/延续既有会话
codewhale exec --resume <SESSION_ID> ...
codewhale exec --continue ...

codewhale 的能力边界遵循 "You decide how much access it has"：默认的普通 exec 只是单轮模型回复，只有加 --auto 才开启带自动审批的 filesystem/shell 工具使用。除 run/exec 外，CLI 还提供 review（对 git diff 做代码评审）、apply（应用补丁）、models（列出缓存模型，--update 刷新目录）、sessions/resume/fork（会话管理）、fleet/lane/workflow（多 Agent 与工作流编排）、mcp、doctor、init（生成默认 AGENTS.md）等子命令，完整命令面可由 codewhale --help 查看。

为什么选择 Codewhale：四大设计支柱

README 用四点概括其设计主张，也是理解这个项目功能边界的最佳框架。

1. Use the model you want —— 模型自由

既可以通过托管服务商接入，也可以连接本地模型服务：Ollama、vLLM 或 SGLang。会话中随时用 /model 切换提供商与模型，不受单一模型厂商绑定。

2. Stay in control —— 控制权与可见性

审批行为是可感知、分级的：Plan 模式只读（不能产生写操作），Ask / Auto-Review / Full Access 三档姿态让每一次"Agent 将要做什么"都透明可见。配合 /undo 撤销上一轮、/restore 回到更早的工作区快照，形成"事前可见、事后可回滚"的闭环。

3. Keep long work organized —— 长任务的秩序化

• 保存（save）会话，随时续跑；
• 设定持久的 /goal，让长任务不因会话切换而丢失方向；
• workflow 运行前先审查（review workflows before they run）；
• 协调多个 Agent 而不把它们的内部指令搅进你的会话记录（transcript）里。

Fleet 相关的运行、名单与配置可参考 docs/FLEET.md；仓库内还有可运行的示例工作流文件，例如 workflows/stopship.workflow.js、workflows/issue_audit.workflow.js。

4. Extend the agent you already have —— 扩展既有 Agent

• 连接 MCP 服务器与 skills；
• 配置 hooks（生命周期钩子）；
• Agent 角色（agent roles）以可读文件的形式放在项目内或个人设置里，便于版本管理与审阅。

相关入口文档：docs/MCP.md 与 docs/HOOKS.md；Agent 角色作为受信文件加载的机制可在 AGENTS.md 相关实现（codewhale init 会在当前目录生成默认 AGENTS.md）与 docs/AGENT_RUNTIME.md 中看到。codewhale setup 可引导初始化 MCP 配置与 skills 目录。

安全模型：授权管线与审批模式

Codewhale 运行在你自己的机器上、使用你授予的访问权限。README 强调的安全要点是：审批模式 + 仓库规则共同约束 Agent 行为，可选 OS 沙箱在受支持的平台上提供更强的执行边界；同时，未知模型的计费价格保持"未知"而不是被误报为免费。

审批模式的源码定义

四种用户可见姿态在 crates/execpolicy/src/approval_mode.rs 中与策略引擎共享同一份定义：

枚举值	TUI 呈现	语义
Suggest（默认）	Ask	对非安全工具建议征求批准
Auto	Auto-Review	先自动审查风险调用再决定是否询问
Bypass	Full Access	绕过审批（对应 --yolo/full-access 等配置值）
Never	Never	永不执行需要审批的工具

配置解析还接受一组别名（如 auto-review、dontask、on-request、denied 等），并定义了 Shift+Tab 权限循环顺序 Suggest → Auto → Bypass。在 TUI 中，Ask、Auto-Review、Full Access 这些姿态直接决定了审批对话框何时出现。

九层授权管线

docs/AUTHORIZATION_ORDER.md 给出了交互引擎对"模型请求的工具调用"的完整求值顺序。值得注意的设计原则是：某一层给予的批准并不是通行证——后面的安全层仍可要求复核或直接拦截；批准也不是操作系统级沙箱授权。

序	层	结果
1	生效配置与姿态	用户设置、命令/运行时覆盖与项目 overlay 在轮次开始前解析；项目 overlay 只能收紧 approval_policy/sandbox_mode/shell 可用性，不能放松
2	模式与工具准入	Plan 模式限制、解析错误、按命令的 deny/allow 清单、调用者限制、缺失执行注册都在策略规则之前生效
3	准备 + tool_call_before 钩子	钩子裁决按 deny > ask > allow 折叠，严格匹配但无裁决则失败关闭（fail closed）
4	已注册工具基线	工具自身的 ApprovalRequirement 决定其常规审批需求；钩子 ask 后置应用，不会被基线抹掉
5	类型化 permissions.toml 规则	匹配的 deny 阻断；allow 只能清除常规注册审批，不能清除钩子 ask 或不可绕过的注册 hold
6	自动审查策略与内置安全底线	在类型化权限之后运行，只能追加提示或阻断，不能移除先前 hold
7	仓库规则（repo law）	受保护路径不变量只能追加提示或阻断
8	人工批准	剩余提示送往审批通道；拒绝即停止本次调用
9	工具权威与执行沙箱	Worker 权威信封、原生工具路径检查与所选沙箱在执行期仍生效

各层的排序在类型化权限层之后是单调收紧的：自动审查与仓库规则只能让结果更严，不会把此前的阻断或提示变成免审执行。类型化规则的匹配优先级为「源层 User > Agent > BuiltinDefault」优先于「动作 deny > ask > allow」优先于「匹配器具体度」。详细规则选择算法（含硬拒绝前缀先于类型化层检查、链式命令逐段求值等）都记录在该文档中。

配置与凭据

本地设置见 docs/CONFIGURATION.md。凭据存储方面，Codewhale 优先使用操作系统凭据管理器（如 Linux D-Bus Secret Service 后端、macOS/Windows 对应 keyring），无 keyring 环境则回退到权限为 0600 的文件式 secrets。仓库还提供独立的远程账号（BYOK 凭据保管）CLI：codewhale account 与简写 codewhale login 走设备码（device flow）登录并管理存放在账号远程保管库中的提供商密钥，其实现在 crates/cli/src/cloud.rs；它明确拒绝全局 --api-key 内联参数，以避免密钥泄漏进 shell 历史。codewhale auth status 与 codewhale doctor 可用来诊断当前生效的凭据来源与整体环境。

文档地图

README 为不同主题给出了权威入口，全部位于根目录相对路径：

• docs/PROVIDERS.md——提供商与本地模型（Ollama / vLLM / SGLang）接入
• docs/FLEET.md——多 Agent 团队（Fleet）编排
• docs/MCP.md、docs/HOOKS.md、docs/CONFIGURATION.md——MCP、hooks 与本地配置
• docs/WEB.md——本地 Web 客户端（codewhale rc 会把会话交给 Web 应用）
• docs/AUTHORIZATION_ORDER.md——授权顺序与安全策略栈
• docs 目录下还有安装/故障排查、模式、快捷键、Web、本地化等更细资料，并提供简体中文镜像（docs/zh_hans 下的 INSTALL、CONFIGURATION、PROVIDERS、MCP、HOOKS、MODES、FLEET 等）。

社区参与

Codewhale 明确表示"在用户的使用中变得更好"：缺了某个提供商、工作流不顺、终端 UI 碍事，都可以开 issue；知道如何改进就开 PR。首次贡献者受欢迎，且贡献者对其落地的成果保留署名（credits）。贡献相关规范见 CONTRIBUTING.md，参与者记录见 docs/CONTRIBUTORS.md。仓库还提供了一组可复用的"dogfood/自举"示例（docs/examples）与 skills 文档（docs/skills）。

项目历史与演进兼容性

Codewhale 起源于 deepseek-tui，并保留了原项目的配置与会话兼容性：旧配置与历史会话仍可继续使用。但今天的 Codewhale 已变为提供商中立并独立维护，与任何模型提供商均无隶属关系。正因如此，CLI 中仍能见到 DEEPSEEK_TUI_* / DEEPSEEK_* 环境变量作为历史别名被接受（以 CODEWHALE_* 为规范名），仓库中 npm/deepseek-tui 等目录也承载了历史路由。

开源许可

Codewhale 以 MIT 协议发布；从其他开源项目改编的部分在 docs/THIRD_PARTY_NOTICES.md 中有完整记录。

综上，Codewhale 的价值在于"把编码 Agent 放回终端并把控制权交还给你"：Rust 单二进制交付（codewhale/codew）、多平台多渠道安装、自然语言驱动的 TUI 与 exec 无头执行、模型自由接入、可见的审批姿态与九层授权管线，以及面向长任务和团队协作的会话/Fleet/工作流编排。如果你正在寻找一款可在现有仓库中立即跑起来的开源终端 Agent，直接按上文安装后运行 codewhale doctor 自检环境、再执行 codewhale exec "explain this repository" 即可开始第一次真实协作。