OpenClaw 여러 에이전트와 모델: 라우팅, 격리 및 비용

OpenClaw의 멀티 에이전트와 여러 모델은 하나의 구성 파일에서 서로 다른 두 계층입니다. 여러 에이전트는 agents.entries 아래의 키가 지정된 항목이며, 각 항목은 자체 workspace, state directory 및 session store를 소유합니다. 반면 여러 모델은 이러한 항목 내부의 에이전트별 model 값입니다. 이들과 나란히 두 계층이 더 있습니다. bindings는 어떤 에이전트가 응답할지 결정하고, 폴백 체인은 모델이 실패했을 때 해당 에이전트가 무엇을 할지 결정합니다. 잘못된 계층을 편집하는 것이 변경 사항이 아무 효과가 없는 것처럼 보이는 가장 흔한 이유입니다.

소프트웨어 자체로는 에이전트를 더 실행해도 비용이 들지 않습니다. OpenClaw의 문서 개요에는 OpenClaw가 "독립적인 501(c)(3) 조직인 OpenClaw Foundation이 공개적으로 개발"하며 "유료 등급이 없고, 끌 수 있는 버전 확인 외에는 기본적으로 텔레메트리가 없으며, 어떤 연구소도 OpenClaw를 소유하지 않는다"고 명시되어 있습니다. 또한 openclaw.ai에는 "구독 없음. 호스팅 등급 없음. 토큰 없음."이라고 적혀 있습니다. npm 패키지 openclaw는 MIT 라이선스이며, latest는 2026.9.5, extended-stable 채널은 2026.7.35이고 engines.node는 >=24.16.0 <25 || >=26.1.0입니다(npm 레지스트리, 2026년 9월 21일 확인). 두 번째 에이전트가 청구서에 추가하는 것은 토큰 비용입니다.

OpenClaw 멀티 에이전트: 네 계층과 잘못된 계층을 편집했을 때의 증상

네 계층 모두 2026년 9월 21일 OpenClaw 자체 문서에서 확인했습니다: 항목 및 멀티 에이전트, 에이전트 바인딩 및 모델 장애 조치. 이전 튜토리얼에 있는 두 가지 형태는 오래되었습니다. agents.list 배열 목록은 Doctor가 마이그레이션하는 레거시 형식이고, 항목의 default: true 표시는 폐기되었습니다. 항목 페이지에는 "default는 폐기되었습니다"라고 명시되어 있으며, 멀티 에이전트 작업에는 바인딩 또는 명시적 대상이 필요합니다. OpenClaw는 이전에 두 가지 이름으로도 운영되었으므로, 발견하는 Moltbot 또는 Clawdbot 시대의 구성은 이 스키마보다 오래된 것입니다.

OpenClaw 멀티 에이전트 설정: 최소한의 2개 에이전트, 2개 모델 구성

이 조각은 이미 작동하는 models.providers 블록이 있다고 가정합니다. OpenClaw에 가장 적합한 API에는 api: "anthropic-messages"와 Anthropic base URL에 공개된 base URL을 포함한 Kunavo 항목이 들어 있습니다. 다음 내용은 에이전트 및 라우팅 계층뿐입니다.

{
  "agents": {
    "defaults": {
      "modelSelectionScope": "session",
      "model": {
        "primary": "kunavo/claude-haiku-4-5",
        "fallbacks": [
          "kunavo/claude-sonnet-5"
        ]
      }
    },
    "entries": {
      "ops": {
        "name": "Ops",
        "workspace": "~/.openclaw/workspace-ops",
        "agentDir": "~/.openclaw/agents/ops/agent",
        "model": "kunavo/claude-haiku-4-5",
        "modelPolicy": {
          "allow": [
            "kunavo/claude-haiku-4-5"
          ]
        }
      },
      "build": {
        "name": "Build",
        "workspace": "~/.openclaw/workspace-build",
        "agentDir": "~/.openclaw/agents/build/agent",
        "model": {
          "primary": "kunavo/claude-opus-5",
          "fallbacks": [
            "kunavo/claude-sonnet-5"
          ]
        },
        "utilityModel": "kunavo/claude-haiku-4-5"
      }
    }
  },
  "bindings": [
    {
      "agentId": "build",
      "match": {
        "channel": "discord",
        "accountId": "build"
      }
    },
    {
      "agentId": "ops",
      "match": {
        "channel": "discord",
        "accountId": "*"
      }
    }
  ]
}

