ตั้งค่านโยบายแซนด์บ็อกซ์

การรันของเอเจนต์จะอยู่ในแซนด์บ็อกซ์หรือไม่นั้นถูกตัดสินบนเซิร์ฟเวอร์ตอนบูต (--sandbox) สวิตช์ เปิดใช้แซนด์บ็อกซ์ และตัวเลือก แบ็กเอนด์ ภายใต้ การตั้งค่า → เซิร์ฟเวอร์ → การวินิจฉัยและความเป็นส่วนตัว เป็นค่ากำหนดที่จัดเก็บไว้บนอุปกรณ์ของคุณ การตรวจหาโฮสต์ของการ์ด แซนด์บ็อกซ์ รายงานว่าโฮสต์ของเซิร์ฟเวอร์ห่ออะไรได้บ้าง

มีส่วนควบคุมสองอย่างที่ไปถึงการรัน และคู่มือนี้ครอบคลุมทั้งคู่: กฎการกระทำใน การตั้งค่า → เวิร์กสเปซ → สิทธิ์ของเอเจนต์ ซึ่งตัดสินว่าเอเจนต์พุช เปิด หรือเข้าถึงอะไรได้ และแฟล็ก --sandbox ของเซิร์ฟเวอร์เอง

อะไรที่เป็นข้อจำกัดต่อการรันของเอเจนต์

มีหกสิ่งที่เป็นข้อจำกัดต่อเอเจนต์ อย่างแรกคือแซนด์บ็อกซ์ของ OS และเป็นสิ่งเดียวที่มีเงื่อนไข — อีกห้าสิ่งคงอยู่บนทุกโฮสต์

ขอบเขต	สิ่งที่มันทำ
แซนด์บ็อกซ์ของ OS	Seatbelt บน macOS, bubblewrap บน Linux และ WSL2 ห่อ Claude Code CLI อะแดปเตอร์ ACP และเครื่องมือ bash ของฮาร์เนส ไม่มีบน Windows และบน Linux ที่ไม่มี bwrap และ socat
worktree ของตัวเอง	การสนทนาแต่ละรายการได้เช็กเอาต์แบบ copy-on-write เช็กเอาต์ต้นฉบับถูกพับเข้าในการรันเป็นเส้นทางที่ห้ามเขียน และแซนด์บ็อกซ์คือสิ่งที่บังคับใช้มัน
ข้อมูลรับรองที่ผ่านนายหน้า	นายหน้าข้อมูลรับรองสร้างสภาพแวดล้อมต่อการรันหนึ่งครั้ง และเพิกถอนมันตอนรื้อถอน โทเคน 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
เข้าถึงเครือข่าย	อนุญาต	แซนด์บ็อกซ์มีเครือข่ายหรือไม่ และเครื่องมือเว็บของฮาร์เนส

1. ไปที่ การตั้งค่า → เวิร์กสเปซ → สิทธิ์ของเอเจนต์
2. เลือกขอบเขต — เวิร์กสเปซ, เอเจนต์ หรือ สเปซ — แล้วเลือก อนุญาต, ถามก่อน หรือ ปฏิเสธ ในแถวของกฎ

กฎการพุชที่จำกัดตามสาขา เช่นกฎที่ปฏิเสธการพุชไป main ก็มีผลด้วย: ดู กฎคุม

จุดตรวจสอบ: สั่งเอเจนต์ให้พุชสาขาหนึ่ง เมื่อตั้งเป็น ถามก่อน คุณจะได้คำขออนุมัติที่ระบุ รีโปและ ref เมื่อตั้งเป็น ปฏิเสธ git จะพิมพ์ ! [remote rejected] <ref> (Control Center policy: …)

แต่ละกฎไปถึงการรันอย่างไร:

• การพุช ถูกบังคับใช้ด้วยสิ่งที่การรันถืออยู่ โทเคน GitHub ของมันคือโทเคนการติดตั้ง GitHub App แบบอ่านอย่างเดียว ที่อ่านเนื้อหาและทำงานกับ pull request ได้ การตั้งค่า git ของมันส่งทุกการพุชไปยัง GitHub ไปที่เกตเวย์ลูปแบ็กบน cc_server ซึ่งถามกฎก่อน แล้วจึง ส่งการพุชต่อด้วยโทเคนเขียนที่เอเจนต์ไม่เคยเห็น เกตเวย์ส่งต่อไปยังรีโปของ worktree เอง หรือรีโป GitHub ที่ลิงก์กับเวิร์กสเปซเท่านั้น สิ่งนี้เป็นจริงกับทุกอะแดปเตอร์
• pull request และ issue จากเชลล์ ถูกจดจำจากบรรทัดคำสั่ง: ในเครื่องมือ bash ของ ฮาร์เนส และผ่านฮุกในเครื่องมือ Bash ของ Claude Code เอเจนต์ที่ซ่อนคำสั่ง (สคริปต์, eval, การเรียก API โดยตรง) เลี่ยงการตรวจนี้ได้ แต่เลี่ยงเกตเวย์การพุชไม่ได้
• คีย์ตั๋วงาน ไม่เคยถูกใส่ลงในแซนด์บ็อกซ์ เอเจนต์เขียนตั๋วงานผ่านเครื่องมือ MCP ของ Control Center ซึ่งถามกฎ
• เครือข่าย ถูกตัดสินครั้งเดียวตอนเริ่มรัน ปฏิเสธ ปิดเครือข่ายของแซนด์บ็อกซ์ อนุญาต และ ถามก่อน คงไว้ให้เปิด และภายใต้ ถามก่อน เครื่องมือ web_fetch และ web_search ของฮาร์เนสยังถามทุกครั้งที่เรียก GitHub อยู่ในรายการขาออกที่อนุญาตเสมอ ตราบที่เครือข่ายเปิดอยู่

