پیکربندی امن Claude Code و بهترین روش‌های Relay API

Claude Code و یکپارچه‌سازی‌های سفارشی API بیش از prompt ارسال می‌کنند؛ متادیتای محیط، انتخاب مسیر و رفتار تلاش مجدد را منتشر می‌کنند که سامانه‌های upstream ممکن است با سلامت حساب همبسته کنند. این راهنما روی ایمنی عملیاتی تمرکز دارد؛ پیکربندی یکنواخت shell، انتخاب gateway و failover نرم وقتی سهمیه‌ها سخت‌گیرانه‌تر می‌شوند. هدف گردش‌کار مهندسی قابل‌اعتماد است، نه دور زدن سیاست Anthropic.

ابتدا خط پایهٔ تمیز داشته باشید؛ قبل از تنظیم متغیرهای CLI، پاک‌سازی محیط و راه‌اندازی IP و انتخاب VPN و proxy را انجام دهید. اگر relay یا روتر چندمدلی اداره می‌کنید، برای مسیرهای تخریب‌پذیری جایگزین‌های بومی و متن‌باز را هم بخوانید.

1. پیکربندی‌های امنیتی Claude Code

Claude Code هنگام راه‌اندازی متغیرهای محیط shell را می‌خواند. تنظیم ناهم‌تراز منطقهٔ زمانی، proxy یا base URL می‌تواند خطاهای گیج‌کننده بدهد، یا باعث شود رفتار کلاینت با نشست مرورگر شما فرق کند. ترمینال را محیطی درجهٔ یک بدانید، نه فکر آخر.

متغیرهای محیط اصلی

# ~/.zshrc or ~/.bashrc — load in every interactive shell

# 1. Declare custom Anthropic-compatible endpoints explicitly
export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_API_KEY="sk-your-key"

# 2. When using a trusted first-party-shaped gateway, reduce client mismatch warnings
export _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1

# 3. Align terminal timezone with your documented operating region
export TZ=Asia/Tokyo   # or America/Los_Angeles — match proxy geo

# 4. Route CLI HTTPS through the same clean proxy as your browser (if required)
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,.internal"

چک‌لیست پیکربندی

1. منبع واحد حقیقت: متغیرهای محیط را در ~/.zshrc (macOS) یا فایل اختصاصی ~/.claude/env که shell آن را source می‌کند نگه دارید؛ از export موردی در یک تب ترمینال پرهیز کنید.
2. قبل از راه‌اندازی بررسی کنید: در همان پنجره‌ای که Claude Code را شروع می‌کنید، env | grep -E 'ANTHROPIC|TZ|PROXY' را اجرا کنید.
3. هم‌راستایی جغرافیای مرورگر و CLI: اگر پروفایل مرورگر با ابزار ضدشناسایی منطقهٔ زمانی توکیو دارد، CLI نباید Asia/Shanghai گزارش کند.
4. تغییرهای base URL را مستند کنید: هنگام جابه‌جایی از Anthropic مستقیم به relay، هر دو ANTHROPIC_BASE_URL و runbook داخلی را به‌روز کنید تا هم‌تیمی‌ها endpoint را قاطی نکنند.
5. بهداشت اسرار: هرگز کلید API را commit نکنید؛ روی فایل‌های env chmod 600 بگذارید و کلیدهای relay را فصلی rotate کنید.

_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL چه می‌کند و چه نمی‌کند

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

خرابی‌های رایج پیکربندی اشتباه

• proxy دوپاره: مرورگر VPN می‌گیرد؛ CLI نه؛ درخواست‌ها از ASNهای مختلف می‌آیند. علامت؛ چت وب کار می‌کند، CLI برمی‌گرداند 403.
• NO_PROXY کهنه: gateway محلی روی 127.0.0.1 باید proxy شرکتی را دور بزند وگرنه حلقه با connection reset شکست می‌خورد.
• دامنهٔ اشتباه کلید API: کلید سازمان در برابر کلید پروژه تحت محدودیت نرخ رفتار متفاوت دارند؛ نوع کلید را در کنسول Anthropic تأیید کنید.
• shell تعاملی در برابر غیرتعاملی: jobهای CI که Claude Code را صدا می‌زنند باید همان فایل env را source کنند؛ shellهای login روی لپ‌تاپ اغلب exportهای گم‌شده را پنهان می‌کنند.

