یکپارچه‌سازی AvalAI با OpenAI Codex

OpenAI Codex یک عامل (Agent) کدنویسی قدرتمند مبتنی بر هوش مصنوعی است که به صورت CLI، افزونه IDE و اپلیکیشن دسکتاپ در دسترس قرار دارد. اگرچه Codex به‌طور پیش‌فرض با مدل‌های OpenAI ارائه می‌شود، اما از ارائه‌دهندگان مدل سفارشی (Custom Model Providers) پشتیبانی می‌کند؛ این یعنی می‌توانید آن را به AvalAI متصل کرده و به بیش از 410 مدل پیشرفته هوش مصنوعی دسترسی پیدا کنید—نه فقط مدل‌های OpenAI، بلکه Claude، Gemini، DeepSeek، Grok، Qwen، Mistral و بسیاری دیگر—همگی از طریق یک API واحد.

از آنجا که Codex پیکربندی خود را از یک فایل ساده ~/.codex/config.toml می‌خواند، یکپارچه‌سازی با AvalAI تنها چند دقیقه زمان می‌برد: یک ارائه‌دهنده سفارشی تعریف کنید، URL پایه آن را به AvalAI اشاره دهید و به Codex بگویید از آن استفاده کند.

💰 پیشنهاد ویژه

با بسته‌های اعتباری اختصاصی AvalAI، تا ۷۰٪ اعتبار بیشتر دریافت کنید یا از تا ۴۰٪ تخفیف ویژه در خریدهای خود بهره‌مند شوید. این پیشنهادهای منحصر به فرد به شما کمک می‌کنند بودجه توسعه هوش مصنوعی خود را به بهترین شکل مدیریت کنید!

چرا AvalAI را با OpenAI Codex یکپارچه کنیم؟

اتصال Codex به AvalAI، قابلیت‌های قدرتمندی را به ترمینال و ویرایشگر شما اضافه می‌کند:

• دسترسی به بیش از 410 مدل: از Claude Opus 4.8، GPT-5.5، Gemini 3.5 Flash، GLM-5.2، Kimi K2.7 Code، MiniMax M3، DeepSeek-V4، Grok، Qwen و بسیاری دیگر استفاده کنید—بدون محدودیت به مدل‌های OpenAI
• چندین ارائه‌دهنده، یک پیکربندی: بدون تغییر ابزار، بین OpenAI، Anthropic، Google، DeepSeek و سایر ارائه‌دهندگان جابجا شوید
• کدنویسی کاملا عاملی (Agentic): کد تولید کنید، بازسازی کنید، اشکال‌زدایی کنید، دستورات را اجرا کنید و فایل‌ها را مستقیما از CLI یا IDE ویرایش کنید
• API سازگار با OpenAI: AvalAI یک نقطه پایانی سازگار با OpenAI ارائه می‌دهد، بنابراین Codex با یک ارائه‌دهنده سفارشی بدون نیاز به تنظیمات اضافی کار می‌کند
• مقرون به صرفه بودن: از قیمت‌گذاری رقابتی AvalAI که کاملا با نرخ‌های ارائه‌دهندگان اصلی همسو است، بهره‌مند شوید
• انعطاف‌پذیری کامل: بهترین مدل را برای هر وظیفه انتخاب کنید—استدلال، کدنویسی سریع یا توسعه مقرون به صرفه

دریافت کلید API از AvalAI (راهنمای گام به گام)

برای دریافت کلید API خود، این مراحل را دنبال کنید:

1. ایجاد حساب کاربری AvalAI: در صورتی که هنوز حساب کاربری ندارید، به داشبورد AvalAI مراجعه کرده و ثبت‌نام کنید.

2. ورود به بخش کلیدهای API: پس از ورود به حساب کاربری، به بخش "کلید‌های API" در داشبورد خود بروید.

3. ایجاد کلید جدید: روی دکمه "ساخت کلید جدید" یا "Create new secret key" کلیک کنید.

4. نام‌گذاری کلید (اختیاری): برای مدیریت بهتر، به کلید API خود نامی توصیفی مانند "توسعه Codex" اختصاص دهید.

