# CodeWhale (ранее DeepSeek-TUI): интеграция

> **Последняя проверка**: 2026-09-18 · 📄 По официальной документации (CodeWhale v0.9.13, выпуск 2026-09-14 (ранее DeepSeek-TUI))

## Кратко

| Параметр | Описание |
|---|---|
| Доступные модели | Claude ✅ (провайдер anthropic, сам дописывает `/v1/messages`) · GPT ✅ · китайские модели ✅ (openai) · Gemini ⚠️ не проверено — официальный провайдер `google` идёт через OpenAI-совместимый маршрут Gemini, и в документации сказано, что строка `google`, направленная на другой шлюз, выдаёт обычную семантику OpenAI. Принимает ли OpenAI Chat-ветка QCode идентификаторы семейства gemini, мы не проверяли |
| Протокол и 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-агент для программирования с десятками
встроенных провайдеров (`anthropic`, `openai`, `deepseek`, `ollama`, `vllm`, `openrouter` и другие;
документация называет первоисточником список `ProviderKind::ALL` в коде, и он меняется между
версиями — какие есть у вас, показывает панель `/provider`. Агент поддерживает и **нативный протокол
Anthropic Messages**, и **OpenAI-совместимый Chat Completions**; оба можно направить на QCode.cc.

## 🔴 Сначала прочтите: для Claude нужен провайдер anthropic

OpenAI-совместимая точка QCode **не принимает модели Claude** — если указать `claude-…` в
`[providers.openai]`, вернётся `model_not_available_on_endpoint`. Таблица совместимости —
в [Точках доступа и форматах API](/docs/getting-started/endpoints-and-api-paths).

| Нужная модель | Провайдер CodeWhale | `base_url` QCode |
|---|---|---|
| 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-ключ**: общая квота тарифа QCode с Claude Code и Codex CLI
- **Переключение провайдеров**: anthropic / openai / ollama / vllm в одном инструменте
- **Удобно из материкового Китая**: `asia.qcode.cc` (азиатский узел, поблизости от HK/JP) даёт минимальную задержку
- **Полностью открытый код**: лицензия MIT, конфигурацию можно проверить

## 1. Установка

Официально первый вариант — скрипт установки из GitHub Releases; npm и Cargo названы в
документации **вторичными** способами упаковки:

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

## 2. Настройка Claude (провайдер anthropic)

Отредактируйте `~/.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"` на верхнем уровне — по умолчанию нативный протокол Messages |
| `api_key` | Из консоли QCode.cc, начинается с `cr_`. CodeWhale отправляет его в заголовке `x-api-key` |
| `base_url` | До `/api`; CodeWhale сам добавит `/v1/messages` (это есть в официальной документации). Слэш в конце не ставьте и `/v1/messages` руками не дописывайте |
| `model` | Идентификатор продаваемой модели Claude — см. [qcode.cc/models](https://qcode.cc/models). В документации `[providers.<table>].model` — это **переопределение на уровне провайдера**; модель по умолчанию лучше задавать сверху, в `default_text_model` |

> **Из материкового Китая** замените хост на `https://asia.qcode.cc/api` (азиатский узел, поблизости от HK/JP).
> Ключ тот же.

Вместо файла можно использовать переменные окружения; документация теперь отдаёт приоритет
универсальному набору `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
```

Специфичные для провайдера переменные (`ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL`) тоже принимаются,
как и флаг `codewhale --provider anthropic`.

## 3. Настройка GPT и китайских моделей (провайдер openai)

В одной конфигурации может быть несколько провайдеров; переключение —
`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` …)
работают на **обоих** протоколах, поэтому подойдёт любой провайдер. Идентификаторы —
в [Китайских моделях](/docs/usage/cn-models).

## 4. Доступные модели

| Идентификатор | Провайдер | Для чего |
|---------|----------|----------|
| `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` | любой | Более дешёвые китайские варианты |

> Модели 4.x, такие как `claude-sonnet-4-6` и `claude-opus-4-8`, всё ещё продаются. Полный
> список и актуальные цены — на [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"
```

## 5. Проверка связи

```bash
KEY="cr_ваш_ключ_QCode"

# Claude (протокол Anthropic) — должен вернуться JSON с полем 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) — должен вернуться JSON с полем 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"}]}'
```

После проверки запустите:

```bash
codewhale
```

## 6. Диагностика

| Симптом | Причина | Решение |
|---------|---------|---------|
| `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) |
| Изменения конфигурации не применяются | По официальному правилу откат к старому каталогу работает лишь когда он единственный, так что устаревший `~/.deepseek/config.toml` — редкая причина. Обычно это приоритет источников ключа (saved config и keyring важнее переменных окружения) либо проектный `.codewhale/config.toml`, наложенный на глобальный | Запустите официальные `codewhale auth status` (показывает, какой источник победил) и `/config audit`; после смены base URL у провайдера клиент модели нужно перезапустить |

## Смежные документы

- [Точки доступа и форматы API](/docs/getting-started/endpoints-and-api-paths) — таблица «протокол × семейство моделей»
- [Китайские модели](/docs/usage/cn-models) — идентификаторы и пути GLM / Kimi / DeepSeek / Qwen
- [Выбор модели](/docs/usage/model-selection) — какая модель для какой задачи