۴ متغیر محیطی برای کاهش هزینه و رفع خطاهای بک‌اِند در Claude Code

اگر ساعت‌ها وقت خود را صرف عیب‌یابی خطای «401 Unauthorized» در Claude Code کرده‌اید، احتمالاً قربانی یک تلهٔ کوچک در متغیرهای محیطی شده‌اید. طبق راهنمای فنی منتشر شده در ۱ سپتامبر ۲۰۲۶ توسط توسعه‌دهنده‌ای به نام هاروی، تفاوت میان یک اتصال موفق و شکست کامل، اغلب تنها در انتخاب یک متغیر محیطی است.

بسیاری از برنامه‌نویسان تلاش می‌کنند از ANTHROPIC_API_KEY استفاده کنند که اعتبارنامه‌ها را از طریق هدر X-Api-Key ارسال می‌کند. اما اکثر بک‌اِندهای سازگار با OpenAI مانند LiteLLM، One API و New-API، و همچنین اکثر واسط‌های فروش (Resellers)، به فرمت Authorization: Bearer نیاز دارند. برای رفع این مشکل، شما باید به‌جای متغیر قبلی، از ANTHROPIC_AUTH_TOKEN استفاده کنید. اگر متغیر اشتباه را تنظیم کنید، با خطای ۴۰۱ مواجه می‌شوید که دقیقاً شبیه به نامعتبر بودن کلید API است؛ این موضوع باعث می‌شود توسعه‌دهندگان به‌جای بررسی هدرهای ارسالی، یک ساعت کامل را صرف چرخش و تعویض کلیدها (Key Rotation) کنند. این چالش در مدیریت کلیدها، اهمیت استفاده از راهکارهای یکپارچه برای جابه‌جایی سریع بین مدل‌های مختلف را دوچندان می‌کند تا از پیچیدگی‌های مدیریتی APIها کاسته شود.

زمینه اتصال

برای اینکه Claude Code بتواند با یک بک‌اِند ارتباط برقرار کند، حداقل پیکربندی لازم شامل سه خط دستور است:

• export ANTHROPIC_BASE_URL=https://your-endpoint/v1
• export ANTHROPIC_AUTH_TOKEN=sk-your-key
• export ANTHROPIC_MODEL=some-model-id

همان‌طور که در تحلیل قبلی ما درباره‌ی سوءاستفاده از پاداش (Reward Hacking) و افزایش ریسک‌های سایبری در شبیه‌سازی‌های Anthropic اشاره کردیم، لایه‌ی عملیاتی این مدل‌ها یک مرکز هزینه‌های پنهان دارد: وظایف پس‌زمینه. Claude Code فقط از مدل اصلی شما برای پاسخ‌دهی استفاده نمی‌کند؛ بلکه به‌طور مداوم درخواست‌های حجیمی برای کارهای «خانه‌داری» مانند خلاصه‌سازی فایل‌های طولانی و فشرده‌سازی زمینه (Context) ارسال می‌کند.

برای بهینه‌سازی کیف پول خود، باید روی این پیکربندی‌های خاص تمرکز کنید:

مبانی اتصال و هزینه

