اتصال Cursor و Codex CLI به API ایرانی

Cursor و Codex دو ابزار محبوب کدنویسی با هوش مصنوعی‌اند، با دو فلسفه‌ی متفاوت. Cursor یک ویرایشگر کامل بر پایه‌ی VS Code است که هوش مصنوعی را در دل محیط توسعه قرار می‌دهد. Codex CLI از OpenAI در ترمینال اجرا می‌شود و مثل یک عامل، کارها را خودش پیش می‌برد. هر دو را می‌توانید با API هوشوانا و پرداخت ریالی استفاده کنید. در این راهنما تنظیمات هر دو را قدم‌به‌قدم انجام می‌دهیم.

پیش از شروع: ساخت کلید

در داشبورد هوشوانا یک کلید API بسازید. پیشنهاد می‌کنیم برای هر ابزار کلید جدا بسازید، مثلاً «Cursor» و «Codex»، تا در گزارش مصرف ببینید هر کدام چقدر هزینه دارد. روی هر کلید سقف خرج روزانه بگذارید و دسترسی را به گروه «کدنویسی» محدود کنید.

بخش اول: Cursor

Cursor اجازه می‌دهد آدرس پایه‌ی API سازگار با OpenAI را تغییر دهید. مراحل:

1. Cursor را باز کنید و به Settings و بعد بخش Models بروید.
2. در قسمت OpenAI API Key، کلید هوشوانا را وارد کنید.
3. گزینه‌ی Override OpenAI Base URL را فعال کنید و آدرس https://hooshvana.ir/api/v1 را بنویسید.
4. با دکمه‌ی Add Model، شناسه‌ی مدل‌هایی را که می‌خواهید اضافه کنید، مثلاً anthropic/claude-sonnet-5.5 یا openai/gpt-6.1-sol.
5. دکمه‌ی Verify را بزنید. اگر پیام موفقیت دیدید، اتصال برقرار است.

کدام قابلیت‌های Cursor کار می‌کنند؟

قابلیت‌هایی که از کلید شخصی استفاده می‌کنند، مثل چت، Composer و حالت Agent، با مدل‌های هوشوانا کار می‌کنند. برخی قابلیت‌های داخلی Cursor مثل Tab که از مدل‌های اختصاصی خود Cursor استفاده می‌کند، به اشتراک Cursor وابسته‌اند و از کلید شخصی استفاده نمی‌کنند.

پیشنهاد مدل برای Cursor

بخش دوم: Codex CLI

Codex CLI از API Responses شرکت OpenAI استفاده می‌کند و هوشوانا این API را کامل پشتیبانی می‌کند. ابتدا Codex را نصب کنید:

npm install -g @openai/codex

حالا فایل تنظیمات را در مسیر ‎~/.codex/config.toml بسازید یا ویرایش کنید:

model = "openai/gpt-5.3-codex"
model_provider = "hooshvana"

[model_providers.hooshvana]
name = "Hooshvana"
base_url = "https://hooshvana.ir/api/v1"
env_key = "HOOSHVANA_API_KEY"
wire_api = "responses"

کلید را در متغیر محیطی قرار دهید:

export HOOSHVANA_API_KEY="hv-کلید-شما"

این خط را به ‎~/.zshrc یا ‎~/.bashrc اضافه کنید تا همیشه در دسترس باشد. حالا داخل پوشه‌ی پروژه دستور codex را اجرا کنید.

انتخاب مدل در Codex

Codex برای مدل‌های OpenAI بهینه شده و بهترین نتیجه را با GPT-5.3 Codex یا GPT-6.1 Sol می‌گیرید. اما چون هوشوانا همه‌ی مدل‌ها را با یک API ارائه می‌دهد، می‌توانید مدل‌های دیگر را هم امتحان کنید:

codex --model anthropic/claude-sonnet-5.5
codex --model deepseek/deepseek-v4-pro

برای کار روزمره GPT-5.3 Codex را پیشنهاد می‌کنیم و برای کارهای سنگین‌تر GPT-6.1 Sol را. اگر بودجه محدود است، DeepSeek V4 Pro با هزینه‌ی بسیار کمتر نتیجه‌ی قابل قبولی می‌دهد.

رفع خطاهای رایج

خطای «model not found»: شناسه‌ی مدل را کامل و دقیق بنویسید، با نام سازنده، مثل openai/gpt-5.3-codex. فهرست کامل شناسه‌ها در صفحه‌ی مدل‌های هوشوانا هست.

خطای ۴۰۱: کلید درست تنظیم نشده است. در Codex مطمئن شوید نام متغیر در env_key با نام متغیر محیطی یکی است و ترمینال را پس از تغییر دوباره باز کرده‌اید.

خطای ۴۰۲: موجودی کیف پول کم است. Codex و Cursor در حالت Agent کانتکست زیادی می‌فرستند و پیش از هر درخواست، هزینه‌ی بدترین حالت تخمین زده می‌شود. کیف پول را شارژ کنید.

خطای ۴۲۹: به محدودیت تعداد درخواست در دقیقه رسیده‌اید که روی کلید تنظیم کرده‌اید. عدد را در تنظیمات کلید بالاتر ببرید.

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

نکته‌های صرفه‌جویی

• در Cursor برای سؤال‌های کوتاه مدل ارزان انتخاب کنید و حالت Agent را برای کارهای واقعاً چندمرحله‌ای نگه دارید.
• در Codex برای پروژه یک فایل AGENTS.md بنویسید تا عامل برای فهمیدن ساختار، کل مخزن را نخواند.
• وقتی کار عوض شد، جلسه‌ی تازه شروع کنید تا کانتکست قدیمی ارسال نشود.
• گزارش مصرف هر کلید را هفته‌ای یک بار ببینید.

Cursor یا Codex؟

اگر بیشتر وقت‌تان داخل ویرایشگر است و می‌خواهید تغییرات را خط‌به‌خط ببینید، Cursor راحت‌تر است. اگر می‌خواهید کار را به عامل بسپارید و فقط نتیجه را بازبینی کنید، Codex یا Claude Code مناسب‌ترند. خیلی از تیم‌ها هر دو را استفاده می‌کنند: Cursor برای کار روزانه و Codex برای کارهای طولانی مثل نوشتن تست یا مهاجرت کد.

استفاده در تیم

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

جمع‌بندی

با یک کلید هوشوانا، هم Cursor و هم Codex CLI به همه‌ی مدل‌های مطرح دسترسی پیدا می‌کنند و شما هزینه را با تومان می‌پردازید. در Cursor آدرس پایه را عوض کنید و مدل‌ها را اضافه کنید، در Codex یک ارائه‌دهنده‌ی سفارشی در config.toml تعریف کنید و بعد بدون نگرانی از تحریم و کارت ارزی کد بنویسید.