# CodeWhale (formerly DeepSeek-TUI) Integration

> **Last verified**: 2026-09-18 · 📄 Per official docs (CodeWhale v0.9.13, released 2026-09-14 (formerly DeepSeek-TUI))

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (anthropic provider, appends `/v1/messages` itself) · GPT ✅ · Chinese models ✅ (openai provider) · Gemini ⚠️ not verified — the official `google` provider uses Gemini's OpenAI-compatible route, and the docs say a `google` row pointed at another gateway degrades to plain OpenAI semantics; we have not verified that QCode's OpenAI Chat leg accepts gemini-family ids |
| Protocol & Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| Where to configure | `~/.codewhale/config.toml` (legacy `~/.deepseek/` is a fallback only when the new dir is absent) |
| Official docs | [Hmbown/Codewhale](https://github.com/Hmbown/Codewhale) |

> **⚠️ The project was renamed.** `DeepSeek-TUI` is now **CodeWhale**. The binary changed from
> `deepseek` to `codewhale`, and the config file moved from `~/.deepseek/config.toml` to
> `~/.codewhale/config.toml`. The fallback is conditional: the official migration contract is
> **read-with-fallback, write-to-new** — reads look in `~/.codewhale/` first and fall back to
> `~/.deepseek/` **only when that is the only directory present**, while every write goes to the new
> directory. Also, since **v0.9.0** the `deepseek` and `deepseek-tui` commands were deleted; the
> entry points are `codewhale`, `codew` (a convenience alias) and `codewhale-tui`. The old site
> `deepseek-tui.com` now 301-redirects to [codewhale.net](https://codewhale.net).
> This page's URL is unchanged.

[CodeWhale](https://codewhale.net) is a terminal AI coding agent with dozens of first-class
providers (`anthropic`, `openai`, `deepseek`, `ollama`, `vllm`, `openrouter` and more; the docs point
at `ProviderKind::ALL` in the source as the real list, which grows and shrinks between versions — run
`/provider` to see the set in your own build). It speaks both the **native Anthropic Messages
protocol** and the **OpenAI Chat Completions** protocol, and either one can point at QCode.cc.

## 🔴 Read this first: Claude requires the anthropic provider

QCode's OpenAI-compatible endpoint **does not accept Claude models** — putting `claude-…` into
`[providers.openai]` returns `model_not_available_on_endpoint`. See the compatibility table in
[Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths).

| Model you want | CodeWhale provider to use | 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 | either | see the two rows above |

## Why use CodeWhale with QCode

- **Familiar TUI**: Plan / Work / Operate modes, with the Ask / Auto-Review / Full Access permission postures (`Shift+Tab`) and built-in MCP / Shell / Git / subagents
- **One API key**: shares your QCode plan quota with Claude Code and Codex CLI
- **Provider switching**: move between anthropic / openai / ollama / vllm in the same tool
- **Works well from mainland China**: `asia.qcode.cc` (Asia node, near HK/JP) has the lowest latency
- **Fully open source**: MIT licensed, the config file is auditable

## 1. Install

The official first choice is the GitHub Releases install script; npm and Cargo are called
**secondary** packaging routes in the docs:

```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
```

Platform limits and details: [official install docs](https://codewhale.net/en/install).

Verify (**trust the actual output, not a version number printed in any doc**):

```bash
codewhale --version
```

## 2. Configure Claude (anthropic provider)

Edit `~/.codewhale/config.toml`:

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

provider = "anthropic"

[providers.anthropic]
api_key  = "cr_your_qcode_key"
base_url = "https://api.qcode.cc/api"
model    = "claude-sonnet-5"
```

| Field | Meaning |
|------|---------|
| `provider` | Set to `"anthropic"` at top level to default to the native Messages protocol |
| `api_key` | From the QCode.cc console, starts with `cr_`. CodeWhale sends it as `x-api-key` |
| `base_url` | Stop at `/api`; CodeWhale appends `/v1/messages` (stated in the official docs). Do not add a trailing `/`, and do not write `/v1/messages` yourself |
| `model` | A Claude model id QCode sells — see [qcode.cc/models](https://qcode.cc/models). The docs treat `[providers.<table>].model` as a **provider-level override**; the default model belongs in the top-level `default_text_model` |

> **From mainland China**, swap the host for `https://asia.qcode.cc/api` (Asia node, near HK/JP).
> The key is unchanged.

Environment variables work instead of the config file; the docs now favour the generic `CODEWHALE_*` set:

```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_your_qcode_key"

codewhale
```

The provider-specific variables (`ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL`) are still accepted, and so
is the `codewhale --provider anthropic` flag.

## 3. Configure GPT and Chinese models (openai provider)

Multiple providers can coexist in one config; switch with `codewhale --provider <id>`:

```toml
[providers.openai]
api_key  = "cr_your_qcode_key"
base_url = "https://api.qcode.cc/openai/v1"
model    = "gpt-6-sol"
```

Stop `base_url` at `/openai/v1`; CodeWhale appends `/chat/completions`. If a build needs a
different suffix, the official key for that is `path_suffix` inside `[providers.openai]` — do not
smuggle it into `base_url`.

The four Chinese families (`glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.8-max` …) work on
**both** legs, so either provider is fine. Ids are listed in
[Chinese Models](/docs/usage/cn-models).

## 4. Available models

| Model id | Provider | Best for |
|---------|----------|----------|
| `claude-opus-5` | `anthropic` | Heavy planning / complex architecture |
| `claude-sonnet-5` | `anthropic` | Everyday coding (**recommended**) |
| `claude-haiku-4-5` | `anthropic` | Quick small tasks / low cost |
| `gpt-6-sol` | `openai` | OpenAI flagship |
| `gpt-6-luna` | `openai` | Fast, low cost |
| `glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.8-max` | either | Cheaper Chinese options |

> 4.x models such as `claude-sonnet-4-6` and `claude-opus-4-8` are still sold. The full list and
> live prices are on [qcode.cc/models](https://qcode.cc/models).

List what you can call right now — note the two legs return **different** lists:

```bash
# Claude and Chinese models (Anthropic leg)
curl https://api.qcode.cc/v1/models -H "Authorization: Bearer cr_your_qcode_key"

# GPT (OpenAI leg)
curl https://api.qcode.cc/openai/v1/models -H "Authorization: Bearer cr_your_qcode_key"
```

## 5. Verify connectivity

```bash
KEY="cr_your_qcode_key"

# Claude (Anthropic protocol) — should return JSON containing content
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 protocol) — should return JSON containing choices
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"}]}'
```

Then launch:

```bash
codewhale
```

## 6. Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| `model_not_available_on_endpoint` | A Claude model was put in `[providers.openai]` | Use `[providers.anthropic]` with `base_url` = `https://api.qcode.cc/api` |
| `Invalid API key` | Wrong key, or stray whitespace | Check it starts with `cr_` and has no leading/trailing spaces |
| 404 | Trailing slash on `base_url`, or wrong path prefix | Compare against [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths) |
| Config edits have no effect | The official contract only falls back to the legacy directory when it is the only one present, so a stale `~/.deepseek/config.toml` is rarely the cause; far more often it is credential precedence (saved config / keyring beat environment variables) or a project-level `.codewhale/config.toml` layered over the global one | Run the official `codewhale auth status` (it prints which source wins) and `/config audit`; a changed provider base URL needs the model client restarted |

## Related

- [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths) — protocol × model-family table
- [Chinese Models](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen ids and paths
- [Model Selection](/docs/usage/model-selection) — which model for which task