이 블록에서 네 가지가 핵심입니다. 멀티 에이전트 페이지에서 "에이전트 간에 agentDir를 절대 재사용하지 마세요. 인증/세션 상태 충돌이 발생합니다."라고 경고하므로 각 에이전트는 자체 agentDir를 가집니다. ops 에이전트는 model의 문자열 형식을 사용하며, entries 페이지는 이를 "모델 폴백이 없는 엄격한 에이전트별 기본 모델"로 정의합니다. 따라서 실패가 표시되고 일반 작업이 더 비싼 등급으로 조용히 이동하지 않습니다. build 에이전트는 명시적인 fallbacks 목록이 있는 객체 형식을 사용하며, 이것이 에이전트의 폴백을 허용하는 방식입니다. failover 페이지에는 에이전트가 model: { fallbacks: [...] }만 설정하고 공유 기본 모델을 계속 상속할 수 있다고도 나와 있습니다. 하나의 일치 계층 안에서는 "처음 일치하는 bindings 항목이 승리"하므로 좁은 바인딩을 와일드카드보다 위에 배치합니다.

기본 에이전트와 나머지 에이전트의 workspace 기본값은 서로 다르므로 명시적으로 설정할 가치가 있습니다. 기본 에이전트의 workspace는 <stateDir>/workspace이고 다른 에이전트의 기본값은 <stateDir>/workspace-<agentId>입니다. OpenClaw의 내장 엔진은 "에이전트의 workspace에 일반 Markdown 파일을 작성해 정보를 기억"하므로 메모리는 workspace를 따릅니다. 따라서 workspace를 분리하면 메모리도 분리됩니다. 세션 권한 모드는 또 다른 별도 축입니다: read-only, guarded, workspace 및 full이며, "full에는 operator.admin가 필요합니다. 다른 모드에는 operator.write가 필요합니다"(권한 모드, 2026년 9월 21일). 권한이 넓은 에이전트에 저렴한 모델을 사용해도 여전히 권한이 넓은 에이전트입니다.

에이전트를 분리하면 무엇이 분리되고, 무엇은 분리되지 않나요

가격표에서 놓치는 경계가 바로 이것입니다. 항목을 분리하면 파일, 메모리, 기록, 도구 정책, 저장된 인증 프로필도 각각 분리됩니다. 하지만 이것만으로 환경 설정에 구성된 사용자 지정 제공자에 대해 각 에이전트에 고유한 API 키가 부여되는 것은 아닙니다. 문서에 명시된 에이전트별 스키마에는 baseUrl, apiKey, providers 필드가 전혀 없습니다. 문서에 없다는 사실이 코드에서 이를 금지한다는 증거는 아니므로, 이는 문서화되지 않음으로 이해해야 합니다. 테넌트별로 키를 엄격하게 분리해야 한다면 별도의 Gateways를 실행하세요. 이와 관련된 제약은 발신자 신원에도 적용됩니다. OpenClaw의 WhatsApp DM 분리 예제에는 "답장은 여전히 동일한 WhatsApp 번호에서 발송되며, 에이전트별 발신자 신원은 없습니다"라고 명시되어 있으며, "직접 대화는 기본적으로 에이전트의 메인 세션 키 하나로 통합되므로, 진정한 격리를 위해서는 사람마다 에이전트 하나가 필요합니다"라고도 설명되어 있습니다. 이 문장은 WhatsApp에 대해 명시된 내용이므로, 일반화하기 전에 사용 중인 채널의 페이지를 확인하세요.

