Hộp cát và công cụ đa tác nhân

Mỗi agent trong cấu hình đa agent có thể ghi đè chính sách sandbox và công cụ toàn cục. Trang này trình bày cấu hình theo từng agent, quy tắc ưu tiên và các ví dụ.

Sandbox

Backend và chế độ — tài liệu tham khảo đầy đủ về sandbox.

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

Gỡ lỗi “tại sao thao tác này bị chặn?”

Chế độ nâng quyền

Thực thi nâng quyền cho người gửi đáng tin cậy.

Xác thực được giới hạn theo agent: mỗi agent có kho lưu trữ xác thực agentDir riêng tại ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Tuyệt đối không dùng lại agentDir cho nhiều agent. Agent có thể đọc các hồ sơ xác thực của agent mặc định/chính khi không có hồ sơ cục bộ, nhưng token làm mới OAuth không được sao chép vào kho lưu trữ của agent phụ. Nếu sao chép thông tin xác thực theo cách thủ công, chỉ sao chép các hồ sơ api_key hoặc token tĩnh có tính di động.

---

​

Ví dụ cấu hình

Ví dụ 1: Agent cá nhân + agent gia đình bị hạn chế

{
  "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", "message"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"],
          "message": {
            "crossContext": {
              "allowWithinProvider": false,
              "allowAcrossProviders": false
            }
          }
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "[e-mail]"
        }
      }
    }
  ]
}

Kết quả:

• Agent main: chạy trên máy chủ, có toàn quyền truy cập công cụ.
• Agent family: chạy trong Docker (mỗi agent một container), chỉ có thể dùng read và gửi tin nhắn trong cuộc trò chuyện hiện tại.

Ví dụ 2: Agent công việc dùng sandbox 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: Hồ sơ lập trình 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 nhận công cụ lập trình.
• Agent support chỉ có thể nhắn tin (+ công cụ Slack).

Ví dụ 3: Chế độ sandbox khác nhau cho từng agent

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off"
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

---

​

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

Khi đồng thời tồn tại 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

Thiết lập riêng cho agent ghi đè thiết lập 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.*

agents.list[].sandbox.{docker,browser,prune}.* ghi đè agents.defaults.sandbox.{docker,browser,prune}.* cho agent đó (bị bỏ qua khi phạm vi sandbox được xác định là "shared").

​

Hạn chế công cụ

Thứ tự lọc như sau:

1. Hồ sơ công cụ

   tools.profile hoặc agents.list[].tools.profile.

2. Hồ sơ công cụ của nhà cung cấp

   tools.byProvider[provider].profile hoặc agents.list[].tools.byProvider[provider].profile.

3. Chính sách công cụ toàn cục

   tools.allow / tools.deny.

4. Chính sách công cụ của nhà cung cấp

   tools.byProvider[provider].allow/deny.

5. Chính sách công cụ riêng cho agent

   agents.list[].tools.allow/deny.

6. Chính sách nhà cung cấp của agent

   agents.list[].tools.byProvider[provider].allow/deny.

7. Chính sách công cụ sandbox

   tools.sandbox.tools hoặc agents.list[].tools.sandbox.tools.

8. Chính sách công cụ của agent phụ

   tools.subagents.tools, nếu áp dụng.

Quy tắc ưu tiên

• Mỗi cấp có thể hạn chế thêm các công cụ, nhưng không thể cấp lại những công cụ đã bị từ chối ở các cấp trước.
• Nếu đặt agents.list[].tools.sandbox.tools, giá trị này sẽ thay thế tools.sandbox.tools cho agent đó.
• Nếu đặt agents.list[].tools.profile, giá trị này sẽ ghi đè tools.profile cho agent đó.
• Khóa công cụ của nhà cung cấp chấp nhận cả provider (ví dụ: google-antigravity) hoặc provider/model (ví dụ: openai/gpt-5.4).

Hành vi khi danh sách cho phép trống

Nếu bất kỳ danh sách cho phép tường minh nào trong chuỗi đó khiến lượt chạy không còn công cụ nào có thể gọi, OpenClaw sẽ dừng trước khi gửi lời nhắc đến mô hình. Đây là hành vi có chủ đích: một agent được cấu hình với công cụ không tồn tại, chẳng hạn agents.list[].tools.allow: ["query_db"], phải báo lỗi rõ ràng cho đến khi Plugin đăng ký query_db được bật, thay vì tiếp tục hoạt động như một agent chỉ xử lý văn bản.

Chính sách công cụ hỗ trợ các dạng viết tắt group:*, được mở rộng thành nhiều công cụ. Xem Nhóm công cụ để biết danh sách đầy đủ.

Các ghi đè nâng quyền theo từng agent (agents.list[].tools.elevated) có thể hạn chế thêm quyền thực thi nâng quyền cho những agent cụ thể. Xem Chế độ nâng quyền để biết chi tiết.

