# CodeWhale（原 DeepSeek-TUI）集成

> **最后核实**：2026-09-18 · 📄 依据官方文档（CodeWhale v0.9.13，2026-09-14 发布（原 DeepSeek-TUI））

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（anthropic provider，自拼 `/v1/messages`）· GPT ✅ · 国产 ✅（openai provider）· Gemini ⚠️ 未核实 —— 官方 `google` provider 走的是 Gemini 的 OpenAI 兼容路由，且明文「指向别的网关时退化为普通 OpenAI 语义」；我们没有核实 QCode 的 OpenAI Chat 腿是否接受 gemini 系 id |
| 协议与 Base URL | Anthropic：`https://api.qcode.cc/api` · OpenAI：`https://api.qcode.cc/openai/v1` |
| 配置位置 | `~/.codewhale/config.toml`（旧 `~/.deepseek/` 仅在无新目录时回退） |
| 官方文档 | [Hmbown/Codewhale](https://github.com/Hmbown/Codewhale) |

> **⚠️ 项目已改名**：`DeepSeek-TUI` 现名 **CodeWhale**，二进制从 `deepseek` 改为 `codewhale`，
> 配置文件从 `~/.deepseek/config.toml` 迁移到 `~/.codewhale/config.toml`。旧目录的回退读取有前提：
> 官方的迁移契约是 **read-with-fallback, write-to-new** —— 读的时候优先看 `~/.codewhale/`，
> **只有旧目录存在时**才退回 `~/.deepseek/`；写的时候永远写新目录。
> 另外自 **v0.9.0** 起，`deepseek` 与 `deepseek-tui` 两个旧命令已被删除，当前入口只有
> `codewhale`、`codew`（便捷别名）、`codewhale-tui`。官网 `deepseek-tui.com` 现 301 跳转到
> [codewhale.net](https://codewhale.net)。本页 URL 保持不变。

[CodeWhale](https://codewhale.net) 是一款命令行 AI 编程 Agent，内置数十个一等公民 provider
（`anthropic`、`openai`、`deepseek`、`ollama`、`vllm`、`openrouter` 等；官方文档说真源是源码里的
`ProviderKind::ALL` 清单，随版本增减，用 `/provider` 面板看你本机版本实际支持的那份），
既支持 **Anthropic 原生 Messages 协议**，也支持 **OpenAI Chat Completions 兼容协议**。
两种协议都能把后端指向 QCode.cc。

## 🔴 先看这一条：Claude 必须走 anthropic provider

QCode 的 OpenAI 兼容端点**不接受 Claude 模型**——把 `claude-…` 填进 `[providers.openai]`
会返回 `model_not_available_on_endpoint`。对照表见
[接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

| 你想用的模型 | CodeWhale 该用的 provider | QCode 的 `base_url` |
|---|---|---|
| Claude（`claude-opus-5` / `claude-sonnet-5` …） | `anthropic` | `https://api.qcode.cc/api` |
| GPT 系（`gpt-6-sol` / `gpt-6-luna` …） | `openai` | `https://api.qcode.cc/openai/v1` |
| GLM / Kimi / DeepSeek / Qwen | 两者皆可 | 见上两行 |

## 为什么用 CodeWhale 接 QCode

- **熟悉的 TUI 体验**：Plan / Work / Operate 三种模式，配合 Ask / Auto-Review / Full Access 三档权限（`Shift+Tab` 切换）；内置 MCP / Shell / Git / 子代理
- **同一份 API Key**：与 Claude Code、Codex CLI 共享 QCode 套餐配额
- **多 provider 切换**：同一个工具里在 anthropic / openai / ollama / vllm 之间随时切
- **中国大陆友好**：`asia.qcode.cc`（亚洲节点，HK/JP 就近），从大陆访问延迟最低
- **完全开源**：MIT 协议，配置文件可审计

## 一、安装

官方首推的是 GitHub Releases 安装脚本，npm / Cargo 被官方明确定位为 **secondary**（次要）打包方式：

```bash
# Officially recommended (macOS / Linux): installs the release binary
curl -fsSL https://codewhale.net/install.sh | sh

# npm - the official docs call this a secondary packaging route (Node 18+)
npm install -g codewhale

# Homebrew - add the tap first, otherwise a fresh machine cannot find the formula
brew tap Hmbown/deepseek-tui
brew install codewhale

# Cargo - source build; the crate is codewhale-cli, the command it installs is codewhale
cargo install codewhale-cli --locked
```

细节与平台限制以 [官方安装文档](https://codewhale.net/en/install) 为准。

验证安装（**不要对照文档里的版本数字，以实际输出为准**）：

```bash
codewhale --version
```

## 二、配置 Claude（anthropic provider）

编辑 `~/.codewhale/config.toml`：

```toml
# ~/.codewhale/config.toml

provider = "anthropic"

[providers.anthropic]
api_key  = "cr_你的QCode密钥"
base_url = "https://api.qcode.cc/api"
model    = "claude-sonnet-5"
```

字段说明：

| 字段 | 说明 |
|------|------|
| `provider` | 顶级设为 `"anthropic"`，默认走 Anthropic 原生 Messages 协议 |
| `api_key` | QCode.cc 控制台获取，`cr_` 开头。CodeWhale 会把它放进 `x-api-key` 头 |
| `base_url` | 填到 `/api` 为止，CodeWhale 会自拼 `/v1/messages`（官方文档明文）。不要在末尾多带 `/`，也不要自己把 `/v1/messages` 写进去 |
| `model` | QCode 在售的 Claude 模型 id，见 [qcode.cc/models](https://qcode.cc/models)。官方把 `[providers.<表>].model` 定位成 **provider 级覆盖**，默认模型更推荐写在配置文件顶层的 `default_text_model` |

> **国内用户**把域名换成 `https://asia.qcode.cc/api`（亚洲节点，HK/JP 就近）即可，Key 不变。

也可以用环境变量替代配置文件。官方现在优先推荐一组通用的 `CODEWHALE_*` 变量：

```bash
export CODEWHALE_PROVIDER="anthropic"
export CODEWHALE_BASE_URL="https://api.qcode.cc/api"
export CODEWHALE_MODEL="claude-sonnet-5"
export ANTHROPIC_API_KEY="cr_你的QCode密钥"

codewhale
```

provider 专用变量（`ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL`）官方仍然接受，`codewhale --provider anthropic` 这个旗标也仍然可用。

## 三、配置 GPT 与国产模型（openai provider）

同一个配置文件里可以并存多个 provider，用 `codewhale --provider <id>` 切换：

```toml
[providers.openai]
api_key  = "cr_你的QCode密钥"
base_url = "https://api.qcode.cc/openai/v1"
model    = "gpt-6-sol"
```

`base_url` 填到 `/openai/v1` 为止，CodeWhale 会自拼 `/chat/completions`。若你的版本要改这个后缀，
官方给的键是 `path_suffix`（写在 `[providers.openai]` 里），不要靠拼进 `base_url` 绕。

国产四家族（`glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.8-max` 等）
两条腿都能走，填在哪个 provider 里都可以，id 见 [国产模型接入](/docs/usage/cn-models)。

## 四、可用模型

| 模型 id | provider | 用途建议 |
|---------|----------|---------|
| `claude-opus-5` | `anthropic` | 重型规划 / 复杂架构设计 |
| `claude-sonnet-5` | `anthropic` | 日常编码（**推荐**） |
| `claude-haiku-4-5` | `anthropic` | 快速小任务 / 低成本场景 |
| `gpt-6-sol` | `openai` | OpenAI 旗舰（默认推荐） |
| `gpt-6-luna` | `openai` | 快速 / 低成本 |
| `glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.8-max` | 两者皆可 | 成本更低的国产选择 |

> `claude-sonnet-4-6`、`claude-opus-4-8` 等 4.x 仍在售。完整清单与实时单价以
> [qcode.cc/models](https://qcode.cc/models) 为准。

查询当前可调模型（注意两条腿的列表**不一样**）：

```bash
# Claude 与国产模型（Anthropic 腿）
curl https://api.qcode.cc/v1/models -H "Authorization: Bearer cr_你的QCode密钥"

# GPT 系（OpenAI 腿）
curl https://api.qcode.cc/openai/v1/models -H "Authorization: Bearer cr_你的QCode密钥"
```

## 五、验证连通

```bash
KEY="cr_你的QCode密钥"

# Claude（Anthropic 协议）—— 应返回含 content 的 JSON
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'

# GPT（OpenAI 协议）—— 应返回含 choices 的 JSON
curl -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

验证通过后启动：

```bash
codewhale
```

## 六、排错

| 现象 | 原因 | 处理 |
|------|------|------|
| `model_not_available_on_endpoint` | 把 Claude 模型填到了 `[providers.openai]` | 改用 `[providers.anthropic]`，`base_url` 填 `https://api.qcode.cc/api` |
| `Invalid API key` | 密钥错误或带了空格 | 检查 `cr_` 开头、无前后空格 |
| 404 | `base_url` 末尾多了 `/`，或路径前缀写错 | 对照 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) |
| 配置改了不生效 | 官方语义是**只在新目录不存在时**才回退读旧目录，所以基本不是旧文件的问题；更常见的原因是密钥来源优先级（saved config / keyring 优先于环境变量）、或项目内 `.codewhale/config.toml` 覆盖在全局之上 | 用官方的 `codewhale auth status`（会打印哪个来源胜出）与 `/config audit` 自查；改完 provider 的 base URL 需要重启客户端才生效 |

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — 协议 × 模型家族真源表
- [国产模型接入](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen 的 id 与路径
- [模型选择指南](/docs/usage/model-selection) — 什么任务该用哪个模型