آموزش نصب و راه‌اندازی Claude Code قدم‌به‌قدم

Claude Code دستیار برنامه‌نویسی Anthropic است که در ترمینال اجرا می‌شود: کد پروژه را می‌خواند، فایل‌ها را ویرایش می‌کند، دستور اجرا می‌کند و تست می‌گیرد. برای راه‌اندازی‌اش سه کار لازم است: Node.js 18 یا بالاتر را نصب کن، با npm install -g @anthropic-ai/claude-code خود Claude Code را نصب کن و دو متغیر ANTHROPIC_BASE_URL و ANTHROPIC_AUTH_TOKEN را با آدرس API و کلیدت تنظیم کن. بعد در پوشهٔ پروژه بزن claude.

در این راهنما همهٔ این مراحل را روی مک، لینوکس و ویندوز جلو می‌رویم، خطاهای رایج را رفع می‌کنیم و می‌بینیم چطور هزینه را پایین نگه داری.

Claude Code چیست؟

Claude Code یک «ایجنت» برنامه‌نویسی است، نه یک چت‌بات. تو کار را به زبان ساده می‌گویی، مثلاً «باگ صفحهٔ ورود را پیدا و درست کن»، و خودش فایل‌های مرتبط را پیدا می‌کند، تغییر را پیشنهاد می‌دهد و با اجازهٔ تو اعمال می‌کند. قبل از هر ویرایش یا اجرای دستور از تو تأیید می‌گیرد، پس کنترل دست خودت می‌ماند.

Claude Code از طریق API به مدل‌های Claude وصل می‌شود و هزینه‌اش بر اساس توکن حساب می‌شود. پس به یک کلید API نیاز داری. این کلید می‌تواند از حساب Anthropic باشد یا از یک درگاه سازگار با API آن، مثل LLMPass که با یک کلید هم مدل‌های Claude و هم GPT را در اختیارت می‌گذارد. اگر هنوز بین ابزارها مردد هستی، مقایسهٔ Claude Code، Codex و Cursor را بخوان.

قبل از نصب Claude Code چه چیزهایی لازم است؟

• Node.js نسخهٔ 18 یا بالاتر، اگر می‌خواهی با npm نصب کنی. نسخه را با node -v چک کن.
• یک ترمینال: Terminal در مک، هر ترمینالی در لینوکس و PowerShell در ویندوز.
• یک کلید API و آدرس پایه (base URL) که در ادامه می‌سازیم.
• Git، که اجباری نیست ولی کمک می‌کند تغییرات Claude Code را ببینی و اگر لازم شد برگردانی.

چطور Claude Code را نصب کنیم؟

نصب روی مک و لینوکس

دو راه داری. راه اول نصب با npm است:

npm install -g @anthropic-ai/claude-code

راه دوم نصب‌کنندهٔ رسمی است که به Node.js نیاز ندارد:

curl -fsSL https://claude.ai/install.sh | bash

نصب روی ویندوز

در PowerShell همان دستور npm را اجرا کن. Claude Code روی ویندوز به Git for Windows هم نیاز دارد؛ اگر نصب نیست، اول آن را نصب کن. اگر با WSL کار می‌کنی، داخل WSL دقیقاً مثل لینوکس جلو برو.

بعد از نصب، با این دستور مطمئن شو همه‌چیز درست است:

claude --version

چطور Claude Code را به کلید API وصل کنیم؟

Claude Code دو متغیر محیطی را می‌خواند: ANTHROPIC_BASE_URL، یعنی آدرس سروری که درخواست‌ها به آن می‌رود، و ANTHROPIC_AUTH_TOKEN، یعنی کلید تو. اگر از LLMPass استفاده می‌کنی، آدرس پایه https://api.llmpass.app است و کلید را از کنسول می‌سازی.

قدم ۱: کلید API بساز

1. در LLMPass ثبت‌نام کن. فقط ایمیل لازم است و به حساب Anthropic نیازی نداری.
2. کیف پول را شارژ کن. حداقل شارژ ۱ دلار است و موجودی منقضی نمی‌شود.
3. در کنسول یک کلید بساز. بهتر است برای هر ابزار کلید جدا بسازی و برایش سقف هزینه بگذاری.

