پرش به مطلب اصلی

اتصال ابزارهای هوش مصنوعی به چابکان

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

  • OpenAI-compatible برای ابزارهایی که از chat/completions یا responses استفاده می‌کنند.
  • Anthropic-compatible برای ابزارهایی مانند Claude Code که از messages استفاده می‌کنند.

هوش مصنوعی چابکان چیست؟​

هوش مصنوعی چابکان سرویسی برای دسترسی برنامه‌نویسی‌شده به مدل‌های AI از طریق یک درگاه مشترک است. توسعه‌دهنده می‌تواند به‌جای تغییر معماری برنامه برای هر مدل، ابزار یا SDK سازگار را با Base URL چابکان تنظیم کند، کلید دسترسی بسازد و مدل موردنیاز را با Model ID انتخاب کند.

این مستندات کل اکوسیستم اتصال را پوشش می‌دهد: عامل‌های برنامه‌نویسی داخل ترمینال، افزونه‌های VS Code و JetBrains، رابط چت self-hosted، workflowهای اتوماسیون، فریم‌ورک LangChain و برنامه‌هایی که با SDK رسمی OpenAI در زبان‌های مختلف نوشته شده‌اند.

چه کارهایی می‌توان انجام داد؟​

  • استفاده از coding agentهایی مانند Claude Code، Codex، OpenCode، Kilo Code و Aider برای تحلیل و ویرایش کد؛
  • افزودن دستیار AI به VS Code با Cline، Continue، Roo Code یا افزونه‌های رسمی؛
  • ساخت رابط گفت‌وگوی داخلی و چندمدلی با Open WebUI؛
  • خلاصه‌سازی، دسته‌بندی و تولید متن در workflowهای n8n؛
  • توسعه چت‌بات، backend و پردازشگر متن با Python، JavaScript، Go، Java، .NET و Ruby؛
  • پیاده‌سازی streaming، tool calling، ورودی تصویر و مکالمه چندمرحله‌ای.

درگاه مدل به‌تنهایی فایل یا فرمان سیستم شما را اجرا نمی‌کند. قابلیت‌هایی مانند خواندن repository، اجرای shell و اتصال به سرویس‌های دیگر را ابزار agent یا برنامه‌ای که می‌سازید مدیریت می‌کند؛ بنابراین مجوزهای آن بخش را نیز باید جداگانه محدود کنید.

در بیشتر ابزارها فقط سه مقدار لازم است:

تنظیممقدار
Base URL در ابزارهای OpenAI-compatiblehttps://ai.chabokan.net/v1
Base URL در Claude Codehttps://ai.chabokan.net
API Keyکلیدی که از پنل سرویس هوش مصنوعی ساخته‌اید
Model IDشناسه دقیق مدل از زبانه «مدل‌های قابل استفاده»
نکته مهم درباره Base URL

در ابزارهای OpenAI-compatible معمولاً /v1 را وارد کنید. در Claude Code آن را ننویسید، چون خود ابزار مسیر /v1/messages را به آدرس پایه اضافه می‌کند.

راه‌اندازی سریع در سه مرحله​

  1. در پنل چابکان یک سرویس هوش مصنوعی بسازید و اعتبار آن را شارژ کنید.
  2. در زبانه کلیدهای API یک کلید بسازید و در زبانه مدل‌های قابل استفاده شناسه مدل را کپی کنید.
  3. اتصال عمومی را با متغیرهای زیر آماده و سپس راهنمای ابزار خود را دنبال کنید.
$env:OPENAI_BASE_URL = "https://ai.chabokan.net/v1"
$env:OPENAI_API_KEY = "sk-chbk-کلید-واقعی-شما"

این دو متغیر برای ابزارهای OpenAI-compatible هستند. Claude Code نام متغیر و Base URL متفاوتی دارد که در راهنمای اختصاصی آن آمده است.

ابزارها بر اساس پروتکل​

پروتکل درگاهابزارهاوضعیت
Anthropic MessagesClaude Code در ترمینال و VS Codeپشتیبانی‌شده
OpenAI ResponsesCodex در ترمینال و VS Codeپشتیبانی‌شده
OpenAI Chat CompletionsCline، Roo Code، Continue، Aider، OpenCode، Kilo Code، Hermes، Open WebUI، LangChain، 9Router و SDKهاپشتیبانی‌شده
Override سفارشی CursorCursorمحدود و وابسته به نسخه
Gemini native generateContentGemini CLI و Google GenAI SDKپشتیبانی نمی‌شود؛ مدل Gemini را با کلاینت OpenAI-compatible فراخوانی کنید
مدل سفارشی در Claude DesktopClaude Desktopفعلاً تضمین و مستند نشده است

