Gateway

แซนด์บ็อกซ์เทียบกับนโยบายเครื่องมือและสิทธิ์ระดับสูง

Status: active

OpenClaw มีการควบคุมสามประเภทที่เกี่ยวข้องกันแต่แตกต่างกัน:

แซนด์บ็อกซ์ (agents.defaults.sandbox.* / agents.list[].sandbox.*) กำหนดว่า เครื่องมือทำงานที่ใด (แบ็กเอนด์แซนด์บ็อกซ์หรือโฮสต์)
นโยบายเครื่องมือ (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) กำหนดว่า เครื่องมือใดพร้อมใช้งาน/ได้รับอนุญาต
สิทธิ์ระดับสูง (tools.elevated.*, agents.list[].tools.elevated.*) เป็น ช่องทางหลีกออกสำหรับ exec เท่านั้น เพื่อทำงานนอกแซนด์บ็อกซ์เมื่อคุณอยู่ในแซนด์บ็อกซ์ (ค่าเริ่มต้นคือ gateway หรือ node เมื่อกำหนดเป้าหมายของ exec เป็น node)

การดีบักอย่างรวดเร็ว

ใช้ตัวตรวจสอบเพื่อดูว่า OpenClaw กำลังทำอะไรอยู่ จริง ๆ:

bash

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

คำสั่งนี้แสดง:

โหมด/ขอบเขต/สิทธิ์เข้าถึงพื้นที่ทำงานของแซนด์บ็อกซ์ที่มีผล
เซสชันอยู่ในแซนด์บ็อกซ์หรือไม่ในขณะนี้ (เซสชันหลักเทียบกับเซสชันที่ไม่ใช่เซสชันหลัก)
การอนุญาต/ปฏิเสธเครื่องมือในแซนด์บ็อกซ์ที่มีผล (รวมถึงมาจากเอเจนต์/ส่วนกลาง/ค่าเริ่มต้น)
เกตสิทธิ์ระดับสูงและพาธคีย์สำหรับการแก้ไข

แซนด์บ็อกซ์: เครื่องมือทำงานที่ใด

การใช้แซนด์บ็อกซ์ควบคุมด้วย agents.defaults.sandbox.mode:

"off": ทุกอย่างทำงานบนโฮสต์
"non-main": เฉพาะเซสชันที่ไม่ใช่เซสชันหลักเท่านั้นที่อยู่ในแซนด์บ็อกซ์ (มักเป็นเรื่อง "ไม่คาดคิด" สำหรับกลุ่ม/ช่องทาง)
"all": ทุกอย่างอยู่ในแซนด์บ็อกซ์

agents.defaults.sandbox.workspaceAccess ควบคุมสิ่งที่แซนด์บ็อกซ์มองเห็นได้: "none", "ro" หรือ "rw"

ดูเมทริกซ์ฉบับเต็ม (ขอบเขต การเมานต์พื้นที่ทำงาน อิมเมจ) ได้ที่ การใช้แซนด์บ็อกซ์

การเมานต์แบบผูก (การตรวจสอบความปลอดภัยอย่างรวดเร็ว)

