دليل sandbox في Claude Code: خطوات إعداد /sandbox
شغّل /sandbox، واختر auto-allow، وضع كل أمر bash داخل حدود يفرضها نظام التشغيل — بمفاتيح الإعدادات الحقيقية لا بالخرافات المتداولة. 12 خطوة موثقة مقابل الوثائق الرسمية.
TL;DR
- يفتح أمر /sandbox لوحة بثلاث تبويبات: Mode وOverrides وConfig. وضع auto-allow يشغّل أوامر bash المعزولة دون طلب إذن؛ وregular permissions يحتفظ بكل تأكيد.
- الحدود يفرضها النواة لا النوافذ المنبثقة: Seatbelt على macOS وbubblewrap على Linux وWSL2. أما Windows الأصلي وWSL1 فغير مدعومين.
- الأوامر المعزولة لا تكتب إلا في مجلد عملك، ومجلد مؤقت لكل مستخدم، ومسارات --add-dir. ومرور الشبكة كله عبر وسيط لا يسمح مسبقًا لأي نطاق.
- القراءات غير محجوبة افتراضيًا — ~/.ssh و~/.aws يبقيان مقروءين حتى تضيف قواعد sandbox.credentials. وحوار Sandbox في VS Code وصل مع v2.1.280.
Claude Code Sandbox Explained
القناة:The Art of Vibe Coding4:29
How auto mode works with Claude Code
القناة:Claude5:42
Configure the sandboxed Bash tool (official docs)
الوثائق:code.claude.com
الفيديو الأول شرح بالجرافيك المتحرك — إطاراته في هذه الصفحة رسوم توضيحية منمقة لا لقطات شاشة، وبعض ادعاءاته صُحح في الخطوات أدناه (بيانات الاعتماد مقروءة افتراضيًا؛ ومفاتيح الإعدادات النموذجية فيه لا تطابق الحقيقية). الفيديو الثاني تسجيل رسمي من Anthropic؛ ولا يُستخدم منه سوى طرفيته وواجهة إعداداته الحقيقيتين.
دُققت الوقائع مقابل code.claude.com/docs/en/sandboxing وسجل CHANGELOG لمشروع anthropics/claude-code (v2.1.280–2.1.283). اللقطات تقتبس مقتطفات وجيزة من التسجيلات للتعليق.
أعد بيئة sandbox في Claude Code في 12 خطوة
افهم الحدود
- 1
تعرف على مشكلة إرهاق الموافقات
بلا sandbox، يتوقف كل أمر مقترح منتظرًا y/n: npm install ثم git status ثم التالي. قاست Anthropic أن 97% من طلبات الأذونات في Claude Code تُوافق عليها — ولهذا بالضبط ينقل sandbox الفحص من كل أمر إلى حدود تضبطها مرة واحدة.
إعادة تمثيل لحلقة y/n لكل أمر يلغيها الـsandbox — تضغط Enter سبعًا وأربعين مرة فتتوقف عن القراءة.شاهد عند 0:22 - 2
شغّل Claude Code على منصة مدعومة
افتح جلسة في مشروعك. العزل مدمج في macOS حيث يأتي Seatbelt مع النظام ولا حاجة لتثبيت شيء. على Linux وWSL2 ثبّت bubblewrap وsocat بمدير الحزم أولًا. أما Windows الأصلي وWSL1 فغير مدعومين — مستخدمو Windows يشغّلون Claude Code داخل توزيعة WSL2.
جلسة في ~/Documents/code/acme — هذا مجلد العمل الذي سيعتبره sandbox قابلًا للكتابة.شاهد عند 0:35 - 3
شغّل /sandbox واقرأ اللوحة
اكتب /sandbox في الجلسة. للوحة ثلاث تبويبات: Mode (كيف تُوافق الأوامر المعزولة)، وOverrides (هل يجوز للأوامر الفاشلة إعادة المحاولة خارج العزل — إعداد allowUnsandboxedCommands)، وConfig (إعدادات sandbox المُحلَّلة بالكامل). ويضيف Linux تبويب Dependencies يسرد الناقص مثل bubblewrap وsocat أو فلتر seccomp الاختياري. ومنذ v2.1.281 يمكنك تنقّل التبويبات بالأسهم، ونال VS Code حوار Sandbox للإعدادات نفسها في v2.1.280.
شغّلها
- 4
اختر auto-allow أو الأذونات العادية
في تبويب Mode، يشغّل auto-allow الأوامر المعزولة بلا سؤال، بينما يحتفظ regular permissions بالأسئلة حتى للأوامر المعزولة. ويُحفظ الاختيار في .claude/settings.local.json للمشروع، الذي يضيفه Claude Code إلى gitignore عنك. لتغطية كل المشاريع، ضع "sandbox": ( "enabled": true ) في ~/.claude/settings.json؛ ولكل جلسة واحدة مرّره عبر --settings.
البداية السريعة من خطوتين: /sandbox يختار الوضع، وsettings.json يحمل كل ما يدوم.شاهد عند 4:00 - 5
اعرف ما يسأل عنه auto-allow رغم كل شيء
إن auto-allow ليس زر كتم. قواعد deny الصريحة تنتصر دائمًا، وrm أو rmdir على مسارات حرجة ما زال يسأل، وقواعد ask المقيدة بالمحتوى مثل Bash(git push *) ما زالت تفرض تأكيدًا. والأوامر التي لا تجوز معزولة ترجع إلى المسار العادي بنافذة عنوانها "Bash command (unsandboxed)". ويعمل auto-allow بمعزل عن وضع الأذونات — فالـbash المعزول يشتغل بلا نوافذ حتى في وضع Manual.
shift+tab يتنقل بين أوضاع الأذونات — تحكم منفصل عن auto-allow في الـsandbox.شاهد عند 0:28 - 6
شاهد كيف يرسم نظام التشغيل الحدود
القيود يفرضها النواة لا أنها مجاملات: يستخدم macOS الـSeatbelt، ويستخدم Linux وWSL2 الـbubblewrap. الأمر المزروع بتلاعب بالمطالبة الذي يحاول قراءة ~/.ssh أو الاتصال بالخارج يصطدم بالجدار نفسه، لأن القواعد تقيّد العملية الجارية وكل ابن تنجبه — لا بلاغة تنفع أمام النواة.
فحوص الأذونات على مستوى التطبيق يمكن التحايل عليها؛ أما طبقة النواة فلا.شاهد عند 2:07
نظام الملفات وبيانات الاعتماد والشبكة
- 7
افهم افتراضيات نظام الملفات — ومطب القراءة
تستطيع الأوامر المعزولة الكتابة في مجلد العمل ومجلداته الفرعية، وفي مجلد مؤقت لكل مستخدم، وفي المجلدات المضافة بـ--add-dir أو permissions.additionalDirectories. أما القراءات فمفتوحة افتراضيًا: القراءة متاحة للقرص كله، بما فيه ~/.aws/credentials و~/.ssh، حتى تسدها أنت. تحب مقاطع الشرح أن تقول إن بيانات الاعتماد تصير «غير مرئية» — لكن الوثائق قاطعة: حمايتها شغلك، عبر sandbox.credentials أو قواعد denyRead.
الكتابة تتوقف عند جدار الـsandbox؛ والقراءة تبقى مفتوحة حتى تغلقها في الخطوة التالية.شاهد عند 1:30 - 8
احمِ بيانات الاعتماد قبل منح الاستقلالية
أضف كتلة sandbox.credentials: اسرد ملفات مثل ~/.ssh أو ~/.aws/credentials بوضع "mode": "deny"، ومتغيرات بيئة سرية مثل GITHUB_TOKEN كي تُفرَّغ داخل كل أمر معزول. ووضع mask يذهب أبعد — يرى الأمر قيمة بديلة، ويستبدل الوسيط القيمة الحقيقية فقط على المضيفين الذين تسمح بهم. وتغطي قواعد Read في permissions.deny أدوات الملفات فوق ذلك.
قواعد deny لـcurl وقراءات .env — ملف الإعدادات نفسه يحمل كتلة sandbox.شاهد عند 4:35 - 9
اسمح بنطاقات الشبكة التي يحتاجها مكدسك
كل المرور المعزول يمر عبر وسيط، ولا نطاق مسموح به مسبقًا. أولما احتاج أمر مضيفًا سأل Claude Code؛ أجب "Yes, and don't ask again" فيحفظ قاعدة سماح WebFetch(domain:...) للجلسات القادمة. اسمح مسبقًا بالسجلات عبر sandbox.network.allowedDomains، واحجب مضيفين بعينهم بـdeniedDomains، وفعّل strictAllowlist لتصير القائمة سقفًا صارمًا لا قائمة أسئلة.
جلب السجلات يمر عبر الوسيط؛ وسكربت postinstall يتصل بـevil.com لا يمر.شاهد عند 1:51 - 10
اضبط نطاق الإعداد: مشروع أم مستخدم أم مُدار
يمكن لإعدادات المشروع في .claude/settings.json إضافة مسارات قابلة للكتابة ونطاقات، لكنها لا تستطيع تعطيل عزل نظام الملفات ولا تمكين Apple Events — هذه المفاتيح لا تُحترم إلا من إعدادات المستخدم أو الإعدادات المُدارة أو راية --settings، فلا يستطيع مستودع مستنسخ إضعاف sandbox. وتفرض الفرق sandbox بإعدادات مُدارة: enabled وfailIfUnavailable وallowUnsandboxedCommands بالقيم true/false/false.
ملف الإعدادات المُدارة يصف بيئة المؤسسة الموثوقة — يضبطها المدراء ويرثها المطورون.شاهد عند 4:10
تحقق وأصلح
- 11
تحقق بمهمة حقيقية
اطلب بناء أو جولة اختبارات. تنفذ الأوامر المعزولة بلا أسئلة، وحين يُحجب شيء تسمي المخالفة المسار أو المضيف في نتيجة الأمر ليتكيف Claude. افتح تبويب Config في /sandbox لتقرأ كل قاعدة محلولة، بما فيها المسارات المحمية التي لا يتجاوزها أي إعداد. ولتجربة صارمة عابرة، شغّل بـ: claude --settings '("sandbox": ("enabled": true, "allowUnsandboxedCommands": false))'.
مهمة واحدة تُكتب ولا نافذة لكل أمر — الحدود تصمد بلا حراسة منك.شاهد عند 0:32 - 12
شخّص الأعطال المألوفة
jest يتعلق — watchman غير متوافق، شغّل jest --no-watchman. docker يفشل — لا يعمل معزولًا، أضف "docker *" إلى excludedCommands. open أو osascript يفشل بخطأ -600 على macOS — Apple Events محجوبة ما لم تكن allowAppleEvents صحيحة. git merge أو checkout يفشل بـ"unable to unlink old" — مسار محمي أو قاعدة denyWrite في الطريق، فوافق على إعادة المحاولة خارج العزل أو شغّل الأمر بنفسك. bwrap يبلّغ Operation not permitted داخل حاوية — فعّل enableWeakerNestedSandbox. وأنابيب الحافظة لا تصل — استخدم /copy بدل pbcopy.
إعدادات sandbox التي تصنع الفرق
تكتب لوحة /sandbox الأساسيات، لكن الرافعة الحقيقية في settings.json. هذه المفاتيح التي توثقها مرجع sandboxing الرسمي — وكلها تحت كتلة "sandbox" (والأخيرة تحت "permissions").
- 1sandbox.enabled — مطفأ حتى تفعّله. القيمة true في ~/.claude/settings.json تغطي كل مشاريعك؛ ولوحة /sandbox تكتب النسخة المحلية للمشروع في .claude/settings.local.json.
- 2sandbox.autoAllowBashIfSandboxed — مفتاح auto-allow، القيمة true افتراضيًا. اجعلها false للاحتفاظ بنوافذ الأذونات حتى لأوامر داخل العزل.
- 3sandbox.allowUnsandboxedCommands وsandbox.failIfUnavailable — القيمة false على الأول تقتل إعادة المحاولة dangerouslyDisableSandbox (تظهر باسم Strict sandbox mode في تبويب Overrides)؛ والقيمة true على الثاني تحول غياب التبعيات إلى فشل صارم عند الإقلاع بدل تحذير.
- 4sandbox.filesystem — allowWrite لمسارات خارج المشروع تحتاجها الأدوات ("~/.kube" و"/tmp/build")، وdenyRead مع allowRead للأماكن السرية، وdisabled (v2.1.216+) لإسقاط طبقة نظام الملفات مع إبقاء عزل الشبكة.
- 5sandbox.network — allowedDomains وdeniedDomains، وstrictAllowlist (v2.1.219+) لحجب كل ما لم يُدرج، وallowLocalBinding ليتيح dev servers ربط المنافذ، وtlsTerminate لتمويه بيانات الاعتماد عند الوسيط.
- 6sandbox.credentials — مدخلات files وenvVars بوضعَي deny أو mask؛ وتتطلب الأقنعة tlsTerminate ولا تُحترم إلا من مصادر user أو managed أو --settings. اقرنها بـpermissions.blockReadsOutsideWorkingDirectories لتقطع كل قراءة خارج مجلدات عملك.
Seatbelt مقابل bubblewrap: فروق المنصات
يستخدم macOS الـSeatbelt المدمج في النظام — لا شيء لتثبيته. الخدوش محددة: واجهات CLI المبنية على Go مثل gh وgcloud وterraform قد تفشل في تحقق TLS تحت Seatbelt، فأدرجها في excludedCommands؛ وopen وosascript وتدفقات مصادقة المتصفح تفشل بخطأ -600 حتى تضبط allowAppleEvents — وهو ما يُضعف العزل ويُتجاهل في إعدادات المشروع.
يستخدم Linux وWSL2 الـbubblewrap مع socat، ويُثبّتان بمدير الحزم. الفلتر الاختياري seccomp (npm install -g @anthropic-ai/sandbox-runtime) يضيف حجب Unix domain sockets وهو ما يمنع ثنائيات Windows من دخول WSL2. وتحمل Ubuntu 24.04 وما بعدها سياسة AppArmor تمنع bubblewrap من إنشاء user namespaces — أضف ملف bwrap من الوثائق وأعد تحميل AppArmor. وداخل حاوية بلا امتيازات، اضبط enableWeakerNestedSandbox ليجري bubblewrap bind-mount لـ/proc الموجود.
الـWSL1 غير مدعوم إطلاقًا — يحتاج bubblewrap ميزات نواة لا يملكها سوى WSL2. كلفة الأداء طفيفة، وإن كانت بعض عمليات نظام الملفات تجري أبطأ قليلًا. ويعمل الوكلاء الفرعيون في العملية نفسها التي تعمل فيها الجلسة الأم ويرثون تهيئة sandbox الخاصة بها، فالـbash الخلفي داخل الوكيل معزول هو أيضًا.
لا يزال التعامل مع sandbox يتغير بين الإصدارات: أضافت v2.1.280 حوار Sandbox في VS Code، وحسّنت v2.1.281 التنقل بين تبويبات /sandbox وتلميح allowLocalBinding لخوادم التطوير، وأصلحت v2.1.282–2.1.283 مطابقة excludedCommands وكتابات TMPDIR وتحليل الإعدادات المُدارة. تصفح CHANGELOG قبل الاعتماد على سلوك حالات الحافة.