لقد واجه كل مطور استخدم Claude Code هذا المشهد من قبل: يظهر سطر في الطرفية (Terminal) بنص "Symbioting… (3m 12s · ↓ 5.7k tokens)"، ويبدو شريط التقدم وكأنه متجمد، حيث لا توجد أي مخرجات جديدة لعدة دقائق. قد تحاول إرسال رسالة مثل "هل ما زلت هناك؟"، لتفاجأ بأن Claude يستأنف العمل فوراً ويكمل المهمة التي كان يقوم بها.
هذه التجربة الغريبة المتمثلة في "التجمد + الإحياء عبر رسالة" تبدو وكأنها لغز، لكنها في الواقع ناتجة عن تداخل عدة أنماط فشل في بروتوكول البث الخاص بـ Anthropic، وآليات المهلة الزمنية (Timeout)، وإدارة السياق. يستند هذا المقال إلى وثائق استكشاف الأخطاء وإصلاحها الرسمية لـ Claude Code، بالإضافة إلى نقاشات GitHub (الإصدارات #25979، #24688، #39718، #25286، #25539، #51659)، لشرح الأسباب الحقيقية وراء تجمد Claude Code، مع تقديم 7 طرق استعادة فورية و5 استراتيجيات وقائية.
القيمة الجوهرية: بعد قراءة هذا المقال، ستعرف معنى كل فعل في مؤشر الانتظار (Spinner)، ولماذا تنجح الرسائل أحياناً في إحياء العملية، ومتى يجب عليك استخدام Ctrl+C لإعادة التشغيل، وكيفية خفض معدل التجمد إلى ما يقرب من الصفر.
قراءة شاملة لمؤشرات حالة Claude Code
لاستكشاف مشكلة "التجمد"، الخطوة الأولى هي فهم السطر الذي يعرضه لك Claude Code في الطرفية. تبدو عبارة Symbioting… (3m 12s · ↓ 5.7k tokens) غامضة، لكنها في الواقع معلومات مهيكلة، ولكل جزء منها معنى محدد.
| الحقل | قيمة المثال | المعنى |
|---|---|---|
| فعل المؤشر (Spinner) | Symbioting… |
وصف مجازي للمرحلة الحالية، يمكن تخصيصه منذ الإصدار 2.1.23 |
| وقت الانتظار | 3m 12s |
الوقت التراكمي المستغرق منذ بدء هذه الجولة |
| سهم التدفق | ↓ أو ↑ |
يشير ↓ إلى استقبال البيانات من API، بينما يشير ↑ إلى الإرسال |
| عداد الرموز (Tokens) | 5.7k tokens |
عدد الرموز التي تم تنزيلها/رفعها حتى الآن |
يحتوي Claude Code على 187 فعلاً افتراضياً للمؤشر، مثل Befuddling وRuminating وAccomplishing وSymbioting. هذه الأفعال موجودة فقط لجعل تجربة الانتظار أكثر حيوية، ولا توجد بينها أي فروق تقنية. منذ الإصدار 2.1.23، تم تقديم خيار الإعداد spinnerVerbs، وهناك حزم مجتمعية تحتوي على أكثر من 1900 فعل مخصص يمكنك استبدالها.
تحديد ما إذا كان Claude Code متجمداً حقاً لا يعتمد على الفعل، بل على أمرين: هل الوقت لا يزال يزداد؟ وهل عداد الرموز لا يزال يتحرك؟. إذا مر 30 ثانية بعد الـ 3m 12s وأصبح الوقت 3m 42s ولكن عداد الرموز لا يزال متوقفاً عند 5.7k، فيمكنك حينها الجزم بأن استجابة البث قد توقفت.
إذا كنت تستخدم Claude API عبر منصات وسيطة مثل APIYI (apiyi.com)، فإن معاني الحقول في سطر الحالة هي نفسها تماماً كما في النسخة الرسمية، ويمكنك استخدام نفس الطريقة لتحديد المشكلة.
بمجرد فهم مؤشرات الحالة، يمكنك مقارنتها بالأداء الفعلي لتحديد السبب الجذري. فيما يلي الأسباب الستة مرتبة حسب تكرار الحدوث، وهي تغطي أكثر من 90% من الحالات الفعلية الموثقة في متتبع مشكلات GitHub.
السبب الجذري 1: انقطاع صامت في استجابة API المتدفقة (Streaming)
هذا هو السبب الأكثر شيوعاً وخفاءً، ويطابق المشكلة رقم #25979 على GitHub. لا يمتلك عميل HTTP الخاص بـ Claude Code آلية مهلة قراءة (read timeout)، فإذا توقف الـ API عن إرسال الحزم أثناء النقل، ستظل العملية عالقة في حالة epoll_wait في النواة بانتظار بيانات جديدة. ستستمر أيقونة التحميل (spinner) في الدوران، لكن عداد الـ token لن يرتفع. تشمل الأسباب الشائعة تذبذب الشبكة العابرة للحدود، أو استخدام tmux، أو انقطاع اتصالات SSH طويلة الأمد.
السبب الجذري 2: حجم حمولة (payload) استدعاء الأداة كبير جداً مما يؤدي لإعادة تعيين الاتصال
يطابق المشكلة رقم #39718. عندما يطلب النموذج من Claude Code تنفيذ أداة تنتج مخرجات ضخمة (مثل كتابة ملف يحتوي على مئات الآلاف من الأسطر)، يتم إعادة تعيين اتصال HTTP الأساسي بواسطة نظام التشغيل إذا لم يتم نقل بيانات فعالة لمدة 5 دقائق. لا يقوم Claude Code بالتقاط هذا الخطأ، لذا يستمر في عرض أيقونة التحميل. عادة ما يتوقف هذا النوع من التعليق بدقة عند علامة الـ 5 دقائق.
السبب الجذري 3: اضطراب الضغط التلقائي (Auto-compact thrashing)
يتم تفعيل الضغط التلقائي عندما تقترب نافذة السياق من الامتلاء. إذا تمت قراءة ملف ضخم أو مخرجات أداة كبيرة وإعادتها إلى السياق فور ضغطها، فسيؤدي ذلك إلى تكرار عملية الضغط، مما يتسبب في توقف النظام وإظهار رسالة Autocompact is thrashing. قبل ظهور هذه الرسالة، يبدو الأمر في واجهة المستخدم وكأنه تعليق.
السبب الجذري 4: تجاوز معدل استخدام السياق لـ 80%
توضح الوثائق الرسمية أن وقت الاستجابة يتدهور بشكل ملحوظ بعد تجاوز 80% من سعة السياق، وفي بعض الحالات يظهر ذلك كعدم استجابة لفترة طويلة. يتميز هذا "التعليق الزائف" بأن عداد الـ token لا يزال ينمو ببطء، ولكن بسرعة أقل بكثير من المعتاد.
السبب الجذري 5: خطأ في إعدادات settings يؤدي إلى تعليق عند البدء
يطابق المشكلات رقم #31049 و #29652. على سبيل المثال، إذا كان إعداد enableAllProjectMcpServers: true يقوم بتحميل عدد كبير من خوادم MCP المحلية، أو إذا تم كتابة additionalDirectories بمسار غير صحيح مثل //C:/، فقد يتسبب ذلك في تعليق Claude Code عند بدء التشغيل. عادة ما يظهر هذا التعليق في الثواني الأولى من فتح جلسة جديدة.
السبب الجذري 6: بقايا سطر الحالة (الاستجابة مكتملة لكن الواجهة لم تتحدث)
يطابق المشكلة رقم #25539. في بعض الإصدارات، يكون Claude قد أعاد النتيجة كاملة، لكن أيقونة التحميل في واجهة الطرفية لم تختفِ، مما يوحي بأنها لا تزال تعمل. في هذه الحالة، إذا ضغطت على زر الإدخال (Enter) أو أرسلت رسالة، سيبدأ Claude جولة عمل جديدة فوراً؛ فهو لم يكن عالقاً، بل كانت الواجهة تضللك فقط.
عند استكشاف الأخطاء، يُنصح بالتحقق أولاً مما إذا كان عداد الـ token يرتفع. إذا كنت تستخدم خدمة وكيل API مثل APIYI (apiyi.com)، يمكنك التحقق من سجلات المنصة لمعرفة ما إذا كان الطلب قد أعاد رمز الحالة 200 OK، واستخدام ذلك للتحقق المتبادل مع حالة واجهة Claude Code.
لماذا تؤدي رسالة واحدة إلى "إحياء" Claude Code؟
يلاحظ الكثيرون ظاهرة هندسية "غريبة": عندما يتوقف Claude Code عن الاستجابة لمدة 3 دقائق، يكفي أن ترسل رسالة مثل "هل أنت موجود؟" أو حتى الضغط على زر الإدخال (Enter) ليعود فوراً ويكمل المهمة التي كان يقوم بها. يمكن تفسير هذه الظاهرة من منظور البروتوكول التقني.
الحالة الأولى هي بقايا حالة العرض (السبب الجذري 6). في الواقع، يكون Claude قد أنهى الاستجابة بالفعل، لكن واجهة المستخدم لم تقم بإزالة مؤشر التحميل (spinner). في هذه الحالة، يتم التعامل مع رسالتك الجديدة مباشرة كـ "موجه" (prompt) للجولة التالية، مما يبدو كأنه "إحياء"، بينما هو في الحقيقة مجرد استمرار للعملية.
الحالة الثانية هي تعليق الاستجابة المتدفقة (السبب الجذري 1). عند تلقي Claude Code لمدخلات جديدة، يقوم بإغلاق حالة الانتظار الحالية (hang) بشكل استباقي، وينظف الطلبات غير المكتملة، ويبدأ طلب HTTP جديداً. يتم إرسال الطلب الجديد مع سجل المحادثة الكامل، ويستأنف النموذج الإجابة من نقطة التوقف، لذا يبدو ظاهرياً أنه "عاد للعمل".
الحالة الثالثة تتعلق بخادم MCP أو استدعاءات الأدوات التي تنتظر استجابة من الطرف الآخر. يتم توجيه الرسالة الجديدة بواسطة Claude Code لاتخاذ قرار استدعاء أداة جديدة، مما يؤدي بشكل غير مباشر إلى تجاوز ذلك الاستدعاء العالق.
يجب التأكيد على أن إرسال رسالة ليس حلاً سحرياً لكل شيء. عندما يكون التعليق ناتجاً عن عملية أساسية دخلت في حالة انتظار غير قابلة للاسترداد (مثل المراحل المتأخرة من السبب الجذري 2)، فإن إرسال رسالة سيؤدي فقط إلى وضعها في طابور الإدخال دون معالجتها، وفي هذه الحالة يجب استخدام Ctrl+C أو إغلاق الطرفية (terminal). بالنسبة للسيناريوهات التي تستخدم خدمة وكيل API عبر منصة APIYI (apiyi.com)، تكون نسبة نجاح "الإحياء" عبر الرسائل أعلى، لأن منصات الوكيل عادة ما تقوم بتحرير الاتصالات التي تجاوزت المهلة (timeout) بشكل أسرع من نقاط النهاية الرسمية.
7 طرق لاستعادة Claude Code عند توقفه
تتطلب الأسباب الجذرية المختلفة وسائل استعادة مختلفة. يوضح الجدول أدناه الطرق السبع الأكثر فعالية مرتبة من "الأقل تطفلاً" إلى "الأكثر تطفلاً" لتسهيل اتخاذ القرار.
| الطريقة | الأمر | السبب الجذري المناسب | هل تفقد السياق؟ |
|---|---|---|---|
| إرسال رسالة | إدخال نص مباشر | السبب 1 / 6 | لا |
| مقاطعة العملية | Ctrl+C |
السبب 1 / 2 / 3 | لا |
| التشخيص الذاتي | /doctor |
أي سبب، للتشخيص أولاً | لا |
| ضغط السياق | /compact |
السبب 3 / 4 | جزء من التاريخ يصبح ملخصاً |
| مسح الجلسة | /clear |
السبب 4 (حالة حادة) | نعم |
| إغلاق الطرفية ثم الاستئناف | claude --resume |
السبب 1 / 2 (حالة حادة) | لا |
| إنهاء العملية قسراً | kill -9 <pid> |
السبب 1 / 2 (غير قابل للاسترداد) | فقدان الجولة الحالية |
توصية ترتيب العمليات الفعلية هي "البدء بالأسهل ثم الأصعب". ابدأ بالضغط على زر الإدخال أو إرسال أي رسالة؛ إذا لم ينجح الأمر، استخدم Ctrl+C لإلغاء الجولة الحالية؛ إذا لم تستجب الطرفية تماماً، أغلقها بالكامل ثم استخدم claude --resume لاستعادة الجلسة.
يعد /doctor أمر التشخيص الموصى به رسمياً من Anthropic. فهو يفحص التثبيت، ملفات الإعدادات، قائمة خوادم MCP، ومعدل استخدام السياق، وعادة ما يقدم اقتراحات إصلاح محددة بعد الانتهاء. إذا أظهر المخرج Context: 87%، فمن المؤكد تقريباً أن السبب هو السبب الجذري 4، ويمكن استخدام /compact لتخفيف الضغط فوراً.
بالنسبة لسيناريوهات المهام الطويلة، يُنصح بإضافة أمر /compact بشكل دوري في سير العمل للحفاظ على استخدام السياق تحت 60%. وفي الوقت نفسه، عند استدعاء Claude عبر منصة APIYI (apiyi.com)، يمكنك تخصيص حصص مستقلة للعملية الرئيسية لـ Claude Code وخوادم MCP، مما يسهل تحديد مصدر الخطأ.
5 ممارسات مثالية لمنع توقف Claude Code
إن استكشاف الأخطاء وإصلاحها بعد وقوعها ليس سوى "إطفاء للحرائق"، بينما تعتمد سير العمل المستقرة حقاً على الوقاية. فيما يلي 5 ممارسات مبنية على تحليل الأسباب الجذرية للعديد من مشكلات GitHub، والتي يمكنها تقليل معدل التوقف إلى مستويات لا تكاد تذكر.
-
قراءة الملفات الكبيرة على أجزاء: قراءة ملف بحجم 1 ميجابايت أو أكثر مباشرة ستؤدي بالتأكيد إلى ضغط على نافذة السياق. استخدم أسلوب الخطوتين: أولاً
ls -laلمعرفة الحجم، ثم استخدمReadمع معاملاتoffset/limitلقراءة الملف على أجزاء، مما يجنبك السبب الجذري الرابع. -
تفويض المهام المعقدة للوكلاء الفرعيين (subagent): يمتلك الوكيل الفرعي في Claude Code نافذة سياق مستقلة. إن إسناد مهام مثل إنشاء ملفات متعددة أو إعادة كتابة الأكواد البرمجية على نطاق واسع للوكيل الفرعي يمنع استهلاك سياق النموذج الرئيسي من الأساس.
-
تعطيل خوادم MCP المشبوهة: كل خادم MCP إضافي يزيد من مخاطر التوقف أثناء بدء التشغيل. احتفظ فقط بخوادم MCP التي تستخدمها يومياً في الإعدادات، وقم بتعطيل البقية لتقليل السبب الجذري الخامس بشكل ملحوظ.
-
ضبط مهلة النموذج الرئيسي ومهلة القراءة: ممارسة شائعة في المجتمع هي ضبط
STREAM_READ_TIMEOUT_MSعلى 120 ثانية، مع إضافة عملية مراقبة (watchdog) خارجية تراقب ملفات JSONL؛ إذا لم يزد حجمها، يتم إعادة تشغيل العملية تلقائياً. هذا فعال جداً ضد السبب الجذري الأول. -
استخدام مسار API مستقر: الاتصالات العابرة للحدود، وشبكات الإنترنت المنزلية، واستخدام tmux تزيد من احتمالية توقف تدفق البيانات. الحل البسيط هو استخدام منصة تجميع مثل APIYI (apiyi.com) لاستدعاء نماذج Claude، مما يضمن مرور اتصالات TCP عبر عقد وسيطة مستقرة، ويقلل من تكرار حدوث السبب الجذري الأول.
الفرق التي تطبق هذه الممارسات الخمس أفادت عموماً بانخفاض معدل التوقف من 5-10 مرات أسبوعياً إلى أقل من مرة واحدة، كما انخفض متوسط زمن الاستعادة من 5-10 دقائق إلى بضع ثوانٍ فقط.
الأسئلة الشائعة
س1: هل تعني الأفعال المختلفة في شريط التحميل (spinner) أن Claude يقوم بمهام مختلفة؟
لا، لا تعني ذلك. الأفعال الـ 187 الافتراضية هي مجرد نصوص عشوائية لإضفاء طابع بشري، ولا توجد علاقة بينها وبين حالة Claude الفعلية. للحكم على الحالة، يرجى النظر إلى عدد الرموز (token) ومدة الانتظار.
س2: هل أفقد السياق عند الضغط على Ctrl+C؟
لا. يقوم Ctrl+C بإلغاء الجولة الحالية التي لم تكتمل فقط، بينما تظل المحادثة بأكملها محفوظة. إذا لم يستجب Ctrl+C، يمكنك الضغط عليه مرة أخرى أو إغلاق الطرفية (Terminal) مباشرة، ثم استعادة الجلسة باستخدام الأمر claude --resume.
س3: هل يسهل تعليق Claude Code عند استخدامه داخل الصين؟
تعد الشبكات العابرة للحدود أحد الأسباب الرئيسية لانقطاع تدفق البيانات (streaming). نوصي باستخدام خدمات وكيل API مثل APIYI (apiyi.com) لاستدعاء نماذج Claude، حيث تقوم عقد الوكيل المستقرة بالحفاظ على اتصال طويل الأمد مع Anthropic، مما يقلل بشكل كبير من احتمالية حدوث تعليق للمطورين داخل الصين.
س4: ماذا أفعل إذا ظهرت لي رسالة `Autocompact is thrashing`؟
أوقف المهمة الحالية فوراً، واستخدم أمر ضغط مركز مثل /compact keep only the plan and the diff لإزالة مخرجات النص الخام الكبيرة من السياق. إذا استمر الفشل، ابدأ جلسة جديدة أو قم بتغيير طريقة قراءة الملفات الكبيرة إلى نمط الوكيل الفرعي (subagent).
س5: هل يمكنني تعديل أفعال شريط التحميل بنفسي؟
نعم، يمكنك ذلك. أضف حقل spinnerVerbs في ملف ~/.claude/settings.json؛ حيث يمكن أن تكون الأنماط default أو append أو replace مع مصفوفة من السلاسل النصية. يوجد في المجتمع حزم تحتوي على 88 سمة وأكثر من 1900 فعل يمكنك استخدامها مباشرة.
الخلاصة
إن تعليق Claude Code ناتج في جوهره عن تداخل مشاكل في ثلاثة أنظمة فرعية: بروتوكول تدفق البيانات، إدارة السياق، وتكامل MCP في السيناريوهات المعقدة. من خلال فهم الحقول الأربعة لمؤشر الحالة، وحفظ الأسباب الجذرية الستة وطرق الاستعادة السبع، يمكنك تحويل "الأخطاء الغامضة" إلى "أعطال معروفة".
نصيحتنا العملية هي تحويل طرق الاستعادة إلى ممارسة تلقائية: أرسل رسالة أولاً، ثم استخدم Ctrl+C، ثم /doctor، وأخيراً أغلق الطرفية واستخدم claude --resume. مع استخدام خدمة وكيل API مستقرة واتباع 5 ممارسات وقائية — مثل الحفاظ على السياق تحت 80%، وتفويض الملفات الكبيرة للوكيل الفرعي (subagent)، واستخدام المسارات المستقرة عبر APIYI (apiyi.com) — يمكن حل معظم حالات التعليق ذاتياً في غضون ثوانٍ.
المؤلف: فريق APIYI التقني
للتواصل: احصل على دعم كامل لنماذج Claude وخدمة وكيل مستقرة لـ Claude Code عبر APIYI (apiyi.com)
تاريخ التحديث: 2026-05-13
