홈 튜토리얼 카테고리 Skills 소개
ZH EN JA KO
기본 설정

OpenClaw 다중 모델 전환 및 라우팅 구성 튜토리얼

· 16 분 소요

들어가며

OpenClaw의 큰 장점 중 하나는 Claude, OpenAI, Ollama, Gemini, OpenRouter 등 여러 AI 모델 제공업체를 동시에 연결할 수 있다는 것입니다. 유연한 라우팅 규칙을 통해 채널별 모델 할당, 키워드 기반 모델 매칭, 장애 시 자동 전환 등 고급 기능을 구현할 수 있습니다. 본 문서에서는 다중 모델 전환 및 라우팅 구성 방법을 상세히 안내합니다.

여러 모델 제공업체 구성

openclaw.json5의 models.providers에 여러 제공업체를 구성합니다.

{
  models: {
    // 기본 사용 제공업체
    default: "claude",

    providers: {
      // Anthropic Claude
      claude: {
        apiKey: "$env:OPENCLAW_CLAUDE_API_KEY",
        model: "claude-sonnet-4-20250514",
        maxTokens: 4096,
        temperature: 0.7,
      },

      // 고급 Claude 모델 (복잡한 작업용)
      "claude-opus": {
        apiKey: "$env:OPENCLAW_CLAUDE_API_KEY",
        model: "claude-opus-4-20250514",
        maxTokens: 4096,
        temperature: 0.5,
      },

      // OpenAI
      openai: {
        apiKey: "$env:OPENCLAW_OPENAI_API_KEY",
        model: "gpt-4o",
        maxTokens: 4096,
        temperature: 0.7,
      },

      // 로컬 Ollama (무료, API 키 불필요)
      ollama: {
        baseUrl: "http://localhost:11434",
        model: "llama3.1:70b",
        maxTokens: 2048,
        temperature: 0.8,
      },

      // Google Gemini
      gemini: {
        apiKey: "$env:OPENCLAW_GEMINI_API_KEY",
        model: "gemini-2.0-flash",
        maxTokens: 4096,
      },

      // OpenRouter (여러 모델 통합)
      openrouter: {
        apiKey: "$env:OPENCLAW_OPENROUTER_API_KEY",
        model: "anthropic/claude-sonnet-4-20250514",
        baseUrl: "https://openrouter.ai/api/v1",
      },
    },
  },
}

위의 claude와 claude-opus처럼 동일한 제공업체에 대해 다른 모델명으로 여러 인스턴스를 구성할 수 있습니다.

수동 모델 전환

구성 완료 후 사용자는 채팅에서 명령어를 통해 현재 사용 중인 모델을 전환할 수 있습니다.

/model claude        → Claude Sonnet으로 전환
/model claude-opus   → Claude Opus로 전환
/model openai        → GPT-4o로 전환
/model ollama        → 로컬 Ollama로 전환
/model list          → 사용 가능한 모든 모델 보기
/model reset         → 기본 모델로 복원

모델 라우팅 규칙

라우팅 규칙을 통해 OpenClaw가 조건에 따라 가장 적합한 모델을 자동으로 선택하도록 할 수 있습니다.

기본 라우팅 구성

{
  models: {
    default: "claude",
    providers: { /* ... */ },

    routing: {
      // 라우팅 규칙 (우선순위 높은 순서대로 정렬)
      rules: [
        {
          name: "코딩 작업에 Claude Opus 사용",
          match: {
            keywords: ["코드 작성", "프로그래밍", "debug", "코드 리뷰", "code"],
          },
          provider: "claude-opus",
        },
        {
          name: "번역 작업에 Gemini 사용",
          match: {
            keywords: ["번역", "translate", "영한번역", "한영번역"],
          },
          provider: "gemini",
        },
        {
          name: "일상 대화에 로컬 모델 사용",
          match: {
            keywords: ["대화", "잡담", "안녕", "ㅋㅋ"],
          },
          provider: "ollama",
        },
      ],

      // 어떤 규칙에도 매칭되지 않을 때의 기본 제공업체
      fallback: "claude",
    },
  },
}

채널별 라우팅

서로 다른 통신 채널에 서로 다른 모델을 지정합니다.

