اولین سؤال برای استفاده از Claude Code در ایران معمولاً پرداخت است: اشتراک Claude Pro و Max و کلید API کنسول Anthropic هر دو با کارت اعتباری خارجی خریده میشوند. راه دیگر وصل کردن Claude Code به یک درگاه API است. اتصال Claude Code (کلود کد) به API هوش مصنوعی چابکان با چهار متغیر محیطی انجام میشود. ظاهر، دستورها و ابزارهای اصلی Claude Code (خواندن و ویرایش فایل، اجرای دستور) همان است. درخواستها به درگاه چابکان میروند و هزینهٔ مصرف از اعتبار سرویس کم میشود. فقط امکاناتی که به حساب claude.ai وابستهاند، مثل Remote Control، دیکتهٔ صوتی و جلسههای وب، با این روش در دسترس نیستند.
اگر هنوز نمیدانی Claude Code چه کاری میکند و چه فرقی با Copilot دارد، اول Claude Code چیست؟ را بخوان. این مقاله فقط به راهاندازی میپردازد. همهٔ قدمها را با Claude Code نسخهٔ 2.1.296 روی لینوکس اجرا کردیم: یک بار با یک سرور آزمایشی که رفتار درگاه را شبیهسازی میکرد، و یک بار با خود درگاه چابکان و یک کلید عمداً اشتباه. هدف این بود که ببینیم متغیرها کجا خوانده میشوند و هر اشتباه چه پیامی میدهد. یعنی در این تست جواب واقعی مدل را با کلید واقعی نگرفتیم.

