خطافات Claude Code لا تعمل على Windows: الأسباب والحلول

الخطاف نفسه الذي يعمل جيدًا على Mac لا يفعل شيئًا على Windows، أو ما هو أسوأ، يحظر كل أمر. السبب في الغالب الأعم هو الـ shell. إليك كيف يشغّل Claude Code الخطافات على Windows وكيف تجعل خطافاتك موثوقة.

بقلم Aslan، فريق Pet Island · آخر تحديث 26 أكتوبر 2026 · مدة القراءة: 5 دقيقة

الإجابة المختصرة

على Windows يشغّل Claude Code قيمة command في الخطاف باستخدام Git Bash، أو باستخدام PowerShell إذا لم يكن Git Bash مثبتًا. حدّد ما تقصده باستخدام "shell": "powershell" أو "shell": "bash"، واجعل stdout كائن JSON واحدًا فقط (دون مخرجات echo من ملف التعريف)، واستخدم رمز الخروج 2 للحظر، وحدّث Claude Code (أُصلحت عدة أخطاء في خطافات Windows في الإصدارات حتى 2.1.310). استكشف الأخطاء باستخدام /hooks وclaude --debug.

أي shell يشغّل خطافك

يمرّر Claude Code سلسلة command إلى shell: ‏sh -c على macOS وLinux، وGit Bash على Windows، أو PowerShell إذا لم يكن Git Bash مثبتًا. هذه الجملة الواحدة من مرجع الخطافات تفسّر معظم بلاغات «يعمل على جهاز Mac الخاص بي». الأمر المكتوب لـ PowerShell يفشل في Git Bash، وسكربت bash يفشل في PowerShell، وأيهما تحصل عليه يعتمد على ما إذا كان Git for Windows مثبتًا مصادفةً.

تخلّص من التخمين باستخدام الحقل shell. يقبل القيمة "bash" أو "powershell":

%USERPROFILE%\.claude\settings.jsonنسخ

