"코딩 질문을 할 때는 까칠하더라도 코드를 완벽하게 짜주는 시니어 개발자 AI가 대답하고, 일정을 관리할 때는 다정한 비서 AI가 대답하게 할 수는 없을까?" 맞춤형 에이전트를 운영하다 보면 자연스럽게 드는 욕심입니다. 단 하나의 에이전트로 모든 역할을 소화하려다 보면 어딘가 어정쩡해지기 마련입니다.
이번 16편에서는 단 하나의 게이트웨이 안에서 각기 다른 역할을 수행하는 여러 에이전트를 생성하고, 작업별로 완벽히 분업시키는 openclaw 멀티에이전트 구성법과 채널 라우팅(Bindings)을 처음부터 끝까지 다룹니다. 부서별 AI 전문가 팀을 거느리는 진정한 자동화 환경을 완성해 보겠습니다.
지난 편(이전: AGENTS.md 작성법 — AI에게 역할과 규칙 부여하기)에서는 AGENTS.md로 AI에게 성격과 규칙을 부여하는 방법을 배웠습니다. 이번 편에서는 그 성격이 다른 여러 AI를 동시에 운영하는 방법을 실습합니다.
멀티 에이전트 시스템의 개념 — defaults-with-overrides 패턴
OpenClaw의 openclaw 멀티에이전트 구조는 defaults-with-overrides(기본값 + 개별 덮어쓰기) 패턴을 사용합니다. 복잡하게 들리지만 개념은 간단합니다.
패턴의 핵심 구조
agents.defaults(공통 기본값): 모든 에이전트가 공통으로 사용할 기본 모델, 메모리 설정, 스킬 등을 여기에 정의합니다. 새 에이전트를 추가할 때마다 반복 설정할 필요가 없어 관리가 편리합니다.agents.list(개별 에이전트 목록): 각 에이전트를 배열 형식으로 나열하고,defaults에서 변경하고 싶은 항목만 선택적으로 덮어씁니다. 예를 들어 코딩 에이전트만 비싸고 똑똑한 Claude 모델을 배정하는 방식입니다.bindings(채널 라우팅): 특정 채널(텔레그램, 디스코드 등)에서 들어오는 메시지를 어느 에이전트에게 전달할지 규칙을 정의합니다. 이 설정으로 채널별 전담 에이전트 분리가 완성됩니다.
이 구조 덕분에 서버 인프라를 여러 개 띄울 필요 없이, 단 하나의 게이트웨이에서 여러 인격을 가진 셀프호스팅 AI 전문가 팀을 운영할 수 있습니다.
compaction, contextPruning 같은 핵심 에이전트 설정은 반드시 agents.defaults에만 정의해야 합니다. agents.list 개별 에이전트 블록에 넣어도 무시됩니다. 📎 OpenClaw 공식 문서(Agents) 원문 보기 →
agents.defaults에 공통 설정을, agents.list에 개별 에이전트의 차이점만 덮어씁니다. bindings로 어떤 채널 메시지를 어느 에이전트에게 보낼지 연결하면 멀티에이전트 팀이 완성됩니다.멀티 에이전트 설정 파일 완성하기 — agents.list와 bindings
~/.openclaw/openclaw.json 파일을 열고 아래 예시를 참고해 여러분만의 AI 팀을 구성해 보세요. 메인 비서 에이전트와 코딩 전담 에이전트를 만들고, 채널별로 자동 연결하는 완성 예시입니다.
{
"agents": {
"defaults": {
"model": {
"primary": "openrouter/openai/gpt-4o-mini"
}
},
"list": [
{
"id": "main",
"default": true
},
{
"id": "coder",
"model": {
"primary": "anthropic/claude-3-5-sonnet-20241022"
}
}
]
},
"bindings": [
{
"agentId": "coder",
"match": {
"channel": "discord"
}
},
{
"agentId": "main",
"match": {
"channel": "telegram"
}
}
]
}설정 항목 해설
defaults.model.primary: "gpt-4o-mini": 모든 에이전트의 기본 모델을 저렴하고 빠른 GPT-4o-mini로 설정합니다. 별도 지정이 없는 에이전트는 이 모델을 사용합니다.coder에이전트의model.primary덮어쓰기: 코딩 전담 에이전트만 성능이 뛰어난 Claude Sonnet으로 교체합니다. 일상 대화로 비싼 토큰을 낭비하지 않습니다.bindings: 디스코드에서 오는 메시지는coder, 텔레그램에서 오는 메시지는main이 전담합니다. 설정 후openclaw gateway restart로 재시작하면 즉시 적용됩니다.
서브 에이전트 소환과 협업 — Orchestration 도구
멀티에이전트의 진정한 힘은 에이전트끼리 협업할 때 드러납니다. OpenClaw는 멀티 에이전트 오케스트레이션을 위해 sessions_spawn, sessions_yield, subagents 도구를 지원합니다.
메인 에이전트에게 "최신 AI 논문을 찾아서 코드로 구현해 줘"라고 지시하면, 메인 에이전트가 sessions_spawn으로 researcher와 coder 서브 에이전트를 백그라운드에서 소환하여 각자 작업을 처리한 뒤 최종 결과를 취합해 보고합니다. 사용자는 단 한 번의 지시로 AI 팀 전체가 일하는 결과를 받을 수 있습니다.
오케스트레이션 도구 활성화 방법
에이전트가 다른 에이전트를 소환하려면 openclaw.json의 tools 설정에서 해당 도구를 명시적으로 활성화해야 합니다.
{
"tools": {
"enabled": ["sessions_spawn", "sessions_yield", "subagents"]
}
}AGENTS.md를 만들어 워크스페이스 하위 폴더에 저장하고, agents.list의 에이전트 설정에서 "workspaceDir"를 지정하면 에이전트별로 완전히 다른 성격과 규칙을 부여할 수 있습니다.비용 폭탄 방지 — 동시 처리 한도 설정
멀티에이전트 운영에서 가장 주의해야 할 것은 API 비용 폭탄입니다. 하나의 에이전트가 수십 개의 서브 에이전트를 무한히 소환하면 API 쿼터를 순식간에 소진할 수 있습니다. 반드시 동시 처리 한도를 설정해 안전장치를 만들어야 합니다.
{
"agents": {
"defaults": {
"maxConcurrent": 4,
"subagents": {
"maxConcurrent": 8
}
}
}
}각 항목의 의미
maxConcurrent: 4: 최상위 에이전트 세션이 동시에 최대 4개까지만 실행됩니다. 그 이상의 요청은 대기열에서 순서를 기다립니다.subagents.maxConcurrent: 8: 한 에이전트가 소환할 수 있는 서브 에이전트의 동시 실행 수를 8개로 제한합니다. 무한 재귀 소환을 차단하는 핵심 안전장치입니다.
maxConcurrent를 낮은 값(2~4)으로 시작하세요. 에이전트 간 협업이 예상치 못한 방식으로 연쇄 실행되면 수 분 내에 API 쿼터가 소진될 수 있습니다. 안정성이 확인된 후 점진적으로 한도를 높이세요.agents.list로 에이전트 팀을 구성하고, bindings로 채널별 담당자를 지정하며, maxConcurrent로 비용 안전장치를 설정하세요. 이 세 가지가 openclaw 멀티에이전트 운영의 완성입니다.
실전 팁과 주의사항
- defaults는 저렴한 모델로, 특수 에이전트만 고급 모델 배정:
agents.defaults에 가장 저렴한 모델을 기본으로 설정하고, 코딩·분석 등 특수 목적 에이전트만 고성능 모델로 덮어쓰면 비용 효율을 극대화할 수 있습니다. - bindings 변경 후 반드시 gateway restart 필요: 채널 라우팅(
bindings) 설정은AGENTS.md와 달리 Hot Reload가 적용되지 않습니다. 변경 후 반드시openclaw gateway restart를 실행해야 새 라우팅 규칙이 반영됩니다. - 에이전트 추가 후 openclaw doctor --fix로 설정 검증: 에이전트를 새로 추가하거나 설정을 변경했다면
openclaw doctor --fix를 실행해 잘못된 위치의 키나 누락된 필수 설정을 자동으로 교정받으세요. - 서브 에이전트 소환 도구는 필요할 때만 활성화:
sessions_spawn등 오케스트레이션 도구는 활성화하면 에이전트가 언제든 서브 에이전트를 소환할 수 있습니다. 의도치 않은 연쇄 실행을 막으려면 필요한 에이전트에만 선택적으로 활성화하세요.
자주 묻는 질문 (FAQ)
- 여러 에이전트를 동시에 돌리면 서버 리소스나 API 비용이 폭발하지 않나요?
- 충분히 주의해야 할 부분입니다. 이를 막기 위해 반드시
"maxConcurrent": 4,"subagents": { "maxConcurrent": 8 }처럼 동시 처리 한도를 합리적으로 제한해 두어야 합니다. 처음에는 낮은 값으로 시작하고 운영이 안정되면 점진적으로 높여가세요. - 각 에이전트마다 서로 다른 AI 모델(Claude와 GPT 등)을 설정할 수 있나요?
- 네, 가능합니다.
agents.defaults에 가장 저렴한 범용 모델을 기본으로 설정한 뒤,agents.list의 특정 에이전트 블록에서만model.primary값을 고성능 모델로 덮어쓰기(Override)하면 됩니다. 일상 대화로 비싼 토큰을 낭비하는 일을 막을 수 있습니다. - 메인 에이전트가 서브 에이전트에게 일을 알아서 시키게 하려면 어떻게 하나요?
openclaw.json의tools.enabled에sessions_spawn과subagents를 추가해 도구를 활성화하면, AI가 복잡한 요청을 받았을 때 스스로 서브 태스크를 쪼개어 다른 에이전트를 백그라운드에서 구동하고 결과를 취합합니다.- 에이전트를 추가했는데 설정이 적용되지 않는 것 같습니다.
compaction,contextPruning등 일부 설정은agents.list개별 블록이 아닌 반드시agents.defaults전역 레벨에만 작성해야 정상 동작합니다. 터미널에서openclaw doctor --fix를 실행하면 잘못된 위치의 키를 자동으로 찾아 수정해 주니 꼭 활용하세요.
이 글이 도움이 됐다면 댓글로 여러분의 경험을 알려주세요! 🙌
openclaw 멀티에이전트 구성에서 막히는 부분은 댓글에 남겨주세요 — 직접 답변드립니다.
📬 새 편 알림 받기 → AI 활용 가이드 구독
댓글