# راه‌اندازی Crush

> **آخرین بازبینی**: 2026-09-18 · 📄 بر اساس مستندات رسمی (Crush v0.95.0، منتشرشده در 2026-09-16)

## نگاه کلی

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (`type: anthropic`) · GPT ✅ · مدل‌های چینی ✅ (`openai-compat`) · Gemini ❌ (هیچ مسیر Gemini در اینجا مستند نشده است) |
| پروتکل و Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| محل پیکربندی | سطح پروژه `crush.json` / سطح کاربر `~/.config/crush/crush.json` |
| مستندات رسمی | [charmbracelet/crush](https://github.com/charmbracelet/crush)

[Crush](https://github.com/charmbracelet/crush) عامل کدنویسی با هوش مصنوعی و ترمینال‌محور Charm است (نوشته‌شده با Go). از **ارائه‌دهنده‌های سفارشی** پشتیبانی می‌کند، بنابراین QCode.cc را می‌توان به‌عنوان یک ارائه‌دهنده پیکربندی کرد.

> **یادداشت نام‌گذاری**: مخزن در ابتدا `charmbracelet/opencode` بود و اکنون `crush` است (URL قدیمی با کد 301 تغییر مسیر می‌دهد؛ نگه‌دارندگان هرگز دلیل آن را اعلام نکردند). این پروژه‌ای **متفاوت** از [OpenCode](/docs/ide/opencode) (opencode.ai) است — و توجه کنید که Crush یک ارائه‌دهنده مدل داخلی به نام `opencode` هم دارد، که آن هم چیز دیگری از سمت Charm است و نباید با آن اشتباه شود.

## کدام پروتکل

ارائه‌دهنده‌های سفارشی Crush مقادیر `anthropic` و `openai-compat` را به‌عنوان `type` می‌پذیرند. **برای Claude از `anthropic` استفاده کنید** — نقطه پایانی OpenAI در QCode مدل‌های Claude را نمی‌پذیرد (به [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) مراجعه کنید).

| مدل موردنظر | `type` | `base_url` |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT / چهار خانواده چینی | `openai-compat` | `https://api.qcode.cc/openai/v1` |

## نصب

```bash
# Homebrew
brew install charmbracelet/tap/crush

# or download a prebuilt binary from Releases
# https://github.com/charmbracelet/crush/releases
```

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

```bash
crush --version
```

## پیکربندی

فایل `crush.json` را در ریشه پروژه یا در سطح کاربر در `~/.config/crush/crush.json` بسازید (= `$XDG_CONFIG_HOME/crush/crush.json`؛ توجه کنید که `~/.local/share/crush/` فایل‌های وضعیتی را نگه می‌دارد که مستندات رسمی می‌گوید نباید ویرایش شوند). نسخه‌های جدیدتر قالب `crushrc` (Bash DSL) را نیز معرفی می‌کنند؛ پیکربندی JSON همچنان خوانده می‌شود:

```json
{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "qcode": {
      "type": "anthropic",
      "base_url": "https://api.qcode.cc/api",
      "api_key": "$QCODE_KEY",
      "extra_headers": { "anthropic-version": "2023-06-01" },
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "QCode Sonnet 5",
          "cost_per_1m_in": 2,
          "cost_per_1m_out": 10,
          "context_window": 1000000,
          "default_max_tokens": 8192,
          "cost_per_1m_in_cached": 0.2,
          "cost_per_1m_out_cached": 2.5,
          "can_reason": true,
          "supports_attachments": true
        },
        {
          "id": "claude-haiku-5-5",
          "name": "QCode Haiku 5.5",
          "cost_per_1m_in": 0.1,
          "cost_per_1m_out": 0.5,
          "context_window": 1000000, "default_max_tokens": 4096,
          "cost_per_1m_in_cached": 0.01,
          "cost_per_1m_out_cached": 0.125,
          "can_reason": true,
          "supports_attachments": true
        }
      ]
    }
  }
}
```

کلید را از طریق محیط تزریق کنید، نه با نوشتن آن در فایل:

```bash
export QCODE_KEY="cr_your_qcode_key"
```

| فیلد | معنا |
|-------|---------|
| `type` | `anthropic` پروتکل بومی Messages را انتخاب می‌کند |
| `base_url` | در `/api` متوقف شوید — **Crush خودش `/v1/messages` را اضافه می‌کند** |
| `api_key` | از بسط متغیر محیطی `$VAR` پشتیبانی می‌کند |
| `extra_headers` | پروتکل Anthropic به `anthropic-version` نیاز دارد |
| `models[]` | فهرست‌کردن مدل‌ها به شما امکان می‌دهد پارامترهای هزینه / زمینه را بازنویسی کنید؛ اگر آن را حذف کنید، Crush از طریق `<base>/v1/models` به‌صورت خودکار کشف می‌کند (`discover_models` به‌طور پیش‌فرض روشن است). هر `id` باید کاراکتر به کاراکتر با [qcode.cc/models](https://qcode.cc/models) مطابقت داشته باشد |

> **از سرزمین اصلی چین**، میزبان را با `https://asia.qcode.cc/api` عوض کنید (گره آسیا، نزدیک‌ترین از کره / تایوان / هنگ‌کنگ)؛ کلید تغییری نمی‌کند.
> `cost_per_1m_*` (شامل دو کلید `*_cached` که طرح‌واره رسمی الزام می‌کند) فقط بر نمایش برآورد مصرف خود Crush اثر می‌گذارد، نه بر صورت‌حساب واقعی — اعداد نمونه از یک نسبت کش معمول پیروی می‌کنند؛ آن‌ها را با نرخ‌های واقعی کش در [qcode.cc/models](https://qcode.cc/models) تنظیم کنید.
## تأیید

```bash
crush run "reply with exactly: OK"
```

دریافت `OK` به معنای برقراری اتصال است.

**برای اثبات این‌که ترافیک واقعاً به QCode می‌رود**، عمداً `base_url` را به مسیری تنظیم کنید که وجود ندارد و دوباره اجرا کنید. باید یک خطای 404 صریح ببینید که URL کامل را بازتاب می‌دهد:

```text
404 Not Found {"error":"Not Found","message":"Route /api/xxx/v1/messages not found"}
```

این خطا اثبات می‌کند که Crush در حال ساختن `base_url + /v1/messages` است و پیکربندی شما اعمال شده است. (این یک کنترل منفی است: موفقیت به‌تنهایی اثبات نمی‌کند که از ارائه‌دهنده شما استفاده شده است — ممکن است Crush به ارائه‌دهنده دیگری بازگشته باشد.)

## استفاده روزمره

```bash
# interactive
crush

# non-interactive
crush run "make this function async"

# pipes
cat README.md | crush run "make this clearer" > README.new.md

# specific directory with debug logging
crush --debug --cwd /path/to/project

# auto-accept every permission (use with care)
crush --yolo
```

## عیب‌یابی

### `model_not_available_on_endpoint`

مقدار `type` برابر `openai-compat` است در حالی که مدل از خانواده Claude است. به `type: "anthropic"` با `base_url` = `https://api.qcode.cc/api` تغییر دهید.

### 401 کلید API نامعتبر

متغیر محیطی تزریق نشده است، یا کلید دارای فاصله اضافی است. بررسی کنید که خروجی `echo $QCODE_KEY` با `cr_` شروع شود.

### مدل در فهرست انتخاب نمایش داده نمی‌شود

Crush فقط مدل‌هایی را نمایش می‌دهد که به‌صراحت در `models[]` فهرست شده باشند. یک ورودی اضافه کنید و برنامه را دوباره راه‌اندازی کنید.

## مطالب مرتبط

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — جدول پروتکل × خانواده مدل
- [یکپارچه‌سازی OpenCode](/docs/ide/opencode) — یک عامل ترمینالی دیگر (نه همان پروژه)
- [مدل‌های چینی](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen
- [راه‌اندازی ارائه‌دهنده Goose](/docs/ide/goose) — یک عامل ترمینالی دیگر؛ آدرس‌ها از طریق `goose configure` در `ANTHROPIC_HOST` / `OPENAI_HOST` قرار می‌گیرند