کرسر و کلاین را به API دلخواه وصل کنید؛ راهنمای Base URL

کرسر را نصب کرده‌اید یا کلاین را روی VS Code گذاشته‌اید و هر دو از شما یک چیز می‌خواهند: یک کلید API. کلید را از هر جایی که تهیه کرده‌اید در فیلد می‌گذارید، ابزار همچنان به api.openai.com می‌زند و نتیجه یا خطای شبکه است یا خطای دسترسی. تقریباً همیشه راه‌حل یک فیلد کوچک است که در هر ابزار اسم دیگری دارد: Base URL. این مقاله همان فیلد است؛ اینکه در کرسر، کلاین، Roo Code و چند ابزار دیگر کجاست، دقیقاً چه چیزی باید داخلش بنویسید و وقتی کار نکرد از کجا شروع به عیب‌یابی کنید.

«سازگار با OpenAI» یعنی چه و چرا فقط همین یک فیلد کافی است؟

هر ابزاری که با مدل زبانی حرف می‌زند، در نهایت یک درخواست HTTP ساده می‌فرستد: یک POST به مسیر /chat/completions، با یک هدر Authorization: Bearer … و یک بدنهٔ JSON که داخلش نام مدل و پیام‌ها هست. جواب هم با همان ساختار برمی‌گردد. این قالب را OpenAI تعریف کرد و بعد به یک استاندارد عملی در کل صنعت تبدیل شد.

نتیجهٔ عملی‌اش این است: هر سرویسی که همین قالب را بفهمد، از دید ابزار شما فرقی با OpenAI ندارد. کافی است ابزار به‌جای آدرس پیش‌فرض، آدرس شما را صدا بزند. به همین دلیل است که تقریباً همهٔ ادیتورها و افزونه‌های کدنویسی هوش مصنوعی جایی در تنظیماتشان فیلدی به نام Base URL، API Base، Endpoint یا Override دارند. سازندهٔ ابزار آن فیلد را برای مدل‌های محلی و سرویس‌های شرکتی گذاشته، اما دقیقاً همان فیلد برای شما هم کار می‌کند.

سرویس API نِت اَرز هم دقیقاً همین قالب را می‌فهمد؛ یعنی هر ابزاری که فیلد Base URL داشته باشد، بدون تغییر یک خط کد به آن وصل می‌شود. توضیح کامل سرویس در صفحهٔ API هوش مصنوعی و جزئیات فنی مسیرها در مستندات فنی آمده است.

سه چیزی که قبل از باز کردن تنظیمات باید آماده داشته باشید

• آدرس پایه: https://netarz.ir/api/ai/v1 — دقیقاً همین، بدون اسلش انتهایی. این آدرس شامل /v1 هست؛ در ادامه می‌بینید که همین یک نکته منشأ بیشترین خطاهاست.
• کلید: کلیدی که در پنل می‌سازید و با sk-ntz-v1- شروع می‌شود. کلید کامل فقط یک بار نمایش داده می‌شود، پس همان لحظه ذخیره‌اش کنید. برای هر ابزار یک کلید جدا بسازید تا اگر یکی لو رفت، بقیه سالم بمانند.
• نام دقیق مدل: ابزار هرچه شما بنویسید را عیناً می‌فرستد. نام‌ها را از فهرست مدل‌ها بردارید و کپی کنید، نه از حافظه. در حال حاضر مدل‌های OpenAI مثل gpt-5، gpt-5-mini و gpt-4.1 فعال‌اند و بقیهٔ ارائه‌دهنده‌ها در حال اتصال هستند؛ پس نام مدلی بنویسید که همین حالا در آن فهرست می‌بینید.

قبل از هر تنظیمی، یک تست سی‌ثانیه‌ای بگیرید. اگر این دستور جواب داد، مشکل بعدی هرچه باشد از سرویس نیست و از تنظیمات ابزار است:

curl https://netarz.ir/api/ai/v1/chat/completions \
  -H "Authorization: Bearer sk-ntz-v1-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5-mini","messages":[{"role":"user","content":"سلام"}]}'

کرسر: فیلد Override OpenAI Base URL کجاست؟

کرسر یک بخش مخصوص مدل‌ها در تنظیماتش دارد. مسیر کلی این است: پنل تنظیمات کرسر را باز کنید (از منوی چرخ‌دنده یا میان‌بر تنظیمات) و به بخش Models بروید. پایین فهرست مدل‌ها، بخشی برای کلید OpenAI هست و زیر آن گزینه‌ای با عنوان Override OpenAI Base URL قرار دارد.

