OpenClaw + LiteLLM 통합

OpenClaw + LiteLLM 통합

OpenClaw는 채팅 앱(WhatsApp, Telegram, Discord 등)을 LLM 제공자에 연결하는 자체 호스팅 AI 어시스턴트예요. OpenClaw를 LiteLLM Proxy로 라우팅하면 단일 게이트웨이에서 100개 이상의 제공자, 비용 추적, 지출 상한, 자동 장애 조치에 접근할 수 있습니다.

구성하는 것

Chat apps → OpenClaw Gateway → LiteLLM Proxy → LLM Providers (OpenAI, Anthropic, etc.)

전제 조건

| Requirement | How to get it | | Node.js 22+ | node --version — install from nodejs.org if needed | | Python 3.10+ | python --version | | At least one LLM API key | OpenAI, Anthropic, Gemini, etc. |

1단계: LiteLLM Proxy 설치

uv tool install 'litellm[proxy]'

2단계: LiteLLM config 파일 생성

사용하려는 모델로 config 파일 litellm_config.yaml을 만드세요. OpenAI를 사용한 예시입니다:

litellm_config.yaml

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEYgeneral_settings:
  master_key: sk-you...-key  # pick any value — this is YOUR proxy password

다중 제공자 예시

다른 제공자에서 원하는 만큼 모델을 추가할 수 있어요:litellm_config.yaml

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: gemini-flash
    litellm_params:
      model: gemini/gemini-3.8-flash
      api_key: os.environ/GEMINI_API_KEYgeneral_settings:
  master_key: sk-you...-key

모든 옵션은 LiteLLM proxy config 문서를 참고하세요.

3단계: proxy 시작

API 키를 환경 변수로(export, .env 파일, 또는 시크릿 관리 방식으로) 사용할 수 있게 한 뒤 proxy를 시작하세요:

litellm --config litellm_config.yaml --port 4000

4단계: OpenClaw 설치

# macOS / Linuxcurl -fsSL https://openclaw.ai/install.sh | bash

Windows

Windows에서는 PowerShell을 사용하세요: iwr -useb https://openclaw.ai/install.ps1 | iex

네이티브 Windows보다는 WSL2를 권장합니다.

5단계: OpenClaw를 LiteLLM에 연결

온보딩 마법사를 실행하세요:

openclaw onboard --install-daemon

프롬프트가 나오면:

• 온보딩 모드로 QuickStart 또는 Manual을 선택하세요.(둘 다 동작하며, Manual은 게이트웨이 설정에 더 많은 옵션을 줍니다)
• 모델/인증 제공자로 LiteLLM을 선택하세요.
• 2단계의 LiteLLM master_key를 입력하고 base URL을 proxy 주소(예: http://localhost:4000)로 설정하세요.
• 기본 모델을 물어보면 Enter model manually를 선택하고 litellm_config.yaml의 모델 이름(예: litellm/gpt-5.6-terra)을 입력하세요.

온보딩 후에도 모델을 설정하거나 변경할 수 있어요:

openclaw models set litellm/gpt-5.6-terra

스크립트/CI 환경에서는 프롬프트를 완전히 건너뛸 수 있어요:

openclaw onboard --non-interactive --accept-risk \
  --auth-choice litellm-api-key \
  --litellm-api-key "sk-you...-key" \
  --custom-base-url "http://localhost:4000" \
  --install-daemon --skip-channels --skip-skills

6단계: 검증

게이트웨이가 정상인지 확인하세요:

openclaw health

그다음 테스트 메시지를 보내 보세요:

openclaw dashboard                                           # web UIopenclaw tui                                                 # terminal UIopenclaw agent --agent main -m "Hello, what model are you?"  # one-shot CLI

모델에서 응답을 받으면 통합이 동작하는 것입니다.

활성 모델을 확인하세요:

openclaw models status

설정 참조

온보딩 후 OpenClaw는 LiteLLM 제공자 설정을 ~/.openclaw/openclaw.json에 저장합니다. 관련 섹션은 대략 다음과 같아요:

~/.openclaw/openclaw.json (excerpt)

{
  "models": {
    "providers": {
      "litellm": {
        "baseUrl": "http://localhost:4000",
        "apiKey": "sk-you...-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5.6-terra",
            "name": "GPT-5.6 Terra via LiteLLM"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "litellm/gpt-5.6-terra" }
    }
  }
}

이 파일을 직접 편집해 모델을 더 추가하거나 baseUrl을 바꿀 수 있어요. OpenClaw는 변경 사항을 자동으로 hot-reload 합니다.

트러블슈팅

Connection refused / proxy not reachable

LiteLLM proxy가 실행 중이고 OpenClaw 설정의 baseUrl이 일치하는지 확인하세요:

curl http://localhost:4000/health -H "Authorization: Bearer ***"

Wrong model or "Invalid model name"

OpenClaw의 모델 이름은 litellm_config.yaml의 model_name과 일치해야 해요. 활성 모델을 다음으로 전환하세요:

openclaw models set litellm/gpt-5.6-terra

재설치 후 게이트웨이 페어링 문제

재설치 후 CLI가 게이트웨이에 연결할 수 없으면 서비스를 중지하고 다시 설치하세요:

openclaw gateway stopopenclaw gateway install

참조

• OpenClaw docs
• OpenClaw LiteLLM provider docs
• OpenClaw model providers
• LiteLLM proxy configuration

더 알아보기 (Learn more)

• LiteLLM proxy configuration