# یکپارچه‌سازی CodeWhale (پیش‌تر DeepSeek-TUI)

> **آخرین بازبینی**: 2026-10-26 · 📄 بر پایه مستندات رسمی (CodeWhale v0.10.2، منتشرشده در 2026-10-24 (پیش‌تر DeepSeek-TUI)؛ بازبینی 2026-09-18 نسخه v0.9.13 را بررسی کرد، منتشرشده در 2026-09-14)

## نگاه کلی

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (ارائه‌دهنده anthropic، خودش `/v1/messages` را اضافه می‌کند) · GPT ✅ · مدل‌های چینی ✅ (ارائه‌دهنده openai) · Gemini ❌ (QCode فعلاً مدل‌های Gemini را ارائه نمی‌دهد) |
| پروتکل و Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| محل پیکربندی | `~/.codewhale/config.toml` (مسیر قدیمی `~/.deepseek/` تنها زمانی جایگزین است که پوشه جدید وجود نداشته باشد) |
| مستندات رسمی | [codewhale-hq/Codewhale](https://github.com/codewhale-hq/Codewhale) |

> **⚠️ نام پروژه تغییر کرده است.** `DeepSeek-TUI` اکنون **CodeWhale** است. نام باینری از
> `deepseek` به `codewhale` تغییر کرد و فایل پیکربندی از `~/.deepseek/config.toml` به
> `~/.codewhale/config.toml` منتقل شد. جایگزینی مشروط است: قرارداد رسمی مهاجرت
> **خواندن با جایگزین، نوشتن در مسیر جدید** است — خواندن ابتدا در `~/.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) یک عامل کدنویسی با هوش مصنوعی در ترمینال است که ده‌ها
ارائه‌دهنده درجه‌یک دارد (`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` …) | `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` (نود آسیا، نزدیک کره / تایوان / هنگ‌کنگ) نزدیک‌ترین نقطه پایانی است
- **کاملاً متن‌باز**: با مجوز 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 - full name taps and trusts in one step (the two-step form fails on Homebrew 7.x)
brew install Hmbown/deepseek-tui/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).

> **تغییر در 2026-10-26:** صفحه نصب رسمی اکنون می‌گوید فرم دو مرحله‌ای (`brew tap Hmbown/deepseek-tui` سپس `brew install codewhale`) در Homebrew 7.x شکست می‌خورد؛ از نام کامل بالا استفاده کنید، یا ابتدا `brew trust hmbown/deepseek-tui` را اجرا کنید. نسخه 2026-09-18 این صفحه فرم دو مرحله‌ای را نشان می‌داد.

بررسی کنید (**به خروجی واقعی اعتماد کنید، نه به شماره نسخه‌ای که در هر مستندی درج شده است**):

```bash
codewhale --version
```
## 2. پیکربندی Claude (ارائه‌دهنده anthropic)

فایل `~/.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"
```

| فیلد | معنا |
|------|---------|
| `provider` | در سطح بالایی روی `"anthropic"` تنظیم کنید تا به‌طور پیش‌فرض از پروتکل بومی Messages استفاده شود |
| `api_key` | از کنسول QCode.cc دریافت می‌شود و با `cr_` شروع می‌شود. CodeWhale آن را به‌عنوان `x-api-key` ارسال می‌کند |
| `base_url` | روی `/api` متوقف شوید؛ CodeWhale به‌صورت خودکار `/v1/messages` را اضافه می‌کند (در مستندات رسمی ذکر شده است). در پایان `/` اضافه نکنید و خودتان `/v1/messages` را ننویسید |
| `model` | شناسه مدل Claude که QCode می‌فروشد — ببینید [qcode.cc/models](https://qcode.cc/models). مستندات `[providers.<table>].model` را به‌عنوان **جایگزین در سطح ارائه‌دهنده** (override) در نظر می‌گیرد؛ مدل پیش‌فرض باید در `default_text_model` در سطح بالایی قرار گیرد |

> **از سرزمین اصلی چین**، میزبان را با `https://asia.qcode.cc/api` جایگزین کنید (گره آسیایی نزدیک کره / تایوان / هنگ‌کنگ).
> کلید تغییر نمی‌کند.

متغیرهای محیطی به‌جای فایل پیکربندی کار می‌کنند؛ مستندات اکنون مجموعه عمومی `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_your_qcode_key"

codewhale
```

متغیرهای اختصاصی ارائه‌دهنده (`ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL`) همچنان پذیرفته می‌شوند و پرچم `codewhale --provider anthropic` هم پذیرفته است.

### تغییرات در v0.10.1–v0.10.2 که بر این پیکربندی اثر می‌گذارند (2026-10-26)

نام باینری (`codewhale`) و مسیر پیکربندی (`~/.codewhale/config.toml`) در مستندات رسمی نصب و پیکربندی که در تاریخ 2026-10-26 بررسی شده‌اند تغییر نکرده‌اند. دو تغییر مرتبط با پیکربندی از نسخه v0.10.0 به بعد:

- **v0.10.1** — سطح بالایی اکنون یک معنا دارد: «یک `base_url` یا `api_key` در سطح بالایی در `config.toml` اکنون یک معنا در همه‌جا دارد.» فایل‌های قدیمی همچنان کار می‌کنند: «کلیدها به‌عنوان `[providers.deepseek]` (یا ارائه‌دهنده‌ای که این کلیدها میزبان رسمی‌اش را نام می‌برند) خوانده می‌شوند؛ ذخیره‌سازی بعدی آن‌ها را با یک پشتیبان یک‌باره و یک یادداشت یک‌خطی به همان‌جا منتقل می‌کند»، و `codewhale config doctor` نشان می‌دهد چه چیزی در حال استفاده است (یادداشت‌های انتشار). این صفحه هر دو مقدار را داخل `[providers.anthropic]` / `[providers.openai]` می‌نویسد و بنابراین تحت تأثیر قرار نمی‌گیرد.
- **v0.10.2 (2026-10-24)** — دستور نصب رسمی می‌تواند نسخه را ثابت کند: `curl -fsSL https://codewhale.net/install.sh | CODEWHALE_VERSION="v0.10.2" sh` (یادداشت‌های انتشار). دستور نصب بدون نسخه ثابت `curl -fsSL https://codewhale.net/install.sh | sh` از صفحه نصب همچنان وجود دارد.

## 3. پیکربندی GPT و مدل‌های چینی (ارائه‌دهنده openai)

چند ارائه‌دهنده می‌توانند در یک پیکربندی هم‌زمان وجود داشته باشند؛ با `codewhale --provider <id>` جابه‌جا شوید:

```toml
[providers.openai]
api_key  = "cr_your_qcode_key"
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-5-5` | `anthropic` | کارهای کوچک سریع / هزینه کم |
| `gpt-6-sol` | `openai` | مدل پرچم‌دار 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 and Chinese models (Anthropic endpoint)
curl https://api.qcode.cc/v1/models -H "Authorization: Bearer cr_your_qcode_key"

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

## 5. بررسی اتصال

```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"}]}'
```

سپس اجرا کنید:

```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` کهنه به‌ندرت علت است؛ بسیار بیشتر اوقات اولویت اعتبارنامه‌ها است (پیکربندی ذخیره‌شده / کی‌رینگ بر متغیرهای محیطی اولویت دارد) یا یک `.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) — کدام مدل برای کدام کار
- [DeepSeek Harness (dsh)](/docs/ide/deepseek-harness) — یک هارنس عامل با فرم API مدل سفارشی