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

Agent coordination

다중 에이전트 샌드박스 및 도구

Status: active

다중 에이전트 설정의 각 에이전트는 전역 샌드박스 및 도구 정책을 재정의할 수 있습니다. 이 페이지에서는 에이전트별 구성, 우선순위 규칙 및 예제를 다룹니다.

샌드박싱

백엔드 및 모드 — 전체 샌드박스 참조 문서입니다.
샌드박스와 도구 정책 및 권한 상승 비교

"이 작업이 차단되는 이유는 무엇인가요?" 문제를 디버깅합니다.
권한 상승 모드

신뢰할 수 있는 발신자를 위한 권한 상승 실행입니다.

구성 예제

예제 1: 개인용 에이전트 + 제한된 가족용 에이전트
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"        }      }    }  ]}

결과:

  • main 에이전트: 호스트에서 실행되며 모든 도구에 접근할 수 있습니다.
  • family 에이전트: Docker에서 실행되며(에이전트마다 컨테이너 하나) read와 현재 대화로의 메시지 전송만 사용할 수 있습니다.
예제 2: 공유 샌드박스를 사용하는 업무용 에이전트
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"]        }      }    ]  }}
예제 2b: 전역 코딩 프로필 + 메시징 전용 에이전트
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

결과:

  • 기본 에이전트에는 코딩 도구가 제공됩니다.
  • support 에이전트는 메시징 전용이며 Slack 도구도 사용할 수 있습니다.
예제 3: 에이전트별로 서로 다른 샌드박스 모드 사용
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"]        }      }    ]  }}

구성 우선순위

전역 구성(agents.defaults.*)과 에이전트별 구성(agents.list[].*)이 모두 존재하는 경우:

샌드박스 구성

에이전트별 설정이 전역 설정을 재정의합니다.

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

도구 제한

필터링 순서는 다음과 같습니다.

  • 도구 프로필

    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"]처럼 존재하지 않는 도구로 구성된 에이전트는 query_db를 등록하는 Plugin이 활성화될 때까지 명확하게 실패해야 하며, 텍스트 전용 에이전트로 계속 실행되어서는 안 됩니다.

    도구 정책은 여러 도구로 확장되는 group:* 축약형을 지원합니다. 전체 목록은 도구 그룹을 참조하세요.

    에이전트별 권한 상승 재정의(agents.list[].tools.elevated)를 사용하면 특정 에이전트의 권한 상승 실행을 추가로 제한할 수 있습니다. 자세한 내용은 권한 상승 모드를 참조하세요.

    단일 에이전트에서 마이그레이션

    이전(단일 에이전트)

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

    이후(다중 에이전트)

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

    도구 제한 예제

    읽기 전용 에이전트

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

    파일 시스템 도구를 비활성화한 셸 실행

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

    통신 전용

    json
    {  "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/전각 모델 제어 토큰 및 잘못된 MiniMax 도구 호출 XML을 제거합니다.

    흔한 함정: "non-main"

    테스트

    다중 에이전트 샌드박스와 도구를 구성한 후:

  • 에이전트 결정 확인

    bash
    openclaw agents list --bindings

  • 샌드박스 컨테이너 확인

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

  • 도구 제한 테스트

    • 제한된 도구가 필요한 메시지를 전송합니다.
    • 에이전트가 거부된 도구를 사용할 수 없는지 확인합니다.

  • 로그 모니터링

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

    • 문제 해결

    `mode: 'all'`인데도 에이전트가 샌드박스에서 실행되지 않음
    • 이를 재정의하는 전역 agents.defaults.sandbox.mode가 있는지 확인합니다.
    • 에이전트별 구성이 우선하므로 agents.list[].sandbox.mode: "all"을 설정합니다.
    거부 목록에도 불구하고 계속 사용할 수 있는 도구
    • 전체 필터링 순서를 확인하세요: 프로필 → 제공자 프로필 → 전역 정책 → 제공자 정책 → 에이전트 정책 → 에이전트 제공자 정책 → 샌드박스 → 하위 에이전트.
    • 각 단계에서는 제한을 더 강화할 수만 있으며, 권한을 다시 부여할 수 없습니다.
    • 단계별 디버깅 방법은 샌드박스와 도구 정책 및 권한 상승 비교를 참조하세요.
    에이전트별로 격리되지 않은 컨테이너
    • 기본 scope는 "agent"입니다(에이전트 ID당 컨테이너 하나).
    • 세션당 컨테이너 하나를 사용하려면 scope: "session"으로 설정하고, 여러 에이전트가 컨테이너 하나를 재사용하게 하려면 scope: "shared"로 설정하세요.

    관련 문서

    Was this useful?
    On this page

    On this page