OpenClaw에 OmniaKey 설정하기: API Provider와 allowlist

OpenClaw API 설정을 찾고 있다면 Provider 정의와 모델 allowlist가 서로 다른 설정이라는 점부터 확인하세요. OpenClaw는 Agent loop, 도구 호출, 코드 편집을 제공하고 실제 응답은 연결한 모델 Provider가 만듭니다.

OmniaKey를 Provider로 추가하기

설정 파일은 ~/.openclaw/openclaw.json입니다. models.providers 아래에 다음 항목을 추가합니다.

{
  "models": {
    "mode": "merge",
    "providers": {
      "omniakey": {
        "baseUrl": "https://api.omniakey.com/v1",
        "apiKey": "your-omniakey-api-key",
        "api": "openai-completions",
        "models": [
          { "id": "claude-opus-4-8" },
          { "id": "gpt-5.5" },
          { "id": "gemini-3.1-pro-preview" },
          { "id": "grok-4.5" }
        ]
      }
    }
  }
}

mode: merge는 기존 설정을 유지하면서 Provider를 추가합니다. 실제 API key를 입력하되 Git, 스크린샷, 공개 채팅에 넣지 마세요. 모델 ID는 현재 카탈로그에서 복사합니다.

자주 빠뜨리는 단계: 모델 allowlist

Provider만 정의하면 끝이 아닙니다. OpenClaw는 allowlist에 있는 모델만 사용할 수 있습니다. 같은 openclaw.json에서 models와 같은 최상위 레벨에 agents를 추가합니다.

{
  "agents": {
    "defaults": {
      "models": [
        "omniakey/claude-opus-4-8",
        "omniakey/gpt-5.5",
        "omniakey/gemini-3.1-pro-preview",
        "omniakey/grok-4.5"
      ],
      "model": "omniakey/claude-opus-4-8"
    }
  }
}

요청 본문에는 모델 ID가 들어가지만 provider/model-id는 OpenClaw 내부 참조입니다. Provider 정의와 allowlist 항목이 모두 필요합니다. 하나만 빠지면 key가 올바르더라도 model not allowed가 발생합니다.

확인하기

openclaw doctor
openclaw models list

doctor는 설정 파일, Provider, key 형식, 실시간 연결과 모델 접근을 확인합니다. 이후 agents.defaults에서 omniakey/gpt-5.5처럼 활성 모델을 선택할 수 있습니다.

OmniaKey를 사용하는 이유

Claude, GPT, Gemini, Grok을 하나의 key와 잔액으로 전환하고 토큰 단위로 사용량을 관리할 수 있습니다. allowlist에 지정한 model ID가 실행되며, upstream 장애 때 다른 모델로 자동 교체되지 않습니다.

도구별 설정은 코딩 Agent 안내에서 확인하세요.