MoltBot API 프록시 설정: Claude Opus 등 여러 대규모 언어 모델 연동 3단계 전체 가이드

MoltBot에서 Claude Opus 4.5나 다른 대규모 언어 모델을 사용하고 싶은데 API 프록시 설정 방법을 모르시나요? 이 글에서는 MoltBot 다중 프로바이더(Provider) 설정을 단계별로 안내해 드립니다. 여러분의 AI 어시스턴트가 여러 모델 서비스에 동시에 연결되어 스마트하게 전환하고 장애에 대비할 수 있도록 도와드릴게요.

핵심 가치: 이 글을 읽고 나면 MoltBot의 models.providers 설정 방법을 마스터하고, 주 모델, 예비 모델, 모델 에일리어스(Alias)를 설정하여 안정적이고 신뢰할 수 있는 AI 어시스턴트를 만드는 법을 배우게 됩니다.

MoltBot API 프록시 설정: 핵심 개념 분석

MoltBot은 OpenAI 호환 API를 통해 거의 모든 주요 대규모 언어 모델 서비스를 지원합니다. 설정을 성공적으로 마치기 위해서는 다음 핵심 개념을 이해하는 것이 중요해요.

MoltBot 설정 파일 체계

MoltBot 프로바이더(Provider) 설정 핵심 필드

각 프로바이더 설정에는 다음과 같은 주요 필드가 포함됩니다.

API 프로토콜 유형 설명

MoltBot은 두 가지 주요 OpenAI 호환 프로토콜을 지원합니다.

🎯 설정 팁: (APIYI apiyi.com 같은) 대부분의 API 프록시 서비스는 openai-completions 프로토콜을 사용합니다. 만약 LM Studio나 Ollama처럼 로컬에 배포된 모델을 사용한다면 openai-responses를 선택해야 해요.

MoltBot 멀티 프로바이더(Provider) 설정: 전체 예시

다음은 APIYI와 Qwen Portal 두 서비스를 동시에 연동하는 실제 사용 가능한 멀티 프로바이더 설정 예시입니다.

전체 설정 파일 예시

