前言：在 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 config set registry https://registry.npmmirror.com

# 验证是否配置成功
npm config get registry

在这里插入图片描述

npm install -g codewhale

方式二：Rust (性能更优)

cargo install codewhale-cli --locked
cargo install codewhale-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 auth set --provider deepseek

在这里插入图片描述

其他备选方案：

  • 配置文件：在 ~/.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 技能结构

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

  1. .agents/skills/
  2. ~/.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的稳定版本。
在这里插入图片描述
最后经过多轮修改，前端展示效果如下：
在这里插入图片描述

Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

3分钟掌握Codex技能安装：一键部署你的AI助手工具库

想要为你的Codex AI助手安装新技能？不用再手动复制文件了！skill-installer为你提供了一套完整的解决方案，让你能够从GitHub仓库快速获取和安装各种实用的Codex技能。无论你是AI开发新手还是经验丰富的开发者，这个工具都能让你在几分钟内扩展Codex的功能边界。## 为什么选择skill-installer？ 🤔在AI辅助编程的时代，Codex技能已经成为提升开发效

avatar AI编程社区

DB-GPT分布式AI数据引擎：企业级智能分析平台架构解析

DB-GPT作为新一代AI数据助手，通过分布式架构和智能代理引擎重构了传统数据分析范式。该平台将大型语言模型的自然语言理解能力与企业级数据处理需求深度融合，构建了面向生产环境的可扩展AI数据平台。其核心价值在于将复杂的SQL生成、数据分析和可视化任务转化为简单的自然语言交互，同时确保系统安全性、可追溯性和企业级可靠性。## 技术定位与生态分析在当前数据智能生态中，DB-GPT填补了传统BI

avatar AI编程社区

如何用Awesome Claude Skills将AI助手打造成你的全能创作伙伴和职业顾问

你是否曾想过，如果有一个AI伙伴能帮你完成从专业文章撰写到完美简历定制的所有工作，工作效率会提升多少倍？Awesome Claude Skills正是这样一个神奇的AI技能宝库，它汇集了1000+个精心筛选的Claude技能，覆盖内容创作、职业发展、文档处理等各个方面，让你在AI的帮助下轻松应对各种工作挑战。## 痛点分析：传统工作流程的三大瓶颈在内容创作和职业发展中，我们常常面临这样的困

avatar AI编程社区