3 حلول لإصلاح خطأ نطاق cache_control في Claude Code Bedrock: دليل استكشاف الأخطاء وإصلاحها الكامل لفشل استئناف الجلسة عبر –resume

إذا واجهت هذا الخطأ أثناء استخدام Claude Code للاتصال بـ AWS Bedrock:

InvokeModelWithResponseStream: operation error Bedrock Runtime:
InvokeModelWithResponseStream, https response error StatusCode: 400,
RequestID: 47574f13-c884-4b12-a003-6d0cf252d8dd,
ValidationException: system.1.cache_control.***.scope:
Extra inputs are not permitted

يظهر هذا الخطأ بشكل متكرر خاصة عند استخدام الأمر --resume لاستئناف جلسة سابقة—هذه مشكلة توافق معروفة، وليست خطأً في إعداداتك.

السبب الجذري هو أن Claude Code يرسل حقل scope الذي لا يدعمه Bedrock. الحل بسيط ويستغرق 30 ثانية فقط عبر ضبط متغير بيئة واحد.

القيمة المضافة: بعد قراءة هذا المقال، ستفهم السبب الجذري لهذا الخطأ، وستتقن 3 حلول لإصلاحه، وستعرف كيفية ضبط الإعدادات بشكل صحيح في بيئات CLI، وVS Code، وJetBrains.

تحليل عميق لأسباب خطأ Claude Code مع Bedrock

لفهم هذا الخطأ، يجب أن تدرك خلفية تقنية جوهرية: وهي أن مستوى دعم cache_control يختلف بين واجهة برمجة التطبيقات (API) الأصلية لـ Anthropic وخدمة AWS Bedrock.

السبب التقني الجذري للخطأ

في يناير 2026، أطلقت Anthropic ميزة تجريبية (Beta) في واجهة API الأصلية تسمى prompt-caching-scope-2026-01-05، والتي أضافت حقل scope إلى كائن cache_control:

{
  "cache_control": {
    "type": "ephemeral",
    "scope": "turn"
  }
}

بدءاً من إصدار Claude Code v2.1.24، أصبح حقل scope هذا مُضمناً بشكل افتراضي في طلبات API.

تكمن المشكلة في أن: AWS Bedrock لا يتعرف على حقل scope، كما أن عملية التحقق من المخطط (Schema validation) في Bedrock صارمة للغاية—حيث تؤدي مواجهة أي حقل غير معروف إلى إرجاع خطأ 400 مباشرة.

ببساطة: واجهة API الأصلية لـ Anthropic أكثر تسامحاً وتتجاهل الحقول التي لا تتعرف عليها، بينما Bedrock صارمة وترفض الطلب فوراً. عندما يرسل Claude Code حقلاً لا يفهمه Bedrock، يظهر الخطأ.

🎯 نصيحة تقنية: تؤثر هذه المشكلة فقط على المستخدمين الذين يستدعون Claude عبر AWS Bedrock. إذا كنت تستخدم واجهة API الأصلية لـ Anthropic (مثل الربط عبر منصة APIYI apiyi.com)، فلن تواجه هذا الخطأ نهائياً، لأن الواجهة الأصلية تدعم حقل scope بالكامل.

لماذا يسهل تفعيل الخطأ عند استخدام --resume في Claude Code؟

على الرغم من أن هذا الخطأ ليس حصرياً لـ --resume، إلا أنه يظهر بشكل متكرر عند استعادة جلسة سابقة. الأسباب كالتالي:

آلية العمل الداخلية لـ --resume:

1. تحميل الجلسة السابقة: قراءة سجل المحادثة الكامل من ~/.claude/projects/<المشروع>/<معرف الجلسة>.jsonl.
2. إعادة بناء السياق: تجميع موجه النظام (system prompt)، وتعريفات الأدوات، وجميع الرسائل السابقة في مصفوفة messages كاملة.
3. تحسين التخزين المؤقت (Caching): نظراً لأن السياق المستعاد عادة ما يكون كبيراً (يحتوي على سجل المحادثة بالكامل)، يقوم Claude Code بوضع نقاط توقف cache_control بشكل أكثر نشاطاً على رسائل النظام لتحسين التكلفة.
4. إرسال الطلب: يتضمن أول استدعاء لـ API السياق المعاد بناؤه بالكامل + cache_control (مع حقل scope).

النقطة الجوهرية: عند استعادة الجلسة، يكون السياق أكبر → تحسين التخزين المؤقت أكثر كثافة → تكرار ظهور حقل cache_control أعلى → احتمالية حدوث الخطأ أكبر.

قد يحدث الخطأ أيضاً عند بدء جلسة جديدة، ولكن نظراً لأن السياق الأولي أصغر، فقد لا تكون علامات التخزين المؤقت مكثفة بنفس القدر.

