玩转 DeepSeek TUI：CodeWhale 从入门到实战完全指南-开发者社区

前言：在 AI 编程辅助工具层出不穷的今天，如何在命令行中获得高效、直观且费用透明的交互体验？CodeWhale作为一款专为 DeepSeek 设计的 TUI（终端用户界面）客户端，凭借其强大的项目管理、技能拓展和实时费用监控功能，成为了开发者的效率利器。本文将手把手带您完成从安装到实战的全流程。

1. 环境准备与快速安装

CodeWhale 提供了跨平台的支持，支持 Node.js 和 Rust 两种安装方式。

1.1 安装命令

您可以根据自己的环境选择以下任意一种方式：

方式一：Node.js (推荐新手)
前提安装node.js
官网：https://nodejs.org/zh-cn

直接点击获取node.js即可，进入到如下界面直接进行选择：

这里根据自己的操作系统直接选择需要下载的安装包即可，下载好之后只需要无脑下一步直接就可完成安装。安装好之后我们配置国内加速的淘宝镜像源
打开终端 / CMD/PowerShell 执行：

# 设置淘宝镜像npm configsetregistry https://registry.npmmirror.com# 验证是否配置成功npm config get registry

npminstall-gcodewhale

方式二：Rust (性能更优)

cargoinstallcodewhale-cli--lockedcargoinstallcodewhale-tui--locked

提示：如果上述安装失败，也可以直接前往 GitHub Releases 下载对应系统的预编译包。

1.2 设置 API Key

启动工具前，必须配置 DeepSeek 的 API 密钥。推荐使用交互式配置：
打开一个新窗口，输入以下命令，然后去Deepseek官网申请一个api-key。
Deepseek官网：https://www.deepseek.com/

然后登录后点击创建AP-key

第一次创建好之后直接复制保存，不然后面就无法看见了，只能重新创建一个新的api-key，然后打开新的CMD/PowerShell窗口，输出下面这个命令：

codewhale authset--providerdeepseek

其他备选方案：
配置文件：在~/.deepseek/config.toml(Linux/macOS) 或%UserProfile%\.deepseek\config.toml(Windows) 中手动写入api_key = "你的API_Key"。
环境变量：设置DEEPSEEK_API_KEY环境变量（该方法与其它工具通用）。

启动：
终端输入：

codewhale

这里直接回车

然后按照提示输入对应的数字来选择语言：

选择1信任

完成配置进入如下界面

直接回车进入界面

输入N直接继续，进入交互界面

切换模型：输入/model命令

然后使用上下键选择自己需要的模型后回车

2. 核心界面与定制

启动 TUI 界面后，您会看到高度定制化的终端操作区。

2.1 自定义状态栏

默认界面底部有一个状态栏，展示会话的实时数据。您可以通过交互式界面选择需要显示在底部的模块：

Mode：代理模式（agent/yolo/plan）。
Model：当前使用的模型 ID。
Session cost：当前会话的累计消耗。
Activity：代理状态（就绪/起草/工作）。
Prompt cache hit rate：提示词缓存命中率（节省费用的关键指标）。

2.2 模型切换

CodeWhale 支持灵活切换模型和提供商。

输入/model可切换模型。
修改配置支持自定义 Base URL（例如接入本地模型如 Qwen3:8b）：
```
base_url = "http://localhost:11434/v1" model = "qwen3:8b"
```

2.3 常用指令

根据最新的官方文档，CodeWhale 的常用指令主要分为命令行（CLI）和会话内斜杠命令两大类。我为你整理了一份速查清单，方便你快速上手。

常用 CLI 命令（在终端使用）

这些命令在系统终端中执行，用于认证、配置、启动和脚本化操作。

命令	用途
`codewhale auth set --provider <提供商>`	设置 API 提供商并保存密钥，如`deepseek`,`anthropic`,`openrouter`。
`codewhale auth status`	检查当前认证状态。
`codewhale doctor`	检查配置和网络连接是否正常。
`codewhale`	直接启动交互式 TUI（终端用户界面）。
`codewhale --model auto "你的任务"`	指定模型（如`auto`）并执行一次性任务。
`codewhale exec "你的任务"`	无头模式，在脚本或 CI 中运行，不打开交互界面。
`codewhale exec --resume <会话ID> "后续任务"`	恢复一个非交互式的会话，继续之前的工作。
`codewhale resume --last`	在 TUI 中恢复最近的会话。
`codewhale update`	检查并应用二进制文件更新。

