DeepSeek-TUI 安装指南

Windows 11 X64 + WSL2 + Ubuntu 24.04

文档版本：2026.05.07 (最新更新)

DeepSeek-TUI 版本：v0.8.15 (2026-05-06)

目标系统：Windows 11 X64 + WSL2 + Ubuntu 24.04

安装目录：~/DeepSeek-TUI/

官方仓库：https://github.com/Hmbown/DeepSeek-TUI

作者：扣子

⚠️ 重要提示：执行本指南前请务必执行环境检查流程，确保所有检查项均可观测

📋 目录

0. 前置环境检查
1. WSL2 前置环境配置
2. WSL2 安装与配置
3. 系统环境准备
4. 国内镜像加速配置
5. DeepSeek-TUI 安装方式
6. 安装后验证
7. 配置说明
8. 常用命令参考
9. 卸载与更新
10. 排错指南

0. 前置环境检查

💡 目的：确认系统软硬件是否满足 DeepSeek-TUI 运行环境要求
📋 检查项目：Windows 版本、虚拟化支持、内存、磁盘空间、WSL 状态

0.1 Windows 系统要求检查

检查项	最低要求	检查方法	预期结果
操作系统	Windows 11 X64	`winver`	Windows 11 版本 22H2+
虚拟化	必须开启	任务管理器→性能→CPU	虚拟化已启用
内存	8GB+	任务管理器→性能→内存	可用内存 > 4GB
磁盘空间	10GB+	此电脑→C 盘属性	可用空间 > 10GB

0.2 WSL 基础环境检查

💻 执行环境：Windows PowerShell（以管理员身份）
💡 目的：检查 WSL 是否已安装及版本状态

执行环境：PowerShell（管理员）

wsl --version

↑ 应显示 WSL 版本号，需 2.0.0+

wsl --list --verbose

↑ 应显示已安装的 WSL 发行版及状态

1. WSL2 前置环境配置

💡 目的：配置 WSL2 系统级参数，为 DeepSeek-TUI 运行提供稳定环境

1.1 WSL2 systemd 启用配置

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：启用 systemd 以支持后台服务管理
📄 配置文件：/etc/wsl.conf

执行环境：Bash

sudo bash -c 'cat > /etc/wsl.conf << EOF [boot] systemd=true EOF'

↑ 创建 wsl.conf 配置文件并启用 systemd

cat /etc/wsl.conf

↑ 验证配置文件内容

1.2 PATH 环境变量配置

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：确保用户本地 bin 目录在 PATH 中，以便安装的工具命令可直接使用

执行环境：Bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

↑ 将 ~/.local/bin 添加到 PATH（Rust、nvm 等工具会安装到此处）

source ~/.bashrc

↑ 立即生效

⚠️ 重要：修改 /etc/wsl.conf 后需要完全关闭 WSL（在 PowerShell 中执行 wsl --shutdown）后重新启动才能生效。

2. WSL2 安装与配置

💡 目的：在 Windows 上安装 WSL2 和 Ubuntu 24.04 发行版

2.1 安装 WSL2

💻 执行环境：Windows PowerShell（以管理员身份）
⚠️ 注意：执行后可能需要重启

执行环境：PowerShell（管理员）

wsl --install --no-distribution

↑ 一键安装 WSL 核心，默认使用 WSL2

2.2 安装 Ubuntu 24.04

💻 执行环境：Windows PowerShell（管理员或普通权限均可）
📦 发行版选择：Ubuntu 24.04 LTS

执行环境：PowerShell

wsl --install -d Ubuntu-24.04

↑ 从 Microsoft Store 安装 Ubuntu 24.04 LTS

验证方式

执行环境：PowerShell

wsl --list --verbose

↑ 应显示：Ubuntu-24.04 Running（或 Stopped）

3. 系统环境准备

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：安装 DeepSeek-TUI 运行所需的系统级工具和依赖项

3.1 nvm + Node.js 安装

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：使用 nvm 管理 Node.js 版本（DeepSeek-TUI 需要 Node.js 环境）
📦 安装方式：通过 nvm 安装 LTS 版本 Node.js

执行环境：Bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

↑ 安装 nvm（Node Version Manager）

source ~/.bashrc

↑ 加载 nvm 环境变量

nvm install --lts

↑ 安装最新 LTS 版本 Node.js

nvm alias default node

↑ 设置默认 Node.js 版本

验证方式

执行环境：Bash

node --version

↑ 应显示 Node.js 版本号

npm --version

↑ 应显示 npm 版本号

3.2 Rust 工具链安装

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 权限要求：需要 sudo 权限
💡 目的：DeepSeek-TUI 由 Rust 编写，需要 Rust 编译器（版本需 1.88+）
📦 安装内容：rustup、cargo、rustc

执行环境：Bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

↑ 安装 Rust 工具链（rustup）

