Codewhale 深度使用指南：Rust 编写的开源终端编码 Agent 的安装、授权控制与扩展体系

Codewhale 是一款用 Rust 编写、面向终端场景的开源编码 Agent，它在你的仓库与 shell 之间充当"队友"式的自动编程助手：既能以交互式 TUI 会话工作，也能通过 codewhale exec 执行一次性任务。本文以仓库自带的 README.hi.md（印地语项目主页，与 README.md 内容同源）为主体骨架，结合仓库源码、CLI 定义与文档体系，为你系统梳理 Codewhale 的安装升级、日常使用、权限控制、模型接入与可扩展机制，帮助你快速把它接入自己的开发工作流。

一、项目定位：终端里的开源编码 Agent

按项目主页的定义，Codewhale 是一个 为你的终端而生的开源编码 Agent，使用 Rust 构建，并与使用者一起在公开环境中持续改进。它的核心工作方式是：读取你的仓库、编辑文件、运行命令、检查结果，并持续朝目标推进——至于给它多大的访问权限，完全由你决定。

从仓库结构看，这一能力由一组职责清晰的 workspace crate 支撑，例如 crates/agent、crates/core（会话与请求核心）、crates/execpolicy（执行权限策略）、crates/tui（终端界面）与 crates/workflow（自动化工作流）等。

二、安装与升级

1. macOS / Linux：官方安装脚本

新机器上推荐直接使用官方 GitHub Release 安装：

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

脚本默认把二进制安装到 $HOME/.local/bin（也可通过 CODEWHALE_INSTALL_DIR 环境变量自定义安装目录，这一点在 crates/release/src/install.rs 中可以看到该变量的使用）。

2. Windows：Release 安装包

Windows 用户从 GitHub Releases 下载与平台匹配的安装程序或压缩归档即可。安装脚本与 NSIS 安装器的实现位于 scripts/installer，winget 清单位于 packaging/winget/Hmbown.CodeWhale.yaml。

3. 自更新：update 与 --check

对既有的直装版本，运行 codewhale update 即可更新到最新稳定版；只想检查是否有新版、不实际安装时用 codewhale update --check。其底层实现在 crates/cli/src/update.rs 的 run_update(beta, check_only, proxy_arg)：

• 更新器会打印可执行文件所在路径，并保留更新的构建；
• 当检测到当前安装由系统目录或包管理器管理、不支持就地自更新时，自更新会被禁用，并给出迁移到官方 Release 的指引。

4. 其他安装途径与镜像

除了官方 Release，Codewhale 还支持：

• npm / Cargo 作为次要打包分发渠道（npm 包装器见 npm/codewhale）；
• Docker（见 Dockerfile 与 docs/DOCKER.md）；
• Nix（nix/package.nix 与 flake.nix）；
• Scoop、预编译归档、Android/Termux（见 docs/TERMUX.md）；
• 面向中国大陆用户的 CNB 镜像（见 docs/CNB_MIRROR.md）。

由包管理器安装的既有版本会收到迁移指引。完整的安装、PATH 设置与多平台说明请参阅 docs/INSTALL.md。

5. 首次运行与 Shell 补全

首次运行会引导你连接某个模型提供商，或选择离线状态继续使用。每个 shell 只需一条命令即可启用 Tab 补全：

codewhale completion bash|zsh|fish|powershell|elvish

CLI 定义中该子命令带有 completions 别名，并且会打印可直接重定向到 shell 加载目录的补全脚本（见 crates/cli/src/lib.rs）；详细的分 shell 安装示例见 docs/INSTALL.md#8-shell-completions。

三、日常使用：像跟队友说话一样

Codewhale 的交互方式与"问同事"一致——直接用自然语言描述目标即可：

Fix the failing tests and explain what changed.

不打开 TUI 的任务执行

如果不想进入交互界面，可以用 exec 子命令一次性运行任务：

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

从 crates/cli/src/lib.rs 的命令帮助可知，exec 的完整形态还支持多种自动化参数，例如：

# 纯文本一次性模型回复
codewhale exec "explain this function"

# 打开自动批准的工具调用模式（可访问文件系统与 shell）
codewhale exec --auto "list crates/ with ls"

# 以流式 JSON 输出，供自动化包装脚本消费
codewhale exec --auto --output-format stream-json "fix the failing test"

# 继续本工作区最近的会话 / 按 ID 续接指定会话
codewhale exec --continue "..."
codewhale exec --resume <SESSION_ID> "..."

TUI 中的帮助

在 TUI 中输入 /help 即可查看全部斜杠命令与键盘快捷键。

四、为什么选择 Codewhale：四大核心能力

1. 用你想用的模型

Codewhale 不绑定任何特定模型提供商：既可以接入托管提供商，也可以通过 Ollama、vLLM 或 SGLang 接入本地模型，并在会话中随时用 /model 切换提供商与模型。模型目录与提供商注册相关的配置资产见 crates/config/assets/provider_descriptors.json 与 crates/config/assets/models_dev.bundled.json；各提供商的完整接入方式见 docs/PROVIDERS.md。

2. 把控制权留在自己手里

项目的授权哲学是"以你授予的权限运行"：

