الوضع Headless في Claude Code: -p والـ CI وإضافة GitHub Action
اسكربت Claude Code كأداة Unix: مطالبات بضربة واحدة عبر claude -p، وملفات تُضخ عبر الأنبوب، وJSON يُحلَّل، وجلسات تُستأنف بمعرّفها، و--bare للـ CI، وإضافة @claude على GitHub تبني ميزات من issue — مستقيمة من جولة Anthropic نفسها.
TL;DR
- claude -p "prompt" تشتغل ضربة واحدة وتطبع النتيجة — بلا جلسة تفاعلية. وتتألف كأداة Unix أي: ضخ مدخل، وضخ مخرج، وتسلسل في السكربتات وخطوات الـ CI.
- --output-format json تعيد النتيجة مع session_id والتكاليف والبيانات الوصفية؛ وstream-json تُصدر أحداثًا مفصولة بأسطر للمستهلكين الآنيين. حلّلها بـ jq وابنِ عليها.
- يشتغل الوضع headless بلا أذونات تعديل أو إتلاف افتراضيًا. امنح ما يلزم بالضبط عبر --allowedTools "Bash(git diff *),Edit" — صياغة قواعد الأذونات، ومطابقة بالبادئة.
- إضافة @claude على GitHub هي الوضع headless بواجهة: أشِر إلى @claude في issue أو PR فتقرأ الكود وتنشئ PR وإيداعات، وتجيب عن الأسئلة وتراجع الكود — على runners GitHub الخاصة بك.
Building headless automation with Claude Code | Code w/ Claude
القناة: Anthropic20:59
Headless mode — official documentation
الوثائق الرسمية: code.claude.com/docs
Claude Code GitHub Action — official docs
الوثائق الرسمية: code.claude.com/docs
الرايات والحدود والسلوكيات في هذه الصفحة موثقة من وثائق الوضع headless الرسمية؛ والمحاضرة أعلاه هي جولة Anthropic نفسها والمصدر البصري للقطات.
تُنسب لقطات الشاشة إلى صانعيها بروابط مباشرة إلى الطوابع الزمنية الدقيقة. لا تُستخدم لقطات المتحدث أو الجمهور.
شغّل Claude Code بلا واجهة، خطوة بخطوة
الجزء 1 — أساسيات الوضع headless
- 1
ما هو الوضع headless
الوضع headless هو Claude Code بلا الواجهة التفاعلية: الوكيل نفسه بقيادة برمجية. يقدّمه Anthropic بوصفه لبنة بسيطة للتطبيقات الوكيلة — استخدمه كأداة Unix في السكربتات والأنابيب، ولأتمتة الـ CI، وللبيئات البعيدة، أو كمحرّك خلف واجهة محادثة ويب.
صياغة Anthropic ذاتها: الـ SDK وصول برمجي إلى Claude Code في البيئات headless.شاهد عند 2:10 - 2
مطالبات بضربة واحدة عبر claude -p
الراية -p (أو --print) تشغّل مطالبة واحدة وتخرج: claude -p "Write me a function that calculates the Fibonacci sequence". لا شيء يبقى مفتوحًا — تحصل على المخرج في stdout ورمز خروج يمكن لسكربتاتك فحصه. اقرنها بـ --allowedTools لمنح صلاحية الكتابة مقدمًا.
سؤال بضربة واحدة: تُنشئ claude -p دالة فيبوناتشي وتخرج — بلا TUI وبلا متابعة.شاهد عند 3:30 - 3
اضخّ الملفات مباشرة في Claude
يعمل stdin كأي أداة CLI: cat app.log | claude -p "summarize the most common error logs". في عرض Anthropic تدخل 2000 سطر سجل ويخرج ملخص أخطاء بلغة سليمة — والحيلة نفسها تنفع لإخفاقات البناء وآثار التكدس والتصديرات. ويُسقف stdin المضخوع عند 10 ميغابايت.
cat مع رمز الأنبوب مع claude -p: ألفا سطرا سجل يصيران تشخيصًا من ثلاث جمل.شاهد عند 3:55 - 4
فكّ شفرة المخرجات التي تكره قراءتها
النمط نفسه يحوّل المخرجات العدائية إلى إجابات: ifconfig | claude -p "what interfaces do I have configured? don't include lo". كل ما يطبعه أمر — حالة الشبكة، وأخطاء المصرّف، وخطط terraform — يمكن تمريره عبر Claude لملخص بشري.
ifconfig مضخوعة عبر claude -p: كل واجهة مشروحة، والـ loopback مستثناة بطلب.شاهد عند 4:15 - 5
احصل على JSON مهيكل
أضف --output-format json فيصير الرد كائنًا قابلًا للتحليل: نص النتيجة، وsession_id، والمدة، وtotal_cost_usd. وللمستهلكين الأحياء تُصدر --output-format stream-json أحداثًا مفصولة بأسطر لحظة حدوثها — آخر سطر هو النتيجة النهائية.
وضع JSON: كتلة واحدة فيها النتيجة ومعرّف جلسة يمكن استئنافه لاحقًا وتكلفة التشغيل.شاهد عند 4:35
الجزء 2 — اسكربت كمهندس
- 6
امنح الأدوات بعمد
يبدأ الوضع headless بلا أذونات تعديل أو إتلاف. وتُقرّ --allowedTools سلفًا بما تحتاجه المهمة، بصياغة قواعد الأذونات: --allowedTools "Bash(npm run build),Bash(npm test:*),Write". ويمكن إدراج أدوات MCP في قائمة السماح بالطريقة نفسها — امنح أضيق مجموعة تُنجز العمل.
الغوص في الـ SDK: أذونات الأدوات وأوضاع المخرجات المهيكلة ومطالبات النظام المخصصة في شريحة واحدة.شاهد عند 11:00 - 7
أبقِ السياق عبر التشغيلات
يعيد وضع JSON session_id — مرّرها راجعة بـ --resume "$session_id" لتواصل حالة المحادثة نفسها من تشغيل لاحق أو عملية أخرى. هكذا تبنين منتجات تفاعلية فوق ذلك: المستخدم يقول شيئًا، ويرد Claude، وتحفظ أنت الجلسة للدورة التالية.
- 8
أدِر الأذونات بلا إنسان
إن لم تستطع توقع الأدوات التي سيحتاجها Claude، فتُسند --permission-prompt-tool قرارات الموافقة إلى خادم MCP وقت التشغيل — تسأل الأداة خدمتك (أو مستخدمك عبر تطبيقك) عن السماح لكل إجراء، بدل أن تسرد كل شيء مقدمًا.
- 9
انتقل إلى --bare للـ CI
تتخطى --bare الاكتشاف التلقائي للـ hooks وskills والأوامر المخصصة والوكلاء الفرعيين والإضافات وخوادم MCP وCLAUDE.md لأسرع إقلاع ممكن — موصى بها للسكربتات والـ CI، ومعدَّة أن تصير افتراض -p. وتتطلب ANTHROPIC_API_KEY وتأخذ السياق صراحة عبر الرايات.
الجزء 3 — إضافة @claude على GitHub
- 10
تعرّف على إضافة @claude على GitHub
إضافة GitHub هي الوضع headless بواجهة مبنية على الـ SDK. أشِر إلى @claude في أي PR أو issue فيمكنها قراءة كودك وإنشاء PR وإلحاق إيداعات بالموجودة والإجابة عن الأسئلة ومراجعة التغييرات — وهي تعمل على runners GitHub القائمة لديك، فلا بنية تحتية تُدار.
عقد الإضافة: أشِر إلى @claude، ووصف ما تحتاجه، فتعمل على المستودع في مسرّعاتك أنت.شاهد عند 17:10 - 11
أسند issue إلى Claude
في العرض الحي من Anthropic، جعل تعليق «@claude please implement this feature and comment on it» البوت يرد بخطة محدودة النطاق — نقاط عمّا سيبنيه — قبل إنشاء الفرع والإيداعات وطلب السحب، كل ذلك قابل للتتبع في سجلات الإضافة.
تعليق @claude على issue حقيقي: يرد Claude بخطة محدودة قبل أن يلمس أي كود.شاهد عند 7:50 - 12
ثبّتها على مستودعك
النتيجة ملخص تنفيذ بخانات مُعلَّمة على الـ issue — ميزات أُضيفت ومهام أُغلقت. وللوصول إلى ذلك، افتح Claude Code في مستودعك وشغّل /install-github-action: يفتح تدفق تفاعلي PR بملف workflow بصيغة YAML، ثم اضبط مفاتيح API بوصفها أسرارًا للمستودع وادمج.
التشغيل المكتمل: ملخص تنفيذ بخانات مُعلَّمة بكل ميزة أضافتها الإضافة إلى تطبيق العرض التجريبي.شاهد عند 13:30
Headless مقابل التفاعلي مقابل الـ SDK مقابل إضافة GitHub Action
أربع طرق لقيادة الوكيل نفسه — اختر بحسب من (أو ما) يسأل:
- 1الـ CLI التفاعلية — جلسة الـ TUI: نوافذ أذونات، ووضع الخطة، و/commands. الأفضل لإنسان يقود مهمة الآن.
- 2Headless عبر claude -p — ضربة برمجية واحدة: مدخل ومخرج معياريان، ورموز خروج، بلا واجهة. الأفضل للسكربتات ومهام cron والأسئلة السريعة من أدوات أخرى.
- 3الـ Agent SDK — القوة headless نفسها كمكتبة مُنمّطة: جلسات متعددة الأدوار، وأدوات مخصصة، وبث. الأفضل حين يكون Claude مكوّنًا داخل تطبيقك.
- 4إضافة @claude على GitHub — وضع headless على نموذج أحداث GitHub: issues وPR ومراجعات على runners الخاصة بك أنت. الأفضل للأتمتة المحصورة في المستودع التي يستطيع الفريق كله إطلاقها.
- 5--bare headless — إقلاع مجرد للـ CI: بلا CLAUDE.md ولا hooks ولا skills ولا إضافات ولا اكتشاف تلقائي لـ MCP، وسياق صريح عبر الرايات، وأسرع بدء بارد.
تتشارك الوصول إلى النموذج نفسه ونظام الأذونات نفسه — قاعدة إذن ممنوحة للوضع headless تسري في كل مكان، ولهذا يهم الانضباط في --allowedTools.
الوضع headless يتخبط؟ الإسعافات الأولى
خمس عقبات خاصة بالوضع headless وإصلاح كل واحدة:
- 1السكربت يخرج قبل أن يفرغ Claude. افحص رمز الخروج: 0 نجاح، وكل ما عداه فشل. وSIGTERM يخرج برمز 143 ويترك الدورة ناقصة — أنهِ التشغيلات بـ SIGINT أو بـ interrupt() من الـ SDK إن اضطررت للتوقف في منتصف دورة.
- 2المدخل المضخوع اقتُطع بصمت. يُسقف stdin عند 10 ميغابايت — اكتب الحمولات الأكبر في ملف وأشِر إلى المسار في المطالبة بدل ذلك.
- 3«--bg rejected» أو خطأ --cloud. الرايات التفاعلية وحدها لا تنطبق على -p: تُرفض --bg جملة واحدة، و--cloud تحتاج معرّف جلسة لتصفي رسالة لا وصف مهمة.
- 4تشغيل الـ CI يتجاهل CLAUDE.md وhooks لديك. تلك هي --bare في عملها: تتخطى الاكتشاف التلقائي. مرّر السياق صراحة عبر --settings و--mcp-config و--agents أو --plugin-dir.
- 5مهام bash في الخلفية تموت في منتصف الطريق. تُقتل الخلفيات بعد نحو 5 ثوانٍ من هبوط النتيجة؛ ويُبقي الوكلاء الفرعيين والسير العمل العملية حية حتى سقف خمول 10 دقائق. انتظرها صراحة في الـ CI.
لكل ما عدا ذلك، أضف --verbose واقرأ أحداث stream-json — system/init تسمّي النموذج والأدوات وخوادم MCP التي حُمّلت فعلًا.