docker.binds เจาะผ่าน ระบบไฟล์ของแซนด์บ็อกซ์: สิ่งใดก็ตามที่คุณเมานต์จะมองเห็นได้ภายในคอนเทนเนอร์ตามโหมดที่กำหนด (:ro หรือ :rw)
หากละเว้นโหมด ค่าเริ่มต้นคืออ่านและเขียนได้ สำหรับซอร์สโค้ด/ข้อมูลลับควรใช้ :ro
scope: "shared" จะไม่สนใจการผูกเฉพาะเอเจนต์ (ใช้เฉพาะการผูกส่วนกลาง)
OpenClaw ตรวจสอบต้นทางของการผูกสองครั้ง: ครั้งแรกกับพาธต้นทางที่ปรับให้อยู่ในรูปมาตรฐานแล้ว จากนั้นตรวจอีกครั้งหลังแก้ไขพาธผ่านบรรพบุรุษที่ลึกที่สุดซึ่งมีอยู่จริง การหลบออกผ่านพาเรนต์ที่เป็นลิงก์สัญลักษณ์ไม่สามารถข้ามการตรวจสอบพาธที่ถูกบล็อกหรือรากที่อนุญาตได้
พาธปลายทางที่ยังไม่มีอยู่จะยังคงได้รับการตรวจสอบอย่างปลอดภัย หาก /workspace/alias-out/new-file ถูกแก้ไขพาธผ่านพาเรนต์ที่เป็นลิงก์สัญลักษณ์ไปยังพาธที่ถูกบล็อกหรืออยู่นอกรากที่กำหนดไว้ การผูกจะถูกปฏิเสธ
การผูก /var/run/docker.sock เท่ากับมอบการควบคุมโฮสต์ให้แซนด์บ็อกซ์โดยพฤตินัย ให้ทำเฉพาะเมื่อมีเจตนาเท่านั้น
สิทธิ์เข้าถึงพื้นที่ทำงาน (workspaceAccess) เป็นอิสระจากโหมดของการผูก

นโยบายเครื่องมือ: เครื่องมือใดมีอยู่/เรียกใช้ได้

มีหลายชั้นที่สำคัญ:

โปรไฟล์เครื่องมือ: tools.profile และ agents.list[].tools.profile (รายการอนุญาตพื้นฐาน)
โปรไฟล์เครื่องมือของผู้ให้บริการ: tools.byProvider[provider].profile และ agents.list[].tools.byProvider[provider].profile
นโยบายเครื่องมือส่วนกลาง/เฉพาะเอเจนต์: tools.allow/tools.deny และ agents.list[].tools.allow/agents.list[].tools.deny
นโยบายเครื่องมือของผู้ให้บริการ: tools.byProvider[provider].allow/deny และ agents.list[].tools.byProvider[provider].allow/deny
นโยบายเครื่องมือในแซนด์บ็อกซ์ (ใช้เฉพาะเมื่ออยู่ในแซนด์บ็อกซ์): tools.sandbox.tools.allow/tools.sandbox.tools.deny และ agents.list[].tools.sandbox.tools.*

หลักทั่วไป:

deny มีสิทธิ์เหนือกว่าเสมอ
หาก allow ไม่ว่างเปล่า รายการอื่นทั้งหมดจะถือว่าถูกบล็อก
นโยบายเครื่องมือคือข้อจำกัดเด็ดขาด: /exec ไม่สามารถข้ามเครื่องมือ exec ที่ถูกปฏิเสธได้
นโยบายเครื่องมือกรองความพร้อมใช้งานของเครื่องมือตามชื่อ แต่ไม่ได้ตรวจสอบผลข้างเคียงภายใน exec หากอนุญาต exec การปฏิเสธ write, edit หรือ apply_patch ไม่ได้ทำให้คำสั่งเชลล์เป็นแบบอ่านอย่างเดียว
/exec เปลี่ยนเฉพาะค่าเริ่มต้นของเซสชันสำหรับผู้ส่งที่ได้รับอนุญาตเท่านั้น ไม่ได้ให้สิทธิ์เข้าถึงเครื่องมือ
คีย์เครื่องมือของผู้ให้บริการยอมรับได้ทั้ง provider (เช่น google-antigravity) หรือ provider/model (เช่น openai/gpt-5.4)
บันทึกของ Gateway มีรายการตรวจสอบ agents/tool-policy เมื่อนโยบายเครื่องมือขั้นตอนใดนำเครื่องมือออก หรือนโยบายเครื่องมือในแซนด์บ็อกซ์บล็อกการเรียกใช้ ใช้ openclaw logs เพื่อดูป้ายกำกับกฎ คีย์การกำหนดค่า และชื่อเครื่องมือที่ได้รับผลกระทบ

กลุ่มเครื่องมือ (รูปแบบย่อ)

นโยบายเครื่องมือ (ส่วนกลาง เอเจนต์ แซนด์บ็อกซ์) รองรับรายการ group:* ซึ่งขยายเป็นเครื่องมือหลายรายการ:

