پیکربندی سیاست‌های سندباکس

اینکه اجرای یک عامل سندباکس می‌شود یا نه، سمت سرور و در زمان بوت تصمیم گرفته می‌شود (--sandbox). کلید فعال‌سازی سندباکس و انتخابگر بک‌اند زیر تنظیمات → سرور → تشخیص و حریم خصوصی ترجیحاتی هستند که روی دستگاه شما ذخیره می‌شوند. تشخیص میزبان در کارت سندباکس گزارش می‌دهد که میزبان سرور چه چیزی را می‌تواند بپیچد.

دو کنترل به یک اجرا می‌رسند و این راهنما هر دو را پوشش می‌دهد: قواعد کنش در تنظیمات → فضای کاری → مجوزهای عامل، که تعیین می‌کنند یک عامل چه چیزی را می‌تواند پوش کند، باز کند یا به آن دسترسی داشته باشد، و پرچم --sandbox خود سرور.

چه چیزی اجرای یک عامل را محدود می‌کند

شش چیز یک عامل را نگه می‌دارد. نخستین مورد سندباکس سیستم‌عامل است و همان موردی است که مشروط است — پنج مورد دیگر روی هر میزبانی برقرارند.

مرز	چه می‌کند
سندباکس سیستم‌عامل	Seatbelt روی macOS، bubblewrap روی Linux و WSL2. CLI مربوط به Claude Code، آداپتورهای ACP و ابزار `bash` هارنس را می‌پیچد. روی Windows و روی Linux بدون `bwrap` و `socat` وجود ندارد
worktree خودش	هر گفتگو یک چک‌اوت کپی-در-نوشتن می‌گیرد. چک‌اوت اصلی به‌عنوان یک مسیر رد-نوشتن در اجرا گنجانده می‌شود و این سندباکس است که آن را اعمال می‌کند
اعتبارنامه‌های کارگزاری‌شده	کارگزار اعتبارنامه یک محیط به‌ازای هر اجرا می‌سازد و آن را هنگام برچیدن باطل می‌کند. توکن GitHub درون آن می‌تواند بخواند اما نمی‌تواند پوش کند: پوش‌ها از Control Center می‌گذرند که ابتدا از قاعدهٔ پوش می‌پرسد
گاردریل‌های کنش	هر ابزار تغییردهنده کلاس‌های اثرش را اعلام می‌کند و نگهبان آن را پیش از اجرای فراخوانی حل می‌کند. یک `prompt` بدون هیچ تأییدکنندهٔ متصل رد می‌شود
پاک‌سازی محیط	ACP و ابزار `bash` هارنس یک محیط پالایش‌شده می‌گیرند. Claude Code از مسیر `NoSandboxAdapter` محیط میزبان را به ارث می‌برد
سطح ابزار حالت	یک حالت فقط‌خواندنی ابزارهای تغییردهندهٔ worktree را یکسره حذف می‌کند و فعل خروجی خودِ حالت را سنجاق می‌کند تا باز هم بتواند تحویل‌دادنی‌اش را ارائه کند

سه چیز ضعیف‌تر از آنچه به نظر می‌رسد باقی می‌ماند:

تنها هارنس داخلی دروازهٔ ابزار، قراردادهای تکمیل و قواعد ساختاری حالت را اعمال می‌کند. آداپتور Claude Code این کار را نمی‌کند. به‌ویژه Claude Code با --dangerously-skip-permissions راه‌اندازی می‌شود، چون یک claude -p غیرتعاملی در غیر این صورت برای همیشه پشت پرامپت خودش گیر می‌کند — بنابراین فراخوانی‌های خواندن، نوشتن و ویرایش خود Claude نه دیده می‌شوند و نه توسط Control Center دروازه‌بندی می‌شوند، و فرمان‌های bash فقط با یک هوک که خط فرمان را می‌خواند بررسی می‌شوند. جایی که سندباکس روشن است، همان مرز پیرامون آن‌هاست.
ابزارهای فایلی درون‌پردازشی هارنس (read، write، edit، apply patch، search، find، search_files) درون فرایند سرور اجرا می‌شوند، پس هیچ پروفایل سندباکسی آن‌ها را محدود نمی‌کند. تنها ابزار bash از مسیر اجراکنندهٔ فرمان سندباکس‌شده می‌گذرد. آن ابزارها با محدودسازی مسیر خودشان به‌علاوهٔ گاردریل‌های کنش محدود می‌شوند.
روی میزبانی بدون بک‌اند، ردیف اول اصلاً اعمال نمی‌شود. ACP و ابزار bash هارنس به پاک‌سازی محیط به‌علاوهٔ سیاست فرمان برمی‌گردند؛ Claude Code از مسیر NoSandboxAdapter محیط میزبان را به ارث می‌برد. سرور این را در لاگ راه‌اندازی‌اش می‌گوید. وضعیت خود را در ادامه بررسی کنید.

