آموزش اتصال Claude Code به API سفارشی در ویندوز و مک

آموزش اتصال Claude Code به API سفارشی در ویندوز و مک

اگر از Claude Code برای برنامه‌نویسی استفاده می‌کنید، احتمالاً می‌دانید که این ابزار می‌تواند کدهای پروژه را بررسی کند، فایل‌ها را تغییر دهد، خطاها را پیدا کند و دستورات ترمینال را اجرا کند. اما آیا می‌دانستید که می‌توان Claude Code را به یک API سفارشی متصل کرد؟

برای این کار الزاماً نیازی نیست ساختار پروژه یا کدهای برنامه خود را تغییر دهید. با تنظیم چند متغیر محیطی مانند ANTHROPIC_BASE_URL و ANTHROPIC_AUTH_TOKEN می‌توانید درخواست‌های Claude Code را از طریق یک API Gateway سازگار با Anthropic ارسال کنید.

در این آموزش، مراحل نصب Claude Code در ویندوز و macOS، دریافت API Key، اتصال به Sinox API، انتخاب مدل و رفع خطاهای متداول را قدم‌به‌قدم بررسی می‌کنیم.

Claude Code چیست و چه کاربردی دارد؟

Claude Code ابزار کدنویسی هوشمند Anthropic است که می‌تواند مستقیماً با فایل‌ها و ساختار پروژه‌های نرم‌افزاری کار کند.

برخلاف یک چت‌بات معمولی که بیشتر برای پرسش‌وپاسخ استفاده می‌شود، Claude Code می‌تواند کدهای موجود را تحلیل کند، تغییرات پیشنهادی ارائه دهد، فایل‌ها را ویرایش کند و با اجازه کاربر دستورات لازم را اجرا کند.

برخی کاربردهای مهم Claude Code عبارت‌اند از:

• بررسی و تحلیل کدهای یک پروژه

• شناسایی و رفع خطاهای برنامه‌نویسی

• نوشتن تست و مستندات فنی

• بازنویسی و بهینه‌سازی بخش‌هایی از کد

• کمک به توسعه قابلیت‌های جدید نرم‌افزار

Claude Code علاوه بر رابط خط فرمان یا CLI، در بعضی محیط‌های توسعه نیز قابل استفاده است. تمرکز این مقاله روی نسخه خط فرمان و اتصال آن به API سفارشی است.

تفاوت Claude Code و Claude Desktop چیست؟

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

بنابراین، اگر قبلاً اتصال API به Claude Desktop را یاد گرفته‌اید، برای استفاده از Claude Code باید تنظیمات مخصوص این ابزار را انجام دهید.

پیش‌نیازهای اتصال Claude Code به API سفارشی

قبل از شروع، موارد زیر را آماده کنید:

1. یک کامپیوتر با ویندوز یا macOS سازگار

2. دسترسی به ترمینال یا PowerShell

3. اتصال اینترنت

4. نسخه نصب‌شده Claude Code یا امکان نصب آن

5. یک API Key معتبر از ارائه‌دهنده سازگار با Anthropic

6. شناسه مدل Claude که ارائه‌دهنده پشتیبانی می‌کند

در این آموزش از Sinox API به‌عنوان نمونه استفاده می‌کنیم. این سرویس علاوه بر رابط سازگار با OpenAI، از فرمت Anthropic Messages API نیز برای مدل‌های Claude پشتیبانی می‌کند.

آموزش نصب Claude Code در ویندوز و macOS

ابتدا باید Claude Code را روی سیستم نصب کنید. روش نصب در سیستم‌عامل‌های مختلف کمی متفاوت است.

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

در ویندوز ۱۰ یا ۱۱، PowerShell را باز کنید و دستور نصب رسمی را اجرا کنید:

irm https://claude.ai/install.ps1 | iex

این دستور اسکریپت نصب Claude Code را از دامنه رسمی Claude دریافت و اجرا می‌کند. پیش از اجرای اسکریپت‌های اینترنتی، از معتبر بودن منبع اطمینان حاصل کنید.

پس از پایان نصب، PowerShell را دوباره باز کنید و دستور زیر را وارد کنید:

claude --version

اگر شماره نسخه نمایش داده شد، ابزار نصب شده است.

اگر فرمان claude شناسایی نشد، ممکن است مسیر نصب هنوز به PATH اضافه نشده باشد. ترمینال را دوباره اجرا کنید و راهنمای نصب رسمی را بررسی کنید.