حل مشكلة خطأ Claude Code Bedrock – الخيار الأول: تعطيل الميزات التجريبية (موصى به)

هذا هو الحل الأكثر توصية، فهو يصحح الخطأ مع الحفاظ على ميزة "التخزين المؤقت للموجه" (Prompt Caching) الأساسية.

مبدأ عمل الحل

عند ضبط CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1، سيقوم Claude Code بما يلي:

• إزالة ترويسات النسخة التجريبية (Beta headers) من الطلبات (مثل prompt-caching-scope-2026-01-05).
• إزالة حقل scope من cache_control.
• الاحتفاظ بالحقول التي يدعمها Bedrock مثل cache_control.type و cache_control.ttl.

بمعنى آخر، ستظل تستفيد من تحسين التكلفة الذي توفره ميزة التخزين المؤقت للموجه، دون استخدام خاصية scope الجديدة.

إعدادات واجهة سطر الأوامر (CLI)

macOS / Linux:

# إعداد مؤقت (فعال لجلسة الطرفية الحالية فقط)
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# إعداد دائم (يُضاف إلى ملف إعدادات shell)
echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.zshrc
source ~/.zshrc

# إذا كنت تستخدم bash
echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell):

# إعداد مؤقت
$env:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1"

# إعداد دائم
[System.Environment]::SetEnvironmentVariable("CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS", "1", "User")

بعد الضبط، قم بتشغيل Claude Code مباشرة:

# بدء جلسة جديدة
claude

# استئناف الجلسة (لن يظهر الخطأ الآن)
claude --resume

إعدادات إضافة VS Code (هام!)

إضافة VS Code لا تقرأ متغيرات بيئة shell، لذا حتى لو قمت بضبطها في .zshrc فلن تتمكن الإضافة من قراءتها. يجب ضبطها بالطريقة التالية:

الطريقة الأولى: تعديل ملف إعدادات Claude العام (موصى به)

قم بتحرير الملف ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

الطريقة الثانية: عبر إعدادات VS Code

افتح إعدادات VS Code ← ابحث عن claude ← ابحث عن خيار إعداد متغيرات البيئة ← أضف CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

إعدادات JetBrains IDE

تحتاج إضافات Claude Code في بيئات JetBrains (مثل IntelliJ، WebStorm، PyCharm، إلخ) إلى تكوين منفصل أيضاً:

قم بتحرير الملف ~/.claude/settings.json (وهو الملف نفسه المستخدم في VS Code):

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

💡 نصيحة: الملف ~/.claude/settings.json هو ملف الإعدادات العام لـ Claude Code، وتقوم جميع المنصات (CLI، VS Code، JetBrains) بقراءته. ضبط متغيرات البيئة هنا هو الطريقة الأسهل لتطبيق الإعدادات على جميع المنصات دفعة واحدة.

حل مشكلة خطأ Claude Code Bedrock – الخيار الثاني: تعطيل التخزين المؤقت للموجه (Prompt Caching)

إذا لم ينجح الخيار الأول في حل مشكلتك (وهو أمر نادر)، يمكنك تعطيل التخزين المؤقت للموجه تماماً.

مبدأ عمل الحل

عند ضبط DISABLE_PROMPT_CACHING=1، سيقوم Claude Code بإزالة جميع حقول cache_control من الطلبات. وبدون cache_control لن يوجد حقل scope، وبالتالي سيختفي الخطأ تماماً.

التكلفة: فقدان ميزة تحسين التكلفة التي يوفرها التخزين المؤقت للموجه. في سيناريوهات المحادثات الطويلة، قد يعني هذا رسوم Token أعلى.

طريقة الضبط

# CLI
export DISABLE_PROMPT_CACHING=1

# ~/.claude/settings.json (مشترك لجميع المنصات)
{
  "env": {
    "DISABLE_PROMPT_CACHING": "1"
  }
}

متى تختار الخيار الثاني؟

Claude Code Bedrock 报错修复方案三：双保险配置

同时设置两个环境变量，确保所有 Bedrock 不支持的字段都被清除。

# CLI
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1"
  }
}

这是最稳妥的配置，适合在生产环境中需要绝对稳定的场景。

🚀 另一个思路: 如果你不想折腾环境变量，也不想受限于 Bedrock 的兼容性问题，可以考虑切换到 Anthropic 原生 API。通过 APIYI (apiyi.com) 平台可以直接接入 Anthropic 原生接口，完整支持 Prompt Caching 所有功能（包括 scope），且无需 AWS 账号。

Claude Code Bedrock 报错完整排查流程

如果你不确定自己的情况适用哪种方案，请按以下流程排查：

第 1 步：确认报错类型

检查报错信息是否包含以下关键词：

cache_control.***.scope: Extra inputs are not permitted

或

