OpenClaw에서 Claude에 연결하는 2가지 설정 방식: OpenAI 호환 모드 vs Claude 네이티브 형식 완전 가이드

작성자 주: OpenClaw에서 OpenAI 호환 모드와 Claude 네이티브 포맷 두 가지 접근 방식을 구성하는 방법을 단계별로 설명합니다. 완전한 JSON 구성 코드, 지원 모델 목록 및 주요 차이점 비교를 포함합니다.

OpenClaw(Open WebUI)에서 대규모 언어 모델을 연결하는 방법은 두 가지가 있습니다: OpenAI 호환 모드(openai-completions)와 Claude 네이티브 포맷(anthropic-messages). 많은 사용자들이 두 가지의 차이점을 잘 모르기 때문에 Claude 모델에 잘못된 포맷을 사용하거나, 네이티브 포맷이 제공하는 Prompt Caching 같은 고급 기능을 놓치는 경우가 많습니다.

핵심 가치: 이 글을 읽고 나면 OpenClaw에서 두 가지 접근 방식을 완전히 구성하는 방법을 익히고, 어떤 모델에 어떤 포맷을 사용해야 하는지 명확히 알게 되며, 구성 코드를 바로 복사해서 사용할 수 있게 됩니다.

OpenClaw 두 가지 접근 방식 핵심 비교

OpenClaw 두 가지 접근 방식 한 줄 요약

간단한 규칙 하나만 기억하세요: Claude 시리즈 모델은 anthropic-messages를 사용하고, 다른 모든 모델은 openai-completions를 사용합니다. 두 가지의 가장 직관적인 차이는 baseUrl입니다—OpenAI 호환 모드는 끝에 /v1이 붙고, Claude 네이티브 포맷은 붙지 않습니다.

OpenAI 호환 모드 구성 튜토리얼

OpenAI 호환 모드 사용 시나리오

OpenAI 호환 모드(openai-completions)는 OpenClaw에서 가장 범용적인 접속 방식으로, Claude가 아닌 모든 대규모 언어 모델에 적용됩니다. 대부분의 API 중계 서비스는 이 표준화된 OpenAI 형식을 사용합니다.

OpenAI 호환 모드 전체 구성 코드

다음은 APIYI를 통해 GPT-5.4에 접속하는 전체 구성입니다:

{
  "agents": {
    "defaults": {
      "model": { "primary": "apiyi/gpt-5.4" }
    }
  },
  "models": {
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "sk-당신의API키",
        "api": "openai-completions",
        "models": [
          { "id": "gpt-5.4", "name": "GPT-5.4" }
        ]
      }
    }
  }
}

{
  "models": {
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "sk-당신의API키",
        "api": "openai-completions",
        "models": [
          { "id": "gpt-5.4", "name": "GPT-5.4" },
          { "id": "gemini-3-flash-preview", "name": "Gemini 3 Flash" },
          { "id": "deepseek-v3.2", "name": "DeepSeek V3.2" },
          { "id": "glm-5", "name": "GLM-5" },
          { "id": "kimi-k2.5", "name": "Kimi K2.5" },
          { "id": "grok-4", "name": "Grok 4" },
          { "id": "Minimax-M2.5", "name": "Minimax M2.5" }
        ]
      }
    }
  }
}

OpenAI 호환 모드 구성 요점

🎯 구성 팁: baseUrl 끝의 /v1은 생략할 수 없습니다. 이는 OpenAI 호환 프로토콜의 표준 경로입니다. APIYI apiyi.com을 방문하여 등록하면 API 키와 무료 크레딧을 받을 수 있습니다.

OpenClaw Claude 네이티브 형식 구성 튜토리얼

Claude 네이티브 형식 사용 시나리오

Claude 네이티브 형식(anthropic-messages)은 Claude 시리즈 모델의 전용 접속 방식입니다. 네이티브 형식을 사용하면 Prompt Caching, Extended Thinking, PDF 처리 등 Claude만의 고급 기능을 이용할 수 있습니다.

Claude 네이티브 형식 전체 구성 코드

다음은 APIYI를 통해 Claude 모델에 접속하는 전체 구성입니다:

{
  "models": {
    "providers": {
      "apiyi-claude": {
        "baseUrl": "https://api.apiyi.com",
        "apiKey": "sk-당신의API키",
        "api": "anthropic-messages",
        "headers": {
          "anthropic-version": "2023-06-01",
          "anthropic-beta": ""
        },
        "models": [
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.6",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          },
          {
            "id": "claude-sonnet-4-6-thinking",
            "name": "Claude Sonnet 4.6 Thinking",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          }
        ]
      }
    }
  }
}

