Multi-Agent Sandbox & Tools 설정

개요

Multi-agent 설정에서 각 agent는 이제 다음을 가질 수 있습니다:

Sandbox 설정 (agents.list[].sandbox가 agents.defaults.sandbox를 재정의)
Tool 제한사항 (tools.allow / tools.deny, 그리고 agents.list[].tools)

이를 통해 서로 다른 보안 프로필을 가진 여러 agent를 실행할 수 있습니다:

전체 액세스 권한을 가진 개인 비서
제한된 tool을 가진 가족/업무용 agent
sandbox에서 실행되는 공개 agent

setupCommand는 sandbox.docker (전역 또는 agent별) 아래에 속하며, 컨테이너가 생성될 때 한 번 실행됩니다.

Auth는 agent별로 적용됩니다: 각 agent는 다음 위치의 자체 agentDir auth 저장소에서 읽습니다:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

자격 증명은 agent 간에 공유되지 않습니다. agent 간에 agentDir을 재사용하지 마세요. 자격 증명을 공유하려면, auth-profiles.json을 다른 agent의 agentDir로 복사하세요.

런타임에서 sandboxing이 작동하는 방식은 Sandboxing을 참조하세요. "왜 차단되었는지" 디버깅하려면 Sandbox vs Tool Policy vs Elevated 및 openclaw sandbox explain을 참조하세요.

설정 예시

예시 1: 개인용 + 제한된 가족용 Agent

{
  "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 agent: 호스트에서 실행, 전체 tool 액세스
family agent: Docker에서 실행 (agent당 하나의 컨테이너), read tool만 사용 가능

예시 2: 공유 Sandbox를 사용하는 업무용 Agent

{
  "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: 전역 coding 프로필 + 메시징 전용 agent

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

결과:

기본 agent는 coding tool을 얻습니다
support agent는 메시징 전용 (+ Slack tool)

예시 3: Agent별 서로 다른 Sandbox 모드

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",  // 전역 기본값
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off"  // 재정의: main은 sandbox 사용 안함
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all",  // 재정의: public은 항상 sandbox 사용
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

설정 우선순위

전역 (agents.defaults.*)과 agent별 (agents.list[].*) 설정이 모두 존재할 때:

Sandbox 설정

Agent별 설정이 전역을 재정의합니다:

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}.*는 해당 agent에 대해 agents.defaults.sandbox.{docker,browser,prune}.*를 재정의합니다 (sandbox scope가 "shared"로 확인되면 무시됨).

Tool 제한사항

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

Tool profile (tools.profile 또는 agents.list[].tools.profile)
Provider tool profile (tools.byProvider[provider].profile 또는 agents.list[].tools.byProvider[provider].profile)
전역 tool 정책 (tools.allow / tools.deny)
Provider tool 정책 (tools.byProvider[provider].allow/deny)
Agent별 tool 정책 (agents.list[].tools.allow/deny)
Agent provider 정책 (agents.list[].tools.byProvider[provider].allow/deny)
Sandbox tool 정책 (tools.sandbox.tools 또는 agents.list[].tools.sandbox.tools)
Subagent tool 정책 (tools.subagents.tools, 해당하는 경우)

각 레벨은 tool을 추가로 제한할 수 있지만, 이전 레벨에서 거부된 tool을 다시 허용할 수는 없습니다. agents.list[].tools.sandbox.tools가 설정되면, 해당 agent에 대해 tools.sandbox.tools를 대체합니다. agents.list[].tools.profile이 설정되면, 해당 agent에 대해 tools.profile을 재정의합니다. Provider tool 키는 provider (예: google-antigravity) 또는 provider/model (예: openai/gpt-5.2)을 허용합니다.

Tool 그룹 (축약형)

Tool 정책(전역, agent, sandbox)은 여러 구체적인 tool로 확장되는 group:* 항목을 지원합니다:

group:runtime: exec, bash, process
group:fs: read, write, edit, apply_patch
group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
group:memory: memory_search, memory_get
group:ui: browser, canvas
group:automation: cron, gateway
group:messaging: message
group:nodes: nodes
group:openclaw: 모든 내장 OpenClaw tool (provider plugin 제외)

Elevated 모드

tools.elevated는 전역 기준선(발신자 기반 allowlist)입니다. agents.list[].tools.elevated는 특정 agent에 대해 elevated를 추가로 제한할 수 있습니다 (둘 다 허용해야 함).

완화 패턴:

신뢰할 수 없는 agent에 대해 exec 거부 (agents.list[].tools.deny: ["exec"])
제한된 agent로 라우팅되는 발신자를 allowlist에 추가하지 않음
전역적으로 elevated 비활성화 (tools.elevated.enabled: false) - sandbox 실행만 원하는 경우
Agent별로 elevated 비활성화 (agents.list[].tools.elevated.enabled: false) - 민감한 프로필의 경우

단일 Agent에서 마이그레이션

이전 (단일 agent):

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

이후 (서로 다른 프로필을 가진 multi-agent):

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

레거시 agent.* 설정은 openclaw doctor에 의해 마이그레이션됩니다. 앞으로는 agents.defaults + agents.list를 사용하세요.

Tool 제한사항 예시

읽기 전용 Agent

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

안전한 실행 Agent (파일 수정 없음)

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

통신 전용 Agent

{
  "tools": {
    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
  }
}

일반적인 함정: "non-main"

agents.defaults.sandbox.mode: "non-main"은 agent id가 아닌 session.mainKey (기본값 "main")를 기반으로 합니다. 그룹/channel 세션은 항상 고유한 키를 얻으므로, non-main으로 처리되어 sandbox가 적용됩니다. agent가 절대 sandbox를 사용하지 않도록 하려면, agents.list[].sandbox.mode: "off"로 설정하세요.

테스트

Multi-agent sandbox 및 tool 설정 후:

Agent 확인:
```
openclaw agents list --bindings
```

Sandbox 컨테이너 확인:

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

Tool 제한사항 테스트:
- 제한된 tool이 필요한 메시지 전송
- agent가 거부된 tool을 사용할 수 없는지 확인

로그 모니터링:

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