الدليل الكامل لمتغيرات بيئة Claude Code: حل خطأ توافق AWS Bedrock بإعداد واحد فقط

ملاحظة المؤلف: شرح مفصل لجميع متغيرات البيئة الـ 60+ في Claude Code وطرق تكوينها، مع التركيز على استخدام CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS لحل مشكلة خطأ ترويسة (header) anthropic-beta في المنصات الخارجية.

عند استخدام Claude Code للاتصال بـ AWS Bedrock أو Google Vertex AI أو أي بوابة نماذج لغة كبيرة (LLM) خارجية أخرى، فمن المرجح جداً أن تواجه هذا الخطأ: "Unexpected value(s) for the anthropic-beta header". يعود أصل هذه المشكلة إلى أن Claude Code يرسل افتراضياً ترويسات تجريبية (Beta) خاصة بـ Anthropic API، وهي ترويسات لا تتعرف عليها المنصات الخارجية مثل AWS Bedrock.

الحل يتطلب سطراً واحداً فقط من الإعدادات: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

لكن متغيرات البيئة في Claude Code تتجاوز هذا المتغير بكثير – حيث تسرد الوثائق الرسمية أكثر من 60 متغيراً للبيئة، تغطي تكوينات المصادقة، واختيار النموذج، وضبط الأداء، ومفاتيح الميزات، وغيرها من الجوانب. سأقوم في هذا المقال بتنظيم هذه المتغيرات بشكل منهجي لمساعدتك في تحديد وحل مختلف مشكلات التكوين في Claude Code بسرعة.

القيمة الجوهرية: بعد قراءة هذا المقال، ستتقن النظام الكامل لمتغيرات البيئة في Claude Code، وستتمكن من حل مشكلات التوافق مع AWS Bedrock/Vertex AI بسرعة، وتعلم كيفية تحسين تجربة استخدام وتكلفة Claude Code من خلال متغيرات البيئة.

النقاط الأساسية لمتغيرات بيئة Claude Code

يمكن تقسيم أكثر من 60 متغير بيئة لـ Claude Code إلى 6 فئات رئيسية. إليك المتغيرات الأساسية التي تحتاج إلى الاهتمام بها:

طريقتان لتعيين متغيرات بيئة Claude Code

الطريقة الأولى: متغيرات بيئة Shell (تأثير مؤقت)

يتم تعيينها في الطرفية (Terminal) قبل تشغيل Claude Code، وتكون صالحة للجلسة الحالية فقط:

# تعطيل الترويسات التجريبية
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
# تعيين مفتاح API الخاص بك
export ANTHROPIC_API_KEY="your-api-key"
claude

الطريقة الثانية: تكوين settings.json (تأثير دائم)

قم بتكوين حقل env في ملف ~/.claude/settings.json ليتم تحميله تلقائيًا في كل مرة يتم فيها التشغيل:

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "ANTHROPIC_API_KEY": "your-api-key"
  }
}

🎯 الطريقة الموصى بها: بالنسبة للإعدادات التي تحتاج إلى مفعول طويل الأمد (مثل مفتاح API أو إصلاحات التوافق مع المنصات)، نقترح استخدام طريقة settings.json لتجنب القيام بعملية التصدير (export) يدويًا في كل مرة. إذا كان مفتاح API الخاص بك من منصة خارجية مثل APIYI (apiyi.com)، يمكنك تكوينه هنا أيضًا.

شرح أهم متغيرات البيئة في Claude Code: حل مشكلات التوافق مع AWS Bedrock

تفاصيل CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS

هذا هو العنصر الأساسي في هذا المقال. عند استخدام Claude Code عبر AWS Bedrock أو Google Vertex AI أو LiteLLM أو غيرها من البوابات الخارجية، يقوم Claude Code تلقائيًا بإضافة معرفات Anthropic التجريبية (Beta) في ترويسة الطلب (Request Headers)، مثل:

anthropic-beta: prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20

