رفتن به محتوا
Claude Code Docs غیر رسمی

پیکربندیِ دروازه‌ی LLM

دروازه‌های LLM (LLM gateway) یک لایه‌ی پراکسیِ متمرکز بینِ Claude Code و ارائه‌دهندگانِ مدل فراهم می‌کنند و اغلب این امکانات را می‌دهند:

  • احراز هویتِ متمرکز — نقطه‌ی واحد برای مدیریتِ کلیدهای API
  • ردیابیِ استفاده — پایشِ استفاده در سراسرِ تیم‌ها و پروژه‌ها
  • کنترلِ هزینه — اعمالِ بودجه و محدودیتِ نرخ
  • ثبتِ ممیزی (Audit logging) — ردیابیِ همه‌ی تعامل‌ها با مدل برای انطباق
  • مسیریابیِ مدل — جابه‌جایی بینِ ارائه‌دهندگان بدونِ تغییرِ کد

این صفحه نیازمندی‌ها و پیکربندیِ دروازه را برای Claude Code CLI پوشش می‌دهد. استقرارهای Enterprise Desktop می‌توانند ارائه‌دهندگانِ دروازه را از طریقِ managed settings پیکربندی کنند. اپلیکیشنِ Claude Desktop هم می‌تواند روی یک دروازه‌ی خودمیزبان اجرا شود، از طریقِ Cowork on 3P research preview که کلیدهای پیکربندیِ مخصوصِ خود را به‌کار می‌برد.

نیازمندی‌های دروازه

Section titled “نیازمندی‌های دروازه”

برای آن‌که یک دروازه‌ی LLM با Claude Code کار کند، باید این نیازمندی‌ها را برآورده کند:

فرمتِ API

دروازه باید دستِ‌کم یکی از فرمت‌های APIِ زیر را به کلاینت‌ها عرضه کند:

  1. Anthropic Messages: /v1/messages, /v1/messages/count_tokens

    • باید این هدرهای درخواست را فوروارد کند: anthropic-beta, anthropic-version

  2. Bedrock InvokeModel: /invoke, /invoke-with-response-stream

    • باید این فیلدهای بدنه‌ی درخواست را حفظ کند: anthropic_beta, anthropic_version

  3. Vertex rawPredict: :rawPredict, :streamRawPredict, /count-tokens:rawPredict

    • باید این هدرهای درخواست را فوروارد کند: anthropic-beta, anthropic-version

ناتوانی در فورواردِ هدرها یا حفظِ فیلدهای بدنه ممکن است به کاهشِ قابلیت‌ها یا عدمِ امکانِ استفاده از قابلیت‌های Claude Code منجر شود.

هدرهای درخواست

Claude Code هدرهای زیر را در درخواست‌های API می‌گنجاند:

هدرتوضیح
X-Claude-Code-Session-Idیک شناسه‌ی یکتا برای نشستِ جاریِ Claude Code. پراکسی‌ها می‌توانند با این هدر همه‌ی درخواست‌های APIِ یک نشست را بدونِ تجزیه‌ی بدنه‌ی درخواست تجمیع کنند.
X-Claude-Code-Agent-Idشناسه‌ی ساب‌ایجنت یا هم‌تیمی‌ای که درخواست را صادر کرده است. پراکسیِ تو می‌تواند با این هدر هزینه‌ی API را به ساب‌ایجنت‌های موازیِ منفرد درونِ یک نشست نسبت دهد، بدونِ تجزیه‌ی بدنه‌ی درخواست. تنها برای درخواست‌هایی حضور دارد که توسطِ یک ساب‌ایجنت یا هم‌تیمیِ درون‌فرایندی صادر شده‌اند.
X-Claude-Code-Parent-Agent-Idشناسه‌ی ایجنتی که ایجنتِ صادرکننده‌ی درخواست را به‌وجود آورده است. این را همراه با X-Claude-Code-Agent-Id به‌کار ببر تا هزینه‌های API را در سراسرِ ایجنت‌های تودرتو در پراکسیِ خودت نسبت دهی. تنها زمانی حضور دارد که خودِ ایجنتِ درخواست‌کننده توسطِ ایجنتِ دیگری به‌وجود آمده باشد.

