يشغّل الوضع headless في Claude Code الوكيل بشكل غير تفاعلي: تمرّر العلم -p (أو --print) مع مطالبة، فيعمل Claude حتى الاكتمال، ويطبع النتيجة، ثم يخرج — لا REPL، ولا لوحة مفاتيح، ولا أحد ينتظر أمام الطرفية. هذا العلم الواحد يحوّل مساعد برمجة تفاعليًا إلى أداة سطر أوامر متوافقة مع Unix يمكنك أن تمرّر إليها عبر الأنابيب، أو تغلّفها في سكربت، أو تجدولها باستخدام cron، أو تدرجها في خط أنابيب CI/CD. يغطي هذا الدليل كيفية عمل الوضع headless في 2026، والأعلام التي تهمّ فعلًا، وكيفية الحصول على مخرجات JSON قابلة للتحليل، ومطبّات الصلاحيات والمصادقة التي تعطّل التشغيل غير المراقب بصمت، والدروس المستفادة من تشغيل خط أنابيب Claude Code في الوضع headless في بيئة الإنتاج.
ما هو الوضع headless في Claude Code؟
الوضع headless هو تشغيل Claude Code من دون واجهته الطرفية التفاعلية. أضف -p (اختصارًا لـ --print) إلى أي أمر claude، وبدلًا من فتح الـ REPL، يقرأ Claude المطالبة، وينفّذ حلقة الوكيل كاملة (قراءة الملفات، وتشغيل الأدوات، وتعديل الكود)، ثم يطبع النتيجة النهائية ويخرج برمز حالة. إنه نفس الوكيل الذي يشغّل Claude Code التفاعلي، لكن يقوده سكربت بدلًا من إنسان. اعتبارًا من 2026، تندرج هذه الميزة ضمن Agent SDK، الذي يُشحن أيضًا كحزم Python وTypeScript إن أردت callbacks وكائنات رسائل أصلية بدلًا من الاستدعاء عبر الصدفة.
claude -p "What does the auth module do?"
ولأن الوضع غير التفاعلي يقرأ من stdin، فإنه يتركّب مثل أي أداة CLI أخرى. يمكنك تمرير سجل بناء مباشرة إليه وإعادة توجيه الإجابة خارجًا:
cat build-error.txt | claude -p "concisely explain the root cause of this build error" > cause.txt
هذه القابلية للتركيب (stdin دخولًا، نص أو JSON خروجًا، ورمز خروج يمكنك التفريع بناءً عليه) هي السبب الكامل لوجود الوضع headless.
كيفية الحصول على مخرجات مُهيكلة قابلة للتحليل
النص العادي يكفي لإنسان يقرأ سجلًا، لكن الأتمتة تحتاج إلى بنية. يقبل العلم --output-format ثلاث قيم تحديدًا: text (الافتراضية)، وjson، وstream-json. صيغة json هي الحصان الأساسي: تعيد الإجابة إضافة إلى بيانات وصفية للجلسة في كائن واحد.
claude -p "Summarize this project" --output-format json | jq -r '.result'
تتضمن حمولة JSON الحقول result (النص)، وsession_id، وnum_turns، وis_error، وduration_ms، وبشكل حاسم لكل من يشغّل هذا على نطاق واسع، total_cost_usd، وهو رقم تكلفة لكل استدعاء كي تتابع الإنفاق دون فتح لوحة التحكم. وللحصول على إجابات قابلة للقراءة آليًا تتوافق مع شكل تحدّده أنت، اقرن --output-format json مع --json-schema '{...}'؛ فيعود الكائن الذي تم التحقق منه في حقل structured_output. استخدم stream-json مع --verbose عندما تريد عرض الرموز فور وصولها. حلّل أيًا منها باستخدام jq وستحصل على واجهة برمجية موثوقة.
الصلاحيات: الجزء الذي يعثر فيه الجميع
تسأل الجلسة التفاعلية قبل تشغيل أمر صدفة أو تعديل ملف. أما التشغيل headless فليس لديه من يسأله، لذا سيرفض الإجراء افتراضيًا وقد يعلّق خط أنابيبك. عليك منح الصلاحية مسبقًا. أنظف أداة هي --allowedTools، وهي قائمة سماح مفصولة بفواصل:
claude -p "Run the test suite and fix any failures" --allowedTools "Bash,Read,Edit"
لمزيد من التحكم الدقيق، يستخدم العلم صيغة قواعد الصلاحيات، فـ --allowedTools "Bash(git diff *)" تسمح فقط بالأوامر التي تبدأ بـ git diff. ولتحديد خط أساس للتشغيل بأكمله بدلًا من سرد الأدوات، مرّر --permission-mode: يتيح acceptEdits لـ Claude كتابة الملفات وتشغيل أوامر نظام الملفات الشائعة دون مطالبة، بينما يرفض dontAsk أي شيء لم يُسمح به صراحة، وهو الخيار الصحيح لمهمة CI محكمة الإغلاق. أما الأداة الفظّة، --dangerously-skip-permissions، فتوافق على كل شيء ويجب ألا تُستخدم إلا في صندوق رمل أو حاوية للاستعمال المؤقت، لا على جهاز فيه بيانات اعتماد أو وصول إلى الإنتاج أبدًا.
المصادقة: مفتاح API مقابل رمز OAuth
يحتاج التشغيل headless إلى بيانات اعتماد لا تتطلب تسجيل دخول عبر المتصفح، وهناك مساران صادقان. الأول هو ANTHROPIC_API_KEY، وهو مفتاح من Anthropic Console يُحاسب لكل رمز، وهو الملائم الطبيعي لمشغّلات CI والأتمتة بالدفع حسب الاستخدام. والثاني يتيح لك إعادة استخدام اشتراك قائم: شغّل claude setup-token مرة واحدة، وأكمل تدفق OAuth في المتصفح، فيطبع رمزًا صالحًا لسنة تصدّره باسم CLAUDE_CODE_OAUTH_TOKEN. هذا الرمز مرتبط بخطة Pro أو Max أو Team أو Enterprise ومقيّد بالاستدلال فقط. اختر حسب نموذج الفوترة: استخدام API المُقاس لأحمال CI المتقطعة، ورمز الاشتراك لوكيل ثابت يعمل دائمًا. تحذير واحد للاستدعاءات المكتوبة برمجيًا: يتجاوز الوضع --bare (الذي يتخطى الاكتشاف التلقائي للـ hooks والمهارات وخوادم MCP من أجل تشغيلات قابلة لإعادة الإنتاج) المصادقة عبر OAuth أيضًا، لذا في الوضع --bare يجب أن توفّر ANTHROPIC_API_KEY.
تشغيل Claude Code في CI/CD وعلى cron
بمجرد أن يعمل أمر واحد بشكل غير تفاعلي، تصبح جدولته من مهام DevOps المعتادة. مدخل cron يشغّل claude -p على VPS يحوّل الوكيل إلى مهمة تنطلق من تلقاء نفسها: فرز السجلات في الثانية صباحًا، أو صياغة سجل تغييرات، أو إصلاح lint وفق جدول. في خط الأنابيب، غلّف الاستدعاء في سكربت يمرّر diff عبر الأنبوب ويتفرّع بناءً على رمز الخروج؛ وتشحن Anthropic تكاملات GitHub Actions وGitLab CI/CD من الطرف الأول لهذا الغرض بالضبط. علمان يهمّان للموثوقية غير المراقبة. أضف --bare كي لا ترث التشغيلات بصمت أي hooks أو خوادم MCP قد تصادف وجودها في مجلد ~/.claude لدى زميل، فتحصل على النتيجة نفسها على كل جهاز. واستخدم --continue أو --resume <session_id> عندما تحتاج مهمة إلى عدة أدوار تبني على بعضها، ملتقطًا معرّف الجلسة من مخرجات JSON للاستدعاء الأول. وإن كنت تجهّز الجهاز بنفسك، فإن دليلنا حول استضافة تطبيقاتك ذاتيًا على VPS يغطي أساسيات cron والتحصين التي تُبقي وكيلًا مجدولًا في صحة جيدة.
| العلم | ما يفعله | متى تحتاجه |
|---|---|---|
-p / --print | تشغيل غير تفاعلي، طباعة النتيجة، ثم الخروج | كل تشغيل headless |
--output-format json | نتيجة مُهيكلة مع التكلفة وبيانات الجلسة الوصفية | أي مستدعٍ مكتوب برمجيًا |
--json-schema | فرض المخرجات ضمن مخطط (structured_output) | استخراج قابل للقراءة آليًا |
--allowedTools | الموافقة المسبقة على أدوات محددة | إيقاف تعليق التشغيل عند المطالبات |
--permission-mode | خط أساس على مستوى الجلسة (acceptEdits، dontAsk) | CI محكم الإغلاق |
--bare | تخطّي الاكتشاف التلقائي لتشغيلات قابلة لإعادة الإنتاج | استدعاءات CI وSDK |
--continue / --resume | محادثات متعددة الأدوار عبر الاستدعاءات | مهام ذات حالة |
ما تعلّمناه من تشغيل محرك محتوى headless
نستخدم Claude Code headless في الإنتاج بأنفسنا: خط الأنابيب الذي يبحث ويكتب وينشر المقالات هنا في TechRiseUps يعمل كمهمة claude -p مجدولة على بنيتنا التحتية الخاصة في WaseerHost، تقودها مهارة مخصصة بدلًا من شخص أمام لوحة المفاتيح. صمدت بعض الدروس التي لا تلمّح إليها الوثائق إلا تلميحًا.
الصلاحيات هي السبب الأول لتشغيل "عالق": مهمة تبدو معلّقة تكاد تكون دائمًا Claude ينتظر موافقة لن تأتي أبدًا، لذا وافق مسبقًا على كل أداة تحتاجها المهمة فعلًا ولا شيء أكثر. اقرأ total_cost_usd من JSON عند كل استدعاء وسجّله؛ فالوكلاء غير المراقبين ليس لديهم سقف تكلفة طبيعي، ورقم التكلفة لكل تشغيل هو الطريقة الرخيصة الوحيدة لضبط مهمة خرجت عن السيطرة. اجعل كل تشغيل idempotent، لأن مهمة cron ستنطلق مرتين في النهاية أو تستأنف في المنتصف، والوكيل الذي يُلحق بشكل أعمى يُحدث فوضى. وبالنسبة للمهام الطويلة الأمد التي تتوسّع باستخدام وكلاء فرعيين في الخلفية، ارفع حدّ واصفات ملفات العملية، لأن وكيلًا headless يفتح ملفات ومقابس كثيرة قد يصطدم بصمت بحدّ ulimit الافتراضي ويتوقف من دون خطأ واضح. لا شيء من هذا غريب؛ إنها النظافة التشغيلية المملة التي تفصل بين عرض توضيحي وخط أنابيب تثق بتشغيله بينما تنام.
الأسئلة الشائعة
ما هو الوضع headless في Claude Code؟
إنه تشغيل Claude Code بشكل غير تفاعلي عبر العلم -p / --print. يقرأ Claude مطالبة، وينفّذ حلقة الوكيل كاملة، ويطبع النتيجة النهائية، ثم يخرج، من دون طرفية تفاعلية. وهو مخصص للسكربتات والأنابيب ومهام cron وCI/CD بدلًا من البرمجة اليدوية.
كيف أشغّل Claude Code headless دون دفع تكاليف مفاتيح API؟
أنشئ رمزًا مدعومًا باشتراك باستخدام claude setup-token، ثم صدّره باسم CLAUDE_CODE_OAUTH_TOKEN. يصادق هذا مقابل خطة Pro أو Max أو Team أو Enterprise بدلًا من فوترة API المُقاسة. لاحظ أن الوضع --bare يتجاوز OAuth ويظل يتطلب ANTHROPIC_API_KEY.
كيف أوقف Claude Code عن طلب الصلاحية في الوضع headless؟
وافق مسبقًا على الأدوات باستخدام --allowedTools "Bash,Read,Edit"، أو حدّد خط أساس للجلسة باستخدام --permission-mode acceptEdits (أو dontAsk لـ CI محكم الإغلاق). استخدم --dangerously-skip-permissions فقط داخل صندوق رمل للاستعمال المؤقت، لا على جهاز فيه بيانات اعتماد حقيقية أبدًا.
هل يمكنني تشغيل Claude Code headless من Python؟
نعم. الوضع headless جزء من Agent SDK، الذي يُشحن كحزم Python وTypeScript إضافة إلى واجهة claude -p عبر سطر الأوامر. استخدم حزم SDK عندما تريد callbacks للموافقة على الأدوات، وكائنات رسائل أصلية، ومخرجات مُهيكلة دون تحليل stdout.
هل الوضع headless هو نفسه Claude Agent SDK؟
إنهما بابان أماميان للمحرك نفسه. claude -p هو الصيغة عبر سطر الأوامر لـ Agent SDK — الأدوات نفسها، وحلقة الوكيل نفسها، وإدارة السياق نفسها. وتمنحك حزم SDK بلغتي Python وTypeScript تحكمًا برمجيًا أكمل لبناء الوكلاء داخل التطبيقات.
المصادر
- Claude Code Docs — Run Claude Code programmatically (headless): العلم
-p/--print، و--output-format، و--bare، والصلاحيات، و--continue/--resume، وحقول نتيجة JSON. - Claude Code Docs — Authentication:
claude setup-token، وCLAUDE_CODE_OAUTH_TOKEN، وكيف تختلف رموز الاشتراك عنANTHROPIC_API_KEY. - Claude Code Docs — GitHub Actions: تكامل CI من الطرف الأول لتشغيل الوكيل في خطوط الأنابيب.
وقاص احمد وسیر
وقاص احمد وسیر مطوّر ومهندس أتمتة بخبرة تزيد على 8 سنوات في بناء أنظمة إنتاجية يستخدمها أكثر من 100 ألف شخص. يبني تطبيقات SaaS متعددة المستأجرين، وأتمتة بالذكاء الاصطناعي (n8n، تدفقات LLM، بوتات واتساب)، وبنية استضافة (WHM/cPanel، CloudLinux) — وهو صانع WaSphere وFlowMaticX وعلامة الاستضافة WaseerHost. أنجز أكثر من 100 مشروع لشركات صغيرة ومتوسطة ووكالات وشركات ناشئة ممولة.