2. انتخاب gatewayهای relay API

وقتی دسترسی مستقیم به api.anthropic.com به‌خاطر مسیریابی یا تدارکات محدود است، relayها می‌توانند دسترس‌پذیری را بالا ببرند، اگر وفاداری پروتکل حفظ شود. gateway ضعیف بی‌صدا header می‌زداید، prompt بازنویسی می‌کند یا جهش تأخیر اضافه می‌کند که شبیه افت کیفیت مدل به نظر می‌رسد.

ماتریس ارزیابی gateway

حفظ Prompt Cache (اثر هزینه)

کش prompt Anthropic می‌تواند هزینهٔ ورودی تکراری را تا ۹۰٪ کم کند. relayهایی که headerهای cache را حذف می‌کنند هر نوبت توکن ورودی با قیمت کامل می‌گیرند، اغلب شوک ۴× تا ۱۰× روی system promptهای بلند. با آزمایش دو درخواست تأیید کنید:

# Request 1: create cache
curl -s "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: prompt-caching-2024-07-15" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":64,
       "system":[{"type":"text","text":"'$(python3 -c "print('x'*5000)")'",
         "cache_control":{"type":"ephemeral"}}],
       "messages":[{"role":"user","content":"ping"}]}'

# Request 2: expect cache_read_input_tokens > 0 in usage

الگوهای بهینه‌سازی عمیق در بهینه‌سازی پیشرفتهٔ API است.

بررسی عملیاتی قبل از production

• ۲۴ ساعت probe مصنوعی (هر ۱۵ دقیقه یک پیام) با اندازه‌گیری p95 تأخیر و نرخ خطا.
• نمونه‌ای از request ID را لاگ کنید؛ تأیید کنید اپ می‌تواند لاگ gateway را با IDهای upstream برای incident همبسته کند.
• توافق‌نامهٔ پردازش داده را مرور کنید؛ برخی relayها برای تشخیص سوءاستفاده prompt لاگ می‌کنند، برای workloadهای تحت مقررات غیرقابل‌قبول است.
• ترجیح gatewayهایی که سازمان شما کنترل می‌کند (LiteLLM self-hosted، One-API روی VPC) بر resellerهای عمومی مبهم هنگام کار با کد منبع.

پایداری سطح حساب همچنان به بهداشت ثبت‌نام وابسته است؛ اگر پذیرش relay با ایجاد سازمان جدید هم‌زمان است ثبت‌نام حساب و پرداخت ضد مسدودسازی را ببینید.

3. محدودیت نرخ (429) و failover نرم

محدودیت‌های نرخ Anthropic در سطح سازمان و لایهٔ مدل اعمال می‌شوند، نه به‌تنهایی per API key. agentهای پرشتاب، jobهای CI موازی و حلقهٔ retry بی‌مرز می‌توانند سهمیهٔ مشترک را تمام کنند و سرویس‌های نامرتبط همان org را مسدود کنند.

رده‌های محدودیت (ساده‌شده)

الگوی retry و failover

// TypeScript — retry 429/529, failover on sustained pressure
async function callClaudeWithFallback(prompt: string, opts: CallOpts) {
  const maxRetries = 4;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await callClaudeAPI(prompt, opts);
    } catch (error: any) {
      const status = error?.status;
      if (status === 429 || status === 529) {
        const delay = Math.min(30_000, 500 * 2 ** attempt + Math.random() * 250);
        await sleep(delay);
        continue;
      }
      if (status === 403) throw error; // surface auth issues
      throw error;
    }
  }
  console.warn('Claude quota saturated; failing over to backup upstream');
  return await callFallbackAPI(prompt, opts); // DeepSeek / GLM / local — see alternatives guide
}

کنترل هم‌زمانی