1. در فیلد کلید، کلید sk-ntz-v1-… خودتان را بگذارید.
2. گزینهٔ Override OpenAI Base URL را فعال کنید و https://netarz.ir/api/ai/v1 را داخلش بنویسید.
3. در فهرست مدل‌ها، مدلی که می‌خواهید استفاده کنید را اضافه کنید. نام باید عیناً همان چیزی باشد که سرویس می‌شناسد. اگر مدل‌های دیگری در فهرست تیک‌خورده‌اند که سرویس شما آن‌ها را ارائه نمی‌کند، تیکشان را بردارید تا کرسر سراغشان نرود.
4. دکمهٔ تأیید یا Verify را بزنید. کرسر یک درخواست آزمایشی می‌فرستد؛ اگر سبز شد، اتصال برقرار است.

حالا نکتهٔ صادقانه‌ای که فروشنده‌ها نمی‌گویند: کلید شخصی در کرسر همهٔ قابلیت‌ها را باز نمی‌کند. بخشی از امکانات کرسر — به‌ویژه تکمیل خودکار درون‌خطی (Tab) و بعضی مراحل داخلی عامل کدنویسی — روی زیرساخت خود کرسر اجرا می‌شود و به اشتراک آن سرویس گره خورده است، نه به کلیدی که شما وارد می‌کنید. یعنی با کلید شخصی معمولاً گفتگو و درخواست‌های مدل کار می‌کند، اما انتظار نداشته باشید تجربهٔ کامل اشتراک را رایگان به دست بیاورید. کرسر این رفتار را هر چند نسخه یک بار تغییر می‌دهد؛ پیش از تصمیم‌گیری همان صفحهٔ تنظیمات را بخوانید. اگر هدفتان خرید خود اشتراک است، آن را در راهنمای Cursor و خرید اشتراک آن جداگانه توضیح داده‌ایم.

کلاین و Roo Code: گزینهٔ OpenAI Compatible

کلاین (Cline) و نسخهٔ منشعب‌شده‌اش Roo Code، افزونهٔ VS Code هستند و برخلاف کرسر هیچ سرویس ابری اختصاصی ندارند؛ یعنی صددرصد کارشان با کلید شما انجام می‌شود و برای این سناریو انتخاب تمیزتری‌اند.