หากไม่มี GitHub App กฎการพุชเป็นเพียงคำแนะนำ

หากไม่ได้กำหนดค่า GitHub App ไว้ การรันจะได้ personal access token ตัวสำรอง ซึ่งจำกัดให้ อ่านอย่างเดียวไม่ได้ git push ยังผ่านเกตเวย์และกฎ แต่โค้ดที่ใช้โทเคนนั้นโดยตรงพุชเลี่ยง กฎได้ ตั้งค่า GitHub App เพื่อให้กฎมีผลผูกมัด

ข้อมูลรับรอง GitHub ของการรันเป็นของนายหน้าเท่านั้นเสมอ — โทเคนการติดตั้ง GitHub App ที่จำกัดขอบเขตกับรีโป หรือ PAT ตัวสำรอง — ไม่เคยเป็นโทเคนที่จัดเก็บไว้ของสมาชิกผู้ร้องขอเอง PAT ของเซิร์ฟเวอร์จะถูกระงับสำหรับการรันที่ทำในนามสมาชิกที่ไม่ได้เป็นเจ้าของและยังไม่ได้ เชื่อม GitHub

ตรวจสอบว่าการรันเอเจนต์ของคุณอยู่ในแซนด์บ็อกซ์หรือไม่

มีสองสิ่งตัดสินเรื่องนี้ ทั้งคู่อยู่บนเซิร์ฟเวอร์: ว่าโฮสต์มีแบ็กเอนด์ให้หรือไม่ และว่า --sandbox เปิดอยู่หรือไม่ ตรวจตามลำดับนั้น

1. ไปที่ การตั้งค่า → เซิร์ฟเวอร์ → การวินิจฉัยและความเป็นส่วนตัว
2. อ่านการ์ด แซนด์บ็อกซ์ ข้อเท็จจริง โฮสต์ คือเครื่องที่ cc_server รันอยู่ ไม่ใช่เครื่องที่คุณกำลังดูอยู่ ฟิลด์ แบ็กเอนด์ แสดง แซนด์บ็อกซ์เนทีฟ (Seatbelt บน macOS, bubblewrap บน Linux และ WSL2) หรือ ไม่แยก ข้อเท็จจริง มีผล คือค่ากำหนดของอุปกรณ์นี้ ไม่ใช่การห่อที่เซิร์ฟเวอร์ใช้จริง
3. อ่านล็อกเริ่มต้นของเซิร์ฟเวอร์ มันพิมพ์หนึ่งในสามบรรทัดนี้เท่านั้น:
   • 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, เผยแพร่หรือรวม, เขียนไปยังตัวติดตามภายนอก, ติดตั้งแพ็กเกจ, รันโปรเซส, เปลี่ยนโครงสร้างเวิร์กสเปซ, บูตหรือควบคุมเอนโคลเจอร์
รีวิว	อ่านอย่างเดียว	สิบเอ็ดคลาสเดิม ไม่ให้ผู้ใช้เลือก — ช่องเขียนข้อความมีเพียงเอเจนต์ แผน และประสานงาน
ประสานงาน	อ่านอย่างเดียว	สิบเอ็ดคลาสเดิม

การเข้าถึงเครือข่ายและการเข้าถึงข้อมูลลับนั้น ไม่ ถูกปฏิเสธโดยโหมดอ่านอย่างเดียวโดยเจตนา: การค้นคว้าคือจุดหมายของมัน

กำหนดให้ต้องอนุมัติก่อนการกระทำจะรัน

การอนุมัติเป็นคำตัดสินของกฎคุม ไม่ใช่การตั้งค่าแซนด์บ็อกซ์

1. ไปที่ การตั้งค่า → เวิร์กสเปซ → สิทธิ์ของเอเจนต์
2. ตั้งคลาสการกระทำเป็น ถามก่อน ที่ขอบเขตเวิร์กสเปซ เอเจนต์ หรือสเปซ

คำตัดสิน ถามก่อน จะขัดจังหวะการรันและถามคุณ เมื่อไม่มีผู้อนุมัติเชื่อมต่ออยู่ มันจะปิดเมื่อล้มเหลวและการกระทำนั้นถูกปฏิเสธ ดูตั้งค่ากฎคุม สำหรับลำดับการแปลงคำตัดสินทั้งหมด

การแก้ปัญหา

เอเจนต์พุชไม่ได้และฉันไม่ได้ห้ามมันเลย

ดูว่า 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 หรือ Claude Code CLI ถูก ห่อที่ใดมีแบ็กเอนด์ และเช็กเอาต์ที่ลงทะเบียนไว้ของคุณเป็นเส้นทางที่ห้ามเขียนภายในที่ห่อนั้นในทุกโหมด รวมถึงรูปที่แปลงซิมลิงก์แล้วของมันด้วย (บน macOS เส้นทางที่เข้าถึงผ่าน /tmp หรือ /var/folders จะแปลงค่าอยู่ใต้ /private และทั้งสองรูปแบบถูกปฏิเสธในตอนนี้) บนโฮสต์ที่ไม่มีแบ็กเอนด์ ไม่มีข้อใดนั้นใช้เลย ไม่ทางใดก็ทางหนึ่ง กฎคุมสามารถปฏิเสธ เขียนนอก worktree ได้ทันที

คู่มือที่เกี่ยวข้อง

• ตั้งค่ากฎคุม
• สร้างและกำหนดค่าเอเจนต์
• วินิจฉัยเอเจนต์
• แบ็กเอนด์แซนด์บ็อกซ์
• cc_server CLI: แฟล็ก --sandbox

แนวคิดที่เกี่ยวข้อง

• แซนด์บ็อกซ์และความปลอดภัย
• โหมด