10. OpenClaw 다중 Agent 라우팅과 세션 격리

OpenClaw v2026.2 적용 | 본문은 팀 사용 또는 컨텍스트 격리가 필요한 사용자를 대상으로 합니다.

TL;DR: 다중 Agent 설정: "agents": {"instances": {"personal": {...}, "work": {...}}}. 라우팅 규칙: "routing": {"rules": [{"match": {"channel": "telegram"}, "agent": "personal"}]}. 세션 격리: "sessions": {"isolation": "user"}. 샌드박스 모드: "sandbox": {"mode": "non-main"}. 다중 사용자, 다중 프로젝트, 다중 용도 시나리오에 적합합니다.

왜 다중 Agent가 필요한가?

단일 Agent의 한계

시나리오	단일 Agent 문제	다중 Agent 해결책
다중 사용자	컨텍스트 혼란, 프라이버시 문제	사용자별 독립 Agent
다중 프로젝트	프로젝트 정보 혼재	프로젝트별 독립 Agent
다중 용도	한 Agent가 여러 역할	전문화된 Agent
다중 팀	권한 제어 어려움	팀별 Agent 격리
비용 제어	사용량 구분 불가	모델별 독립 과금

다중 Agent 사용 시나리오

flowchart TB
    subgraph Users["사용자"]
        U1[사용자A]
        U2[사용자B]
        U3[팀X]
        U4[팀Y]
    end
    
    subgraph Router["메시지 라우팅"]
        R[라우팅 규칙]
    end
    
    subgraph Agents["Agent 인스턴스"]
        A1[개인 Agent A]
        A2[개인 Agent B]
        A3[팀 Agent X]
        A4[팀 Agent Y]
    end
    
    subgraph Models["모델"]
        M1[Claude Opus]
        M2[Claude Sonnet]
        M3[GPT-4o]
        M4[Haiku]
    end
    
    U1 --> R
    U2 --> R
    U3 --> R
    U4 --> R
    R --> A1
    R --> A2
    R --> A3
    R --> A4
    A1 --> M1
    A2 --> M2
    A3 --> M3
    A4 --> M4

다중 Agent 설정

기본 구조

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4",
      "workspace": "~/.openclaw/workspace"
    },
    "instances": {
      "personal": {
        "model": "anthropic/claude-opus-4-6",
        "workspace": "~/.openclaw/workspaces/personal",
        "thinkingLevel": "high"
      },
      "work": {
        "model": "anthropic/claude-sonnet-4",
        "workspace": "~/.openclaw/workspaces/work",
        "skills": ["github", "jira", "confluence"]
      },
      "assistant": {
        "model": "anthropic/claude-haiku-3.5",
        "workspace": "~/.openclaw/workspaces/assistant"
      }
    }
  }
}

Agent 설정 항목

설정 항목	설명	예시
`model`	사용 모델	`anthropic/claude-opus-4-6`
`workspace`	작업 디렉토리	`~/.openclaw/workspaces/personal`
`thinkingLevel`	사고 수준	`high`, `medium`, `low`
`skills`	활성화 스킬	`["gmail", "calendar"]`
`sandbox`	샌드박스 설정	`{ "mode": "non-main" }`
`contextWindow`	컨텍스트 창	`200000`

Workspace 구조

~/.openclaw/
├── workspace/              # 기본 workspace
│   ├── AGENTS.md
│   ├── SOUL.md
│   └── skills/
├── workspaces/
│   ├── personal/          # 개인 Agent
│   │   ├── AGENTS.md
│   │   ├── SOUL.md
│   │   └── USER.md
│   ├── work/              # 업무 Agent
│   │   ├── AGENTS.md
│   │   └── skills/
│   └── assistant/         # 어시스턴트 Agent
│       └── AGENTS.md
└── openclaw.json          # 메인 설정

메시지 라우팅 규칙

라우팅 설정