نصب Claude Code در macOS

در مک، برنامه Terminal را باز کنید و دستور زیر را اجرا کنید:

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

پس از نصب، نسخه برنامه را بررسی کنید:

claude --version

همچنین می‌توانید وضعیت نصب را با دستور زیر بررسی کنید:

claude doctor

برای نصب و به‌روزرسانی، بهتر است از روش‌های رسمی معرفی‌شده در مستندات Claude Code استفاده کنید.

دریافت API Key برای اتصال Claude Code

برای اتصال Claude Code به یک سرویس سفارشی، به کلید API معتبر نیاز دارید.

در Sinox API مراحل کلی به این صورت است:

1. وارد وب‌سایت Sinox API شوید.

2. وارد داشبورد حساب خود شوید.

3. بخش «کلیدهای API» را باز کنید.

4. یک کلید جدید با نوع پکیج موردنظر بسازید.

5. کلید را کپی کرده و در محلی امن نگهداری کنید.

کلید API اطلاعات محرمانه محسوب می‌شود. آن را در مخزن عمومی GitHub، فایل‌های قابل‌انتشار پروژه یا اسکرین‌شات‌ها قرار ندهید.

برای ابزارهایی مانند Claude Code که ممکن است در یک کار چندین درخواست با Context طولانی ارسال کنند، بررسی پکیج توکنی می‌تواند انتخاب مناسبی باشد. البته انتخاب نهایی به تعرفه و الگوی مصرف پروژه بستگی دارد.

آموزش اتصال Claude Code به Sinox API

برای اتصال Claude Code به یک Gateway سازگار با Anthropic، سه تنظیم اصلی نیاز داریم.

نکته بسیار مهم: برای Claude Code در Sinox، آدرس پایه باید https://sinoxapi.com باشد؛ یعنی بدون /v1.

این تفاوت به این دلیل است که Claude Code از رابط سازگار با Anthropic استفاده می‌کند و مسیر /v1/messages را خودش به آدرس پایه اضافه می‌کند.

تنظیم Claude Code در ویندوز با PowerShell

PowerShell را باز کنید و دستورات زیر را وارد کنید:

$env:ANTHROPIC_BASE_URL="https://sinoxapi.com"
$env:ANTHROPIC_AUTH_TOKEN="YOUR_SINOX_API_KEY"
$env:ANTHROPIC_MODEL="t-claude-sonnet-5"

به‌جای YOUR_SINOX_API_KEY کلید واقعی خودتان را قرار دهید.

شناسه مدل نمونه بالا برای کلید توکنی است. اگر از کلید ریکوستی استفاده می‌کنید، باید شناسه سازگار با همان نوع کلید را از داشبورد Sinox انتخاب کنید.

سپس در همان پنجره PowerShell دستور زیر را اجرا کنید:

claude

تنظیمات انجام‌شده با $env: فقط برای نشست فعلی PowerShell و فرایندهای اجراشده از آن اعمال می‌شوند. بنابراین با باز کردن یک ترمینال جدید، ممکن است لازم باشد متغیرها را دوباره تنظیم کنید.

تنظیم Claude Code در macOS

در Terminal مک، دستورات زیر را وارد کنید:

export ANTHROPIC_BASE_URL="https://sinoxapi.com"
export ANTHROPIC_AUTH_TOKEN="YOUR_SINOX_API_KEY"
export ANTHROPIC_MODEL="t-claude-sonnet-5"

سپس Claude Code را اجرا کنید:

claude

این تنظیمات نیز برای نشست فعلی ترمینال اعمال می‌شوند.

اگر می‌خواهید از آن‌ها در نشست‌های بعدی استفاده کنید، می‌توانید متغیرهای غیرمحرمانه را در تنظیمات Shell ذخیره کنید. برای نگهداری API Key بهتر است از روش‌های امن مدیریت اطلاعات محرمانه استفاده کنید.

تنظیم دائمی Claude Code با settings.json

اگر نمی‌خواهید هر بار متغیرهای محیطی را وارد کنید، Claude Code امکان استفاده از فایل تنظیمات را نیز فراهم می‌کند.

فایل تنظیمات کاربر معمولاً در مسیر زیر قرار دارد:

در macOS:

~/.claude/settings.json

در ویندوز:

%USERPROFILE%\.claude\settings.json

نمونه ساختار فایل:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://sinoxapi.com",
    "ANTHROPIC_MODEL": "t-claude-sonnet-5"
  }
}

