آشا آشا AI Gateway
ورود شروع رایگان

Claude Code

کلود کد را به‌جای اتصال مستقیم به Anthropic، از طریق درگاه آشا وصل کنید؛ با جابه‌جایی خودکار بین پروایدرها، کنترل هزینهٔ تیم و مصرف کاملاً شفاف.

Claude Code عامل (Agent) کدنویسیِ خط‌فرمانی Anthropic است. وقتی آن را به آشا وصل می‌کنید، همهٔ درخواست‌ها از درگاه عبور می‌کنند و شما علاوه بر مدل‌های Anthropic، کنترل بیشتری روی پایداری، هزینه و نظارت مصرف خواهید داشت.

!

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

چرا باید کلود کد را به آشا وصل کنیم؟

آشا یک لایهٔ پایداری و مدیریت بین Claude Code و API ارائه‌دهندگان اضافه می‌کند و چند مزیت کلیدی برای شما و سازمانتان فراهم می‌کند.

جابه‌جایی خودکار پروایدر برای دسترس‌پذیری بالا

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

کنترل بودجهٔ سازمانی

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

دید و تحلیل مصرف

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

شروع سریع

این راهنما شما را در چند دقیقه به Claude Code‌ای که با آشا کار می‌کند می‌رساند.

گام ۱ — نصب کلود کد

macOS, Linux, WSL:

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

Windows PowerShell:

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

به Node.js نسخهٔ ۱۸ یا جدیدتر نیاز دارد.

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

گام ۲ — اتصال کلود کد به آشا

به‌جای ورود مستقیم با حساب Anthropic، Claude Code را با چند متغیر محیطی به آشا وصل کنید.

الزامات:

  • از آدرس کامل API آشا بدون پیشوند مسیر، یعنی https://app.asha-ai.ir استفاده کنید.
  • کلید API آشا را به‌عنوان ANTHROPIC_AUTH_TOKEN قرار دهید.
  • مهم: ANTHROPIC_API_KEY را صریحاً خالی کنید تا تداخل ایجاد نشود.
?

چرا ANTHROPIC_AUTH_TOKEN؟ درگاه آشا درخواست‌ها را با توکن Bearer احراز هویت می‌کند و Claude Code مقدار ANTHROPIC_AUTH_TOKEN را به‌صورت هدر Authorization: Bearer <token> ارسال می‌کند؛ همان الگویی که Anthropic برای درگاه‌های احراز Bearer مستند کرده است. اما ANTHROPIC_API_KEY به‌صورت x-api-key ارسال می‌شود، به‌عنوان اعتبارنامهٔ مستقیم Anthropic شناخته می‌شود و در حالت تعاملی برای تأیید روی یک لاگین ذخیره‌شده یک‌بار از شما پرسش می‌کند. خالی‌کردن آن مانع از برگشت Claude Code به احراز هویت مستقیم با Anthropic می‌شود.

این متغیرها را به فایل پوستهٔ خود اضافه کنید:

export ASHA_API_KEY="sk-asha-your-key"
export ANTHROPIC_BASE_URL="https://app.asha-ai.ir"
export ANTHROPIC_AUTH_TOKEN="$ASHA_API_KEY"
export ANTHROPIC_API_KEY="" # مهم: باید صریحاً خالی باشد
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 # اختیاری

و سپس پوسته را بارگذاری دوباره کنید تا مقادیر جدید فعال شوند:

source ~/.zshrc  # یا ~/.bashrc، یا یک ترمینال جدید باز کنید
ی

توصیه می‌کنیم این خطوط را در فایل پوستهٔ خود نگه دارید (~/.bashrc، ~/.zshrc یا ~/.config/fish/config.fish).

!

ترتیب تعریف مهم است: ANTHROPIC_AUTH_TOKEN="$ASHA_API_KEY" هنگام بارگذاری پوسته توسعه (expand) می‌شود. اگر ASHA_API_KEY «بعداً» در همان فایل، در فایل دیگری، یا توسط یک ابزار مدیریت اسرار پس از اجرای پوسته تعریف شده باشد، توکن به مقدار خالی توسعه می‌یابد و همهٔ درخواست‌ها با خطای احراز هویت رد می‌شوند. مطمئن شوید کلید «قبل از» مصرف‌شدن توسط ANTHROPIC_AUTH_TOKEN تعریف شده یا آن را در فایلی بگذارید که زودتر بارگذاری می‌شود (مثل ~/.zshenv در zsh).