---

​

Di chuyển từ một agent

Trước đây (một agent)

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

Sau khi chuyển đổi (đa agent)

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

Các khóa cấu hình agents.defaults.*/agents.list[].* cũ (chẳng hạn sandbox.perSession, agentRuntime, embeddedPi) được openclaw doctor di chuyển; từ nay nên ưu tiên dùng agents.defaults + agents.list.

---

​

Ví dụ hạn chế công cụ

Agent chỉ đọc

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

Thực thi shell khi các công cụ hệ thống tệp bị vô hiệu hóa

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

Chính sách này vô hiệu hóa các công cụ hệ thống tệp của OpenClaw, nhưng exec vẫn là một shell và có thể ghi tệp ở bất kỳ nơi nào mà hệ thống tệp của máy chủ hoặc sandbox đã chọn cho phép. Đối với agent chỉ đọc, hãy từ chối exec và process, hoặc kết hợp quyền truy cập shell với các biện pháp kiểm soát hệ thống tệp của sandbox như agents.defaults.sandbox.workspaceAccess: "ro" hoặc "none".

Chỉ giao tiếp

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

sessions_history trong hồ sơ này vẫn trả về chế độ xem truy hồi đã được làm sạch và giới hạn, thay vì kết xuất bản ghi hội thoại thô. Chức năng truy hồi của trợ lý loại bỏ các thẻ suy luận, cấu trúc khung <relevant-memories>, tải trọng XML dạng văn bản thuần của lệnh gọi công cụ (bao gồm <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> và các khối lệnh gọi công cụ bị cắt ngắn), cấu trúc khung lệnh gọi công cụ bị hạ cấp, các token điều khiển mô hình ASCII/toàn chiều rộng bị rò rỉ và XML lệnh gọi công cụ MiniMax không đúng định dạng trước khi che thông tin/cắt ngắn.

---

​

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

agents.defaults.sandbox.mode: "non-main" kiểm tra khóa phiên dựa trên khóa phiên chính (luôn là "main"; người dùng không thể cấu hình session.mainKey, đồng thời OpenClaw sẽ cảnh báo và bỏ qua mọi giá trị khác), chứ không phải mã định danh agent. Các phiên nhóm/kênh luôn có khóa riêng, vì vậy chúng được coi là không phải phiên chính và sẽ chạy trong sandbox. Nếu muốn một agent không bao giờ chạy trong sandbox, hãy đặt agents.list[].sandbox.mode: "off".

---

​

Kiểm thử

Sau khi cấu hình sandbox và công cụ cho nhiều agent:

1. Kiểm tra việc phân giải agent

   openclaw agents list --bindings
   
2. Xác minh các container sandbox

   docker ps --filter "name=openclaw-sbx-"
   
3. Kiểm thử các hạn chế công cụ

   • Gửi một tin nhắn yêu cầu các công cụ bị hạn chế.
   • Xác minh rằng agent không thể sử dụng các công cụ bị từ chối.
4. Theo dõi nhật ký

   openclaw logs --follow | grep -E "routing|sandbox|tools"
   

---

​

Khắc phục sự cố

Agent không chạy trong sandbox dù đã đặt `mode: 'all'`

• Kiểm tra xem có agents.defaults.sandbox.mode toàn cục ghi đè thiết lập này hay không.
• Cấu hình riêng cho agent được ưu tiên, vì vậy hãy đặt agents.list[].sandbox.mode: "all".

Các công cụ vẫn khả dụng dù có trong danh sách từ chối

• Kiểm tra toàn bộ thứ tự lọc: hồ sơ → hồ sơ nhà cung cấp → chính sách toàn cục → chính sách nhà cung cấp → chính sách tác tử → chính sách nhà cung cấp của tác tử → sandbox → tác tử con.
• Mỗi cấp chỉ có thể hạn chế thêm, không thể cấp lại quyền.
• Xem Sandbox so với chính sách công cụ và chế độ đặc quyền để gỡ lỗi từng bước.

Vùng chứa không được cô lập theo từng tác tử

• scope mặc định là "agent" (mỗi mã định danh tác tử có một vùng chứa).
• Đặt scope: "session" để mỗi phiên có một vùng chứa, hoặc scope: "shared" để dùng lại một vùng chứa cho nhiều tác tử.

---

​

Liên quan

• Chế độ đặc quyền
• Định tuyến đa tác tử
• Cấu hình sandbox
• Sandbox so với chính sách công cụ và chế độ đặc quyền — gỡ lỗi “tại sao thao tác này bị chặn?”
• Cơ chế sandbox — tài liệu tham khảo đầy đủ về sandbox (chế độ, phạm vi, phần phụ trợ, ảnh)
• Quản lý phiên