التكوين الآمن لـ Claude Code وأفضل ممارسات Relay API

يرسل Claude Code وتكاملات API المخصصة أكثر من الـ prompts؛ فهي تصدر بيانات وصفية للبيئة وخيارات التوجيه وسلوك إعادة المحاولة التي قد تربطها الأنظمة upstream بصحة الحساب. تركز هذه الدليل على الأمان التشغيلي: تهيئة shell متسقة، واختيار البوابة، والتحويل الاحتياطي السلس عندما تشتد الحصص. الهدف سير عمل هندسي موثوق، وليس التحايل على سياسة Anthropic.

ابدأ بخط أساس نظيف: تنظيف البيئة وإعداد IP واختيار VPN والـ proxy قبل ضبط متغيرات CLI. إذا شغّلت relays أو موجهات متعددة النماذج، اقرأ أيضاً البدائل المحلية ومفتوحة المصدر لمسارات التدهور.

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 — وتجنّب التصدير المؤقت في تبويب طرفية واحد.
2. تحقق قبل التشغيل: نفّذ env | grep -E 'ANTHROPIC|TZ|PROXY' في نفس النافذة التي تبدأ منها Claude Code.
3. واءِم جغرافيا المتصفح وCLI: إذا كان ملف تعريف المتصفح يستخدم منطقة زمنية طوكيو عبر أدوات anti-detect، فلا ينبغي أن يبلغ CLI عن Asia/Shanghai.
4. وثّق تغييرات base URL: عند الانتقال من Anthropic مباشرة إلى relay، حدّث ANTHROPIC_BASE_URL وrunbooks الداخلية حتى لا يخلط الزملاء بين نقاط النهاية.
5. نظافة الأسرار: لا ترفع مفاتيح API إلى المستودع؛ استخدم chmod 600 على ملفات env ودوّر مفاتيح relay كل ربع سنة.

ماذا يفعل _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL وماذا لا يفعل

يخبر هذا العلم Claude Code بمعاملة ANTHROPIC_BASE_URL غير الافتراضي كما لو كان endpoint Anthropic القياسي لبعض فحوصات جانب العميل. يقلل الاحتكاك عندما تشغّل مؤسستك بوابة داخلية معتمدة. إنه لا يغيّر السياسة من جانب الخادم ولا الفوترة ولا الأهلية. لكيفية تقييم بيانات وصفية للعميل قد تبقى مُقيَّمة، راجع الإخفاء في Claude ونموذج المخاطر.

أعطال شائعة بسبب سوء التهيئة

• انقسام الـ proxy: المتصفح يستخدم VPN والـ CLI لا — الطلبات من ASN مختلفة. العرض: الدردشة على الويب تعمل والـ CLI يرجع 403.
• NO_PROXY قديم: البوابة المحلية على 127.0.0.1 يجب أن تتجاوز proxy الشركة وإلا فشل الحلقة مع connection reset.
• نطاق مفتاح API خاطئ: مفاتيح المؤسسة مقابل مفاتيح المشروع تتصرف بشكل مختلف تحت حدود المعدل؛ أكد نوع المفتاح في console Anthropic.
• shell تفاعلي مقابل غير تفاعلي: وظائف CI التي تستدعي Claude Code يجب أن تحمّل نفس ملف env؛ login shells على الحواسيب المحمولة غالباً تخفي exports ناقصة.

2. اختيار بوابات relay لـ API

عندما يكون الوصول المباشر إلى api.anthropic.com مقيداً بالتوجيه أو المشتريات، قد يحسّن relay التوفر — إذا حافظ على دقة البروتوكول. بوابة رديئة تزيل العناوين بصمت أو تعيد كتابة الـ prompts أو تضيف قفزات زمنية تبدو كتراجع في جودة النموذج.

مصفوفة تقييم البوابة

الحفاظ على Prompt Cache (أثر التكلفة)

قد يخفّض Prompt Cache لدى Anthropic تكلفة الإدخال المتكرر حتى 90%. البوابات التي تحذف عناوين cache تفرض تسعير input كامل في كل دورة — غالباً مفاجأة 4×–10× على system prompts طويلة. تحقق باختبار طلبين:

# 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 المتقدم.

العناية الواجبة التشغيلية قبل الإنتاج

• شغّل مسبارات تركيبية 24 ساعة (رسالة كل 15 دقيقة) لقياس p95 للزمن والخطأ.
• سجّل عينة من request IDs؛ تأكد أن تطبيقك يربط سجلات البوابة بمعرّفات upstream للحوادث.
• راجع اتفاقية معالجة البيانات: بعض الـ relays يسجّل prompts لكشف إساءة الاستخدام — غير مقبول لأحمال خاضعة للتنظيم.
• فضّل بوابات تتحكم بها مؤسستك (LiteLLM مستضاف ذاتياً، One-API على VPC) على موزعين عامين غامضين عند التعامل مع كود المصدر.

