جدول المحتويات
- 1. "أوامر التشخيص" التي تُشغّلها أولاً
- 2. المصادقة وتسجيل الدخول
- 3. الاستهلاك وحدود المعدل (الأكثر شيوعاً)
- 4. السياق والرموز (Tokens)
- 5. الخادم والنموذج
- 6. التثبيت وPATH والتحديث
- 7. الشبكة والوكيل (Proxy)
- 8. MCP (الخوادم المتصلة)
- 9. الأذونات والأدوات
- 10. أخرى (thinking / صورة-PDF / IDE)
- 11. ورقة مرجعية: الخطأ ← الحل
- الخلاصة
- الأسئلة الشائعة
أنت تعمل في Claude Code فيتوقف فجأة بخطأ — "سجّل الدخول مجدداً" أو "حد المعدل" أو "الموجّه طويل جداً" أو "MCP لا يتصل". الأنواع كثيرة لدرجة أن البحث عن كل واحد منها يصبح مرهقاً. هذه المقالة مرجع عملي يفهرس الأخطاء التي تصادفها بكثرة في Claude Code، مع السبب والأمر الذي تُشغّله لكل واحد منها.
الخلاصة أولاً: بالنسبة لمعظم الأخطاء، فإن تشغيل claude doctor (تشخيص كامل) و/status (مصادقتك الحالية) و/context (تفصيل السياق) أولاً سيُضيّق نطاق السبب. والأخطاء الشائعة تتجمع في أربع عائلات: ① الاستهلاك/حدود المعدل، ② تجاوز السياق، ③ انتهاء صلاحية المصادقة، ④ فشل اتصال MCP. أدناه، نُنظّم كل فئة على شكل "العرَض ← السبب ← أمر الحل". احفظها في المفضلة وانتقل إلى القسم المناسب عندما تتعثر.
عند الشك، هذه الأوامر الثلاثة
— معظم الأخطاء تبدأ بعزل السبب
العائلات الأربع: ① الاستهلاك/حدود المعدل ② تجاوز السياق ③ انتهاء المصادقة ④ فشل اتصال MCP.
وبهدوء، فإن "التحديث إلى الأحدث" claude update يحلّ الكثير من العلل.
* الأوامر والحلول هنا مبنية على وثائق Claude Code الرسمية (حتى 2026). يتحدّث Claude Code بسرعة، وقد تتغيّر أسماء الأوامر وصياغة الرسائل. تأكّد من الأحدث عبر claude doctor والوثائق الرسمية.
1. "أوامر التشخيص" التي تُشغّلها أولاً
قبل الغوص في أخطاء بعينها، فإن معرفة أوامر التشخيص التي تساعد على عزل السبب تتيح لك تحديد معظم المشكلات بسرعة.
| الأمر | ماذا يُظهر / يفعل |
|---|---|
claude doctor | فحص كامل للتثبيت والإعدادات وخوادم MCP واستخدام السياق |
/status | طريقة المصادقة النشطة حالياً (Pro / Max / Team / مفتاح API) |
/context | تفصيل السياق (موجّه النظام، السجل، الملفات، أدوات MCP) |
/usage | حدود خطتك الحالية وأوقات إعادة الضبط |
/permissions | قائمة قواعد الأذونات (سماح/منع) ومصادرها |
/mcp | حالة اتصال خادم MCP وعدد الأدوات المعروضة |
/feedback | الإبلاغ عن علّة إلى Anthropic مع سجل المحادثة |
2. المصادقة وتسجيل الدخول
عائلة "كان يعمل ثم طلب مني فجأة تسجيل الدخول". الفخّ الكلاسيكي هو مفتاح API في متغيّر بيئة يتجاوز اشتراكك.
| العرَض | السبب | الحل |
|---|---|---|
| Not logged in / Please run /login | لا يوجد اعتماد صالح (رمز منتهي، إلخ) | /login. إذا تكرّر، تحقّق من ساعة النظام وقفل Keychain |
| Invalid API key | بقاء ANTHROPIC_API_KEY قديم | env | grep ANTHROPIC ← unset ANTHROPIC_API_KEY ← /login |
| OAuth token revoked / expired | تسجيل خروج من مكان آخر / تعطيل من المسؤول | /logout ← /login. اشتبه أيضاً في انحراف الساعة |
| This organization has been disabled | مفتاح API من مؤسسة مُعطّلة يتجاوز | أزِل المفتاح من ملف تعريف الصدفة (.zshrc إلخ) ← /login ← تأكّد عبر /status |
| 403 Forbidden (after login) | اشتراك منتهٍ / دور مفقود / تدخّل الوكيل | تحقّق من الاشتراك ودور Console. للوكلاء، اضبط HTTPS_PROXY |
قاعدة عامة: مفتاح API في متغيّر بيئة له أسبقية على تسجيل الدخول بالاشتراك. إذا ضبطت ANTHROPIC_API_KEY لمهمة CI ونسيته، فسيُتجاهل اشتراكك الشخصي Pro/Max. التحقّق من "أيّ اعتماد نشط" عبر /status أولاً هو الخطوة الصحيحة.
3. الاستهلاك وحدود المعدل (الأكثر شيوعاً)
أكثر الشكاوى شيوعاً مع Claude Code. يستهلك Claude Code ما يعادل 10-100 ضعف رموز الدردشة (محادثات متعددة الأدوار، سياقات ضخمة، رحلات ذهاب وإياب للأدوات)، لذا تبلغ الحدود أسرع مما يبدو معقولاً.
3 خطوات عندما "تبلغ الحد"
/usage للحدود ووقت إعادة الضبط، /status للاعتماد/model لنموذج أخفّ، /compact لتقليص السجل، عطّل MCP غير المستخدم
ملاحظة: "Server is temporarily limiting requests" هو تقييد مؤقت من جانب الخادم، وليس حد خطتك. فقط انتظر وأعد المحاولة.
لا تخلط بينه وبين حدود الخطة (الجلسة/الأسبوعية).
والمزيد: "429 / Request rejected" هو تجاوز للمعدل على مفتاح API أو مساحة العمل لديك. "Credit balance is too low" هو نفاد رصيد Console المدفوع مسبقاً (أعِد الشحن في الفوترة أو انتقل إلى اشتراك). لاحظ أنه حوالي مارس 2026، أبلغ مستخدمو Max عن استنزاف نوافذ الـ5 ساعات لديهم بسرعة غير معتادة في الإعلام التقني وفي مشكلات المستودع الرسمي (يُشتبه أنها علّة). إذا تكرّر، حدّث إلى أحدث إصدار، وقِس عبر /usage، وقدّم /feedback عند الحاجة. لتوفير الرموز بشكل منهجي، راجع توفير رموز الذكاء الاصطناعي وتوفير الرموز في Claude Code.
4. السياق والرموز (Tokens)
يظهر هذا عندما تتعامل مع اجتماعات طويلة أو ملفات ضخمة.
| العرَض | السبب | الحل |
|---|---|---|
| Prompt is too long | تجاوز المحادثة + الملفات لنافذة السياق | /compact (تلخيص)، /clear (إعادة ضبط)، /context لرؤية التفصيل، عطّل MCP غير المستخدم عبر /mcp |
| Error during compaction: Conversation too long | مساحة حرّة غير كافية لمخرجات التلخيص | اضغط Esc مرتين للتراجع بضعة أدوار، ثم /compact. إذا استمر التعثّر، /clear |
| Auto-compact is thrashing | مخرجات ضخمة تملأ السياق مجدداً مباشرة بعد التلخيص | اقرأ الملفات الكبيرة حسب نطاق الأسطر / /compact keep only <focus> / انقلها إلى وكيل فرعي |
الحيلة هي ألّا تقرأ ملفاً ضخماً بأكمله أبداً. مرّر السجلات والبيانات في أجزاء صغيرة بنطاق أسطر. واستيعاب فكرة نافذة السياق يجعل هذا الصنف من الأخطاء أندر بكثير.
5. الخادم والنموذج
| العرَض | السبب | الحل |
|---|---|---|
| 500 Internal server error | عطل مؤقت من جانب Anthropic | تحقّق من status.claude.com ← أعد المحاولة بعد دقيقة |
| 529 Overloaded (repeated) | وصول الـAPI إلى السعة مؤقتاً | انتظر بضع دقائق. بدّل النموذج عبر /model لتوزيع الحِمل |
| Request timed out | لا استجابة خلال الـ10 دقائق الافتراضية | قسّم المهمة. على خط بطيء، ارفع API_TIMEOUT_MS |
| model not found / no access | اسم نموذج خاطئ أو غير متوفّر في خطتك | /model لإعادة الاختيار. تحقّق من متغيّر بيئة ANTHROPIC_MODEL قديم |
| Opus is not available with Pro plan | النموذج المختار غير متوفّر في خطتك | /model إلى نموذج متاح. بعد تغيير الخطة، /logout←/login |
6. التثبيت وPATH والتحديث
| العرَض | السبب | الحل |
|---|---|---|
| command not found: claude | دليل التثبيت ليس على PATH | أضِف ~/.local/bin (في Windows: %USERPROFILE%\.local\bin) إلى PATH |
| Install fails (HTML error, etc.) | حجب من الوكيل / المنطقة | Homebrew brew install --cask claude-code / WinGet winget install Anthropic.ClaudeCode |
| TLS / SSL certificate verification failed | تفتيش TLS من وكيل الشركة / شهادة CA مفقودة | وجِّه NODE_EXTRA_CA_CERTS=/path/ca.pem. NEVER set NODE_TLS_REJECT_UNAUTHORIZED=0 |
| Multiple claude installations found | نسخ مكرّرة من npm/Homebrew/native | أبقِ واحدة فقط، مثلاً npm uninstall -g @anthropic-ai/claude-code |
| علل من إصدار قديم | عدم التحديث | claude update (الحل الأول الذي يعالج كثيراً من العلل) |
7. الشبكة والوكيل (Proxy)
شائع على شبكات الشركات وVPN. تأكّد أولاً من إمكانية الوصول عبر curl -I https://api.anthropic.com.
| العرَض | السبب | الحل |
|---|---|---|
| Unable to connect / ECONNREFUSED / ETIMEDOUT | عدم اتصال / حجب VPN / الوكيل غير مضبوط | اضبط HTTPS_PROXY=http://proxy:8080. اطلب من قسم تقنية المعلومات السماح لـapi.anthropic.com |
| SSL certificate verification failed (corporate) | شهادة اعتراض موقّعة ذاتياً | احصل على حزمة CA من قسم تقنية المعلومات واضبط NODE_EXTRA_CA_CERTS |
| 403 host_not_allowed (cloud runs) | خارج قائمة السماح لبيئة السحابة | اضبط الوصول للشبكة على Custom واسمح للنطاق المستهدف |
8. MCP (الخوادم المتصلة)
تصادف هذه بمجرد أن تبدأ استخدام خوادم MCP. تحقّق من الحالة أولاً عبر /mcp.
| العرَض | السبب | الحل |
|---|---|---|
| Server failed to connect / Pending approval | تعطّل الخادم / غير قابل للوصول / مصادقة مطلوبة | /mcp للحالة. stdio: تحقّق من وجود الأمر + قابليته للتنفيذ؛ HTTP: تحقّق من URL/ترويسات المصادقة |
| Tool not found | متصل لكن لا أدوات معروضة / اسم خاطئ | /mcp لتأكيد عدد الأدوات، claude mcp get <name> للتحقّق من الصحة |
| Reconnection attempts exhausted | تعطّل خادم HTTP/SSE بعد 5 محاولات | تأكّد أن الخادم يعمل، أعِد الاتصال يدوياً في /mcp. لـstdio، أعِد تشغيل claude |
| MCP server timeout | بدء التشغيل >5 ثوانٍ، إلخ | MCP_TIMEOUT=10000 claude (مللي ثانية). لكل خادم: "timeout" في .mcp.json |
9. الأذونات والأدوات
عائلة "طُلب الإذن حتى في وضع التجاوز (bypass)". النقطة الجوهرية: قواعد المنع لها أسبقية على السماح والتجاوز.
| العرَض | السبب | الحل |
|---|---|---|
| طُلب الإذن حتى في وضع التجاوز | قواعد المنع تفوز؛ العمليات الخطرة تطلب الإذن دائماً (قاطع دائرة) | تحقّق من قواعد المنع واضبطها في /permissions |
| Tool execution denied by PreToolUse hook | حظرها خطّاف (hook) برمز خروج 2 | تحقّق من الخطّاف في .claude/settings.json. شاهِد المخرجات عبر claude --debug |
لمعرفة سبب توقّفه رغم التجاوز، راجع لماذا يطلب الإذن حتى في وضع التجاوز؛ ولتصميم أذونات آمن، راجع أوضاع الأذونات والأمان.
10. أخرى (thinking / صورة-PDF / IDE)
- thinking blocks cannot be modified (400): علّة معروفة تتعطّل فيها كتل التفكير الموسّع (extended-thinking) في السجل. اضغط Esc مرتين ← /rewind، وإلا فجلسة جديدة، و
claude update. التفاصيل: خطأ thinking blocks 400. - Could not check the pull request status: مشكلة اتصال بـGitHub (غالباً مصادقة
gh). ابدأ بـgh auth status. التفاصيل: خطأ حالة PR. - Image was too large / PDF too large: الصور التي تتجاوز 8000 بكسل على الحافة الطويلة، وملفات PDF التي تتجاوز 100 صفحة / 32 ميغابايت تُرفض. اضغط Esc مرتين لإزالة المرفق؛ غيّر الحجم أو اقرأ حسب نطاق الأسطر. أشِر إلى الملفات الكبيرة بالمسار بدلاً من لصقها.
- امتداد VS Code لا يتصل: تأكّد من أن
claude --versionيعمل في طرفية VS Code. تحقّق من PATH، أعِد تشغيل VS Code، أعِد تثبيت الامتداد.
11. ورقة مرجعية: الخطأ ← الحل
| عندما يحدث هذا | جرّب هذا أولاً |
|---|---|
| سبب غير معروف / عام | claude doctor ← /status ← /context |
| طُلب منك فجأة تسجيل الدخول | /status ← (إذا كان هناك مفتاح قديم) unset ANTHROPIC_API_KEY ← /login |
| بلغت حد المعدل | /usage ← /model أخفّ ← /compact ← انتظر |
| Prompt is too long | /compact ← /clear ← اقرأ الملفات الكبيرة حسب نطاق الأسطر |
| 500/529/مهلة منتهية | تحقّق من status.claude.com ← انتظر قليلاً ← /model |
| command not found: claude | أضِف ~/.local/bin إلى PATH |
| تعذّر الاتصال (شبكة الشركة) | curl -I https://api.anthropic.com ← HTTPS_PROXY/NODE_EXTRA_CA_CERTS |
| MCP لا يتصل | /mcp ← تحقّق من URL/الأذونات/الأمر ← MCP_TIMEOUT |
| طُلب الإذن حتى في وضع التجاوز | /permissions للتحقّق من قواعد المنع |
| تريد فقط إصلاحه | claude update (الإصدار الأحدث يصلح الكثير) |
الخلاصة
لدى Claude Code أخطاء كثيرة، لكن الخطوة الأولى هي عزل السبب بثلاثة أوامر: claude doctor / /status / /context — وهذا يُعيد معظم المشكلات إلى الحركة. والشائعة منها أربع عائلات — الاستهلاك/حدود المعدل، تجاوز السياق، انتهاء المصادقة، فشل اتصال MCP — مع /usage و/compact و/login و/mcp كحلول الخط الأول.
والخطوة الأقوى التي يسهل إغفالها هي إبقاؤه محدّثاً عبر claude update. يتحدّث Claude Code بسرعة، والعلل السابقة (مثل thinking-blocks 400) غالباً ما تختفي بمجرد رفع الإصدار. "عند التعثّر، أوامر التشخيص الثلاثة أولاً؛ وإن لم يُصلَح، حدّث إلى الأحدث." التزِم بهذا النمط، وستتوقّف عن إذابة الوقت في الأخطاء.
قراءات ذات صلة: خطأ thinking blocks 400، خطأ التحقّق من حالة PR، توفير الرموز في Claude Code، لماذا يطلب الإذن في وضع التجاوز، وما هو MCP.
الأسئلة الشائعة
س. ظهر خطأ — ماذا أفعل أولاً؟
ج. شغّل claude doctor. يفحص التثبيت والإعدادات وMCP والسياق دفعة واحدة. ثم انظر إلى /status (المصادقة الحالية) و/context (ما الذي يستهلك السياق)، وعادةً يمكنك تمييز ما إذا كانت المشكلة في المصادقة أو السياق أو الاتصال.
س. أبلغ حدود المعدل بسرعة. ما الذي يساعد؟
ج. يستهلك Claude Code ما يعادل 10-100 ضعف رموز الدردشة، لذا تبلغها أسرع مما هو متوقّع. تحقّق من الحدود ووقت إعادة الضبط عبر /usage، وبدّل إلى نموذج أخفّ عبر /model، وقلّص السجل عبر /compact، وعطّل MCP غير المستخدم. إذا لم يكفِ ذلك، فكّر في خطة أعلى (Max، إلخ) أو أرصدة إضافية.
س. تظهر "Invalid API key" لكن مفتاحي يُفترض أنه صحيح.
ج. السبب الكلاسيكي هو متغيّر بيئة ANTHROPIC_API_KEY قديم يتجاوز اشتراكك. تحقّق عبر env | grep ANTHROPIC، ثم unset ANTHROPIC_API_KEY (أزِله من ملف تعريف الصدفة أيضاً)، ثم /login وتأكّد عبر /status.
س. لا يتصل على شبكة شركتي.
ج. تأكّد أولاً من إمكانية الوصول عبر curl -I https://api.anthropic.com. للوكيل، اضبط HTTPS_PROXY؛ ولتفتيش TLS، وجِّه NODE_EXTRA_CA_CERTS إلى شهادة CA. لا تستخدم NODE_TLS_REJECT_UNAUTHORIZED=0 — فهو خطر. المسار الصحيح هو أن تطلب من قسم تقنية المعلومات السماح لـapi.anthropic.com.
س. لا شيء أجرّبه ينجح — الملاذ الأخير؟
ج. حدّث إلى الأحدث عبر claude update. يتحدّث Claude Code بسرعة والعلل المعروفة غالباً ما تختفي بمجرد رفع الإصدار. إن استمر الفشل، أبلِغ عنه عبر /feedback (يتضمّن سجل المحادثة) إلى Anthropic.