역할을 분리할 때 알아둘 기능 경계가 하나 더 있습니다. Kunavo는 text-to-speech, speech-to-text 또는 embedding 모델을 제공하지 않으므로 음성 출력이나 벡터 인덱스가 필요한 에이전트는 해당 단계에서 외부 공급자를 호출해야 합니다.

OpenClaw 여러 모델: 엄격 모드, 폴백, 정책 및 utility 경로

에이전트별 모델 선택에는 의도적으로 설정할 가치가 있는 네 가지 제어 기능이 있습니다. 문자열 형식의 model는 엄격합니다. { primary, fallbacks: [...] }는 해당 에이전트의 폴백을 활성화합니다. modelPolicy.allow는 "해당 에이전트의 기본 정책을 대체"하는 허용 목록입니다. 별칭, 정확한 참조 및 뒤따르는 와일드카드를 허용하므로 일반 에이전트가 비싼 모델에 도달하지 못하게 할 수 있습니다. 그리고 utilityModel는 "생성된 세션 및 스레드 제목과 같은 짧은 내부 작업"에 사용하는 별도의, 일반적으로 더 저렴한 모델이며 에이전트별 재정의를 지원합니다.

문서화된 트리거 목록은 구체적입니다. OpenClaw는 "인증 실패, 속도 제한 및 쿨다운 소진, 과부하/공급자 사용 중 오류, 타임아웃 형태의 폴백 오류, 결제 비활성화, model_not_found" 및 후보가 남아 있는 동안의 기타 인식되지 않은 오류에서 다음 모델로 진행합니다. 그러나 컨텍스트 초과 오류에서는 진행하지 않고 압축 및 재시도 로직 내부에 남으며, "타임아웃/폴백 형태가 아닌 명시적 중단"에서도 진행하지 않습니다. 그룹 및 채널 대화 밖에서는 이 동작이 표시됩니다. 해당 화면은 Model Fallback: <fallback> (selected <primary>; <reason>) 형식의 상태 알림과 이에 대응하는 해제 알림을 게시합니다. 반면 그룹 및 채널 대화에서는 "동일한 폴백 상태를 유지하면서 표시되는 알림을 억제"하므로 공유 방에서 이러한 알림이 보일 것이라고 기대하지 마세요. 명시적 세션 선택인 /model, 모델 선택기, session_status(model=...) 또는 sessions.patch는 엄격합니다. 해당 모델이 답변을 생성하기 전에 실패하면 OpenClaw는 구성된 폴백으로 답변하지 않고 실패를 보고합니다. cron 작업의 --model는 그중 하나가 아닙니다. 문서에서는 이를 구성된 폴백을 계속 사용하는 작업 기본 모델이라고 하며, 작업이 payload.fallbacks: []를 설정한 경우는 예외입니다.

의도가 유지되는지 여부를 결정하는 메커니즘이 두 가지 더 있습니다. 요청 매개변수는 agents.defaults.params에서 agents.entries.*.params까지 네 계층을 거쳐 병합되며, 나중 계층이 키별로 이전 계층을 덮어씁니다. 병렬 처리에도 계산된 상한이 있습니다. agents.defaults.maxConcurrent는 세션 전체에서 max(8, available CPU parallelism * 4)를 기본값으로 하며, 각 세션은 직렬로 유지됩니다. 즉, 하나의 에이전트에 대한 두 메시지가 동시에 실행되지는 않습니다. 각 역할에 어떤 모델을 배치할지 선택하려면 Opus vs Sonnet vs Haiku에서 기능 측면을 확인하세요.

에이전트가 아니라 경로별 비용 배분

