چگونه گیت‌وی‌های سازگار با OpenAI را به عامل Pi متصل کنیم؟

تصور کنید تنها با یک فایل پیکربندی JSON، دسترسی به بیش از ۱۳۰ مدل مختلف — از جمله پرچمداران وزن‌باز چینی — باز شود و تمام هزینه‌ها تنها از طریق یک کلید API مدیریت شود. این قابلیت در ۱۸ اوت ۲۰۲۶ طی تست‌های نسخه ۰.۸۴.۱ ابزار Pi روی سیستم‌عامل macOS به اثبات رسید. با متصل کردن یک گیت‌وی API سفارشی به عامل کدنویسی Pi، شما می‌توانید هر مدلی را که ارائه‌دهنده شما می‌فروشد، مستقیماً در حلقه خودمختار Pi اجرا کنید.

بسیاری از توسعه‌دهندگان در حال حاضر برای استفاده از مدل‌های OpenAI، Anthropic یا Google به اشتراک‌های داخلی Pi متکی هستند. این ابزار در حالت پیش‌فرض با ۳۶ ارائه‌دهنده کلید API و ۶ ورود اشتراکی (مانند ChatGPT Plus و Pro، Claude Pro و Max، GitHub Copilot، xAI و OpenRouter) عرضه می‌شود. اما این ساختار شما را به مدل‌هایی محدود می‌کند که Pi از پیش شناسایی کرده است. با استفاده از یک ارائه‌دهنده سفارشی، می‌توانید مدل‌های ارزان‌قیمت پیش‌فرض را در برابر مدل‌های گران‌قیمت ارتقایی (Escalation Models) تست کنید، بدون اینکه نیاز باشد چندین حساب کاربری مختلف مدیریت کنید. این موضوع به‌ویژه برای کسانی حیاتی است که می‌خواهند به‌جای داشبوردهای متعدد هر فروشنده، تنها از یک کلید برای تمام ابزارهای خود استفاده کنند. این رویکرد مشابه راهکاری است که Routara برای متمرکز کردن چندین ارائه‌دهنده LLM در یک نقطه اتصال OpenAI به کار گرفته است تا مدیریت مدل‌ها ساده‌تر شود.

چه زمانی از ارائه‌دهندگان سفارشی استفاده کنیم؟

افزودن یک ارائه‌دهنده سفارشی در سناریوهای خاصی توجیه می‌شود:

• مدل‌های غیررسمی (Non-First-Party): زمانی که به مدل‌هایی نیاز دارید که ارائه‌دهندگان اصلی آن‌ها را ندارند، مانند اکثر پرچمداران وزن‌باز چینی یا نسخه‌های میزبانی‌شده از مدل‌های باز.
• یکپارچه‌سازی صورت‌حساب: اگر ابزارهایی مانند Claude Code یا Codex CLI را از طریق یک گیت‌وی هدایت می‌کنید و می‌خواهید به‌جای چهار صورت‌حساب، تنها یک صورت‌حساب داشته باشید.
• بهینه‌سازی هزینه: زمانی که می‌خواهید یک مدل ارزان را به عنوان پیش‌فرض در برابر یک مدل گران‌قیمت برای موارد پیچیده تست A/B کنید، بدون اینکه حساب کاربری دومی باز کنید.

در مقابل، اگر تنها از یک فروشنده و یک طرح استفاده می‌کنید، این تلاش ارزشمند نیست، زیرا دستور /login مستقیماً شش اشتراک اصلی را پوشش می‌دهد. همچنین محیط‌های اجرای محلی مانند Ollama، vLLM و llama.cpp موارد مستندی هستند که معمولاً تنها به یک baseUrl و شناسه مدل (Model ID) نیاز دارند و به تنظیمات پیچیده ارائه‌دهنده سفارشی که در اینجا شرح داده شده است، نیازی ندارند. برای کسانی که علاوه بر دسترسی به مدل‌ها، بر امنیت داده‌ها متمرکز هستند، استفاده از گیت‌وی‌های حریم خصوصی برای حذف اطلاعات شخصی پیش از ارسال پرامپت‌ها به مدل‌های ابری، یک مکمل ضروری است.