{
  "models": {
    "providers": {
      "apiyi-claude": {
        "baseUrl": "https://api.apiyi.com",
        "apiKey": "sk-당신의API키",
        "api": "anthropic-messages",
        "headers": {
          "anthropic-version": "2023-06-01",
          "anthropic-beta": ""
        },
        "models": [
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.6",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          },
          {
            "id": "claude-sonnet-4-6-thinking",
            "name": "Claude Sonnet 4.6 Thinking",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          },
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          },
          {
            "id": "claude-haiku-4-5-20251001",
            "name": "Claude Haiku 4.5",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

Claude 네이티브 형식 구성 요점

🎯 핵심 차이점: Claude 네이티브 형식의 baseUrl은 /v1을 포함하지 않습니다. 이는 초보자가 가장 흔히 저지르는 실수입니다. Claude 접속 시 오류가 발생하면 먼저 URL 끝에 /v1을 잘못 추가했는지 확인하세요.

OpenClaw 두 형식 동시 사용 설정

실제 사용 중에는 범용 모델과 Claude 모델을 동시에 사용해야 할 가능성이 높습니다. 이때 OpenClaw에서 두 개의 provider를 설정해야 합니다:

이중 Provider 병합 설정 코드

두 형식의 provider를 동일한 설정 파일에 작성하면 OpenClaw에서 모델을 자유롭게 전환할 수 있습니다:

{
  "agents": {
    "defaults": {
      "model": { "primary": "apiyi/gpt-5.4" }
    }
  },
  "models": {
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "sk-당신의API키",
        "api": "openai-completions",
        "models": [
          { "id": "gpt-5.4", "name": "GPT-5.4" },
          { "id": "deepseek-v3.2", "name": "DeepSeek V3.2" },
          { "id": "gemini-3-flash-preview", "name": "Gemini 3 Flash" },
          { "id": "glm-5", "name": "GLM-5" },
          { "id": "kimi-k2.5", "name": "Kimi K2.5" },
          { "id": "grok-4", "name": "Grok 4" },
          { "id": "Minimax-M2.5", "name": "Minimax M2.5" }
        ]
      },
      "apiyi-claude": {
        "baseUrl": "https://api.apiyi.com",
        "apiKey": "sk-당신의API키",
        "api": "anthropic-messages",
        "headers": {
          "anthropic-version": "2023-06-01",
          "anthropic-beta": ""
        },
        "models": [
          {
            "id": "claude-sonnet-4-6",
            "name": "Claude Sonnet 4.6",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          },
          {
            "id": "claude-sonnet-4-6-thinking",
            "name": "Claude Sonnet 4.6 Thinking",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          },
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          }
        ]
      }
    }
  }
}

🎯 중요 설명: 두 provider는 동일한 API 키를 사용할 수 있습니다. APIYI apiyi.com의 동일한 키는 OpenAI 호환 형식과 Claude 네이티브 형식을 동시에 지원하므로 여러 개의 키를 신청할 필요가 없습니다.

OpenClaw 두 형식 일반적인 오류 해결

설정 과정에서 가장 쉽게 실수하는 부분은 baseUrl과 api 유형이 일치하지 않는 경우입니다. 다음은 일반적인 오류 및 해결 방법입니다:

🎯 빠른 문제 해결 구문: OpenAI 형식은 /v1을 포함하고, Claude 형식은 /v1을 포함하지 않습니다. 이 점만 기억하면 설정 오류의 80%를 피할 수 있습니다. 다른 문제가 발생하면 APIYI apiyi.com의 문서 센터를 방문하여 전체 접속 가이드를 확인하세요.

자주 묻는 질문

요약

OpenClaw의 두 가지 연결 방식 핵심 요점:

1. 일반 모델은 openai-completions 사용: GPT, Gemini, DeepSeek, GLM, Kimi, Grok, Minimax 등 Claude가 아닌 모든 모델. baseUrl은 /v1을 포함합니다.
2. Claude 시리즈는 anthropic-messages 사용: claude-sonnet-4-6, claude-opus-4-6, claude-haiku 등. baseUrl은 /v1을 포함하지 않으며, anthropic-version 헤더가 필요합니다.
3. 두 개의 Provider를 함께 사용하는 것이 최선의 방법: 동일한 API 키로 두 개의 provider를 구성하여 OpenClaw에서 모든 모델을 자유롭게 전환할 수 있습니다.

APIYI(apiyi.com)를 통해 API 키를 획득하는 것을 추천합니다. 하나의 키로 GPT, Claude, Gemini, DeepSeek 등 모든 주요 모델에 접속할 수 있으며, OpenAI 호환 및 Claude 네이티브 두 가지 형식을 모두 지원합니다.

📚 참고 자료

1. APIYI 도움말 센터: OpenClaw 연동 설정 완전 가이드

   • 링크: help.apiyi.com
   • 설명: 각 사이트별 상세 연동 문서와 최신 모델 목록 포함

2. Anthropic API 문서: Claude 네이티브 API 형식 규격

   • 링크: platform.claude.com/docs/en/api/messages
   • 설명: Messages API의 전체 매개변수와 응답 형식

3. OpenAI SDK 호환성 문서: Claude에서 무시되는 매개변수

   • 링크: platform.claude.com/docs/en/api/openai-sdk
   • 설명: 지원 및 미지원 매개변수 전체 목록

4. Open WebUI 문서: OpenClaw 다중 Provider 설정 가이드

   • 링크: docs.openwebui.com
   • 설명: Provider 설정, 모델 관리 및 Agent 설정

작성자: APIYI 기술팀
기술 교류: 댓글로 토론을 환영합니다. 더 많은 자료는 APIYI docs.apiyi.com 문서 센터에서 확인하실 수 있습니다.