Hmbown/Codewhale · 上手攻略

  • 仓库：Hmbown/Codewhale
  • 链接：https://github.com/Hmbown/Codewhale
  • 分类：AI 编程助手 / Coding Agent
  • 作者：Tom
  • 更新：2026-09-19

这是什么

Codewhale 是一款开源的终端编程智能体（coding agent），使用 Rust 构建，MIT 许可证。它能读取项目代码、编辑文件、执行命令、检验结果，对接你选择的托管模型或本地模型。从终端的一条任务开始，逐步扩展到多智能体团队协作。2026-Q2 进入 1.x 稳定版，支持 HTTP/SSE API 与 ACP 协议集成。

解决什么问题

当你需要在大型代码库中完成具体开发任务（修复 bug、写测试、重构代码、写文档），又不想频繁切换到浏览器操作 Claude Code 或 Cursor 时，Codewhale 把 AI 编程能力直接带入终端。它支持本地模型（Ollama / vLLM / SGLang），可以在不联网、不依赖云服务的情况下完成大部分工作。同时支持多智能体团队（Fleet），把复杂任务拆分给不同角色、不同模型的子智能体并行处理。

快速安装

macOS / Linux（推荐）

curl -fsSL https://codewhale.net/install.sh | sh

安装后二进制位于 ~/.local/bin/codewhale，同时提供 codew 便捷命令。安装脚本会验证 SHA256 校验和。

Windows

从 GitHub Releases 下载匹配的安装程序或压缩包，解压后运行。

npm

npm install -g codewhale

Cargo

cargo install codewhale-cli

其他安装方式：Docker、Nix、Scoop、Android/Termux、可选 CNB 镜像。具体见 docs/INSTALL.md。

核心用法

基本任务

# 进入项目目录，启动交互式 TUI
cd /path/to/your/project
codewhale

# 非交互式执行（适合脚本 / CI）
codewhale exec "fix the failing tests and explain what changed"

选择模型和提供商

# 连接托管或本地提供商
/provider

# 选择具体模型
/model

支持的提供商包括 OpenAI、Anthropic（Claude）、DeepSeek 等托管服务，以及 Ollama、vLLM、SGLang 等本地模型。

模式切换

/mode plan   # 探索模式：不修改文件、不执行 shell 命令
/mode work  # 工作模式：实际修改文件和执行命令

按 Shift+Tab 切换权限级别：Ask（仅询问）/ Auto-Review（自动审查）/ Full Access（完全访问）。

团队协作（Fleet）

复杂项目可拆分为多个子智能体，指定不同模型和角色：

# 见 docs/FLEET.md

MCP 服务器与技能扩展

# 连接 MCP 服务器
# 配置钩子（hooks）
# 将智能体角色保存为项目级或个人级可读文件

Shell 补全

codewhale completion bash    # Bash
codewhale completion zsh     # Zsh
codewhale completion fish    # Fish
codewhale completion powershell

其他常用命令

codewhale web        # 打开本地 Web 客户端（TUI 同一 Runtime）
codewhale update     # 更新到最新发布版
codewhale update --check  # 只检查，不更新
/help                 # 查看所有命令和快捷键
/statusline           # 底部状态栏显示缓存命中率、模型、Token 余额

VS Code 扩展

社区维护的 VS Code 扩展通过侧边栏连接本地 Runtime，可从 VS Code Marketplace 安装。

典型适用场景

  • 本地隐私优先：代码涉及内部业务逻辑，不适合上传云端，使用 Ollama/vLLM 本地模型。
  • CI 自动化：在 codewhale exec 模式下结合 CI pipeline，自动修复测试失败。
  • 大型代码库探索：用 /mode plan 探索不熟悉的项目结构，不产生副作用。
  • 多语言并行开发：团队用不同语言的子智能体处理各自模块，再汇总。
  • 成本敏感场景：通过 prefix-cache 降低 Token 消耗；DeepSeek 模型性价比高。

坑与注意

  1. 模型必须自己提供：Codewhale 本身不包含模型，运行时必须连接托管或本地模型才能工作。
  2. Windows 补全功能：Windows 版部分 shell 补全支持不如 macOS/Linux 完整。
  3. 版本与源码差异：源码 v0.9.14 为候选版本，install.sh 拉取的是最新已发布正式版（可能滞后于源码）。
  4. 沙箱限制：Codewhale 在你的机器上运行，权限等同于你的用户；Full Access 模式仍受不可逾越的策略边界约束。
  5. Computer Use 插件：内置 Computer Use 需要 Node.js 20+ 在 PATH，macOS 构建已包含 native helper，无需单独安装。
  6. 未签名应用：macOS 直接下载的二进制需在「系统设置 → 隐私与安全」中点"仍然打开"。

与同类对比

特性 Codewhale Claude Code Aider
语言 Rust（高效） TypeScript Python
多智能体团队 ✅ Fleet ❌ ❌
本地模型 Ollama/vLLM/SGLang ❌ ✅
Computer Use ✅ 内置 ❌ ❌
VS Code 扩展 ✅ 社区版 ✅ 官方 ❌
多平台 macOS/Linux/Windows macOS/Linux/Windows 全平台
许可证 MIT 专有 MIT

Codewhale 的独特优势：Fleet 多智能体团队协作、内置 Computer Use（桌面自动化）、Rust 高性能、深度本地模型支持。相比 Claude Code，Codewhale 完全开源、可自托管；相比 Aider，Codewhale 的 TUI 体验更现代、功能更丰富。

一句话推荐

如果你想在终端里用 AI 编程、又不绑死在某一云服务，且有团队协作复杂任务的需求，Codewhale 是目前开源生态里功能最完整的 Rust 原生方案。

⚠️ 注：版本信息基于 2026-09-18 抓取的源码文档；实际安装推荐以 codewhale update --check 显示的版本为准。