ق

بهداشت اسرار: قرار دادن کلید به‌صورت متنی در فایل پوسته، فایلی است که به‌راحتی ممکن است سهواً در یک مخزن dotfiles منتشر یا در یک gist پیست شود. در عوض کلید را از keychain سیستم‌عامل بخوانید، مثلاً در macOS: export ASHA_API_KEY="$(security find-generic-password -s asha -w)". اگر کلیدی درز کرد، فوراً آن را در داشبورد آشا لغو و بچرخانید.

به‌جای پوسته می‌توانید با فایل تنظیمات سطح پروژه در .claude/settings.local.json پوشهٔ ریشهٔ پروژه پیکربندی کنید: 

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://app.asha-ai.ir",
    "ANTHROPIC_AUTH_TOKEN": "<sk-asha-your-key>",
    "ANTHROPIC_API_KEY": "",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

این روش تنظیمات را به پروژه محدود می‌کند و اشتراک‌گذاری آن با تیم از طریق کنترل نسخه راحت است (فقط مراقب باشید کلید API را در مخزن نیندازید).

!

محل متغیرها: این متغیرها را در فایل .env سطح پروژه نگذارید؛ نصب‌کنندهٔ بومی Claude Code فایل‌های استاندارد .env را نمی‌خواند.

گام ۳ — پاک‌کردن لاگین Anthropic کش‌شده

اگر پیش از این با حساب Anthropic وارد Claude Code شده‌اید، باید یک‌بار /logout اجرا کنید تا نشست کش‌شده حذف شود. هم‌زمانیِ یک لاگین ذخیره‌شده و یک اعتبارنامهٔ درگاه، هشدار تداخل ایجاد می‌کند و در هنگام شروع، رفتار غیرمنتظره‌ای — معمولاً خطاهای «مدل پیدا نشد» برای مدل‌های فقط‌درگاهی — به‌وجود می‌آورد.

Claude Code slash command 
/logout

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

ت

اگر هرگز با Anthropic وارد Claude Code نشده‌اید، می‌توانید این گام را رد کنید.

ج

محل نشست کش‌شده: در macOS نشست در Keychain به‌عنوان یک گذرواژهٔ عمومی به نام Claude Code-credentials ذخیره می‌شود. برای بررسی وجود نشست قدیمی: security find-generic-password -s "Claude Code-credentials". اگر پس از /logout همچنان موردی چاپ شد، با security delete-generic-password -s "Claude Code-credentials" حذفش کنید و دوباره claude را اجرا کنید.

گام ۴ — شروع نشست

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

Terminal bash 
cd /path/to/your/project
claude

اتصال برقرار است؛ هر دستوری بدهید از درگاه آشا عبور می‌کند.

گام ۵ — بررسی اتصال

اتصال را با دستور /status داخل Claude Code تأیید کنید:

Claude Code /status 
Auth token:        ANTHROPIC_AUTH_TOKEN
Anthropic base URL: https://app.asha-ai.ir

اگر خط Auth token به ANTHROPIC_API_KEY اشاره کرد، یا خط Login method حساب Claude را نشان داد، یعنی متغیرهای محیطی به نشست نرسیده‌اند؛ پوسته را بارگذاری دوباره کنید و claude را دوباره اجرا کنید.

هم‌چنین می‌توانید داشبورد فعالیت آشا را بررسی کنید تا درخواست‌ها را همان لحظه ببینید.

نحوهٔ کار

آشا نقطهٔ پایانی سازگار با Anthropic Messages API ارائه می‌دهد:

  • اتصال مستقیم: با تنظیم ANTHROPIC_BASE_URL به آدرس درگاه، Claude Code مستقیماً با پروتکل بومی خود با آشا صحبت می‌کند؛ هیچ پروکسی محلی لازم نیست.
  • پوست Anthropic: پوست Anthropicِ آشا دقیقاً مانند API خود Anthropic رفتار می‌کند؛ نگاشت مدل‌ها را انجام می‌دهد و قابلیت‌های پیشرفته مثل بلوک‌های «تفکر» و استفادهٔ بومی از ابزارها را منتقل می‌کند.
  • صورتحساب: هزینه از اعتبار کیف پول آشا کسر می‌شود و مصرف (شامل توکن‌های استدلال) در داشبورد آشا نمایش داده می‌شود.

