نصب goose و پیکربندی یک ارائه‌دهنده سفارشی

goose یک دستیار هوش مصنوعی چندمنظوره است که روی رایانه شما اجرا می‌شود. علاوه بر کدنویسی، می‌تواند به تحقیق، نوشتن، اتوماسیون و سازماندهی داده‌ها بپردازد. می‌توانید از طریق برنامه دسکتاپ، ترمینال یا API از آن استفاده کنید و نسخه‌های دسکتاپ و ترمینال پیکربندی مدل یکسانی را به اشتراک می‌گذارند. این ابزار برای وظایف کدنویسی تکراری مناسب است و همچنین می‌تواند به GitHub، پایگاه‌های داده و فایل‌ها متصل شود.

قبل از شروع

goose دو گزینه نصب ارائه می‌دهد: دسکتاپ و CLI. دسکتاپ نسخه گرافیکی با پنجره است، در حالی که CLI با وارد کردن دستورات در ترمینال استفاده می‌شود. هر دو پیکربندی اصلی یکسانی را به اشتراک می‌گذارند، از جمله ارائه‌دهنده (Provider) و مدل. ارائه‌دهنده پیکربندی اتصالی است که به goose می‌گوید از کدام سرویس مدل استفاده کند.

پنجره می‌خواهید

goose Desktop

• دانلود فایل zip در macOS
• یا استفاده از brew cask
• استفاده از بسته نصب‌کننده در لینوکس

فقط ترمینال

goose CLI

• download_cli.sh
• یا Homebrew CLI
• سپس goose session را اجرا کنید

ویندوز

ابتدا یک محیط انتخاب کنید

• Git Bash یا MSYS2
• همچنین می‌توانید از PowerShell استفاده کنید
• اگر دستور پیدا نشد، آن را به PATH اضافه کنید

قبل از شروع، شناسه مدل را از لیست مدل فعلی آماده داشته باشید. شناسه مدل نامی است که سرویس مدل برای شناسایی یک مدل خاص استفاده می‌کند و هنگام استفاده باید شناسه کامل را کپی کنید.

نصب و اولین اجرا

اگر پنجره گرافیکی می‌خواهید

دو روش نصب مستند برای macOS وجود دارد:

• آن را از صفحه نصب دانلود کنید. صفحه نسخه‌های macOS Silicon و macOS Intel را ارائه می‌دهد. پس از دانلود، فایل zip را استخراج کرده و برنامه داخل آن را اجرا کنید.
• یا از Homebrew استفاده کنید:

brew install --cask block-goose

این همان برنامه را دانلود می‌کند و همچنین می‌تواند به‌روزرسانی‌ها را مدیریت کند.

اگر از Apple Mac M3 استفاده می‌کنید و پس از باز کردن برنامه پنجره‌ای ظاهر نمی‌شود، بررسی کنید که آیا ~/.config قابل خواندن و نوشتن است. goose از این دایرکتوری برای نوشتن گزارش‌ها استفاده می‌کند.

برای نسخه دسکتاپ لینوکس، آن را از صفحه نصب دانلود کنید. بسته‌های موجود DEB برای اوبونتو/دبیان، RPM برای RHEL/فدورا و Flatpak هستند. در دبیان یا اوبونتو، فایل DEB را دانلود کنید، دایرکتوری که در آن ذخیره شده را باز کنید، اجرا کنید sudo dpkg -i (filename).deb، و سپس goose را از منوی برنامه باز کنید. جایگزین کنید (filename) با نام فایل واقعی.

برای نسخه دسکتاپ ویندوز، آن را از صفحه نصب دانلود کنید، فایل zip را استخراج کرده و برنامه داخل آن را اجرا کنید.

اگر فقط نسخه ترمینال را می‌خواهید

در مک و لینوکس، اجرا کنید:

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

برای رد کردن پیکربندی تعاملی در حین نصب، اضافه کنید CONFIGURE=false قبل از bash:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

در مک، همچنین می‌توانید اجرا کنید:

brew install block-goose-cli

برای به‌روزرسانی CLI نصب شده، اجرا کنید:

goose update