قدم ۲، روش سریع: متغیرهای محیطی

در مک و لینوکس این‌ها را در ترمینال بزن:

export ANTHROPIC_BASE_URL="https://api.llmpass.app"
export ANTHROPIC_AUTH_TOKEN="sk-XXXXXXXXXXXXXXXX"
export ANTHROPIC_MODEL="claude-sonnet-5-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
claude

در ویندوز، داخل PowerShell:

$env:ANTHROPIC_BASE_URL = "https://api.llmpass.app"
$env:ANTHROPIC_AUTH_TOKEN = "sk-XXXXXXXXXXXXXXXX"
$env:ANTHROPIC_MODEL = "claude-sonnet-5-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

این روش فقط در همان پنجرهٔ ترمینال کار می‌کند و با بستنش تنظیمات از بین می‌رود. برای استفادهٔ هرروزه روش بعدی راحت‌تر است.

قدم ۲، روش دائمی: فایل settings.json

تنظیمات را در فایل ~/.claude/settings.json بگذار (در ویندوز: %USERPROFILE%\.claude\settings.json). Claude Code هر بار که اجرا شود بخش env این فایل را می‌خواند. اگر فایل وجود ندارد، خودت بسازش:

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.llmpass.app",
    "ANTHROPIC_AUTH_TOKEN": "sk-XXXXXXXXXXXXXXXX",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

ANTHROPIC_MODEL مدل اصلی را تعیین می‌کند. ANTHROPIC_DEFAULT_HAIKU_MODEL مدل سبک‌تری است که Claude Code برای کارهای پس‌زمینه مثل عنوان‌گذاری و خلاصه‌سازی از آن استفاده می‌کند. Sonnet 5.5 برای کار روزمره تعادل خوبی بین کیفیت و هزینه دارد.

اولین اجرای Claude Code

به پوشهٔ پروژه برو و Claude Code را اجرا کن:

cd ~/projects/my-app
claude

با یک کار کوچک و مشخص شروع کن تا ببینی اتصال درست است. مثلاً «ساختار این پروژه را توضیح بده» یا «برای تابع parseDate تست بنویس». اگر جواب گرفتی، همه‌چیز آماده است.

چند دستور که از روز اول به کارت می‌آید:

• /init فایل CLAUDE.md را با توضیح پروژه می‌سازد. Claude Code این فایل را در هر جلسه می‌خواند، پس لازم نیست هر بار پروژه را از اول معرفی کنی.
• /model مدل را وسط کار عوض می‌کند.
• /clear تاریخچهٔ گفتگو را پاک می‌کند. وقتی سراغ کار جدیدی می‌روی از آن استفاده کن.
• /compact گفتگوی طولانی را خلاصه می‌کند تا context سبک‌تر شود.
• /help فهرست همهٔ دستورها را نشان می‌دهد.

چطور مدل Claude Code را عوض کنیم؟

داخل Claude Code بزن /model و از فهرست انتخاب کن، یا شناسهٔ مدل را مستقیم بنویس: /model claude-opus-5-5. برای عوض کردن مدل پیش‌فرض، مقدار ANTHROPIC_MODEL را در settings.json تغییر بده.

این‌ها قیمت رسمی Anthropic است. قیمت LLMPass تا ۵۰٪ ارزان‌تر است؛ جدول به‌روز را در صفحهٔ قیمت‌ها ببین.

خطاهای رایج Claude Code و راه حلشان

command not found: claude

پوشهٔ نصب سراسری npm در PATH نیست. اول ترمینال را ببند و دوباره باز کن. اگر درست نشد، مسیر را با npm config get prefix پیدا کن و پوشهٔ bin آن را به PATH اضافه کن.

خطای 401 یا Invalid API key

کلید درست کپی نشده (فاصلهٔ اضافه یا کوتیشن جاافتاده) یا در کنسول حذفش کرده‌ای. اگر قبلاً با حساب دیگری وارد Claude Code شده‌ای یا متغیر ANTHROPIC_API_KEY هم تنظیم است، ممکن است Claude Code به‌جای کلید تو از آن استفاده کند. با /logout خارج شو و متغیرهای اضافه را پاک کن.

