Sandbox so với chính sách công cụ so với quyền nâng cao

1. Môi trường cách ly (agents.defaults.sandbox.* / agents.list[].sandbox.*) quyết định công cụ chạy ở đâu (phần nền môi trường cách ly hay host).
2. Chính sách công cụ (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) quyết định công cụ nào có sẵn/được phép dùng.
3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) là một lối thoát chỉ dành cho exec để chạy bên ngoài môi trường cách ly khi bạn đang bị cách ly (gateway theo mặc định, hoặc node khi đích exec được cấu hình là 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/truy cập workspace hiệu lực của môi trường cách ly
• phiên hiện có đang bị cách ly hay không (main so với không phải main)
• allow/deny công cụ trong môi trường cách ly hiệu lực (và nó đến từ agent/global/default hay không)
• các cổng elevated và đường dẫn khóa để sửa

​

Môi trường cách ly: công cụ chạy ở đâu

• "off": mọi thứ chạy trên host.
• "non-main": chỉ các phiên không phải main bị cách ly (điểm thường gây “bất ngờ” cho nhóm/kênh).
• "all": mọi thứ đều bị cách ly.

​

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

• docker.binds xuyên qua hệ thống tệp của môi trường cách ly: 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ế độ; ưu tiên :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: đầu tiên trên đường dẫn nguồn đã chuẩn hóa, sau đó lần nữa sau khi phân giải qua tổ tiên sâu nhất đang tồn tại. Việc thoát qua cha là symlink không vượt qua được kiểm tra đường dẫn bị chặn hoặc gốc được phép.
• 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 cha là symlink tới đường dẫn bị chặn hoặc ra ngoài các gốc được phép đã cấu hình, bind sẽ bị từ chối.
• Bind /var/run/docker.sock thực chất trao quyền kiểm soát host cho môi trường cách ly; chỉ làm việc này một cách 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ụ theo 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ụ theo provider: tools.byProvider[provider].allow/deny và agents.list[].tools.byProvider[provider].allow/deny
• Chính sách công cụ trong môi trường cách ly (chỉ áp dụng khi bị cách ly): 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.
• Chính sách công cụ lọc khả dụng của công cụ theo tên; nó không kiểm tra tác dụng phụ bên trong exec. Nếu exec được phép, việc từ chối write, edit, hoặc apply_patch không làm cho lệnh shell trở thành chỉ đọc.
• /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ụ theo provider chấp nhận provider (ví dụ google-antigravity) hoặc provider/model (ví dụ openai/gpt-5.4).
• Nhật ký Gateway bao gồm các mục kiểm toán agents/tool-policy khi một bước chính sách công cụ loại bỏ công cụ hoặc một chính sách công cụ trong môi trường cách ly chặn một lệnh gọi. Dùng openclaw logs để xem nhãn quy tắc, khóa cấu hình và tên công cụ bị ảnh hưởng.

​

Nhóm công cụ (dạng 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 Với agent chỉ đọc, hãy từ chối group:runtime cũng như các công cụ hệ thống tệp có thể thay đổi dữ liệu, trừ khi chính sách hệ thống tệp của môi trường cách ly hoặc một ranh giới host riêng thực thi ràng buộc chỉ đọc.
• 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ụ OpenClaw tích hợp sẵn (không bao gồm Plugin provider)
• group:plugins: tất cả công cụ thuộc Plugin đã tải, bao gồm các máy chủ MCP đã cấu hình được phơi bày qua bundle-mcp

​

Elevated: “chạy trên host” chỉ dành cho exec

• Nếu bạn đang bị cách ly, /elevated on (hoặc exec với elevated: true) chạy bên ngoài môi trường cách ly (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, elevated thực tế là không có tác dụng (vẫn bị kiểm soát bởi cổng).
• Elevated không bị giới hạn theo Skills và không ghi đè allow/deny của công cụ.
• Elevated không cấp quyền ghi đè xuyên host tùy ý từ host=auto; nó tuân theo các quy tắc đích exec thông thường và chỉ giữ node khi đích đã cấu hình/của phiên đã là node.
• /exec tách biệt với elevated. 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ác cách sửa “kẹt trong môi trường cách ly” thường gặp

​

“Công cụ X bị chặn bởi chính sách công cụ trong môi trường cách ly”

• Tắt môi trường cách ly: 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 môi trường cách ly:
  • xóa nó 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)
• Kiểm tra openclaw logs để tìm mục agents/tool-policy. Nó ghi lại chế độ môi trường cách ly và quy tắc allow hay deny đã chặn công cụ.

​

“Tôi nghĩ đây là main, tại sao nó lại bị cách ly?”

​

Liên quan

• Cơ chế cách ly — tài liệu tham chiếu đầy đủ về môi trường cách ly (chế độ, phạm vi, phần nền, image)
• Môi trường cách ly & Công cụ đa agent — ghi đè và thứ tự ưu tiên theo từng agent
• Chế độ Elevated