에이전트별 지출을 보고하는 문서화된 명령이 없으므로 경로별로 배분하세요. 아래 계산은 측정된 청구액이 아니며 상한도 아닌 예시입니다. 30일 한 달, 문서화된 30m heartbeat 기본값(1,440회 실행), heartbeat당 출력 토큰 300개, 캐시 적중 없음, 주 대화 경로의 입력 토큰 8M 및 출력 토큰 500K를 가정합니다. 실행당 약 100K 및 약 2–5K의 컨텍스트 수치는 isolatedSession가 제거하는 내용을 보여주는 OpenClaw 자체의 예시일 뿐이며 여기서 측정한 값이 아닙니다. 3,000은 중간값입니다. 요금은 백만 토큰당 Kunavo 카탈로그의 최신 가격입니다.

Claude Haiku 4.5에는 실시간 카탈로그에서 백만 입력/출력 토큰당 $0.70 / $3.50가 표시되고, Claude Opus 5에는 $3.50 / $17.50가 표시됩니다. 중요한 해석은 다음과 같습니다. 이러한 가정에서는 예약된 경로가 지배적입니다. 강한 모델을 사용하는 공유 세션 heartbeat는 한 달에 $511.56가 되며, 동일한 주기를 저렴한 모델의 isolatedSession: true으로 실행하면 $4.54입니다. OpenClaw 자체도 이를 설명합니다. "Heartbeat는 전체 에이전트 턴을 실행합니다. 간격이 짧을수록 더 많은 토큰을 소비합니다." 또한 isolatedSession, lightContext, 더 저렴한 model 및 target: "none"를 조정 수단으로 제시합니다.

저렴한 하트비트 방식에는 문서화된 실패 모드가 있으며, 이것이 모델만 바꾸는 것보다 isolatedSession가 더 나은 조정 수단인 이유입니다. 하트비트는 "실행이 완료된 후 공유 세션의 기존 런타임 모델을 유지"하므로, 세션을 더 작은 모델로 전환한 하트비트가 다음 메인 세션 턴에도 그 모델을 그대로 남겨 둘 수 있습니다. 그러면 해당 턴에서 컨텍스트 초과가 보고될 수 있으며 OpenClaw의 복구 메시지는 이를 heartbeat model bleed라고 부릅니다. 문서에서 설명하는 예제는 32k 컨텍스트 윈도우의 로컬 모델이므로 위험의 크기는 하트비트 모델의 컨텍스트 윈도우가 공유 세션의 요구량보다 얼마나 작은지에 따라 달라집니다. 일정 관련 참고 사항으로, 문서화된 기본 간격은 30m이며, 실제로 결정된 인증 모드가 Anthropic OAuth/token일 때만 1h로 늘어납니다. 따라서 일반 API 키 경로는 heartbeat.every를 직접 설정하지 않는 한 30분을 유지합니다. 예산을 세우기 전에 자신의 설정값을 확인하세요.

달러 수치에 관한 주의 사항은 두 가지입니다. Kunavo 카탈로그 금액은 상한이 아니라 청구 하한입니다. 업스트림이 요금을 보고하면 청구액은 카탈로그 비용과 해당 마크업을 적용한 업스트림 비용 중 더 큰 금액입니다. 또한 모델별 cost 객체 없이 선언된 custom provider는 OpenClaw 자체 표시를 쓸모없게 만듭니다. OpenClaw는 cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }를 기본값으로 사용하여 공급자가 정상적으로 청구하는 동안에도 $0을 표시합니다. 추가하는 각 모델에 cost, contextWindow 및 maxTokens를 선언하고 공급자 원장과 대조하세요. Kunavo의 최소 충전액은 선불 크레딧 $10입니다. 이는 자금 충전 최소액이지 작업 수수료나 구독료가 아닙니다. 청구 세부 정보 및 AI 비용 최적화를 참조하세요.

멀티 에이전트 Gateway에 적합한 구매 경로