{

"hooks": {

"Notification": [

{

"matcher": "permission_prompt",

"hooks": [

{

"type": "command",

"shell": "powershell",

"command": "[Console]::Beep(880, 200)"

}

]

}

]

}

إذا كنت تريد Git Bash ولم يتمكن Claude Code من العثور عليه، فثبّت Git for Windows أو اضبط CLAUDE_CODE_GIT_BASH_PATH على موقعه، ثم ابدأ جلسة جديدة.

الأعراض وأسبابها

ما تراه	السبب المرجّح	الحل
يبدو أن الخطاف لا يعمل أبدًا	إصدار قديم من Claude Code، أو حدث أو مطابِق (matcher) خاطئ، أو JSON غير صالح في الإعدادات	حدّث؛ وتحقق من `/hooks`؛ واحذف التعليقات والفواصل الزائدة في النهاية
`ParserError` أو «unexpected token»	صيغة PowerShell تصل إلى Git Bash، أو العكس	اضبط `shell` صراحةً
مخرجات الخطاف «does not start with {»	شيء طُبع قبل JSON، وغالبًا يكون ملف تعريف الـ shell	أسكت مخرجات ملف التعريف؛ وأرسل السجلات إلى stderr
مسار يخلط بين `\` و`/` لا يمكن العثور عليه	متغير مسار Windows مدموج مع لاحقة بأسلوب Unix	استخدم صيغة exec: البرنامج في `command`، وكل وسيطة في `args`
`powershell: Permission denied` من Git Bash	أُبلغ عنه بشكل متقطع في 2.1.283 و2.1.304 إلى 2.1.305 (#103910، مفتوحة)	استخدم `"shell": "powershell"` حتى لا يكون Git Bash وسيطًا
خطاف الحماية يسمح بمرور كل شيء	رمز الخروج 1 بدلًا من 2، أو خطأ في الإصدارات الأقدم يجعله يسمح بالمرور عند الفشل (fail-open)	اخرج بالرمز 2 للحظر؛ وحدّث إلى 2.1.310 أو أحدث
يعود الخطاف فورًا دون أي مخرجات	برنامج من النظام الفرعي للواجهة الرسومية (GUI) لا ينتظره الـ shell	استخدم برنامج وحدة تحكم (console)، أو انتظر انتهاء العملية

JSON فقط على stdout

يقرأ Claude Code المخرجات القياسية لخطافك على أنها إجابته. القاعدة في الوثائق قصيرة: لا تطبع على stdout شيئًا سوى كائن JSON. على Windows تنكسر هذه القاعدة بطريقة خفية: لا يزال Git Bash وبعض الإعدادات يحمّلان ملف تعريف الـ shell، وأي echo غير مشروط في ذلك الملف يُضاف قبل JSON الخاص بك. عندها «يعمل» الخطاف في الطرفية ويفشل داخل Claude Code.

اكتب السجلات في ملف أو في stderr بدلًا من ذلك، واجعل مخرجات ملف التعريف مشروطة بأن يكون الـ shell تفاعليًا.

رموز الخروج: 2 يحظر، و1 لا يحظر

الخروج بالرمز 0 يعني النجاح. والخروج بالرمز 2 خطأ حاظر: في الأحداث القابلة للحظر يوقف Claude Code الإجراء ويعرض stderr الخاص بك. الخروج بالرمز 1 دون JSON صالح خطأ غير حاظر، ويستمر الإجراء. إذا كان خطافك يفرض سياسة، فاستخدم رمز الخروج 2.

لا يمكن حظر كل الأحداث بهذه الطريقة. رمز خروج خطاف Notification يُتجاهل. وخطاف Stop الذي يخرج بالرمز 2 يُبقي Claude يعمل. أما خطاف PermissionRequest فيتجاهل رمز الخروج 2 تمامًا، ويقرر عبر كائن decision في JSON الخاص به.

أصلح Claude Code 2.1.309 مشكلة عدم حظر خطافات PowerShell عندما يخرج برنامج الخطاف بالرمز 2. إذا بدا أن خطاف الحماية في PowerShell متجاهَل، فتحقق من إصدارك أولًا.

إصلاحات Windows التي تستحق التحديث من أجلها

يحتوي سجل تغييرات Anthropic على عدد كبير من إصلاحات خطافات Windows. وهذه هي الإصلاحات التي تفسّر نقاشات المنتديات القديمة:

الإصدار	الإصلاح
2.1.47	كانت خطافات PreToolUse وPostToolUse تفشل بصمت على Windows؛ أصبحت تعمل الآن باستخدام Git Bash بدلًا من cmd.exe
2.1.161	الخطافات التي تستدعي bash صراحةً (`/usr/bin/bash script.sh`) كانت تفشل مع «command not found»
2.1.299	كانت خطافات PreToolUse وPermissionRequest التي لم يُضبط لها shell تسمح بالمرور عند الفشل (fail-open) دون Git for Windows؛ أصبح خطاف الحماية الفاشل يحظر الآن
2.1.309	لم تكن خطافات PowerShell تحظر عند رمز الخروج 2؛ وكانت خطافات الحماية ذات `"shell": "powershell"` تسمح بالمرور عند الفشل دون Git for Windows
2.1.310	كانت خطافات الحماية التي يتكون أمرها من سلاسل بين علامات اقتباس فقط (مثل مسار بين علامتي اقتباس) تسمح بالمرور عند الفشل دون Git Bash

المشكلة الأقدم بعنوان «No hook is working on Windows» ‏(#10450) أُبلغ عنها على الإصدار 2.0.27؛ وتتبّعها أحد المعلّقين إلى أن stdin لم يكن يصل إلى أوامر الخطافات. إذا كنت تستخدم إصدارًا بهذا القدم، فحدّثه قبل استكشاف أي شيء آخر.

استدعاء برنامج مباشرة

إذا كان خطافك برنامجًا مُصرَّفًا، فيمكنك تخطي الـ shell باستخدام صيغة exec (الحقل args؛ ويُتجاهل shell عند ضبط args). على Windows تتطلب صيغة exec أن يشير command إلى ملف تنفيذي حقيقي مثل .exe؛ أما ملفات .cmd و.bat الوسيطة (بما فيها معظم ما يثبّته npm) فلا يمكن تشغيلها دون shell. أشِر إلى ملف .exe، أو استخدم صيغة shell.

درس تعلّمناه من بناء أداة الخطافات المساعدة الخاصة بنا: على Windows، البرنامج المبني للنظام الفرعي للواجهة الرسومية لا يُنتظر عندما يشغّله shell. يعود الـ shell فورًا، ويقرأ الوكيل مخرجات فارغة، فيبدو الخطاف معطّلًا. يجب أن تكون برامج الخطافات برامج وحدة تحكم (console).

خطافات الإضافات والمسارات

تعطّلت خطافات الإضافات التي تبني مسارات مثل ${CLAUDE_PLUGIN_ROOT}/hooks/run.sh على Windows بين v2.1.2 وv2.1.12 ‏(#18610): يتوسع المتغير إلى مسار بشرطات مائلة عكسية، وإضافة لاحقة بشرطة مائلة أمامية تعطي مسارًا مختلطًا لا يستطيع bash حلّه. تقدم الوثائق الحالية الحل النظيف: استخدم صيغة exec كلما أشار الخطاف إلى عنصر نائب لمسار. ضع البرنامج في command وكل وسيطة في args، مثل "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js"]. يُمرَّر كل عنصر كوسيطة واحدة، دون shell يشوّهه.

قائمة التحقق لاستكشاف الأخطاء

/hooks يفتح قائمة للقراءة فقط بكل خطاف مُهيأ ومصدره.
claude --debug (أو /debug أثناء الجلسة) يعرض كل تشغيل لخطاف ومخرجاته ورمز خروجه. ويكتب claude --debug-file <path> ذلك في ملف.
تحقق من صحة JSON. ملفات الإعدادات بصيغة JSON صارمة؛ وفاصلة زائدة واحدة في النهاية تعطّل الملف بأكمله.
تحقق من المطابِق (matcher). المطابِقات حساسة لحالة الأحرف؛ و"*" أو "" أو عدم وجود مطابِق يطابق كل شيء.
شغّل الأمر بنفسك في الـ shell نفسه الذي سيستخدمه Claude Code، مع تمرير JSON تجريبي إليه.
انتبه إلى المهلة. المهلة الافتراضية لخطافات الأوامر 600 ثانية؛ والخطاف الذي ينتظر شخصًا يحتاج إلى هذا الهامش.

لإيقاف كل الخطافات أثناء التحقيق، اضبط "disableAllHooks": true.

إذا كنت تريد الإشعارات والموافقات فقط

كثير من إعدادات الخطافات على Windows موجودة لسبب واحد: معرفة متى يحتاجك Claude Code والرد عليه. يفعل Pet Island ذلك دون أي سكربتات. يتصل بـ Claude Code بنقرة واحدة، ويتولى تفاصيل Windows نيابةً عنك، ويضع كل طلب إذن وسؤال وخطة في جزيرة صغيرة أعلى الشاشة، مع الأمر أو الفروقات (diff)، حيث تسمح به أو ترفضه. ويعمل أيضًا عندما يعمل Claude Code داخل WSL.

الأسئلة الشائعة

أي shell يشغّل خطافات Claude Code على Windows؟

Git Bash، أو PowerShell إذا لم يكن Git Bash مثبتًا. اضبط "shell": "powershell" أو "shell": "bash" في الخطاف لتختار صراحةً.

لماذا يعمل خطاف Claude Code في الطرفية ولا يعمل في Claude Code؟

السبب عادةً مخرجات إضافية: ملف تعريف shell يطبع نصًا يُضاف قبل JSON الخاص بالخطاف. لا تطبع على stdout سوى كائن JSON.

كيف أجعل خطافًا يحظر استدعاء أداة؟

اخرج بالرمز 2 (أو أعد قرار رفض في JSON). رمز الخروج 1 خطأ غير حاظر ويستمر الإجراء. خطافات PermissionRequest تتجاهل رمز الخروج 2 وتستخدم كائن decision بدلًا منه.

هل يمكن أن يكون أمر الخطاف ملف .cmd أو .bat؟

ليس في صيغة exec. على Windows يجب أن يشير إلى ملف تنفيذي حقيقي مثل .exe. استخدم صيغة shell لتشغيل ملفات .cmd أو .bat.

كيف أعرف سبب فشل خطاف؟

شغّل claude --debug أو اكتب /debug، واستخدم /hooks لمعرفة الخطافات المحمّلة.

المصادر

راجعنا كل إعداد وسلوك في هذه الصفحة مقابل هذه الصفحات بتاريخ 26 أكتوبر 2026. الوكلاء يتغيرون بسرعة؛ فإذا لم يعد شيء مطابقًا، فالمرجع هو الصفحة الرسمية.

تابع القراءة

Claude Code