41K Star！开源终端 AI 编程助手 CodeWhale 安装使用教程：一行命令，让 AI 在终端里帮你改代码（原 DeepSeek-TUI）

一、为什么我又盯上了一个终端编程工具？

2026 年，AI 编程助手已经彻底卷成红海：Cursor 要 $20/月，Claude Code 也是 $20/月起步，GitHub Copilot 改成按量计费后重度用户直呼伤不起。钱包在燃烧，代码却还是要写，怎么办？

答案是：把目光转向开源阵营。今天要介绍的 CodeWhale（就是去年爆火的 deepseek-tui 改名而来），在 GitHub 上已经狂揽 41,000+ Star，是目前最火的开源终端 AI 编程助手之一。它用 Rust 写成，能读你的代码仓库、改文件、跑命令、自己检查结果，关键是——完全免费开源（MIT 协议），模型随便你接：DeepSeek 官方 API、Ollama 本地模型、OpenAI 兼容接口全都行。

本篇是新手向安装使用教程，跟着做就能跑起来，不需要任何前置知识。

二、CodeWhale 是什么来头？

一句话解释：CodeWhale 就是一个跑在你终端里的 AI 编程智能体（Agent）。”智能体”听着玄乎，说白了就是：你用大白话给它派活，它自己去读代码、改文件、执行命令、看结果，改完还会向你汇报改了什么。

它的几个核心特点：

• Rust 编写：单个二进制文件，启动飞快，没有 Node/Python 环境依赖的烦恼
• 模型中立：起初绑定 DeepSeek，现在已支持 DeepSeek、OpenAI、Ollama（本地免费模型）、Moonshot/Kimi、OpenRouter 等一大堆提供商
• 审批可控：AI 每次改文件、跑命令前可以先让你确认，不会”乱杀”
• 兼容旧配置：如果你以前用过 deepseek-tui，配置和会话直接无缝迁移

三、安装：一行命令搞定（Mac / Linux）

3.1 macOS / Linux 官方安装脚本

打开终端，粘贴这一行：

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

脚本会自动下载最新版（当前是 v0.10.0）并装到 ~/.local/bin。装完运行：

"$HOME/.local/bin/codewhale"

3.2 Windows 安装

Windows 用户直接去 GitHub Releases 页面 下载 codewhale-windows-x64.exe，放到一个目录里，在 CMD 或 PowerShell 里运行即可。已装过的用 codewhale update 一键升级。

3.3 国内下载加速（重要）

GitHub 直连慢是老问题了，三个加速方案任选：

• 安装脚本慢：先用浏览器打开 codewhale.net/install.sh 保存到本地再执行 sh install.sh
• Cargo 源码安装慢：配置清华镜像（见下方代码块）
• Release 下载慢：在下载 URL 前面加 https://ghproxy.net/ 前缀走镜像

# ~/.cargo/config.toml —— Cargo 清华镜像
[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

另外还支持 npm install -g codewhale、cargo install codewhale-cli、Docker、Scoop 等方式，挑你顺手的。

四、首次配置：接上模型才能干活

装好后，在你的项目文件夹里打开终端，运行：

codewhale

第一次启动会直接进入输入框，界面底部可能显示 no model connected——意思很直白：还没接模型，AI 是”失联”状态。接下来两步接上：

步骤 1：选择提供商

输入 /provider（或按 F3），会弹出提供商列表。国内用户最常用的两个选择：

• deepseek：去 platform.deepseek.com 注册并创建 API Key（几块钱能用很久），选这个最省心
• ollama：如果你本地装了 Ollama 并拉过聊天模型，CodeWhale 会自动检测并切换过去，一分钱不花

步骤 2：保存 API Key

codewhale auth set --provider deepseek
# 按提示粘贴你的 API Key
codewhale auth status   # 检查配置状态（不会打印密钥本身）

也可以用环境变量 DEEPSEEK_API_KEY 提供密钥，但推荐用 auth set 存到钥匙串里，更安全。

步骤 3：选模型

输入 /model 打开模型选择器。比如 DeepSeek 用户可以选 deepseek-v4-flash（快、便宜，日常够用）或推理更强的版本。也可以用 /models 直接拉取当前提供商的可用模型列表。

五、核心用法：三分钟上手

5.1 交互模式（最常用）

在项目目录运行 codewhale 进入 TUI（终端图形界面），然后用大白话描述任务就行：

Fix the failing tests and explain what changed.
把 utils.py 里的日期处理函数加上类型注解，并补两个单元测试

它会自己读仓库 → 定位问题 → 改文件 → 跑命令验证 → 汇报结果。

5.2 两种模式，先看清再动手

5.3 权限档位（防翻车关键）

按 Shift+Tab 可以在三个权限档位间切换：

• Ask：每一步都问你，最保守
• Auto-Review：自动执行但变更可审查（默认推荐）
• Full Access：全自动，但仍有不可逾越的策略边界

5.4 非交互模式（脚本/CI 用）

codewhale exec "fix the failing tests and explain what changed"
codewhale exec --resume <SESSION_ID> "再来个补充需求"
codewhale --yolo "全部自动执行，别问我"

六、常用命令速查表

七、进阶速览：还能玩什么？

• 本地 Web 界面：codewhale web 打开浏览器客户端，不想盯终端时用
• MCP 扩展：接入 MCP 服务器，让它能操作数据库、调用外部工具（配置见官方 docs/MCP.md）
• 技能系统：/skill install github:xxx/xxx 安装社区技能包
• VS Code 扩展：社区维护的侧边栏插件，可在 VS Code Marketplace 搜 brotherwhale 安装
• 多智能体协作：大任务拆给不同模型、不同角色的子智能体分头干（官方叫 Fleet）

八、FAQ：新手最常踩的坑

Q1：启动后一直显示 no model connected？
说明还没配置模型。运行 /provider 选提供商，再用 codewhale auth set 存 Key；本地党确认 Ollama 服务在跑、且已经 ollama pull 过模型。

Q2：提示 API Key 被拒绝？
多半是环境变量里有旧的 DEEPSEEK_API_KEY 干扰了。运行 codewhale doctor 定位来源，删掉 shell 配置文件里的过期 export，重开终端，或直接 codewhale auth set --provider deepseek 重新保存。

Q3：它会不会背着我乱改代码？
不会。默认审批模式下每个有副作用的操作都要你点头；就算开 Full Access，也有策略边界兜底，且随时 /undo。

Q4：跟 Cursor / Claude Code 比怎么选？
要 IDE 图形体验、预算充足 → Cursor；要终端工作流、不想被订阅绑定 → CodeWhale 这类开源工具，接 DeepSeek API 一个月几块钱，接 Ollama 本地模型直接零成本。

九、总结

CodeWhale 最大的价值在于把”AI 编程智能体”这个曾经只有大厂订阅制才能体验到的能力，以开源免费的方式带进了每个开发者的终端。41K Star 的社区热度、Rust 的性能底子、对国产模型（DeepSeek）和本地模型（Ollama）的友好支持，让它成为 2026 年最值得尝试的编程工具之一。如果你已经受够了按月付费的 AI 编程助手，不妨花十分钟装一个试试——反正，不要钱。

参考资料：CodeWhale GitHub 仓库（Hmbown/CodeWhale）· 中文 README · 官方文档 docs/

关注公众号：「实用软技」，在公众号窗口里回复关键字”软件”即可免费获取