5. کپی و ذخیره‌سازی کلید API: کلید تولید شده تنها یک بار نمایش داده می‌شود. بسیار مهم: این کلید را فورا کپی کرده و در مکانی امن ذخیره کنید. به دلایل امنیتی، امکان مشاهده مجدد کلید کامل وجود ندارد.

نصب Codex CLI

اگر هنوز Codex را نصب نکرده‌اید، ابتدا CLI را نصب کنید.

در macOS یا Linux، از نصب‌کننده مستقل استفاده کنید:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

در Windows، این دستور را اجرا کنید:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

همچنین می‌توانید Codex CLI را با npm یا Homebrew نصب کنید:

npm install -g @openai/codex

brew install --cask codex

Codex CLI و افزونه IDE از لایه‌های پیکربندی یکسانی استفاده می‌کنند، بنابراین مراحل زیر برای هر دو معتبر است.

تنظیم کلید API به عنوان متغیر محیطی

Codex کلید API ارائه‌دهنده را از یک متغیر محیطی می‌خواند که شما آن را در پیکربندی (از طریق env_key) نام‌گذاری می‌کنید. در این راهنما از AVALAI_API_KEY استفاده می‌کنیم.

کلید API AvalAI خود را به‌گونه‌ای صادر (export) کنید که Codex بتواند آن را بخواند:

macOS / Linux (bash یا zsh):

export AVALAI_API_KEY="your-avalai-api-key"

برای دائمی کردن آن، این خط را به فایل ~/.zshrc، ~/.bashrc یا ~/.bash_profile اضافه کنید و سپس ترمینال خود را مجددا راه‌اندازی کنید.

Windows (PowerShell):

setx AVALAI_API_KEY "your-avalai-api-key"

پس از اجرای setx، ترمینال خود را مجددا راه‌اندازی کنید تا متغیر در دسترس قرار گیرد.

نکته امنیتی

هرگز کلید API خود را مستقیما در فایل config.toml قرار ندهید. استفاده از متغیر محیطی از طریق env_key، رمز شما را از فایل‌های پیکربندی که ممکن است در سیستم کنترل نسخه ثبت شوند، دور نگه می‌دارد.

پیکربندی Codex برای AvalAI

Codex پیکربندی سطح کاربر خود را در ~/.codex/config.toml ذخیره می‌کند. این فایل را باز (یا ایجاد) کرده و AvalAI را به عنوان یک ارائه‌دهنده مدل سفارشی تعریف کنید.

نکته

در افزونه IDE Codex، می‌توانید این فایل را از طریق نماد چرخ‌دنده در گوشه بالا سمت راست و سپس Codex Settings > Open config.toml باز کنید.

پیکربندی توصیه‌شده

موارد زیر را به ~/.codex/config.toml اضافه کنید:

model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
model_provider = "avalai"

[model_providers.avalai]
name = "AvalAI"
base_url = "https://api.avalai.ir/v1"
env_key = "AVALAI_API_KEY"

عملکرد هر تنظیم به شرح زیر است:

• model — مدل پیش‌فرضی که Codex استفاده می‌کند. می‌توانید آن را روی هر مدلی که از طریق AvalAI در دسترس است تنظیم کنید (برای مثال gpt-5.3-codex، claude-opus-4-8، gemini-3.1-pro-preview یا deepseek-v4-pro).
• model_reasoning_effort — میزان تلاش استدلالی مدل را در صورت پشتیبانی تنظیم می‌کند. گزینه‌ها عبارتند از low، medium، high یا xhigh.
• model_provider — Codex را به ارائه‌دهنده سفارشی تعریف‌شده در زیر اشاره می‌دهد. مقدار آن باید با نام جدول ارائه‌دهنده مطابقت داشته باشد.
• [model_providers.avalai] — ارائه‌دهنده سفارشی را تعریف می‌کند:
  • name — یک نام نمایشی که در رابط کاربری Codex نشان داده می‌شود.
  • base_url — نقطه پایانی سازگار با OpenAI در AvalAI: https://api.avalai.ir/v1
  • env_key — نام متغیر محیطی که کلید API شما را نگه می‌دارد (AVALAI_API_KEY).

مهم