پیکربندی مدل‌ها

Claude Code با چند متغیر محیطی مشخص می‌کند هر نقش با کدام مدل اجرا شود. می‌توانید هر نقش را به یک مدل خاص مسیردهی کنید:

Shell ~/.zshrc 
export ANTHROPIC_DEFAULT_FABLE_MODEL="anthropic/claude-fable-latest"
export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-latest"
export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-latest"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-latest"
export CLAUDE_CODE_SUBAGENT_MODEL="anthropic/claude-opus-latest"
متغیرتوضیح
ANTHROPIC_DEFAULT_FABLE_MODELمدل برای کارهای کلاس Fable (سخت‌ترین کارهای استدلال و بلندمدت).
ANTHROPIC_DEFAULT_OPUS_MODELمدل برای کارهای کلاس Opus (مثل استدلال پیچیده).
ANTHROPIC_DEFAULT_SONNET_MODELمدل برای کارهای کلاس Sonnet (مثل کدنویسی عمومی).
ANTHROPIC_DEFAULT_HAIKU_MODELمدل برای کارهای کلاس Haiku (مثل تکمیل‌های سریع).
CLAUDE_CODE_SUBAGENT_MODELمدل برای کارهای ساب‌ایجنت‌های تولیدشده توسط Claude Code.
!

Claude Code نسخهٔ 2.1.x، Fable را به‌عنوان کلاس چهارم اضافه کرد. وقتی Claude Code به درگاه وصل است، Fable به‌صورت پیش‌فرض در /model ارائه نمی‌شود؛ تنظیم ANTHROPIC_DEFAULT_FABLE_MODEL تنها راهِ انتخاب‌پذیرکردن آن است.

پس از تنظیم این مقادیر، در داخل Claude Code دستور /model را باز کنید و مطمئن شوید هر کلاس مدلی که انتظار دارید فهرست شده است و در داشبورد فعالیت نیز تأیید کنید درخواست‌ها به همان مدل‌ها مسیردهی می‌شوند.

این‌ها را به همان فایل پوسته یا فایل تنظیمات پروژه که در گام ۲ تنظیم کردید اضافه کنید.

Claude Code برای مدل‌های Anthropic بهینه شده است و ممکن است با سایر ارائه‌دهندگان درست کار نکند.

انتخاب‌گر مدل درگاه

بارگیری خودکار فهرست مدل درگاه به‌صورت تک‌به‌تک (opt-in) است؛ با تنظیم CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 انتخاب‌گر مدل فعال می‌شود. این انتخاب‌گر مجموعه‌ای از بالاترین رتبه‌ها را نمایش می‌دهد، نه کل فهرست درگاه. سنجاق‌کردن مدل با یکی از متغیرهای بالا، آن را مستقیم انتخاب می‌کند و از انتخاب‌گر رد می‌شود. فهرستِ بارگیری‌شده به‌صورت محلی ذخیره می‌شود و هنگام شروع‌به‌کار، تازه‌سازی می‌شود؛ بنابراین پس از فعال‌سازی، Claude Code را دوباره راه‌اندازی کنید.

حالت سریع (Fast Mode)

حالت سریع Anthropic خروجی را تا ۲٫۵ برابر سریع‌تر با قیمت پریمیوم ارائه می‌کند. حالت سریع فقط روی Claude Opus 4.6، 4.7، 4.8 و 5 در دسترس است — هیچ مدل Anthropic دیگری از آن پشتیبانی نمی‌کند.

برای هر نسخهٔ Opus پشتیبانی‌شده، سه راه برای درخواست حالت سریع از طریق آشا وجود دارد:

  1. ارسال speed: "fast" همراه با anthropic/claude-opus-5 یا نسخه‌های مشابه — آشا درخواست را به مدل *-fast متناظر هدایت می‌کند (مثل anthropic/claude-opus-5 ← anthropic/claude-opus-5-fast).
  2. فراخوانی مستقیم مدل *-fast.
  3. ارسال service_tier: "fast" یا service_tier: "priority" — کاملاً با speed: "fast" هم‌ارز است.

همهٔ مسیرها از طریق پروایدر Anthropic (first-party) عبور می‌کنند و هدر beta موردنیاز به‌صورت خودکار تزریق می‌شود.

