Môi trường cách ly và công cụ đa tác nhân

Mỗi agent trong một thiết lập đa agent có thể ghi đè sandbox và chính sách 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à ví dụ.

Sandboxing

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

Sandbox vs tool policy vs elevated

Gỡ lỗi “tại sao nội dung này bị chặn?”

Elevated mode

Exec 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 xác thực agentDir riêng tại ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. Không bao giờ dùng lại agentDir giữa các agent. Agent có thể đọc xuyên tới hồ sơ xác thực của agent mặc định/chính khi chúng 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 agent phụ. Nếu bạn sao chép thông tin xác thực 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

Example 1: Personal + restricted family agent

{
  "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ột container cho mỗi agent), chỉ có read và gửi tin nhắn trong cuộc trò chuyện hiện tại.

Example 2: Work agent with shared sandbox

{
  "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"]
        }
      }
    ]
  }
}

Example 2b: Global coding profile + messaging-only agent

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

Kết quả:

• agent mặc định nhận các công cụ lập trình.
• agent support chỉ dành cho nhắn tin (+ công cụ Slack).

Example 3: Different sandbox modes per 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 cả cấu hình toàn cục (agents.defaults.*) và cấu hình riêng cho agent (agents.list[].*) cùng tồn tại:

​

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 phân giải thành "shared").

​

Hạn chế công cụ

Thứ tự lọc là:

1. Tool profile

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

2. Provider tool profile

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

3. Global tool policy

   tools.allow / tools.deny.

4. Provider tool policy

   tools.byProvider[provider].allow/deny.

5. Agent-specific tool policy

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

6. Agent provider policy

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

7. Sandbox tool policy

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

8. Subagent tool policy

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

Precedence rules

• Mỗi cấp có thể hạn chế thêm công cụ, nhưng không thể cấp lại các công cụ đã bị từ chối ở các 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 đó.
• Khóa công cụ của provider chấp nhận provider (ví dụ google-antigravity) hoặc provider/model (ví dụ openai/gpt-5.4).

Empty allowlist behavior

Nếu bất kỳ allowlist rõ ràng 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 prompt cho model. Đây là hành vi có chủ đích: một agent được cấu hình với công cụ bị thiếu như agents.list[].tools.allow: ["query_db"] nên thất bại rõ ràng cho đến khi Plugin đăng ký query_db được bật, thay vì tiếp tục như một agent chỉ dùng văn bản.

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

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

---

​

Di chuyển từ một tác tử

Trước (một tác tử)

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

Sau (đa tác tử)

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

Các cấu hình agent.* cũ được di chuyển bằng openclaw doctor; từ nay nên dùng agents.defaults + agents.list.

---

​

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

Tác tử chỉ đọc

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

Thực thi shell khi công cụ hệ thống tệp bị tắt

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

Chính sách này tắt 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 cứ nơi nào máy chủ đã chọn hoặc hệ thống tệp sandbox cho phép. Với tác tử 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 kiểm soát hệ thống tệp 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ề một chế độ xem nhớ lại có giới hạn và đã được làm sạch, thay vì bản đổ transcript thô. Việc nhớ lại của trợ lý loại bỏ các thẻ suy nghĩ, khung <relevant-memories>, payload XML gọi công cụ dạng văn bản thuần (bao gồm <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls>, và các khối gọi công cụ đã bị cắt ngắn), khung gọi công cụ bị hạ cấp, token điều khiển mô hình ASCII/toàn chiều rộng bị rò rỉ, và XML gọi công cụ MiniMax sai định dạng trước khi biên tập/cắt ngắn.

---

​

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

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

---

​

Kiểm thử

Sau khi cấu hình sandbox và công cụ đa tác tử:

1. Kiểm tra phân giải tác tử

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

   docker ps --filter "name=openclaw-sbx-"
   
3. Kiểm tra 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 tác tử không thể dùng các công cụ bị từ chối.
4. Theo dõi log

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

---

​

Khắc phục sự cố

Tác tử không bị sandbox dù có `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 của tác tử được ưu tiên, nên hãy đặt agents.list[].sandbox.mode: "all".

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

• Kiểm tra thứ tự lọc công cụ: toàn cục → 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.
• Xác minh bằng log: [tools] filtering tools for agent:${agentId}.

Container không được cô lập theo từng tác tử

• Đặt scope: "agent" trong cấu hình sandbox riêng của tác tử.
• Mặc định là "session", tạo một container cho mỗi phiên.

---

​

Liên quan

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