{
  "routing": {
    "rules": [
      {
        "match": {
          "channel": "telegram",
          "sender": "123456789"
        },
        "agent": "personal"
      },
      {
        "match": {
          "channel": "discord",
          "guild": "987654321"
        },
        "agent": "work"
      },
      {
        "match": {
          "session": "main"
        },
        "agent": "personal"
      }
    ],
    "default": "personal"
  }
}

라우팅 규칙 상세

매칭 필드	설명	예시
`channel`	채널 유형	`telegram`, `discord`, `slack`
`sender`	발신자 ID	`123456789`
`guild`	Discord 서버 ID	`987654321`
`group`	그룹 ID	`-100123456789`
`session`	세션 ID	`main`, `telegram:user:123`
`pattern`	정규식 매칭	`^work-`

복잡한 라우팅 예시

{
  "routing": {
    "rules": [
      {
        "name": "개인 Telegram",
        "match": {
          "channel": "telegram",
          "sender": ["123456789", "987654321"]
        },
        "agent": "personal"
      },
      {
        "name": "업무 Discord",
        "match": {
          "channel": "discord",
          "guild": "111222333"
        },
        "agent": "work"
      },
      {
        "name": "업무 그룹",
        "match": {
          "channel": "telegram",
          "group": "-100111222333"
        },
        "agent": "work"
      },
      {
        "name": "테스트 환경",
        "match": {
          "pattern": "^test-"
        },
        "agent": "assistant",
        "config": {
          "sandbox": { "mode": "always" }
        }
      }
    ],
    "default": "personal"
  }
}

라우팅 우선순위

flowchart TB
    MSG[메시지 도착] --> R1{규칙 1 매칭?}
    R1 -->|예| A1[Agent 1]
    R1 -->|아니오| R2{규칙 2 매칭?}
    R2 -->|예| A2[Agent 2]
    R2 -->|아니오| R3{규칙 3 매칭?}
    R3 -->|예| A3[Agent 3]
    R3 -->|아니오| D[기본 Agent]

규칙은 순서대로 매칭되며, 첫 번째로 매칭된 규칙이 적용됩니다.

세션 격리

격리 수준

수준	설명	사용 시나리오
격리 없음	컨텍스트 공유	단일 사용자, 단일 용도
채널 격리	채널별 독립 컨텍스트	다중 채널 접속
사용자 격리	사용자별 독립 컨텍스트	다중 사용자 공유
세션 격리	세션별 독립	완전 격리
Agent 격리	Agent별 독립	다중 Agent 배포

세션 격리 설정

{
  "sessions": {
    "isolation": "user",
    "persistence": true,
    "retention": {
      "maxAge": 604800000,
      "maxSessions": 100
    }
  }
}

격리 설정 상세

{
  "sessions": {
    "isolation": "user",
    "storage": {
      "type": "file",
      "path": "~/.openclaw/sessions"
    },
    "encryption": {
      "enabled": true,
      "algorithm": "aes-256-gcm"
    },
    "retention": {
      "maxAge": 604800000,
      "maxSessions": 100,
      "cleanupInterval": 86400000
    }
  }
}

설정 항목	설명	기본값
`isolation`	격리 수준	`user`
`storage.type`	저장소 유형	`file`
`encryption.enabled`	암호화 활성화	`true`
`retention.maxAge`	최대 보유 기간	7일
`retention.maxSessions`	최대 세션 수	100

팀 협업 시나리오

시나리오 1: 소규모 팀 공유

{
  "agents": {
    "instances": {
      "team": {
        "model": "anthropic/claude-sonnet-4",
        "workspace": "~/.openclaw/workspaces/team",
        "skills": ["github", "jira", "slack"]
      }
    }
  },
  "routing": {
    "rules": [
      {
        "match": { "channel": "slack" },
        "agent": "team"
      },
      {
        "match": { "channel": "discord" },
        "agent": "team"
      }
    ],
    "default": "team"
  }
}

시나리오 2: 부서별 격리

