OpenClaw에서 LLM 모델 프로바이더 설정하기

새로운 프로젝트를 시작할 때마다 각기 다른 LLM API를 연동하고 설정을 맞추는 일은 꽤 번거로워요. 모델마다 다른 인증 방식과 엔드포인트를 관리하다 보면 정작 중요한 로직 개발에 집중하기 어려울 때가 많죠. OpenClaw는 이런 불편함을 해결하기 위해 여러 프로바이더를 하나의 체계로 관리할 수 있게 도와줘요.

필요한 것

OpenClaw 설치 환경
각 프로바이더별 API Key (OpenAI, Anthropic, Google 등)
로컬 모델 사용 시 Ollama 설치

빠른 시작

5분 안에 모델 설정을 끝내는 방법이에요.

모델 참조 형식 확인: 모든 모델은 provider/model 형식을 사용해요. (예: opencode/claude-opus-4-6)
CLI 도우미 활용: openclaw onboard 명령어를 실행하면 단계별로 설정을 도와줘요.
모델 리스트 확인: openclaw models list로 사용 가능한 모델을 확인하세요.
기본 모델 설정: openclaw models set <provider/model> 명령어로 사용할 모델을 지정해요.

Built-in 프로바이더 설정

OpenClaw는 pi‑ai 카탈로그를 내장하고 있어서 별도의 models.providers 설정 없이 API Key만 있으면 바로 사용할 수 있어요.

OpenAI & Anthropic

가장 많이 사용하는 프로바이더들이에요. CLI에서 바로 인증을 진행할 수 있어요.

OpenAI: openclaw onboard --auth-choice openai-api-key
Anthropic: openclaw onboard --auth-choice token 또는 openclaw models auth paste-token --provider anthropic

// Anthropic 설정 예시
{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

Google Gemini & Vertex

Google의 모델들은 서비스 유형에 따라 인증 방식이 달라요.

Gemini (API key): openclaw onboard --auth-choice gemini-api-key 환경 변수에 GEMINI_API_KEY를 설정하세요.

Vertex AI & Antigravity: 플러그인을 먼저 활성화해야 해요.

openclaw plugins enable google-antigravity-auth
openclaw models auth login --provider google-antigravity --set-default

커스텀 프로바이더 및 Proxy 설정

models.providers 설정을 통해 OpenAI/Anthropic과 호환되는 커스텀 엔드포인트를 추가할 수 있어요.

Moonshot AI (Kimi)

Moonshot은 OpenAI 호환 엔드포인트를 사용하므로 아래와 같이 설정해요.

{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.5" } },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.5", name: "Kimi K2.5" }],
      },
    },
  },
}

로컬 모델 (Ollama & LM Studio)

로컬에서 실행 중인 모델도 쉽게 연결할 수 있어요. Ollama는 별도 설정 없이도 http://127.0.0.1:11434/v1에서 자동으로 감지돼요.

# Ollama 모델 다운로드 예시
ollama pull llama3.3

LM Studio 같은 로컬 Proxy를 사용할 때는 아래와 같이 상세 설정을 추가하는 것을 추천해요.

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/minimax-m2.1-gs32" },
      models: { "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "LMSTUDIO_KEY",
        api: "openai-completions",
        models: [
          {
            id: "minimax-m2.1-gs32",
            name: "MiniMax M2.1",
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

문제 해결

Google Gemini CLI/Antigravity 로그인 문제: openclaw.json에 직접 Client ID나 Secret을 입력하지 마세요. 반드시 CLI 로그인 흐름을 통해 Gateway 호스트의 인증 프로필에 토큰을 저장해야 해요.
Qwen OAuth 인증: Qwen은 device-code flow를 사용해요. openclaw plugins enable qwen-portal-auth로 플러그인을 켠 뒤 로그인을 진행하세요.
커스텀 모델 파라미터 미적용: reasoning, cost, contextWindow 등을 직접 지정하지 않으면 기본값(contextWindow: 200,000 등)이 적용돼요. 모델의 실제 제한 수치에 맞춰 명시적으로 설정하는 것이 좋아요.

설정 중에 어려움이 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.