تصمیم بگیرید یک عامل چه چیزی را می‌تواند پوش کند

برای git push، GitHub، تیکتینگ یا شبکه هیچ کلید به‌ازای هر عامل وجود ندارد. هر کدام یک قاعدهٔ کنش است:

قاعده	پیش‌فرض داخلی	آنچه پوشش می‌دهد
پوش به یک ریموت	ابتدا بپرس	هر `git push` به GitHub، از هر آداپتوری
باز کردن یک pull request	ابتدا بپرس	`gh pr create` و ابزارهای pull request
انتشار یک بازبینی یا ادغام	ابتدا بپرس	`gh pr merge`، `gh pr review`، `gh pr comment`، `gh pr close`
نوشتن در یک ردیاب خارجی	ابتدا بپرس	نوشتن تیکت از طریق ابزارهای Control Center و `gh issue`
دسترسی به شبکه	اجازه	اینکه سندباکس شبکه دارد یا نه، و ابزارهای وب هارنس

به تنظیمات → فضای کاری → مجوزهای عامل بروید
یک محدوده انتخاب کنید — فضای کاری، عامل یا فضا — سپس روی ردیف قاعده اجازه، ابتدا بپرس یا رد را انتخاب کنید

قواعد پوش محدود به شاخه، مانند قاعده‌ای که پوش به main را رد می‌کند، هم اعمال می‌شوند: گاردریل‌ها را ببینید.

چک‌پوینت: از یک عامل بخواهید شاخه‌ای را پوش کند. با ابتدا بپرس یک درخواست تأیید می‌گیرید که مخزن و ref را نام می‌برد؛ با رد، git چاپ می‌کند ! [remote rejected] <ref> (Control Center policy: …).

هر قاعده چگونه به اجرا می‌رسد:

پوش‌ها با آنچه اجرا در دست دارد اعمال می‌شوند. توکن GitHub آن یک توکن نصب فقط‌خواندنی GitHub App است که محتوا را می‌خواند و با pull requestها کار می‌کند. پیکربندی git آن هر پوش به GitHub را به یک دروازهٔ loopback روی cc_server می‌فرستد، که از قاعده می‌پرسد و تنها پس از آن پوش را با یک توکن نوشتنی که عامل هرگز نمی‌بیند عبور می‌دهد. دروازه فقط به مخزن خود worktree یا یک مخزن GitHub پیوندخورده با فضای کاری می‌فرستد. این برای هر آداپتوری صادق است.
pull requestها و ایشوها از پوسته از روی خط فرمان شناخته می‌شوند: در ابزار bash هارنس، و از طریق یک هوک در ابزار Bash در Claude Code. عاملی که فرمان را پنهان کند (اسکریپت، eval، فراخوانی مستقیم API) این بررسی را دور می‌زند، اما دروازهٔ پوش را نه.
کلیدهای تیکتینگ هرگز در سندباکس گذاشته نمی‌شوند. عامل‌ها تیکت‌ها را از طریق ابزارهای MCP در Control Center می‌نویسند که از قاعده می‌پرسند.
شبکه یک‌بار، در شروع اجرا، حل می‌شود. رد شبکهٔ سندباکس را خاموش می‌کند؛ اجازه و ابتدا بپرس آن را روشن نگه می‌دارند، و زیر ابتدا بپرس ابزارهای web_fetch و web_search هارنس همچنان در هر فراخوانی می‌پرسند. تا وقتی شبکه روشن است، GitHub همیشه در فهرست مجاز خروج قرار دارد.

وقتی هیچ GitHub Appی پیکربندی نشده باشد، اجرا personal access token جایگزین را می‌گیرد که نمی‌توان آن را به فقط‌خواندنی محدود کرد. git push همچنان از دروازه و قاعده می‌گذرد، اما کدی که آن توکن را مستقیماً به کار ببرد می‌تواند با دور زدن قاعده پوش کند. یک GitHub App پیکربندی کنید تا قاعده الزام‌آور شود.