{
  "models": {
    "providers": {
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "${QWEN_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "coder-model", "name": "Qwen Coder", "contextWindow": 128000 },
          { "id": "vision-model", "name": "Qwen Vision", "contextWindow": 128000 }
        ]
      },
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "claude-opus-4-5-20251101", "name": "Claude Opus 4.5", "contextWindow": 200000 },
          { "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4", "contextWindow": 200000 },
          { "id": "gpt-4o", "name": "GPT-4o", "contextWindow": 128000 }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "apiyi/claude-opus-4-5-20251101",
        "fallbacks": ["qwen-portal/vision-model"]
      },
      "models": {
        "apiyi/claude-opus-4-5-20251101": { "alias": "opus" },
        "apiyi/claude-sonnet-4-20250514": { "alias": "sonnet" },
        "qwen-portal/coder-model": { "alias": "qwen" }
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

설정 구조 상세 설명

1. models.providers 섹션

API 프록시 서비스를 정의하는 핵심 부분입니다.

"providers": {
  "apiyi": {
    "baseUrl": "https://api.apiyi.com/v1",
    "apiKey": "${APIYI_API_KEY}",
    "api": "openai-completions",
    "models": [...]
  }
}

• 프로바이더 ID (apiyi): 사용자 정의 서비스 식별자로, 나중에 참조할 때 사용합니다.
• baseUrl: API 엔드포인트이며, 반드시 /v1로 끝나야 합니다.
• apiKey: API 키를 직접 입력하거나 ${ENV_VAR} 형식의 환경 변수를 사용할 수 있습니다.
• models: 해당 프로바이더가 지원하는 모델 목록입니다.

2. agents.defaults.model 섹션

기본으로 사용할 모델과 장애 복구(Failover) 전략을 정의합니다.

"model": {
  "primary": "apiyi/claude-opus-4-5-20251101",
  "fallbacks": ["qwen-portal/vision-model"]
}

• primary: 주 모델이며, 형식은 provider-id/model-id입니다.
• fallbacks: 보조 모델 배열로, 주 모델 호출에 실패하면 자동으로 전환됩니다.

3. agents.defaults.models 섹션

모델 별칭(Alias)을 정의하여 모델을 더 편리하게 전환할 수 있습니다.

"models": {
  "apiyi/claude-opus-4-5-20251101": { "alias": "opus" },
  "qwen-portal/coder-model": { "alias": "qwen" }
}

별칭을 설정해두면 대화 중에 /model opus와 같은 명령어로 모델을 빠르게 바꿀 수 있어 매우 편리해요.

MoltBot API 프록시 설정: 단계별 튜토리얼

1단계: API 키 가져오기

설정을 시작하기 전에 먼저 API 키를 준비해야 해요.

🚀 빠른 시작: 주요 Provider로 APIYI(apiyi.com)를 사용하는 것을 추천해요. 하나의 API 키로 Claude, GPT, Gemini 등 대부분의 주요 모델을 호출할 수 있어 여러 플랫폼에 일일이 가입할 필요가 없답니다.

2단계: 환경 변수 설정하기

보안을 위해 API 키는 환경 변수에 저장하는 것이 좋아요.

# Linux/macOS - ~/.bashrc 또는 ~/.zshrc에 추가
export APIYI_API_KEY="sk-your-apiyi-key"
export QWEN_API_KEY="your-qwen-key"
export TELEGRAM_BOT_TOKEN="your-telegram-token"

# 설정 적용
source ~/.bashrc

# Windows PowerShell
$env:APIYI_API_KEY = "sk-your-apiyi-key"
$env:QWEN_API_KEY = "your-qwen-key"
$env:TELEGRAM_BOT_TOKEN = "your-telegram-token"

3단계: 설정 파일 편집하기

MoltBot 설정 파일을 열거나 새로 생성해 주세요.

# 설정 파일 열기
nano ~/.moltbot/moltbot.json

# 또는 VS Code 사용
code ~/.moltbot/moltbot.json

파일에 다음 내용을 붙여넣으세요.

{
  "models": {
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-5-20251101",
            "name": "Claude Opus 4.5",
            "contextWindow": 200000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "apiyi/claude-opus-4-5-20251101"
      }
    }
  }
}

4단계: 설정 확인하기

MoltBot을 재시작하고 설정이 잘 적용되었는지 확인해 보세요.

# MoltBot 재시작
moltbot restart

# 현재 모델 설정 확인
moltbot models list

# 모델 호출 테스트
moltbot chat "안녕하세요, 당신은 어떤 모델인가요?"

{
  "models": {
    "mode": "merge",
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-5-20251101",
            "name": "Claude Opus 4.5",
            "contextWindow": 200000,
            "maxTokens": 32000
          },
          {
            "id": "claude-sonnet-4-20250514",
            "name": "Claude Sonnet 4",
            "contextWindow": 200000,
            "maxTokens": 64000
          },
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "contextWindow": 128000,
            "maxTokens": 16384
          },
          {
            "id": "gemini-2.5-pro",
            "name": "Gemini 2.5 Pro",
            "contextWindow": 1000000,
            "maxTokens": 65536
          }
        ]
      },
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "${QWEN_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "coder-model",
            "name": "Qwen Coder",
            "contextWindow": 128000
          },
          {
            "id": "vision-model",
            "name": "Qwen Vision",
            "contextWindow": 128000
          }
        ]
      },
      "local-ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-responses",
        "models": [
          {
            "id": "llama3.3:70b",
            "name": "Llama 3.3 70B",
            "contextWindow": 128000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "apiyi/claude-opus-4-5-20251101",
        "fallbacks": [
          "apiyi/claude-sonnet-4-20250514",
          "qwen-portal/vision-model",
          "local-ollama/llama3.3:70b"
        ]
      },
      "models": {
        "apiyi/claude-opus-4-5-20251101": {
          "alias": "opus",
          "params": { "temperature": 0.7 }
        },
        "apiyi/claude-sonnet-4-20250514": {
          "alias": "sonnet",
          "params": { "temperature": 0.5 }
        },
        "apiyi/gpt-4o": {
          "alias": "gpt"
        },
        "qwen-portal/coder-model": {
          "alias": "qwen"
        },
        "local-ollama/llama3.3:70b": {
          "alias": "llama"
        }
      },
      "imageModel": "apiyi/gpt-4o"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}"
    },
    "discord": {
      "enabled": false,
      "token": "${DISCORD_BOT_TOKEN}"
    }
  }
}

