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

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

Cơ chế hộp cát

Phần phụ trợ và chế độ — tài liệu tham khảo đầy đủ về 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 việ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 tác nhân: mỗi tác nhân 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 tác nhân. Tác nhân có thể đọc xuyên tới hồ sơ xác thực của tác nhân mặc định/chính khi chúng không có hồ sơ cục bộ, nhưng mã làm mới OAuth không được sao chép vào kho của tác nhân phụ. Nếu bạn 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ó thể di chuyển.

Ví dụ cấu hình

Ví dụ 1: Tác nhân cá nhân + tác nhân 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"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "120363424282127706@g.us"
        }
      }
    }
  ]
}

Kết quả:

Tác nhân main: chạy trên máy chủ, có quyền truy cập đầy đủ vào công cụ.
Tác nhân family: chạy trong Docker (một vùng chứa cho mỗi tác nhân), chỉ có công cụ read.

Ví dụ 2: Tác nhân công việc với hộp cát 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: Hồ sơ lập trình toàn cục + tác nhân chỉ nhắn tin

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

Kết quả:

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

Ví dụ 3: Các chế độ hộp cát khác nhau theo từng tác nhân

{
  "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 tác nhân (agents.list[].*) đều tồn tại:

Cấu hình hộp cát

Các thiết lập riêng cho tác nhân 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 tác nhân đó (bị bỏ qua khi phạm vi hộp cát phân giải thành "shared").

Hạn chế công cụ

Thứ tự lọc là:

Hồ sơ công cụ

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

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

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ụ của nhà cung cấp

tools.byProvider[provider].allow/deny.

Chính sách công cụ riêng cho tác nhân

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

Chính sách nhà cung cấp của tác nhân

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

Chính sách công cụ hộp cát

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

Chính sách công cụ của tác nhân con

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

Quy tắc ưu tiên

Mỗi cấp có thể tiếp tục hạn chế 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ó thay thế tools.sandbox.tools cho tác nhân đó.
Nếu agents.list[].tools.profile được đặt, nó ghi đè tools.profile cho tác nhân đó.
Khóa công cụ của nhà cung cấp chấp nhận provider (ví dụ google-antigravity) hoặc provider/model (ví dụ openai/gpt-5.4).

Hành vi 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ần 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 tới mô hình. Đây là chủ ý: một tác nhân được cấu hình với công cụ còn thiếu như agents.list[].tools.allow: ["query_db"] phải 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 tác nhân chỉ 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 đủ. Các ghi đè nâng quyền theo từng tác nhân (agents.list[].tools.elevated) có thể hạn chế thêm thực thi nâng quyền cho các tác nhân cụ thể. Xem Chế độ nâng quyền để biết chi tiết.

Di chuyển từ tác nhân đơn

Trước (tác nhân đơn)
Sau (đa tác nhân)

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

{
  "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ởi openclaw doctor; từ nay trở đi nên dùng agents.defaults + agents.list.

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

Tác nhân chỉ đọc
Thực thi an toàn (không sửa đổi tệp)
Chỉ giao tiếp

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

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

{
  "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 khung xem truy hồi có giới hạn và đã được làm sạch, thay vì bản đổ bản ghi thô. Truy hồi của trợ lý loại bỏ các thẻ suy luận, khung dựng <relevant-memories>, nội dung 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, mã thông báo điều khiển mô hình dạng 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 ẩn bớt/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 nhân. Các phiên nhóm/kênh luôn nhận khóa riêng, nên chúng được coi là không phải main và sẽ được chạy trong hộp cát. Nếu bạn muốn một tác nhân không bao giờ chạy trong hộp cát, hãy đặt agents.list[].sandbox.mode: "off".

Kiểm thử

Sau khi cấu hình hộp cát và công cụ đa tác nhân:

Kiểm tra cách phân giải tác nhân

openclaw agents list --bindings

Xác minh các vùng chứa hộp cát

docker ps --filter "name=openclaw-sbx-"

Kiểm thử 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 nhân không thể dùng các công cụ bị từ chối.

Theo dõi nhật ký

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

Khắc phục sự cố

Tác nhân không được chạy trong hộp cát dù có `mode: 'all'`

Kiểm tra liệu có agents.defaults.sandbox.mode toàn cục ghi đè nó hay không.
Cấu hình riêng cho tác nhân có độ ưu tiên cao hơ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 nhân → hộp cát → tác nhân 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 nhật ký: [tools] filtering tools for agent:${agentId}.

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

Đặt scope: "agent" trong cấu hình hộp cát riêng cho tác nhân.
Mặc định là "session", tạo một vùng chứa 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 việc này bị chặn?”
Cơ chế hộp cát — tài liệu tham khảo đầy đủ về hộp cát (chế độ, phạm vi, phần phụ trợ, ảnh)
Quản lý phiên

Overview

Plugins

Skills

Automation and tasks

Tools

Agent coordination

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

Cơ chế 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

Chế độ nâng quyền

Ví dụ cấu hình

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

Cấu hình hộp cát

Hạn chế công cụ

Di chuyển từ tác nhân đơn

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

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

Kiểm thử

Khắc phục sự cố

Liên quan

Overview

Plugins

Skills

Automation and tasks

Tools

Agent coordination

Documentation Index

Cơ chế 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

Chế độ nâng quyền

​Ví dụ cấu hình

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

​Cấu hình hộp cát

​Hạn chế công cụ

​Di chuyển từ tác nhân đơn

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

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

​Kiểm thử

​Khắc phục sự cố

​Liên quan

Ví dụ cấu hình

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

Cấu hình hộp cát

Hạn chế công cụ

Di chuyển từ tác nhân đơn

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

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

Kiểm thử

Khắc phục sự cố

Liên quan