Claude Code چطور به API چابکان وصل میشود؟
Claude Code، دستیار کدنویسی هوش مصنوعی Anthropic، درخواستهایش را با قالب Anthropic Messages میفرستد. درگاه هوش مصنوعی چابکان همین قالب را در مسیر /v1/messages پشتیبانی میکند و مستند اتصال Claude Code به چابکان هم همین را میگوید. پس به هیچ ابزار واسطی نیاز نداری. کافی است چهار چیز را به Claude Code بگویی:
- آدرس درگاه:
ANTHROPIC_BASE_URL - کلید:
ANTHROPIC_AUTH_TOKEN - مدل اصلی:
ANTHROPIC_MODEL - مدل سبک برای کارهای پسزمینه:
ANTHROPIC_DEFAULT_HAIKU_MODEL
در تست ما، Claude Code بعد از تنظیم این متغیرها درخواستش را به /v1/messages فرستاد، کلید را در هدر Authorization: Bearer گذاشت و دقیقاً همان شناسهٔ مدلی را که داده بودیم به کار برد. ابزارهایش (خواندن فایل، ویرایش، اجرای دستور) هم همراه درخواست رفتند و ورود به حساب Anthropic را هم نخواست.
پیشنیازها
- Node.js نسخهٔ ۲۲ یا جدیدتر. با
node --versionچک کن. با نسخههای قدیمیتر هم نصب میشود، ولی هشدارEBADENGINEمیبینی. - ترمینال. مستند چابکان نصب را برای macOS، لینوکس و WSL ویندوز آورده و تنظیم متغیرها را برای PowerShell هم توضیح داده است.
- سرویس هوش مصنوعی چابکان با اعتبار مثبت. پلن سرویس و اعتبار مصرف مدل دو چیز جدا هستند. تا اعتبار مصرف شارژ نشده باشد، مدل جواب نمیدهد.
- یک کلید API و شناسهٔ دقیق مدل.
ساخت سرویس، شارژ اعتبار و ساخت کلید
- در پنل چابکان از بخش محصولات «هوش مصنوعی» را باز کن، سرویس بساز و صبر کن وضعیتش «فعال» شود.
- در زبانهٔ «اعتبار و شارژ» اعتبار مصرف مدل را از کیف پول شارژ کن.
- در زبانهٔ «کلیدهای API» یک کلید با اسمی مثل
claude-code-laptopبساز. اگر خواستی، برایش تاریخ انقضا و سقف مصرف ماهانه هم بگذار. - کلید فقط همان یک بار کامل نشان داده میشود و با
sk-chbk-شروع میشود. همان لحظه کپیاش کن و جای امنی نگه دار.
جزئیات هر مرحله در راهنمای آمادهسازی سرویس و کلید آمده است. با همین کلید sk-chbk- مدلهای GPT فهرست سرویست را هم میتوانی صدا بزنی. ساختن کلید و تست آن با curl در آموزش کار با API ChatGPT و ساخت کلید آمده است.
کدام مدل را انتخاب کنی؟
Anthropic پشتیبانی رسمی Claude Code را فقط برای مدلهای Claude اعلام کرده است، پس از مدلهای Claude در چابکان شروع کن. شناسهها با anthropic/ شروع میشوند:
- مدل اصلی: یک مدل Sonnet مثل
anthropic/claude-sonnet-5.5برای بیشتر کارهای کدنویسی کافی است. برای کارهای سنگینتر، مثل بازنویسی بخش بزرگی از پروژه، Opus را بگذار:anthropic/claude-opus-5.5. - مدل سبک: یک مدل Haiku مثل
anthropic/claude-haiku-5.5. Claude Code کارهای کوچکی مثل ساختن عنوان جلسه را به این مدل میدهد.
شناسههایی که به -latest ختم میشوند، مثل anthropic/claude-sonnet-latest، همیشه به تازهترین نسخه اشاره میکنند. اگر نمیخواهی رفتار ابزار با آمدن نسخهٔ تازه عوض شود، شناسهٔ نسخهدار را بگذار. از نسخههای قدیمی هم دوری کن. Claude Code برای بعضی شناسههای قدیمی هشدار بازنشستگی نشان میدهد و گاهی شناسهٔ چابکان را با یک مدل قدیمیتر اشتباه میگیرد. اگر چنین هشداری دیدی، شناسهٔ 5.5 را بگذار. اینکه کدام مدلها برایت باز است به پلن سرویس بستگی دارد. شناسه را از زبانهٔ «مدلهای قابل استفاده» در پنل کپی کن، نه از روی اسم نمایشی مدل. راهنمای کاملتر در انتخاب مدل هست.
قدم ۱: نصب Claude Code
npm install -g @anthropic-ai/claude-code
claude --version
دستور را بدون sudo بزن. مستند Claude Code صریحاً از sudo npm install -g منع کرده است. اگر claude --version شمارهٔ نسخه را نشان داد، نصب درست است و claude doctor هم وضعیت نصب را بررسی میکند.
طبق مستند تنظیم مدل در Claude Code، Sonnet 5.5 به نسخهٔ 2.1.284 و Haiku 5.5 به نسخهٔ 2.1.293 یا جدیدتر نیاز دارد. پس نسخهٔ تو باید 2.1.293 یا جدیدتر باشد. برای بهروزرسانی npm install -g @anthropic-ai/claude-code@latest را بزن، نه npm update -g.
اگر نصب با npm خیلی طول کشید یا خطای شبکه داد، میتوانی میرور چابکان را با --registry=https://mirror2.chabokan.net/npm/ امتحان کنی. بعد از نصب حتماً claude --version را چک کن: موقع نوشتن این مقاله، آخرین نسخهٔ Claude Code روی میرور 2.1.280 بود که برای Sonnet 5.5 و Haiku 5.5 قدیمی است.
اگر Claude Code را از قبل با اشتراک Claude نصب کردهای، نصب دوباره لازم نیست و متغیرهای قدم بعد کافی است. اگر موقع اجرا هشداری دربارهٔ دو روش ورود دیدی، داخل Claude Code دستور /logout را بزن تا فقط کلید چابکان بماند.
قدم ۲: تنظیم متغیرها برای اتصال Claude Code به API چابکان
در macOS، لینوکس یا WSL، در همان ترمینالی که Claude Code را از آن اجرا میکنی:
export ANTHROPIC_BASE_URL="https://ai.chabokan.net"
export ANTHROPIC_AUTH_TOKEN="sk-chbk-your-key"
export ANTHROPIC_MODEL="anthropic/claude-sonnet-5.5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-5.5"
در PowerShell ویندوز:
$env:ANTHROPIC_BASE_URL = "https://ai.chabokan.net"
$env:ANTHROPIC_AUTH_TOKEN = "sk-chbk-your-key"
$env:ANTHROPIC_MODEL = "anthropic/claude-sonnet-5.5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "anthropic/claude-haiku-5.5"
سه جایی که معمولاً اتصال خراب میشود:
- Base URL بدون
/v1. Claude Code خودش/v1/messagesرا به آخر آدرس اضافه میکند. یک بار عمداًhttps://ai.chabokan.net/v1گذاشتیم. درخواست به/v1/v1/messagesرفت، درگاه 404 داد و Claude Code پیام گمراهکنندهٔThere's an issue with the selected modelرا نشان داد. اگر این پیام را دیدی، اول آدرس را نگاه کن، بعد مدل را. - کلید در
ANTHROPIC_AUTH_TOKEN. Claude Code این مقدار را در هدرAuthorization: Bearerمیفرستد، همان چیزی که مستند چابکان گفته است.ANTHROPIC_API_KEYرا نگذار. Claude Code آن را در هدر دیگری (x-api-key) میفرستد و در حالت تعاملی یک بار هم تأیید میخواهد. - اسم متغیر مدل سبک. مستند چابکان هنوز اسم قدیمی
ANTHROPIC_SMALL_FAST_MODELرا آورده است. مستند متغیرهای Claude Code این اسم را منسوخ اعلام کرده وANTHROPIC_DEFAULT_HAIKU_MODELرا به جایش گذاشته است. اگر نسخهٔ Claude Code تو قدیمی است، هر دو را با یک مقدار تنظیم کن. با نسخهٔ 2.1.293 یا جدیدتر، فقطANTHROPIC_DEFAULT_HAIKU_MODELکافی است.
این متغیرها فقط تا وقتی همان ترمینال باز است میمانند. برای تنظیم دائمی، قدم ۴ را ببین.
قدم ۳: تست اتصال
اول درگاه و کلید را جدا از Claude Code امتحان کن. اگر این دستور جواب نداد، مشکل از Claude Code نیست:
curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "anthropic/claude-haiku-5.5", "max_tokens": 16, "messages": [{"role": "user", "content": "Say: connected"}]}'
در PowerShell به جای curl بنویس curl.exe، متغیرها را به شکل $env:ANTHROPIC_BASE_URL بنویس و \ آخر خطها را بردار تا دستور در یک خط باشد.
- اگر جوابی با
"type": "message"و یک بخشcontentگرفتی، کلید، اعتبار و مدل درستاند. - خطای 401 با
Invalid API keyیاMalformed API keyیعنی کلید اشتباه یا ناقص کپی شده است. با یک کلید ساختگی دقیقاً همین را از درگاه گرفتیم. - خطای 402 یعنی اعتبار تمام شده یا کلید به سقف ماهانهاش رسیده است.
- خطای 404 با
model not foundیعنی شناسهٔ مدل غلط است یا در پلنت نیست.
بعد خود Claude Code را امتحان کن:
cd /path/to/your/project
claude -p "Reply with: connected"
اگر جواب گرفتی، claude را بدون -p باز کن و دستور /status را بزن. خط Anthropic base URL باید آدرس چابکان را نشان بدهد و خط Auth token هم باید دیده شود. در آخر، در پنل چابکان زبانهٔ «گزارش درخواستها» را باز کن. درخواستت باید با مسیر messages و وضعیت موفق ثبت شده باشد.

