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

خطای اتصال یک ابزار AI ممکن است در شبکه، احراز هویت، اعتبار حساب، انتخاب مدل، پروتکل API یا تنظیمات خود ابزار رخ دهد. روش مؤثر این است که لایه‌ها را جداگانه آزمایش کنید: ابتدا سلامت درگاه، بعد API Key و Model ID و در پایان پیکربندی Claude Code، Codex، OpenCode یا ابزار دیگر.

این راهنما هم برای خطاهای اولیه نصب و هم برای اختلال‌های محیط production کاربرد دارد. متن کامل خطا، status code و X-Request-Id معمولاً مهم‌تر از پیام خلاصه‌ای است که رابط گرافیکی نشان می‌دهد.

روش تشخیص سریع

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

۱. بررسی دسترسی شبکه

curl --fail-with-body https://ai.chabokan.net/health

۲. بررسی کلید و فهرست مدل‌ها

curl --fail-with-body https://ai.chabokan.net/v1/models \
  -H "Authorization: Bearer $CHABOKAN_AI_API_KEY"

۳. بررسی یک درخواست ساده

curl --fail-with-body https://ai.chabokan.net/v1/chat/completions \
  -H "Authorization: Bearer $CHABOKAN_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "سلام"}]
  }'

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

health ناموفق → شبکه یا دسترسی به دامنه
models ناموفق → کلید، وضعیت سرویس یا اعتبار
chat ناموفق → Model ID، payload یا قابلیت مدل
cURL موفق و ابزار ناموفق → Base URL، پروتکل یا تنظیمات ابزار

جدول خطاهای رایج

وضعیت یا پیام	علت معمول	راه‌حل
401 Missing API key	کلید ارسال نشده است	نام متغیر و اجرای ابزار از همان shell را بررسی کنید
401 Invalid API key	کلید ناقص، اشتباه یا لغوشده است	کلید را دوباره paste کنید یا کلید جدید بسازید
API key is disabled	کلید در پنل لغو شده است	کلید فعال تازه بسازید
API key has expired	تاریخ انقضای کلید گذشته است	کلید تازه با تاریخ مناسب بسازید
402 AI credit exhausted	اعتبار مصرف مدل تمام شده است	زبانه «اعتبار و شارژ» را شارژ کنید
402 Monthly usage cap reached	سقف ماهانه کلید رسیده است	سقف را افزایش دهید یا تا دوره بعد صبر کنید
404 Unknown path	Base URL یا مسیر دوبار/ناقص شده است	قواعد Base URL پایین صفحه را بررسی کنید
404 یا model not found	شناسه مدل غلط یا خارج از پلن است	شناسه را از «مدل‌های قابل استفاده» عیناً کپی کنید
429 rate limit	تعداد درخواست در دقیقه بیش از پلن است	هم‌زمانی را کم و با فاصله retry کنید
5xx	خطای موقت درگاه یا تأمین‌کننده مدل	X-Request-Id را نگه دارید و با backoff دوباره تلاش کنید

قاعده Base URL در هر ابزار

ابزار	Base URL درست
Claude Code	https://ai.chabokan.net
Codex، Cline، Roo Code، Continue، Aider، OpenCode، Kilo Code، Hermes، Open WebUI، LangChain و SDK OpenAI	https://ai.chabokan.net/v1
9Router به‌عنوان upstream	https://ai.chabokan.net/v1
ابزار متصل به 9Router محلی	http://localhost:20128/v1
n8n با HTTP Request	URL کامل: https://ai.chabokan.net/v1/chat/completions

نشانه خطای رایج Claude Code مسیر /v1/v1/messages است؛ /v1 را از ANTHROPIC_BASE_URL حذف کنید.

متغیر محیطی به ابزار نمی‌رسد

در macOS، Linux و WSL:

test -n "$CHABOKAN_AI_API_KEY" && echo "key is set" || echo "key is missing"

برای Claude Code:

test -n "$ANTHROPIC_AUTH_TOKEN" && echo "token is set" || echo "token is missing"

در PowerShell:

if ($env:CHABOKAN_AI_API_KEY) { "key is set" } else { "key is missing" }

اگر ابزار را از آیکون گرافیکی اجرا کرده‌اید، ممکن است environment ترمینال را به ارث نبرده باشد. ابزار را از همان ترمینال باز کنید یا secret را در تنظیمات امن خود ابزار ثبت کنید.

مدل پاسخ می‌دهد اما ابزارخوانی خراب است

ابزارهای agent به function/tool calling قوی نیاز دارند. این مراحل را انجام دهید:

1. از پنل، مدلی با پشتیبانی ابزارخوانی انتخاب کنید.
2. شناسه مدل را در همه محل‌های config یکسان کنید.
3. ابتدا حالت ساده chat را آزمایش کنید.
4. سپس یک درخواست فقط خواندنی برای مشاهده فایل بدهید.
5. در Continue قابلیت tool_use را فقط برای مدل پشتیبان اضافه کنید.

اطلاعات لازم برای ارسال به پشتیبانی

این موارد را ارسال کنید:

• نام و نسخه ابزار و سیستم‌عامل
• زمان تقریبی رخداد با منطقه زمانی
• endpoint استفاده‌شده، بدون API Key
• شناسه مدل
• status code و متن خطا
• مقدار X-Request-Id پاسخ یا شناسه درخواست در پنل

هرگز کلید کامل، محتوای محرمانه prompt یا فایل‌های خصوصی پروژه را ارسال نکنید.