جدول المحتويات
- 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 expired · Please run /login) | /login. إذا تكرّر، تحقّق من ساعة النظام وقفل Keychain |
| Invalid API key · Fix external API key | رفضت الـ API مفتاحًا من ANTHROPIC_API_KEY أو من apiKeyHelper (غالبًا مفتاح قديم) | env | grep ANTHROPIC ← unset ANTHROPIC_API_KEY ← /login |
| OAuth token revoked · Please run /login Please run /login · API Error: 401 OAuth token has expired ... | تسجيل خروج من كل مكان / سحب المسؤول للوصول (revoked)، فشل التحديث التلقائي (expired) | /login. وإن عاد في الجلسة نفسها فـ /logout ← /login. وإن ظهر عند كل تشغيل فاشتبه في انحراف الساعة |
| Your ANTHROPIC_API_KEY belongs to a disabled organization · … API Error: 400 ... This organization has been disabled. | يُستخدم ANTHROPIC_API_KEY قديم من مؤسسة مُعطّلة. وإن لم يكن هناك متغيّر بيئة، فالمعطّلة هي مؤسسة /login | أزِل المفتاح من ملف تعريف الصدفة (.zshrc إلخ) ← /login ← تأكّد عبر /status. ومن دون متغيّر بيئة، تواصل مع الدعم أو سجّل الدخول بحساب آخر |
| 403 Forbidden (after login) | اشتراك منتهٍ / دور مفقود / تدخّل الوكيل | تحقّق من الاشتراك ودور Console. للوكلاء، اضبط HTTPS_PROXY |
قاعدة عامة: مفتاح API في متغيّر بيئة له أسبقية على تسجيل الدخول بالاشتراك. إذا ضبطت ANTHROPIC_API_KEY لمهمة CI ونسيته، فسيُتجاهل اشتراكك الشخصي Pro/Max. التحقّق من "أيّ اعتماد نشط" عبر /status أولاً هو الخطوة الصحيحة. ولمعالجة أعمق لمشاكل المصادقة وتسجيل الدخول (أسبقية ANTHROPIC_API_KEY، وانتهاء صلاحية التوكن، وKeychain وغيرها)، راجع أسباب أخطاء المصادقة وتسجيل الدخول وطرق معالجتها.
3. الاستهلاك وحدود المعدل (الأكثر شيوعاً)
أكثر الشكاوى شيوعاً مع Claude Code. وبحسب دليل التكاليف الرسمي (Manage costs effectively)، يحمل كل دور في Claude Code محتوى الملفات واستدعاءات الأدوات واستدلالاً متعدد الخطوات، لذا قد تستهلك جلسة تصحيح واحدة أكثر من يوم كامل من الدردشة. ولهذا تبلغ الحدود أسرع مما يبدو.
3 خطوات عندما "تبلغ الحد"
/usage للحدود ووقت إعادة الضبط، /status للاعتماد/model لنموذج أخفّ، /compact لتقليص السجل، عطّل MCP غير المستخدم
ملاحظة: "Server is temporarily limiting requests" هو تقييد مؤقت من جانب الخادم، وليس حد خطتك. فقط انتظر وأعد المحاولة.
لا تخلط بينه وبين حدود الخطة (الجلسة/الأسبوعية).
والمزيد: "API Error: Request rejected (429)" يعني أنك بلغت حد المعدل المضبوط لمفتاح API (أو لمشروعك في Amazon Bedrock أو Google Cloud)؛ وإن كنت تقصد استخدام اشتراك، فتحقّق عبر /status من عدم تسلّل ANTHROPIC_API_KEY. و"Credit balance is too low" يعني نفاد رصيد Console المدفوع مسبقاً، أو أن الطلبات تُرسل بمفتاح API من Console بينما أردت استخدام اشتراكك (أعِد الشحن، أو تحقّق من المفتاح في /status وأزِله). لاحظ أنه في مارس 2026، اشتكى مستخدمو Pro وMax من نفاد حدود Claude Code أسرع بكثير من المتوقع، وأقرّت Anthropic بأنها تحقق في الأمر كأولوية قصوى (The Register، 31 مارس 2026). إذا تكرّر، حدّث إلى أحدث إصدار، وقِس عبر /usage، وقدّم /feedback عند الحاجة. لتوفير الرموز بشكل منهجي، راجع توفير رموز الذكاء الاصطناعي وتوفير الرموز في Claude Code. ولفهم آلية "usage limit reached" (نافذة الـ5 ساعات والنافذة الأسبوعية) وما العمل عند بلوغ الحد، راجع بالتفصيل المقال المخصص حول usage limit reached.
4. السياق والرموز (Tokens)
يظهر هذا عندما تتعامل مع اجتماعات طويلة أو ملفات ضخمة.
| العرَض | السبب | الحل |
|---|---|---|
| Prompt is too long | تجاوز المحادثة + الملفات لنافذة السياق | /compact (تلخيص)، /clear (إعادة ضبط)، /context لرؤية التفصيل، عطّل MCP غير المستخدم عبر /mcp |
| Error during compaction: Conversation too long | مساحة حرّة غير كافية لمخرجات التلخيص | اضغط Esc مرتين للتراجع بضعة أدوار، ثم /compact. إذا استمر التعثّر، /clear |
| Autocompact is thrashing | مخرجات ضخمة تملأ السياق مجدداً مباشرة بعد التلخيص | اقرأ الملفات الكبيرة حسب نطاق الأسطر / /compact keep only <focus> / انقلها إلى وكيل فرعي |
الحيلة هي ألّا تقرأ ملفاً ضخماً بأكمله أبداً. مرّر السجلات والبيانات في أجزاء صغيرة بنطاق أسطر. واستيعاب فكرة نافذة السياق يجعل هذا الصنف من الأخطاء أندر بكثير. ولمعرفة الأسباب التفصيلية وطرق معالجة خطأ Prompt is too long (نافذة 200K مقابل 1M، والاستعانة بالوكلاء الفرعيين)، راجع المقال المخصص.
5. الخادم والنموذج
| العرَض | السبب | الحل |
|---|---|---|
| 500 Internal server error | عطل مؤقت من جانب Anthropic | تحقّق من status.claude.com ← أعد المحاولة بعد دقيقة |
| 529 Overloaded (repeated) | وصول الـAPI إلى السعة مؤقتاً | انتظر بضع دقائق. بدّل النموذج عبر /model لتوزيع الحِمل |
| Request timed out | لا استجابة خلال الـ10 دقائق الافتراضية | قسّم المهمة. على خط بطيء، ارفع API_TIMEOUT_MS |
| There's an issue with the selected model / Model '…' not found | اسم نموذج خاطئ أو غير متوفّر في خطتك | /model لإعادة الاختيار. تحقّق من متغيّر بيئة ANTHROPIC_MODEL قديم |
| Claude Opus is not available with the Claude Pro plan | النموذج المختار غير متوفّر في خطتك | /model إلى نموذج متاح. بعد تغيير الخطة، /logout←/login |
لمعرفة لماذا تُعد 529 Overloaded / 500 مشاكل من جانب الخادم ولا تستهلك حصتك، وكيف تعمل إعادة المحاولة التلقائية (حتى 10 مرات)، والفرق بينها وبين 429، راجع 529 Overloaded / 500: الأسباب والحلول.
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 |
| عدة تثبيتات لـ Claude Code (عدم تطابق الإصدارات، سلوك غير متوقع) | نسخ مكرّرة من native وnpm وHomebrew وWinGet وغيرها | تحقّق عبر which -a claude (في Windows: where.exe claude) وأبقِ واحدة فقط؛ ويُوصى بالتثبيت الأصلي في ~/.local/bin/claude. مثلاً npm uninstall -g @anthropic-ai/claude-code |
| علل من إصدار قديم | عدم التحديث | claude update (الحل الأول الذي يعالج كثيراً من العلل) |
| تطبيق سطح المكتب يعرض "Can't open this app" | تسجيل حزمة MSIX بشكل ناقص أثناء التحديث (Windows) | أنهِ العمليات العاملة في الخلفية ثم استخدم "إصلاح" من الإعدادات. الشرح التفصيلي |
أسباب خطأ command not found: claude وطرق إصلاحه (PATH، وتعارض التثبيتات المتعددة، وصلاحيات npm، وفخ استخدام الـ shell الخاطئة في Windows) مشروحة بالتفصيل في كيفية إصلاح خطأ "command not found" في التثبيت وPATH.
7. الشبكة والوكيل (Proxy)
شائع على شبكات الشركات وVPN. تأكّد أولاً من إمكانية الوصول عبر curl -I https://api.anthropic.com.
| العرَض | السبب | الحل |
|---|---|---|
| Unable to connect to API / Connection refused … (ECONNREFUSED) | عدم اتصال / حجب 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 واسمح للنطاق المستهدف |
| Connection lost mid-response (قبل الإصدار v2.1.227 كانت: Connection closed mid-response) | اتصل وبدأ البث، ثم انقطع الاتصال | المخرجات الجزئية تبقى، فردّ بـ continue. وإن تكرّر فافحص claude --version وحدِّث |
لمعالجة أعمق تشمل إعداد الـ proxy وشهادات TLS (NODE_EXTRA_CA_CERTS) ونطاقات الـ allowlist ولماذا يُعدّ NODE_TLS_REJECT_UNAUTHORIZED=0 خطيراً، راجع أسباب أخطاء الاتصال والـ proxy وطرق إصلاحها. أما Connection lost mid-response (اسمها السابق Connection closed mid-response) فمشكلة أخرى تقع بعد وصول الطلب؛ ويجمع مقال أسباب انقطاع الرد في منتصفه وحلوله خطوات العزل وما أصلحته كل نسخة.
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 | لا يكتمل بدء التشغيل خلال MCP_TIMEOUT (الافتراضي 30 ثانية) | ارفعه بالمللي ثانية، مثل MCP_TIMEOUT=60000 claude. أما "timeout" في .mcp.json فهو حد تنفيذ كل أداة، لا مهلة بدء التشغيل |
للاطلاع على معالجة مفصّلة حسب حالة اتصال MCP —failed وneeds authentication وpending— (بما في ذلك تغليف npx بـ cmd /c على Windows)، راجع كيفية إصلاح أخطاء اتصال MCP.
9. الأذونات والأدوات
عائلة "طُلب الإذن حتى في وضع التجاوز (bypass)". نقطتان جوهريتان: الوثائق الرسمية تحدّد الإجراءات التي تطلب التأكيد حتى في وضع التجاوز، وقواعد المنع تحظر التنفيذ في كل الأوضاع، بما فيها التجاوز (قواعد السماح لا أثر لها في وضع التجاوز؛ راجع Choose a permission mode في الوثائق الرسمية).
| العرَض | السبب | الحل |
|---|---|---|
| طُلب الإذن حتى في وضع التجاوز | قواعد ask الصريحة، والأدوات التي تحتاج إلى تفاعل المستخدم مثل AskUserQuestion، وrm / rmdir على مسار حرج مثل الجذر أو المجلد الرئيسي أو مجلد العمل (ما تسمّيه الوثائق circuit breaker) تطلب التأكيد حتى في وضع التجاوز. أما الكتابة في المسارات المحمية مثل .git و.claude فلا تطلبه في وضع التجاوز | تحقّق من قواعد ask واضبطها في /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. - court / يظهر وسم <invoke> خام ولا تُنفَّذ الأداة: علّة معروفة يُولَّد فيها وسم التحكّم باستدعاء الأداة بشكل معطوب. إذا فشل مرتين فابدأ جلسة جديدة (/clear). التفاصيل: شرح خطأ تسرّب وسم court / invoke.
- Could not check the pull request status: مشكلة اتصال بـGitHub (غالباً مصادقة
gh). ابدأ بـgh auth status. التفاصيل: خطأ حالة PR. - Image was too large / PDF too large: الصور التي تتجاوز 8000 بكسل على الحافة الطويلة (2000 بكسل عند وجود صور كثيرة في السياق)، وملفات PDF التي تتجاوز 100 صفحة / 20 ميغابايت تُرفض. اضغط 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 للتحقّق من قواعد ask (حذف مسار حرج يطلب التأكيد حتى في وضع التجاوز) |
| تريد فقط إصلاحه | claude update (الإصدار الأحدث يصلح الكثير) |
الخلاصة
لدى Claude Code أخطاء كثيرة، لكن الخطوة الأولى هي عزل السبب بثلاثة أوامر: claude doctor / /status / /context — وهذا يُعيد معظم المشكلات إلى الحركة. والشائعة منها أربع عائلات — الاستهلاك/حدود المعدل، تجاوز السياق، انتهاء المصادقة، فشل اتصال MCP — مع /usage و/compact و/login و/mcp كحلول الخط الأول.
والخطوة الأقوى التي يسهل إغفالها هي إبقاؤه محدّثاً عبر claude update. يتحدّث Claude Code بسرعة، والعلل السابقة (مثل thinking-blocks 400) غالباً ما تختفي بمجرد رفع الإصدار. "عند التعثّر، أوامر التشخيص الثلاثة أولاً؛ وإن لم يُصلَح، حدّث إلى الأحدث." التزِم بهذا النمط، وستتوقّف عن إذابة الوقت في الأخطاء.
وإذا لم تكن المشكلة خطأً، بل شعورك بأنّ السلوك ثقيل أو بطيء أكثر من اللازم، فإنّ مراجعة إعداد الجهد (effort) في Claude Code تتيح لك ضبط التوازن بين عمق التفكير واستهلاك الرموز. قراءات ذات صلة: خطأ thinking blocks 400، خطأ التحقّق من حالة PR، توفير الرموز في Claude Code، لماذا يطلب الإذن في وضع التجاوز، ما هو MCP، وThe model returned no content — الأسباب والحل.
الأسئلة الشائعة
س. ظهر خطأ — ماذا أفعل أولاً؟
ج. شغّل claude doctor. يفحص التثبيت والإعدادات وMCP والسياق دفعة واحدة. ثم انظر إلى /status (المصادقة الحالية) و/context (ما الذي يستهلك السياق)، وعادةً يمكنك تمييز ما إذا كانت المشكلة في المصادقة أو السياق أو الاتصال.
س. أبلغ حدود المعدل بسرعة. ما الذي يساعد؟
ج. يحمل كل دور في Claude Code محتوى الملفات واستدعاءات الأدوات، وتشير الوثائق الرسمية إلى أن جلسة تصحيح واحدة قد تستهلك أكثر من يوم كامل من الدردشة، لذا تبلغها أسرع مما هو متوقّع. تحقّق من الحدود ووقت إعادة الضبط عبر /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.