قدم ۴: ذخیرهٔ تنظیمات در settings.json
برای اینکه هر بار export نزنی، متغیرها را در فایل ~/.claude/settings.json بگذار (در ویندوز %USERPROFILE%\.claude\settings.json):
{
"env": {
"ANTHROPIC_BASE_URL": "https://ai.chabokan.net",
"ANTHROPIC_AUTH_TOKEN": "sk-chbk-your-key",
"ANTHROPIC_MODEL": "anthropic/claude-sonnet-5.5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-5.5",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
}
}
در تست ما Claude Code بدون هیچ متغیری در ترمینال و فقط با همین فایل به درگاه وصل شد. چند نکته دربارهٔ این فایل:
- کلید داخلش است. در لینوکس و macOS دسترسیاش را با
chmod 600 ~/.claude/settings.jsonمحدود کن. کلید را هیچوقت در.claude/settings.jsonداخل پوشهٔ پروژه نگذار، چون آن فایل برای اشتراک با تیم ساخته شده و معمولاً commit میشود. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICترافیک جانبی Claude Code مثل تلهمتری، گزارش خطا و بررسی بهروزرسانی را خاموش میکند. این درخواستها از درگاه چابکان رد نمیشوند و مستقیم به سرورهای Anthropic میروند. با این متغیر بهروزرسانی خودکار هم خاموش میشود، پس هر چند وقت یک بارnpm install -g @anthropic-ai/claude-code@latestرا بزن.- اولویت. اگر یک متغیر هم در ترمینال و هم در این فایل باشد، مقدار فایل حساب میشود. برای عوض کردن کلید یا مدل، همین فایل را ویرایش کن و با
/statusنتیجه را ببین.
اختیاری: سوییچ سریع بین Sonnet و Opus
داخل Claude Code میشود با /model sonnet یا /model opus مدل را عوض کرد. برای اینکه این دو اسم کوتاه به شناسههای چابکان برسند، این دو خط را هم به بلوک env اضافه کن:
"ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5.5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5.5"
بعد از این، /model opus و /model sonnet به مدلهای چابکان میروند.
تنظیم در VS Code
افزونهٔ Claude Code قبل از اجرا خودش دنبال اطلاعات ورود میگردد و آن را از settings.json نمیخواند. پس اگر فقط قدم ۴ را انجام داده باشی، VS Code از تو میخواهد لاگین کنی. برای VS Code این دو کار را هم بکن:
کار اول: دستور Preferences: Open User Settings (JSON) را باز کن و متغیرها را در claudeCode.environmentVariables بگذار:
"claudeCode.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "https://ai.chabokan.net" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-chbk-your-key" },
{ "name": "ANTHROPIC_MODEL", "value": "anthropic/claude-sonnet-5.5" },
{ "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "anthropic/claude-haiku-5.5" }
]
کار دوم: در تنظیمات VS Code عبارت Claude Code login را جستجو کن و Disable Login Prompt را تیک بزن.
در آخر پنجره را با دستور Developer: Reload Window دوباره باز کن. منبع این دو تنظیم راهنمای اتصال Claude Code به درگاه و مستند افزونهٔ VS Code است. نصب خود افزونه در راهنمای افزونههای رسمی VS Code چابکان آمده است.
اولین کار واقعی با Claude Code
در پوشهٔ پروژه claude را اجرا کن. اولین پیام را فقط برای خواندن بنویس، مثلاً همان پیشنهاد مستند چابکان: «فایلهای پروژه را بررسی کن و فقط معماری کلی را توضیح بده. هیچ فایلی را تغییر نده.» اینطوری بدون تغییر فایل میبینی مدل پروژه را درست فهمیده یا نه.
بعد یک کار کوچک بخواه، مثلاً «کنار index.html یک صفحهٔ about.html ساده با همان استایل بساز». Claude Code قبل از ساختن یا ویرایش فایل و قبل از اجرای هر دستور، تغییر را نشان میدهد و اجازه میگیرد. diff را بخوان و فقط وقتی تأیید کن که با آن موافقی.
کلید API چابکان فقط اجازهٔ فراخوانی مدل را میدهد. اینکه Claude Code به کدام فایلها و دستورها دست بزند، با تأییدهای خودت روی همان سیستم تعیین میشود. پس روی پوشهای کار کن که Git دارد تا هر تغییری را بتوانی برگردانی، و تا مطمئن نشدهای، اجرای خودکار دستورها را روشن نکن.
کنترل هزینه و امنیت کلید
Claude Code برای هر کار چند درخواست پشت سر هم میفرستد: خواندن فایلها، اجرای ابزارها و بررسی نتیجه. هر کدام از اعتبار سرویس کم میکند. چند عادت ساده خرج را قابل پیشبینی نگه میدارد:
- مدل مناسب کار. برای کارهای روزمره Sonnet کافی است. Opus را برای کارهای سنگین نگه دار.
- مدل سبک برای پسزمینه. وقتی
ANTHROPIC_DEFAULT_HAIKU_MODELرا روی Haiku بگذاری، کارهای کوچک با مدل اصلی انجام نمیشوند. - سقف ماهانه روی کلید. وقتی سقف پر شود، درگاه خطای 402 میدهد و خرج بیشتری نمیشود.
- یک کلید برای هر دستگاه. مصرف هر لپتاپ یا سرور جدا دیده میشود و اگر یکی گم شد، فقط کلید همان را غیرفعال میکنی. راهنمای استفاده در محیط واقعی چابکان هم همین را توصیه میکند.
- گزارش درخواستها. هر چند وقت یک بار این زبانه را در پنل نگاه کن تا ببینی کدام مدل بیشتر مصرف کرده است.
خطاهای رایج و راه حل
| پیامی که میبینی | علت | راه حل |
|---|---|---|
Not logged in · Please run /login |
ANTHROPIC_AUTH_TOKEN به Claude Code نرسیده است |
متغیر را در همان ترمینال تنظیم کن یا در settings.json بگذار |
401 Malformed API key یا Invalid API key |
کلید اشتباه یا ناقص کپی شده است | کلید را دوباره کپی کن یا کلید تازه بساز |
هشداری دربارهٔ دو روش ورود که با auth may not work as expected تمام میشود |
کلید چابکان و لاگین قبلی حساب Claude هر دو فعالاند | داخل Claude Code دستور /logout را بزن |
API key is disabled یا API key has expired |
کلید غیرفعال شده یا تاریخ انقضایش گذشته است | در زبانهٔ «کلیدهای API» کلید تازه بساز |
There's an issue with the selected model |
Base URL با /v1 تمام شده، یا شناسهٔ مدل غلط است یا در پلن نیست |
/v1 را از آدرس بردار و شناسه را از پنل کپی کن |
Claude Code ... does not support this model; version ... or newer is required |
نسخهٔ Claude Code برای این مدل قدیمی است | npm install -g @anthropic-ai/claude-code@latest |
402 AI credit exhausted |
اعتبار مصرف تمام شده است | از زبانهٔ «اعتبار و شارژ» شارژ کن |
402 Monthly usage cap reached |
کلید به سقف ماهانهاش رسیده است | سقف کلید را بیشتر کن یا تا ماه بعد صبر کن |
429 |
تعداد درخواستها از حد پلن بیشتر شده است | چند ثانیه صبر کن و دوباره امتحان کن |
400 با Extra inputs are not permitted |
مدل بعضی فیلدهای آزمایشی Claude Code را نمیپذیرد | CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 را اضافه کن |
| Claude Code صفحهٔ وب را باز نمیکند و ابزار WebFetch خطا میدهد | WebFetch قبل از باز کردن هر آدرس، اسم دامنه را برای بررسی امنیتی به api.anthropic.com میفرستد و این درخواست به آن سرور نمیرسد |
در settings.json گزینهٔ "skipWebFetchPreflight": true را بگذار و دسترسی WebFetch را با قانونهای permissions محدود کن |
ردیفهای Not logged in، Malformed API key و There's an issue with the selected model را خودمان در تست دیدیم. بقیه از جدول عیبیابی هوش مصنوعی چابکان و مستندهای رسمی Claude Code (خطاها و داده و حریم خصوصی) آمده است. اگر خطای 5xx گرفتی، مقدار X-Request-Id پاسخ را برای پشتیبانی بفرست.
استفاده از Claude Code در ایران با API چابکان
برای اتصال Claude Code به API چابکان سه چیز لازم داشتی: سرویس هوش مصنوعی با اعتبار، یک کلید و شناسهٔ مدل. هر سه را از یک پنل میگیری و اعتبار را بدون کارت اعتباری خارجی و با پرداخت ریالی شارژ میکنی. فهرست مدلها و شناسههایشان در صفحهٔ API مدلهای Claude در چابکان هست و بقیهٔ خانوادهها در هوش مصنوعی ابری چابکان. اعتبار هدیهٔ ۱۰۰ هزار تومانی را میتوانی برای مصرف هوش مصنوعی خرج کنی، پس اولین جلسههای Claude Code را با همان تست کن.
اگر میخواهی ایجنتی بسازی که روی سرور همیشه روشن بماند، اجرای AI Agent روی سرور را بخوان. برای آنلاین کردن پروژهای که با Claude Code ساختهای، آنلاین کردن پروژه ChatGPT یا Claude را ببین، و اگر تازه با این سبک کار آشنا شدهای، وایب کدینگ چیست؟ را.
سوالات متداول درباره اتصال Claude Code به API
برای استفاده از Claude Code در ایران اشتراک Claude Pro یا Max لازم است؟
نه. وقتی ANTHROPIC_AUTH_TOKEN تنظیم شده باشد، Claude Code به جای ورود به حساب از همین کلید استفاده میکند و حساب Anthropic لازم نیست. هزینه هم به ازای مصرف از اعتبار سرویس چابکان کم میشود، نه به صورت اشتراک ماهانه.
میتوانم برای یک کار مدل دیگری بگذارم؟
بله. با claude --model anthropic/claude-opus-5.5 فقط همان جلسه با Opus اجرا میشود و تنظیم ANTHROPIC_MODEL دست نمیخورد. در تست ما Claude Code همین شناسه را بدون تغییر برای درگاه فرستاد. برای سوییچ وسط جلسه با /model opus و /model sonnet، بخش «اختیاری: سوییچ سریع بین Sonnet و Opus» را ببین.
با مدلهایی غیر از Claude هم کار میکند؟
مستند چابکان میگوید هر مدل سازگار و مجاز در پلن را میتوانی بگذاری، مثلاً مدلهای GLM. ولی Anthropic فقط مدلهای Claude را برای Claude Code پشتیبانی میکند. Claude Code برای خواندن و ویرایش فایل به ابزارخوانی نیاز دارد، پس مدلی بگذار که ابزارخوانی (tool calling) را پشتیبانی کند و اول با یک کار فقطخواندنی امتحانش کن.
هزینه چطور حساب میشود؟
هر درخواست به اندازهٔ توکنهایی که مصرف کرده از اعتبار سرویس کم میشود و تعرفهٔ هر مدل در صفحهٔ همان مدل آمده است. هزینهٔ پلن سرویس از اعتبار مصرف جداست. چون Claude Code برای هر کار چند درخواست میفرستد، اول با کارهای کوچک شروع کن و مصرف را در «گزارش درخواستها» ببین.
کد پروژهام کجا فرستاده میشود؟
Claude Code فایلهایی را که برای انجام کار میخواند، همراه درخواست به درگاه میفرستد و درگاه آنها را به سرویسدهندهٔ مدل میرساند. فایلهای حساس مثل .env را با قانون deny در بخش permissions همان settings.json از دسترس Claude Code خارج کن، مثلاً "Read(./.env)".
در ویندوز هم کار میکند؟
بله. مستند چابکان نصب را در WSL پیشنهاد کرده و دستورهای PowerShell را هم برای تنظیم متغیرها آورده است. متغیرهای PowerShell فقط برای همان پنجرهاند، پس Claude Code را از همان پنجره اجرا کن یا تنظیمات را در settings.json بگذار.