source ~/.cargo/env

↑ 加载 Rust 环境变量

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

↑ 将 cargo/bin 添加到 PATH

验证方式

执行环境：Bash

rustc --version

↑ 应显示 rustc 版本（需 1.88+）

cargo --version

↑ 应显示 cargo 版本

3.3 ripgrep 安装

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：DeepSeek-TUI 使用 ripgrep 进行快速文件搜索

执行环境：Bash

sudo apt install -y ripgrep

↑ 安装 ripgrep

验证方式

执行环境：Bash

rg --version

↑ 应显示 ripgrep 版本号

3.4 ffmpeg 安装（可选）

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：用于音视频处理功能（如需要）

执行环境：Bash

sudo apt install -y ffmpeg

↑ 安装 ffmpeg（可选）

验证方式

执行环境：Bash

ffmpeg -version

↑ 应显示 ffmpeg 版本信息

4. 国内镜像加速配置

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：配置国内镜像源加速下载，解决 GitHub 访问缓慢问题

4.1 配置 npm 淘宝镜像

💡 目的：加速 Node.js 包下载

执行环境：Bash

npm config set registry https://registry.npmmirror.com

↑ 配置 npmmirror 国内镜像

4.2 配置 cargo 清华镜像

💡 目的：加速 Rust crates.io 下载

执行环境：Bash

mkdir -p ~/.cargo && cat > ~/.cargo/config.toml << 'EOF' [source.crates-io] replace-with = "tuna" [source.tuna] registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/" [net] git-fetch-with-cli = true EOF

↑ 配置 cargo 清华镜像

4.3 配置 GitHub 镜像

💡 目的：加速 GitHub 仓库克隆

执行环境：Bash

git config --global url."https://ghproxy.cn/https://github.com".insteadOf "https://github.com"

↑ 使用 ghproxy 镜像加速 GitHub

5. DeepSeek-TUI 安装方式

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 说明：以下提供三种安装方式，推荐使用方式一（npm 安装）

5.1 方式一：npm 安装（推荐）

🎯 推荐方式 - npm 全局安装

零配置，一键安装，自动处理依赖。

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：使用 npm 全局安装 DeepSeek-TUI

执行环境：Bash

npm install -g deepseek-tui

↑ 全局安装 DeepSeek-TUI

验证步骤

执行环境：Bash

deepseek --version

↑ 应显示 DeepSeek-TUI 版本号，确认安装成功

5.2 方式二：直接下载二进制（零依赖）

📦 零依赖方式 - 下载预编译二进制

无需 Node.js/Rust 环境，下载即可运行，适合快速体验。

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
📂 安装目录：~/DeepSeek-TUI/

执行环境：Bash

mkdir -p ~/DeepSeek-TUI && cd ~/DeepSeek-TUI

↑ 创建并进入安装目录

curl -LO https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-tui-x86_64-unknown-linux-musl.tar.gz

↑ 下载最新版本的二进制压缩包

curl -LO https://ghproxy.cn/https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-tui-x86_64-unknown-linux-musl.tar.gz

↑ 使用 ghproxy 镜像加速下载（国内推荐）

💡 如果 GitHub 下载速度慢，可使用上面的镜像地址替代

解压二进制文件

执行环境：Bash

tar -xzf deepseek-tui-x86_64-unknown-linux-musl.tar.gz

↑ 解压二进制文件

配置 PATH（重要）

执行环境：Bash

echo 'export PATH="$HOME/DeepSeek-TUI:$PATH"' >> ~/.bashrc

↑ 将 DeepSeek-TUI 目录添加到 PATH

source ~/.bashrc

↑ 立即生效

验证步骤

执行环境：Bash

deepseek --version

↑ 应显示 DeepSeek-TUI 版本号，确认安装成功

5.3 方式三：源码编译

🔨 开发者方式 - 从源码编译

需要 Rust 工具链，可自定义构建选项，适合开发者贡献代码。

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 权限要求：需要 sudo 权限
📂 安装目录：~/DeepSeek-TUI/

执行环境：Bash

sudo apt install -y build-essential pkg-config libdbus-1-dev

↑ 安装编译依赖

git clone https://github.com/Hmbown/DeepSeek-TUI.git ~/DeepSeek-TUI

↑ 克隆源码仓库

cd ~/DeepSeek-TUI && cargo install --path crates/cli --locked

↑ 编译安装 CLI 工具

cd ~/DeepSeek-TUI && cargo install --path crates/tui --locked

↑ 编译安装 TUI 界面

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

↑ 确保 cargo/bin 在 PATH 中

source ~/.bashrc

↑ 立即生效

验证步骤

执行环境：Bash

deepseek --version

↑ 应显示 DeepSeek-TUI 版本号，确认安装成功

6. 安装后验证

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：验证 DeepSeek-TUI 安装成功，所有组件正常工作