هر دو هدرِ شناسه‌ی ایجنت، شناسه‌های گذرا و به‌ازای هر spawn هستند، نه شناسه‌های ماندگارِ کاربر یا دستگاه.

Claude Code همچنین یک بلاکِ کوتاهِ انتساب (attribution) را پیش از system prompt اضافه می‌کند که نسخه‌ی کلاینت و یک اثرِانگشتِ برگرفته از گفت‌وگو را در بر دارد. Anthropic API این بلاک را پیش از پردازش حذف می‌کند، پس روی prompt cachingِ شخصِ اول تأثیری ندارد. اگر دروازه‌ی تو کشِ promptِ خودش را بر پایه‌ی کلِ بدنه‌ی درخواست کلیددهی می‌کند، CLAUDE_CODE_ATTRIBUTION_HEADER=0 را تنظیم کن تا این بلاک حذف شود.

پیکربندی

Section titled “پیکربندی”

انتخابِ مدل

Section titled “انتخابِ مدل”

به‌طورِ پیش‌فرض، Claude Code برای فرمتِ APIِ انتخاب‌شده از نام‌های استانداردِ مدل استفاده می‌کند.

وقتی ANTHROPIC_BASE_URL به دروازه‌ای اشاره می‌کند که فرمتِ Anthropic Messages را عرضه می‌کند، Claude Code می‌تواند هنگامِ راه‌اندازی endpointِ /v1/models دروازه را پرس‌وجو کند و مدل‌های بازگشتی را به انتخابگرِ /model اضافه کند. برای فعال کردنِ این کار CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 را تنظیم کن. کشف به‌طورِ پیش‌فرض خاموش است تا دروازه‌هایی که با یک کلیدِ APIِ مشترک پشتیبانی می‌شوند، هر مدلی را که آن کلید به آن دسترسی دارد به هر کاربری نشان ندهند. هر ورودیِ کشف‌شده با برچسبِ «From gateway» مشخص می‌شود و وقتی در پاسخ فیلدِ display_name ارائه شده باشد، از آن استفاده می‌کند. این قابلیت به Claude Code نسخه‌ی v2.1.129 یا بالاتر نیاز دارد.

کشف تنها برای فرمتِ Anthropic Messages اعمال می‌شود. برای endpointهای pass-throughِ Bedrock یا Vertex اجرا نمی‌شود، و زمانی که ANTHROPIC_BASE_URL تنظیم نشده باشد یا به api.anthropic.com اشاره کند نیز اجرا نمی‌شود.

درخواستِ کشف به همان شیوه‌ی درخواست‌های inference احراز هویت می‌شود: ANTHROPIC_AUTH_TOKEN را به‌عنوانِ توکنِ bearer می‌فرستد، یا وقتی توکنِ احراز هویت تنظیم نشده باشد، ANTHROPIC_API_KEY را به‌عنوانِ هدرِ x-api-key می‌فرستد، همراه با هر هدری از ANTHROPIC_CUSTOM_HEADERS. تنها مدل‌هایی که شناسه‌شان با claude یا anthropic شروع می‌شود به انتخابگر افزوده می‌شوند. نتایج در ~/.claude/cache/gateway-models.json کش می‌شوند و در هر بارِ راه‌اندازی تازه می‌شوند. اگر درخواست شکست بخورد یا دروازه /v1/models را پیاده‌سازی نکرده باشد، انتخابگر به فهرستِ کش‌شده از راه‌اندازیِ قبلی یا به فهرستِ داخلیِ مدل‌ها بازمی‌گردد.

اگر دروازه‌ی تو از نام‌های مدلی استفاده می‌کند که با فیلترِ کشف تطبیق ندارند، از متغیرهای محیطیِ مستندشده در Model configuration برای افزودنِ دستیِ آن‌ها استفاده کن.

پیکربندیِ LiteLLM