ارائه‌دهندگان سفارشی نمی‌توانند از شناسه‌های داخلی رزرو‌شده Codex استفاده کنند: openai، ollama و lmstudio. به همین دلیل ارائه‌دهنده را avalai نام‌گذاری می‌کنیم.

نکته‌ای درباره Responses API (سازگاری نقطه پایانی)

نکته

مهم — اگر یک مدل غیر OpenAI درست کار نکرد، این بخش را بخوانید. نسخه‌های اخیر Codex دیگر از نقطه پایانی v1/chat/completions استفاده نمی‌کنند. در عوض، Codex درخواست‌ها را منحصرا به نقطه پایانی v1/responses (یعنی OpenAI Responses API) ارسال می‌کند.

این موضوع برای مدل‌های OpenAI به‌خوبی کار می‌کند. اکثر ارائه‌دهندگان شخص ثالث (Claude، Gemini، DeepSeek و دیگران) کاملا با v1/chat/completions سازگار هستند، اما همیشه به‌طور کامل با v1/responses سازگار نیستند. از آنجا که Codex اکنون به نقطه پایانی Responses متکی است، ممکن است گهگاه با برخی مدل‌های غیر OpenAI با ناسازگاری یا رفتار نامطلوب مواجه شوید.

توجه

AvalAI تمام تلاش خود را می‌کند تا اطمینان حاصل شود که همه مدل‌ها از طریق نقطه پایانی v1/responses قابل استفاده باشند، اما سازگاری کامل برای تک‌تک مدل‌ها تضمین نمی‌شود. اگر مدل خاصی با Codex به‌درستی کار نمی‌کند، لطفا با پشتیبانی AvalAI تماس بگیرید—ما تمام تلاش خود را خواهیم کرد تا آن مدل از طریق نقطه پایانی Responses کار کند.

مورد اعتماد کردن پروژه (Trust)

Codex فقط زمانی پیکربندی سطح پروژه را بارگذاری می‌کند و بدون درخواست‌های مکرر اجرا می‌شود که پروژه مورد اعتماد باشد. می‌توانید یک پروژه را در config.toml خود به‌عنوان مورد اعتماد علامت‌گذاری کنید:

[projects."/path/to/your/project"]
trust_level = "trusted"

عبارت /path/to/your/project را با مسیر مطلق دایرکتوری پروژه خود جایگزین کنید.

نمونه کامل

با کنار هم قرار دادن همه موارد، یک فایل کامل ~/.codex/config.toml برای AvalAI به این شکل خواهد بود:

model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
model_provider = "avalai"

[model_providers.avalai]
name = "AvalAI"
base_url = "https://api.avalai.ir/v1"
env_key = "AVALAI_API_KEY"

[projects."/Users/yourname/projects/my-app"]
trust_level = "trusted"

اجرای Codex

پس از تنظیم متغیر محیطی و ذخیره config.toml، Codex را از دایرکتوری پروژه خود اجرا کنید:

cd /path/to/your/project
codex

Codex یک نشست تعاملی را با استفاده از ارائه‌دهنده AvalAI و مدلی که پیکربندی کرده‌اید آغاز می‌کند. برای تأیید اتصال، یک دستور ساده را امتحان کنید:

درباره این پروژه به من بگو

اگر پاسخ عادی دریافت کردید، یکپارچه‌سازی شما کار می‌کند! 🎉

تغییر موقت مدل (Override)

می‌توانید مدل را برای یک اجرای واحد بدون ویرایش config.toml تغییر دهید:

# استفاده از یک فلگ اختصاصی
codex --model claude-opus-4-8

# یا تغییر عمومی کلید/مقدار (مقدار به فرمت TOML است، نه JSON)
codex --config model='"gemini-3.1-pro-preview"'

استفاده از مدل‌های سایر ارائه‌دهندگان

یکی از بزرگ‌ترین مزایای AvalAI، دسترسی به مدل‌های ارائه‌دهندگان متعدد از طریق همان نقطه پایانی سازگار با OpenAI است. کافیست مقدار model را تغییر دهید—هیچ تغییر پیکربندی دیگری لازم نیست.

# Anthropic Claude
model = "claude-opus-4-8"

# Google Gemini
model = "gemini-3.1-pro-preview"

# DeepSeek
model = "deepseek-v4-pro"

