OpenClaw에서 OpenRouter를 통한 다중 모델 연동 가이드

서문

OpenRouter는 통합 AI 모델 게이트웨이로, 하나의 API Key만으로 Claude, GPT, Gemini, Llama, Mistral 등 거의 모든 주요 대규모 모델에 접근할 수 있습니다. 여러 플랫폼에 각각 가입하고 싶지 않은 사용자에게 OpenRouter는 매우 편리한 선택입니다. 본 가이드에서는 OpenClaw에서 OpenRouter를 설정하는 방법을 상세히 설명합니다.

OpenRouter의 장점

특성	설명
원스톱 연동	하나의 API Key로 200개 이상 모델 접근
통합 과금	모든 모델 비용을 일괄 정산
자동 장애 전환	특정 제공자에 문제 발생 시 자동으로 대안으로 전환
VPN 불필요	일부 모델은 직접 접근 가능 (지역에 따라 다름)
무료 모델	일부 오픈소스 모델의 무료 할당량 제공

1단계: OpenRouter 가입 및 API Key 발급

1.1 계정 등록

openrouter.ai에 접속합니다
Google 계정 또는 이메일로 가입합니다
가입 완료 후 Dashboard에 진입합니다

1.2 API Key 생성

Keys 페이지에 진입합니다
Create Key를 클릭합니다
이름을 입력합니다 (예: openclaw-prod)
생성된 키를 복사합니다

API Key 형식:

sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

1.3 충전 (선택)

OpenRouter는 다양한 결제 수단을 지원합니다. 일부 오픈소스 모델에는 무료 할당량이 있지만, Claude, GPT 등 상용 모델은 사전 충전이 필요합니다. 먼저 $5를 충전하여 시험해 보는 것을 권장합니다.

2단계: 기본 설정

2.1 설정 파일 편집

nano ~/.config/openclaw/openclaw.json5

OpenRouter 설정을 추가합니다:

{
  models: {
    openrouter: {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "anthropic/claude-sonnet-4",
    }
  }
}

2.2 환경 변수 설정

# ~/.bashrc에 추가
export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
source ~/.bashrc

2.3 재시작 및 검증

openclaw restart
openclaw doctor

3단계: 사용 가능한 모델 목록

OpenRouter를 통해 다음과 같은 주요 모델에 접근할 수 있습니다:

모델	OpenRouter 식별자	입력 가격 (백만 토큰당)	출력 가격 (백만 토큰당)
Claude Sonnet 4	anthropic/claude-sonnet-4	$3.00	$15.00
Claude Haiku 3.5	anthropic/claude-3.5-haiku	$0.80	$4.00
GPT-4o	openai/gpt-4o	$2.50	$10.00
GPT-4o mini	openai/gpt-4o-mini	$0.15	$0.60
Gemini 2.5 Pro	google/gemini-2.5-pro	$1.25	$10.00
Gemini 2.5 Flash	google/gemini-2.5-flash	$0.15	$0.60
Llama 3.3 70B	meta-llama/llama-3.3-70b	$0.10	$0.10
DeepSeek V3	deepseek/deepseek-chat	$0.14	$0.28
Mistral Large	mistralai/mistral-large	$2.00	$6.00
Qwen 2.5 72B	qwen/qwen-2.5-72b-instruct	$0.15	$0.15

3.1 무료 모델

OpenRouter는 일부 모델의 무료 할당량을 제공하며, 시험 사용 및 저빈도 사용에 적합합니다:

{
  models: {
    "openrouter-free": {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "meta-llama/llama-3.3-70b:free",  // 무료 버전 식별자
    }
  }
}

참고: 무료 모델은 속도 제한이 엄격하여 고빈도 사용에는 적합하지 않습니다.

4단계: 다중 모델 설정

OpenRouter의 핵심 장점은 여러 모델을 유연하게 전환할 수 있다는 점입니다.

4.1 채널별 다른 모델 설정

{
  models: {
    "router-premium": {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "anthropic/claude-sonnet-4",
    },
    "router-standard": {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "google/gemini-2.5-flash",
    },
    "router-budget": {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "meta-llama/llama-3.3-70b",
    }
  },
  channels: {
    whatsapp: {
      model: "router-premium",     // WhatsApp에서는 최강 모델 사용
    },
    telegram: {
      model: "router-standard",   // Telegram에서는 중간급 모델 사용
    },
    discord: {
      model: "router-budget",     // Discord에서는 경제적 모델 사용
    }
  }
}

4.2 모델 라우팅 전략