会话内斜杠命令（在 TUI 中使用）

在 TUI 底部的输入框中输入，以/开头，用于在会话中实时调整。

命令	用途
`/provider`	在对话中途切换 API 提供商（如从 DeepSeek 切到 Anthropic）。
`/model`	在对话中途切换或指定模型（如`/model auto`让系统自动选择）。
`/mode`	切换 TUI 的工作模式：`plan`（只读规划）、`act`（常规工作，需审批）和`operate`。
`/restore`	从 side-git 快照回滚到之前某轮对话的状态，安全地撤销操作。
`/config`	编辑运行时设置（如审批模式、沙箱行为等）。
`/statusline`	自定义 TUI 底部状态栏显示的信息（如费用、模型）。
`/compact`	总结并压缩过长的对话上下文，以节省 token 预算。
`/mcp`	配置或检查 MCP (Model Context Protocol) 服务器集成。
`/fleet`	配置 Fleet 角色或查看 Worker 状态（用于多智能体协同工作）。
`/skills`	从`~/.codewhale/skills/`目录加载可复用的工作流。

更高级的用法

快捷键: TUI 中有大量快捷键提升效率。例如Tab切换工作模式，Ctrl-K打开命令面板，Ctrl-R打开会话恢复选择器等。完整的快捷键列表可参考官方文档。
Fleet 多智能体协同: CodeWhale 支持本地优先的多智能体协同工作（Agent Fleet）。相关命令以codewhale fleet开头，如codewhale fleet init初始化，codewhale fleet run tasks.json运行任务，适合处理需要持久化、可重试的复杂工作流。

请注意：CodeWhale 的命令和功能迭代较快，官方文档提示，TUI 内的命令面板（Ctrl-K）是当前会话中最准确的命令来源。

3. 项目管理与版本控制

CodeWhale 不仅仅是一个对话窗口，更是一个项目上下文感知的智能体。

3.1 初始化项目描述

在项目根目录下执行/init命令。

作用：会在当前目录下自动生成AGENTS.md文件。
功能：您可以在这个文件中描述项目的业务逻辑、技术栈和 API 规范，让 AI 理解您的上下文。

3.2 会话管理

召回历史：按下Ctrl + R或输入/sessions即可查看并恢复之前的所有对话。
重命名：输入/rename为当前会话改名，便于日后查找。
保存/加载：使用/save和/load将会话保存为文件或从文件加载。
修改重发：使用/edit召回上一条指令，修改后重新提交。

3.3 Git 版本控制协作

典型案例：
假设您有master和dev两个分支，且test.txt在分支中有差异。您可以向 AI 直接下达复杂的 Git 操作指令：

指令：当前目录下有一个test.txt文件，对比一下在 git 里，master 分支和 dev 分支上这个文件内容有啥不同？请使用 master 分支上的内容覆盖 dev，并新提交到 dev 分支上，备注为 “from master”。

智能体会自动执行git diff并执行git checkout与commit操作。

4. 拓展技能 (Skills)

CodeWhale 支持通过Skills（技能）来约束 AI 的输出风格和专业知识。

4.1 技能结构

技能文件存放在以下路径（优先级由高到低）：

.agents/skills/
~/.codewhale/skills/(全局)

一个标准的技能包结构如下：

frontend-design-3-0.1.0/ ├── meta.json # 元数据（名称、描述） └── SKILL.md # 技能核心指令

示例SKILL.md内容（前端设计）：

Description: Create distinctive, production-grade frontend interfaces. Use this skill when building web components… Generates creative, polished code that avoids generic AI aesthetics.

4.2 使用技能

在输入指令时，AI 会自动判断是否命中技能。您也可以直接输入指令，例如：

指令：帮我设计一个电商活动专题页，主题是电子消费产品 618 优惠。

此时，若您的技能库中有frontend-design，AI 将会自动激活该技能，并输出符合该技能规范的高质量代码。

5. 透明化费用：实时监控消耗

这是 CodeWhale 最实用的功能之一，无需去官网查账单，终端直接显示。

5.1 底部状态条

状态栏会实时显示当前会话的Session cost估算值。例如：
agent · deepseek-v4-pro · $0.82

5.2 详细费用查询