6.1 验证安装

执行环境：Bash

deepseek --version

↑ 确认版本号

deepseek doctor

↑ 诊断检查，查看环境状态

6.2 配置 API Key

💡 目的：设置 DeepSeek API Key 以便使用服务
⚠️ 重要：以下两种方式二选一即可，无需重复设置

📋 两种方式对比：

对比项	方式一：deepseek auth set	方式二：环境变量
存储位置	~/.deepseek/ 配置文件	~/.bashrc 环境变量
安全性	✅ 更安全，Key 加密存储在应用配置中	⚠️ Key 以明文写在 bashrc 中
作用范围	仅 DeepSeek-TUI 使用	所有终端程序均可读取
多 Provider	✅ 支持，每个 Provider 独立设置 Key	❌ 仅支持一个 DEEPSEEK_API_KEY
适用场景	日常使用（推荐）	CI/CD、脚本自动化等需要全局变量的场景

方式一：交互式设置（推荐）

执行环境：Bash

deepseek auth set --provider deepseek

↑ 交互式输入 API Key，Key 加密存储在 ~/.deepseek/ 配置文件中，仅 DeepSeek-TUI 读取

方式二：环境变量（备选）

执行环境：Bash

echo 'export DEEPSEEK_API_KEY="YOUR_KEY"' >> ~/.bashrc

↑ 将 Key 写入环境变量（将 YOUR_KEY 替换为实际密钥），所有终端程序均可通过 $DEEPSEEK_API_KEY 读取

source ~/.bashrc

↑ 使环境变量立即生效

6.3 首次启动

执行环境：Bash

deepseek --model auto

↑ 启动 DeepSeek-TUI，自动选择模型

7. 配置说明

7.1 配置文件位置

📂 配置目录：~/.deepseek/
📄 配置文件：~/.deepseek/config.toml

7.2 人民币费用显示

💡 目的：将费用显示从美元改为人民币

执行环境：Bash

mkdir -p ~/.deepseek && cat >> ~/.deepseek/config.toml << 'EOF' cost_currency = "cny" EOF

↑ 配置人民币显示

7.3 中文界面

💡 目的：设置界面语言为简体中文

执行环境：Bash

cat >> ~/.deepseek/config.toml << 'EOF' [tui] locale = "zh-Hans" EOF

↑ 配置中文界面

7.4 多 Provider 配置

💡 目的：DeepSeek-TUI 支持多种 AI Provider，灵活切换

🤖 DeepSeek（默认）

使用官方 DeepSeek API，直接设置 API Key 即可。

执行环境：Bash

deepseek auth set --provider deepseek

🦙 Ollama 本地模型

使用 Ollama 部署的本地模型，保护隐私，无需 API Key。

安装 Ollama：curl -fsSL https://ollama.com/install.sh | sh
拉取模型：ollama pull deepseek-coder:1.3b
启动 Ollama 服务：ollama serve

💡 WSL2 GPU 直通配置（NVIDIA 显卡）：

确认 Windows 已安装最新 NVIDIA 驱动（无需在 WSL 内额外安装）
在 WSL 中验证 GPU：nvidia-smi（应显示显卡信息）
Ollama 会自动检测并使用 GPU，无需额外配置
如 nvidia-smi 不可用，参考：https://docs.nvidia.com/cuda/wsl-user-guide/

执行环境：Bash

deepseek --provider ollama --model deepseek-coder:1.3b

↑ 使用 Ollama 本地模型

⚡ vLLM 本地模型

使用 vLLM 部署的高性能推理服务器。

安装 vLLM：参考 https://docs.vllm.ai/
启动 vLLM 服务器

执行环境：Bash

VLLM_BASE_URL="http://localhost:8000/v1" deepseek --provider vllm --model deepseek-v4-flash

↑ 使用 vLLM 本地模型

☁️ 其他 Provider

DeepSeek-TUI 还支持以下 Provider：

nvidia-nim - NVIDIA NIM 推理服务
fireworks - Fireworks.ai
sglang - SGLang 推理框架

7.5 ACP 编辑器集成（v0.8.15 新增）

💡 功能说明：ACP（Agent Client Protocol）允许 DeepSeek-TUI 作为后端服务，为代码编辑器提供 AI 辅助功能
🎯 支持编辑器：Zed、Cursor、VS Code（通过插件）等

执行环境：Bash

deepseek serve --acp

↑ 启动 Agent Client Protocol 服务器

💡 使用场景：

在 Zed 编辑器中通过 MCP（Model Context Protocol）连接 DeepSeek-TUI
获得代码补全、解释、重构等 AI 辅助功能
享受本地模型的隐私保护和低延迟优势

8. 常用命令参考

8.1 基础命令

💡 目的：DeepSeek-TUI 基本用法

执行环境：Bash

deepseek --version

↑ 查看版本号

