راه‌اندازی Claude Code روی API واسط: تنظیم ANTHROPIC_BASE_URL و رفع اشکال گام‌به‌گام
راه‌اندازی Claude Code روی API واسط: راهنمای ANTHROPIC_BASE_URL
Claude Code به‌عنوان یک ابزار خط فرمان، خودش مدل ندارد؛ این یک کلاینت است که درخواست‌هایش را به یک نقطه پایانی می‌فرستد. به‌صورت پیشفرض آن نقطه پایانی، API رسمی Anthropic است، اما Claude Code امکان بازنویسی آدرس پایه را به‌صورت مستند دارد. اگر آن آدرس را به یک نقطه پایانی سازگار با Anthropic تغییر دهید، همان جریان کاری روی مدل‌هایی اجرا میشود که آن نقطه پایانی ارائه می‌دهد.
این مقاله فقط دربارهٔ همین سازوکار است: کدام متغیر محیطی چه کاری می‌کند، دو روش تنظیم آن، و ترتیبی که باید عیب‌یابی را بر اساس آن پیش ببرید تا حدس زدن جای خود را به تشخیص بدهد.
دامنهٔ آنچه در این مقاله بررسی شده
آدرس‌ها و شناسه‌های مدل در این مقاله با مستندات عمومی EXAIV و فهرست زندهٔ مدل‌ها (/docs/api/anthropic-messages و /models) هم‌خوان است. بازنویسی آدرس پایه یک قابلیت مستند خود Claude Code است؛ ولی پشتیبانی رسمی Anthropic از مسیردهی Claude Code به مدلهای غیرClaude وجود ندارد و این متن هم چنین ادعایی نمی‌کند. آنچه در ادامه می‌آید یک جریان کاری سازگاری از سمت واسط است، نه تأییدیهٔ رسمی.
متغیرهایی که واقعاً مهم‌اند
| متغیر | کارکرد | نکته |
|---|---|---|
ANTHROPIC_BASE_URL | مقصد ارسال درخواست‌ها | ریشهٔ نقطه پایانی سازگار؛ در EXAIV: https://exaiv.com/api/ai/v1/anthropic |
ANTHROPIC_API_KEY | کلید API | در سرآیند x-api-key فرستاده میشود؛ Anthropic و بیشتر واسط‌ها از همین استفاده میکنند |
ANTHROPIC_AUTH_TOKEN | توکن Bearer | در سرآیند Authorization: Bearer فرستاده میشود؛ تنها اگر نقطه پایانی آن را بخواهد |
ANTHROPIC_MODEL | مدل پیشفرض | شناسهٔ مدلی که نقطه پایانی پشتیبانی می‌کند، مثلاً claude-opus-5-5 |
ANTHROPIC_DEFAULT_SONNET_MODEL و ANTHROPIC_DEFAULT_HAIKU_MODEL | نگاشت tier | درخواستهای کوچک پسزمینه را به مدلی می‌فرستد که واقعاً روی نقطه پایانی وجود دارد |
شایع‌ترین خطا
بیشتر شکست‌های اتصال ربطی به سازگاری نقطه پایانی ندارند؛ متغیرها به پوستهٔ فعلی نرسیده‌اند: پنجرهٔ ترمینال دیگر، فایل تنظیمات اشتباه، یا دو تنظیم که روی هم می‌افتند. عیب‌یابی را همیشه از متغیرهای محیطی شروع کنید.
روش اول: settings.json (پیشنهادی، ماندگار)
Claude Code متغیرهای محیطی را از ~/.claude/settings.json می‌خواند. این روش روی همهٔ نشست‌ها اثر می‌گذارد و برای یکسان‌سازی در تیم ساده‌ترین شکل است. نمونه برای EXAIV:
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"env": {
"ANTHROPIC_BASE_URL": "https://exaiv.com/api/ai/v1/anthropic",
"ANTHROPIC_API_KEY": "YOUR_EXAIV_API_KEY",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
},
"model": "claude-opus-5-5"
}
بعد از ذخیره، claude را دوباره اجرا کنید. اگر می‌خواهید این بازنویسی فقط برای یک پروژه باشد، همان ساختار را در .claude/settings.json در ریشهٔ پروژه بگذارید.
روش دوم: متغیر موقت در پوسته (آزمون سریع)
بدون تغییر فایل، در همان پوسته صادر کنید:
export ANTHROPIC_BASE_URL="https://exaiv.com/api/ai/v1/anthropic"
export ANTHROPIC_API_KEY="YOUR_EXAIV_API_KEY"
# کمترین آزمون ممکن
claude --print "say hi"
اگر پاسخ آمد، نقطه پایانی زنده است. برای ماندگاری می‌توانید این دو خط را در ~/.zshrc یا ~/.bashrc بگذارید، اما آن‌گاه روی هر فراخوانی claude اثر می‌گذارد. اگر اشتراک رسمی هم دارید، تنظیم سطح پروژه را ترجیح دهید تا اشتباهاً اعتبار واسط مصرف نشود.
مدلهای موجود را از کجا بگیریم
این نقطه پایانی است که تعیین می‌کند چه مدل‌هایی وجود دارند. فهرست کامل EXAIV (شامل Claude، GPT، DeepSeek، Kimi و غیره) در صفحهٔ مدل‌ها آمده است. تغییر مدل در Claude Code از طریق ANTHROPIC_MODEL یا فرمان /model در نشست انجام میشود.
نکتهٔ عملی: هر شناسهٔ مدلی که در تنظیمات می‌نویسید باید در همان فهرست زنده وجود داشته باشد. نامی که از مستندات یک ارائه‌دهندهٔ دیگر به خاطر دارید، از مسیر واسط حل نمی‌شود.
عیب‌یابی: به همین ترتیب پیش بروید
این ترتیب تصادفی نیست؛ هر لایه یا کار می‌کند یا شما را به لایهٔ بعد می‌فرستد:
- متغیرهای محیطی — آیا متغیر در همین پوسته دیده میشود؟
echo $ANTHROPIC_BASE_URLرا اجرا کنید. یک پنجرهٔ ترمینال دیگر، یا متغیر قدیمی‌ای که در نشست قبلی صادر شده، شایع‌ترین ریشهٔ خطاهای 401 است: متغیرهای پوسته بر فایل تنظیمات اولویت دارند. - آدرس پایه — آیا با
/api/ai/v1/anthropicتمام میشود؟ یک کاراکتر کم یا اضافه، خطای 404 می‌دهد که شبیه خطای مدل به نظر می‌رسد. - کلید — کلید در همان جایی تنظیم شده که واقعاً خوانده میشود؟ اگر کلید را در فایل تنظیمات گذاشته‌اید و پوسته هم یک کلید قدیمی دارد، کلید قدیمی برنده است.
- شناسهٔ مدل — مقدار
ANTHROPIC_MODELرا با فهرست/modelsمقایسه کنید. - نگاشت tier — Claude Code فقط مدل اصلی شما را صدا نمی‌زند؛ در پسزمینه درخواستهای کوچک‌تری برای خلاصه‌سازی خروجی ابزار و تولید پیام commit می‌فرستد. اگر نقطه پایانی مدل پیشفرض آن tierها را نداشته باشد، آن فراخوانیها شکست میخورند.
- شبکه — اگر تا اینجا همه چیز درست بود، سراغ مسیر شبکه بروید: پروکسی محلی، فایروال سازمانی، یا زمان‌بندی.
یک الگوی واقعی
توسعه‌دهنده‌ای settings.json را ویرایش می‌کند، claude --print "say hi" می‌زند و خطای 401 می‌گیرد. حدس اولش مشکل نقطه پایانی است. با همین ترتیب پیش می‌رود و در لایهٔ اول می‌بیند همان روز صبح یک ANTHROPIC_API_KEY قدیمی را در پوسته صادر کرده بوده؛ متغیر پوسته بر فایل تنظیمات اولویت داشته و کلید قدیمی فرستاده شده. با unset کردن آن، پاسخ برمی‌گردد. زمان کل: چند دقیقه، چون دو لایه هم‌زمان اشکال‌زدایی نشدند.
چرا نگاشت tier مهم‌تر از آن است که فکر می‌کنید
درخواستهای پس‌زمینهٔ Claude Code با برچسب tier فرستاده می‌شوند (sonnet یا haiku). اگر نقطه پایانی مدل پیشفرض آن برچسب را نداشته باشد، یا فراخوانی شکست می‌خورد یا رفتار غیرقابل‌پیش‌بینی رخ می‌دهد. ANTHROPIC_DEFAULT_SONNET_MODEL و ANTHROPIC_DEFAULT_HAIKU_MODEL دقیقاً برای همین‌اند.
ساده‌ترین الگوی قابل‌اعتماد: هر دو را به همان مدل اصلی نگاشت کنید. پس از پایدار شدن، نگاشت tier سبک به یک مدل سریع‌تر یک بهینه‌سازی متعارف است، چون تعداد آن درخواست‌ها بیشتر است.
زمان‌بندی و تنظیم شبکه
دو متغیر بیشتر شکایت‌های اتصال را حل می‌کند:
API_TIMEOUT_MS— یک نوبت بلند در حالت agent می‌تواند چند دقیقه طول بکشد؛ زمان‌بندی کوتاه، درخواستی را می‌کشد که در حال موفق شدن بوده است. اگر نوبت‌ها بدون پیام خطا نیمه‌کاره میمانند، این مقدار را بالا ببرید.- پروکسی محلی — اگر پوستهٔ شما
HTTP_PROXYیاHTTPS_PROXYرا تنظیم کرده باشد، درخواست ممکن است اول به یک پروکسی محلی برود. وقتی آدرس پایه درست است ولی اتصال برقرار نمی‌شود، یک بار با متغیرهای پروکسی خالی آزمایش کنید.
هیچ‌کدام از این دو به‌صورت پیشفرض لازم نیستند؛ وقتی تنظیمات درست است و مسیر شبکه مشکل دارد، این‌ها دو پیچ اولی هستند که باید بچرخانید.
هزینه چگونه حساب میشود
EXAIV به‌صورت اعتباری (credits) و بر اساس مصرف محاسبه می‌کند: بستهٔ اعتبار را یک‌بار می‌خرید و مصرف هر فراخوانی با نرخ همان مدل کسر میشود؛ اشتراک ماهانه‌ای وجود ندارد. کمترین بستهٔ موجود در صفحهٔ قیمت فهرست شده است و برای یک چرخهٔ اعتبارسنجی واقعی کافی است:
- ثبت‌نام کنید و در کنسول یک کلید API بسازید
- کمترین بسته را تهیه کنید
- با همان سه فرمان این مقاله، اتصال را روی یک کار واقعی آزمایش کنید
- اگر نتیجه کافی بود، برای بارهای بزرگ‌تر بستهٔ بزرگ‌تر بگیرید — کلید و تنظیمات تغییر نمی‌کنند
قیمت‌ها به‌صورت زنده در همان صفحه به‌روزرسانی می‌شوند؛ به‌جای تکیه بر عددی که در یک مقاله خوانده‌اید، همان‌جا ببینید.
نکات امنیتی
کلید API یک مجوز کیف پول است. چهار قاعدهٔ ابتدایی:
- کلید هرگز در git. فایل تنظیمات با کلید واقعی بیرون از نسخه‌بندی بماند؛ در مخزن فقط نمونهٔ بدون کلید قرار بگیرد.
- چرخش دوره‌ای. کلیدها را در کنسول به‌صورت دوره‌ای بازتولید و کلیدهای قدیمی را باطل کنید؛ در صورت شک به افشا، فوراً چرخش دهید.
- کمترین دسترسی. کلید را در لاگ‌های CI، کد فرانت‌اند یا رشته‌های گفتگو جا نگذارید.
- پایش ناهنجاری. اگر سرعت مصرف اعتبار از الگوی معمول شما فاصله گرفت، اول کلید را باطل کنید و بعد بررسی کنید.