در این مثال، آدرس سرور و شناسه مدل در فایل ذخیره شده‌اند. کلید API را می‌توانید جداگانه و به‌صورت امن از طریق متغیر محیطی یا ابزار مدیریت Secrets در اختیار Claude Code قرار دهید.

اگر تصمیم گرفتید کلید را نیز در فایل تنظیمات کاربر ذخیره کنید، توجه داشته باشید که محتوای فایل به‌صورت متن قابل‌خواندن روی سیستم قرار می‌گیرد. دسترسی به آن را محدود کنید و هرگز کلید را در فایل تنظیمات پروژه‌ای که وارد Git می‌شود قرار ندهید.

چگونه مدل Claude را در Sinox انتخاب کنیم؟

یکی از موارد مهم در اتصال Claude Code، انتخاب شناسه مدل صحیح است.

در Sinox API شناسه مدل با نوع کلید ارتباط دارد.

برای مثال:

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

همچنین می‌توانید فهرست مدل‌های فعال را از بخش مدل‌ها در داشبورد یا Endpoint زیر دریافت کنید:

GET https://sinoxapi.com/v1/models

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

اگر نوع کلید و شناسه مدل با یکدیگر مطابقت نداشته باشند، ممکن است خطای billing_type_mismatch دریافت کنید.

تست اتصال Claude Code و اجرای اولین دستور

بعد از انجام تنظیمات، وارد پوشه پروژه موردنظر شوید.

برای مثال، در ترمینال:

cd my-project
claude

با اجرای دستور claude، محیط تعاملی Claude Code باز می‌شود.

حالا می‌توانید یک درخواست ساده وارد کنید:

ساختار این پروژه را بررسی کن و توضیح بده هر پوشه چه کاربردی دارد.

اگر اتصال به‌درستی برقرار شده باشد و مدل انتخابی پاسخ دهد، Claude Code شروع به بررسی پروژه می‌کند.

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

فایل‌های اصلی پروژه را بررسی کن و سه پیشنهاد برای بهبود کیفیت کد ارائه بده. فعلاً هیچ فایلی را تغییر نده.

این درخواست برای اولین تست مناسب است؛ چون بدون نیاز به تغییر فایل‌ها، امکان بررسی عملکرد مدل را فراهم می‌کند.

نکته امنیتی: قبل از تأیید اجرای دستورات یا تغییر فایل‌ها توسط Claude Code، اقدامات پیشنهادی ابزار را بررسی کنید. بهتر است آزمایش اولیه را روی یک پروژه آزمایشی یا مخزن دارای نسخه پشتیبان انجام دهید.

خطاهای رایج اتصال Claude Code به API سفارشی

در زمان پیکربندی Claude Code ممکن است با خطاهایی روبه‌رو شوید. بیشتر مشکلات به تنظیمات احراز هویت، Base URL یا شناسه مدل مربوط هستند.

خطای 401: مشکل API Key

این خطا معمولاً به معنی نامعتبر بودن کلید یا مشکل احراز هویت است.

بررسی کنید که کلید Sinox را درست وارد کرده باشید و فاصله یا کاراکتر اضافی در مقدار آن وجود نداشته باشد.

اگر قبلاً Claude Code را به حساب یا کلید دیگری متصل کرده‌اید، ممکن است تنظیمات احراز هویت قبلی با تنظیمات جدید تداخل داشته باشند.

در چنین شرایطی، وضعیت اعتبارنامه‌ها و متغیر ANTHROPIC_API_KEY را نیز بررسی کنید.

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

یکی از رایج‌ترین دلایل این خطا، استفاده از Base URL نادرست است.

برای Claude Code در Sinox مقدار صحیح این است:

https://sinoxapi.com

نه:

https://sinoxapi.com/v1

اگر آدرس درست است، شناسه مدل را بررسی کنید و مطمئن شوید مدل انتخاب‌شده در سرویس فعال است.

خطای 402: مشکل سهمیه یا نوع پکیج

خطای 402 ممکن است به تمام شدن سهمیه، انقضای پکیج یا ناهماهنگی نوع کلید و مدل مربوط باشد.

برای مثال، استفاده از شناسه مدل توکنی همراه کلید ریکوستی می‌تواند خطای billing_type_mismatch ایجاد کند.

برای رفع مشکل، نوع کلید، شناسه مدل و موجودی پکیج را در داشبورد بررسی کنید.

