English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

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

OpenClaw có ba cơ chế điều khiển liên quan với nhau (nhưng khác nhau):

  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

Dùng trình kiểm tra để xem OpenClaw thực sự đang làm gì:

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

Nó in ra:

  • 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

Hộp cát được điều khiển bởi agents.defaults.sandbox.mode:

  • "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.

Xem Hộp cát để biết ma trận đầy đủ (phạm vi, mount workspace, image).

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

Có hai lớp quan trọng:

  • 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.*

Quy tắc kinh nghiệm:

  • 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)

Các chính sách công cụ (toàn cục, agent, hộp cát) hỗ trợ mục group:* mở rộng thành nhiều công cụ:

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

Các nhóm có sẵn:

  • 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âng quyền không cấp thêm công cụ; nó chỉ ảnh hưởng đến 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.

Các cổng:

  • 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>)

Xem Chế độ nâng quyền.

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"

Khóa sửa lỗi (chọn mộ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?"

Ở chế độ "non-main", khóa nhóm/kênh không phải là main. Dùng khóa phiên main (được hiển thị bởi sandbox explain) hoặc chuyển chế độ sang "off".

Liên quan