هذه المعرفات هي ميزات خاصة بالاتصال المباشر بـ API الخاص بشركة Anthropic، ولا تستطيع المنصات الخارجية مثل AWS Bedrock التعرف عليها، مما يؤدي إلى ظهور خطأ:

Error: Unexpected value(s) for the anthropic-beta header

طريقة الحل:

# الطريقة الأولى: عبر أمر Shell
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# الطريقة الثانية: في ملف settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

عند ضبط القيمة على 1 كقيمة منطقية، سيتوقف Claude Code عن إرسال ترويسات Beta التجريبية هذه، مما يجعله متوافقًا مع جميع المنصات الخارجية.

المشكلات المعروفة والحلول المؤقتة

وفقًا لسجلات GitHub Issues، تعاني بعض إصدارات Claude Code (بعد الإصدار 2.1.18) من مشكلة عدم تفعيل هذا المتغير بشكل كامل؛ حيث تظل بعض ترويسات Beta الجديدة (مثل advanced-tool-use-2025-11-20) تُرسل حتى مع ضبط CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

إذا كنت لا تزال تواجه مشكلات، يمكنك تجربة الإجراءات الإضافية التالية:

• تخفيض إصدار Claude Code: العودة إلى إصدار مستقر معروف مثل 2.1.68.
• استخدام بوابة LiteLLM: توفر LiteLLM ملف تكوين anthropic_beta_headers_config.json يتيح لك التحكم الدقيق في ترويسات Beta التي يتم تمريرها.
• ضبط DISABLE_PROMPT_CACHING في نفس الوقت: يؤدي تعطيل تخزين الموجهات (Prompt Caching) إلى تجنب الترويسات المتعلقة بـ prompt-caching-scope.

# إعدادات التوافق الشاملة
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

دليل تصنيف متغيرات البيئة في Claude Code

الفئة الأولى: المصادقة وإعدادات API

هذه هي الفئة الأساسية والأكثر استخدامًا، وهي تتحكم في كيفية اتصال Claude Code بخدمة API:

🎯 تنبيه لمستخدمي المنصات الخارجية: عند استخدام منصات API خارجية مثل APIYI apiyi.com، يجب ضبط كل من ANTHROPIC_API_KEY و ANTHROPIC_BASE_URL. سيعطي Claude Code الأولوية لمفتاح API الموجود في متغيرات البيئة، حتى لو كنت قد سجلت الدخول بحساب اشتراك Anthropic.

الفئة الثانية: اختيار النموذج وإعداده

تتحكم في النموذج الذي يستخدمه Claude Code ومعايير سلوكه:

الفئة الثالثة: التوافق مع المنصات وإعدادات البوابات

هذه المتغيرات مخصصة لحل مشكلات التوافق بين Claude Code ومختلف المنصات السحابية وبوابات نماذج اللغة الكبيرة:

الفئة الرابعة: مفاتيح الميزات

تعطيل ميزات معينة باستخدام المتغيرات التي تبدأ بـ DISABLE_ أو CLAUDE_CODE_DISABLE_:

الفئة الخامسة: إدارة السياق والأداء

تتحكم في كيفية إدارة Claude Code لنافذة السياق واستخدام الموارد:

🎯 نصيحة لتحسين الأداء: إذا وجدت أن Claude Code يقوم بضغط السياق بشكل متكرر في المحادثات الطويلة، يمكنك ضبط CLAUDE_AUTOCOMPACT_PCT_OVERRIDE على قيمة أقل (مثل 50) لتفعيل الضغط مبكرًا وتقليل فقدان المعلومات. هذه الإعدادات مدعومة أيضًا عند الاستدعاء عبر APIYI apiyi.com.

دليل سريع لمتغيرات بيئة Claude Code

مثال مبسط: تهيئة Claude Code للاتصال بمنصة API خارجية