در ویندوز، یکی از سه محیط زیر مورد نیاز است: Git Bash، که همراه با Git for Windows ارائه شده و به عنوان توصیه شده علامت‌گذاری شده است؛ MSYS2؛ یا PowerShell موجود در ویندوز 10/11. در Git Bash و MSYS2، از همان download_cli.sh دستور نشان داده شده در بالا استفاده کنید. در PowerShell، ابتدا اسکریپت را دانلود کرده و سپس اجرا کنید:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
.\download_cli.ps1

اگر به شما گفته شد که goose در PATH نیست، صفحه نصب را دنبال کنید و اضافه کنید ~/.local/bin یا %USERPROFILE%\.local\bin به پیکربندی پوسته فعلی، سپس ترمینال را دوباره باز کنید. PATH مجموعه‌ای از دایرکتوری‌ها است که ترمینال برای برنامه‌ها جستجو می‌کند. اگر دایرکتوری نصب گنجانده نشده باشد، ممکن است نتوانید با وارد کردن مستقیم نام برنامه، آن را اجرا کنید.

از تاریخ 2026-10-09، نسخه CLI 1.54.0 بود. به‌طور پیش‌فرض، اسکریپت نصب برنامه را در ~/.local/binقرار می‌دهد. می‌توانید این دایرکتوری را با GOOSE_BIN_DIR متغیر محیطی تغییر دهید. اگر آن را تغییر دهید، اسکریپت به‌طور خودکار پیکربندی پوسته را به‌روزرسانی نمی‌کند و ترمینال گزارش می‌دهد که دایرکتوری در PATH نیست. آن دایرکتوری را به PATH اضافه کنید یا goose را با استفاده از مسیر کامل آن اجرا کنید.

اولین باری که از goose استفاده می‌کنید، از شما می‌خواهد یک ارائه‌دهنده پیکربندی کنید. می‌توانید ارائه‌دهنده‌های داخلی را رد کرده و یک ارائه‌دهنده سفارشی همانطور که در بخش بعدی توضیح داده شده اضافه کنید. در ترمینال، به دایرکتوری که می‌خواهید در آن کار کنید بروید و اجرا کنید:

goose session

دریافت مقادیر اتصال از OmniProxy

آدرس، کلید و نام مدل را از نمونه OmniProxy خود آماده کنید. نمونه ارائه‌دهنده سفارشی از یک base_url استفاده می‌کند که به /v1/chat/completionsختم می‌شود، بنابراین این راهنما از همان فرمت پیروی می‌کند:

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   Copy from the current OmniProxy model list; separate multiple models with commas

نام کامل مدل را از لیست فعلی OmniProxy کپی کنید، از جمله هرگونه اسلش. از تاریخ 2026-10-09، دو شناسه مرجع در مستندات ارائه‌دهنده عبارت بودند از grok-4.7 برای Grok و gpt-6-luna از مستندات OpenAI. gpt-6-luna از Chat Completions پشتیبانی می‌کند؛ فراخوانی تابع در Chat Completions فقط زمانی پشتیبانی می‌شود که reasoning_effort تنظیم شده باشد به none. نامی را که در لیست ظاهر نمی‌شود کپی نکنید.

ورود به پیکربندی ابزار

یک ارائه‌دهنده سفارشی می‌تواند از فرمت سازگار با OpenAI، Anthropic یا Ollama استفاده کند. فرمت سازگار به این معنی است که ابزار درخواست‌ها را طبق یک مشخصات API مشترک ارسال می‌کند. هنگام اتصال به OmniProxy، OpenAI Compatible را انتخاب کنید.

دسکتاپ

1. روی دکمه در گوشه سمت چپ بالا کلیک کنید تا نوار کناری باز شود.
2. روی Settings کلیک کنید.
3. روی Models کلیک کنید.
4. روی Configure providers کلیک کنید.
5. روی Add Custom Provider در پایین پنجره کلیک کنید.
6. برای نوع ارائه‌دهنده (Provider Type)، OpenAI Compatible را انتخاب کنید. می‌توانید نام نمایشی (Display Name) را روی OmniProxy تنظیم کنید. آدرس بخش قبلی را در API URL وارد کنید. اگر کلید مورد نیاز است، گزینه‌ای که نیاز به API Key دارد را انتخاب کرده و کلید OmniProxy خود را وارد کنید. در مدل‌های موجود (Available Models)، نام مدل‌ها را وارد کنید و چندین نام را با کاما جدا کنید.
7. روی Create Provider کلیک کنید.