• سطل توکن در CI: jobهای agent موازی را سقف بگذارید (مثلاً حداکثر ۳ هم‌زمان) per organization.
• ادغام درخواست: در صورت امکان اصلاح lint کوچک چندفایلی را یک فراخوانی API کنید نه یکی per فایل.
• Circuit breaker: پس از N بار متوالی ۴۲۹، ۶۰ ثانیه مدار باز و failover خودکار به مسیر پشتیبان، جلوی طوفان retry را می‌گیرد.
• قابلیت مشاهده: متریک export کنید: claude_requests_total{status}، fallback_invocations_total، p95 تأخیر. وقتی نرخ fallback بیش از ۱۵٪ برای ۱۰ دقیقه بود هشدار دهید.

403 در برابر 429؛ یکسان قلمداد نکنید

۴۲۹ فشار موقت است، عقب بروید و ادامه دهید. ۴۰۳ اغلب لغو credential، محدودیت جغرافیایی یا تغییر وضعیت حساب را نشان می‌دهد. retry کردن ۴۰۳ با کلیدهای جایگزین بدون تشخیص می‌تواند اجرای سیاست را تسریع کند. قبل از چرخش زیرساخت از راهنمای عیب‌یابی برای طبقه‌بندی خطا استفاده کنید.

سؤالات متداول

اگر منطقهٔ زمانی سیستم درست است، آیا TZ را تنظیم کنم؟

اگر منطقهٔ زمانی OS، geo خروج proxy و پروفایل مرورگر هم‌راستا هستند، TZ صریح شاید اضافی باشد، اما کانتینرهای CI اغلب پیش‌فرض UTC دارند. export صریح رفتار را بین لپ‌تاپ و سرور قطعی می‌کند.

آیا reseller عمومی API برای کد منبع شرکت «ایمن» است؟

مثل هر پردازندهٔ فرعی سوم‌شخص با آن رفتار کنید؛ لاگ، نگهداری و فهرست subprocessors را مرور کنید. برای کد اختصاصی، relay self-hosted روی VPC شما از resellerهای ناشناس قطعاً ایمن‌تر است.

چرا پس از عوض کردن gateway صرفه‌جویی cache ناپدید می‌شود؟

رایج‌ترین علت این است که relay headerهای anthropic-beta را می‌زداید یا بلوک‌های system را جابه‌جا می‌کند و کلید cache باطل می‌شود. پس از هر تغییر gateway آزمایش کش دو درخواستی را دوباره اجرا کنید.

آیا می‌توانم برای مرورگر و Claude Code proxy متفاوت استفاده کنم؟

از نظر فنی بله، اما ریسک واگرایی بیشتر می‌شود. یک مسیر egress مستند برای همهٔ ترافیک Claude ترجیح دهید مگر حساب‌های آزمایشی را در پروفایل‌های جدا نگه دارید.

Claude Code روی 429 باید به کدام مدل fallback کند؟

خود Claude Code failover چندمدلی داخلی ندارد؛ در gateway (One-API/LiteLLM) پیاده‌سازی کنید یا موقتاً Claude Code را خاموش کنید و افزونهٔ IDE را به API پشتیبان اشاره دهید. جداول مسیریابی در جایگزین‌های بومی و متن‌باز.

چطور «در curl کار می‌کند ولی در Claude Code نه» را debug کنم؟

1. headerها را diff کنید؛ curl در برابر CLI را با mitmproxy یا لاگ دسترسی gateway بگیرید.
2. env در shell راه‌انداز را تأیید کنید؛ ترمینال‌های یکپارچهٔ IDE گاهی rc فایل‌های login را رد می‌کنند.
3. agentهای proxy Node/fetch را بررسی کنید؛ بعضی نسخه‌ها HTTPS_PROXY را نادیده می‌گیرند مگر GLOBAL_AGENT_HTTP_PROXY تنظیم شود.
4. بازرسی TLS روی شبکهٔ شرکتی را بررسی کنید.

فرض base URL شبیه first-party روی صورتحساب Anthropic اثر می‌گذارد؟

نه. صورتحساب از کلید API و سازمانی که واقعاً درخواست را سرو می‌کند پیروی می‌کند. اگر gateway به Anthropic فوروارد کند، Anthropic را پرداخت می‌کنید؛ اگر مدل عوض کند، هر providerی که gateway صدا می‌زند را.