• ANTHROPIC_BASE_URL: ابزار را به نقطه انتهایی (Endpoint) خاص شما هدایت می‌کند (مثلاً https://your-endpoint/v1).
• ANTHROPIC_AUTH_TOKEN: استفاده از توکن‌های Bearer را برای درگاه‌های سازگار تضمین می‌کند.
• ANTHROPIC_MODEL: مدل اصلی مورد استفاده برای تعاملات اولیه و استدلال‌های اصلی را تغییر می‌دهد. این قابلیت جایگزینی مدل‌ها در واقع گامی در جهت جایگزینی منطق صلب If/Else با استدلال هوشمند در اتوماسیون است که انعطاف‌پذیری سیستم را افزایش می‌دهد.
• ANTHROPIC_DEFAULT_HAIKU_MODEL: حیاتی‌ترین متغیر برای کاهش هزینه است. متصل کردن این متغیر به ارزان‌ترین مدل موجود در دسترس شما، هزینه‌های جلسه را بیشتر از کاهش سطح مدل اصلی کم می‌کند؛ زیرا این متغیر مسئول مدیریت کارهای حجیم پس‌زمینه است.
• ANTHROPIC_DEFAULT_SONNET_MODEL: نام مستعار مدل سطح متوسط (Mid-tier) را تعیین می‌کند.
• ANTHROPIC_DEFAULT_OPUS_MODEL: نام مستعار مدل سطح پیشرفته و قدرتمند (Strong-tier) را تعیین می‌کند.

پایداری و قابلیت‌های پیشرفته

• ENABLE_TOOL_SEARCH: اگر از پروکسی استفاده می‌کنید، این مقدار باید روی true تنظیم شود. جست‌وجوی ابزار MCP در میزبان‌های غیررسمی (Non-first-party) به‌طور پیش‌فرض غیرفعال است و اغلب به‌جای نمایش «قابلیت غیرفعال»، با پیام «ابزارهای MCP کار نمی‌کنند» ظاهر می‌شود. این تنظیم در صورتی که پروکسی شما بلوک‌های tool_reference را فوروارد می‌کند، ضروری است.
• API_FORCE_IDLE_TIMEOUT: تنظیم این مقدار روی ۰ باعث حذف قطع شدن خودکار در ۵ دقیقه بیکاری می‌شود. این کار مانع از توقف پاسخ‌های جریانی (Streaming) در درگاه‌های کند می‌شود که در لحظات بین تکه‌های پاسخ (Chunks) مکث می‌کنند؛ در غیر این صورت، Claude Code بدون هیچ خطایی در وسط جمله متوقف می‌شود.
• API_TIMEOUT_MS: مقدار پیش‌فرض ۶۰۰,۰۰۰ میلی‌ثانیه (۱۰ دقیقه) است. اگر با خطاهای Timeout مواجه شدید، باید این مقدار را بررسی و تأیید کنید.

یک هشدار بسیار مهم برای کاربران: متغیر ANTHROPIC_SMALL_FAST_MODEL اکنون منسوخ شده است. تنظیم آن در حال حاضر هیچ اثری ندارد و به‌صورت بی‌صدا نادیده گرفته می‌شود؛ به این معنی که ممکن است تصور کنید مدل پس‌زمینه پیکربندی شده است در حالی که چنین نیست. به‌جای آن حتماً از ANTHROPIC_DEFAULT_HAIKU_MODEL استفاده کنید.

برای کسانی که از حالت «Plan Mode» استفاده می‌کنند، متغیر ANTHROPIC_DEFAULT_OPUS_MODEL رفتار تنظیمات opusplan را کنترل می‌کند. نادیده گرفتن این پیکربندی می‌تواند منجر به رفتارهای غیرمنتظره و ناپایدار در مراحل برنامه‌ریزی پیچیده شود.

عملکرد درگاه و تأخیر

تفاوت در میزان تأخیر (Latency) می‌تواند بسیار شدید باشد. در تست‌های انجام شده در ۳۱ اوت، سه درخواست به یک نقطه انتهایی و مدل یکسان، پراکندگی عجیبی داشتند: یکی ۹۲ ثانیه طول کشید و در نهایت Timeout شد، در حالی که بقیه در ۲.۴ و ۱۱.۲ ثانیه به پایان رسیدند. تست‌های بعدی نتایجی بین ۱.۶۴، ۲.۵۳ و ۸.۴۰ ثانیه داشتند. این تفاوت ۵ برابری ثابت می‌کند که نبودِ Timeout در یک درگاه، یک شبکه ایمنی نیست، بلکه فقط جایی برای انتظار طولانی است.

از دیدگاه کاربردی، این یعنی تنظیمات «پیش‌فرض» اغلب گران‌ترین و شکننده‌ترین حالت ممکن است. با جداسازی مدل «خانه‌داری» پس‌زمینه از مدل استدلالی اصلی، توسعه‌دهندگان می‌توانند کیفیت خروجی را حفظ کرده و هم‌زمان هزینه توکن‌های نامرئی که قدرت‌بخش جلسه هستند را به‌شدت کاهش دهند.

اگر با شکست مواجه شدید، هرگز از طریق CLI عیب‌یابی نکنید. از یک دستور مستقیم curl برای تست نقطه انتهایی با توکن Bearer استفاده کنید:
curl -s https://your-endpoint/v1/chat/completions \ -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{"model":"your-model","messages":[{"role":"user","content":"say OK"}],"max_tokens":10}'

اگر درخواست curl شکست خورد، مشکل قطعاً از کلید یا درگاه شماست، نه پیکربندی Claude Code. همچنین، یک بار موفقیت کافی نیست؛ این دستور را چندین بار اجرا کنید تا از پایداری اتصال مطمئن شوید.

به تعامل این متغیرها با حافظه پنهان پرامپت (Prompt Caching) توجه کنید. از آن‌جا که پرامپت‌های سیستمی Claude Code ثابت هستند، نرخ برخورد (Hit Rate) بالایی ممکن است رخ دهد، اما طبق گزارش ۱ سپتامبر، تغییرات قیمت در لایه‌های بالادستی (Upstream) می‌تواند بودجه شما را یک‌شبه ۱۵ برابر تغییر دهد. علاوه بر این، آگاه باشید که از نسخه ۲.۱.۱۹۶ به بعد، کنترل از راه دور (Remote Control) در صورتی که URL پایه چیزی جز api.anthropic.com باشد، غیرفعال می‌شود؛ رفتاری که مشابه محدودیت‌های مشاهده شده در Bedrock و Vertex است.

در نهایت، قابلیت‌های فراخوانی تابع (Tool Calling) را بررسی کنید. اگر فراخوانی ابزار در درگاه شما شکست می‌خورد اما در API رسمی Anthropic به‌درستی کار می‌کند، احتمالاً با یک شکاف در قابلیت‌های مدل (Model Capability Gap) روبرو هستید، نه یک مشکل در پیکربندی.

گام بعدی شما

• متغیر ANTHROPIC_DEFAULT_HAIKU_MODEL را به ارزان‌ترین مدل در دسترس خود متصل کنید تا هزینه‌های پس‌زمینه کاهش یابد.
• برای رفع خطاهای ۴۰۱، ANTHROPIC_API_KEY را حذف و از ANTHROPIC_AUTH_TOKEN استفاده کنید.
• مقدار API_FORCE_IDLE_TIMEOUT را روی ۰ قرار دهید تا از قطع شدن پاسخ‌های طولانی جلوگیری کنید.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.