Section titled “پیکربندیِ LiteLLM”

پیش‌نیازها

Section titled “پیش‌نیازها”
  • Claude Code که به آخرین نسخه به‌روزرسانی شده باشد
  • LiteLLM Proxy Server که مستقر و در دسترس باشد
  • دسترسی به مدل‌های Claude از طریقِ ارائه‌دهنده‌ی انتخابیِ تو

راه‌اندازیِ پایه‌ی LiteLLM

Section titled “راه‌اندازیِ پایه‌ی LiteLLM”

پیکربندیِ Claude Code:

روش‌های احراز هویت

Section titled “روش‌های احراز هویت”
کلیدِ API ثابت
Section titled “کلیدِ API ثابت”

ساده‌ترین روش، با استفاده از یک کلیدِ APIِ ثابت:

Terminal window
# Set in environment
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key


# Or in Claude Code settings
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
  }
}

این مقدار به‌عنوانِ هدرِ Authorization فرستاده می‌شود.

کلیدِ APIِ پویا با helper
Section titled “کلیدِ APIِ پویا با helper”

برای کلیدهای چرخشی یا احراز هویتِ به‌ازای هر کاربر:

  1. یک اسکریپتِ helperِ کلیدِ API بساز:
~/bin/get-litellm-key.sh
#!/bin/bash
# Example: Fetch key from vault
vault kv get -field=api_key secret/litellm/claude-code


# Example: Generate JWT token
jwt encode \
  --secret="${JWT_SECRET}" \
  --exp="+1h" \
  '{"user":"'${USER}'","team":"engineering"}'
  1. تنظیماتِ Claude Code را برای استفاده از helper پیکربندی کن:
{
  "apiKeyHelper": "~/bin/get-litellm-key.sh"
}
  1. بازه‌ی تازه‌سازیِ توکن را تنظیم کن:
Terminal window
# Refresh every hour (3600000 ms)
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000

این مقدار به‌عنوانِ هدرهای Authorization و X-Api-Key فرستاده می‌شود. اولویتِ apiKeyHelper پایین‌تر از ANTHROPIC_AUTH_TOKEN یا ANTHROPIC_API_KEY است.

endpointِ یکپارچه (توصیه‌شده)

Section titled “endpointِ یکپارچه (توصیه‌شده)”

با استفاده از endpointِ فرمتِ Anthropicِ LiteLLM:

Terminal window
export ANTHROPIC_BASE_URL=https://litellm-server:4000

مزایای endpointِ یکپارچه نسبت به endpointهای pass-through:

  • توزیعِ بار (Load balancing)
  • fallbackها
  • پشتیبانیِ یکدست از ردیابیِ هزینه و ردیابیِ کاربرِ نهایی

endpointهای pass-throughِ مخصوصِ ارائه‌دهنده (جایگزین)

Section titled “endpointهای pass-throughِ مخصوصِ ارائه‌دهنده (جایگزین)”
Claude API از طریقِ LiteLLM
Section titled “Claude API از طریقِ LiteLLM”

با استفاده از endpointِ pass-through:

Terminal window
export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic
Amazon Bedrock از طریقِ LiteLLM
Section titled “Amazon Bedrock از طریقِ LiteLLM”

با استفاده از endpointِ pass-through:

Terminal window
export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1
Google Vertex AI از طریقِ LiteLLM
Section titled “Google Vertex AI از طریقِ LiteLLM”

با استفاده از endpointِ pass-through:

Terminal window
export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
Claude Platform on AWS از طریقِ یک دروازه
Section titled “Claude Platform on AWS از طریقِ یک دروازه”

به دروازه‌ای مسیریابی کن که به endpointِ Claude Platform on AWS فوروارد می‌کند:

Terminal window
export ANTHROPIC_AWS_BASE_URL=https://litellm-server:4000/anthropic-aws
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

برای اطلاعاتِ مفصل‌تر، به مستنداتِ LiteLLM رجوع کن.

منابعِ بیشتر

Section titled “منابعِ بیشتر”