English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Agent coordination

แซนด์บ็อกซ์และเครื่องมือสำหรับหลายเอเจนต์

แต่ละเอเจนต์ในการตั้งค่าแบบหลายเอเจนต์สามารถแทนที่นโยบายแซนด์บ็อกซ์และเครื่องมือส่วนกลางได้ หน้านี้ครอบคลุมการกำหนดค่าต่อเอเจนต์ กฎลำดับความสำคัญ และตัวอย่าง

การทำแซนด์บ็อกซ์

แบ็กเอนด์และโหมด — อ้างอิงแซนด์บ็อกซ์ฉบับเต็ม
แซนด์บ็อกซ์เทียบกับนโยบายเครื่องมือเทียบกับโหมดยกระดับ

ดีบัก "ทำไมสิ่งนี้จึงถูกบล็อก?"
โหมดยกระดับ

การดำเนินการ exec แบบยกระดับสำหรับผู้ส่งที่เชื่อถือได้

ตัวอย่างการกำหนดค่า

ตัวอย่างที่ 1: เอเจนต์ส่วนตัว + เอเจนต์ครอบครัวแบบจำกัด 
{
  "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]"
        }
      }
    }
  ]
}

ผลลัพธ์:

  • เอเจนต์ main: ทำงานบนโฮสต์ มีสิทธิ์เข้าถึงเครื่องมือเต็มรูปแบบ
  • เอเจนต์ family: ทำงานใน Docker (หนึ่งคอนเทนเนอร์ต่อเอเจนต์) มีเฉพาะเครื่องมือ read
ตัวอย่างที่ 2: เอเจนต์งานพร้อมแซนด์บ็อกซ์ที่ใช้ร่วมกัน 
{
  "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"]
        }
      }
    ]
  }
}
ตัวอย่างที่ 2b: โปรไฟล์การเขียนโค้ดส่วนกลาง + เอเจนต์เฉพาะการรับส่งข้อความ 
{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

ผลลัพธ์:

  • เอเจนต์เริ่มต้นจะได้รับเครื่องมือการเขียนโค้ด
  • เอเจนต์ support เป็นแบบเฉพาะการรับส่งข้อความ (+ เครื่องมือ Slack)
ตัวอย่างที่ 3: โหมดแซนด์บ็อกซ์ที่แตกต่างกันต่อเอเจนต์ 
{
  "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"]
        }
      }
    ]
  }
}

ลำดับความสำคัญของการกำหนดค่า

เมื่อมีทั้งการกำหนดค่าส่วนกลาง (agents.defaults.*) และเฉพาะเอเจนต์ (agents.list[].*):

การกำหนดค่าแซนด์บ็อกซ์

การตั้งค่าเฉพาะเอเจนต์จะแทนที่ค่าส่วนกลาง:

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

ข้อจำกัดเครื่องมือ

