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`, `sessions_list`, `sessions_history`, `sessions_search`, `conversations_list`, `conversations_send`, `conversations_turn`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`, `spawn_task`, `dismiss_task`
`group:memory`	`memory_search`, `memory_get`
`group:web`	`web_search`, `x_search`, `web_fetch`
`group:ui`	`browser`, `screen`, `terminal`, `canvas`, `show_widget`
`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`, `ask_user`, `skill_workshop`
`group:media`	`image`, `image_generate`, `music_generate`, `video_generate`, `tts`
`group:openclaw`	เครื่องมือ OpenClaw ในตัวส่วนใหญ่ (ไม่รวมองค์ประกอบพื้นฐาน fs และรันไทม์ `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 แบบรวมชุดหรือ Claude .mcp.json ใช้ด่านแซนด์บ็อกซ์เดียวกัน แต่การวินิจฉัยนี้ยังไม่แจกแจงแหล่งข้อมูลเหล่านั้น หากเครื่องมือของแหล่งดังกล่าวหายไปในเทิร์นที่อยู่ในแซนด์บ็อกซ์ ให้ใช้รายการในรายการอนุญาตแบบเดียวกัน

สิทธิ์ยกระดับ: "เรียกใช้บนโฮสต์" สำหรับ 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?