# راه‌اندازی Droid (Factory)

> **آخرین بازبینی**: 2026-09-18 · 📄 بر پایه مستندات رسمی (Droid CLI v0.222.0 منتشر شده در 2026-09-18؛ انتشارهای پرتکرار — به `droid --version` اعتماد کنید)

## در یک نگاه

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (`provider: "anthropic"`) · GPT ✅ · مدل‌های چینی ✅ (`provider: "generic-chat-completion-api"`) · Gemini ❌ (چنین ارائه‌دهنده‌ای در Droid وجود ندارد) |
| پروتکل و Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI Chat: `https://api.qcode.cc/openai/v1` |
| محل پیکربندی | `~/.factory/settings.json` (در نخستین اجرای `droid` به‌صورت خودکار ساخته می‌شود) |
| مستندات رسمی | [BYOK](https://docs.factory.ai/model-independence/byok) · [settings](https://docs.factory.ai/droid-cli/settings)

[Droid](https://docs.factory.ai/droid-cli/overview) عامل کدنویسی ترمینالی با هوش مصنوعی از Factory است. از **مدل‌های سفارشی BYOK** پشتیبانی می‌کند، بنابراین QCode.cc را می‌توان به‌عنوان یک مدل سفارشی افزود.

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

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

| مدلی که می‌خواهید | `provider` | `baseUrl` |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT / چهار خانواده چینی | `generic-chat-completion-api` (سازگار با Chat-Completions) | `https://api.qcode.cc/openai/v1` |

> 🔴 `"provider": "openai"` را **ننویسید** — Factory آن را برای **OpenAI Responses API** رزرو کرده است («مگر اینکه API رسمی OpenAI یا Anthropic را فراخوانی می‌کنید، از provider: `"generic-chat-completion-api"` استفاده کنید»، [مستندات BYOK](https://docs.factory.ai/model-independence/byok)). GPT / مدل‌های چینی روی QCode با Chat Completions صحبت می‌کنند، پس `generic-chat-completion-api` را به کار ببرید.

## نصب

```bash
curl -fsSL https://app.factory.ai/cli | sh
```

در `~/.local/bin/droid` نصب می‌شود. اگر نصب‌کننده گزارش دهد که PATH پیکربندی نشده است، خطی که چاپ می‌کند را به `~/.zshrc` / `~/.bashrc` بیفزایید.

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

```bash
droid --version
```

## پیکربندی

فایل `~/.factory/settings.json` را ویرایش کنید (**در نخستین اجرای `droid` به‌صورت خودکار ساخته می‌شود**؛ فایل سطح پروژه `.factory/settings.local.json` هم کار می‌کند — روی آن ادغام می‌شود، یادتان باشد آن را در gitignore بگذارید):

```json
{
  "customModels": [
    {
      "model": "claude-sonnet-5",
      "displayName": "QCode Sonnet 5",
      "baseUrl": "https://api.qcode.cc/api",
      "apiKey": "${QCODE_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 8192
    },
    {
      "model": "claude-haiku-5-5",
      "displayName": "QCode Haiku 5.5",
      "baseUrl": "https://api.qcode.cc/api",
      "apiKey": "${QCODE_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 4096
    }
  ]
}
```

کلید را از طریق متغیر محیطی تزریق کنید:

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

| فیلد | معنا |
|-------|---------|
| `model` | شناسه مدلی که به API فرستاده می‌شود؛ باید دقیقاً با [qcode.cc/models](https://qcode.cc/models) مطابقت داشته باشد |
| `displayName` | برچسب در انتخاب‌گر مدل؛ متن آزاد |
| `baseUrl` | تا `/api` متوقف شوید؛ Droid خودش `/v1/messages` را می‌افزاید |
| `apiKey` | از ارجاع‌های محیطی `${VAR}` پشتیبانی می‌کند |
| `provider` | برای Claude: `anthropic` |
| `maxOutputTokens` | حداکثر خروجی در هر پاسخ |

> بر پایه مستندات Factory، **کلیدهای API محلی می‌مانند و به سرورهای Factory بارگذاری نمی‌شوند**.
> از سرزمین اصلی چین، میزبان را با `https://asia.qcode.cc/api` عوض کنید (نود آسیا، نزدیک‌ترین از کره / تایوان / هنگ‌کنگ).
## تأیید

```bash
droid exec --model "claude-sonnet-5" "reply with exactly: OK"
```

`OK` یعنی اتصال برقرار است.

**کنترل منفی** (برای اثبات اینکه پیکربندی واقعاً اعمال شده است): `baseUrl` را موقتاً روی مسیری قرار دهید که وجود ندارد و دوباره اجرا کنید — باید شکست بخورد. یک موفقیت به‌تنهایی ثابت نمی‌کند که از نقطه پایانی شما استفاده شده است.

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

```bash
# interactive
droid

# non-interactive
droid exec "run the tests and fix the failures"

# specific working directory
droid --cwd /path/to/project

# run inside a git worktree (isolated changes)
droid -w feature-x

# autonomy level
droid --auto medium
```

## عیب‌یابی

### `model_not_available_on_endpoint`

`provider` مقداری سازگار با OpenAI است در حالی که مدل متعلق به Claude است. `"provider": "anthropic"` را همراه با `baseUrl` = `https://api.qcode.cc/api` تنظیم کنید.

### 401 / شکست احراز هویت

`${QCODE_KEY}` بسط داده نشده است (متغیر به محیط صادر نشده است)، یا کلید فاصله اضافی دارد. بررسی کنید که `echo $QCODE_KEY` با `cr_` شروع شود.
تله دیگر: قرار دادن پیکربندی در فایل **قدیمی** `~/.factory/config.json` (فیلدهای snake_case) — به‌طور رسمی فایل قدیمی ارجاعات محیطی `apiKey` را بسط **نمی‌دهد**، بنابراین `${QCODE_KEY}` عیناً به‌عنوان کلید ارسال می‌شود. از `settings.json` استفاده کنید.

### مدل در فهرست انتخاب وجود ندارد

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

## مرتبط

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — جدول پروتکل × خانواده مدل
- [راه‌اندازی Crush](/docs/ide/crush) — یک عامل ترمینال دیگر
- [مدل‌های چینی](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen