اتصال Cursor به هوشوانا

Cursor ویرایشگر کدی است که اجازه می‌دهد کلید OpenAI خودتان را وارد کنید و آدرس پایه‌ی آن را تغییر دهید. با این دو تنظیم، درخواست‌های چت و Agent به‌جای OpenAI به هوشوانا می‌روند و با اعتبار ریالی شما پرداخت می‌شوند.

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

• دسترسی به مدل‌های چند سازنده در چت Cursor با یک کلید.
• پرداخت ریالی و دیدن هزینه‌ی هر درخواست در گزارش‌های هوشوانا.
• محدود کردن هزینه با قوانین کلید.

پیش‌نیازها

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

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

اگر روی 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 ثبت می‌کند.
• از هر فایلی که تغییر می‌دهد پیش از تغییر نسخه‌ی پشتیبان می‌گیرد.

نصب‌کننده فقط سرور MCP را برای Cursor تنظیم می‌کند. کلید OpenAI و Base URL را باید طبق مراحل زیر در تنظیمات خود Cursor وارد کنید.

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

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

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

راه‌اندازی

1. در Cursor تنظیمات را باز کنید (Cursor Settings) و به بخش Models بروید.
2. بخش API Keys را باز کنید و در قسمت OpenAI API Key کلید هوشوانا (hv-...) را وارد کنید.
3. گزینه‌ی Override OpenAI Base URL را روشن کنید و این آدرس را بنویسید:

https://hooshvana.ir/api/v1

4. در فهرست مدل‌ها روی Add model (یا Add custom model) بزنید و شناسه‌ی کامل مدل را وارد کنید، مثلاً:

openai/gpt-4.1
anthropic/claude-sonnet-4.6
deepseek/deepseek-v4-flash

5. مدل‌هایی را که اضافه کرده‌اید فعال کنید و دکمه‌ی Verify کنار کلید را بزنید.

جای دقیق گزینه‌ها ممکن است در نسخه‌های مختلف Cursor کمی جابه‌جا شود، اما نام‌های OpenAI API Key و Override OpenAI Base URL معمولاً ثابت می‌مانند.

نکته درباره‌ی مدل‌های پیش‌فرض Cursor

وقتی Base URL را عوض می‌کنید، Cursor همه‌ی مدل‌های OpenAI فعال را به همین آدرس می‌فرستد. اگر مدل‌هایی مثل gpt-4o (بدون پیشوند) فعال باشند، هنگام Verify یا استفاده خطای model_not_found می‌گیرید. مدل‌های پیش‌فرضی را که با کلید خودتان استفاده نمی‌کنید غیرفعال کنید و فقط شناسه‌های vendor/model را نگه دارید.

بررسی اتصال

1. پنل چت Cursor را باز کنید.
2. از منوی انتخاب مدل، یکی از مدل‌هایی را که اضافه کرده‌اید انتخاب کنید، مثلاً openai/gpt-4.1.
3. یک سؤال کوتاه بپرسید.
4. به گزارش‌ها بروید. باید درخواستی به /chat/completions با همان مدل و هزینه‌ی آن را ببینید.

Cursor درخواست‌ها را از سرورهای خودش به آدرسی که وارد کرده‌اید می‌فرستد. به همین دلیل اگر برای کلید فهرست IP مجاز گذاشته باشید، درخواست‌های Cursor رد می‌شوند. برای کلید Cursor فهرست IP را خالی بگذارید.

اتصال سرور MCP هوشوانا

هوشوانا یک سرور MCP دارد که به Agent در Cursor امکان می‌دهد از پایگاه‌های دانش شما جست‌وجو کند، فهرست مدل‌ها را ببیند و مصرف حساب را گزارش دهد. این سرور از نوع Streamable HTTP و بدون حالت (stateless) است و با کلید هوشوانا احراز می‌شود. این بخش مستقل از تنظیم کلید OpenAI است و حتی اگر چت Cursor را با مدل‌های خود Cursor استفاده کنید، کار می‌کند.

فایل ~/.cursor/mcp.json را باز کنید (اگر وجود ندارد بسازید) و سرور هوشوانا را اضافه کنید:

{
  "mcpServers": {
    "hooshvana": {
      "url": "https://hooshvana.ir/api/mcp",
      "headers": {
        "Authorization": "Bearer hv-YOUR_KEY"
      }
    }
  }
}

اگر این فایل سرورهای دیگری هم دارد، فقط کلید hooshvana را داخل mcpServers اضافه کنید. ابزارهای در دسترس: search_knowledge_base، list_knowledge_bases، list_models و get_account_usage.

برای بررسی، در تنظیمات Cursor بخش MCP را باز کنید؛ سرور hooshvana باید با نشانگر سبز و فهرست ابزارها دیده شود. جزئیات بیشتر در راهنمای MCP آمده است.

چه چیزهایی از هوشوانا عبور نمی‌کنند

همه‌ی قابلیت‌های Cursor با کلید شخصی کار نمی‌کنند. تکمیل خودکار Tab و برخی قابلیت‌های داخلی مثل اعمال ویرایش‌ها با مدل‌های اختصاصی Cursor اجرا می‌شوند و به هوشوانا نمی‌رسند. برای این قابلیت‌ها همچنان به اشتراک یا سهمیه‌ی خود Cursor نیاز دارید. چت و حالت‌های گفت‌وگو با مدلی که خودتان انتخاب می‌کنید از طریق هوشوانا اجرا می‌شوند. اینکه کدام حالت‌ها با کلید شخصی در دسترس‌اند به نسخه و طرح Cursor شما بستگی دارد.

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

شناسه‌ها نمونه هستند؛ فهرست کامل را در کاتالوگ مدل‌ها ببینید.

کنترل هزینه

• برای Cursor یک کلید جدا بسازید.
• در قوانین کلید سقف خرج روزانه بگذارید.
• در مدل‌های مجاز فقط مدل‌هایی را که در Cursor اضافه کرده‌اید باز بگذارید تا انتخاب اشتباه یک مدل گران هزینه‌ای نسازد.
• نقطه‌های پایانی مجاز را روی chat محدود کنید.
• با سقف توکن در هر درخواست از پاسخ‌های بسیار طولانی جلوگیری کنید.

رفع اشکال

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