json5

{  tools: {    sandbox: {      tools: {        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],      },    },  },}

กลุ่มที่พร้อมใช้งาน:

กลุ่ม	เครื่องมือ
`group:runtime`	`exec`, `process`, `code_execution` (ยอมรับ `bash` เป็นชื่อแทนของ `exec`)
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:sessions`	`sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`
`group:memory`	`memory_search`, `memory_get`
`group:web`	`web_search`, `x_search`, `web_fetch`
`group:ui`	`browser`, `canvas`
`group:automation`	`heartbeat_respond`, `cron`, `gateway`
`group:messaging`	`message`
`group:nodes`	`nodes`, `computer`
`group:agents`	`agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `skill_workshop`
`group:media`	`image`, `image_generate`, `music_generate`, `video_generate`, `tts`
`group:openclaw`	เครื่องมือ OpenClaw ในตัวส่วนใหญ่ (ไม่รวมเครื่องมือพื้นฐานด้านระบบไฟล์และรันไทม์ `read`/`write`/`edit`/`apply_patch`/`exec`/`process`, `canvas` และ Plugin ของผู้ให้บริการ)
`group:plugins`	เครื่องมือทั้งหมดที่เป็นของ Plugin ซึ่งโหลดแล้ว รวมถึงเซิร์ฟเวอร์ MCP ที่กำหนดค่าและเปิดเผยผ่าน `bundle-mcp`

สำหรับเอเจนต์แบบอ่านอย่างเดียว ให้ปฏิเสธ group:runtime รวมถึงเครื่องมือระบบไฟล์ที่แก้ไขข้อมูลได้ เว้นแต่นโยบายระบบไฟล์ของแซนด์บ็อกซ์หรือขอบเขตโฮสต์แยกต่างหากจะบังคับใช้ข้อจำกัดแบบอ่านอย่างเดียว

สำหรับเซิร์ฟเวอร์ MCP ที่อยู่ในแซนด์บ็อกซ์ นโยบายเครื่องมือในแซนด์บ็อกซ์เป็นเกตการอนุญาตชั้นที่สอง หากกำหนดค่า mcp.servers แล้ว แต่รอบการทำงานในแซนด์บ็อกซ์แสดงเฉพาะเครื่องมือในตัว ให้เพิ่ม bundle-mcp, group:plugins หรือชื่อ/รูปแบบชื่อเครื่องมือ MCP ที่มีคำนำหน้าเซิร์ฟเวอร์ เช่น outlook__send_mail หรือ outlook__* ลงใน tools.sandbox.tools.alsoAllow จากนั้นรีสตาร์ต/โหลด Gateway ใหม่และบันทึกรายการเครื่องมืออีกครั้ง รูปแบบชื่อเซิร์ฟเวอร์ใช้คำนำหน้าเซิร์ฟเวอร์ MCP ที่ปลอดภัยสำหรับผู้ให้บริการ: อักขระที่ไม่ใช่ [A-Za-z0-9_-] จะเปลี่ยนเป็น -, ชื่อที่ไม่ได้ขึ้นต้นด้วยตัวอักษรจะได้รับคำนำหน้า mcp- และคำนำหน้าที่ยาวหรือซ้ำกันอาจถูกตัดทอนหรือเติมคำต่อท้าย

ปัจจุบัน openclaw doctor ตรวจสอบโครงสร้างนี้สำหรับเซิร์ฟเวอร์ที่ OpenClaw จัดการใน mcp.servers เซิร์ฟเวอร์ MCP ที่โหลดจากแมนิเฟสต์ของ Plugin ที่รวมมาให้หรือ .mcp.json ของ Claude ใช้เกตแซนด์บ็อกซ์เดียวกัน แต่การวินิจฉัยนี้ยังไม่แจกแจงแหล่งที่มาเหล่านั้น ให้ใช้รายการอนุญาตเดียวกันหากเครื่องมือของเซิร์ฟเวอร์หายไปจากรอบการทำงานในแซนด์บ็อกซ์

