# راه‌اندازی magpie با QCode: Claude Code و Codex

> **آخرین بررسی**: 2026-11-10 · 📄 بر اساس مستندات رسمی (2026-11-10) · ✅ دسترسی QCode با magpie 0.1.3533 آزمایش شد (2026-11-10؛ پیش‌تر با magpie 0.1.1677 در 2026-10-27، شامل Claude Code 2.1.311 و Codex CLI 0.164.0)

## در یک نگاه

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ از طریق نشانی `anthropic` · GPT ✅ از طریق `chat` / `responses` · مدل‌های چینی ✅ از طریق `anthropic` / `chat` · Gemini ❌: QCode سری Gemini را ارائه نمی‌دهد؛ از Claude، GPT یا یک مدل چینی استفاده کنید |
| سه نشانی | `anthropic`: `https://api.qcode.cc/api` · `chat`: `https://api.qcode.cc/openai/v1` · `responses`: `https://api.qcode.cc/openai` |
| محل پیکربندی | لینک واردکردن (برنامه دسکتاپ / لینک وب) · یک فرمان `magpie provider add` · بخش ارائه‌دهندگان برنامه → افزودن ارائه‌دهنده |
| مستندات رسمی | [usemagpie.ai](https://usemagpie.ai) · [مستندات](https://usemagpie.ai/docs/start) · [لینک‌های واردکردن](https://usemagpie.ai/docs/import) · [Docker](https://usemagpie.ai/docs/docker) · [مرجع](https://github.com/yetone/magpie/blob/main/docs/reference.md) |

## magpie چیست و چه تفاوتی با CC Switch دارد

magpie روی دستگاه شما یک دروازه اجرا می‌کند (`127.0.0.1:3425`). با APIهای OpenAI، Anthropic و Gemini صحبت می‌کند و میان آن‌ها ترجمه انجام می‌دهد، از جمله جریان‌سازی و فراخوانی ابزار. وقتی در magpie مدلی را برای یک عامل انتخاب می‌کنید، magpie آن مدل را در فایل پیکربندی خود عامل می‌نویسد. بنابراین Claude Code و Codex به دروازه محلی متصل می‌شوند؛ کلید QCode شما در magpie می‌ماند و دروازه هر درخواست را به QCode هدایت می‌کند.

تفاوت ساختاری با [CC Switch](/docs/ide/cc-switch) در یک جمله است: CC Switch نقطه پایانی و کلید را در پیکربندی خود هر کلاینت می‌نویسد و کلاینت مستقیماً به ارائه‌دهنده متصل می‌شود؛ magpie کلاینت را به یک دروازه محلی متصل می‌کند که درخواست‌ها را به مقصد ارسال می‌کند.

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

| فیلد magpie | معنای آن در magpie | مقدار QCode |
|---|---|---|
| `anthropic` | Base URL مربوط به Anthropic Messages، ریشه بدون `/v1` | `https://api.qcode.cc/api` |
| `chat` (در CLI با نام `url` خوانده می‌شود) | Base URL مربوط به OpenAI Chat Completions، با پایان `/v1` | `https://api.qcode.cc/openai/v1` |
| `responses` | Base URL مربوط به OpenAI Responses | `https://api.qcode.cc/openai` |

**Claude فقط از طریق `/api` ارائه می‌شود؛ نشانی‌های سازگار با OpenAI، Claude را ارائه نمی‌دهند.** اگر شناسه `claude-*` را به chat یا responses بفرستید، QCode مقدار `model_not_available_on_endpoint` را برمی‌گرداند؛ این بررسی پیش از احراز هویت اجرا می‌شود. GPT از هر دو مسیر OpenAI استفاده می‌کند و مدل‌های چینی روی هر دو chat و anthropic کار می‌کنند.

برای استفاده از نقطه دسترسی آسیا یا آمریکای شمالی، دامنه را با `asia.qcode.cc` یا `us.qcode.cc` جایگزین کنید؛ مسیرها ثابت می‌مانند. هر سه دامنه قابلیت‌های یکسانی دارند و فقط در مسیریابی شبکه تفاوت می‌کنند.

توصیف رسمی magpie از `responses` یک Base URL با پایان `/v1` است. برای QCode، مقدار `https://api.qcode.cc/openai` را وارد کنید (همان base_url در پیکربندی Codex مربوط به QCode). با magpie 0.1.3533 در 2026-11-10 آزمایش شد: خط responses در `magpie provider test qcode` با این نشانی موفق می‌شود؛ نشست‌های Codex از طریق آن با magpie 0.1.1677 در 2026-10-27 آزمایش شدند.
## نصب

نصب‌کننده رسمی:

```bash
curl -fsSL https://usemagpie.ai/install.sh | sh
```

نصب‌کننده دستور `magpie` را در `~/.local/bin` و برنامه را در جای درست آن قرار می‌دهد: `/Applications` روی Mac و منوی برنامه شما در Linux. روی Windows، فایل `magpie-windows-amd64.exe` (ARM: `magpie-windows-arm64.exe`) را از صفحه انتشار دانلود کنید؛ نسخه‌های مخصوص ترمینال با نام `magpie-cli-<os>-<arch>` نام‌گذاری شده‌اند، برای مثال `magpie-cli-windows-amd64.exe`. magpie روی macOS، Windows و Linux به‌صورت برنامه نوار منو، پنجره، TUI، رابط وب و CLI، و همچنین در Docker و روی Termux اجرا می‌شود.

روی Linux، اسکریپت برنامه دسکتاپ را نصب می‌کند؛ اگر دسکتاپی نباشد، نسخه ترمینال را نصب می‌کند، و `--gui` یا `--tui` انتخاب را انجام می‌دهد. پشت فایروال، نصب‌کننده و `magpie update` گزینه `--proxy` را می‌پذیرند، برای مثال:

```bash
curl -fsSL https://usemagpie.ai/install.sh \
  | sh -s -- --proxy http://127.0.0.1:7890
```

**حذف نصب.** دستور رسمی این است:

```bash
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --uninstall
```

عامل‌های شما را به وضعیت قبلی برمی‌گرداند، سپس چیزهایی را که اسکریپت نصب کرده حذف می‌کند. تنظیمات، ارائه‌دهنده‌ها و مصرف شما در `~/.config/magpie` برای نصب دوباره باقی می‌مانند؛ برای حذف آن‌ها هم `--purge` را اضافه کنید. اگر به روش دیگری نصب کرده‌اید، `magpie uninstall` یا تنظیمات → حذف magpie همان کاری را می‌کند که `--purge` می‌کند و خود برنامه را باقی می‌گذارد تا خودتان حذف کنید.

**Docker.** ایمیج `ghcr.io/yetone/magpie` است، برای یک سرور یا NAS؛ بخش کلیدهای دروازه، اشتراک‌گذاری و همگام‌سازی در ادامه به آن می‌پردازد.

## افزودن QCode

**گزینه A: لینک درون‌ریزی (برنامه دسکتاپ و وب)**

magpie انتظار دارد هر مقدار با URL کدگذاری شود. لینک QCode، بدون کلید، این است:

```
magpie://import?name=QCode&anthropic=https%3A%2F%2Fapi.qcode.cc%2Fapi&chat=https%3A%2F%2Fapi.qcode.cc%2Fopenai%2Fv1&responses=https%3A%2F%2Fapi.qcode.cc%2Fopenai&models=gpt-6.1-sol%2Cgpt-6.1-terra%2Cgpt-5.6-sol%2Cclaude-opus-5-5%2Cclaude-sonnet-5-5%2Cclaude-haiku-5-5&website=https%3A%2F%2Fqcode.cc&keys=https%3A%2F%2Fqcode.cc%2Fdashboard
```

در وب، از شکل قابل کلیک با همان پارامترها پس از `#` استفاده کنید (مرورگرها هرگز قطعه را به سرور نمی‌فرستند، و لینک وقتی magpie نصب نیست، دانلود را ارائه می‌دهد):

```
https://usemagpie.ai/import#name=QCode&anthropic=https%3A%2F%2Fapi.qcode.cc%2Fapi&chat=https%3A%2F%2Fapi.qcode.cc%2Fopenai%2Fv1&responses=https%3A%2F%2Fapi.qcode.cc%2Fopenai&models=gpt-6.1-sol%2Cgpt-6.1-terra%2Cgpt-5.6-sol%2Cclaude-opus-5-5%2Cclaude-sonnet-5-5%2Cclaude-haiku-5-5&website=https%3A%2F%2Fqcode.cc&keys=https%3A%2F%2Fqcode.cc%2Fdashboard
```

اگر کلیدی در لینک نباشد، کاربر کلید را در دیالوگ magpie جای‌گذاری می‌کند، همان‌طور که مستندات رسمی می‌گوید؛ تا زمانی که «Add» فشرده نشود، چیزی ذخیره نمی‌شود. در ترمینال، `magpie import` بدون کلید فقط نشان می‌دهد چه چیزی اضافه می‌شود و چیزی ذخیره نمی‌کند (آزمایش‌شده در 2026-10-27)، بنابراین کاربران ترمینال باید از گزینه B استفاده کنند. برای جایگزینی کلید یک ارائه‌دهنده ذخیره‌شده، `magpie provider key qcode cr_xxx` را اجرا کنید.

لینک‌های درون‌ریزی به magpie 0.1.8 یا جدیدتر نیاز دارند. پارامترهایی که یک لینک درون‌ریزی می‌پذیرد، همان‌طور که صفحه رسمی درون‌ریزی فهرست می‌کند:

| پارامتر | معنی (رسمی) |
|---|---|
| `name` یا `preset` | نامی که ارائه‌دهنده در magpie با آن خوانده می‌شود، حداکثر 80 کاراکتر؛ یک شناسه پیش‌تنظیم از نقاط پایانی‌ای استفاده می‌کند که magpie از قبل می‌شناسد |
| `chat` | Base URL مربوط به OpenAI Chat Completions که به `/v1` ختم می‌شود (magpie مسیر `/chat/completions` را اضافه می‌کند) |
| `responses` | Base URL مربوط به OpenAI Responses که به `/v1` ختم می‌شود |
| `anthropic` | Base URL مربوط به Anthropic Messages: ریشه، بدون `/v1` |
| `gemini` | Base URL مربوط به API Google Gemini که به `/v1beta` ختم می‌شود |
| `key` | کلید API کاربر؛ اگر آن را وارد نکنید، کاربر یکی را در دیالوگ جای‌گذاری می‌کند |
| `models` | شناسه‌های مدل برای ارائه به عامل‌ها، جداشده با کاما |
| `id` | شناسه‌ای که عامل‌ها در `id/model` استفاده می‌کنند؛ به‌طور پیش‌فرض همان نام است، با حروف کوچک و خط تیره |
| `catalog` | شناسه ارائه‌دهنده models.dev که فراداده آن اعمال می‌شود (نام‌های نمایشی، اندازه‌های پنجره زمینه، سطوح استدلال، قیمت‌ها) |
| `website`, `keys` | سایت شما، و صفحه‌ای که کاربران در آن کلید می‌سازند (https) |
| `icon` | تصویری از خودتان (https)، حداکثر 1 MB |
| `balance`, `balance_path`, `balance_method` | محلی که موجودی کلید از آن خوانده می‌شود، محلی که مبلغ در پاسخ JSON قرار دارد، و `GET` یا `POST` |
| `region` | هنگام استفاده از پیش‌تنظیمی که منطقه‌ها دارد، اینکه کدام منطقه |

بدون یک پیش‌تنظیم، دست‌کم یکی از `chat`، `responses`، `anthropic` و `gemini` لازم است. Base URL‌ها باید https باشند، به‌جز http ساده به localhost، نشانی‌های بازگشتی، نشانی‌های خصوصی و `*.local`. توصیه خود صفحه درون‌ریزی درباره کلیدها: یک صفحه عمومی مانند README هرگز نباید کلید داشته باشد؛ `key` را وارد نکنید تا کاربر کلید خودش را جای‌گذاری کند. لینک QCode بالا از همین توصیه پیروی می‌کند.

**گزینه B: یک دستور در ترمینال (آزمایش‌شده)**

```bash
magpie provider add QCode \
  anthropic=https://api.qcode.cc/api \
  url=https://api.qcode.cc/openai/v1 \
  responses=https://api.qcode.cc/openai \
  key=cr_xxx
```

آزمایش‌شده با magpie 0.1.3533 در 2026-11-10: این دستور ارائه‌دهنده را یک‌جا اضافه می‌کند (`✓ added QCode (qcode)`) و فهرست مدل‌ها را از QCode دریافت می‌کند؛ سپس `magpie provider qcode` نشانی‌های `chat`، `responses` و `anthropic` را نشان می‌دهد. `magpie providers` همه ارائه‌دهنده‌های شما را فهرست می‌کند.

**گزینه C: برنامه**

زبانه ارائه‌دهنده‌ها را باز کنید، دکمه «＋ Add provider» را فشار دهید، گزینه «Custom» را انتخاب کنید (برچسب رسمی: `Custom · any compatible URL`)، یک «Name» وارد کنید، یک Base URL سازگار با OpenAI (که به `/v1` ختم می‌شود) و/یا یک Base URL سازگار با Anthropic (ریشه) وارد کنید، سپس کلید را وارد کرده و ذخیره کنید.
## انتخاب مدل‌ها

```bash
magpie claude qcode/claude-sonnet-5-5        # main model
magpie claude opus qcode/claude-opus-5-5     # the opus slot in Claude Code
magpie codex qcode/gpt-6.1-sol               # Codex
magpie claude default                        # restore the previous Claude Code setup
magpie codex default                         # restore the previous Codex setup
```

magpie آدرس گیت‌وی محلی را در `~/.claude/settings.json` می‌نویسد (`ANTHROPIC_BASE_URL` برابر با `http://127.0.0.1:3425` است) به‌همراه توکن `magpie`؛ کلید QCode در magpie می‌ماند و در تنظیمات Claude Code نوشته نمی‌شود. تنظیم فقط مدل اصلی، جایگاه opus را نیز روی همان مدل تنظیم می‌کند؛ برای قرار دادن Opus در جایگاه opus، دستور `magpie claude opus qcode/claude-opus-5-5` را جداگانه اجرا کنید. magpie جایگاه haiku را به‌طور خودکار روی `qcode/claude-haiku-5-5` تنظیم می‌کند.

بدون `models=` هنگام افزودن ارائه‌دهنده، magpie فقط 24 مدل اول فهرست را نمایش می‌دهد (آزمایش‌شده با magpie 0.1.3533 در 2026-11-10: `24 exposed of 28`). مدل‌هایی را که می‌خواهید نمایش دهید با `magpie provider models qcode <id> <id> …` انتخاب کنید. بدون `+`، شناسه‌هایی که می‌دهید کل فهرست را جایگزین می‌کنند (خروجی می‌گوید `the ids given are now the whole list`)؛ `magpie provider models qcode +<model>` یک مدل اضافه می‌کند و بقیه را نگه می‌دارد. برای مثال:

```bash
magpie provider models qcode gpt-6.1-sol gpt-6.1-terra gpt-5.6-sol \
  claude-opus-5-5 claude-sonnet-5-5 claude-haiku-5-5
magpie provider models qcode +glm-5.3
magpie providers
```

شناسه‌های پیشنهادی: `gpt-6.1-sol`، `gpt-6.1-terra`، `gpt-5.6-sol`، `claude-opus-5-5`، `claude-sonnet-5-5` و `claude-haiku-5-5`؛ با یک شناسه GPT در ابتدا، `magpie provider test qcode` در هر سه خط ✓ نشان می‌دهد (به «بررسی» مراجعه کنید). مدل‌های قابل خرید در https://qcode.cc/models فهرست شده‌اند. صورت‌حساب بر اساس توکن است و قیمت هر مدل در https://qcode.cc/models فهرست شده است.

## بررسی

```bash
magpie healthcheck
magpie provider test qcode
```

`magpie healthcheck` تا زمانی که گیت‌وی پاسخ می‌دهد با کد 0 خارج می‌شود؛ وقتی هیچ گیت‌ویی در حال اجرا نیست، `magpie: no gateway at http://127.0.0.1:3425: …` را چاپ می‌کند و با کد 1 خارج می‌شود (آزمایش‌شده با magpie 0.1.3533 در 2026-11-10؛ این دستور کار می‌کند هرچند `magpie --help` آن را فهرست نمی‌کند). `magpie provider test qcode` برای chat، responses و anthropic هر کدام یک درخواست کوچک می‌فرستد و تأخیر را نشان می‌دهد.

وقتی یک مدل GPT اولین مدل فهرست باشد، مانند مثال بالا، هر سه خط ✓ نشان می‌دهند و دستور با کد 0 خارج می‌شود؛ خط anthropic خودش یک مدل Claude انتخاب می‌کند (آزمایش‌شده با magpie 0.1.3533 در 2026-11-10). وقتی اولین مدل یک مدل Claude باشد، خط‌های chat و responses با `400 · Model 'claude-haiku-5-5' is not available on this endpoint.` ✗ نشان می‌دهند و دستور با کد 1 خارج می‌شود. این رفتار QCode همان‌گونه است که طراحی شده: Claude فقط روی نقطه پایانی Anthropic Messages ارائه می‌شود، بنابراین ✓ در خط anthropic همچنان یعنی Claude کار می‌کند.

سپس در Claude Code عبارت «ping» را بفرستید و از Codex بخواهید یک فایل را بخواند. طبق آزمایش با magpie 0.1.1677 در 2026-10-27، درخواست‌های Claude از طریق magpie با یک اتصال مستقیم QCode مطابقت دارند، کش prompt طبق معمول کار می‌کند و Codex از Responses API استفاده می‌کند.
## magpie چه کلاینت‌هایی را می‌شناسد

README در magpie فهرست عامل‌هایی را ارائه می‌دهد که می‌تواند به آن‌ها متصل شود. مواردی که این سایت برایشان راهنمای راه‌اندازی دارد یا کاربران QCode درباره‌شان می‌پرسند عبارت‌اند از: Claude Code، Codex، OpenCode، ZCode، Qoder، CodeBuddy، WorkBuddy، Kimi Code، MiniMax Code، DeepSeek Harness و T3 Code (فهرست README بلندتر است). magpie فقط عامل‌های نصب‌شده روی ماشین شما را نشان می‌دهد و انتخاب یک مدل در magpie آن را در پیکربندی خودِ آن عامل می‌نویسد. مرجع فایلی را که هر کدام از طریق آن متصل می‌شود ارائه می‌دهد:

| کلاینت | مقصدی که magpie در آن می‌نویسد (بر اساس مرجع) |
|---|---|
| Claude Code | `~/.claude/settings.json` |
| Codex | `~/.codex/config.toml` |
| ZCode | `~/.zcode/v2/provider_config.json` و `config.json` |
| WorkBuddy | `~/.workbuddy/models.json` (نسخه بین‌المللی: `~/.workbuddy-ai/models.json`) |
| CodeBuddy | `~/.codebuddy/models.json` |
| Kimi Code | `~/.kimi/config.toml` |
| MiniMax Code | `~/.minimax/config.yaml` |
| Qoder (CLI) | `~/.qoder/settings.json` (مرجع اشاره می‌کند که به یک پلن Qoder با BYOK نیاز دارد) |

ردیف Kimi Code همان عبارت مرجع است؛ مستندات خودِ Kimi Code CLI فایل `~/.kimi-code/config.toml` را به‌عنوان فایل پیکربندی فعلی نام می‌برند (`~/.kimi/config.toml` متعلق به kimi-cli قدیمی‌تر بود)، به [Kimi Code](/docs/ide/kimi-code) مراجعه کنید.

راهنماهای این سایت: [Codex](/docs/ide/codex)، [ZCode](/docs/ide/zcode)، [Qoder](/docs/ide/qoder)، [CodeBuddy](/docs/ide/codebuddy)، [MiniMax Code](/docs/ide/minimax-code)، [Kimi Code](/docs/ide/kimi-code)، [DeepSeek Harness](/docs/ide/deepseek-harness)، [T3 Code](/docs/ide/t3code)، [WorkBuddy](/docs/ide/workbuddy) و [OpenCode](/docs/ide/opencode). هر چیز دیگری که Base URL دریافت می‌کند نیز می‌تواند از دروازه استفاده کند؛ README این متغیرها را ارائه می‌دهد:

```bash
export OPENAI_BASE_URL=http://127.0.0.1:3425/v1     OPENAI_API_KEY=magpie
export ANTHROPIC_BASE_URL=http://127.0.0.1:3425     ANTHROPIC_API_KEY=magpie
```

مدل‌های QCode در این کلاینت‌ها به‌صورت `qcode/<model id>` ظاهر می‌شوند. همان‌طور که در جدول پروتکل بالا آمده است، مدل‌های Claude روی آدرس `anthropic` و GPT روی `chat` / `responses` ارائه می‌شوند.

## مدل‌های بیش‌ازحد: گروه‌های مسیریابی

وقتی فهرست مدل‌ها طولانی می‌شود، یک گروه مسیریابی چند مدل را پشت یک نام قرار می‌دهد. مرجع رسمی آن را این‌گونه تعریف می‌کند: یک گروه چند مدل است که عامل آن‌ها را به‌عنوان یک واحد انتخاب می‌کند، `group/<id>`. نویسنده magpie در یک پاسخ در X در تاریخ 2026-11-05 کاربرد آن را این‌گونه توصیف کرد: در صفحه Routing یک گروه بسازید، مدل یکسان از هر ارائه‌دهنده را به آن اضافه کنید، در عامل فقط همان گروه را انتخاب کنید، و magpie بر اساس ترتیب، سرعت یا سهمیه جابه‌جا می‌شود؛ همچنین می‌توان یک ارائه‌دهنده را روی «only through routing groups» تنظیم کرد تا فهرست مدل‌ها مرتب بماند. مرجع آن سوئیچ را **Only through routing groups** می‌نامد: «برای نگه‌داشتن یک ارائه‌دهنده به‌طور کامل برای گروه‌ها، به‌جای آن از سوئیچ **Only through routing groups** آن استفاده کنید.»

از یک ترمینال، شکل دستور در مستندات رسمی `magpie group add "<name>" models=… routing=order` و سپس `magpie claude group/<id>` است. با مدل‌های QCode:

```bash
magpie group add "Daily coding" \
  models=qcode/claude-sonnet-5-5,qcode/claude-opus-5-5 routing=order
magpie claude group/daily-coding
```

حالت‌های مسیریابی شامل `order` («از اولین مدل استفاده کنید تا زمانی که نتواند پاسخ دهد، سپس مدل بعدی»)، `rotate` («در هر نوبت به عضو بعدی بروید») و `usage` («ابتدا از کم‌استفاده‌ترین عضو استفاده کنید») است. ما خودمان این مثال گروه را اجرا نکرده‌ایم؛ از نحو مستندشده پیروی می‌کند. مدل‌های Claude روی آدرس `anthropic` ارائه می‌شوند، بنابراین یک گروه برای Claude Code از مدل‌های Claude استفاده می‌کند.
## برای یک تیم یا چند کامپیوتر: کلیدهای Gateway، اشتراک‌گذاری در شبکه محلی، پشتیبان‌گیری و همگام‌سازی

**کلیدهای Gateway.** مستند مرجع می‌گوید که Gateway برای کلاینت‌ها کلید Gateway صادر می‌کند، جدا از کلیدهای API ارائه‌دهندگان شما. گزینه Settings → Network and sharing → Share on local network را روشن کنید، سپس Gateway → Gateway keys → Add gateway key را باز کنید و برای هر کلاینت یک کلید نام‌دار بسازید. از یک ترمینال:

```bash
magpie gateway-key add team-a
magpie gateway-key list
magpie gateway-key limit team-a week --tokens 2m --cost 5
magpie gateway-key models team-a qcode/*
```

هر کلید می‌تواند محدودیت خودش را داشته باشد (توکن، هزینه تخمینی، یا هر دو، به‌ازای روز، هفته یا ماه، یا هر N روز یا ساعت) و فهرست مدل‌های خودش را. پاسخ نویسنده در issue #1496 (بسته‌شده در 2026-10-12) اضافه می‌کند که مصرف به‌ازای هر کلید شمرده می‌شود: مسیر Usage → Overview → Gateway keys توکن‌ها و هزینه را به‌ازای کلید جمع می‌زند، در Usage → Requests می‌توان بر اساس کلید فیلتر کرد، و CSV خروجی ستون‌های `caller_key_id` و `caller_key_name` را دارد. کلید QCode داخل magpie می‌ماند؛ هم‌تیمی‌ها کلید Gateway می‌گیرند، نه کلید QCode.

**بررسی شخصی مصرف و چرخش کلید.** هم‌تیمی‌ای که کلید Gateway دارد می‌تواند در مرورگر نشانی `/me` را روی آدرسی که با آن به Gateway دسترسی دارد باز کند (برای مثال `http://192.168.1.10:3999/me`)، کلید خود را وارد کند و محدودیت‌های آن کلید، مصرفش در امروز، 7 و 30 روز، مدل‌هایی که می‌تواند از آن‌ها استفاده کند، و تنظیمات آماده کپی برای Claude Code، Codex و هر کلاینت سازگار با OpenAI را ببیند؛ صفحه هیچ چیز درباره کلیدها یا ارائه‌دهندگان دیگر نشان نمی‌دهد. مسیر Gateway → Gateway keys آن آدرس را همراه با دکمه Copy نشان می‌دهد، تا بتوانید آن را همراه کلیدها تحویل دهید. هر کلید Gateway را می‌توان جداگانه تغییر نام داد، غیرفعال کرد، چرخاند (rotate) یا حذف کرد: چرخش، نام، وضعیت فعال‌بودن، محدودیت‌ها و تاریخچه مصرف را نگه می‌دارد، و حذف یک کلید دسترسی راه دور آن را باطل می‌کند.

**magpie کامپیوتر دیگر.** مستند مرجع یک magpie را توصیف می‌کند که به چند کامپیوتر سرویس می‌دهد: آن را در شبکه به اشتراک بگذارید، سپس روی هر کامپیوتر دیگر آن را به‌عنوان magpie راه دور اضافه کنید، برای مثال `magpie provider add remote-magpie sk-magpie-… url=http://192.168.1.20:3425 id=office`. magpie خودِ هر کامپیوتر همچنان عامل‌های خودش را متصل می‌کند.

**Docker.** برای یک سرور یا NAS، صفحه رسمی [Docker](https://usemagpie.ai/docs/docker) ایمیج `ghcr.io/yetone/magpie` و پورت‌های 3425 (Gateway که عامل‌ها فراخوانی می‌کنند) و 3430 (رابط کاربری مرورگر) را معرفی می‌کند. درخواستی که از بیرون کانتینر می‌آید باید یک کلید Gateway فعال همراه داشته باشد، و درخواست بدون آن 401 می‌گیرد. با `docker exec magpie magpie gateway-key add "Docker client"` یک کلید بسازید.

**پشتیبان‌گیری و همگام‌سازی.** فرمان‌های مستند مرجع:

```bash
magpie backup                               # asks for a passphrase twice
magpie backup --no-keys ~/b.magpie-backup   # no API keys in it
magpie restore magpie.magpie-backup         # on the other machine
```

فایل روی دستگاه شما رمزنگاری می‌شود (AES-256-GCM، کلید با PBKDF2-SHA256 از عبارت عبور مشتق می‌شود). مسیر Settings → Sync and backup همان پشتیبان را روی یک پوشه WebDAV (مستند مرجع از جمله Nextcloud و Synology را نام می‌برد)، یک باکت S3 یا یک مخزن خصوصی GitHub نگه می‌دارد و تا زمانی که Gateway در حال اجراست، هر 3 دقیقه همه دستگاه‌ها را به‌روز می‌کند؛ سرور هرگز جز متن رمزشده چیزی ذخیره نمی‌کند. در issue #28 (بسته‌شده در 2026-09-25) نویسنده نوشت که همگام‌سازی WebDAV در v0.1.76 اضافه شد و همان عبارت عبور روی کامپیوترهای دیگر استفاده می‌شود. تنظیمات پروکسی و اندازه پنجره برای هر کامپیوتر جداگانه می‌ماند.
## مهاجرت از CC Switch

README می‌گوید **واردکردن** ارائه‌دهنده‌ها را از CC Switch، Claude Code، Codex و Alma وارد می‌کند، و صفحه شروع رسمی می‌گوید واردکردن… فایل `settings.json` مربوط به Claude Code و `config.toml` مربوط به Codex را می‌خواند، هیچ تغییری در آن‌ها ایجاد نمی‌کند، و ارائه‌دهنده‌هایی را که تیک می‌زنید منتقل می‌کند. در یک پاسخ در X در 2026-11-09، نویسنده magpie نوشت که پیکربندی CC Switch با یک کلیک وارد می‌شود و استفاده از هر دو با هم هم کار می‌کند. چون QCode را با سه نشانی بالا اضافه می‌کنید، افزودن دوباره آن از طریق لینک واردکردن هم به‌همان سرعت است.

یک نکته درباره تاریخچه Codex: ایشو #887 (بسته‌شده در 2026-10-14) توضیح می‌داد که پس از مهاجرت به magpie، فهرست تاریخچه Codex دیگر نشست‌هایی را که زیر ارائه‌دهنده CC Switch ساخته شده بودند نشان نمی‌داد (فایل‌ها هنوز آنجا بودند) و خواستار مهاجرت دستی شده بود. پاسخ نویسنده: در v0.1.999 (2026-10-05)، نشست‌ها → Codex نشست‌های ساخته‌شده زیر ارائه‌دهنده دیگر را فهرست می‌کند، **انتقال به magpie…** فقط نشانگر ارائه‌دهنده را پس از پشتیبان‌گیری از فایل‌ها تغییر می‌دهد، و **واگرد** آن‌ها را بازمی‌گرداند؛ نویسنده افزود که این نسخه هنوز روی یک تاریخچه واقعی CC Switch اجرا نشده بود. برای راهنمای گام‌به‌گام، [مهاجرت از CC Switch به magpie](https://qcode.cc/en/magpie-migrate-from-cc-switch) را ببینید؛ برای مقایسه کنار به کنار، [magpie در برابر CC Switch: چگونه انتخاب کنیم](https://qcode.cc/en/magpie-vs-cc-switch) را ببینید.

## پرسش‌های متداول

### مدل را عوض کردم، اما عامل من هنوز از مدل قبلی استفاده می‌کند

یک نشست در حال اجرا همان چیزی را نگه می‌دارد که با آن شروع شده است. نشست جدیدی شروع کنید؛ برای Codex، برنامه Codex را هم دوباره راه‌اندازی کنید. این پاسخ رسمی در راهنمای شروع است.

### چگونه magpie را حذف نصب کنم؟

`curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --uninstall` را اجرا کنید؛ عامل‌های شما را به وضعیت پیش از حذف برنامه بازمی‌گرداند و سپس برنامه را حذف می‌کند. تنظیمات شما در `~/.config/magpie` باقی می‌ماند مگر اینکه `--purge` را اضافه کنید. جزئیات در بخش نصب آمده است.

### وقتی درگاه در حال اجرا نیست، Claude Code نمی‌تواند متصل شود

ابتدا `magpie healthcheck` را اجرا کنید: کد خروج 0 یعنی درگاه پاسخ می‌دهد، و کد خروج 1 همراه با `magpie: no gateway at http://127.0.0.1:3425` یعنی درگاه در حال اجرا نیست. درگاه همراه با برنامه اجرا می‌شود، و بستن پنجره آن را در نوار منو یا سینی سیستم باقی می‌گذارد. همچنین می‌توانید برای اجرای فقط درگاه، `magpie serve` را اجرا کنید، یا `magpie daemon install` را اجرا کنید تا آن را به‌عنوان سرویس نگه دارید (systemd در Linux، launchd در macOS).

### آیا خطوط 400 برای chat و responses در `magpie provider test qcode` به‌معنای پیکربندی اشتباه است؟

نه، تا زمانی که خط anthropic ✓ باشد. وقتی اولین مدل در فهرست یک مدل Claude باشد، آزمون آن را به chat و responses هم می‌فرستد و QCode به‌طور عمدی آن را آنجا رد می‌کند، چون مدل‌های Claude فقط روی نقطه پایانی Anthropic Messages ارائه می‌شوند. یک مدل GPT را اول قرار دهید، مانند `magpie provider models qcode gpt-6.1-sol …` در بالا (شناسه‌هایی که می‌دهید کل فهرست را تشکیل می‌دهند)، و هر سه خط ✓ می‌شوند.

### چرا فقط برخی از مدل‌ها را می‌بینم؟

بدون `models=` در زمان افزودن، magpie فقط 24 مدل اول را در دسترس قرار می‌دهد (`24 exposed of 28` در 2026-11-10). `magpie provider models qcode <id> …` فهرست را با شناسه‌هایی که می‌دهید جایگزین می‌کند، `magpie provider models qcode +<model>` یکی را اضافه می‌کند و بقیه را نگه می‌دارد، و `magpie providers` نشان می‌دهد هر ارائه‌دهنده چند مدل را در دسترس قرار می‌دهد. فهرست مدل‌های موجود برای فروش در https://qcode.cc/models است.

### چگونه پیکربندی قبلی Claude Code را بازگردانم؟

`magpie claude default` را اجرا کنید، یا در انتخاب‌گر یکی از مدل‌های خود عامل را انتخاب کنید. magpie آنچه را نوشته است حذف می‌کند و مقادیری را که جایگزین کرده بود بازمی‌گرداند.

### چگونه سطح تلاش استدلال Codex را تغییر دهم؟

از `magpie codex effort <level>` استفاده کنید، برای مثال `magpie codex effort high`؛ `magpie codex effort` مقدار فعلی را نشان می‌دهد. یک سطح تنها هم کار می‌کند، برای مثال `magpie codex xhigh`.

### ماسک‌سازی حریم خصوصی چیست و آیا به‌طور پیش‌فرض فعال است؟

به‌طور پیش‌فرض خاموش است؛ آن را در تنظیمات → حریم خصوصی روشن کنید. کلیدهای API، کلیدهای خصوصی، توکن‌ها، ایمیل‌ها، و شماره‌های کارت و شناسه‌هایی که چک‌سامشان درست باشد، پیش از آنکه درخواستی از دستگاه شما خارج شود به جای‌نگهدارهایی مانند `{{API_KEY_k3v9x2mq}}` تبدیل می‌شوند و در پاسخ بازگردانده می‌شوند؛ مقادیر فقط در حافظه نگه داشته می‌شوند.

### چگونه شمارش مصرف ناشناس را خاموش کنم؟

گزینه مرا به‌عنوان کاربر بشمار را در تنظیمات → حریم خصوصی خاموش کنید، یا `DO_NOT_TRACK=1` / `MAGPIE_NO_STATS=1` را تنظیم کنید. نسخه منتشرشده magpie روزی یک بار یک دسته ناشناس می‌فرستد که شامل شناسه‌ای تصادفی است که روی رایانه شما ساخته می‌شود، به‌همراه نسخه و سیستم آن و شناسه‌های داخلی عامل‌ها، ارائه‌دهنده‌ها و مدل‌هایی که با آن‌ها به کار می‌رود.
## مرتبط

- [CC Switch](/docs/ide/cc-switch): ابزاری دسکتاپ که نقطه پایانی و کلید را در پیکربندی هر کلاینت می‌نویسد
- [Codex](/docs/ide/codex): فرم Responses در `~/.codex/config.toml`
- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths): سه پروتکل و سه دامنه دسترسی
- [متغیرهای محیطی](/docs/getting-started/environment): نحوه استفاده از `ANTHROPIC_BASE_URL` و متغیرهای مشابه