{
  "agents": {
    "instances": {
      "engineering": {
        "model": "anthropic/claude-opus-4-6",
        "workspace": "~/.openclaw/workspaces/engineering",
        "skills": ["github", "jira", "pagerduty"],
        "sandbox": { "mode": "off" }
      },
      "marketing": {
        "model": "anthropic/claude-sonnet-4",
        "workspace": "~/.openclaw/workspaces/marketing",
        "skills": ["mailchimp", "analytics"],
        "sandbox": { "mode": "non-main" }
      },
      "support": {
        "model": "anthropic/claude-haiku-3.5",
        "workspace": "~/.openclaw/workspaces/support",
        "skills": ["zendesk", "intercom"],
        "sandbox": { "mode": "always" }
      }
    }
  },
  "routing": {
    "rules": [
      {
        "name": "Engineering Discord",
        "match": { "channel": "discord", "guild": "111111111" },
        "agent": "engineering"
      },
      {
        "name": "Marketing Slack",
        "match": { "channel": "slack", "team": "T22222222" },
        "agent": "marketing"
      },
      {
        "name": "Support Telegram",
        "match": { "channel": "telegram", "group": "-100333333333" },
        "agent": "support"
      }
    ],
    "default": "support"
  }
}

시나리오 3: 다중 테넌트 SaaS

{
  "agents": {
    "dynamic": true,
    "template": {
      "model": "anthropic/claude-sonnet-4",
      "workspace": "~/.openclaw/workspaces/tenants/{{tenantId}}",
      "skills": ["base"],
      "sandbox": { "mode": "always" }
    },
    "limits": {
      "maxAgents": 100,
      "maxSessionsPerAgent": 50,
      "maxTokensPerMonth": 1000000
    }
  },
  "routing": {
    "rules": [
      {
        "name": "Tenant Routing",
        "match": { "header": "X-Tenant-Id" },
        "agent": "tenant_{{tenantId}}",
        "createIfNotExists": true
      }
    ]
  }
}

권한 및 보안

Agent 권한 제어

{
  "agents": {
    "instances": {
      "trusted": {
        "model": "anthropic/claude-opus-4-6",
        "sandbox": { "mode": "off" },
        "permissions": {
          "filesystem": { "read": true, "write": true },
          "network": { "outbound": true },
          "process": { "execute": true }
        }
      },
      "restricted": {
        "model": "anthropic/claude-haiku-3.5",
        "sandbox": { "mode": "always" },
        "permissions": {
          "filesystem": { 
            "read": ["~/allowed/"],
            "write": ["~/allowed/"]
          },
          "network": { 
            "outbound": ["api.example.com"]
          },
          "process": { "execute": false }
        }
      }
    }
  }
}

샌드박스 모드

모드	설명	적용 시나리오
`off`	샌드박스 없음	신뢰 Agent
`non-main`	비주요 세션 샌드박스	팀 공유
`always`	항상 샌드박스	비신뢰 환경

샌드박스 설정

{
  "sandbox": {
    "mode": "non-main",
    "container": {
      "image": "openclaw/sandbox:latest",
      "timeout": 30000,
      "memory": "512m",
      "cpu": "0.5"
    },
    "allowlist": ["read", "write", "edit", "bash"],
    "denylist": ["browser", "canvas", "nodes"],
    "networkPolicy": {
      "allow": ["api.example.com"],
      "deny": ["*"]
    }
  }
}

모니터링 및 관리

Agent 상태 모니터링

# 모든 Agent 인스턴스 나열
openclaw agents list

# 출력 예시:
# Name        Model                  Sessions  Status   Last Active
# personal    claude-opus-4-6        3         active   2 min ago
# work        claude-sonnet-4        5         active   5 min ago
# assistant   claude-haiku-3.5       2         idle     1 hour ago

# Agent 상세 확인
openclaw agents show personal

# 라우팅 규칙 확인
openclaw routing list

세션 관리

# 모든 세션 나열
openclaw sessions list --agent personal

# 출력 예시:
# Session ID              Channel    Sender      Created      Messages
# telegram:user:123       telegram   123456789   2026-02-26   42
# main                    cli        -           2026-02-25   128

# 세션 상세 확인
openclaw sessions show telegram:user:123

