اتصال Claude Code به API ایرانی با پرداخت ریالی

Claude Code یکی از بهترین دستیارهای کدنویسی امروز است. داخل ترمینال اجرا می‌شود، کل پروژه را می‌خواند، فایل‌ها را ویرایش می‌کند، تست می‌گیرد و تا وقتی کار تمام نشده جلو می‌رود. مشکل همیشگی توسعه‌دهنده‌های ایرانی اما روشن است: حساب Anthropic با کارت ایرانی ساخته نمی‌شود، IP ایران مسدود است و پرداخت دلاری دردسر دارد.

هوشوانا یک API سازگار با Anthropic Messages دارد. یعنی Claude Code بدون هیچ تغییری در کد خودش، فقط با عوض کردن دو متغیر محیطی به هوشوانا وصل می‌شود و شما هزینه را از کیف پول ریالی‌تان پرداخت می‌کنید. در این راهنما همه‌ی مراحل را با هم انجام می‌دهیم.

پیش‌نیازها

پیش از شروع این‌ها را آماده کنید:

• یک حساب هوشوانا با شماره‌ی موبایل (ثبت‌نام کمتر از یک دقیقه طول می‌کشد)
• کمی اعتبار در کیف پول؛ برای شروع حتی صد هزار تومان هم کافی است
• Node.js نسخه‌ی ۱۸ یا بالاتر روی سیستم
• یک ترمینال: روی مک و لینوکس همان ترمینال پیش‌فرض، روی ویندوز PowerShell یا WSL

قدم اول: ساخت کلید API

وارد داشبورد شوید و از بخش «کلیدهای API» روی «ساخت کلید جدید» بزنید. یک نام قابل تشخیص مثل «Claude Code لپ‌تاپ» بگذارید. کلید فقط یک بار نمایش داده می‌شود و با hv- شروع می‌شود، پس همان لحظه آن را در جای امنی نگه دارید.

پیشنهاد ما این است که برای Claude Code یک کلید جدا بسازید و روی آن قانون بگذارید:

• سقف خرج روزانه: مثلاً ۲۰۰ هزار تومان، تا اگر عاملی در حلقه گیر کرد، کیف پول خالی نشود.
• مدل‌های مجاز: گروه سیستمی «کدنویسی» را انتخاب کنید تا کلید فقط به مدل‌های مناسب این کار دسترسی داشته باشد.
• Endpoint مجاز: فقط Anthropic Messages. این‌طوری اگر کلید جایی لو برود، برای کار دیگری قابل استفاده نیست.

قدم دوم: نصب Claude Code

اگر Claude Code را نصب نکرده‌اید، با npm نصبش کنید:

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

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

قدم سوم: تنظیم متغیرهای محیطی

Claude Code دو متغیر را می‌خواند: آدرس پایه‌ی API و توکن احراز هویت. روی مک و لینوکس این خطوط را به انتهای فایل ‎~/.zshrc یا ‎~/.bashrc اضافه کنید:

export ANTHROPIC_BASE_URL="https://hooshvana.ir/api"
export ANTHROPIC_AUTH_TOKEN="hv-کلید-شما"
export ANTHROPIC_MODEL="anthropic/claude-sonnet-5.5"
export ANTHROPIC_SMALL_FAST_MODEL="anthropic/claude-haiku-5.5"

دقت کنید که آدرس پایه بدون ‎/v1 نوشته می‌شود، چون Claude Code خودش مسیر ‎/v1/messages را اضافه می‌کند. روی ویندوز در PowerShell می‌توانید از این دستورها استفاده کنید:

setx ANTHROPIC_BASE_URL "https://hooshvana.ir/api"
setx ANTHROPIC_AUTH_TOKEN "hv-کلید-شما"
setx ANTHROPIC_MODEL "anthropic/claude-sonnet-5.5"

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

قدم چهارم: انتخاب مدل مناسب

هوشوانا همه‌ی مدل‌های Claude را از طریق شناسه‌های کامل مثل anthropic/claude-sonnet-5.5 در اختیار شما می‌گذارد. انتخاب مدل مستقیم روی کیفیت و هزینه اثر می‌گذارد:

قیمت‌ها با نرخ فعلی دلار در هوشوانا محاسبه شده‌اند و جدول به‌روز همیشه در صفحه‌ی قیمت‌ها هست. برای بیشتر پروژه‌ها Sonnet 5.5 بهترین نقطه‌ی شروع است. وقتی به کار سنگینی رسیدید، داخل Claude Code با دستور ‎/model مدل را موقتاً عوض کنید.

قدم پنجم: کم کردن هزینه با کش

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

چند عادت ساده هم هزینه را پایین نگه می‌دارد:

• پروژه را با فایل CLAUDE.md توضیح دهید تا مدل برای فهمیدن ساختار، کل مخزن را نخواند.
• وقتی موضوع کار عوض شد، با ‎/clear گفت‌وگوی تازه شروع کنید تا کانتکست قدیمی بی‌دلیل ارسال نشود.
• برای جست‌وجو و کارهای تکراری از Haiku استفاده کنید و Opus را برای تصمیم‌های مهم نگه دارید.

عیب‌یابی رایج

خطای ۴۰۱: کلید را درست کپی نکرده‌اید یا کلید متوقف شده است. در داشبورد وضعیت کلید را ببینید و مطمئن شوید فاصله‌ی اضافه در ابتدا یا انتهای آن نیست.

خطای ۴۰۲: موجودی کیف پول کافی نیست. هوشوانا پیش از هر درخواست، بدترین حالت هزینه را تخمین می‌زند. کیف پول را شارژ کنید یا مقدار max_tokens را پایین بیاورید.

خطای ۴۰۳ با پیام «مدل مجاز نیست»: روی کلید قانون مدل مجاز گذاشته‌اید و مدلی که Claude Code درخواست کرده در فهرست نیست. یا مدل را به فهرست اضافه کنید یا متغیر ANTHROPIC_MODEL را اصلاح کنید.

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

امنیت کلید

کلید API را هرگز داخل مخزن گیت قرار ندهید. اگر روی سرور مشترک کار می‌کنید، روی کلید فهرست IP مجاز بگذارید تا فقط از سیستم شما قابل استفاده باشد. اگر احساس کردید کلید لو رفته، در داشبورد آن را باطل کنید و کلید تازه بسازید؛ این کار چند ثانیه بیشتر طول نمی‌کشد.

گزارش مصرف

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

جمع‌بندی

با دو متغیر محیطی، Claude Code بدون تحریم و با پرداخت ریالی کار می‌کند. یک کلید جدا با سقف خرج بسازید، Sonnet 5.5 را مدل پیش‌فرض بگذارید، از کش و دستور ‎/clear استفاده کنید و مصرف را در داشبورد زیر نظر داشته باشید. اگر در راه‌اندازی به مشکل خوردید، از بخش پشتیبانی تیکت بزنید؛ تیم فنی هوشوانا هر روز پاسخ‌گوی شماست.