استفاده از /fast در Claude Code

Claude Code دستور داخلی /fast دارد که حالت سریع را روشن/خاموش می‌کند. در این حالت Claude Code پارامتر speed: "fast" را همراه مدل Opus پیکربندی‌شده ارسال می‌کند؛ کافی است متغیر محیطی زیر را تنظیم کنید:

Shell ~/.zshrc 
export CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1
ت

به Claude Code نسخهٔ v2.1.96 یا جدیدتر نیاز دارد.

!

Claude Code فقط وقتی پارامتر speed: "fast" را ضمیمه می‌کند که شناسهٔ مدلِ انتخاب‌شده با یک نسخهٔ Opus پشتیبانی‌شده مطابقت داشته باشد (مثل anthropic/claude-opus-5). اگر ANTHROPIC_DEFAULT_OPUS_MODEL را روی الیاس (alias) مانند anthropic/claude-opus-latest بگذارید، /fast گزارش «Fast mode ON» می‌دهد اما درخواست‌ها بدون speed ارسال می‌شوند: سرعت و قیمت عادی. برای استفادهٔ واقعی از حالت سریع، متغیر را به یک شناسهٔ Opus مشخص مثل anthropic/claude-opus-5 سنجاق کنید.

قیمت‌گذاری

حالت سریع با قیمت پریمیوم نسبت به نرخ استاندارد توکن مدل Claude Opus پایه محاسبه می‌شود؛ نرخ‌های جاری را در مستندات Anthropic ببینید. وقتی حالت سریع فعال است، شیء usage پاسخ شامل "speed": "fast" است تا تأیید کند درخواست در لایهٔ سریع‌تر پردازش شده.

ن

اگر speed: "fast" برای مدلی که حالت سریع ندارد ارسال شود، همچنان در صورت وجود، لایهٔ سرویس priority درخواست می‌شود؛ در غیر این صورت درخواست با سرعت و قیمت عادی ادامه می‌یابد. Claude Fable لایهٔ سریع ندارد — روشن‌کردن /fast روی مدل Fable آن را سریع نمی‌کند؛ بلکه Claude Code نشست شما را به مدل Opus پیکربندی‌شده تغییر می‌دهد، پس درخواست‌های بعدی روی Opus اجرا و صورتحساب می‌شوند.

Agent SDK

Anthropic Agent SDK به شما اجازه می‌دهد عامل‌های هوش مصنوعی را برنامه‌نویسی‌شده با Python یا TypeScript بسازید. چون Agent SDK از Claude Code به‌عنوان زمان اجرا استفاده می‌کند، می‌توانید با همین متغیرهای محیطی که در بالا توضیح داده شد آن را به آشا وصل کنید.

GitHub Action

می‌توانید آشا را با GitHub Action رسمی Claude Code استفاده کنید. برای تطبیق با آشا، دو تغییر در گام اکشن اعمال کنید:

  1. کلید API آشا را از طریق ورودی anthropic_api_key بدهید (به‌صورت GitHub Secret به نام ASHA_API_KEY ذخیره کنید).
  2. ANTHROPIC_BASE_URL را روی آدرس درگاه و ANTHROPIC_AUTH_TOKEN را روی همان Secret در بخش env گام تنظیم کنید.
YAML .github/workflows/claude.yml 
- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ASHA_API_KEY }}
  env:
    ANTHROPIC_BASE_URL: https://app.asha-ai.ir
    ANTHROPIC_AUTH_TOKEN: ${{ secrets.ASHA_API_KEY }}

اکشن به ورودی anthropic_api_key نیاز دارد تا پیش از اجرای Claude Code راه‌اندازی شود و خودش ANTHROPIC_AUTH_TOKEN را نمی‌خواند؛ بنابراین همان ورودی، شرط راه‌اندازی را برآورده می‌کند در حالی که متغیر محیطی، کلید را در هدر Authorization قرار می‌دهد. برخلاف پیکربندی محلی، در اینجا ANTHROPIC_API_KEY خالی نیست — اکشن آن را از ورودی پر می‌کند — و این مشکلی نیست چون اجرا غیرتعاملی است و ANTHROPIC_BASE_URL همهٔ درخواست‌ها را به آشا هدایت می‌کند.

نوار وضعیت ردیابی هزینه