ValidationException: ... cache_control ... scope

如果是，说明就是 scope 字段的兼容性问题。

第 2 步：确认调用路径

# 检查当前 Claude Code 使用的 API 端点
echo $ANTHROPIC_BASE_URL
echo $CLAUDE_CODE_USE_BEDROCK

如果你设置了 CLAUDE_CODE_USE_BEDROCK=1 或 AWS_REGION 等 Bedrock 相关变量，说明你正在使用 Bedrock。

第 3 步：应用修复

# 先尝试方案一
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# 测试是否修复
claude --resume

第 4 步：验证修复

# 验证环境变量是否生效
echo $CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS
# 应该输出: 1

# 测试新建会话
claude

# 测试恢复会话
claude --resume

第 5 步：如果仍然报错

# 追加方案二
export DISABLE_PROMPT_CACHING=1

# 同时检查 settings.json
cat ~/.claude/settings.json

确保 settings.json 格式正确：

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1"
  }
}

🎯 技术建议: 如果你使用 LiteLLM 等网关代理连接 Bedrock，LiteLLM 从 2026 年 3 月起已经内置了自动剥离 scope 字段的功能（PR #22867）。更新到最新版 LiteLLM 也可以解决此问题。如果你在寻找更稳定的 Claude API 接入方案，APIYI (apiyi.com) 提供 Anthropic 原生 API 通道，天然不受此类兼容性限制。

مشكلات التوافق الشائعة الأخرى في Claude Code مع Bedrock

لا يقتصر حقل cache_control.scope على كونه العقبة الوحيدة في التوافق مع Bedrock. إليك قائمة بالمشكلات المماثلة التي يواجهها مستخدمو Bedrock بشكل متكرر:

يمكن حل معظم هذه المشكلات جذرياً باستخدام CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1، لأن هذه الحقول غير المدعومة هي في جوهرها ميزات تجريبية (Beta) خاصة بـ API الأصلي لشركة Anthropic.

💰 تحسين التكلفة: يدعم Prompt Caching في Bedrock فترات TTL مدتها 5 دقائق وساعة واحدة فقط. إذا كان سيناريو استخدامك يعتمد بشكل كبير على التخزين المؤقت، فإن الوصول إلى API الأصلي لشركة Anthropic عبر خدمة وكيل API مثل APIYI (apiyi.com) يمنحك استراتيجيات تخزين مؤقت أكثر مرونة، مع تجنب تكاليف استكشاف الأخطاء وإصلاحها الناتجة عن مشكلات التوافق المذكورة أعلاه.

الأسئلة الشائعة حول أخطاء Claude Code مع Bedrock

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

جدول استكشاف أخطاء Claude Code مع Bedrock وإصلاحها

ملخص

عند استدعاء Claude Code عبر AWS Bedrock، قد تظهر رسالة الخطأ cache_control.scope: Extra inputs are not permitted. السبب الجذري هو أن Bedrock لا يدعم حقل scope التجريبي الموجود في واجهة برمجة تطبيقات (API) الخاصة بـ Anthropic.

أسرع طريقة للإصلاح:

# في واجهة سطر الأوامر (CLI)
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

// في ملف ~/.claude/settings.json (موصى به، يعمل على جميع المنصات)
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

ثلاث نقاط يجب تذكرها:

1. الخطأ ليس منك—بل هو ناتج عن اختلاف في الميزات بين Bedrock وواجهة برمجة تطبيقات Anthropic.
2. يجب على مستخدمي VS Code الضبط في ملف settings.json—لأن متغيرات بيئة shell لا تُقرأ بواسطة إضافة VS Code.
3. الأمر --resume ليس هو السبب الجذري—فجميع استدعاءات Bedrock قد تؤدي إلى هذا الخطأ، لكن --resume يجعل اكتشافه أسهل.

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

كاتب المقال: فريق تقنية APIYI
للتواصل التقني: تفضل بزيارة APIYI على apiyi.com للحصول على المزيد من دروس استخدام Claude Code والدعم الفني.
تاريخ التحديث: أبريل 2026
الإصدارات المتوافقة: Claude Code v2.1.24+، وAWS Bedrock

المراجع:

1. GitHub Issue #23220: خطأ cache_control.scope في إصدار Claude Code v2.1.24+
   • الرابط: github.com/anthropics/claude-code/issues/23220
2. GitHub Issue #41731: إضافة VS Code ترسل حقل scope غير مدعوم
   • الرابط: github.com/anthropics/claude-code/issues/41731
3. وثائق AWS Bedrock Prompt Caching:
   • الرابط: docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
4. وثائق Anthropic Prompt Caching:
   • الرابط: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
5. وثائق Claude Code الرسمية على Amazon Bedrock:
   • الرابط: docs.anthropic.com/en/docs/claude-code/bedrock