خطای 429: تعداد درخواست زیاد

این خطا معمولاً زمانی رخ می‌دهد که تعداد درخواست‌ها یا درخواست‌های هم‌زمان از محدودیت سرویس عبور کرده باشد.

بهتر است کمی صبر کنید و در صورت نیاز، تعداد درخواست‌های هم‌زمان را کاهش دهید.

خطای Timeout یا عدم پاسخ مدل

گاهی درخواست‌های Claude Code شامل فایل‌ها، تاریخچه گفتگو و اطلاعات زیادی از پروژه هستند.

این موضوع می‌تواند زمان پردازش را افزایش دهد.

اگر درخواست پاسخ نمی‌دهد، وضعیت سرویس، حجم Context و اتصال شبکه را بررسی کنید. همچنین می‌توانید یک درخواست ساده‌تر ارسال کنید تا مشخص شود مشکل از اتصال است یا حجم پردازش.

آیا Claude Code مصرف توکن زیادی دارد؟

Claude Code برخلاف یک چت‌بات ساده، ممکن است برای انجام یک کار چندین بار با مدل ارتباط برقرار کند.

برای مثال، هنگام رفع یک باگ، ابزار ممکن است فایل‌ها را بخواند، کد را تحلیل کند، تغییراتی پیشنهاد دهد و نتیجه اجرای تست‌ها را دوباره به مدل ارسال کند.

در نتیجه، حجم توکن‌های ورودی و خروجی می‌تواند افزایش پیدا کند.

برای مدیریت بهتر مصرف:

• وظایف را تا حد امکان مشخص و محدود تعریف کنید.

• از ارسال فایل‌های غیرضروری جلوگیری کنید.

• پروژه‌های بزرگ را به وظایف کوچک‌تر تقسیم کنید.

• گزارش مصرف API را در داشبورد بررسی کنید.

• پکیج توکنی و ریکوستی را متناسب با الگوی مصرف خود مقایسه کنید.

برای آشنایی بیشتر با نحوه محاسبه مصرف، مقاله «توکن هوش مصنوعی چیست؟ آموزش محاسبه هزینه API» را مطالعه کنید.

سؤالات متداول درباره اتصال Claude Code

آیا Claude Code از API سفارشی پشتیبانی می‌کند؟

بله. Claude Code امکان تنظیم آدرس سرور و اعتبارنامه‌های اتصال به Gatewayهای سازگار با Anthropic را فراهم می‌کند.

آیا برای اتصال Claude Code به Sinox باید کد پروژه را تغییر دهیم؟

خیر. تنظیم اتصال معمولاً از طریق متغیرهای محیطی یا فایل تنظیمات Claude Code انجام می‌شود و نیازی به تغییر کد اصلی پروژه ندارد.

آیا Base URL در Claude Code و OpenAI SDK یکسان است؟

خیر. در Sinox، آدرس پایه Claude Code برابر با https://sinoxapi.com است، اما برای OpenAI SDK از https://sinoxapi.com/v1 استفاده می‌شود.

آیا می‌توان Claude Code را در ویندوز بدون WSL نصب کرد؟

بله. Claude Code روش نصب بومی برای ویندوز دارد. برای برخی قابلیت‌ها و محیط‌های کاری، نصب Git for Windows یا تنظیمات تکمیلی ممکن است لازم باشد.

آیا Claude Code با پکیج توکنی Sinox کار می‌کند؟

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

جمع‌بندی

اتصال Claude Code به API سفارشی روشی کاربردی برای استفاده از Gatewayهای سازگار با Anthropic در محیط توسعه نرم‌افزار است.

برای این کار کافی است Claude Code را نصب کنید، API Key معتبر دریافت کنید و متغیرهای ANTHROPIC_BASE_URL، ANTHROPIC_AUTH_TOKEN و ANTHROPIC_MODEL را مطابق ارائه‌دهنده تنظیم کنید.

در Sinox API، مهم‌ترین نکته استفاده از Base URL بدون /v1 و انتخاب شناسه مدل متناسب با نوع کلید است.

با انجام این تنظیمات، می‌توانید Claude Code را از طریق Sinox اجرا کنید، اتصال را آزمایش کنید و از قابلیت‌های کدنویسی هوشمند آن در پروژه‌های خود استفاده کنید.

برای دریافت کلید و مشاهده مدل‌های پشتیبانی‌شده، به Sinox API و مستندات اتصال API مراجعه کنید.