deepseek --help

↑ 显示帮助信息

deepseek doctor

↑ 环境诊断检查

8.2 会话管理

💡 目的：管理对话会话

执行环境：Bash

deepseek chat

↑ 开始新对话

deepseek sessions list

↑ 列出历史会话

deepseek sessions delete <session_id>

↑ 删除指定会话

deepseek --continue

↑ 继续上次会话

8.3 认证管理

执行环境：Bash

deepseek auth set --provider deepseek

↑ 设置 API Key

deepseek auth list

↑ 列出已配置的 Provider

deepseek auth remove --provider deepseek

↑ 移除 Provider

8.4 工具与 MCP

执行环境：Bash

deepseek tools list

↑ 列出可用工具

deepseek mcp list

↑ 列出已配置的 MCP 服务器

deepseek serve --acp

↑ 启动 ACP 服务器（编辑器集成）

8.5 其他命令

执行环境：Bash

deepseek config

↑ 查看当前配置

deepseek config set <key> <value>

↑ 设置配置项

deepseek update

↑ 检查并更新到最新版本

8.6 快捷键

快捷键	功能
`Ctrl+C`	取消当前输入
`Ctrl+L`	清屏
`Ctrl+S`	暂停输出
`↑/↓`	历史命令切换
`Tab`	自动补全
`Ctrl+Shift+C`	复制选中内容

9. 卸载与更新

9.1 卸载 DeepSeek-TUI

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 说明：根据安装方式选择对应的卸载命令

方式一卸载（npm 安装）

执行环境：Bash

npm uninstall -g deepseek-tui

↑ 卸载 npm 全局包

方式二卸载（二进制安装）

执行环境：Bash

rm -rf ~/DeepSeek-TUI

↑ 删除安装目录

sed -i '/DeepSeek-TUI/d' ~/.bashrc

↑ 清理 ~/.bashrc 中的 DeepSeek-TUI PATH 配置

方式三卸载（Cargo 安装）

执行环境：Bash

cargo uninstall deepseek

↑ 卸载 cargo 安装的二进制

清理配置

执行环境：Bash

rm -rf ~/.deepseek

↑ 删除配置和数据目录

9.2 更新 DeepSeek-TUI

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 说明：根据安装方式选择对应的更新命令

方式一更新（npm 安装）

执行环境：Bash

npm update -g deepseek-tui

↑ 更新 npm 全局包

方式二更新（二进制安装）

执行环境：Bash

deepseek update

↑ 使用内置更新命令

方式三更新（Cargo 安装）

执行环境：Bash

cd ~/DeepSeek-TUI && git pull && cargo install --path crates/cli --locked

↑ 拉取最新代码并重新编译

10. 排错指南

💡 目的：列出常见问题及解决方案

10.1 command not found 错误

问题：执行 deepseek 提示 command not found

原因：PATH 环境变量未包含 DeepSeek-TUI 安装目录

解决方案：

确认安装方式：
- npm 安装：检查 npm root -g 输出目录是否在 PATH
- 二进制安装：确认 ~/DeepSeek-TUI 在 PATH
- cargo 安装：确认 ~/.cargo/bin 在 PATH
添加 PATH：echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
使用完整路径：~/.cargo/bin/deepseek --version

10.2 API Key 相关问题

问题：API Key 无效或认证失败

原因：API Key 未设置或设置错误

解决方案：

重新设置 API Key：deepseek auth set --provider deepseek
检查环境变量：echo $DEEPSEEK_API_KEY
确认 API Key 有效：访问 DeepSeek 开放平台验证

10.3 网络连接问题

问题：网络连接失败，无法访问 API

原因：网络问题或代理配置错误

解决方案：

检查网络连接：ping api.deepseek.com
配置代理（如需要）：export http_proxy="http://proxy:port"
使用镜像加速：配置 GitHub 镜像
检查防火墙设置

10.4 Rust 编译失败

问题：cargo build 或 cargo install 编译失败

原因：Rust 版本过低或缺少依赖

解决方案：

更新 Rust：rustup update
检查 Rust 版本：rustc --version（需 1.88+）
安装编译依赖：sudo apt install -y build-essential pkg-config libdbus-1-dev
清理缓存后重试：cargo clean && cargo install --path ...

10.5 获取帮助

问题：遇到其他未知问题

解决方案：

查看帮助文档：deepseek --help
运行诊断：deepseek doctor
访问官方仓库：https://github.com/Hmbown/DeepSeek-TUI
查看 Issues：https://github.com/Hmbown/DeepSeek-TUI/issues

📕 文档验证完成

所有 11 个章节已完整覆盖：前置环境检查、WSL2 配置、系统环境准备、镜像加速、三种安装方式（含验证步骤）、安装后验证、多 Provider 配置、ACP 编辑器集成、常用命令、卸载更新、排错指南。