OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Agent coordination

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

Status: active

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.

Ví dụ cấu hình

Ví dụ 1: Agent cá nhân + agent gia đình bị hạn chế
json
{  "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": "120363424282127706@g.us"        }      }    }  ]}

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
json
{  "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
json
{  "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
json
{  "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:

text
agents.list[].sandbox.mode > agents.defaults.sandbox.modeagents.list[].sandbox.scope > agents.defaults.sandbox.scopeagents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRootagents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccessagents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

Hạn chế công cụ

Thứ tự lọc như sau:

  • 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 agent

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

  • Chính sách nhà cung cấp 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ụ 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)

    json
    {  "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)

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

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

    Agent chỉ đọc

    json
    {  "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

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

    Chỉ giao tiếp

    json
    {  "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"

    Kiểm thử

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

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

    bash
    openclaw agents list --bindings

  • Xác minh các container sandbox

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

  • 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.

  • Theo dõi nhật ký

    bash
    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
    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

    Was this useful?
    On this page

    On this page