اتصال Claude Code به هوشوانا

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

چه چیزی به دست می‌آورید

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

پیش‌نیازها

1. حساب کاربری در هوشوانا.
2. یک کلید API که در صفحه‌ی کلیدها ساخته‌اید. کلید با hv- شروع می‌شود و فقط یک بار نمایش داده می‌شود.
3. اعتبار کافی در کیف پول. جلسه‌های طولانی Claude Code توکن زیادی مصرف می‌کنند، پس موجودی را از حداقل بالاتر نگه دارید.
4. خود Claude Code که نصب شده باشد:

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

روش سریع: نصب‌کننده‌ی یک‌خطی

اگر روی macOS یا Linux کار می‌کنید، می‌توانید تنظیمات را با یک دستور انجام دهید:

curl -fsSL https://hooshvana.ir/install.sh | bash

نصب‌کننده کلید API را از شما می‌پرسد و بعد این کارها را انجام می‌دهد:

• متغیرهای ANTHROPIC_BASE_URL (برابر https://hooshvana.ir/api) و ANTHROPIC_AUTH_TOKEN را برای Claude Code تنظیم می‌کند و سرور MCP هوشوانا را به Claude Code اضافه می‌کند.
• بلوک ارائه‌دهنده‌ی [model_providers.hooshvana] را با base_url = "https://hooshvana.ir/api/v1"، env_key = "HOOSHVANA_API_KEY" و wire_api = "responses" به تنظیمات Codex CLI اضافه می‌کند.
• سرور MCP هوشوانا را در ~/.cursor/mcp.json برای Cursor ثبت می‌کند.
• از هر فایلی که تغییر می‌دهد پیش از تغییر نسخه‌ی پشتیبان می‌گیرد.

پس از اجرای نصب‌کننده، ترمینال را ببندید و دوباره باز کنید تا متغیرها خوانده شوند. مدل‌ها را همچنان می‌توانید طبق بخش راه‌اندازی تنظیم کنید.

اجرای اسکریپت از اینترنت یعنی به آن اعتماد کرده‌اید. پیشنهاد ما این است که اول محتوای آن را ببینید و بعد اجرا کنید:

curl -fsSL https://hooshvana.ir/install.sh -o install.sh
less install.sh
bash install.sh

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

راه‌اندازی

Claude Code تنظیمات اتصال را از متغیرهای محیطی می‌خواند. چهار متغیر مهم این‌ها هستند:

نسخه‌های قدیمی‌تر Claude Code به‌جای ANTHROPIC_DEFAULT_HAIKU_MODEL متغیر ANTHROPIC_SMALL_FAST_MODEL را می‌خوانند. اگر مطمئن نیستید، هر دو را تنظیم کنید.

macOS و Linux

این خطوط را در ترمینال اجرا کنید، یا برای ماندگاری به ~/.zshrc یا ~/.bashrc اضافه کنید:

export ANTHROPIC_BASE_URL="https://hooshvana.ir/api"
export ANTHROPIC_AUTH_TOKEN="hv-YOUR_KEY"
export ANTHROPIC_MODEL="anthropic/claude-sonnet-4.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-4.5"
export ANTHROPIC_SMALL_FAST_MODEL="anthropic/claude-haiku-4.5"

# If you previously used an Anthropic key, remove it so it does not take precedence
unset ANTHROPIC_API_KEY

Windows (PowerShell)

$env:ANTHROPIC_BASE_URL = "https://hooshvana.ir/api"
$env:ANTHROPIC_AUTH_TOKEN = "hv-YOUR_KEY"
$env:ANTHROPIC_MODEL = "anthropic/claude-sonnet-4.6"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "anthropic/claude-haiku-4.5"
$env:ANTHROPIC_SMALL_FAST_MODEL = "anthropic/claude-haiku-4.5"
Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue

این مقدارها فقط برای همان پنجره‌ی PowerShell معتبرند. برای ماندگاری از روش settings.json در ادامه استفاده کنید.

روش ماندگار: فایل settings.json

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

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://hooshvana.ir/api",
    "ANTHROPIC_AUTH_TOKEN": "hv-YOUR_KEY",
    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4.5",
    "ANTHROPIC_SMALL_FAST_MODEL": "anthropic/claude-haiku-4.5"
  }
}

اگر این فایل از قبل وجود دارد، فقط بلوک env را به آن اضافه کنید و بقیه‌ی تنظیمات را دست نزنید. اگر در محیط شما ANTHROPIC_API_KEY تعریف شده، آن را حذف کنید؛ وگرنه Claude Code ممکن است همان کلید را به‌جای کلید هوشوانا بفرستد.

بررسی اتصال

در پوشه‌ی یک پروژه دستور زیر را اجرا کنید:

claude

داخل Claude Code دستور /status را بزنید. در خروجی باید آدرس https://hooshvana.ir/api و مدل anthropic/claude-sonnet-4.6 را ببینید. بعد یک سؤال کوتاه بپرسید، مثلاً «فایل‌های این پوشه را خلاصه کن». اگر پاسخ گرفتید، به گزارش‌ها بروید؛ درخواست‌های /messages با نام کلید، مدل و هزینه آنجا ثبت شده‌اند.

اگر Claude Code از شما خواست وارد حساب Anthropic شوید، یعنی متغیرها را نخوانده است. ترمینال را ببندید، دوباره باز کنید و /status را چک کنید.

اتصال سرور MCP هوشوانا

هوشوانا یک سرور MCP دارد که به Claude Code امکان می‌دهد مستقیم از پایگاه‌های دانش شما جست‌وجو کند، فهرست مدل‌ها را ببیند و مصرف حساب را گزارش دهد. این سرور از نوع Streamable HTTP و بدون حالت (stateless) است و با همان کلید هوشوانا احراز می‌شود.

claude mcp add --transport http -s user hooshvana https://hooshvana.ir/api/mcp --header "Authorization: Bearer hv-YOUR_KEY"

گزینه‌ی -s user سرور را برای همه‌ی پروژه‌های شما فعال می‌کند. ابزارهایی که در اختیار Claude Code قرار می‌گیرند:

برای بررسی، داخل Claude Code دستور /mcp را بزنید؛ سرور hooshvana باید وصل باشد. جزئیات بیشتر در راهنمای MCP آمده است.

مدل‌های پیشنهادی

Claude Code برای قابلیت‌هایی مثل ابزارها و ویرایش فایل روی رفتار مدل‌های Claude حساب می‌کند، پس بهترین نتیجه را با همین مدل‌ها می‌گیرید. شناسه‌های بالا نمونه هستند؛ فهرست دقیق را در کاتالوگ مدل‌ها ببینید. داخل Claude Code هم می‌توانید با /model مدل را عوض کنید.

کنترل هزینه

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

• برای Claude Code یک کلید جداگانه بسازید تا هزینه‌اش در گزارش‌ها جدا دیده شود.
• در قوانین کلید سقف خرج روزانه و سقف ماهانه بگذارید. وقتی سقف پر شود، درخواست‌ها با spend_cap_reached متوقف می‌شوند و کیف پول خالی نمی‌شود.
• در مدل‌های مجاز فقط anthropic/claude-sonnet-4.6 و anthropic/claude-haiku-4.5 را باز بگذارید.
• نقطه‌های پایانی مجاز را روی messages محدود کنید.
• گفت‌وگوهای طولانی را با /clear یا /compact کوتاه کنید تا زمینه‌ی تکراری فرستاده نشود.

رفع اشکال

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