Cấu hình Multi-Agent Sandbox & Tools

Tổng quan

Mỗi Agent trong hệ thống đa Agent giờ có thể có riêng:

Cấu hình Sandbox (agents.list[].sandbox ghi đè agents.defaults.sandbox)
Giới hạn công cụ (tools.allow / tools.deny, cộng với agents.list[].tools)

Điều này cho phép các bạn chạy nhiều Agent với các mức độ bảo mật khác nhau:

Agent trợ lý cá nhân với quyền truy cập đầy đủ
Agent gia đình/công việc với công cụ bị giới hạn
Agent công khai chạy trong Sandbox

setupCommand nằm dưới sandbox.docker (toàn cục hoặc theo Agent) và chỉ chạy một lần khi container được tạo.

Xác thực (Auth) là theo từng Agent: mỗi Agent đọc từ auth store riêng của nó tại agentDir:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Thông tin xác thực không được chia sẻ giữa các Agent. Không bao giờ dùng chung agentDir cho nhiều Agent. Nếu muốn chia sẻ thông tin xác thực, hãy copy auth-profiles.json vào agentDir của Agent khác.

Để hiểu cách Sandbox hoạt động lúc runtime, xem Sandboxing. Để debug “tại sao bị chặn?”, xem Sandbox vs Tool Policy vs Elevated và openclaw sandbox explain.

Các ví dụ cấu hình

Ví dụ 1: Agent cá nhân + Agent gia đình bị giới hạn

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Personal Assistant",
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "name": "Family Bot",
        "workspace": "~/.openclaw/workspace-family",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "[email protected]"
        }
      }
    }
  ]
}

Kết quả:

Agent main: Chạy trên host, có quyền truy cập đầy đủ các công cụ
Agent family: Chạy trong Docker (một container cho mỗi Agent), chỉ có công cụ read

Ví dụ 2: Agent công việc với Sandbox dùng chung

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "sandbox": {
          "mode": "all",
          "scope": "shared",
          "workspaceRoot": "/tmp/work-sandboxes"
        },
        "tools": {
          "allow": ["read", "write", "apply_patch", "exec"],
          "deny": ["browser", "gateway", "discord"]
        }
      }
    ]
  }
}

Ví dụ 2b: Profile coding toàn cục + Agent chỉ nhắn tin

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

Kết quả:

Các Agent mặc định có công cụ coding
Agent support chỉ dùng cho nhắn tin (+ công cụ Slack)

Ví dụ 3: Các chế độ Sandbox khác nhau cho mỗi Agent

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main", // Mặc định toàn cục
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off" // Ghi đè: main không bao giờ bị sandbox
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all", // Ghi đè: public luôn bị sandbox
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

Thứ tự ưu tiên cấu hình

Khi có cả cấu hình toàn cục (agents.defaults.*) và cấu hình riêng cho Agent (agents.list[].*):

Cấu hình Sandbox

Cài đặt riêng cho Agent sẽ ghi đè cài đặt toàn cục:

agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

Lưu ý:

agents.list[].sandbox.{docker,browser,prune}.* ghi đè agents.defaults.sandbox.{docker,browser,prune}.* cho Agent đó (bị bỏ qua khi sandbox scope được giải quyết thành "shared").

Giới hạn công cụ

Thứ tự lọc là:

Tool profile (tools.profile hoặc agents.list[].tools.profile)
Provider tool profile (tools.byProvider[provider].profile hoặc agents.list[].tools.byProvider[provider].profile)
Chính sách công cụ toàn cục (tools.allow / tools.deny)
Chính sách công cụ Provider (tools.byProvider[provider].allow/deny)
Chính sách công cụ riêng cho Agent (agents.list[].tools.allow/deny)
Chính sách provider của Agent (agents.list[].tools.byProvider[provider].allow/deny)
Chính sách công cụ Sandbox (tools.sandbox.tools hoặc agents.list[].tools.sandbox.tools)
Chính sách công cụ Subagent (tools.subagents.tools, nếu có)

