اتصال Cline و Roo Code به هوشوانا

راهنمای اتصال Cline و Roo Code در VS Code به هوشوانا با ارائه‌دهنده‌ی OpenAI Compatible، انتخاب Model ID، کنترل هزینه و رفع خطاهای رایج.

آخرین به‌روزرسانی: ۲۲ مهر ۱۴۰۵

Cline

افزونه‌ی VS Code

شروع رایگان

Cline و Roo Code (که از Cline منشعب شده) دستیارهای کدنویسی عامل‌محور داخل VS Code هستند. هر دو ارائه‌دهنده‌ای به نام OpenAI Compatible دارند که با هوشوانا کار می‌کند. تنظیمات دو افزونه تقریباً یکسان است و این راهنما برای هر دو کاربرد دارد.

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

دسترسی به مدل‌های OpenAI، Anthropic، Google، DeepSeek و سازنده‌های دیگر از یک ارائه‌دهنده.
پرداخت ریالی و دیدن هزینه‌ی هر کار در گزارش‌ها.
امکان عوض کردن مدل فقط با تغییر Model ID.

پیش‌نیازها

حساب کاربری در هوشوانا.
یک کلید API از صفحه‌ی کلیدها.
اعتبار کافی در کیف پول.
افزونه‌ی Cline یا Roo Code نصب‌شده در VS Code (یا ویرایشگرهای مبتنی بر آن).

راه‌اندازی

پنل Cline یا Roo Code را از نوار کناری باز کنید و روی آیکون تنظیمات بزنید.
در API Provider گزینه‌ی OpenAI Compatible را انتخاب کنید.
فیلدها را این‌طور پر کنید:

فیلد	مقدار
Base URL	`https://hooshvana.ir/api/v1`
API Key	`hv-YOUR_KEY`
Model ID	`anthropic/claude-sonnet-4.6` (یا هر مدل دیگر)

در بخش تنظیمات مدل (Model Configuration)، اگر نمایش داده می‌شود، Context Window را مطابق مدل انتخابی بگذارید و اگر مدل تصویر می‌پذیرد گزینه‌ی Supports Images را روشن کنید. این اعداد را از صفحه‌ی همان مدل در کاتالوگ مدل‌ها بردارید.
تنظیمات را ذخیره کنید.

برای استفاده از مدل‌های Claude نیازی به انتخاب ارائه‌دهنده‌ی Anthropic نیست. با همان OpenAI Compatible و Model ID مثل anthropic/claude-sonnet-4.6، هوشوانا درخواست را به مدل درست می‌رساند.

بررسی اتصال

در پنل افزونه یک کار ساده بنویسید، مثلاً «فایل README این پروژه را خلاصه کن».
اگر پاسخ آمد، اتصال برقرار است.
در گزارش‌ها درخواست‌های /chat/completions را با مدل و هزینه ببینید.

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

کاربرد	مدل
کارهای عامل‌محور و ویرایش چندفایلی	`anthropic/claude-sonnet-4.6`
کدنویسی با هزینه‌ی کمتر	`deepseek/deepseek-v4-flash` یا `openai/gpt-4.1`
برنامه‌ریزی و استدلال (حالت Plan)	`deepseek/deepseek-r1-0528` یا `google/gemini-2.5-pro`

Cline و Roo Code به فراخوانی ابزار و پیروی دقیق از دستورالعمل وابسته‌اند. مدل‌های کوچک گاهی قالب پاسخ را رعایت نمی‌کنند و کار نیمه‌کاره می‌ماند. شناسه‌ها نمونه هستند؛ فهرست کامل در کاتالوگ مدل‌ها است.

کنترل هزینه

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

برای افزونه کلید جداگانه بسازید و سقف خرج روزانه بگذارید.
در مدل‌های مجاز فقط مدل‌هایی را که استفاده می‌کنید باز بگذارید.
نقطه‌های پایانی مجاز را روی chat محدود کنید.
در تنظیمات افزونه، تأیید خودکار (Auto-approve) را با احتیاط و با سقف تعداد درخواست روشن کنید.
برای کار تازه، گفت‌وگوی تازه شروع کنید تا تاریخچه‌ی قبلی دوباره فرستاده نشود.

رفع اشکال

خطا	علت رایج	راه‌حل
`401 invalid_api_key`	کلید ناقص کپی شده یا فاصله‌ی اضافه دارد	کلید را دوباره و بدون فاصله وارد کنید
`404 model_not_found`	Model ID بدون پیشوند نوشته شده، مثل `claude-sonnet-4.6`	شناسه‌ی کامل مثل `anthropic/claude-sonnet-4.6` بنویسید
`403 model_not_allowed`	مدل در قوانین کلید مجاز نیست	مدل را به فهرست مجاز کلید اضافه کنید
`402 insufficient_balance`	موجودی کافی نیست یا `max_tokens` بالا برآورد هزینه را از موجودی بیشتر کرده	کیف پول را شارژ کنید یا سقف خروجی را کم کنید
`404` بدون کد خطای هوشوانا	Base URL اشتباه است، مثلاً `/chat/completions` به انتهای آن اضافه شده	فقط `https://hooshvana.ir/api/v1` را بنویسید
`429 rate_limited`	افزونه در زمان کوتاه درخواست زیادی فرستاده	RPM کلید را بالا ببرید یا چند ثانیه صبر کنید
پاسخ‌های ناقص یا «مدل از ابزار استفاده نکرد»	مدل انتخابی برای کار عامل‌محور ضعیف است	یک مدل قوی‌تر مثل `anthropic/claude-sonnet-4.6` انتخاب کنید

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