Sandbox vs Tool Policy vs Elevated

OpenClaw có ba cơ chế kiểm soát liên quan (nhưng khác nhau):

Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) quyết định tool chạy ở đâu (Docker hay host).
Tool policy (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) quyết định tool nào được phép dùng.
Elevated (tools.elevated.*, agents.list[].tools.elevated.*) là lối thoát chỉ dành cho exec để chạy trên host khi các bạn đang ở trong sandbox.

Debug nhanh

Dùng inspector để xem OpenClaw đang làm gì:

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

Lệnh này sẽ hiển thị:

Sandboxing được điều khiển bởi agents.defaults.sandbox.mode:

"off": mọi thứ chạy trên host.
"non-main": chỉ non-main sessions bị sandbox (thường gây “bất ngờ” với groups/channels).
"all": mọi thứ đều bị sandbox.

Xem Sandboxing để biết chi tiết đầy đủ (scope, workspace mounts, images).

docker.binds xuyên thủng filesystem của sandbox: bất cứ thứ gì các bạn mount sẽ hiển thị bên trong container với mode đã set (:ro hoặc :rw).
Mặc định là read-write nếu bỏ qua mode; nên dùng :ro cho source/secrets.
scope: "shared" bỏ qua per-agent binds (chỉ global binds có hiệu lực).
Binding /var/run/docker.sock thực tế là trao quyền kiểm soát host cho sandbox; chỉ làm điều này khi có chủ đích.
Workspace access (workspaceAccess: "ro"/"rw") độc lập với bind modes.

Có hai lớp quan trọng:

Tool profile: tools.profile và agents.list[].tools.profile (allowlist cơ bản)
Provider tool profile: tools.byProvider[provider].profile và agents.list[].tools.byProvider[provider].profile
Global/per-agent tool policy: tools.allow/tools.deny và agents.list[].tools.allow/agents.list[].tools.deny
Provider tool policy: tools.byProvider[provider].allow/deny và agents.list[].tools.byProvider[provider].allow/deny
Sandbox tool policy (chỉ áp dụng khi bị sandbox): tools.sandbox.tools.allow/tools.sandbox.tools.deny và agents.list[].tools.sandbox.tools.*

Nguyên tắc cơ bản:

deny luôn thắng.
Nếu allow không rỗng, mọi thứ khác sẽ bị coi là blocked.
Tool policy là điểm dừng cứng: /exec không thể override một exec tool bị denied.
/exec chỉ thay đổi session defaults cho authorized senders; nó không cấp quyền truy cập tool. Provider tool keys chấp nhận provider (ví dụ google-antigravity) hoặc provider/model (ví dụ openai/gpt-5.2).

Tool policies (global, agent, sandbox) hỗ trợ các entry group:* mở rộng thành nhiều tools:

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

Các groups có sẵn:

group:runtime: exec, bash, process
group:fs: read, write, edit, apply_patch
group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
group:memory: memory_search, memory_get
group:ui: browser, canvas
group:automation: cron, gateway
group:messaging: message
group:nodes: nodes
group:openclaw: tất cả built-in OpenClaw tools (không bao gồm provider plugins)

Elevated không cấp thêm tools; nó chỉ ảnh hưởng đến exec.

Nếu các bạn đang bị sandbox, /elevated on (hoặc exec với elevated: true) sẽ chạy trên host (vẫn có thể cần approvals).
Dùng /elevated full để bỏ qua exec approvals cho session.
Nếu các bạn đã chạy direct rồi, elevated thực tế là no-op (vẫn bị gated).
Elevated không phải skill-scoped và không override tool allow/deny.
/exec tách biệt với elevated. Nó chỉ điều chỉnh per-session exec defaults cho authorized senders.

Gates:

Enablement: tools.elevated.enabled (và tùy chọn agents.list[].tools.elevated.enabled)
Sender allowlists: tools.elevated.allowFrom.<provider> (và tùy chọn agents.list[].tools.elevated.allowFrom.<provider>)

Các key để fix (chọn một):

Tắt sandbox: agents.defaults.sandbox.mode=off (hoặc per-agent agents.list[].sandbox.mode=off)
Cho phép tool bên trong sandbox:
- xóa nó khỏi tools.sandbox.tools.deny (hoặc per-agent agents.list[].tools.sandbox.tools.deny)
- hoặc thêm nó vào tools.sandbox.tools.allow (hoặc per-agent allow)

Ở mode "non-main", group/channel keys không phải main. Dùng main session key (hiển thị bởi sandbox explain) hoặc chuyển mode sang "off".