اعتبارنامهٔ GitHub یک اجرا همیشه فقط مال کارگزار است — یک توکن نصب GitHub App با دامنهٔ محدود به مخزن، یا PAT جایگزین — هرگز توکن ذخیره‌شدهٔ خودِ عضوی که درخواست داده. PAT سرور از اجراهایی که به نمایندگی از عضوی که مالک نیست و GitHub را متصل نکرده عمل می‌کنند بازداشته می‌شود.

بررسی اینکه اجراهای عامل شما سندباکس می‌شوند یا نه

دو چیز آن را تعیین می‌کند، هر دو سمت سرور: اینکه میزبان بک‌اندی عرضه می‌کند یا نه و اینکه --sandbox روشن است یا نه. به همین ترتیب بررسی‌شان کنید.

به تنظیمات → سرور → تشخیص و حریم خصوصی بروید
کارت سندباکس را بخوانید. مقدار میزبان ماشینی است که cc_server روی آن اجرا می‌شود، نه ماشینی که به آن نگاه می‌کنید. فیلد بک‌اند سندباکس بومی (Seatbelt روی macOS، bubblewrap روی Linux و WSL2) یا بدون جداسازی را فهرست می‌کند. مقدار در حال اجرا ترجیح این دستگاه است، نه پوششی که سرور در واقع استفاده می‌کند.
لاگ راه‌اندازی سرور را بخوانید. دقیقاً یکی از این سه خط را چاپ می‌کند:
- agent sandbox ON به‌همراه یادداشت بک‌اند — اجراها پیچیده می‌شوند
- no OS-native agent sandbox on this host به‌همراه یک راهنمای نصب، جایی که وجود دارد — اجراها پیچیده نمی‌شوند
- agent sandbox DISABLED by --sandbox off — یک انصراف عامدانه

GET /healthz وضعیت سندباکس را گزارش نمی‌کند، پس همان لاگ راه‌اندازی بررسی است.

برای خاموش‌کردن عامدانهٔ سندباکس — میزبانی که پروفایل در آن بدرفتاری می‌کند دلیل وجود این گزینه است — سرور را با --sandbox off راه‌اندازی کنید، یا CC_SERVER_SANDBOX=off را تنظیم کنید. پیش‌فرض on است و on یعنی «اگر میزبان بک‌اندی دارد از آن استفاده کن»، هرگز یعنی «بک‌اند را الزام کن».

دو وضعیت هرگز پوشش سندباکس بومی نمی‌گیرند. روی Windows تشخیص‌دهندهٔ بومی همیشه «در دسترس نیست» گزارش می‌دهد و چیزی برای نصب وجود ندارد — اعزام عامل از none استفاده می‌کند. بک‌اند microvm جداست (ترمینال‌های تعاملی و ریگ‌ها) و دسترسی‌اش با تشخیص به زمان اجرای خودش گره خورده است. روی Linux و WSL2 هر دوی bwrap و socat باید روی PATH باشند؛ بدون آن‌ها تشخیص‌دهنده «در دسترس نیست» گزارش می‌دهد و بسته‌های غایب را نام می‌برد.

روی Linux/WSL2 با bubblewrap نصب‌شده، الگوهای فایل محرمانهٔ سیاست استاندارد برای فایل‌هایی که عامل بعداً می‌سازد قابل اعمال نیستند. چنین اجرای بومی اکنون شکست می‌خورد، به‌جای آنکه قواعد را بی‌صدا نادیده بگیرد. پس یک تشخیص مثبت در هنگام بوت تضمین نمی‌کند که یک اعزام Linux می‌تواند شروع شود. --sandbox off یک انصراف عامدانه و بدون محدودیت است، نه یک مرز امنیتی جانشین.

بدانید یک حالت از قبل چه چیزی را ممنوع می‌کند

حالت به‌ازای هر فضا ذخیره می‌شود و به‌عنوان لایهٔ پیش‌تنظیم حالت به حل‌کنندهٔ گاردریل تغذیه می‌شود. سه تا از چهار حالت فقط‌خواندنی‌اند و یک حالت فقط‌خواندنی یازده کلاس اثر را یکسره رد می‌کند:

حالت	worktree	ردشده توسط پیش‌تنظیم
عامل (`chat`)	نوشتنی	هیچ‌چیز — پیش‌فرض‌های داخلی اعمال می‌شوند
برنامه	فقط‌خواندنی	حذف یک فایل، نوشتن بیرون از worktree، کامیت، پوش، باز کردن یک PR، انتشار یا ادغام، نوشتن در یک ردیاب خارجی، نصب یک بسته، اجرای یک فرایند، تغییر ساختار فضای کاری، راه‌اندازی یا راندن یک محفظه
بازبینی	فقط‌خواندنی	همان یازده مورد. توسط کاربر قابل انتخاب نیست — نویسندهٔ پیام تنها عامل، برنامه و ارکستر را عرضه می‌کند
ارکستر	فقط‌خواندنی	همان یازده مورد

دسترسی به شبکه و دسترسی به راز عامدانه توسط یک حالت فقط‌خواندنی رد نمی‌شوند: پژوهش همان نقطهٔ وجودی چنین حالتی است.

پیش از اجرای یک کنش، تأیید بخواهید

تأیید یک تصمیم گاردریل است، نه یک تنظیم سندباکس.

به تنظیمات → فضای کاری → مجوزهای عامل بروید
کلاس کنش را در محدودهٔ فضای کاری، عامل یا فضا روی ابتدا بپرس بگذارید

یک تصمیم ابتدا بپرس اجرا را متوقف می‌کند و از شما می‌پرسد. با نبود تأییدکنندهٔ متصل، به‌صورت بسته شکست می‌خورد و کنش رد می‌شود. برای ترتیب کامل حل‌وفصل پیکربندی گاردریل‌ها را ببینید.

عیب‌یابی

یک عامل نمی‌تواند push کند و من هرگز آن را رد نکرده‌ام

ببینید git چه چاپ کرده است. Control Center policy: … یعنی یک قاعده پوش را رد کرده یا یک ابتدا بپرس بی‌پاسخ مانده است. … is not linked to this workspace یعنی مقصد نه مخزن خود worktree است و نه با فضای کاری پیوند خورده. Control Center has no GitHub credential that can push … یعنی مخزن هیچ نصبی از GitHub App ندارد و هیچ اعتبارنامهٔ جایگزینی که بتواند پوش کند وجود ندارد: برنامه را روی آن مخزن نصب کنید، یا GitHub را متصل کنید.

کارت سندباکس سندباکس بومی گزارش نمی‌کند

در آن صورت اجراهای عامل روی آن میزبان با Seatbelt یا bubblewrap پیچیده نمی‌شوند و مرزهای باقی‌مانده همان‌هایی هستند که دارید. روی Linux و WSL2 هر دو ابزار غایب را نصب کنید — sudo apt-get install bubblewrap socat — و سرور را دوباره راه‌اندازی کنید؛ لاگ راه‌اندازی باید بگوید سندباکس روشن است. روی Windows هیچ بک‌اند بومی‌ای برای نصب وجود ندارد، پس در عوض گاردریل‌ها را سخت‌تر کنید: پیکربندی گاردریل‌ها را ببینید.

یک عامل به فایلی بیرون از worktree خودش رسیده است

اینکه کدام ابزار به آن رسیده تعیین می‌کند که آیا این انتظارمی‌رفته است یا نه.

ابزارهای فایلی درون‌پردازشی هارنس (read، write، edit، apply patch، search، find، search_files) درون فرایند سرور اجرا می‌شوند، پس هیچ پروفایل سندباکسی بر آن‌ها اعمال نمی‌شود — کرانشان محدودسازی مسیر خودشان به‌علاوهٔ گاردریل‌هاست. یک فرمان bash یا CLI مربوط به Claude Code جایی که بک‌اندی وجود دارد پیچیده می‌شوند و چک‌اوت‌های ثبت‌شدهٔ شما درون آن پوشش، در هر حالتی، رد-نوشتن هستند، از جمله صورت‌های حل‌شدهٔ symlinkشان (روی macOS مسیری که از /tmp یا /var/folders رسیده باشد زیر /private حل می‌شود و هر دو صورت اکنون رد هستند). روی میزبانی بدون بک‌اند هیچ‌یک از این‌ها اعمال نمی‌شود. در هر صورت، گاردریل‌ها می‌توانند نوشتن بیرون از worktree را یکسره رد کنند.