캐싱이 비용 절감의 핵심이므로 API 방식에 관해 한 가지 짚고 넘어가겠습니다. 관련 가이드의 Kunavo 블록은 api: "anthropic-messages"를 선언하며, OpenClaw는 이를 Anthropic에 직접 연결되는 엔드포인트가 아닌 것으로 취급합니다. 이에 따라 문서에 명시된 결과는 두 가지입니다. 이러한 엔드포인트에서는 암시적 Anthropic 베타 헤더가 억제되므로, 교차 추론과 같은 기능은 자동으로 활성화되지 않고 명시적인 headers["anthropic-beta"]를 통해 선택해야 합니다. 또한 캐싱은 직접 요청해야 합니다. OpenClaw는 직접 연결되는 anthropic 및 anthropic-vertex 공급자에 대해서만 cacheRetention: "short"를 초기 설정하며, "사용자 지정 anthropic-messages 호환 엔드포인트"는 "cacheRetention가 명시적으로 설정된 경우" 지원됩니다. 따라서 기본값을 가정하지 말고 직접 params.cacheRetention를 설정하세요(프롬프트 캐싱, 2026년 9월 21일). 다른 API 방식에는 별도 규칙이 있습니다. 네이티브가 아닌 엔드포인트로 연결되는 openai-completions 경로에서는 "프롬프트 캐시 힌트가 전송되지 않습니다". 반복되는 컨텍스트를 캐시 적중으로 간주하여 예산에 반영하기 전에 자신의 경로에서 보고된 캐시 사용량을 확인하세요. 프롬프트 캐싱에서 요금 측면을 다룹니다.

의도한 위치에 적용되었는지 확인하세요

openclaw config validate
openclaw gateway restart
openclaw agents list --bindings
openclaw models status --agent ops --json --check
openclaw models list --agent build

구성 검증은 형식을 확인하고 Gateway 재시작은 구성을 다시 로드하지만, 어느 것도 요금이 청구된 요청이 성공했다는 증거는 아닙니다. openclaw agents list --bindings는 실제로 로드된 라우팅을 보여주므로, 개념 페이지에는 나오지만 CLI 명령 표에는 나오지 않는 --tree보다 우선하세요. openclaw models status --agent <id>는 해당 에이전트의 구성된 기본값을 설명하고, models list --agent <id>는 해당 에이전트의 목록을 보여줍니다. 알 수 없는 공급자에서 models set가 0이 아닌 상태로 종료되면 모델 계층의 문제입니다. 해당 공급자는 설치된 플러그인이거나 models.providers 아래에 선언되어 있어야 합니다. 메시지가 어떤 에이전트에도 도달하지 않으면 라우팅 계층의 문제입니다. 여러 에이전트가 하나의 채널을 공유할 때 중복 실행이 나타나면 OpenClaw는 봇 루프 방지 키를 보호 장치로 문서화합니다. 문서는 방지를 설명할 뿐 근본 원인을 설명하지 않으므로, 추측하기 전에 진단하세요.

그런 다음 에이전트별로 하나의 제한된 작업을 실행하고 공급자 계정에 기록된 비용을 확인하세요. Kunavo는 OpenClaw를 단일 에이전트 또는 멀티 에이전트로 런타임 테스트하지 않았습니다. 위의 모든 내용은 OpenClaw가 공개한 문서에서 읽은 것이며, 공개된 구성은 호환성 테스트가 아닙니다. 시도하는 동안 작동하는 경로를 유지하세요. 공급자 구성에서 시작하고, OpenClaw 가격에서 전체 운영 비용을 비교한 다음, 키에 자금을 충전할 준비가 되면 Kunavo 계정을 생성하세요.

자주 묻는 질문

OpenClaw 문서, CLI 참조 및 npm 레지스트리 항목을 2026년 9월 21일 패키지 버전 2026.9.5에서 확인했으며, 여기서는 Gateway, 에이전트, 바인딩 또는 유료 요청을 실행하지 않았습니다. Kunavo 토큰 요금은 실시간 카탈로그에서 읽었으며, 이 페이지의 모든 달러 수치는 측정된 청구액이 아니라 예시 토큰 계산입니다.