خطای 404 یا آدرس اشتباه

آدرس پایه را بدون /v1 بنویس. Claude Code خودش /v1/messages را به انتهای آدرس اضافه می‌کند؛ اگر /v1 را هم بنویسی، آدرس دو بار /v1 می‌گیرد و درخواست به جای درستی نمی‌رسد.

model not found

شناسهٔ مدل را دقیق بنویس، مثلاً claude-sonnet-5-5 و نه «sonnet 5.5». فهرست کامل شناسه‌ها در مستندات هست.

خطای موجودی یا سقف هزینه

اگر کیف پول خالی شده یا کلید به سقف هزینه‌اش رسیده، درخواست رد می‌شود. موجودی و سقف کلید را در کنسول چک کن. درخواست‌های ناموفق هزینه‌ای ندارند.

هزینهٔ Claude Code چقدر است و چطور کمش کنیم؟

Claude Code در هر نوبت کل context را می‌فرستد: دستورالعمل سیستم، فایل‌هایی که خوانده و تاریخچهٔ گفتگو. برای همین یک نوبت معمولی ده‌ها هزار توکن ورودی دارد و چند صد تا چند هزار توکن خروجی. خبر خوب این است که بخش تکراری context کش می‌شود و خواندن از کش خیلی ارزان‌تر از ورودی تازه است.

یک مثال با قیمت رسمی Sonnet 5.5: ۴۰ هزار توکن ورودی تازه حدود $0.08 هزینه دارد. اگر همین ۴۰ هزار توکن از کش خوانده شود، با نرخ $0.20 برای هر میلیون توکن، حدود $0.008 می‌شود. دو هزار توکن خروجی هم حدود $0.02 است. برای جزئیات بیشتر توکن چیست و قیمت API Claude و GPT را بخوان.

• Sonnet 5.5 را پیش‌فرض نگه دار و فقط برای مسئله‌های واقعاً سخت با /model سراغ Opus 5.5 برو. Fable 5.1 چند برابر گران‌تر است.
• بین کارها /clear بزن. گفتگوی طولانی یعنی context بزرگ‌تر و هزینهٔ بیشتر در هر نوبت.
• کار را دقیق تعریف کن. «تابع login در auth.ts را درست کن» ارزان‌تر از «یک نگاهی به پروژه بینداز» تمام می‌شود، چون فایل‌های کمتری خوانده می‌شود.
• برای کلید سقف هزینه بگذار تا یک حلقهٔ ناخواسته موجودی‌ات را خالی نکند.
• لاگ مصرف را ببین. در کنسول برای هر درخواست مدل، تعداد توکن، مدت و هزینه ثبت می‌شود و می‌فهمی پولت کجا می‌رود.

Claude Code را با LLMPass راه بیندازم یا با حساب Anthropic؟

اگر حساب Anthropic داری و از آن راضی هستی، همان را نگه دار. LLMPass برای وقتی است که می‌خواهی با یک کلید هم Claude Code و هم Codex، Cursor یا Cline را راه بیندازی، اشتراک ماهانه نمی‌خواهی و ترجیح می‌دهی فقط به اندازهٔ مصرف پول بدهی.

• قیمت تا ۵۰٪ ارزان‌تر از قیمت رسمی.
• کیف پول پیش‌پرداخت، بدون اشتراک؛ موجودی کیف پول منقضی نمی‌شود.
• سقف هزینه و محدودیت IP برای هر کلید.
• محتوای درخواست‌ها ذخیره نمی‌شود؛ فقط آمار مصرف مثل زمان، مدل، توکن و هزینه.

همین کلید در Codex هم کار می‌کند؛ آموزش راه‌اندازی Codex CLI را ببین. بعد از ثبت‌نام هم می‌توانی نام کاربری‌ات را به پشتیبانی تلگرام (@llmpassapp) بفرستی تا اعتبار آزمایشی بگیری.