برای کسانی که از محیط‌های محلی استفاده می‌کنند، اگر دستور pi --list-models در حال حاضر مدلی را که قصد اجرای آن را دارید نشان می‌دهد، هیچ پیکربندی سفارشی لازم نیست. تمام موارد زیر برای افزودن مدل‌هایی است که Pi آن‌ها را نمی‌شناسد.

پیش‌نیازها و محیط اجرا

قبل از شروع، مطمئن شوید که Node نسخه ۲۲ یا جدیدتر را دارید (پکیج اعلام کرده است engines: node >=22.19.0؛ تست‌ها روی Node 24.14.1 اجرا شده‌اند). شما به یک کلید API معتبر و یک Base URL نیاز دارید که قبلاً از طریق curl تأیید شده باشد.

چک‌لیست الزامات:

• Node.js: نسخه ۲۴.۱۴.۱ (حداقل ۲۲.۱۹.۰)
• نسخه Pi: ۰.۸۴.۱ (آخرین نسخه ۰.۸۴.۲)
• پکیج: @earendil-works/pi-coding-agent (تحت لایسنس MIT)
• نقطه اتصال (Endpoint): باید به /chat/completions پاسخ دهد، نه فقط به /models (مثلاً https://api.ofox.ai/v1)
• شناسه مدل‌ها (Model IDs): باید دقیقاً رشته‌های ارسالی از گیت‌وی باشند، نه شناسه‌های فروشنده.

اگر هنوز عامل را نصب نکرده‌اید، از دستور زیر استفاده کنید:
npm install -g @earendil-works/pi-coding-agent

یک تصمیم حیاتی قبل از نوشتن پیکربندی: نام ارائه‌دهنده‌ای که انتخاب می‌کنید، بخشی از هر فلگ --provider و سوابق نشست (Session Record) می‌شود. تغییر نام آن در آینده باعث می‌شود نشست‌های قدیمی به ارائه‌دهنده‌ای اشاره کنند که دیگر وجود ندارد.

مکانیسم راه‌اندازی

برای افزودن یک ارائه‌دهنده سفارشی، باید فایل ~/.pi/agent/models.json را ویرایش کنید. یک ورودی حداقلی به چهار فیلد نیاز دارد: baseUrl ،api ،apiKey و یک آرایه models.

مثال پیکربندی برای گیت‌وی Ofox:

{
  "providers": {
    "ofox": {
      "baseUrl": "https://api.ofox.ai/v1",
      "api": "openai-completions",
      "apiKey": "$OFOX_API_KEY",
      "models": [
        {
          "id": "deepseek/deepseek-v4-flash",
          "contextWindow": 1000000,
          "maxTokens": 384000
        }
      ]
    }
  }
}

Pi از چهار پروتکل اصلی پشتیبانی می‌کند: openai-completions ،openai-responses ،anthropic-messages و google-generative-ai. پروتکل openai-completions گسترده‌ترین پیاده‌سازی را دارد و باید اولین انتخاب شما باشد. اگرچه openai-responses ممکن است برای برخی مدل‌ها در همان گیت‌وی کار کند، اما تضمینی جهانی نیست. Codex CLI یکی از ابزارهایی است که استفاده از openai-responses را اجباری می‌کند زیرا منحصراً با این پروتکل صحبت می‌کند.

امنیت با اجتناب از قرار دادن کلیدها به‌صورت مستقیم (Inline) مدیریت می‌شود. Pi سه روش برای تحلیل فیلد apiKey پشتیبانی می‌کند:

• رشته‌های تحت‌اللفظی: کلیدهای سخت‌افزاری (توصیه نمی‌شود).
• درونی‌سازی متغیرهای محیطی: استفاده از $VAR یا ${VAR} (مثلاً $OFOX_API_KEY).
• دستورات شل: استفاده از !command که یک دستور شل را اجرا کرده و از خروجی استاندارد (stdout) استفاده می‌کند. برای مثال در macOS: "apiKey": "!security find-generic-password -ws ofox".

پس از ذخیره فایل، می‌توانید یکپارچگی را با دستور pi --list-models [provider] تأیید کنید. این دستور پنجره متنی، حداکثر توکن‌ها، قابلیت‌های تفکر (Thinking) و پشتیبانی از تصویر را نمایش می‌دهد. اگر این فیلدها حذف شوند، Pi به‌طور پیش‌فرض پنجره متنی ۱۲۸ هزار و حداکثر خروجی ۱۶.۴ هزار توکن را در نظر می‌گیرد. توجه داشته باشید که انتخاب‌گر /model هر بار که باز می‌شود، فایل JSON را مجدداً می‌خواند و اجازه می‌دهد تغییرات پیکربندی به‌طور خودکار بارگذاری شوند.

تست یکپارچگی

برای اثبات اینکه تنظیمات کار می‌کند، دستوری را اجرا کنید که با دیسک در ارتباط باشد. حالت چاپ (Print mode) سریع‌ترین راه اثبات است زیرا به‌جای تست صرف نقطه اتصال، حلقه ابزار (Tool Loop) را به چالش می‌کشد:

pi --provider ofox --model deepseek/deepseek-v4-flash -p "Read buggy.py, run it, and state the one-line bug. Do not edit files."

در یک دایرکتوری تست با فایلی که حاوی یک باگ ساده در جمع (مثلاً return a - b) بود، مدل DeepSeek V4 Flash با موفقیت فایل را خواند، مفسر را از طریق ابزار bash اجرا کرد و باگ را در اولین تلاش شناسایی کرد. این موضوع یکپارچگی کامل را تأیید می‌کند: خواندن فایل، اجرای شل و ارائه پاسخ.

حل شکست‌های «ساکت»

یکپارچگی اغلب با سه دیوار غیربدیهی برخورد می‌کند که خود را به‌عنوان خطاهای پیکربندی اعلام نمی‌کنند.

۱. پارادوکس «آماده بودن» (Ready Paradox)
اجرای pi auth check --provider [name] تنها تأیید می‌کند که یک کلید در جای خود قرار گرفته است، نه اینکه کلید معتبر باشد. ارائه‌دهنده‌ای که به یک کلید عمداً نامعتبر اشاره می‌کند، همچنان پاسخ # ready می‌دهد. تنها تست واقعی احراز هویت، بروز خطای ۴۰۱ در طول یک اجرای واقعی است.

۲. شکاف حسابداری هزینه‌ها
به‌طور پیش‌فرض، ارائه‌دهندگان سفارشی برای هر نشست مبلغ $0.00 گزارش می‌کنند زیرا Pi قیمت‌ها را از گیت‌وی دریافت نمی‌کند. حسابداری توکن‌ها دقیق است، اما مبلغ صفر می‌ماند تا زمانی که نرخ‌ها را خودتان بنویسید. برای رفع این مشکل، یک بلوک cost به ورودی مدل با نرخ‌های هر میلیون توکن اضافه کنید:

"cost": {
  "input": 2,
  "output": 10,
  "cacheRead": 0.2,
  "cacheWrite": 2.5
}

بدون این تنظیمات، لاگ‌های نشست شما (در مسیر ~/.pi/agent/sessions/) تعداد دقیق input ،output و cacheRead را نشان می‌دهند، اما ستون هزینه $0.00 باقی می‌ماند. برای مثال، یک اجرا با Claude Sonnet 5 با ۴,۱۱۱ توکن ورودی و ۴ توکن خروجی، تنها در صورتی قیمت درست $0.008262 را نشان می‌دهد که این نرخ‌ها صراحتاً تایپ شده باشند.

۳. کرش «نقش توسعه‌دهنده» (Developer Role Crash)
وقتی reasoning: true فعال باشد، Pi پرامپت سیستم را به‌عنوان یک پیام با نقش developer ارسال می‌کند. بسیاری از سیستم‌های بالادستی، به‌ویژه مدل‌های خانواده Anthropic که از طریق گیت‌وی‌های سازگار با OpenAI هدایت می‌شوند، این نقش را با خطای ۵۰۰ رد می‌کنند: "unsupported message role: developer".

دو راه برای مدیریت این موضوع وجود دارد:

• راهکار درست: افزودن compat: { supportsDeveloperRole: false }. این کار پرامپت سیستم را به یک پیام system منتقل می‌کند در حالی که reasoning_effort را حفظ می‌کند تا قابلیت تفکر باقی بماند.
• راهکار سخت: تنظیم reasoning: false. این کار با حذف کامل پارامتر استدلال، خطا را برطرف می‌کند که معمولاً معامله‌ای اشتباه است.

پنجره متنی و فشرده‌سازی

یکی از خطرناک‌ترین تله‌ها، استفاده از شناسه‌های مدل لیست‌نشده است. Pi به شما اجازه می‌دهد هر شناسه مدلی را که در فایل JSON شما نیست اجرا کنید، اما این کار باعث ایجاد یک هشدار شده و به پیش‌فرض ۱۲۸ هزار توکن باز می‌گردد.

اگر یک مدل با پنجره متنی ۱ میلیون توکن (مانند Claude Sonnet 5) را بدون تعریف contextWindow در JSON اجرا کنید، فشرده‌سازی خودکار Pi بسیار زودتر از موعد فعال می‌شود. فشرده‌سازی خودکار زمانی رخ می‌دهد که contextTokens > contextWindow - reserveTokens (که در آن reserveTokens به‌طور پیش‌فرض ۱۶,۳۸۴ است). در نتیجه، یک مدل ۱ میلیون توکنی، خلاصه‌سازی تاریخچه خود را در حدود ۱۱۱,۶۰۰ توکن آغاز می‌کند و به‌طور مؤثر ۸۸٪ از ظرفیت واقعی مدل را بدون اطلاع کاربر هدر می‌دهد.

بهینه‌سازی یکپارچگی Claude

برای کسانی که به‌طور خاص از مدل‌های Claude استفاده می‌کنند، بازنویسی ارائه‌دهنده داخلی anthropic کارآمدتر از ایجاد یک ورودی سفارشی سازگار با OpenAI است. با هدایت baseUrl به مسیر Anthropic در گیت‌وی (توقف قبل از بخش /v1)، Pi تمام کاتالوگ داخلی Claude را با پنجره‌های متنی درست (مثلاً Claude Fable 5 در ۱ میلیون، Opus و Haiku در ۲۰۰ هزار) حفظ می‌کند.

{
  "providers": {
    "anthropic": {
      "baseUrl": "https://api.ofox.ai/anthropic",
      "apiKey": "$OFOX_API_KEY"
    }
  }
}

این مسیر به‌طور کامل مشکل نقش توسعه‌دهنده را دور می‌زند زیرا از ساختار بومی Messages API استفاده می‌کند. با این حال، کاربران باید از یک مشکل شمای شناخته شده که توسط آرمین روناچر در ۴ ژوئیه ۲۰۲۶ گزارش شده است، آگاه باشند. مدل‌های جدیدتر مانند Opus 4.8 و Sonnet 5 گاهی فیلدهای اضافی در آرایه edits[] اختراع می‌کنند که باعث می‌شود Pi فراخوانی ابزار را رد کرده و مجبور به تلاش مجدد شود. این یک عدم تطابق در آموزش و ابزارسازی است که هر بار باعث یک تلاش مجدد (Retry) می‌شود.

عیب‌یابی بدنه درخواست

وقتی یک مدل خطای ۴۰۰ یا ۵۰۰ برمی‌گرداند، رشته خطا اغلب گمراه‌کننده است. برای مثال، هدایت یک ارائه‌دهنده داخلی Anthropic به یک مسیر OpenAI، خطای ۴۰۱ 'Missing API Key' برمی‌گرداند. در واقع، این یک عدم تطابق پروتکل است: Pi هدر x-api-key را ارسال می‌کند، اما مسیر OpenAI منتظر Authorization: Bearer است.

برای تشخیص این مسائل، توسعه‌دهندگان باید لاگ‌های نشست Pi در ~/.pi/agent/sessions/ را با یک درخواست دستی curl مقایسه کنند.

متریک‌های کلیدی برای بررسی در پاسخ خام API:

• prompt_tokens_details.cached_tokens: تأیید می‌کند که آیا حافظه پنهان پرامپت واقعاً کار می‌کند یا خیر. Pi این مقدار را به ستون cacheRead منتقل می‌کند.
• completion_tokens_details.reasoning_tokens: تأیید می‌کند که آیا تفکر (Thinking) واقعاً در حال اجرا است، که سریع‌تر از حدس زدن از روی خروجی است.

خلاصه شکست‌های رایج و راهکارها

همکاری تیمی و ثبات

برای اطمینان از ثبات تیمی، باید بلوک‌های ارائه‌دهنده models.json را در یک مخزن مشترک Commit کنید در حالی که apiKey را به‌عنوان یک متغیر محیطی نگه دارید. این کار تضمین می‌کند که هر توسعه‌دهنده در تیم از پنجره‌های متنی و محدودیت‌های نرخ (Rate Limits) یکسانی استفاده می‌کند و از رفتارهای متفاوت عامل در ماشین‌های مختلف جلوگیری می‌کند.

گردش کار پیشنهادی برای تیم:

• Commit کنید: Base URL، پروتکل و ورودی‌های کامل مدل (Context، Max Tokens، Reasoning و Cost).
• Commit نکنید: کلید واقعی API. در فایل مشترک از "apiKey": "$OFOX_API_KEY" استفاده کنید.
• نسخه را پین کنید: نسخه Pi (مثلاً ۰.۸۴.۱) را که پیکربندی با آن تأیید شده ثبت کنید، زیرا Pi تقریباً هر هفته به‌روزرسانی می‌شود.
• یکپارچه کردن نقطه اتصال: از یک Base URL برای کل تیم استفاده کنید تا یک کاتالوگ مدل و استخر محدودیت نرخ واحد داشته باشید.

مدیریت کلید در بسترهای مختلف

هر بستر (Harness) دسترسی به مدل را در گویش خاص خود ذخیره می‌کند. Claude Code مقدار ANTHROPIC_BASE_URL را می‌خواند، Codex CLI از config.toml استفاده می‌کند و Pi از فایل JSON شرح داده شده در اینجا. چون همه آن‌ها از طریق HTTP با نقاط اتصال سازگار با OpenAI یا Anthropic صحبت می‌کنند، راهکار چرخش کلیدها یکسان است: یک Base URL و یک کلید. برای مثال در گیت‌وی Ofox، یک کلید در تاریخ ۱۸ اوت ۲۰۲۶ به ۱۳۱ مدل دسترسی داشت، از جمله Kimi K3 و MiniMax M3.

این رویکرد مینیمالیستی در پیکربندی به این معناست که Pi از حدس زدن مشخصات ارائه‌دهنده شما خودداری می‌کند. هر راهکار — از نرخ‌های هزینه تا سازگاری نقش‌ها — مستلزم آن است که توسعه‌دهنده حقیقت را به‌طور صریح در فایل JSON تعریف کند.