💡 설정 팁: "mode": "merge"를 사용하면 MoltBot의 내장 모델 설정을 유지하면서 커스텀 Provider를 추가할 수 있어요. 이렇게 하면 커스텀 서비스가 작동하지 않을 때도 기본 설정으로 원활하게 돌아갈 수 있답니다.

MoltBot 모델 설정: 고급 파라미터 상세 설명

모델 항목 전체 필드

모델 파라미터 설정 (params)

agents.defaults.models에서 각 모델별 기본 파라미터를 설정할 수 있어요.

"models": {
  "apiyi/claude-opus-4-5-20251101": {
    "alias": "opus",
    "params": {
      "temperature": 0.7,
      "maxTokens": 16000
    }
  }
}

⚠️ 주의: temperature는 고급 파라미터예요. 모델의 기본 설정을 잘 알고 있고 특별히 조정이 필요한 경우가 아니라면 설정을 생략하는 것을 권장해요.

MoltBot Fallback 설정

Fallback 메커니즘은 MoltBot의 중요한 기능으로, AI 어시스턴트가 항상 사용 가능한 상태를 유지하도록 보장합니다.

Fallback 작동 원리

사용자 요청
    ↓
기본 모델 (primary)
    ↓ (실패 시)
예비 모델 1 (fallbacks[0])
    ↓ (실패 시)
예비 모델 2 (fallbacks[1])
    ↓ (실패 시)
...계속 시도

권장하는 Fallback 설정 전략

권장 설정:

"model": {
  "primary": "apiyi/claude-opus-4-5-20251101",
  "fallbacks": [
    "apiyi/claude-sonnet-4-20250514",
    "apiyi/gpt-4o",
    "qwen-portal/vision-model"
  ]
}

💰 비용 최적화: APIYI(apiyi.com)를 통해 Fallback을 설정하면 여러 모델 간에 자동으로 전환할 수 있을 뿐만 아니라, 통합된 결제 방식을 통해 비용 관리가 훨씬 수월해집니다.

MoltBot 모델 전환: 실전 팁

별칭(Alias)을 사용한 빠른 전환

별칭을 설정해두면 대화 중에 언제든지 모델을 바꿀 수 있어요:

나: /model opus
MoltBot: Claude Opus 4.5로 전환되었습니다.

나: /model sonnet
MoltBot: Claude Sonnet 4로 전환되었습니다.

나: /model qwen
MoltBot: Qwen Coder로 전환되었습니다.

특정 작업에 모델 지정하기

나: /model gpt 이 이미지를 분석해 줘
MoltBot: [GPT-4o를 사용하여 이미지 분석 중...]

나: /model opus 심도 있는 기술 아티클을 써 줘
MoltBot: [Claude Opus를 사용하여 글쓰기 중...]

현재 모델 상태 확인하기

# 명령행(CLI)에서 확인
moltbot models list

# 대화 중에 확인
나: /model
MoltBot: 현재 모델: apiyi/claude-opus-4-5-20251101 (alias: opus)

MoltBot API 프록시 설정: 자주 묻는 질문(FAQ)

{
  "models": {
    "mode": "merge",
    "providers": {
      "local-ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-responses",
        "models": [...]
      },
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [...]
      }
    }
  }
}

"agents": {
  "defaults": {
    "model": {
      "primary": "apiyi/claude-opus-4-5-20251101"
    },
    "imageModel": "apiyi/gpt-4o",
    "models": {
      "apiyi/claude-opus-4-5-20251101": { "alias": "opus" },
      "apiyi/gpt-4o": { "alias": "vision" }
    }
  }
}