استكشاف الأخطاء وإصلاحها (FAQ / Troubleshooting)
📚 تنقل السلسلة: المقال السابق 50 الأنماط المضادة: الاستخدامات الخاطئة الشائعة تناول الاستخدامات التي «تبدو صحيحة ولكنها في الواقع توقعك في الفخ». هذا المقال يستكمل الحديث عن استكشاف الأخطاء — عندما يواجه Claude Code مشكلة حقيقية، كيف تتبع الأدلة خطوة بخطوة للوصول إلى السبب الجذري. تعذر التثبيت، تعذر تسجيل الدخول، حظر الصلاحيات، عدم اتصال خوادم MCP، بطء التشغيل، أو ظهور خطأ باللون الأحمر... يقدم لك هذا المقال خريطة «الأعراض ← أين تبحث وماذا تكتب» لحل المشاكل.
لنبدأ بسيناريو نموذجي للغاية، ويسهل الوقوع فيه بشدة، وبفهمه ستدرك ما يهدف هذا المقال إلى حله.
تخيل هذا الموقف: قمت للتو بالانتقال إلى جهاز Mac جديد، وقمت بتثبيت Claude Code من مشروع الشركة، وبمجرد تشغيله ظهرت رسالة This organization has been disabled. رد فعلك الأول غالبًا سيكون «لقد انتهى الأمر، هل تم حظر حسابي؟»، فتسرع إلى تسجيل الدخول في claude.ai للتحقق من الاشتراك — كل شيء على ما يرام، واشتراك Max لا يزال نشطًا. ثم تشك في الشبكة، فتستخدم أداة لتخطي الحجب (VPN) وتحاول مجددًا، لكن تظهر نفس الرسالة. تظل تتخبط هكذا لما يقارب الأربعين دقيقة، وأعدت تثبيت Claude Code مرتين، وكدت تفتح تذكرة دعم فني.
وما هو السبب الجذري في النهاية؟ عندما تم نقل الإعدادات من جهاز Mac القديم، كان هناك سطر في ملف ~/.zshrc نسيته منذ زمن طويل وهو export ANTHROPIC_API_KEY=...، متبقي من مشروع شركة قديم تم إلغاؤه منذ نصف عام. أولوية متغيرات البيئة تفوقت على تسجيل دخول الاشتراك، فقام Claude Code بكل أمانة باستخدام ذلك المفتاح الملغى للتحقق، فتم إخباره بشكل طبيعي بـ «تم تعطيل هذه المؤسسة». تشغيل سطر واحد وهو unset ANTHROPIC_API_KEY أصلح المشكلة في ثوانٍ.
ذكرت هذا المثال لأجعلك تتذكر شيئًا واحدًا: أسوأ ما في استكشاف الأخطاء هو «الاعتماد على التخمين». الأربعون دقيقة ضاعت بالكامل في التخمين — تخمين الحساب، تخمين الشبكة، وكلما زاد التخمين ابتعدت عن الحقيقة. في الواقع، يحتوي Claude Code نفسه على أداة فحص، وأمر واحد وهو /status يمكنه إخبارك بـ «أي وسيلة تحقق يتم استخدامها حاليًا»، دون الحاجة للتخمين إطلاقًا. هذا المقال سيعلمك كيف تتبع مسارًا واضحًا خاليًا من التخمين لحصار المشكلة وحلها.
بعد قراءة هذا المقال، ستحصل على:
- جدول توجيه شامل «الأعراض ← أين تبحث»: طابق الخطأ أولاً، ولا تبدأ في التجربة العشوائية
- أمرين للمساعدة الذاتية يجب تشغيلهما أولاً —
/doctorللفحص، و/feedbackللإبلاغ — ومتى تستخدم كل منهما - جدول مطابقة «المشكلة ← الحل» مصنفًا إلى ست فئات رئيسية (التثبيت، تسجيل الدخول والتحقق، الصلاحيات، MCP، الأداء، رسائل الأخطاء)
- كيفية استخدام مفاتيح تصحيح الأخطاء من عائلة
--debug، بالإضافة إلى السلاح السري المسمى «طريقة مقارنة الإعدادات النظيفة» - تمرين عملي يوضح المخرجات المتوقعة: استخدام
/doctorبنفسك لإجراء فحص شامل لعملية التثبيت لديك
01排查的第一原则：先定位「这是哪一类问题」，别瞎试
先给结论，这条原则比后面所有具体命令都重要：遇到问题，第一步不是动手修，是先搞清楚「它属于哪一类」——是装的问题、登录的问题、配置的问题，还是 API 那头的问题。 类别定错，后面全白忙。
تشبيه: تعذر فتح صفحة الويب، حدد أولاً ما إذا كان الموقع معطلاً أم أنك غير متصل بالإنترنت. إذا كان الموقع معطلاً، فلن يفيدك تحديث الصفحة مائة مرة، وعليك الانتظار؛ أما إذا كنت غير متصل، فعليك التحقق من جهاز التوجيه (router) الخاص بك. ينطبق نفس المنطق على أخطاء API — حدد أولاً من المتسبب في الخطأ، ثم قرر ما إذا كان يجب «الانتظار» أم «التعديل».
لماذا هذه الفئة هي الأكثر أهمية؟ لأن مستندات Claude Code الرسمية مقسمة بالفعل حسب الفئة — صفحة للتثبيت وتجيل الدخول، صفحة لأخطاء التشغيل، صفحة للإعدادات وتصحيح الأخطاء، وصفحة للأداء. إذا لم تكن متأكدًا من فئة مشكلتك، فلن تعرف أي صفحة تتصفحها في المستندات. تقدم صفحة استكشاف الأخطاء الرسمية جدول توجيه في بدايتها، وقمنا بنقله ليتناسب مع المشاكل التي قد تواجهها:
| الأعراض التي تراها | أي فئة هذه / راجع أي مقال |
|---|---|
command not found: claude、تعذر التثبيت、مشكلة في PATH、أو EACCES | فئة التثبيت (لمزيد من التفاصيل راجع المقال 02 + القسم 02 في هذا المقال) |
طلب تسجيل الدخول بشكل متكرر、403 Forbidden、أو organization disabled | فئة تسجيل الدخول والتحقق (القسم 03 في هذا المقال) |
| عدم تفعيل الإعدادات、عدم تشغيل hooks、عدم تحميل خادم MCP、أو عدم عمل قواعد الصلاحيات | فئة الإعدادات (القسم 04 في هذا المقال + تصحيح أخطاء إعداداتك) |
أخطاء API مثل API Error: 5xx、529 Overloaded、أو 429 | فئة أخطاء API (القسم 06 في هذا المقال، وغالبًا ليس خطأك) |
model not found أو you may not have access to it | فئة الأخطاء (القسم 06 في هذا المقال، اختيار نموذج خاطئ أو غياب الصلاحيات) |
| البطء、استهلاك عالٍ لـ CPU / الذاكرة、أو عدم العثور على الملفات أثناء البحث | فئة الأداء (القسم 05 في هذا المقال) |
طريقة الاستخدام بسيطة للغاية: ابحث في العمود الأيمن عن العبارة الأكثر شبهًا بالتي تظهر على شاشتك، وسيوضح لك العمود الأيسر الاتجاه الذي يجب اتباعه. وسنفصل كل فئة في الأقسام التالية من هذا المقال.
هنا اقتباس من الوثائق الرسمية يستحق الحفظ: «إذا لم تكن متأكدًا مما ينطبق عليك، فيرجى تشغيل
/doctorداخل Claude Code للتحقق تلقائيًا من التثبيت والإعدادات وخوادم MCP واستخدام السياق. وإذا تعذر تشغيلclaudeعلى الإطلاق، فقم بتشغيلclaude doctorمن سطر الأوامر (shell).»
وبعبارة أخرى — لا تستطيع تحديد الفئة؟ لا تقلق، قم بتشغيل /doctor أولاً، وسيتولى تحديد النطاق الأكبر لك. وسنفرد القسم التالي لشرح هذين الأمرين المساعدين.
💡 الخلاصة في جملة واحدة: الخطوة الأولى في الاستكشاف هي دائمًا التصنيف والابتعاد عن المحاولات العشوائية — طابق الأعراض بالجدول لمعرفة الفئة، ثم انتقل للقسم المقابل؛ وإذا تعذر التصنيف ابدأ بـ
/doctor.
02 أمرين للمساعدة الذاتية: /doctor للفحص، و/feedback للإبلاغ
قبل أن تتصفح أي مستندات أو تسأل أي شخص، يوفر لك Claude Code خيارين للمساعدة الذاتية. تسعون بالمائة من المشاكل إما أن يوضحها لك /doctor مباشرة، أو يتم الإبلاغ عنها باستخدام /feedback إذا تعذر حلها. اتقان هذين الأمرين سيوفر لك الكثير من الوقت.
تشبيه: إذا شعرت بوعكة صحية، اذهب لإجراء فحص شامل أولاً. لن تخضع لعملية جراحية بمجرد شعورك بالألم، بل ستجري فحصًا طبيًا أولاً — ضغط الدم، نبضات القلب، والمؤشرات المختلفة، وبنظرة سريعة على التقرير سيعرف الطبيب أين تكمن المشكلة تقريبًا. أمر /doctor هو جهاز فحص Claude Code: أمر واحد للتحقق من صحة التثبيت، وجود أخطاء صياغة في الإعدادات، اتصال خوادم MCP، ومقدار السياق المستهلك، كل ذلك دفعة واحدة.
/doctor：一键体检
أمر /doctor هو أول أمر يجب كتابته عند استكشاف الأخطاء. تفحص هذه الأداة أشياء تم سردها بوضوح في الوثائق الرسمية — حالة صحة التثبيت، صلاحية الإعدادات (وجود مفاتيح غير صالحة أو أخطاء في المخطط schema)، إعدادات MCP، واستخدام السياق.
الأمر يعتمد على إمكانية تشغيل الأداة:
- إذا كنت تستطيع الدخول إلى الجلسة: اكتب
/doctorمباشرة داخل Claude. - إذا تعذر تشغيل
claudeعلى الإطلاق (مثل خطأcommand not foundأو الانهيار عند البدء): اكتبclaude doctorفي سطر الأوامر (shell) — لاحظ عدم وجود الشرطة المائلة، فهو أمر مستقل في سطر الأوامر.
يحتوي /doctor على ميزة مفيدة: عند اكتشاف مشكلة، يمكنك الضغط على f لإرسال تقرير التشخيص مباشرة إلى Claude، ليساعدك في حله خطوة بخطوة. هذا يشبه قراءة الطبيب لتقرير الفحص بجانبك بعد الانتهاء منه.
/feedback：实在搞不定，上报
إذا قمت بمراجعة المستندات وتشغيل /doctor وظلت المشكلة قائمة — لا تحاول حلها بمفردك دون جدوى، بل استخدم /feedback للإبلاغ عنها إلى Anthropic. سيقوم بإرسال سجل المحادثة مع الوصف، وهذه هي أسرع طريقة للتشخيص الرسمي للمشاكل الحقيقية (خاصة المشاكل الغامضة مثل «تراجع جودة الاستجابة فجأة» دون وجود رسالة خطأ). يوفر هذا الأمر أيضًا خيارًا: مساعدتك في فتح issue على GitHub بمحتوى ممتلئ مسبقًا. ملاحظة: إذا كنت تستخدم موفرين خارجيين مثل Bedrock أو Vertex، فلن يقوم /feedback إرسال المعلومات إلى Anthropic، بل سيحفظها في ملف محلي، ويتعين عليك إرسالها يدويًا إلى ممثل حساب Anthropic الخاص بك.
ربما سمعت عن أمر /bug سابقًا — وهو مجرد التسمية القديمة لـ «الإبلاغ عن المشاكل». الآن قامت الوثائق الرسمية بتوحيد التسمية لتصبح /feedback: لإرسال السجل والوصف إلى Anthropic داخل الجلسة، أو فتح تذكرة GitHub issue ممتلئة مسبقًا. تذكر /feedback فقط فهو كافٍ.
إليك جدولاً يلخص الخيارات الأولى للتشغيل:
| موقفك | اكتب هذا أولاً | ماذا يفعل |
|---|---|---|
| لست متأكدًا من فئة المشكلة | /doctor | فحص شامل لمرة واحدة لتحديد الاتجاه العام |
تعذر تشغيل claude على الإطلاق | claude doctor (في سطر الأوامر) | تشخيص يمكن تشغيله قبل بدء الأداة |
أظهر /doctor مشكلة وتريد من Claude مساعدتك في حلها | اضغط على f في نتائج /doctor | إرسال تقرير التشخيص إلى Claude |
| لم تنجح الحلول المقترحة في المستندات | /feedback | إرسال السجل والوصف إلى Anthropic |
| تريد معرفة ما إذا كانت الخدمات الرسمية معطلة | افتح status.claude.com في المتصفح | التحقق من وجود أعطال في واجهة برمجة التطبيقات (API) |
تذكر دائمًا موقع status.claude.com: عند ظهور العديد من أخطاء الخادم مثل 5xx أو 529، فإن الخطوة الأولى هي مراجعة صفحة الحالة للتأكد، بدلاً من الشك في إعداداتك الخاصة — ففي كثير من الأحيان يكون الخلل من جهة Anthropic ولا علاقة له بإعداداتك على الإطلاق. وسنفصل هذا في القسم 06.
💡 الخلاصة في جملة واحدة: قبل البدء، جرب أمرين للمساعدة الذاتية —
/doctor(أوclaude doctorفي الطرفية) للفحص وتحديد الاتجاه، و/feedbackللإبلاغ عند الاستعصاء؛ وعند الشك في تعطل الخوادم راجع موقعstatus.claude.com.
03 فئة تسجيل الدخول والتحقق: طلب تسجيل الدخول بشكل متكرر، أو تعطيل المؤسسة
بدءًا من هذا القسم، سنمر على المشاكل التفصيلية حسب الفئة. لنبدأ بـ تسجيل الدخول والتحقق — هذه الفئة هي الأسهل لإثارة ذعر المبتدئين، لأن كلمات الأخطاء تبدو مخيفة للغاية (مثل disabled وForbidden وrevoked)، لكن الحقيقة غالبًا ما تكون بسيطة للغاية.
تشبيه: تمرير بطاقة الدخول عند بوابة الشركة، عدم فتح البوابة لا يعني بالضرورة أنه تم فصلك. قد تكون البطاقة قد فقدت مغناطيسيتها، أو ربما تحمل بطاقة قديمة خاطئة، أو قد يكون وقت نظام البوابة غير مضبوط. رسالة الخطأ «تم رفض الدخول» لا تعني «أنك لا تملك الصلاحية». مشكلة التحقق مماثلة تمامًا — تحقق أولاً من «أي وسيلة تحقق يستخدمها Claude Code للتحقق»، ولا تفكر في الأسوأ مباشرة.
第一招：看清「当前用的是哪套凭证」
هذه هي الخطوة الأولى الشاملة لمشاكل التحقق، وهي العلاج لتجنب إضاعة الأربعين دقيقة المذكورة في البداية. اكتب في الجلسة:
/statusالمتوقع: سيعرض طريقة التحقق النشطة حاليًا — سواء كانت اشتراكك (تسجيل الدخول عبر OAuth) أو مفتاح API key معين. إذا كنت مشتركًا بالفعل ولكن يظهر هنا أنه يتم استخدام API key، فقد تم تحديد المشكلة تقريبًا.
最经典的坑：ANTHROPIC_API_KEY 偷偷压过订阅
هذا هو الفخ الذي وقعنا فيه في البداية. توضح الوثائق الرسمية هذه الآلية بوضوح:
تتمتع متغيرات البيئة بالأولوية على
/login، لذلك سيتم استخدام المفتاح المصدر في ملف تكوين shell أو المحمل من ملف.env، حتى لو كان لديك اشتراك Pro أو Max صالح. في الوضع غير التفاعلي (-p)، يتم دائمًا استخدام المفتاح عند وجوده.
لذلك، بمجرد وجود متغير ANTHROPIC_API_KEY في بيئتك (حتى لو كان متبقيًا من مشروع قبل بضعة أشهر ونسيته تمامًا)، سيستخدمه Claude Code للتحقق. وإذا كان هذا المفتاح منتهي الصلاحية أو ينتمي لمؤسسة معطلة، فستظهر رسالة This organization has been disabled. الحل:
unset ANTHROPIC_API_KEY
claudeولكن أمر unset يعمل فقط على نافذة الطرفية (terminal) الحالية، ولحل المشكلة جذريًا، يجب الانتقال إلى ملف ~/.zshrc أو ~/.bashrc أو ~/.profile وحذف السطر export ANTHROPIC_API_KEY=... (على نظام Windows، تحقق من ملف تكوين PowerShell المسمى $PROFILE ومتغيرات بيئة المستخدم). بعد الحذف أعد تشغيل claude واكتب /status للتأكد من العودة إلى الاشتراك. لقد تم شرح «أولويات وسائل التحقق» هذه في [المقال 04] (تكوين API)، تذكر مراجعتها عند حدوث مشاكل في التحقق.
إليك كيفية التعامل مع أخطاء التحقق الأخرى:
| الخطأ | ماذا يعني | كيف يتم إصلاحه |
|---|---|---|
Not logged in · Please run /login | لا توجد وسيلة تحقق صالحة في هذه الجلسة | اكتب /login لتسجيل الدخول؛ وإذا كنت تعتمد على التحقق عبر متغيرات البيئة، تأكد من تصدير ANTHROPIC_API_KEY بالفعل |
OAuth token revoked / has expired | انتهت صلاحية تسجيل الدخول المحفوظ | اكتب /login لإعادة تسجيل الدخول؛ وإذا تكرر الخطأ في نفس الجلسة، استخدم /logout أولاً ثم /login |
| طلب تسجيل الدخول بشكل متكرر (عبر عمليات تشغيل متعددة) | مفتاح التحقق ينتهي باستمرار | تحقق من دقة ساعة النظام (يعتمد التحقق من المفتاح على الطابع الزمني الصحيح)；على نظام macOS قد يحدث هذا عند قفل Keychain، قم بتشغيل claude doctor للتحقق من الوصول إلى Keychain |
403 Forbidden (بعد تسجيل الدخول) | مشكلة في الاشتراك / الدور / الوكيل | لمستخدمي Pro/Max، انتقل إلى claude.ai/settings للتحقق من الاشتراك؛ ولمستخدمي Console تأكد من امتلاك دور Claude Code أو Developer |
Invalid API key | تم رفض المفتاح | تحقق من الهجاء وتأكد من عدم إلغاء المفتاح في Console؛ اكتب env | grep ANTHROPIC لمعرفة ما إذا كان ملف .env قد قام بتحميل مفتاح منتهي الصلاحية |
نصيحة «التحقق من ساعة النظام عند تكرار طلب تسجيل الدخول» سهلة الإغفال للغاية — فعلى البيئات الافتراضية غير المتصلة بالإنترنت لفترة طويلة، قد يفشل تسجيل الدخول باستمرار، ويتبين في النهاية أن وقت النظام متأخر ببضعة أيام، مما يجعل المفتاح غير صالح فور إصداره. ضبط الوقت يحل المشكلة مباشرة.
💡 الخلاصة في جملة واحدة: عند مشاكل التحقق اكتب
/statusلمعرفة وسيلة التحقق المستخدمة؛ وانتبه للفخ المتمثل في تغلب مفتاحANTHROPIC_API_KEYفي shell على الاشتراك (unsetوحذف سطر التصدير)؛ وعند تكرار تسجيل الدخول تحقق من ساعة النظام ووصول Keychain على macOS.
04 فئة الإعدادات: عدم تفعيل الإعدادات / hooks / MCP
الفئة الثانية هي عدم تفعيل الإعدادات — على الرغم من كتابة القواعد، وإعداد hooks، وإضافة خوادم MCP server في ملف settings.json، إلا أن Claude يبدو كأنه لا يراها. تفرد الوثائق الرسمية صفحة خاصة لهذه المشاكل تسمى «تصحيح أخطاء إعداداتك»، وتلخص الفكرة الأساسية في جملة واحدة: تحقق أولاً من «ما قام Claude Code بتحميله فعليًا»، ولا تفترض أن ما كتبته قد تم تفعيله تلقائيًا.
تشبيه: تسليم الواجب لا يعني بالضرورة أن المعلم قد استلمه. قد تضع الواجب على الطاولة وتذهب، وعدم تفعيله قد يرجع لوضعه على الطاولة الخاطئة، أو تداخله مع دفاتر الآخرين، أو تغطيته بنسخة أخرى. ينطبق نفس المنطق على الإعدادات — عند عدم التفعيل، ابحث أولاً عن «أي نسخة تم قراءتها فعليًا»، بدلاً من تعديل النسخة التي تعتقد أنها صحيحة تكرارًا.
一组「查实际加载了啥」的命令
هذه هي الأدوات الأساسية لفئة الإعدادات، واستخدم الأمر المقابل حسب المشكلة:
| الأمر | ماذا يفحص |
|---|---|
/context | معرفة من يستهلك السياق في الجلسة الحالية (توجيهات النظام، الملفات في الذاكرة، skills، أدوات MCP، الرسائل) |
/memory | معرفة ملفات CLAUDE.md وقواعدها التي تم تحميلها |
/skills | معرفة الـ skills المتاحة من المشروع / المستخدم / الإضافات |
/agents | معرفة الوكلاء الفرعيين وإعداداتهم المحددة |
/hooks | معرفة الـ hooks المسجلة في الجلسة الحالية |
/mcp | معرفة خوادم MCP server المتصلة وحالتها |
/permissions | معرفة قواعد السماح / الرفض المفعلة حاليًا |
/debug [وصف المشكلة] | تفعيل سجلات تصحيح الأخطاء للجلسة الحالية، وتوجيه Claude لمساعدتك في التشخيص باستخدام السجلات ومسارات الإعدادات |
/status | معرفة مصادر الإعدادات النشطة (بما في ذلك تفعيل الإعدادات المدارة) |
طريقة الاستخدام هي «كتابة الأمر المقابل للشيء الذي أعددته للتأكد من وجوده عند عدم تفعيله». على سبيل المثال، إذا كتبت hook ولم يتم تشغيله، اكتب أولاً /hooks لمعرفة ما إذا كان مسجلاً — إذا لم يظهر، فهذا يعني أنه لم يُقرأ على الإطلاق؛ وإذا ظهر ولم يتم تشغيله، فالخلل يكمن في المطبق (matcher).
几个新手最常踩的配置坑
إليك الفخاخ الأكثر تكرارًا للمبتدئين في الإعدادات وطرق حلها:
| الأعراض | السبب المحتمل غالبًا | كيف يتم الإصلاح |
|---|---|---|
| عدم تشغيل hook على الإطلاق | كتابة اسم الأداة في matcher بأحرف صغيرة (مثل "bash") | أسماء الأدوات تحسس لحالة الأحرف وتبدأ بحرف كبير: Bash، Edit、Write、Read |
| 与其不触发 | كتابة hook في ملف مستقل | يجب وضع hooks الخاصة بالمشروع / المستخدم تحت المفتاح "hooks" في ملف settings.json |
تجاهل قيم ملف settings.json | تم إعداد نفس المفتاح في ملف settings.local.json | يتفوق ملف settings.local.json على settings.json، وكلاهما يتفوقان على ~/.claude/settings.json (راجع المقال 31) |
عدم تحميل خادم MCP المحدد في .mcp.json | تم وضع الملف داخل دليل .claude/ | يجب وضع إعدادات MCP الخاصة بالمشروع في الدليل الرئيسي للمستودع باسم .mcp.json وليس داخل دليل .claude/ |
| عدم ظهور خادم MCP الخاص بالمشروع | تم إيقاف نافذة الموافقة لمرة واحدة | تتطلب خوادم المشروع موافقة، اكتب /mcp للتحقق من الحالة والموافقة عليها (راجع المقال 22) |
عدم تفعيل توجيهات CLAUDE.md في الدليل الفرعي | يتم تحميلها «عند الطلب» | يتم تحميلها فقط عندما يقرأ Claude ملفات ذلك الدليل باستخدام أداة Read، وليس عند بدء الجلسة (راجع المقال 18) |
الفخ المتمثل في «حالة الأحرف لـ matcher في hook» هو الأسهل للوقوع فيه: عند كتابة PostToolUse hook لأول مرة، قمت بوضع "edit|write" في matcher، ولم يتم تشغيله مهما عدلت الملفات. يظهر في /hooks أنه مسجل بالفعل، وتنظر للإعدادات طويلاً دون اكتشاف أي خلل — وفي النهاية تدرك أن أسماء الأدوات يجب أن تبدأ بأحرف كبيرة لتصبح "Edit|Write". تنص الوثائق الرسمية بوضوح: «المطابقة تحسس لحالة الأحرف.» هذا النوع من الفخاخ يصعب كشفه إذا كنت لا تعرفه، وبمجرد معرفته تحل المشكلة في ثانية واحدة.
权限相关：「明明配了规则，怎么还是拦不住 / 老来问我」
مشاكل الصلاحيات (permission) تندرج أيضًا تحت فئة الإعدادات، ويواجه المبتدئون نوعين منها عادة:
الأول هو «فشل الحظر المكتوب في CLAUDE.md». المعرفة الأساسية هنا هي: العبارات المكتوبة في CLAUDE.md مثل «لا تقم بتعديل .env أبدًا» هي مجرد «رجاء» وليست «ضمانًا». توضح الوثائق الرسمية هذا الأمر بوضوح — لجعل Claude «يتخذ قرارًا جيدًا» استخدم CLAUDE.md، ولفرض قيود صارمة «تُنفذ بغض النظر عن قراره» يجب استخدام قواعد الصلاحيات أو hooks (لمزيد من التفاصيل راجع المقالين 20 و21). لذا إذا كنت تريد منع عملية معينة تمامًا، لا تعتمد على CLAUDE.md، بل اكتب قاعدة صلاحيات deny أو PreToolUse hook.
النوع الآخر وهو الأكثر خفاءً: كتابة قاعدة deny ولكنها تعجز عن منع الأوامر المكافئة لها. على سبيل المثال، إذا كتبت Bash(rm *) لمنع الحذف، فقد يستخدم Claude أمر /bin/rm أو find . -delete ويقوم بالحذف بنجاح. والسبب هو — تطابق قواعد البادئة (prefix rules) يعتمد على «سلسلة الأوامر الحرفية»، وليس على الملف التنفيذي الأساسي. الحل هو إضافة قواعد صريحة لكل متغير، أو استخدام PreToolUse hook / البيئة المعزولة (sandbox) للحصول على «ضمان صارم». عند استكشاف أخطاء الصلاحيات، اكتب أولاً /permissions للاطلاع على قواعد السماح / الرفض المفعلة حاليًا، ومطابقتها للتأكد من أنها النسخة الصحيحة.
هذا يعود بنا إلى نفس الفكرة الواردة في المقال 50 حول الأنماط المضادة: الاعتماد على اللغة الطبيعية لفرض «حدود الأمان» هو نمط مضاد في حد ذاته — فالتعليمات مرنة بطبيعتها، والقواعد وhooks هي الوحيدة الصارمة.
💡 الخلاصة في جملة واحدة: عند عدم تفعيل الإعدادات، استخدم أولاً الأوامر
/contextو/memoryو/hooksو/mcpو/permissionsللتحقق من «ما تم تحميله فعليًا»؛ والفخاخ الشائعة تشمل حالة أحرف أسماء الأدوات في hook، وتغطية الإعدادات بملفات ذات أولوية أعلى مثلsettings.local.json، ووضع.mcp.jsonفي مجلد خاطئ، وكتابة القواعد الصارمة في CLAUDE.md بدلاً من قواعدdeny.
05 فئة الأداء: البطء، استهلاك عالٍ للذاكرة، وعدم العثور على الملفات أثناء البحث
الفئة الثالثة هي الأداء غير المريح — الاستجابة تصبح أبطأ وأبطأ، استهلاك الذاكرة يزداد بشكل مخيف، وتعذر إكمال @file نهائيًا. تصنف الوثائق الرسمية هذه المشاكل تحت «الأداء والاستقرار»، وهي ترتبط في معظمها بـ «امتلاء السياق» ومشاكل البيئة الصغيرة، ونادرًا ما تكون بسبب أخطاء برمجية (bugs).
تشبيه: يصبح الكمبيوتر بطيئًا مع الاستخدام، وغالبًا ما يرجع ذلك لفتح الكثير من التطبيقات في الخلفية، وليس لععل في المكونات المادية. لن ترسل الكمبيوتر للإصلاح بمجرد حدوث بطء، بل ستغلق بعض البرامج التي تستهلك الذاكرة وتنظف ذاكرة التخزين المؤقت. ينطبق نفس المنطق على بطء Claude Code — نظف «طاولة العمل» أولاً، ولا تسرع في إعادة التثبيت.
卡顿 / 高内存：先收拾上下文
خطوات التعامل التي تقترحها الوثائق الرسمية عملية للغاية:
- استخدم أمر
/compactبشكل دوري لضغط السياق (تنظيم المحادثة في صفحة واحدة من النقاط الرئيسية، راجع المقال 19). - أغلق وأعد تشغيل Claude Code بين المهام الرئيسية.
- أضف أدلة البناء الكبيرة إلى ملف
.gitignoreلمنعه من فحصها.
إذا ظل استهلاك الذاكرة مرتفعًا بعد القيام بذلك، يمكنك تشغيل /heapdump — حيث يقوم بكتابة لقطة من ذاكرة JavaScript الذاكرة المؤقتة (heap snapshot) إلى ~/Desktop (على نظام Linux يتم كتابتها في الدليل الرئيسي لغياب سطح المكتب)، وقم بإرفاقها مع تذكرة GitHub issue عند الإبلاغ عن مشاكل الذاكرة. لن تحتاج لتشغيل هذا الأمر يوميًا، ويكفي معرفة وجوده فقط.
حول «التجمد التام وعدم الاستجابة»: تصيغ الوثائق الرسمية الحل ببساطة — اضغط أولاً على Ctrl+C لإلغاء العملية الحالية؛ وإذا لم تستجب الأداة إطلاقًا، أغلق الطرفية وأعد التشغيل. إعادة التشغيل لن تفقدك المحادثة، واكتب
claude --resumeفي نفس الدليل للاستمرار من حيث توقفت.
自动压缩「抖动」：一个新手会被吓到的报错
قد تواجه هذا السطر: Autocompact is thrashing: the context refilled to the limit.... لا تقلق — هذا يعني أن الضغط التلقائي قد نجح، ولكن وجود ملف ضخم أو مخرجات أداة قد ملأت السياق مجددًا على الفور، فتوقف Claude Code عن المحاولة لتجنب استهلاك نداءات API دون جدوى. طريقة الاستعادة: اطلب منه قراءة الملف الضخم في أجزاء (تحديد نطاق الأسطر أو دالة معينة، وتجنب قراءة الملف بالكامل)، أو حدد لـ /compact «الاحتفاظ بالخطة والـ diff فقط»، وإذا لم يفلح ذلك استخدم /clear للبدء من جديد.
搜索 / @file 补全失灵：换个 ripgrep
إذا تعذر على أداة البحث، أو إشارة @file، أو الـ skills المخصصة العثور على الملفات، فالسبب غالبًا هو أن أداة ripgrep المدمجة (أداة بحث سريعة للغاية) في Claude Code تعجز عن التشغيل على نظامك. الحل الرسمي هو تثبيت إصدار النظام من ripgrep وتوجيه Claude Code لاستخدامه:
# macOS
brew install ripgrepثم قم بإعداد المتغير USE_BUILTIN_RIPGREP=0 في متغيرات البيئة (لمزيد من التفاصيل حول إعداد متغيرات البيئة راجع المقال 42).
إليك جدولاً سريعًا للتعامل مع مشاكل الأداء:
| الأعراض | افعل هذا أولاً |
|---|---|
| بطء مستمر، استهلاك الذاكرة مرتفع | اكتب /compact ثم أعد تشغيل Claude Code |
| تجمد تام، الأداة لا تستجيب | اضغط على Ctrl+C؛ وإذا لم ينجح، أغلق الطرفية واكتب claude --resume للاستمرار |
ظهور خطأ Autocompact is thrashing | اطلب منه قراءة الملفات الضخمة في أجزاء + /compact keep only ... |
تعذر إكمال @file / فشل البحث في العثور على الملفات | ثبت ripgrep الخاص بالنظام، وقم بإعداد USE_BUILTIN_RIPGREP=0 |
| نصوص مشوشة أو مربعات في الطرفية المدمجة | تشغيل /terminal-setup داخل Claude لإيقاف تشغيل معالجة GPU |
النقطة الأخيرة المتعلقة بـ «شطب النصوص» قد تظهر أحيانًا في طرفية VS Code المدمجة، حيث تتشوه النصوص وتظهر كمربعات. تشغيل /terminal-setup لإيقاف تسريع GPU وإعادة تحميل النافذة كفيل بحل المشكلة — فالمشكلة فنية تتعلق بالرسوميات ولا شأن لـ Claude بها.
💡 الخلاصة في جملة واحدة: لمشاكل الأداء ابدأ بالشك في «امتلاء السياق» — أمر
/compactوإعادة التشغيل يمثلان الحل الشامل؛ وللتجمد اضغط Ctrl+C أو استخدمclaude --resume؛ ولفشل البحث ثبتripgrepللنظام؛ ولتشوه النصوص استخدم/terminal-setup.
06 فئة أخطاء API: ظهور رسالة باللون الأحمر، حدد أولاً «هل الخلل من جانبك أم لا»
الفئة الرابعة هي ظهور خطأ API Error: ... باللون الأحمر مباشرة في المحادثة. يصاب المبتدئون بالذعر عند رؤية اللون الأحمر، ولكن التصرف الصحيح هنا هو تحديد ما إذا كان الخطأ «من جهة الخادم» أم «من جهتك» — فأسلوب التعامل مع الحالتين مختلف تمامًا.
تشبيه: تعذر فتح صفحة الويب، حدد أولاً ما إذا كان الموقع معطلاً أم أنك غير متصل بالإنترنت. إذا كان الموقع معطلاً، فلن يفيدك تحديث الصفحة مائة مرة، وعليك الانتظار؛ أما إذا كنت غير متصل، فعليك التحقق من جهاز التوجيه (router) الخاص بك. ينطبق نفس المنطق على أخطاء API — حدد أولاً من المتسبب في الخطأ، ثم قرر ما إذا كان يجب «الانتظار» أم «التعديل».
先记住：Claude Code 早就帮你自动重试过了
هناك آلية رسمية تستحق المعرفة أولاً: عند حدوث أخطاء خادم، أو ضغط زائد، أو انتهاء الوقت، أو قيود مؤقتة، أو انقطاع الاتصال، يقوم Claude Code تلقائيًا بإعادة المحاولة بحد أقصى 10 مرات وبأوقات انتظار متزايدة، وستشاهد مؤقتًا بجانب علامة التحميل يوضح Retrying in Ns · attempt x/y. لذلك — عندما تشاهد رسالة الخطأ بالفعل، فهذا يعني أن جميع محاولات إعادة التشغيل قد استُنفدت بالكامل، وليس أنه استسلم فورًا.
三大类报错，三种应对
يمكن تقسيم أخطاء API الطويلة إلى ثلاث فئات رئيسية لتحديد طريقة التعامل:
| الخطأ | من المتسبب | ماذا يجب عليك فعله |
|---|---|---|
API Error: 500 / 529 Overloaded / Server is temporarily limiting requests | الخادم (ليس من جانبك) | انتظر قليلاً ثم حاول مجددًا؛ تحقق من صفحة الحالة status.claude.com；أو استخدم /model لتغيير النموذج (حيث يتم احتساب السعة لكل نموذج بشكل مستقل) |
You've hit your session/weekly/Opus limit | حصتك قد نفدت | انتظر وقت إعادة التعيين؛ اكتب /usage لمعرفة الاستهلاك؛ أو اكتب /usage-credits لإضافة رصيد أو ترقية الباقة |
Prompt is too long / Request too large | مدخلاتك كبيرة للغاية | استخدم /compact أو /clear؛ واطلب منه قراءة الملفات الضخمة في أجزاء بدلاً من لصق الملف بالكامل |
أسلوب التعامل مع هذه الحالات الثلاث مختلف تمامًا: الأولى تتطلب «الانتظار فقط»، والثانية تتطلب «الدفع أو انتظار إعادة التعيين»، والثالثة تتطلب «تقليص مدخلاتك». عدم التمييز بينها يؤدي إلى تصرفات خاطئة — مثل حذف محادثاتك بينما الخادم معطل، أو الاستمرار في المحاولة معتقدًا أنه خطأ برمجي بينما نفد رصيدك.
وهناك فئة أخرى وهي تعذر الاتصال بـ API (أخطاء مثل Unable to connect to API وfetch failed وRequest timed out مصحوبة بعبارة «تحقق من الشبكة») — وهذا لا يتعلق بـ Anthropic عادة، بل بـ شبكتك، أو VPN، أو الوكيل (proxy)键، أو جدار الحماية لديك. الخطوة الأولى هي التحقق من إمكانية الوصول إلى خادم API من نفس الطرفية:
curl -I https://api.anthropic.comإذا نجح الاتصال، فهذا يعني أن الشبكة سليمة، وأن المشكلة تقع في مستوى أعلى (مثل الوكيل أو الشهادات)؛ أما ظهور Could not resolve host أو انتهاء الوقت فيعني أن الشبكة محجوبة. غالبًا ما يتطلب هذا تشغيل VPN لتخطي الحجب؛ وخلف شبكات الشركات يجب إعداد HTTPS_PROXY. وإذا كانت الشبكة بطيئة وتؤدي لانتهاء الوقت باستمرار، يمكنك زيادة مهلة الطلب الواحد — حيث توفر الوثائق الرسمية خيارين للضبط (لمزيد من التفاصيل حول إعداد متغيرات البيئة راجع المقال 42):
| متغير البيئة | القيمة الافتراضية | الفائدة |
|---|---|---|
API_TIMEOUT_MS | 600000 (10 دقائق) | مهلة الطلب الواحد، قم بزيادتها عند بطء الشبكة أو استخدام الوكيل |
CLAUDE_CODE_MAX_RETRIES | 10 | عدد محاولات إعادة التشغيل التلقائي، قم بتقليلها عند الرغبة في الفشل السريع للبرمجيات |
两个新手高频、又容易误解的报错
model not found / you may not have access to it: لم يتم التعرف على اسم النموذج المكتوب، أو أن حسابك لا يملك الصلاحية للوصول إليه. اكتب /model أولاً في واجهة سطر الأوامر التفاعلية (CLI) لإعادة الاختيار من النماذج المتاحة. إذا استمر ظهور نموذج خاطئ، فهذا يعني أنه تم إعداد معرف نموذج منتهي الصلاحية في مكان ما — ابحث حسب الأولوية: علامة --model ← متغير البيئة ANTHROPIC_MODEL ← ملف settings.local.json ← حقل model في ملفات settings.json في جميع المستويات، وقم بحذف القيم منتهية الصلاحية للعودة إلى القيمة الافتراضية للحساب. تقترح الوثائق الرسمية نصيحة عملية: استخدم الأسماء المستعارة (مثل sonnet وopus) بدلاً من معرفات الإصدارات الثابتة، حيث تتبع الأسماء المستعارة أحدث إصدار تلقائيًا دون أن تصبح منتهية الصلاحية (لمزيد من التفاصيل حول طرق إعداد /model وANTHROPIC_MODEL راجع المقال 04 تكوين API).
Claude Code is unable to respond to this request, which appears to violate our Usage Policy: تم إيقاف الطلب بواسطة فحص سياسة الاستخدام. لاحظ نقطة غير بديهية — هذا الفحص يقيم المحادثة بأكملها، وليس جملتك الأخيرة فقط، لذا فإن تغيير الجملة وإرسالها مجددًا في نفس الجلسة قد يؤدي غالبًا لتفعيل نفس الرفض. التصرف الصحيح هو الضغط على مفتاح Esc مرتين أو استخدام /rewind للعودة إلى ما قبل الجولة التي فعلت الرفض (راجع المقال 37)، وتغيير الصياغة أو الفكرة؛ وإذا تعذر تحديد الجولة، استخدم /clear للبدء من جديد.
💡 الخلاصة في جملة واحدة: لأخطاء API صنفها لثلاث حالات — أخطاء
5xx/529تخص الخادم (الانتظار ومراجعة صفحة الحالة وتغيير النموذج)، وحصص الاستهلاك تخص الاشتراك (الانتظار أو الدفع)، وحجم المدخلات يخصك (الضغط وقراءة الملفات في أجزاء)؛ وتعذر الاتصال يرجع للشبكة لديك (تحقق بـcurlوشغل VPN أو إعدادات الوكيل)؛ ولمشاكل النموذج استخدم الأسماء المستعارة وتخلص من المعرفات القديمة.
07 الأسلحة السرية: سجلات تصحيح الأخطاء --debug + طريقة مقارنة الإعدادات النظيفة
تغطي الفئات الست السابقة تسعين بالمائة من الحالات. ولكن في بعض الأحيان، تكون الأعراض غريبة ويتعذر تحديدها بالاعتماد على المستندات. في هذه الحالة، يمكن استخدام سلاحين متقدمين لإخراج أدق المشاكل وحلها.
تشبيه: فحص أعطال الكهرباء بالاعتماد على جهاز القياس (multimeter) + إزالة المقابس واحدًا تلو الآخر. عندما يواجه فني الكهرباء عطلاً غير واضح، فإنه أولاً يستخدم جهاز القياس لمعرفة الجزء الذي يفتقر للجهد المناسب (الاطلاع على السجلات الحية)، وثانيًا يقوم بفصل الأجهزة الكهربائية واحدًا تلو الآخر لمعرفة أي جهاز يتسبب في العطل عند فصله (الاستبعاد التدريجي). السلاحان السريان لاستكشاف أخطاء Claude Code هما محاكاة لهاتين الطريقتين تمامًا.
武器一：--debug 实时看它在干啥
عندما يتعذر تخمين السبب بناءً على النتائج فقط، ابدأ التشغيل مع علامة --debug لعرض العمليات الداخلية أمامك. يمكنك إضافة علامات فرعية للمشاكل المختلفة للتركيز على الأجزاء التي تهمك فقط:
| الأمر | الاستخدام |
|---|---|
claude --debug | سجلات تصحيح الأخطاء العامة، لمتابعة سير العمل الإجمالي |
claude --debug mcp | مخرجات stderr لتشغيل / اتصال خادم MCP (استخدمه عندما يظهر اتصال خادم MCP ولكن دون وجود أدوات) |
claude --debug hooks | متابعة أحداث hook في الوقت الفعلي، ومعرفة الـ matchers المطابقة، ورموز الخروج والمخرجات (استخدمه عند عدم تشغيل hook) |
وهناك أيضًا خيار داخل الجلسة وهو /debug [وصف المشكلة]: لتفعيل سجلات تصحيح الأخطاء للجلسة الحالية، وتوجيه Claude لمساعدتك في التشخيص بالاستعانة بالسجلات ومسارات الإعدادات.
مثال على الاستخدام: الـ hook الخاص بك مسجل بالفعل في /hooks ولكنه لا يعمل — ابدأ التشغيل باستخدام claude --debug hooks، وقم بتشغيل استدعاء الأداة، وسيوضح لك السجل بكل دقة «وصول الحدث، المطبق matcher الذي تم فحصه، وما إذا كان مطابقًا أم لا». هذا أفضل بمئات المرات من التحديق في الإعدادات دون جدوى.
武器二：干净配置对照法（最被低估的一招）
هذه الطريقة تستحق التذكر دائمًا، وهي مخصصة لحل القضايا الغامضة مثل «هل الخلل ناتج عن إعداداتي الشخصية أم لا». الفكرة هي: فتح جلسة نظيفة لا يتم فيها تحميل أي شيء ومقارنتها بجلساتك المعتادة — إذا اختفت المشكلة في الجلسة النظيفة، فهذا يعني أن الخلل يكمن في إعداداتك الشخصية. الأمر المقترح رسميًا:
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeيوجه هذا الأمر المتغير CLAUDE_CONFIG_DIR إلى دليل فارغ، لتجاوز كل ما هو موجود تحت ~/.claude؛ ويبدأ التشغيل من دليل لا يحتوي على مجلد .claude ولا ملف .mcp.json ولا ملف CLAUDE.md (مثل /tmp)، لتجاوز إعدادات المشروع أيضًا. وبذلك لا تحتوي هذه الجلسة على أي إعدادات مستخدم / مشروع، أو hooks، أو MCP، أو إضافات، أو ذاكرة.
- إذا اختفت المشكلة في الجلسة النظيفة ← فالسبب الجذري يكمن في مجلدك الحقيقي
~/.claudeأو مجلد المشروع.claude. الخطوة التالية هي إعادة العناصر واحدًا تلو الآخر (نسخ ملف واحد إلى الدليل، أو بدء التشغيل من مشروعك)، ومراقبة العنصر الذي يتسبب في تكرار المشكلة عند إعادته، وحينها ستحدد المتسبب. - إذا ظلت المشكلة قائمة في الجلسة النظيفة ← فالسبب الجذري يقع خارج إعدادات المستخدم والمشروع (قد يتعلق بالإعدادات المدارة، أو متغيرات البيئة، أو مشاكل التثبيت الأساسية).
هذا «الاستبعاد الثنائي» يمثل حكمة عامة لاستكشاف الأخطاء — تضييق النطاق من خلال «إلغاء نصف المتغيرات لمعرفة ما إذا كانت المشكلة قائمة أم لا». على سبيل المثال، إذا تعذر على Claude قراءة قاعدة معينة في CLAUDE.md دون سبب واضح، فإن الاستعانة بالجلسة النظيفة تمكنك من التأكد من أن «المشكلة ليست خطأً برمجيًا في Claude Code، بل تضارب بين توجيهين في ملفي CLAUDE.md في المشروع»، مما يوفر عليك قضاء ليلة كاملة في تصفح المستندات.
💡 الخلاصة في جملة واحدة: للمشاكل الغامضة استخدم سلاحين —
claude --debug [mcp/hooks]لعرض السجلات الحية وتحديد موضع العطل، وطريقة مقارنة الإعدادات النظيفة (توجيهCLAUDE_CONFIG_DIRإلى مجلد فارغ) لتحديد «هل المشكلة بسبب إعداداتي أم لا»، ثم أعد العناصر تدريجيًا لحصر المشكلة.
08 تمرين عملي: إجراء فحص كامل للتثبيت لديك
القراءة دون تطبيق لا تساعد على الحفظ. سنقوم الآن بتشغيل فحص /doctor بأنفسنا، والتحقق من حالة التحقق بطريقنا. لا يتطلب هذا التمرين أي بيئة معقدة، ويمكنك القيام به بمجرد تثبيت Claude Code.
الخطوة الأولى: التأكد من تثبيت claude بشكل صحيح وحداثة الإصدار في الطرفية
claude --versionالمتوقع: طباعة رقم الإصدار، مثل 2.1.xxx (Claude Code). رؤية رقم الإصدار تعني أن التثبيت سليم في الأساس. وإذا ظهر خطأ command not found: claude، فهذا يعني أن دليل التثبيت ليس مضافًا إلى PATH — هذه مشكلة تثبيت، ارجع إلى المقال 02 لإصلاح PATH حسب منصتك (على نظام macOS/Linux، يكون التثبيت المحلي في ~/.local/bin).
الخطوة الثانية: الدخول للجلسة وتشغيل الفحص
claudeبعد الدخول اكتب:
/doctorالمتوقع: ظهور لوحة تشخيص توضح حالة صحة التثبيت، صلاحية ملفات الإعدادات (حيث يتم تمييز المفاتيح غير الصالحة أو أخطاء المخطط schema باللون الأحمر)، إعدادات خادم MCP، واستخدام السياق. عدم وجود أخطاء في كل بند يعني أن إعداداتك نظيفة. وإذا تم تحديد مشكلة في أحد البنود، اضغط على f لإرسال هذا التقرير إلى Claude، ليساعدك في حلها خطوة بخطوة.
الخطوة الثالثة: التأكد من «أي وسيلة تحقق يتم استخدامها حاليًا»
ثم اكتب:
/statusالمتوقع: عرض طريقة التحقق النشطة حاليًا. إذا كنت مشتركًا، فيجب أن يظهر هنا الاشتراك (OAuth) وليس مفتاح API key معين. وإذا ظهر أنه يتم استخدام API key بما يخالف توقعاتك — تهانينا، لقد كشفت الفخ المذكور في البداية مبكرًا، انتقل إلى ملف تكوين shell واكتب unset ANTHROPIC_API_KEY واحذف سطر التصدير (export).
الخطوة الرابعة (اختياري): تجربة مقارنة الإعدادات النظيفة
لتجربة الطريقة المذكورة في القسم 07، افتح جلسة نظيفة لا يتم فيها تحميل أي شيء:
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeالمتوقع: بعد بدء التشغيل، لن تحتوي هذه الجلسة على أي من ملفات CLAUDE.md المعتادة، أو الأوامر المخصصة، أو خوادم MCP server (كتابة /memory أو /mcp بداخلها ستظهر أنها فارغة). هذا هو المعيار المرجعي لمقارنتك في المستقبل لتحديد «هل المشكلة ناتجة عن إعداداتي أم لا». ملاحظة: على أنظمة Linux / Windows، سيطلب منك تسجيل الدخول مجددًا (حيث تُخزن وسائل التحقق في دليل الإعدادات)، بينما على نظام macOS سيتم جلبها تلقائيًا لكونها مخزنة في Keychain. بعد الانتهاء، اخرج بشكل طبيعي، ولن يؤثر هذا الدليل المؤقت على مجلدك الحقيقي ~/.claude.
بإتمام هذه الخطوات الأربع، تكون قد مررت بالمسار الرئيسي لاستكشاف الأخطاء بنفسك: «الفحص ← الاطلاع على وسيلة التحقق ← فتح جلسة نظيفة للمقارنة». عند حدوث أي مشكلة في المستقبل، اتبع هذا الترتيب، فهو أفضل بكثير من المحاولات العشوائية المذعورة.
💡 الخلاصة في جملة واحدة: قم بتطبيق خطوات الفحص الأربع
claude --version←/doctor←/status← الجلسة النظيفة؛ وتذكر دائمًا «/doctorلتحديد الاتجاه، و/statusلمعرفة وسيلة التحقق»، فمعظم المشاكل تنكشف في هذه الخطوة.
09 ملخص
يقدم لك هذا المقال إطار عمل لاستكشاف الأخطاء «خالٍ من التخمين ويعتمد على مسار واضح» — بدءًا من «تصنيف المشكلة أولاً» إلى «الأمر المناسب كتابته»، ووصولاً للأدوات المتقدمة للمشاكل المستعصية.
دعنا نستعرض النقاط الأساسية معًا:
| موقفك | الخطوة المتبعة | النقاط الهامة |
|---|---|---|
| عدم معرفة فئة المشكلة | مطابقة جدول الأعراض + /doctor | صنف المشكلة أولاً قبل البدء، ولا تجرب عشوائيًا |
| طلب تسجيل الدخول بشكل متكرر / تعطيل المؤسسة | /status للتحقق من الوسيلة | غالبًا بسبب متبقيات ANTHROPIC_API_KEY التي تتغلب على الاشتراك |
| عدم تفعيل الإعدادات / hook / MCP | /context، /hooks، /mcp | تحقق من «ما تم تحميله فعليًا»؛ وانتبه لحالة الأحرف وتداخل الإعدادات |
| بطء / استهلاك عالٍ للذاكرة / فشل البحث | /compact + إعادة التشغيل / استبدال ripgrep | غالبًا بسبب امتلاء السياق أو مشكلة بسيطة في البيئة |
ظهور أخطاء API Error باللون الأحمر | تقسيم الأخطاء إلى «الخادم / الحصة / مدخلاتك» | خادم 5xx (راجع صفحة الحالة)، حصة limit (انتظر التصفير)، ومدخلات too long (الضغط) |
| تعذر تحديد المشكلة الغامضة | --debug + مقارنة الإعدادات النظيفة | مراجعة السجلات الحية + إلغاء نصف المتغيرات بالاستبعاد |
يجب أن تكون قادرًا الآن على: التعامل مع أي عطل في Claude Code دون ذعر — استخدم جدول الأعراض لتحديد فئة المشكلة أولاً، واكتب /doctor لتشخيص الاتجاه و/status لمعرفة وسيلة التحقق؛ وتعامل مع المشكلة بناءً على فئتها (التثبيت / التحقق / الإعدادات / الأداء / الأخطاء)；وعند الاستعصاء استخدم --debug لمراجعة السجلات أو طريقة مقارنة الإعدادات النظيفة لتحديد السبب؛ وإذا تعذر الحل أبلغ عنها باستخدام /feedback. تحويل هذه الخطوات إلى ذاكرة عضلية يرفعك من مرحلة «الارتباك عند الخطأ» إلى مرحلة «معرفة أين تبحث فور حدوث الخطأ».
إلى هنا، تكون قد مررت بالتطبيق العملي الكامل بدءًا من «التثبيت» إلى «الاستخدام السلس» ووصولاً إلى «كيفية الإنقاذ عند الأعطال». وما يتبقى هو تنظيم المصطلحات التي ظهرت في هذه الرحلة بوضوح تام.
المقال التالي 52 «مسرد المصطلحات (صديق للمبتدئين)» — خلال هذه القراءة، مرت عليك العشرات من المصطلحات مثل CLAUDE.md، ونافذة السياق، وMCP، وSubagent، وHook، ونقاط الفحص، وauto-compact... وتتداخل في ذهنك حاليًا. المقال التالي يقدم لك مسرد مصطلحات مبسط للغاية: شرح مبسط لكل مصطلح في جملة واحدة، مصحوبًا بالتشبيه الأكثر دقة، ومصنفة حسب الموضوع، لتكون متاحة للاطلاع السريع والفهم المباشر. فكر في الأمر: لو سألك أحدهم فجأة «ما هي العلاقة بين الـ token ونافذة السياق»، هل يمكنك شرحها بجملة واحدة الآن؟