اتصال Codex CLI به هوشوانا

Codex CLI دستیار کدنویسی ترمینالی OpenAI است و با Responses API کار می‌کند. هوشوانا نقطه‌ی پایانی /responses را ارائه می‌دهد، پس می‌توانید هوشوانا را به‌عنوان یک ارائه‌دهنده‌ی سفارشی در تنظیمات Codex تعریف کنید.

چه چیزی به دست می‌آورید

• اجرای Codex با مدل‌های OpenAI بدون حساب خارجی.
• پرداخت ریالی از کیف پول هوشوانا.
• ثبت هر درخواست با هزینه و توکن در گزارش‌ها.

پیش‌نیازها

1. حساب کاربری در هوشوانا.
2. یک کلید API از صفحه‌ی کلیدها.
3. اعتبار کافی در کیف پول.
4. Codex CLI نصب‌شده:

npm install -g @openai/codex

روش سریع: نصب‌کننده‌ی یک‌خطی

اگر روی macOS یا Linux کار می‌کنید، می‌توانید تنظیمات را با یک دستور انجام دهید:

curl -fsSL https://hooshvana.ir/install.sh | bash

نصب‌کننده کلید API را از شما می‌پرسد و بعد این کارها را انجام می‌دهد:

• متغیرهای ANTHROPIC_BASE_URL (برابر https://hooshvana.ir/api) و ANTHROPIC_AUTH_TOKEN را برای Claude Code تنظیم می‌کند و سرور MCP هوشوانا را به Claude Code اضافه می‌کند.
• بلوک ارائه‌دهنده‌ی [model_providers.hooshvana] را با base_url = "https://hooshvana.ir/api/v1"، env_key = "HOOSHVANA_API_KEY" و wire_api = "responses" به تنظیمات Codex CLI اضافه می‌کند.
• سرور MCP هوشوانا را در ~/.cursor/mcp.json برای Cursor ثبت می‌کند.
• از هر فایلی که تغییر می‌دهد پیش از تغییر نسخه‌ی پشتیبان می‌گیرد.

پس از اجرای نصب‌کننده، ترمینال را دوباره باز کنید و مطمئن شوید model_provider = "hooshvana" و مدل دلخواه در بالای ~/.codex/config.toml آمده است.

اجرای اسکریپت از اینترنت یعنی به آن اعتماد کرده‌اید. پیشنهاد ما این است که اول محتوای آن را ببینید و بعد اجرا کنید:

curl -fsSL https://hooshvana.ir/install.sh -o install.sh
less install.sh
bash install.sh

اگر می‌خواهید دقیقاً بدانید چه چیزی کجا تنظیم می‌شود، یا روی Windows هستید، مراحل دستی زیر را دنبال کنید. مسیر اصلی و پیشنهادی همین مراحل دستی است.

راه‌اندازی

۱. کلید را در متغیر محیطی بگذارید

Codex کلید ارائه‌دهنده‌ی سفارشی را از متغیری می‌خواند که خودتان نامش را تعیین می‌کنید. در این راهنما نام آن HOOSHVANA_API_KEY است.

macOS و Linux (برای ماندگاری به ~/.zshrc یا ~/.bashrc اضافه کنید):

export HOOSHVANA_API_KEY="hv-YOUR_KEY"

Windows (PowerShell):

$env:HOOSHVANA_API_KEY = "hv-YOUR_KEY"

۲. ارائه‌دهنده را در config.toml تعریف کنید

فایل ~/.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"

توضیح هر کلید:

model و model_provider باید در بالای فایل و پیش از هر جدول [...] بیایند؛ در غیر این صورت TOML آن‌ها را جزو جدول قبلی حساب می‌کند.

بررسی اتصال

در پوشه‌ی یک پروژه یک درخواست غیرتعاملی بفرستید:

codex exec "List the files in this directory and describe the project in one sentence."

یا حالت تعاملی را با codex باز کنید. در سربرگ Codex باید مدل openai/gpt-5.3-codex و ارائه‌دهنده‌ی hooshvana را ببینید. بعد در گزارش‌ها درخواست‌های /responses را با هزینه‌شان پیدا می‌کنید.

برای امتحان یک مدل دیگر بدون تغییر فایل:

codex -m openai/gpt-4.1

مدل‌های پیشنهادی

شناسه‌ها نمونه هستند؛ مدل‌های در دسترس را در کاتالوگ مدل‌ها ببینید. Codex برای Responses API ساخته شده و با مدل‌های OpenAI بهترین نتیجه را می‌دهد.

کنترل هزینه

• برای Codex کلید جداگانه بسازید.
• سقف خرج روزانه و سقف ماهانه بگذارید تا یک حلقه‌ی طولانی عامل، کیف پول را خالی نکند.
• مدل‌های مجاز را به مدل‌هایی که واقعاً در Codex استفاده می‌کنید محدود کنید.
• نقطه‌های پایانی مجاز را روی responses بگذارید.
• برای کارهای ساده مدل ارزان‌تری را با -m انتخاب کنید.

رفع اشکال

اگر مشکل حل نشد، کد خطا و زمان درخواست را در تیکت پشتیبانی بفرستید.