# 세션 내보내기
openclaw sessions export telegram:user:123 --format json

# 세션 삭제
openclaw sessions delete telegram:user:123

사용량 통계

# Agent별 사용량 확인
openclaw usage --by-agent

# 출력 예시:
# Agent       Tokens In    Tokens Out   Cost      Requests
# personal    125,000     45,000      $2.10     128
# work        89,000      32,000      $1.25     95
# assistant   15,000      8,000       $0.15     42

# 기간별 통계
openclaw usage --by-agent --from 2026-02-01 --to 2026-02-28

모범 사례

1. Agent 합리적 구분

구분 기준	설명	예시
용도	기능별 구분	`coding`, `research`, `assistant`
프로젝트	프로젝트별 구분	`project-alpha`, `project-beta`
팀	팀별 구분	`engineering`, `marketing`
모델	모델별 구분	`opus`, `sonnet`, `haiku`

2. 설정 상속

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4",
      "workspace": "~/.openclaw/workspace",
      "thinkingLevel": "medium",
      "sandbox": { "mode": "non-main" }
    },
    "instances": {
      "opus": {
        "model": "anthropic/claude-opus-4-6",
        "thinkingLevel": "high"
        // defaults의 workspace와 sandbox 상속
      },
      "haiku": {
        "model": "anthropic/claude-haiku-3.5",
        "thinkingLevel": "minimal"
        // defaults의 기타 설정 상속
      }
    }
  }
}

3. 최소 권한

{
  "agents": {
    "instances": {
      "restricted": {
        "model": "anthropic/claude-haiku-3.5",
        "sandbox": { "mode": "always" },
        "permissions": {
          "filesystem": {
            "read": ["~/allowed/read"],
            "write": ["~/allowed/write"]
          },
          "network": {
            "outbound": []
          },
          "process": {
            "execute": false
          }
        }
      }
    }
  }
}

4. 모니터링 및 알림

{
  "monitoring": {
    "alerts": [
      {
        "condition": "usage > 1000000",
        "action": "notify"
      },
      {
        "condition": "error_rate > 0.1",
        "action": "notify"
      },
      {
        "condition": "response_time > 10000",
        "action": "notify"
      }
    ],
    "webhook": "https://your-monitoring.com/webhook"
  }
}

문제 해결

라우팅 미적용

# 현재 라우팅 규칙 확인
openclaw routing list

# 라우팅 테스트
openclaw routing test --channel telegram --sender 123456789

# 출력 예시:
# Matched Rule: 개인 Telegram
# Target Agent: personal
# Route Path: default -> rule 1 -> personal

세션 격리 문제

# 세션 격리 설정 확인
openclaw config get sessions.isolation

# 세션 목록 확인
openclaw sessions list --all

# 세션 격리 초기화
openclaw sessions reset --agent personal

권한 문제

# 권한 설정 확인
openclaw agents permissions show personal

# 권한 테스트
openclaw agents test-permission personal --action filesystem.read --path ~/test

# 출력 예시:
# Permission: filesystem.read
# Path: ~/test
# Result: ALLOWED

요약

다중 Agent 아키텍처는 OpenClaw의 고급 기능으로, 팀과 엔터프라이즈 시나리오에 강력한 지원을 제공합니다:

유연한 라우팅: 채널, 사용자, 프로젝트별로 다른 Agent 배정
세션 격리: 프라이버시 보호, 컨텍스트 혼란 방지
권한 제어: 세밀한 권한 관리
비용 최적화: 용도별 다른 모델 선택
확장성: 동적 Agent 생성 및 관리 지원

본문 요약:

다중 Agent 아키텍처의 가치와 시나리오 이해
Agent 설정과 메시지 라우팅 규칙 습득
세션 격리 설정 방법 학습
팀 협업 시나리오 모범 사례 이해
권한 제어와 모니터링 관리 습득

업데이트 기록:

2026-02-26: 초판 발행, OpenClaw v2026.2 기반

시리즈 네비게이션:

← 이전: Web Control UI와 Canvas
→ 다음: 보안 설정 모범 사례