Multi-Agent Sandbox 및 도구 설정 가이드

여러 에이전트를 동시에 운영하다 보면 보안과 권한 관리가 고민될 때가 많아요. 모든 에이전트에게 내 시스템의 전체 권한을 주기에는 불안하고, 그렇다고 기능을 너무 제한하면 에이전트가 제 역할을 못 하기도 하죠.

이런 고민을 해결하기 위해 이제 각 에이전트마다 독립적인 Sandbox 설정과 Tool 권한을 부여할 수 있어요. 개인 비서 에이전트에게는 모든 권한을 주고, 외부 노출용 에이전트는 안전한 Sandbox에 가두어 특정 도구만 사용하도록 설정하는 식이죠.

필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

• OpenClaw 설치 환경
• Docker (Sandbox 기능을 사용하는 경우)
• agents.defaults 및 agents.list 설정이 포함된 구성 파일

빠른 시작

5분 만에 개인용 에이전트와 제한된 권한을 가진 가족용 에이전트를 설정하는 방법이에요.

1. 설정 파일 수정: ~/.openclaw/config.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"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "120363424282127706@g.us"
        }
      }
    }
  ]
}

2. 결과 확인:
   • main 에이전트: 호스트에서 직접 실행되며 모든 Tool에 접근할 수 있어요.
   • family 에이전트: Docker 컨테이너 내에서 실행되며 오직 read Tool만 사용할 수 있어요.

주요 설정 가이드

Sandbox 우선순위

전역 설정(agents.defaults)과 에이전트별 설정(agents.list[])이 부딪히면 에이전트별 설정이 우선해요.

• agents.list[].sandbox.mode > agents.defaults.sandbox.mode
• agents.list[].sandbox.scope > agents.defaults.sandbox.scope

Tool 제한 필터링 순서

도구 권한은 여러 단계를 거쳐 필터링돼요. 하위 단계에서 권한을 더 제한할 수는 있지만, 상위 단계에서 이미 거부된 권한을 다시 허용할 수는 없어요.

1. Tool profile 설정
2. Global tool policy (allow / deny)
3. Agent-specific tool policy
4. Sandbox tool policy

유용한 Tool 그룹 (Shorthands)

일일이 도구 이름을 적지 않아도 그룹 단위로 관리할 수 있어요.

• group:runtime: exec, bash, process 포함
• group:fs: read, write, edit, apply_patch 포함
• group:messaging: message 포함
• group:openclaw: 모든 내장 OpenClaw 도구 포함

문제 해결

설정 중 문제가 발생하면 다음 사항을 확인해 보세요.

mode: "all"인데도 에이전트가 Sandbox에서 실행되지 않아요

• 전역 설정인 agents.defaults.sandbox.mode가 에이전트 설정을 덮어쓰고 있는지 확인하세요. 에이전트별 설정에 직접 mode: "all"을 명시해야 해요.

deny 목록에 넣었는데도 도구가 계속 실행돼요

• 필터링 순서를 확인해 보세요. 로그에서 [tools] filtering tools for agent:${agentId} 부분을 확인하면 어떤 단계에서 필터링되는지 알 수 있어요.

컨테이너가 에이전트별로 분리되지 않아요

• 에이전트별 Sandbox 설정에서 scope: "agent"로 설정되어 있는지 확인하세요. 기본값은 "session"이라 세션마다 컨테이너가 생성될 수 있어요.

non-main 설정이 의도대로 작동하지 않아요

• non-main 모드는 에이전트 ID가 아니라 session.mainKey(기본값 "main")를 기준으로 해요. 에이전트가 Sandbox를 절대 사용하지 않게 하려면 mode: "off"를 명시적으로 설정하세요.

---

도움이 더 필요하신가요? AI Setup Assistant에게 물어보세요!

다음 단계

• Multi-Agent Routing
• Sandbox Configuration
• Session Management
• Sandbox vs Tool Policy vs Elevated