输入/cost或/token可以查看详细的用量统计。

输出面板包含信息：

Token 用量：活动上下文、输入/输出 Token 数量。
缓存命中率：Prompt Cache 的命中情况（命中越高，费用越低）。
交互详情：当前命令所属的提交哈希、已执行的 Git 命令。
总费用：预估累积消耗。

省钱小技巧：如果看到提示词缓存命中率稳定在 70% 以上，说明您的上下文利用非常高效，费用会被大幅压缩。

6. 实战案例

6.1 AI对话页面

在交互窗口输入以下提示词

用 Python + FastAPI + LangChain 最新统一接口做后端，前端用 HTML + CSS + JS 三件套，开发一个 AI 对话 Web 应用： ## 后端需求（FastAPI） 1. 使用 LangChain 的 initChatModel 统一接口调用 DeepSeek API 2. 提供一个 POST /chat 接口，接收 { "message": "用户问题" }，返回 { "reply": "AI回复" } 3. API Key 从 .env 读取，模型名也从环境变量读取 4. 支持跨域（CORS），方便前端调用 5. 异常处理：API 报错返回友好错误信息 ## 前端需求（原生三件套） 1. 单页面：一个聊天框 + 发送按钮 + 对话气泡显示区 2. 样式干净简洁，类似微信/Telegram 风格 3. 用 fetch 调用后端 /chat 接口 4. 发送后清空输入框，显示加载状态（转圈或"正在思考..."） 5. 对话存在前端内存里（JavaScript 数组），不刷新页面就能看到历史 ## 代码结构 - backend/ - main.py：FastAPI 主程序 - .env：环境变量 - requirements.txt：依赖 - frontend/ - index.html：页面结构 - style.css：样式 - script.js：交互逻辑 ## 环境变量 DEEPSEEK_API_KEY=sk-xxx MODEL_NAME=deepseek:deepseek-chat

等待一会，让它完成代码的编写。
在编写过程中需要一些权限选择：
这里选择2

以此类推，看见提示，根据实际情况自己选择，一般来说，大部分代码编写都是在项目目录中，大多数情况下同意即可，如果是git命令的话就慎重一点选择。
这里我们也选择2->本次会话同类自动批准

完成效果如下：

项目已全部创建完成。以下是完整的结构和说明： ──────────────────────────────────────────────────────────── 项目结构 demo1/ ├── backend/ │ ├── main.py# FastAPI 主程序│ ├──.env# 环境变量（API Key 和模型名）│ └── requirements.txt# Python 依赖└── frontend/ ├── index.html# 页面结构├── style.css# 样式（微信/Telegram 风格气泡）└── script.js# 交互逻辑核心设计 后端(`backend/main.py`)-统一接口：先用 langchain.chat_models.initChatModel 调用 DeepSeek，格式 deepseek:deepseek-chat-自动降级：如果 initChatModel 不支持 DeepSeek，自动回退到 ChatOpenAI（兼容接口）+base_url="https://api.deepseek.com/v1"-CORS：全开，前端无跨域问题-异常处理：空消息 400，API 调用失败返回 502+具体错误-健康检查：GET/health 端点，前端用它监测连接状态 前端(`frontend/`)-UI 风格：居中卡片布局，iOS 风格圆角气泡 — 用户蓝色右对齐，AI 灰色左对齐-输入：发送后立即清空，按钮和输入框置为 disabled，防止重复提交-加载态：三点跳动动画+"思考中..."文本，在 AI 气泡位置显示-历史记录：history 数组存所有对话，不刷新页面即保留-状态指示：右上角绿点/灰点，每 30s 健康检查 启动方式# 1. 配置 API Key编辑 backend/.env，将 DEEPSEEK_API_KEY 改为你的真实 key# 2. 安装依赖pip install-r backend/requirements.txt# 3. 启动后端cd backend python main.py# → http://localhost:8000# 4. 打开前端直接用浏览器打开 frontend/index.html （或用 VS Code Live Server、python-m http.server 等）

打开PyCharm终端安装依赖

当我们去安装依赖的时候会发现这里无法连接外网去下载依赖，就直接让给codewhale直接说让他给我命令去清华源去安装；
同时这里的Langchain也不是最新的稳定版本1.x版本，需要让AI帮我们将Langchain升级为1.x的稳定版本。

最后经过多轮修改，前端展示效果如下：