جابجایی بین مدل‌ها با پروفایل‌ها (Profiles)

اگر به‌طور مکرر بین مدل‌ها جابجا می‌شوید، پروفایل‌های Codex به شما امکان می‌دهند لایه‌های پیکربندی نام‌گذاری‌شده را ذخیره کنید. برای هر پروفایل یک فایل جداگانه در ~/.codex/ ایجاد کنید:

# ~/.codex/claude.config.toml
model = "claude-opus-4-8"
model_reasoning_effort = "high"

سپس Codex را با آن پروفایل اجرا کنید:

codex --profile claude

پروفایل بر روی پیکربندی پایه ~/.codex/config.toml شما قرار می‌گیرد، بنابراین فقط به مقادیری نیاز دارد که متفاوت هستند.

انتخاب مدل مناسب

AvalAI دسترسی به بیش از 410 مدل را فراهم می‌کند. در ادامه چند توصیه برای وظایف کدنویسی با Codex آورده شده است:

برای تولید کد پیچیده و استدلال

• Claude Opus 4.8 (claude-opus-4-8) - بهترین گزینه برای استدلال پیچیده و کدبیس‌های بزرگ
• GPT-5.5 (gpt-5.5) - عالی برای حل مسائل پیشرفته
• Claude 4.6 Sonnet (claude-sonnet-4-6) - تعادل عالی بین سرعت و کیفیت

برای کدنویسی عاملی سریع و کارآمد

• GPT-5.3 Codex (gpt-5.3-codex) - بهینه‌شده برای کدنویسی عاملی به سبک Codex
• Gemini 3.1 Flash (gemini-3.1-flash) - پاسخ‌های سریع با کیفیت خوب
• Claude Haiku 4.5 (claude-haiku-4-5) - سریع و کارآمد برای وظایف روزمره

برای توسعه مقرون به صرفه

• DeepSeek V4 Flash (deepseek-v4-flash) - تخصصی برای کدنویسی
• Qwen3 Coder (qwen3-coder-next) - کیفیت خوب با هزینه کمتر
• Gemini 3.5 Flash (gemini-3.5-flash) - سریع، چندوجهی و اقتصادی
• Kimi K2.7 Code (kimi-k2.7-code) - مدل کدنویسی متن‌باز قدرتمند برای گردش‌کارهای عاملی

نکات و بهترین شیوه‌ها

• ذخیره‌سازی امن: با کلید API AvalAI خود مانند یک رمز عبور رفتار کنید. به جای قرار دادن مستقیم آن در config.toml، از رویکرد متغیر محیطی env_key استفاده کنید. هرگز کلید خود را در سیستم کنترل نسخه ثبت نکنید.
• تلاش استدلالی: برای وظایف ساده، مقدار model_reasoning_effort را برای پاسخ‌های سریع‌تر و ارزان‌تر کاهش دهید؛ برای حل مسائل پیچیده آن را افزایش دهید.
• نقاط بازگشت Git: Codex می‌تواند کدبیس شما را تغییر دهد. قبل و بعد از هر وظیفه، نقاط بازگشت (Checkpoint) Git ایجاد کنید تا در صورت نیاز به راحتی تغییرات را برگردانید.
• فایل AGENTS.md: یک فایل AGENTS.md به مخزن خود اضافه کنید تا راهنمایی منسجمی (دستورات ساخت، قراردادها و انتظارات) به Codex بدهید.
• محدودیت‌های نرخ: به محدودیت‌های نرخ AvalAI توجه داشته باشید. اکثر وظایف کدنویسی به خوبی در محدوده باقی می‌مانند، اما در اجراهای عاملی بزرگ مراقب باشید.
• پایش هزینه: استفاده خود را از طریق داشبورد AvalAI پیگیری کنید تا هزینه‌ها را رصد کرده و انتخاب مدل را بهینه کنید.
• آزمایش مدل‌ها: مدل‌های مختلف را برای وظایف مختلف امتحان کنید—برخی در اشکال‌زدایی عالی هستند و برخی دیگر در مستندسازی یا بازسازی‌های بزرگ.

عیب‌یابی

