# راه‌اندازی ارائه‌دهنده Goose

> **آخرین بازبینی**: 2026-11-12 · 📄 بر اساس مستندات رسمی (goose v1.54.0، نسخه‌ای که بقیه این صفحه در 2026-10-13 بر اساس آن نوشته شده است؛ فهرست مدل‌های Claude در ادامه در 2026-11-12 دوباره با مستندات مدل Anthropic بررسی شد)

## در یک نگاه

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ از طریق ارائه‌دهنده `Anthropic` · GPT ✅ و مدل‌های چینی ✅ از طریق سمت سازگار با OpenAI · Gemini ❌ — QCode سری Gemini را ارائه نمی‌دهد، لطفاً از Claude، GPT یا یک مدل چینی استفاده کنید |
| پروتکل و Base URL | Anthropic Messages: `https://api.qcode.cc/api` · OpenAI Chat Completions: `https://api.qcode.cc/openai/v1` |
| محل پیکربندی | `goose configure` در ترمینال، goose Desktop → تنظیمات → مدل‌ها، یا متغیرهای محیطی (`ANTHROPIC_HOST`، `OPENAI_HOST`، `OPENAI_BASE_PATH`، `GOOSE_PROVIDER__HOST`) |
| مستندات رسمی | [goose-docs.ai — پیکربندی ارائه‌دهنده LLM](https://goose-docs.ai/docs/getting-started/providers) |

goose خود را «عامل هوش مصنوعی متن‌باز بومی شما — اپلیکیشن دسکتاپ، CLI و API» توصیف می‌کند. اکنون پروژه‌ای از Agentic AI Foundation است، بنابراین مستندات در `goose-docs.ai` قرار دارد (نشانی پیشین `block.github.io/goose` فقط تغییرمسیر می‌دهد) و مخزن `aaif-goose/goose` است، در حالی که فرمول Homebrew هنوز `block-goose-cli` نامیده می‌شود. نسخه ارجاع‌شده در این صفحه انتشار پایدار `v1.54.0` است که در 2026-10-08 منتشر شد.

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

| مدل‌هایی که می‌خواهید | ارائه‌دهنده goose / نوع API | نقطه پایانی‌ای که وارد می‌کنید |
|---|---|---|
| Claude | ارائه‌دهنده داخلی `Anthropic` (`ANTHROPIC_HOST`)، یا یک ارائه‌دهنده سفارشی که نوع API آن `Anthropic Compatible` است | `https://api.qcode.cc/api` |
| GPT و مدل‌های چینی | ارائه‌دهنده داخلی `OpenAI` (`OPENAI_HOST` + `OPENAI_BASE_PATH`)، یا یک ارائه‌دهنده سفارشی که نوع API آن `OpenAI Compatible` است | `https://api.qcode.cc/openai/v1` (مسیر درخواست `/openai/v1/chat/completions` است) |

**هرگز Claude را از طریق نقطه پایانی سازگار با OpenAI فراخوانی نکنید.** QCode شناسه‌های `claude-*` را فقط در سمت Anthropic Messages ارائه می‌دهد؛ سمت OpenAI آن‌ها را رد می‌کند (`model_not_available_on_endpoint`). دو ارائه‌دهنده را به‌جای یکی نگه دارید و برای هر نشست با `goose run --provider … --model …` انتخاب کنید. جزئیات: [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths).

**نام فیلد HOST است، نه base_url.** goose از شما `ANTHROPIC_HOST`، `OPENAI_HOST` و `GOOSE_PROVIDER__HOST` را می‌خواهد. فقط میزبان به‌همراه پیشوند مسیر را وارد کنید — `/v1/messages` را در فیلد ننویسید. در سمت OpenAI، مسیر درخواست یک فیلد مستندشده جداگانه است: جدول رسمی `OPENAI_BASE_PATH` را چنین توصیف می‌کند: "Request path appended to the host (defaults to v1/chat/completions)". مستندات رسمی به‌روشنی بیان نمی‌کند که `ANTHROPIC_HOST` چگونه با مسیر messages ترکیب می‌شود؛ بنابراین این صفحه فقط مقدار QCode را بیان می‌کند و هیچ ادعایی به‌عنوان اندازه‌گیری‌شده ندارد.
## نصب

CLI، با Homebrew یا اسکریپت رسمی:

```bash
brew install block-goose-cli

# or
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

goose update
goose --version
```

دسکتاپ: در macOS از Homebrew یا دکمه‌های دانلود استفاده کنید؛ در Linux صفحه رسمی بسته‌های `.deb`، `.rpm` و Flatpak را ارائه می‌دهد:

```bash
brew install --cask block-goose
```

## پیکربندی Claude (ارائه‌دهنده Anthropic)

مسیر تعاملی از prompt‌های رسمی پیروی می‌کند:

```bash
goose configure
# Configure Providers (Change provider or update credentials)  -> choose Anthropic
# Provider Anthropic requires ANTHROPIC_API_KEY, please enter a value  -> your QCode key
# Enter your desired ANTHROPIC_HOST or press Enter to use the default.  -> https://api.qcode.cc/api
```

متغیرهایی که صفحه رسمی متغیرهای محیطی آن‌ها را زیر نقاط پایانی سفارشی گروه‌بندی می‌کند، بدون ویزارد همان کار را انجام می‌دهند:

```bash
export GOOSE_PROVIDER="anthropic"
export GOOSE_MODEL="claude-sonnet-5"
export GOOSE_PROVIDER__TYPE="anthropic"
export GOOSE_PROVIDER__HOST="https://api.qcode.cc/api"
export GOOSE_PROVIDER__API_KEY="cr_your_qcode_key"
```

در `config.yaml` (در macOS/Linux: `~/.config/goose/config.yaml`) تنظیمات ارائه‌دهنده در کلیدهای `active_provider` و `providers` قرار دارند:

```yaml
active_provider: anthropic
providers:
  anthropic:
    enabled: true
    model: claude-sonnet-5
    configured: true
```

- کلید در آن فایل قرار نمی‌گیرد: مستندات رسمی اعلام می‌کنند "Provider API keys do not go in config.yaml". آن را از طریق `goose configure` در مخزن کلید، در `secrets.yaml` یا در متغیر محیطی ارائه‌دهنده نگه دارید.
- گره‌های منطقه‌ای: میزبان را با `https://asia.qcode.cc/api` یا `https://us.qcode.cc/api` جایگزین کنید. همان کلید کار می‌کند.
- شناسه‌های Claude موجود در QCode: `claude-sonnet-5`، `claude-sonnet-5-5`، `claude-opus-5`، `claude-opus-5-5`، `claude-haiku-5-5`، `claude-sonnet-4-6`، `claude-fable-5-2`، `claude-fable-5-1`، `claude-fable-5`. به‌ازای هر توکن صورت‌حساب می‌شود؛ نرخ‌های هر مدل در https://qcode.cc/models فهرست شده‌اند
- `claude-fable-5-2` همان Claude Fable 5.2 است که در 2026-11-09 منتشر شده و Fable کنونی در QCode است؛ نسخه قبلی `claude-fable-5-1` همچنان به فروش می‌رسد. این مدل روی همان نقطه پایانی Anthropic Messages با پنجره زمینه 1M توکن و حداکثر خروجی 128K ارائه می‌شود؛ بنابراین در سمت goose فقط مقدار مدل تغییر می‌کند: `export GOOSE_MODEL="claude-fable-5-2"`.
## پیکربندی GPT و مدل‌های چینی (سازگار با OpenAI)

ارائه‌دهنده داخلی OpenAI «می‌تواند به API رسمی OpenAI (api.openai.com) یا هر نقطه پایانی سازگار با OpenAI متصل شود»، و راهنمای رسمی برای چنین دروازه‌ای این است که «OPENAI_HOST را روی ریشه پراکسی خود تنظیم کنید (بدون مسیر انتهایی) و OPENAI_BASE_PATH را روی مسیری که سرو می‌کند (معمولاً v1/chat/completions) تنظیم کنید»:

```bash
export OPENAI_API_KEY="cr_your_qcode_key"
export OPENAI_HOST="https://api.qcode.cc"
export OPENAI_BASE_PATH="openai/v1/chat/completions"
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="gpt-6.1-sol"
```

راه جایگزین این است که مسیر پیش‌فرض مستندشده را نگه دارید و پیشوند را به میزبان منتقل کنید، `export OPENAI_HOST="https://api.qcode.cc/openai"`، و `OPENAI_BASE_PATH` را روی `v1/chat/completions` باقی بگذارید. در هر دو حالت، درخواست به URL نقطه پایانی مستندشده `https://api.qcode.cc/openai/v1/chat/completions` ارسال می‌شود.

### به‌عنوان ارائه‌دهنده سفارشی نام‌دار

`goose configure` را اجرا کنید، **Custom Providers** را انتخاب کنید، سپس **Add A Custom Provider** (متن خط منو «Add a new OpenAI/Anthropic/Ollama compatible Provider» است):

| Prompt | چه چیزی وارد کنید |
|---|---|
| API Type | `OpenAI Compatible (most common)` |
| Name | هر نامی که می‌خواهید، مثلاً `qcode` |
| API URL | `https://api.qcode.cc/openai/v1/chat/completions` — مستندات رسمی این prompt را «Base URL نقطه پایانی API» توصیف می‌کنند، و مثال JSON برای همان فیلد شامل مسیر کامل درخواست است |
| Authentication Required | بله، سپس یک کلید API ثابت |
| Available Models | فهرست نام مدل‌ها که با کاما جدا شده‌اند، مثلاً `gpt-6.1-sol,gpt-5.6-terra,gpt-5.5,deepseek-v4.1-flash,glm-5.3,kimi-k3` |
| Streaming Support | فعال |

ارائه‌دهنده کلید خود را از متغیر محیطی‌ای می‌خواند که به آن اختصاص داده‌اید. در عبارت رسمی، «سپس از api_key_env برای تنظیم کلید نشست خود استفاده کنید»، با مثال مستندشده:

```bash
export CUSTOM_CORP_API_API_KEY="your-api-key"
goose session start --provider custom_corp_api
```

از نام ارائه‌دهنده و متغیر کلید خودتان به‌جای `custom_corp_api` / `CUSTOM_CORP_API_API_KEY` استفاده کنید. اگر ترجیح می‌دهید فایل JSON را خودتان بنویسید، آن را در `macOS/Linux: ~/.config/goose/custom_providers/` قرار دهید. به دو نکته توجه کنید: «ارائه‌دهندگان سفارشی باید از قالب‌های API سازگار با OpenAI، Anthropic یا Ollama استفاده کنند.» و مثال‌های رسمی فقط `"engine": "openai"` را نشان می‌دهند — مستندات هیچ مقداری برای سمت Anthropic منتشر نمی‌کنند، بنابراین ارائه‌دهندگان سفارشی سازگار با Anthropic را از طریق `goose configure` بسازید و بگذارید goose همان خط را بنویسد.

شناسه‌های مدل چینی در QCode شامل `deepseek-v4.1-flash`، `deepseek-v4-flash`، `deepseek-v4-pro`، `glm-5.3`، `glm-5.2`، `qwen3.8-max`، `qwen3.8-flash`، `qwen3.7-plus`، `kimi-k3` است — به [مدل‌های چینی](/docs/usage/cn-models) مراجعه کنید.
## بررسی

```bash
goose info
goose run --provider anthropic --model claude-sonnet-5 -t "ping"
```

توضیح `goose info` چنین است: «Shows goose information, including the version, configuration file location, session storage, and logs.» در `goose run`، `--provider` یعنی «Specify the provider to use for this session (overrides environment variable)» و `--model` یعنی «Specify the model to use for this session (overrides environment variable)».

پیش از عیب‌یابی خود goose، نقطه پایانی را تأیید کنید:

```bash
KEY="cr_your_qcode_key"
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"}]}'
```

بدنه JSON حاوی `content` یعنی سمت نقطه پایانی پاسخ داده است و مشکل باقی‌مانده در تنظیمات goose است. این صفحه از مستندات رسمی ساخته شده است؛ کلید آزمایشی وجود نداشت، بنابراین هیچ درخواستی در اینجا با QCode آزمایش نشد.

## عیب‌یابی / محدودیت‌های شناخته‌شده

| نشانه یا محدودیت | آنچه مستندات رسمی می‌گوید و راه‌حل |
|---|---|
| شناسه مدل شما در فهرست `goose configure` ارائه نمی‌شود | «goose configure از وارد کردن نام مدل سفارشی پشتیبانی نمی‌کند. برای استفاده از مدلی که در فهرست ارائه‌دهنده نیست، از goose Desktop استفاده کنید یا متغیر GOOSE_MODEL را مستقیماً در config.yaml خود ویرایش کنید.» در Desktop، انتخاب‌گر مدل به شما اجازه می‌دهد «Use custom model» را انتخاب کنید تا یک نام مدل مشخص وارد کنید. |
| 404 در سمت OpenAI | «یک 404 معمولاً یعنی OPENAI_BASE_PATH برای پراکسی شما اشتباه است.» QCode در `/openai/v1/chat/completions` پاسخ می‌دهد. |
| `No api key passed in` | «goose کلیدهای API ارائه‌دهنده را از config.yaml نمی‌خواند. کلیدی که آنجا قرار داده شود نادیده گرفته می‌شود و این معمولاً به‌صورت یک خطای احراز هویت مانند No api key passed in ظاهر می‌شود.» کلید را با `goose configure` دوباره وارد کنید. |
| خطاهای کی‌رینگ در کانتینرها یا استفاده بدون رابط گرافیکی | goose «به‌طور پیش‌فرض تلاش می‌کند از کی‌رینگ سیستم (keychain در macOS) برای ذخیره اطلاعات محرمانه استفاده کند»؛ اگر کی‌رینگ در دسترس نباشد، «لطفاً کلید(های) محرمانه را از طریق متغیرهای محیطی تنظیم کنید»، یا `GOOSE_DISABLE_KEYRING=1 goose configure` را اجرا کنید. |
| سرآیندهای اضافی درخواست | «در حال حاضر، سرآیندهای سفارشی فقط برای ارائه‌دهندگان سازگار با OpenAI در CLI قابل تعریف هستند. برای ارائه‌دهندگان سازگار با Anthropic یا Ollama، فایل پیکربندی ارائه‌دهنده را پس از ایجاد ویرایش کنید.» |
| شناسه مدل توسط QCode رد می‌شود | QCode سری Gemini را ارائه نمی‌دهد و `gpt-6-luna` / `gpt-5.6-luna` را نیز ارائه نمی‌دهد؛ از شناسه‌های دیگر GPT (`gpt-6.1-sol`، `gpt-6-sol`، `gpt-5.6-terra`) یا یک مدل Claude / چینی استفاده کنید. برای Haiku، از شناسه فعلی `claude-haiku-5-5` استفاده کنید. |
| 429 از طرف ارائه‌دهنده | مستندات رسمی: «goose ممکن است هنگام تعامل با ارائه‌دهندگان LLM با خطای 429 (تجاوز از محدودیت نرخ درخواست) روبه‌رو شود.» فهرست مدل‌ها: [انتخاب مدل](/docs/usage/model-selection)؛ بررسی‌های سمت سرویس: [عیب‌یابی](/docs/reference/troubleshooting). |

صورتحساب به‌ازای هر توکن است؛ نرخ‌های هر مدل در https://qcode.cc/models فهرست شده‌اند.

## مرتبط

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — پروتکل × خانواده مدل
- [سازگاری ابزارها](/docs/ide/tool-compatibility) — کدام ابزارها کدام پروتکل را می‌پذیرند
- [راه‌اندازی OpenCode](/docs/ide/opencode) — یک عامل ترمینالی دیگر روی همان دو نقطه پایانی
- [راه‌اندازی Crush](/docs/ide/crush) — همان جفت ارائه‌دهنده، یک فایل پیکربندی JSON به‌جای ویزارد
- [یکپارچه‌سازی Aider](/docs/ide/aider) — هر دو نقطه پایانی نیز، بر اساس نام مدل انتخاب می‌شوند
- [انتخاب مدل](/docs/usage/model-selection)
- [مدل‌های چینی](/docs/usage/cn-models)