می‌توانید یک نوار وضعیت سفارشی به Claude Code اضافه کنید که هزینهٔ API آشا را لحظه‌ای نشان دهد؛ نوار وضعیت پروایدر، مدل، هزینهٔ تجمعی و تخفیف‌های کش را برای نشست جاری نمایش می‌دهد.

اسکریپت‌های نوار وضعیت را از مخزن نمونه‌ها دریافت، قابل‌اجرا (executable) کنید و به ~/.claude/settings.json اضافه کنید:

JSON ~/.claude/settings.json 
{
  "statusLine": {
    "type": "command",
    "command": "/path/to/statusline.sh"
  }
}

اسکریپت ANTHROPIC_AUTH_TOKEN را می‌خواند و در صورت نبود، به ANTHROPIC_API_KEY برمی‌گردد؛ پس کلید آشای تنظیم‌شده در گام ۲ را پیدا می‌کند.

چند نکتهٔ عملی:

  • پیش‌نیازها: statusline.sh یک wrapper کوچک است که npx tsx statusline.ts را اجرا می‌کند؛ بنابراین به Node.js و دسترسی شبکه نیاز دارد (npx در اولین استفاده، tsx را دانلود می‌کند که اولین نوسازی را کند می‌کند). هر دو فایل را دانلود و در یک پوشه نگه دارید.
  • فقط یک نوار وضعیت: settings.json فقط یک ورودی statusLine پشتیبانی می‌کند. اگر نوار وضعیت دیگری دارید، افزودن این یکی جایگزین آن می‌شود؛ ترکیب آن‌ها بدون نوشتن اسکریپت wrapper امکان‌پذیر نیست.
  • مصرف API: هر نوسازی، برای هر نسل جدید در نشست، یک درخواست به نقطهٔ پایانی «دریافت نسل» (generation) ارسال می‌کند.
  • فایل‌های وضعیت: وضعیت هر نشست در مسیری مانند /tmp/claude-asha-cost-<session-id>.json ذخیره می‌شود؛ این فایل‌ها کوچک‌اند و در بیشتر سیستم‌ها با ری‌استارت، پاک می‌شوند، ولی هر زمان بخواهید می‌توانید آن‌ها را حذف کنید.

رفع اشکال

  • خطای «مدل پیدا نشد» برای مدل‌های درگاه: معمولاً ناشی از یک تداخل اعتبارنامه است که در هنگام شروع، به‌صورت هشدار تداخل احراز هویت نمایان می‌شود. دو سناریو متمایز هست: (۱) اگر از قبل یک لاگین OAuth قدیمی Anthropic دارید، داخل Claude Code /logout بزنید، سپس خارج شوید و claude را دوباره اجرا کنید. (۲) اگر در فایل پوسته یک ANTHROPIC_API_KEY واقعی تنظیم شده (مثل یک کلید قدیمی Anthropic)، /logout کمکی نمی‌کند — فقط نشست OAuth کش‌شده را حذف می‌کند، نه متغیرهای محیطی را. در این حالت مطمئن شوید ANTHROPIC_API_KEY="" در فایل پوسته طبق گام ۲ تنظیم شده، سپس پوسته را بارگذاری دوباره کنید. با /status بررسی کنید توکن ANTHROPIC_AUTH_TOKEN و Base URL برابر آدرس آشا باشد.
  • خطاهای احراز هویت: مطمئن شوید کلید آشا در ANTHROPIC_AUTH_TOKEN است و ANTHROPIC_API_KEY یک رشتهٔ خالی ("") است. اگر ANTHROPIC_API_KEY یک کلید واقعی Anthropic داشته باشد، Claude Code آن را به‌صورت x-api-key ارسال می‌کند و ممکن است در برابر خود Anthropic احراز هویت کند. پس از ویرایش فایل پوسته، پوسته را بارگذاری دوباره کنید و اگر همچنان خطای احراز هویت دیدید، /logout را اجرا کنید.
  • خطای طول Context: اگر به سقف حافظه برخوردید، کار را به بخش‌های کوچک‌تر بشکنید یا نشست تازه‌ای شروع کنید.
  • حریم خصوصی: آشا کد‌های منبع و پرامپت‌های شما را ثبت نمی‌کند مگر اینکه صریحاً ثبت پرامپت را در تنظیمات حساب خود فعال کرده باشید. برای جزئیات، سیاست حریم خصوصی آشا را ببینید.