Mỗi cấp độ có thể giới hạn thêm các công cụ, nhưng không thể cấp lại các công cụ đã bị từ chối ở cấp độ trước. Nếu agents.list[].tools.sandbox.tools được đặt, nó sẽ thay thế tools.sandbox.tools cho Agent đó. Nếu agents.list[].tools.profile được đặt, nó sẽ ghi đè tools.profile cho Agent đó. Các key công cụ Provider chấp nhận provider (ví dụ google-antigravity) hoặc provider/model (ví dụ openai/gpt-5.2).

Nhóm công cụ (shorthands)

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

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ả công cụ OpenClaw tích hợp sẵn (không bao gồm plugin của provider)

Chế độ Elevated

tools.elevated là baseline toàn cục (allowlist dựa trên người gửi). agents.list[].tools.elevated có thể giới hạn thêm elevated cho các Agent cụ thể (cả hai phải cho phép).

Các pattern giảm thiểu rủi ro:

Từ chối exec cho các Agent không tin cậy (agents.list[].tools.deny: ["exec"])
Tránh cho phép các sender định tuyến đến các Agent bị giới hạn
Tắt elevated toàn cục (tools.elevated.enabled: false) nếu chỉ muốn thực thi trong Sandbox
Tắt elevated cho từng Agent (agents.list[].tools.elevated.enabled: false) cho các profile nhạy cảm

Migration từ Single Agent

Trước (single agent):

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["read", "write", "apply_patch", "exec"],
        "deny": []
      }
    }
  }
}

Sau (multi-agent với các profile khác nhau):

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    ]
  }
}

Các cấu hình agent.* cũ được migrate bởi openclaw doctor; nên dùng agents.defaults + agents.list từ giờ trở đi.

Các ví dụ giới hạn công cụ

Agent chỉ đọc

{
  "tools": {
    "allow": ["read"],
    "deny": ["exec", "write", "edit", "apply_patch", "process"]
  }
}

Agent thực thi an toàn (không sửa file)

{
  "tools": {
    "allow": ["read", "exec", "process"],
    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
  }
}

Agent chỉ giao tiếp

{
  "tools": {
    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
  }
}

Lỗi thường gặp: “non-main”

agents.defaults.sandbox.mode: "non-main" dựa trên session.mainKey (mặc định là "main"), không phải agent id. Các Session nhóm/channel luôn có key riêng, nên chúng được coi là non-main và sẽ bị sandbox. Nếu muốn một Agent không bao giờ bị sandbox, hãy đặt agents.list[].sandbox.mode: "off".

Kiểm tra

Sau khi cấu hình multi-agent sandbox và tools:

Kiểm tra agent resolution:
```
openclaw agents list --bindings
```
Xác minh sandbox containers:
```
docker ps --filter "name=openclaw-sbx-"
```
Test giới hạn công cụ:
- Gửi một tin nhắn yêu cầu các công cụ bị giới hạn
- Xác minh Agent không thể dùng các công cụ bị từ chối

Theo dõi logs:

tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

Troubleshooting

Agent không bị sandbox mặc dù đặt `mode: "all"`

Kiểm tra xem có agents.defaults.sandbox.mode toàn cục ghi đè nó không
Cấu hình riêng cho Agent được ưu tiên, nên đặt agents.list[].sandbox.mode: "all"

Công cụ vẫn khả dụng mặc dù có deny list

Kiểm tra thứ tự lọc công cụ: toàn cục → Agent → Sandbox → subagent
Mỗi cấp độ chỉ có thể giới hạn thêm, không thể cấp lại
Xác minh bằng logs: [tools] filtering tools for agent:${agentId}

Container không được cô lập theo Agent

Đặt scope: "agent" trong cấu hình Sandbox riêng cho Agent
Mặc định là "session" tạo một container cho mỗi Session