Môi trường cô lập so với chính sách công cụ so với quyền nâng cao

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

1. Hộp cát (agents.defaults.sandbox.* / agents.list[].sandbox.*) quyết định công cụ chạy ở đâu (backend hộp cát hay máy chủ).
2. Chính sách công cụ (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) quyết định những công cụ nào có sẵn/được phép dùng.
3. Nâng quyền (tools.elevated.*, agents.list[].tools.elevated.*) là một lối thoát chỉ dành cho exec để chạy bên ngoài hộp cát khi bạn đang ở trong hộp cát (gateway theo mặc định, hoặc node khi mục tiêu exec được cấu hình thành node).

​

Gỡ lỗi nhanh

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

• chế độ/phạm vi/quyền truy cập workspace hiệu lực của hộp cát
• liệu phiên hiện tại có đang ở trong hộp cát hay không (main so với non-main)
• allow/deny công cụ hộp cát hiệu lực (và nó đến từ agent/global/default hay không)
• các cổng nâng quyền và đường dẫn khóa sửa lỗi

​

Hộp cát: công cụ chạy ở đâu

• "off": mọi thứ chạy trên máy chủ.
• "non-main": chỉ các phiên non-main được đưa vào hộp cát (điểm thường gây “bất ngờ” cho nhóm/kênh).
• "all": mọi thứ đều được đưa vào hộp cát.

​

Bind mount (kiểm tra nhanh về bảo mật)

• docker.binds xuyên qua hệ thống tệp của hộp cát: bất cứ thứ gì bạn mount đều hiển thị bên trong container với chế độ bạn đặt (:ro hoặc :rw).
• Mặc định là đọc-ghi nếu bạn bỏ qua chế độ; nên dùng :ro cho mã nguồn/bí mật.
• scope: "shared" bỏ qua bind theo từng agent (chỉ áp dụng bind toàn cục).
• OpenClaw xác thực nguồn bind hai lần: lần đầu trên đường dẫn nguồn đã chuẩn hóa, rồi lần nữa sau khi phân giải qua ancestor tồn tại sâu nhất. Việc thoát qua symlink ở thư mục cha không vượt qua được kiểm tra blocked-path hoặc allowed-root.
• Các đường dẫn lá không tồn tại vẫn được kiểm tra an toàn. Nếu /workspace/alias-out/new-file phân giải qua một thư mục cha là symlink tới một đường dẫn bị chặn hoặc ra ngoài các allowed root đã cấu hình, bind sẽ bị từ chối.
• Bind /var/run/docker.sock thực chất trao quyền điều khiển máy chủ cho hộp cát; chỉ làm việc này khi có chủ đích.
• Quyền truy cập workspace (workspaceAccess: "ro"/"rw") độc lập với chế độ bind.

​

Chính sách công cụ: công cụ nào tồn tại/có thể gọi

• Hồ sơ công cụ: tools.profile và agents.list[].tools.profile (allowlist cơ sở)
• Hồ sơ công cụ của provider: tools.byProvider[provider].profile và agents.list[].tools.byProvider[provider].profile
• Chính sách công cụ toàn cục/theo agent: tools.allow/tools.deny và agents.list[].tools.allow/agents.list[].tools.deny
• Chính sách công cụ của provider: tools.byProvider[provider].allow/deny và agents.list[].tools.byProvider[provider].allow/deny
• Chính sách công cụ hộp cát (chỉ áp dụng khi đang trong hộp cát): tools.sandbox.tools.allow/tools.sandbox.tools.deny và agents.list[].tools.sandbox.tools.*

• deny luôn thắng.
• Nếu allow không rỗng, mọi thứ khác được xem là bị chặn.
• Chính sách công cụ là điểm chặn cứng: /exec không thể ghi đè một công cụ exec đã bị từ chối.
• /exec chỉ thay đổi mặc định của phiên cho người gửi được ủy quyền; nó không cấp quyền truy cập công cụ. Khóa công cụ của provider chấp nhận cả provider (ví dụ google-antigravity) hoặc provider/model (ví dụ openai/gpt-5.4).

​

Nhóm công cụ (cách viết tắt)

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

• group:runtime: exec, process, code_execution (bash được chấp nhận làm bí danh cho 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
• group:agents: agents_list, update_plan
• group:media: image, image_generate, music_generate, video_generate, tts
• group:openclaw: tất cả công cụ tích hợp sẵn của OpenClaw (không bao gồm Plugin của provider)

​

Nâng quyền: “chạy trên máy chủ” chỉ dành cho exec

• Nếu bạn đang ở trong hộp cát, /elevated on (hoặc exec với elevated: true) sẽ chạy bên ngoài hộp cát (phê duyệt vẫn có thể áp dụng).
• Dùng /elevated full để bỏ qua phê duyệt exec cho phiên.
• Nếu bạn đã chạy trực tiếp, nâng quyền thực chất không có tác dụng (vẫn bị cổng kiểm soát).
• Nâng quyền không theo phạm vi skill và không ghi đè allow/deny của công cụ.
• Nâng quyền không cấp ghi đè tùy ý xuyên máy chủ từ host=auto; nó tuân theo các quy tắc mục tiêu exec bình thường và chỉ giữ node khi mục tiêu đã cấu hình/của phiên đã là node.
• /exec tách biệt với nâng quyền. Nó chỉ điều chỉnh mặc định exec theo từng phiên cho người gửi được ủy quyền.

• Bật tính năng: tools.elevated.enabled (và tùy chọn agents.list[].tools.elevated.enabled)
• Allowlist người gửi: tools.elevated.allowFrom.<provider> (và tùy chọn agents.list[].tools.elevated.allowFrom.<provider>)

​

Cách sửa lỗi “kẹt trong hộp cát” thường gặp

​

”Công cụ X bị chặn bởi chính sách công cụ hộp cát”

• Tắt hộp cát: agents.defaults.sandbox.mode=off (hoặc theo từng agent agents.list[].sandbox.mode=off)
• Cho phép công cụ bên trong hộp cát:
  • xóa công cụ đó khỏi tools.sandbox.tools.deny (hoặc theo từng agent agents.list[].tools.sandbox.tools.deny)
  • hoặc thêm nó vào tools.sandbox.tools.allow (hoặc allow theo từng agent)

​

“Tôi tưởng đây là main, tại sao nó lại ở trong hộp cát?”

​

Liên quan

• Hộp cát — tham chiếu đầy đủ về hộp cát (chế độ, phạm vi, backend, image)
• Hộp cát và công cụ đa agent — ghi đè và thứ tự ưu tiên theo từng agent
• Chế độ nâng quyền