• خطای کلید API نامعتبر / احراز هویت:

  • بررسی کنید که متغیر محیطی AVALAI_API_KEY تنظیم شده باشد: دستور echo $AVALAI_API_KEY (در macOS/Linux) یا echo %AVALAI_API_KEY% (در Windows) را اجرا کنید.
  • پس از تنظیم متغیر، ترمینال خود را مجددا راه‌اندازی کنید تا Codex بتواند آن را بخواند.
  • مطمئن شوید کلید همچنان در داشبورد AvalAI فعال است و env_key در config.toml دقیقا با نام متغیر مطابقت دارد.

• خطای عدم شناسایی ارائه‌دهنده / "reserved provider ID":

  • مطمئن شوید ارائه‌دهنده سفارشی شما با نام‌های openai، ollama یا lmstudio نام‌گذاری نشده باشد—این شناسه‌ها توسط Codex رزرو شده‌اند. به جای آن از avalai استفاده کنید.
  • تأیید کنید که model_provider با نام جدول [model_providers.<name>] مطابقت دارد.

• مشکلات اتصال:

  • اتصال اینترنت خود را بررسی کنید.
  • مطمئن شوید هیچ فایروال یا پراکسی، دسترسی به https://api.avalai.ir را مسدود نمی‌کند.
  • مطمئن شوید base_url دقیقا https://api.avalai.ir/v1 است (شامل /v1).

• رفتار غیرمنتظره یک مدل غیر OpenAI:

  • Codex از نقطه پایانی v1/responses استفاده می‌کند که برخی مدل‌های غیر OpenAI هنوز به‌طور کامل از آن پشتیبانی نمی‌کنند (به بخش «نکته‌ای درباره Responses API» در بالا مراجعه کنید).
  • یک مدل دیگر را امتحان کنید، یا با پشتیبانی AvalAI تماس بگیرید تا به ما کمک کنید آن مدل از طریق نقطه پایانی Responses کار کند.

• خطای یافت نشدن مدل (Model Not Found):

  • تأیید کنید شناسه مدل صحیح است (به نمای کلی مدل‌های AvalAI مراجعه کنید).
  • یک مدل رایج مانند gpt-5.3-codex یا claude-opus-4-8 را امتحان کنید.

• بارگذاری نشدن پیکربندی:

  • تأیید کنید فایل در مسیر ~/.codex/config.toml قرار دارد (یا تحت CODEX_HOME در صورت تنظیم آن).
  • نحو TOML را برای اشتباهات تایپی بررسی کنید—یک جدول یا کوتیشن نادرست از بارگذاری پیکربندی جلوگیری می‌کند.
  • برای بارگذاری پیکربندی سطح پروژه، پروژه باید مورد اعتماد باشد.

• خطاهای محدودیت نرخ (Rate Limit):

  • محدودیت‌های نرخ مربوط به سطح (Tier) خود را بررسی کنید.
  • لحظه‌ای قبل از تلاش مجدد صبر کنید، یا برای محدودیت‌های بالاتر، ارتقای سطح خود را در نظر بگیرید.

نتیجه‌گیری

یکپارچه‌سازی AvalAI با OpenAI Codex ساده است و دسترسی به بیش از 410 مدل قدرتمند هوش مصنوعی را مستقیما در ترمینال و IDE شما باز می‌کند. با تعریف یک ارائه‌دهنده سفارشی واحد در ~/.codex/config.toml و صادر کردن کلید API AvalAI خود، آزادی استفاده از OpenAI، Claude، Gemini، DeepSeek و بسیاری مدل‌های دیگر را به دست می‌آورید—و با تغییر تنها یک خط بین آن‌ها جابجا می‌شوید.

چه مدل سریع gpt-5.3-codex در Codex را ترجیح دهید و چه بخواهید از استدلال عمیق Claude بهره ببرید، AvalAI یک دروازه انعطاف‌پذیر و مقرون به صرفه به بهترین مدل‌های هوش مصنوعی موجود در اختیار شما قرار می‌دهد.

منابع مرتبط

• مرجع API AvalAI: مقدمه
• نمای کلی مدل‌های AvalAI
• راهنمای محدودیت‌های نرخ
• یکپارچه‌سازی AvalAI با افزونه‌های VSCode
• راهنمای انتخاب مدل
• مستندات رسمی OpenAI Codex