สิทธิ์ระดับสูง: "ทำงานบนโฮสต์" สำหรับ exec เท่านั้น

สิทธิ์ระดับสูง ไม่ได้ ให้เครื่องมือเพิ่มเติม แต่มีผลต่อ exec เท่านั้น

หากคุณอยู่ในแซนด์บ็อกซ์ /elevated on (หรือ exec ที่มี elevated: true) จะทำงานนอกแซนด์บ็อกซ์ (อาจยังต้องได้รับการอนุมัติ)
ใช้ /elevated full เพื่อข้ามการอนุมัติ exec สำหรับเซสชัน
หากคุณกำลังทำงานโดยตรงอยู่แล้ว สิทธิ์ระดับสูงจะไม่มีผลโดยพฤตินัย (แต่ยังอยู่ภายใต้เกต)
สิทธิ์ระดับสูง ไม่ได้ จำกัดขอบเขตตาม Skills และ ไม่ สามารถข้ามการอนุญาต/ปฏิเสธเครื่องมือ
สิทธิ์ระดับสูงไม่ได้ให้สิทธิ์ข้ามโฮสต์โดยพลการจาก host=auto แต่จะเป็นไปตามกฎเป้าหมาย exec ปกติ และคง node ไว้เฉพาะเมื่อเป้าหมายที่กำหนดค่า/เป้าหมายของเซสชันเป็น node อยู่แล้ว
/exec แยกต่างหากจากสิทธิ์ระดับสูง โดยปรับเฉพาะค่าเริ่มต้นของ exec ต่อเซสชันสำหรับผู้ส่งที่ได้รับอนุญาต

เกต:

การเปิดใช้งาน: tools.elevated.enabled (และอาจใช้ agents.list[].tools.elevated.enabled)
รายการอนุญาตผู้ส่ง: tools.elevated.allowFrom.<provider> (และอาจใช้ agents.list[].tools.elevated.allowFrom.<provider>)

ดู โหมดสิทธิ์ระดับสูง

วิธีแก้ปัญหา "ถูกขังในแซนด์บ็อกซ์" ที่พบบ่อย

"เครื่องมือ X ถูกบล็อกโดยนโยบายเครื่องมือในแซนด์บ็อกซ์"

คีย์สำหรับการแก้ไข (เลือกหนึ่งรายการ):

ปิดใช้งานแซนด์บ็อกซ์: agents.defaults.sandbox.mode=off (หรือเฉพาะเอเจนต์ด้วย agents.list[].sandbox.mode=off)
อนุญาตเครื่องมือภายในแซนด์บ็อกซ์:
- นำเครื่องมือออกจาก tools.sandbox.tools.deny (หรือเฉพาะเอเจนต์ด้วย agents.list[].tools.sandbox.tools.deny)
- หรือเพิ่มเครื่องมือลงใน tools.sandbox.tools.allow (หรือรายการอนุญาตเฉพาะเอเจนต์)
ตรวจสอบรายการ agents/tool-policy ใน openclaw logs รายการนี้บันทึกโหมดแซนด์บ็อกซ์และระบุว่ากฎอนุญาตหรือปฏิเสธใดบล็อกเครื่องมือ

"ฉันคิดว่านี่คือเซสชันหลัก เหตุใดจึงอยู่ในแซนด์บ็อกซ์?"

ในโหมด "non-main" คีย์ของกลุ่ม/ช่องทาง ไม่ใช่ เซสชันหลัก ให้ใช้คีย์เซสชันหลัก (แสดงโดย sandbox explain) หรือเปลี่ยนโหมดเป็น "off"

เนื้อหาที่เกี่ยวข้อง

การใช้แซนด์บ็อกซ์ -- เอกสารอ้างอิงแซนด์บ็อกซ์ฉบับเต็ม (โหมด ขอบเขต แบ็กเอนด์ อิมเมจ)
แซนด์บ็อกซ์และเครื่องมือสำหรับหลายเอเจนต์ -- การแทนที่เฉพาะเอเจนต์และลำดับความสำคัญ
โหมดสิทธิ์ระดับสูง

Was this useful?