1. افزونه را از نوار کناری باز کنید و آیکون چرخ‌دنده (Settings) را بزنید.
2. در فهرست کشویی API Provider، به‌جای OpenAI گزینهٔ OpenAI Compatible را انتخاب کنید. این گزینه دقیقاً برای همین کار گذاشته شده است.
3. سه فیلد ظاهر می‌شود: Base URL (آدرس https://netarz.ir/api/ai/v1)، API Key (کلید شما) و Model ID (نام دقیق مدل). برخلاف حالت OpenAI، اینجا فهرست کشویی مدل نمی‌بینید و باید نام را دستی تایپ کنید؛ یک حرف اشتباه یعنی خطا.
4. در تنظیمات پیشرفتهٔ همان صفحه معمولاً می‌توانید اندازهٔ پنجرهٔ متن و پشتیبانی از تصویر را برای مدل دلخواه اعلام کنید. اگر این عدد را خیلی کوچک بگذارید، افزونه پیش از ارسال، تاریخچه را می‌برد و مدل نصف کد را نمی‌بیند.

Roo Code دقیقاً همین مسیر را دارد و اگر با یکی راه بیفتید، دیگری هم برایتان آشناست. برای هر پروژه یک پروفایل جدا بسازید تا بتوانید بین مدل ارزان برای کارهای روزمره و مدل گران برای بازسازی‌های سنگین جابه‌جا شوید.

بقیهٔ ابزارها: همان فیلد، اسم متفاوت

الگو همه‌جا یکی است. فقط باید بدانید سازندهٔ آن ابزار اسمش را چه گذاشته:

همین منطق در ابزارهای بدون کد هم صادق است؛ اتصال n8n و Make را جداگانه در راهنمای اتصال n8n و Make با یک base_url نوشته‌ایم.

وقتی جواب نمی‌دهد؛ پنج خطای رایج و علتشان

• خطای 404 روی مسیر: شایع‌ترین علت، اسلش انتهایی یا /v1 تکراری است. بعضی ابزارها خودشان /v1 را به آدرس شما اضافه می‌کنند و نتیجه /v1/v1/chat/completions می‌شود. اگر خطای مسیر گرفتید، یک بار با /v1 و یک بار بدون آن امتحان کنید و به آدرسی که در لاگ خطا چاپ می‌شود دقت کنید.
• خطای مربوط به مدل: پیامی شبیه «model not found» یعنی نام مدل را سرویس نمی‌شناسد. نام را از فهرست مدل‌ها کپی کنید. اگر مدلی از ارائه‌دهنده‌ای می‌خواهید که هنوز فعال نشده، همین خطا را می‌گیرید.
• خطای 401: کلید اشتباه است یا موقع کپی یک فاصله یا خط جدید هم آمده. کلید را دوباره از پنل کپی کنید. اگر برای کلید فهرست IP مجاز تعریف کرده‌اید و IP شما عوض شده، همین خطا را می‌بینید.
• پاسخ نصفه یا قطع‌شده: معمولاً به پنجرهٔ متن مربوط است. اگر در تنظیمات ابزار اندازهٔ نادرستی اعلام کرده‌اید، ابزار ورودی را می‌برد یا خروجی زودتر تمام می‌شود.
• ابزار وصل می‌شود اما یک قابلیت خاص کار نمی‌کند: این تقریباً همیشه یعنی آن قابلیت اصلاً از مسیر مدل نمی‌گذرد و به سرویس داخلی خود ابزار وابسته است. با تغییر Base URL برنمی‌گردد.

هزینه: عامل کدنویسی چقدر توکن می‌خورد؟

یک نکتهٔ مهم که تازه‌کارها را غافلگیر می‌کند: عامل‌های کدنویسی سخاوتمندانه توکن مصرف می‌کنند. هر بار که کلاین فایلی را می‌خواند، محتوای آن فایل وارد ورودی می‌شود؛ یک بازسازی چندمرحله‌ای روی پروژهٔ متوسط، به‌راحتی چند صد هزار توکن ورودی می‌سازد. سه کار ساده جلوی هزینهٔ غیرمنتظره را می‌گیرد:

• برای کارهای روزمره (توضیح کد، تست‌نویسی، تغییرات کوچک) مدل سبک‌تر بگذارید و مدل قوی را برای مسائل واقعاً سخت نگه دارید.
• روی کلیدی که به ابزار می‌دهید سقف هزینه تعیین کنید. یک حلقهٔ اشتباه در عامل خودکار می‌تواند در چند دقیقه اعتبار بسوزاند.
• گزارش مصرف را هفتهٔ اول هر روز نگاه کنید تا حس واقعی از هزینهٔ کار خودتان پیدا کنید. روش محاسبه را در توکن چیست و هزینهٔ API چطور حساب می‌شود با مثال آورده‌ایم.

اشتراک بخرم یا با کلید کار کنم؟

جواب به ابزارتان بستگی دارد و برای همه یکسان نیست. اگر تجربهٔ کامل کرسر — به‌خصوص تکمیل خودکار درون‌خطی — برایتان مهم است، مسیر درست خرید اشتراک همان سرویس است و کلید شخصی جایگزینش نمی‌شود. اگر با کلاین، Roo Code یا Aider کار می‌کنید، کل پردازش با کلید شماست و پرداخت به‌ازای مصرف معمولاً برای استفادهٔ متوسط منطقی‌تر درمی‌آید. مقایسهٔ عددی این دو مسیر را در تفاوت API و اشتراک نوشته‌ایم و اگر برنامه‌نویسید و بین ابزارها مردد، گیت‌هاب کوپایلوت برای برنامه‌نویسان ایرانی گزینهٔ سومی است که ارزش نگاه کردن دارد.

برای شروع، از صفحهٔ سرویس API یک کلید بسازید، اعتبار کوچکی شارژ کنید و اول با همان دستور curl بالا تست بگیرید؛ بعد سراغ تنظیمات ابزار بروید. قیمت لحظه‌ای شارژ اعتبار در صفحهٔ محصول درج شده و مالیات بر ارزش افزوده هنگام پرداخت جداگانه نمایش داده می‌شود. اگر هم تصمیمتان خرید اشتراک ابزار است، پلن‌ها را در دستهٔ اکانت هوش مصنوعی ببینید.

فایل تنظیم Continue، آمادهٔ کپی

تنظیم هر سه ابزار، Cursor و Cline و Continue، در یک جدول در integrations/editors آمده و فایل continue-config.yaml همان‌جا آمادهٔ کپی است. دو نکته از همان راهنما که زیاد پرسیده می‌شود: Cursor درخواست را از سرورهای خودش می‌فرستد، پس فهرست IP مجاز این کلید را خالی بگذارید؛ و تکمیل خودکار خط‌به‌خط (FIM) را به این درگاه نسپارید. اگر تنظیمی در نسخهٔ ابزار شما جای دیگری است، در بخش Issues همان مخزن بنویسید.