# 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` は [codewhale.net](https://codewhale.net) へ 301 リダイレクトします。
> 本ページの URL は変更ありません。

[CodeWhale](https://codewhale.net) は数十個の一級 provider を内蔵したターミナル AI
コーディングエージェントです（`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) を参照。

| 使いたいモデル | 使うべき provider | QCode の `base_url` |
|---|---|---|
| Claude（`claude-opus-5` / `claude-sonnet-5` など） | `anthropic` | `https://api.qcode.cc/api` |
| GPT 系（`gpt-5.5` / `gpt-5.4` など） | `openai` | `https://api.qcode.cc/openai/v1` |
| GLM / Kimi / DeepSeek / Qwen | どちらでも可 | 上の 2 行を参照 |

## CodeWhale を QCode で使う理由

- **使い慣れた TUI**：Plan / Work / Operate の 3 モードに、Ask / Auto-Review / Full Access の権限段階（`Shift+Tab` で切替）を組み合わせ。MCP / Shell / Git / サブエージェントも内蔵
- **API キーは 1 本**：Claude Code、Codex CLI と QCode プランのクォータを共有
- **provider 切り替え**：同一ツール内で anthropic / openai / ollama / vllm を随時切替
- **中国本土から快適**：`asia.qcode.cc`（アジアノード、HK/JP 付近）が最も低遅延
- **完全オープンソース**：MIT ライセンス、設定ファイルは監査可能

## 1. インストール

公式が最初に勧めるのは 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
```

## 2. 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` まで（`/v1/messages` の自動連結は公式文書に記載）。末尾に `/` を付けず、`/v1/messages` 側も自分で書かないでください |
| `model` | QCode で販売中の Claude モデル id（[qcode.cc/models](https://qcode.cc/models)）。文書では `[providers.<table>].model` は **provider 単位の上書き**扱いで、既定のモデルはトップレベルの `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
```

provider 専用の変数（`ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL`）も引き続き認識され、
`codewhale --provider anthropic` のフラグも有効です。

## 3. GPT と中国系モデルの設定（openai provider）

1 つの設定ファイルに複数の provider を併存でき、`codewhale --provider <id>` で切り替えます：

```toml
[providers.openai]
api_key  = "cr_あなたのQCodeキー"
base_url = "https://api.qcode.cc/openai/v1"
model    = "gpt-5.5"
```

`base_url` は `/openai/v1` までとしてください。CodeWhale が `/chat/completions` を連結します。
サフィックスを変える必要がある場合、公式が用意するキーは `[providers.openai]` 内の `path_suffix` です。
`base_url` に混ぜて書かないでください。

中国系 4 ファミリー（`glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.8-max` など）は
**両方のレッグ**で動くため、どちらの provider に書いても構いません。id は
[中国系モデル連携](/docs/usage/cn-models) を参照。

## 4. 利用可能なモデル

| モデル id | provider | 用途 |
|---------|----------|------|
| `claude-opus-5` | `anthropic` | 重い計画立案 / 複雑なアーキテクチャ設計 |
| `claude-sonnet-5` | `anthropic` | 日常のコーディング（**推奨**） |
| `claude-haiku-4-5` | `anthropic` | 軽量タスク / 低コスト |
| `gpt-5.5` | `openai` | 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) を参照。

現在呼べるモデルの確認（2 つのレッグで**一覧が異なります**）：

```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 プロトコル）—— content を含む JSON が返れば OK
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 が返れば OK
curl -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","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) と照合 |
| 設定を変えても反映されない | 公式の仕様上、旧ディレクトリフォールバックは「旧ディレクトリしかない」場合のみなので、旧ファイルが原因になることは稀です。より多いのは、認証情報の優先順位（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) — どのタスクにどのモデルか