ลำดับการกรองคือ:

  • โปรไฟล์เครื่องมือ

    tools.profile หรือ agents.list[].tools.profile

  • โปรไฟล์เครื่องมือของผู้ให้บริการ

    tools.byProvider[provider].profile หรือ agents.list[].tools.byProvider[provider].profile

  • นโยบายเครื่องมือส่วนกลาง

    tools.allow / tools.deny

  • นโยบายเครื่องมือของผู้ให้บริการ

    tools.byProvider[provider].allow/deny

  • นโยบายเครื่องมือเฉพาะเอเจนต์

    agents.list[].tools.allow/deny

  • นโยบายผู้ให้บริการของเอเจนต์

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

  • นโยบายเครื่องมือของแซนด์บ็อกซ์

    tools.sandbox.tools หรือ agents.list[].tools.sandbox.tools

  • นโยบายเครื่องมือของเอเจนต์ย่อย

    tools.subagents.tools หากใช้ได้

    • กฎลำดับความสำคัญ
    • แต่ละระดับสามารถจำกัดเครื่องมือเพิ่มเติมได้ แต่ไม่สามารถให้สิทธิ์เครื่องมือที่ถูกปฏิเสธจากระดับก่อนหน้ากลับมาได้
    • หากตั้งค่า agents.list[].tools.sandbox.tools ค่านั้นจะแทนที่ tools.sandbox.tools สำหรับเอเจนต์นั้น
    • หากตั้งค่า agents.list[].tools.profile ค่านั้นจะแทนที่ tools.profile สำหรับเอเจนต์นั้น
    • คีย์เครื่องมือของผู้ให้บริการรับได้ทั้ง provider (เช่น google-antigravity) หรือ provider/model (เช่น openai/gpt-5.4)
    พฤติกรรมของรายการอนุญาตที่ว่างเปล่า

    หากรายการอนุญาตแบบชัดเจนใดๆ ในสายโซ่นั้นทำให้การรันไม่มีเครื่องมือที่เรียกใช้ได้ OpenClaw จะหยุดก่อนส่งพรอมป์ไปยังโมเดล สิ่งนี้เป็นความตั้งใจ: เอเจนต์ที่กำหนดค่าด้วยเครื่องมือที่หายไป เช่น agents.list[].tools.allow: ["query_db"] ควรล้มเหลวอย่างชัดเจนจนกว่า Plugin ที่ลงทะเบียน query_db จะถูกเปิดใช้งาน ไม่ใช่ดำเนินต่อในฐานะเอเจนต์แบบข้อความเท่านั้น

    นโยบายเครื่องมือรองรับชอร์ตแฮนด์ group:* ที่ขยายเป็นหลายเครื่องมือ ดูรายการทั้งหมดที่ กลุ่มเครื่องมือ

    การแทนที่โหมดยกระดับต่อเอเจนต์ (agents.list[].tools.elevated) สามารถจำกัด elevated exec เพิ่มเติมสำหรับเอเจนต์เฉพาะได้ ดูรายละเอียดที่ โหมดยกระดับ

    การย้ายจากเอเจนต์เดี่ยว

    ก่อนหน้า (เอเจนต์เดี่ยว)

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

    ตัวอย่างข้อจำกัดเครื่องมือ

    เอเจนต์อ่านอย่างเดียว

    {
  "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 ในโปรไฟล์นี้ยังคงส่งคืนมุมมองการเรียกคืนแบบจำกัดขอบเขตและผ่านการทำให้ปลอดภัย แทนการดัมป์ทรานสคริปต์ดิบ การเรียกคืนของผู้ช่วยจะลบแท็กการคิด โครง <relevant-memories> เพย์โหลด XML ของการเรียกเครื่องมือแบบข้อความล้วน (รวมถึง <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> และบล็อกการเรียกเครื่องมือที่ถูกตัดทอน), โครงการเรียกเครื่องมือที่ถูกลดระดับ, โทเค็นควบคุมโมเดล ASCII/ฟูลวิดท์ที่รั่วไหล และ XML การเรียกเครื่องมือ MiniMax ที่ผิดรูป ก่อนการปกปิด/ตัดทอน

    ข้อผิดพลาดที่พบบ่อย: "non-main"

    การทดสอบ

    หลังจากกำหนดค่าแซนด์บ็อกซ์และเครื่องมือแบบหลายเอเจนต์แล้ว:

  • ตรวจสอบการแก้ค่าเอเจนต์

    openclaw agents list --bindings

  • ตรวจสอบคอนเทนเนอร์แซนด์บ็อกซ์

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

  • ทดสอบข้อจำกัดเครื่องมือ

    • ส่งข้อความที่ต้องใช้เครื่องมือที่ถูกจำกัด
    • ตรวจสอบว่าเอเจนต์ไม่สามารถใช้เครื่องมือที่ถูกปฏิเสธได้

  • ตรวจสอบบันทึก

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

    • การแก้ไขปัญหา

    เอเจนต์ไม่ถูกแซนด์บ็อกซ์แม้ตั้งค่า `mode: 'all'`
    • ตรวจสอบว่ามี agents.defaults.sandbox.mode ส่วนกลางที่แทนที่อยู่หรือไม่
    • การกำหนดค่าเฉพาะเอเจนต์มีลำดับความสำคัญสูงกว่า ดังนั้นให้ตั้งค่า agents.list[].sandbox.mode: "all"
    เครื่องมือยังพร้อมใช้งานแม้มีรายการปฏิเสธ
    • ตรวจสอบลำดับการกรองเครื่องมือ: ส่วนกลาง → เอเจนต์ → แซนด์บ็อกซ์ → เอเจนต์ย่อย
    • แต่ละระดับสามารถจำกัดเพิ่มเติมได้เท่านั้น ไม่สามารถให้สิทธิ์กลับมาได้
    • ตรวจสอบด้วยบันทึก: [tools] filtering tools for agent:${agentId}
    คอนเทนเนอร์ไม่ได้แยกต่อเอเจนต์
    • ตั้งค่า scope: "agent" ในการกำหนดค่าแซนด์บ็อกซ์เฉพาะเอเจนต์
    • ค่าเริ่มต้นคือ "session" ซึ่งสร้างหนึ่งคอนเทนเนอร์ต่อเซสชัน

    ที่เกี่ยวข้อง