{
  models: {
    routing: {
      rules: [
        {
          name: "Telegram에는 Claude 사용",
          match: {
            channel: "telegram",
          },
          provider: "claude",
        },
        {
          name: "Discord에는 GPT-4o 사용",
          match: {
            channel: "discord",
          },
          provider: "openai",
        },
        {
          name: "Slack 업무 그룹에는 Claude Opus 사용",
          match: {
            channel: "slack",
          },
          provider: "claude-opus",
        },
        {
          name: "WhatsApp에는 Gemini 사용 (비용 절감)",
          match: {
            channel: "whatsapp",
          },
          provider: "gemini",
        },
      ],
      fallback: "claude",
    },
  },
}

사용자별 라우팅

특정 사용자에게 모델을 지정합니다.

{
  models: {
    routing: {
      rules: [
        {
          name: "VIP 사용자에게 Opus 사용",
          match: {
            users: ["user_001", "user_002"],
          },
          provider: "claude-opus",
        },
        {
          name: "일반 사용자에게 Sonnet 사용",
          match: {
            users: ["*"],  // 와일드카드로 모든 사용자 매칭
          },
          provider: "claude",
        },
      ],
    },
  },
}

시간대별 라우팅

서로 다른 시간대에 서로 다른 모델을 사용합니다 (예: 야간에 더 저렴한 모델 사용).

{
  models: {
    routing: {
      rules: [
        {
          name: "업무 시간에 고급 모델 사용",
          match: {
            timeRange: {
              start: "09:00",
              end: "18:00",
              timezone: "Asia/Shanghai",
              weekdays: [1, 2, 3, 4, 5],  // 월요일~금요일
            },
          },
          provider: "claude-opus",
        },
        {
          name: "비업무 시간에 경제적 모델 사용",
          match: {
            timeRange: {
              start: "18:00",
              end: "09:00",
              timezone: "Asia/Shanghai",
            },
          },
          provider: "gemini",
        },
      ],
    },
  },
}

조건 조합

여러 조건을 조합할 수 있으며, 조건 간의 관계는 AND입니다.

{
  name: "Slack의 코딩 작업에 Opus 사용",
  match: {
    channel: "slack",
    keywords: ["코드", "code", "debug"],
  },
  provider: "claude-opus",
},

장애 시 자동 전환 체인

주 모델을 사용할 수 없는 경우 OpenClaw가 자동으로 백업 모델로 전환할 수 있습니다.

{
  models: {
    default: "claude",
    providers: { /* ... */ },

    // 장애 전환 체인
    fallbackChain: [
      "claude",       // 1순위
      "openai",       // 1차 백업
      "gemini",       // 2차 백업
      "ollama",       // 최종 대체 (로컬 모델, 항상 사용 가능)
    ],

    // 전환 트리거 조건
    fallbackPolicy: {
      // 연속 실패 횟수 후 전환 트리거
      maxFailures: 3,

      // 전환 후 복구 시도까지 대기 시간
      recoveryInterval: 300,  // 초

      // 시간 초과 (초과 시 실패로 간주)
      timeout: 30000,  // 밀리초

      // 전환 발생 시 알림 방법
      notification: {
        enabled: true,
        message: "모델 {provider}을(를) 사용할 수 없어 {fallback}(으)로 자동 전환했습니다",
      },
    },
  },
}

전환 프로세스 설명

사용자가 메시지 전송
    ├─ Claude 시도 → 성공 → 응답 반환
    │                  실패 ↓
    ├─ OpenAI 시도 → 성공 → 응답 반환
    │                  실패 ↓
    ├─ Gemini 시도 → 성공 → 응답 반환
    │                  실패 ↓
    └─ Ollama 시도 → 성공 → 응답 반환 (로컬 모델)
                       실패 → 오류 메시지 반환

로드 밸런싱

동일 모델에 대한 여러 API 키가 있는 경우 로드 밸런싱을 구성할 수 있습니다.