• Plan 模式是只读的，适合让 Agent 先做规划、不出手改东西；
• Ask、Auto-Review、Full Access 三种姿态把"何时征求批准"变得清晰可见；
• /undo 回滚上一轮对话的操作；
• /restore 把工作区恢复到更早的某个快照。

从源码看，这四种姿态正是执行权限枚举 ApprovalMode 的四个取值（crates/execpolicy/src/approval_mode.rs）：

枚举值	TUI 显示标签	语义
Suggest（默认）	Ask	对非安全工具调用征求用户批准
Auto	Auto-Review	先自动评审高风险工具调用，再决定是否询问
Bypass	Full Access	完全跳过审批（即 YOLO / --yolo 模式）
Never	Never	绝不执行需要审批的工具

源码还显示配置解析会接受一组同义词，例如 ask、untrusted、on-request 都映射到 Suggest，full-access、dontask、yolo 等映射到 Bypass（见 crates/execpolicy/src/approval_mode.rs），方便与旧配置兼容；Shift+Tab 的权限循环顺序为 Suggest → Auto → Bypass。授权模式与仓库规则的精确优先级栈请参阅 docs/AUTHORIZATION_ORDER.md。

3. 让长任务保持条理

对持续数小时乃至跨天的任务，Codewhale 提供了会话级与目标级的组织手段：

• 保存 / 续接会话：codewhale sessions 列出已保存会话，codewhale resume <SESSION_ID> 或 --resume / --continue 续接；
• 设置持久目标：/goal 把目标写入会话，使 Agent 在长跑中不跑偏；
• 工作流先审后跑：工作流（workflow）在真正运行前可被审阅，相关编排逻辑见 crates/workflow；
• 多 Agent 协调：协调若干子 Agent 时，不会把它们的内部指令混入你的对话记录——这对应仓库中的 Agent 团队（Fleet）与工作间（Workroom）设计，见 docs/FLEET.md。

4. 扩展你已经拥有的 Agent

与其另起炉灶，不如把 Codewhale 的能力嫁接到你的既有工具链上：

• MCP：连接 MCP 服务器以接入外部数据源与工具，见 docs/MCP.md（协议客户端实现在 crates/mcp）；
• 技能（Skills）：把可复用流程封装为技能；
• 钩子（Hooks）：在生命周期节点上挂载自定义逻辑（如 message_submit、tool_call_before 决策钩子），见 docs/HOOKS.md 与 crates/hooks；
• Agent 角色文件化：把 Agent 的角色定义（role）保存为项目目录或用户私有配置中的可读文件，便于版本管理与跨机器同步。

以上各项的本地配置写法统一沉淀在 config.example.toml 与 docs/CONFIGURATION.md 中，可以直接作为起点进行复制改写。

五、安全模型

Codewhale 默认以"用户授予多少权限就拥有多少权限"的方式运行在本地机器上，安全设计分为三层：

1. 授权模式（Approval Mode） 与 仓库规则：限制 Agent 可以执行的操作边界；
2. 可选的 OS 沙箱：在受支持的平台上提供更强的执行隔离边界；
3. 透明的定价信息：对于价格未知的模型，界面会如实标注为"未知"，而不会误报为"免费"。

想要掌握每条策略的精确生效顺序与本地配置，建议通读 docs/AUTHORIZATION_ORDER.md 与 docs/CONFIGURATION.md；授权决策链相关测试位于 crates/execpolicy/tests/authorization_order.rs。

六、文档体系一览

仓库在 docs 目录维护了围绕上述主题的完整文档：

• docs/PROVIDERS.md：提供商与本地模型接入；
• docs/FLEET.md：Agent 团队与多代理协调；
• docs/MCP.md、docs/HOOKS.md、docs/CONFIGURATION.md：扩展机制与配置；
• docs/WEB.md：本地 Web 客户端；
• docs/INSTALL.md：各平台安装、升级与排障；
• docs/CONTRIBUTORS.md：贡献者记录。

七、社区、项目历史与许可证

Codewhale 强调"在公开中改进"：当使用者报告不顺手的体验、缺位的提供商或碍事的终端 UI，并帮助修复时，项目才会变得更好。贡献方式包括提交 issue 与 pull request（见 CONTRIBUTING.md），并欢迎首次贡献者。

值得注意的是它的项目历史：Codewhale 起源于 deepseek-tui，至今仍保留着与其配置与会话格式的兼容性；如今它已不依赖任何单一提供商，独立维护，且不与任何模型提供商存在隶属关系。

项目以 MIT 许可证 发布，从其他开源项目借鉴或改编的部分会在 docs/THIRD_PARTY_NOTICES.md 中如实记录。

小结

从安装升级、自然语言使用，到 Ask / Auto-Review / Full Access 的授权姿态、/undo 与 /restore 的回滚保障，再到 MCP、Skills、Hooks 与角色文件化构成的扩展生态，Codewhale 用一套"可读配置 + 显式授权 + 模块化 crate"的方式，把终端编码 Agent 的能力边界交还给了开发者。如果你想在熟悉官方中文文档之前快速上手，也可以参照 docs/INSTALL.md 完成安装后，在 TUI 中输入 /help 开始你的第一个任务。