# قم بتشغيل Claude Code بعد ضبط متغيرات البيئة في الطرفية (Terminal)
export ANTHROPIC_API_KEY="sk-your-api-key"
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-api-key",
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com/v1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80",
    "DISABLE_TELEMETRY": "1"
  },
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": []
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1",
    "ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION": "us-east-1"
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_BASE_URL": "https://my-resource.services.ai.azure.com/anthropic",
    "ANTHROPIC_FOUNDRY_API_KEY": "your-foundry-key",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

نصيحة: إذا كنت لا ترغب في التعامل مع التعقيدات البرمجية لـ AWS Bedrock أو Azure، يمكنك استخدام مجموعة نماذج Claude الكاملة مباشرة عبر APIYI (apiyi.com). كل ما عليك فعله هو ضبط متغيرين فقط: مفتاح API ورابط Base URL، دون الحاجة للتعامل مع مشكلات المصادقة والتوافق الخاصة بالمنصات السحابية.

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

ملخص

النقاط الأساسية لمتغيرات البيئة في Claude Code:

1. حل أخطاء AWS Bedrock: قم بضبط CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 لتعطيل ترويسات Beta التجريبية، وهو إعداد من سطر واحد يحل خطأ "Unexpected value(s) for the anthropic-beta header".
2. أكثر من 60 متغير بيئة مقسمة إلى 6 فئات رئيسية: إعدادات المصادقة، اختيار النموذج، توافق المنصات، مفاتيح الميزات، إدارة السياق، وإعدادات أخرى.
3. طريقتان للتكوين: عبر Shell export (مؤقت) أو ملف settings.json (دائم)، ويُنصح بكتابة الإعدادات الدائمة في ملف settings.json.
4. حلول مبسطة عبر منصات الطرف الثالث: من خلال منصات API الموحدة مثل APIYI (apiyi.com)، تحتاج فقط لضبط متغيرين: ANTHROPIC_API_KEY و ANTHROPIC_BASE_URL دون الحاجة للتعامل مع تعقيدات مصادقة المنصات السحابية أو مشاكل توافق ترويسات Beta.

نوصي باستخدام APIYI (apiyi.com) لتجربة سريعة لربط Claude Code، حيث توفر المنصة رصيداً مجانياً وواجهة موحدة، مما يجنبك مشاكل التوافق المعقدة في إعدادات AWS Bedrock أو Vertex AI.

📚 المراجع

1. وثائق Claude Code الرسمية – متغيرات البيئة: قائمة كاملة بمتغيرات البيئة مع الشرح.

   • الرابط: code.claude.com/docs/en/env-vars
   • الوصف: المرجع الرسمي المعتمد لجميع متغيرات البيئة الـ 60+.

2. وثائق Claude Code الرسمية – الإعدادات: نطاق الإعدادات ومعايير ملف settings.json.

   • الرابط: code.claude.com/docs/en/settings
   • الوصف: فهم نظام التكوين رباعي المستويات (Managed/User/Project/Local).

3. وثائق Claude Code الرسمية – Amazon Bedrock: دليل التكامل مع AWS Bedrock.

   • الرابط: code.claude.com/docs/en/amazon-bedrock
   • الوصف: الإعدادات الخاصة بـ Bedrock وحلول المشكلات الشائعة.

4. GitHub Issue #22893 – عدم فعالية DISABLE_EXPERIMENTAL_BETAS بشكل كامل: تقرير عن خطأ من المجتمع.

   • الرابط: github.com/anthropics/claude-code/issues/22893
   • الوصف: التعرف على القيود المعروفة لهذا المتغير والحلول المؤقتة.

5. LiteLLM – إدارة ترويسات Claude Code Beta: حلول تصفية ترويسات Beta على مستوى البوابة (Gateway).

   • الرابط: docs.litellm.ai/docs/tutorials/claude_code_beta_headers
   • الوصف: التحكم الدقيق في ترويسات Beta عند استخدام بوابة LiteLLM.

المؤلف: فريق APIYI التقني
التواصل التقني: نرحب بمناقشة تجاربكم في إعداد Claude Code في قسم التعليقات. لمزيد من الشروحات التعليمية، يمكنكم زيارة مركز الوثائق في APIYI عبر docs.apiyi.com