{
  models: {
    providers: {
      "claude-pool": {
        type: "pool",
        strategy: "round-robin",  // round-robin, random, least-used
        instances: [
          {
            apiKey: "sk-ant-key-1",
            model: "claude-sonnet-4-20250514",
            weight: 1,
          },
          {
            apiKey: "sk-ant-key-2",
            model: "claude-sonnet-4-20250514",
            weight: 1,
          },
          {
            apiKey: "sk-ant-key-3",
            model: "claude-sonnet-4-20250514",
            weight: 2,  // 가중치가 높아 더 많은 요청 할당
          },
        ],
      },
    },
  },
}

로드 밸런싱 전략 설명:

전략 설명
round-robin 라운드 로빈, 각 인스턴스를 순서대로 사용
random 랜덤 선택 (가중치 기반)
least-used 현재 사용량이 가장 적은 인스턴스 선택

비용 제어

여러 유료 모델을 사용할 때 비용 경고 및 제한을 설정할 수 있습니다.

{
  models: {
    costControl: {
      // 일일 예산 (달러)
      dailyBudget: 10.0,

      // 월간 예산
      monthlyBudget: 200.0,

      // 예산 도달 시 동작
      onBudgetReached: "switch-to-free",  // switch-to-free, warn, block

      // 무료/저비용 모델
      freeProvider: "ollama",

      // 경고 임계값 (예산의 백분율에 도달하면 알림 전송)
      warningThreshold: 0.8,
    },
  },
}

모델 사용 통계 확인

Dashboard에서 각 모델의 사용 현황을 확인할 수 있습니다. 명령줄을 통해서도 확인할 수 있습니다.

# Dashboard 열기
openclaw dashboard

# 현재 구성된 모든 모델 확인
openclaw skill list

Dashboard 주소: http://localhost:18789/dashboard, 통계 페이지에서 다음을 확인할 수 있습니다.

  • 각 모델의 호출 횟수
  • 각 모델의 평균 응답 시간
  • 토큰 사용량
  • 비용 추정
  • 전환 이벤트 기록

전체 구성 예제

다음은 다중 모델 라우팅, 장애 전환 및 비용 제어가 포함된 완전한 구성입니다.

{
  gateway: {
    port: 18789,
    host: "0.0.0.0",
  },

  models: {
    default: "claude",

    providers: {
      claude: {
        apiKey: "$env:OPENCLAW_CLAUDE_API_KEY",
        model: "claude-sonnet-4-20250514",
        maxTokens: 4096,
      },
      openai: {
        apiKey: "$env:OPENCLAW_OPENAI_API_KEY",
        model: "gpt-4o",
        maxTokens: 4096,
      },
      ollama: {
        baseUrl: "http://localhost:11434",
        model: "llama3.1",
      },
    },

    routing: {
      rules: [
        {
          name: "Slack에는 Claude 사용",
          match: { channel: "slack" },
          provider: "claude",
        },
        {
          name: "잡담에는 로컬 모델 사용",
          match: { keywords: ["대화", "잡담"] },
          provider: "ollama",
        },
      ],
      fallback: "claude",
    },

    fallbackChain: ["claude", "openai", "ollama"],

    costControl: {
      dailyBudget: 5.0,
      monthlyBudget: 100.0,
      onBudgetReached: "switch-to-free",
      freeProvider: "ollama",
    },
  },
}

마무리

OpenClaw의 다중 모델 아키텍처를 통해 단일 AI 제공업체에 종속되지 않을 수 있습니다. 유연한 라우팅 규칙으로 작업 유형, 통신 채널, 사용자 신원, 심지어 시간대에 따라 지능적으로 모델을 할당할 수 있습니다. 장애 전환 체인을 함께 사용하면 특정 제공업체가 다운되더라도 AI 어시스턴트가 계속 서비스를 제공할 수 있습니다. 간단한 구성부터 시작하여 실제 사용 상황에 따라 라우팅 규칙과 전환 전략을 점진적으로 추가하는 것을 권장합니다.

OpenClaw는 무료 오픈소스 개인 AI 어시스턴트로, WhatsApp, Telegram, Discord 등 다양한 플랫폼을 지원합니다
더 많은 튜토리얼 Skills 다운로드

관련 튜토리얼

Gateway 설정 완전 레퍼런스
openclaw onboard 대화형 가이드 튜토리얼
openclaw configure 설정 마법사 튜토리얼