نسخه دسکتاپ در حال حاضر نمی‌تواند هدرهای درخواست سفارشی را در این پنجره تعریف کند. اگر به هدرهای درخواست نیاز دارید، پس از ایجاد ارائه‌دهنده، فایل پیکربندی را ویرایش کنید.

ترمینال

اجرا کنید:

goose configure

گزینه Custom Providers را انتخاب کنید، سپس Add A Custom Provider را انتخاب کنید. برای نوع API، OpenAI Compatible را انتخاب کنید، سپس دستورالعمل‌ها را برای وارد کردن نام، API URL، اینکه آیا کلید مورد نیاز است، نام مدل‌ها و اینکه آیا پاسخ‌های جریانی (streaming) پشتیبانی می‌شوند، دنبال کنید.

هنگام پیکربندی دستی در ویندوز، اگر keychain خطا گزارش کرد، دستورالعمل‌های نصب می‌گویند از ذخیره کلید در keyring خودداری کنید و به جای آن از یک متغیر محیطی استفاده کنید. سپس اجرا کنید goose configure دوباره. keychain یک سیستم ذخیره‌سازی امن کوچک است که توسط سیستم عامل برای ذخیره اسرار استفاده می‌شود.

فایل پیکربندی

دایرکتوری‌های مستند شده عبارتند از:

• مک و لینوکس: ~/.config/goose/custom_providers/
• ویندوز: %APPDATA%\Block\goose\config\custom_providers\

می‌توانید فایل را بر اساس نمونه ارائه‌شده قرار دهید. نام، آدرس و مدل‌ها را با مقادیر خود جایگزین کنید. کلید را در متغیر محیطی مشخص شده توسط api_key_envذخیره کنید؛ کلید واقعی را در فایل ننویسید:

{
  "name": "omniproxy",
  "engine": "openai",
  "display_name": "OmniProxy",
  "api_key_env": "OMNIPROXY_API_KEY",
  "base_url": "https://your-omniproxy-origin.example/v1/chat/completions",
  "models": [
    { "name": "grok-4.7", "context_limit": 128000 },
    { "name": "gpt-6-luna", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

یک مقدار عددی برای context_limitنگه دارید، همانطور که در مثال نشان داده شده است. محدودیت زمینه واقعی به مدل و OmniProxy بستگی دارد؛ عدد مثال را به عنوان محدودیت رسمی مدل در نظر نگیرید. قبل از استفاده از آن، اجرا کنید:

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

پس از ورود به دایرکتوری کاری، اجرا کنید:

goose session --provider omniproxy --model grok-4.7

مقدار --model را با شناسه کامل از لیست جایگزین کنید. goose session یک start زیردستور ندارد. همچنین می‌توانید تنظیم کنید --provider و --model از طریق GOOSE_PROVIDER و GOOSE_MODEL متغیرهای محیطی. حتی اگر درگاه کلیدها را تأیید نمی‌کند، OMNIPROXY_API_KEY همچنان باید مقداری داشته باشد. این می‌تواند یک رشته جای‌نگهدار باشد که فقط در رایانه محلی شما استفاده می‌شود. این پیکربندی در آزمایش در تاریخ 2026-10-09 با موفقیت یک فایل را خواند.

پنجره

تنظیمات

• تنظیمات در نوار کناری
• صفحه مدل‌ها
• افزودن ارائه‌دهنده سفارشی

ترمینال

goose configure

• انتخاب ارائه‌دهنده‌های سفارشی
• سپس افزودن را انتخاب کنید
• OpenAI Compatible را به عنوان نوع انتخاب کنید

فایل

custom_providers

• در مک و لینوکس، زیر ~/.config است
• در ویندوز، زیر APPDATA است
• base_url را طبق مثال رسمی تنظیم کنید

تأیید با یک وظیفه واقعی

دایرکتوری حاوی یک فایل معمولی را باز کنید و اجرا کنید goose session همانطور که در بخش قبلی نشان داده شده است. از آن بخواهید اولین خط فایلی که مشخص می‌کنید را بخواند. باید محتویات فایل را برگرداند نه اینکه فقط بگوید پیکربندی ذخیره شده است.

برای خواندن فایل‌ها یا اجرای دستورات، جلسه به افزونه Developer نیاز دارد. افزونه Developer یک ماژول ابزار است که به goose اجازه می‌دهد با فایل‌ها و دستورات محلی کار کند. این افزونه معمولاً در پیکربندی پیش‌فرض گنجانده شده است. اگر goose می‌گوید ابزار فایل ندارد، موارد زیر را به دستور اضافه کنید:

--with-builtin developer

همچنین اضافه نکنید --no-profile، زیرا آن گزینه افزونه‌های پیش‌فرض را غیرفعال می‌کند.

در آزمایش در تاریخ 2026-10-09، goose 1.54.0 با موفقیت اولین خط فایل مشخص شده را خواند. اولین پاسخ ممکن است حدود یک دقیقه طول بکشد.

سپس گزارش‌های درخواست OmniProxy را بررسی کنید تا منبع و نام مدل را تأیید کنید.

اجرا

یک جلسه باز می‌شود

• goose session
• ارائه‌دهنده همان است که به‌تازگی اضافه شده
• نام مدل در لیست است

وظیفه

در واقع وظیفه را تکمیل کرد

• به عنوان مثال، دایرکتوری فعلی را فهرست کنید
• پاسخ آن را بررسی کنید
• فقط به یک ذخیره موفق تکیه نکنید

گزارش‌ها

قابل مشاهده در درگاه

• از آدرس موجود در مثال مستندات استفاده کنید
• کلید را در مخزن قرار ندهید
• شناسه مدل با لیست مطابقت دارد

خطاهای رایج

• goose دستور پیدا نشد: دایرکتوری نصب را همانطور که در صفحه نصب توضیح داده شده به PATH اضافه کنید، سپس ترمینال را دوباره باز کنید.
• هیچ پنجره‌ای در نسخه دسکتاپ در M3 Mac ظاهر نمی‌شود: مجوزهای خواندن و نوشتن را برای ~/.configبررسی کنید.
• keychain شکست می‌خورد: کلید را در keyring ذخیره نکنید؛ به جای آن از یک متغیر محیطی استفاده کنید.
• مدل در لیست نیست: در نسخه دسکتاپ، Use custom model را انتخاب کرده و نام مدل را به‌صورت دستی وارد کنید. goose configure نمی‌تواند نام مدل سفارشی را بپذیرد. برای استفاده از ترمینال، به نسخه دسکتاپ بروید یا ویرایش کنید GOOSE_MODEL مستقیماً در پیکربندی.
• آدرس قابل دسترسی نیست: تأیید کنید که API URL به /v1/chat/completionsختم می‌شود، همانطور که در مثال است، و OmniProxy در حال اجرا است.
• می‌گوید نمی‌تواند فایل‌ها را بخواند: افزونه Developer را اضافه کنید و از آن استفاده نکنید --no-profile.
• برمی‌گرداند unsupported Responses role: system: آدرس معمولاً درست است. به یک شناسه کامل دیگر از لیست مدل بروید.

مراجع رسمی

برای نصب، ببینید نصب goose. برای ارائه‌دهنده‌های سفارشی، ببینید ارائه‌دهنده‌های goose. برای شناسه‌های مدل استفاده شده در مثال‌ها، ببینید صفحه مدل‌های xAI و GPT-6 Luna.

هر جایگاه را با مقادیر از پیکربندی OmniProxy خود جایگزین کنید. هرگز یک کلید واقعی را منتشر نکنید.

یک نتیجه ذخیره شده یا HTTP 200 به تنهایی سازگاری کامل عامل را اثبات نمی‌کند. منبع و مدل را در گزارش درخواست OmniProxy بررسی کنید.

منابع رسمی · goose ↗