OpenRouter는 요청 내용에 따라 자동으로 가장 적합한 모델을 선택하는 자동 라우팅 기능을 지원합니다:

{
  models: {
    "router-auto": {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "openrouter/auto",   // 최적 모델 자동 선택
      parameters: {
        temperature: 0.7,
      }
    }
  }
}

5단계: 장애 전환 설정

특정 모델 제공자에 장애가 발생하면 OpenRouter가 자동으로 대체 모델로 전환할 수 있습니다.

5.1 Fallback 목록 설정

{
  models: {
    "router-resilient": {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "anthropic/claude-sonnet-4",
      fallbackModels: [
        "openai/gpt-4o",
        "google/gemini-2.5-pro",
        "deepseek/deepseek-chat",
      ],
      retryOnFailure: true,
      maxRetries: 2,
    }
  }
}

5.2 작동 원리

장애 전환 트리거 흐름:

요청 전송 → Claude Sonnet 4
    ↓ 실패
재시도 → GPT-4o
    ↓ 실패
재시도 → Gemini 2.5 Pro
    ↓ 실패
최종 재시도 → DeepSeek Chat
    ↓ 성공
응답 반환

이러한 설정은 매우 높은 가용성을 보장하며, 특정 제공자가 완전히 다운되더라도 서비스에 영향을 미치지 않습니다.

6단계: 비용 최적화

6.1 예산 한도 설정

OpenRouter Dashboard에서 총 예산과 일일 한도를 설정할 수 있습니다. 동시에 OpenClaw 설정에서도 추가적인 제어 레이어를 구성할 수 있습니다:

{
  models: {
    openrouter: {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "google/gemini-2.5-flash",
      budget: {
        dailyLimit: 2.00,          // 일일 최대 $2 지출
        monthlyLimit: 30.00,       // 월간 최대 $30 지출
        alertThreshold: 0.8,       // 80% 도달 시 알림 발송
      }
    }
  }
}

6.2 작업 복잡도에 따른 모델 선택 전략

현명한 방법은 작업 유형에 따라 동적으로 모델을 선택하는 것입니다:

{
  models: {
    "router-smart": {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "google/gemini-2.5-flash",    // 기본으로 저렴한 모델 사용
      complexModel: "anthropic/claude-sonnet-4",   // 복잡한 작업에는 강력한 모델 사용
      complexTriggers: [
        "代码",
        "分析",
        "翻译长文",
        "写文章",
      ]
    }
  }
}

7단계: 고급 설정 옵션

7.1 커스텀 HTTP Headers

일부 시나리오에서는 추가 HTTP 헤더 정보를 전달해야 할 수 있습니다:

{
  models: {
    openrouter: {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "anthropic/claude-sonnet-4",
      headers: {
        "HTTP-Referer": "https://your-site.com",  // OpenRouter의 소스 통계에 도움
        "X-Title": "OpenClaw Assistant",           // OpenRouter 로그에 표시
      }
    }
  }
}

7.2 특정 제공자 비활성화

특정 제공자를 통한 모델 접근을 원하지 않는 경우:

{
  models: {
    openrouter: {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      defaultModel: "anthropic/claude-sonnet-4",
      providerPreferences: {
        exclude: ["azure"],        // Azure를 통한 모델 사용 안 함
        prefer: ["anthropic"],     // Anthropic 직접 연결 우선
      }
    }
  }
}

자주 묻는 질문

잔액 부족

Error: 402 Payment Required - Insufficient credits

OpenRouter Dashboard에서 충전하면 즉시 복구됩니다.

모델 사용 불가

Error: 503 Model temporarily unavailable

이는 보통 상위 제공자의 일시적인 문제입니다. fallbackModels가 설정되어 있으면 자동으로 전환되며, 그렇지 않은 경우 몇 분 후에 다시 시도하십시오.

응답 속도 저하

OpenRouter는 중간 계층으로서 약간의 지연이 추가됩니다 (보통 100-300ms). 지연에 극도로 민감한 경우 해당 모델 제공자에 직접 연결하는 것을 권장합니다.

요약

OpenRouter는 OpenClaw 생태계에서 강력한 모델 통합 솔루션입니다. 핵심 가치는 다중 모델 관리 간소화, 장애 전환 기능 제공, 통합 과금에 있습니다. 여러 모델을 유연하게 사용하면서도 각 제공자의 API를 별도로 관리하고 싶지 않은 사용자에게 OpenRouter는 최적의 선택입니다. 장애 전환 설정과 함께 백업 또는 주력 방안으로 활용하여 고가용성 AI 어시스턴트 서비스를 구현하는 것을 권장합니다.