استقرار الحساب ما زال يعتمد على نظافة التسجيل — راجع التسجيل والدفع ومكافحة الحظر إذا صادف اعتماد relay إنشاء مؤسسة جديدة.

3. حدود المعدل (429) والتحويل الاحتياطي السلس

تطبّق حدود معدل Anthropic على مستوى المؤسسة ودرجة النموذج، وليس لكل مفتاح API بمعزل. وكلاء الطفرات ووظائف CI المتوازية وحلقات إعادة المحاولة غير المحدودة قد تستنفد الحصة المشتركة وتعطل خدمات أخرى في نفس المؤسسة.

أصناف الحد (مبسّطة)

نمط إعادة المحاولة والتحويل الاحتياطي

// 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
}

ضوابط التزامن

• دلو tokens في CI: احدُد وظائف الوكيل المتوازية (مثل 3 كحد أقصى) لكل مؤسسة.
• دمج الطلبات: اجمع إصلاحات lint الصغيرة في استدعاء API واحد عند الإمكان.
• قاطع دائرة: بعد N من 429 متتالية، افتح الدائرة 60 ثانية ووجّه تلقائياً للاحتياطي — يمنع عواصف إعادة المحاولة.
• القابلية للمراقبة: صدّر مقاييس: claude_requests_total{status}، fallback_invocations_total، p95 للزمن. نبّه عندما يتجاوز معدل الاحتياطي 15% لمدة 10 دقائق.

403 مقابل 429: لا تعاملهما بنفس الطريقة

429 ضغط مؤقت — تراجع ثم استأنف. 403 غالباً يعني إبطال اعتماد أو قيد جغرافي أو تغيّر حالة حساب. إعادة محاولة 403 بمفاتيح بديلة دون تشخيص قد تسرّع الإنفاذ. استخدم دليل استكشاف الأخطاء لتصنيف الأخطاء قبل تدوير البنية التحتية.

الأسئلة الشائعة

هل أضبط TZ إذا كانت منطقة النظام الزمنية صحيحة أصلاً؟

إذا كانت المنطقة الزمنية للنظام وجغرافيا خروج الـ proxy وملف تعريف المتصفح متوافقة، قد يكون تصدير TZ صريحاً زائداً — لكن حاويات CI غالباً افتراضياً UTC. التصدير الصريح يجعل السلوك حتمياً بين الحواسيب المحمولة والخوادم.

هل موزع API عام «آمن» لكود مصدر الشركة؟

عامله كأي معالج فرعي ثالث: راجع التسجيل والاحتفاظ وقائمة المعالجين الفرعيين. للكود الخاص، relay مستضاف ذاتياً على VPC الخاص بك أكثر أماناً بكثير من موزعين مجهولين.

لماذا تختفي وفورات cache بعد تبديل البوابات؟

الأشيع أن الـ relay يزيل عناوين anthropic-beta أو يعيد ترتيب كتل system، فيبطل مفاتيح cache. أعد اختبار cache بطلبين بعد أي تغيير بوابة.

هل يمكنني استخدام proxies مختلفة للمتصفح وClaude Code؟

تقنياً نعم، لكنك تزيد مخاطر التباعد. فضّل مسار خروج موثّقاً واحداً لكل حركة Claude ما لم تعزل حسابات تجريبية في ملفات تعريف منفصلة.

ما النموذج الاحتياطي الذي يجب أن يستخدمه Claude Code عند 429؟

Claude Code نفسه بلا failover متعدد النماذج مدمج — نفّذه عند البوابة (One-API/LiteLLM) أو عطّل Claude Code مؤقتاً واستخدم إضافات IDE موجهة لـ APIs احتياطية. راجع البدائل المحلية ومفتوحة المصدر لجداول التوجيه.

كيف أستكشف «يعمل في curl ويفشل في Claude Code»؟

1. قارن العناوين: التقط curl مقابل CLI بـ mitmproxy أو سجلات وصول البوابة.
2. أكد env في shell التشغيل: طرفيات IDE المدمجة أحياناً تتخطى ملفات rc لتسجيل الدخول.
3. تحقق من وكلاء proxy لـ Node/fetch — بعض الإصدارات تتجاهل HTTPS_PROXY ما لم يُضبط GLOBAL_AGENT_HTTP_PROXY.
4. تحقق من اعتراض TLS على شبكات الشركة.

هل افتراض first-party base URL يؤثر على فوترة Anthropic؟

لا. الفوترة تتبع مفتاح API والمؤسسة المرتبطين بـ upstream الذي يخدم الطلب فعلياً. إذا كانت بوابتك تمرّر إلى Anthropic تدفع لـ Anthropic؛ إذا بدّلت النماذج تدفع لمزود البوابة الذي تستدعيه.