از کدام راهنما استفاده کنم؟​

نیاز شماراهنما
عامل برنامه‌نویسی در ترمینالClaude Code، Codex CLI، Aider، OpenCode یا Kilo Code
عامل برنامه‌نویسی داخل VS Code یا JetBrainsCline، Continue، Roo Code یا Kilo Code
مسیریابی چند provider و fallback محلی9Router
استفاده از CursorCursor و محدودیت‌های آن
افزونه رسمی Claude Code یا Codex در VS Codeراهنمای افزونه‌های VS Code
عامل عمومی در ترمینالHermes Agent
رابط گفت‌وگوی داخلی و چندمدلیOpen WebUI
اتوماسیون workflown8n
توسعه برنامه با LangChainPython و JavaScript
اتصال برنامه یا اسکریپتشروع سریع cURL، Python و Node.js، SDKهای Python، JavaScript، Go، Java، .NET، Ruby، PHP و Rust
مثال‌های پیشرفته APIStreaming، async، ابزارخوانی، تصویر و Responses
انتخاب مدل بر اساس context و toolsراهنمای انتخاب مدل
کلیدها و کنترل هزینه برای تیماستفاده تیمی و Production
خطا یا قطع اتصالعیب‌یابی

مسیر پیشنهادی برای شروع​

  1. ابتدا سرویس، اعتبار، کلید و مدل را آماده کنید.
  2. اتصال را با دستور آزمون همان صفحه بررسی کنید.
  3. راهنمای ابزار موردنظر را انجام دهید.
  4. یک درخواست ساده بفرستید و سپس مصرف آن را در زبانه «گزارش درخواست‌ها» ببینید.

انتخاب ابزار بر اساس سبک کار​

اگر بیشتر در ترمینال کار می‌کنید، Claude Code، Codex، OpenCode، Kilo Code و Aider گزینه‌های طبیعی‌تری هستند. اگر می‌خواهید پیشنهاد و تغییر کد را در editor ببینید، Cline، Continue، Roo Code یا Kilo Code را بررسی کنید. برای ارائه چت به چند کاربر Open WebUI و برای اتصال AI به فرایندهای کسب‌وکار n8n مناسب‌تر است. اگر چند provider را پشت یک endpoint محلی و fallback می‌خواهید، 9Router را بررسی کنید. در پروژه‌ای که کنترل کامل منطق و رابط را می‌خواهید، مستقیماً از SDK رسمی OpenAI یا LangChain استفاده کنید.

پرسش‌های پرتکرار​

آیا برای هر ابزار API Key جدا لازم است؟​

از نظر فنی می‌توان یک کلید را استفاده کرد، اما برای امنیت، گزارش‌گیری و لغو مستقل بهتر است هر ابزار و محیط کلید جدا با نام و سقف مصرف مشخص داشته باشد.

آیا می‌توان مدل‌های Gemini را با SDK OpenAI فراخوانی کرد؟​

بله، اگر مدل موردنظر در فهرست مدل‌های سرویس شما موجود باشد، شناسه آن را در یک کلاینت OpenAI-compatible قرار دهید. endpoint بومی Google مانند generateContent در این راهنما مبنای اتصال نیست.

چرا اتصال ساده کار می‌کند اما Agent ابزار اجرا نمی‌کند؟​

پاسخ متنی فقط سلامت اتصال را نشان می‌دهد. agent به مدلی با tool calling مناسب، context کافی و مجوزهای صحیح در خود ابزار نیاز دارد. راهنمای انتخاب مدل و عیب‌یابی را بررسی کنید.

API Key را کجا نگه دارم؟​

در محیط production از secret manager و در توسعه محلی از environment یا credential store ابزار استفاده کنید. کلید را در source code، Git، تصویر یا فایل exportشده قرار ندهید.

ساختار راهنماها​

راهنماها فقط مقدار Base URL را فهرست نمی‌کنند. هر اتصال در صورت نیاز این لایه‌ها را پوشش می‌دهد:

پیش‌نیاز → نصب → نگهداری امن کلید → پیکربندی → آزمون ساده
        → آزمون ابزارخوانی → مرز قابلیت‌ها → عیب‌یابی → Production

به‌دلیل تغییر نسخه ابزارها و فهرست مدل‌ها، Model ID را همیشه از پنل یا /v1/models بردارید و بخش منابع رسمی انتهای هر صفحه را نیز ببینید.