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

2026년 10월 30일 업데이트: 자주 나는 설정 오류 네 가지를 아래에 정리했고, 각각 증상·원인·OpenClaw 공식 문서의 해결 방법을 담았습니다.

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, 스크린샷, 공개 채팅에 넣지 마세요. OpenAI 호환 Provider 하나로 네 모델 패밀리를 모두 쓸 수 있습니다. OmniaKey는 model ID로 모델을 찾으므로 claude-opus-4-8, gpt-5.5, gemini-3.1-pro-preview, grok-4.5가 모두 같은 항목으로 실행됩니다.

자주 빠뜨리는 단계: 모델 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

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

자주 나는 설정 오류

• Model override "provider/model" is not allowed by agents.defaults.modelPolicy.allow. 고른 ref가 비어 있지 않은 agents.defaults.modelPolicy.allow 목록에 없습니다. OpenClaw는 이 목록으로 /model, 세션 단위 재정의, --model을 검사합니다. 정확한 ref나 omniakey/* 같은 Provider 와일드카드를 목록에 넣거나, 목록을 비우거나, /model list에 있는 모델을 고르세요(OpenClaw 모델 FAQ).

• 같은 model ID를 직접 호출하면 되는데 model_not_found나 404가 납니다. 사용자 정의 항목은 baseUrl이 /v1로 끝나고, api가 "openai-completions"이고, 카탈로그에는 접두사 없는 ID를 그대로 두고 선택할 때만 Provider 접두사를 붙이는 세 가지가 맞을 때만 해석됩니다. 세 가지를 확인하고 Provider 접두사를 붙여 한 번 선택한 뒤 같은 프롬프트를 다시 실행하세요(로컬 백엔드 문제 해결).

• 응답 본문이 "Your request was blocked" 하나뿐인 403. 이 문구는 보통 엔드포인트 앞단의 보안 계층(CDN, WAF, bot 규칙, 리버스 프록시)에서 오며 openclaw.json 문제가 아닙니다. openclaw logs --follow로 같은 Provider의 여러 모델이 같이 실패하는지 보세요. Provider 쪽을 먼저 고치되, 규칙은 OpenClaw가 호출하는 경로만 덮게 하고 사이트 나머지의 보호는 그대로 두세요(upstream 403 문제 해결).

• agent를 실행할 때마다 messages[...].content: invalid type: sequence, expected a string가 납니다. 백엔드가 OpenAI 방식의 구조화된 content 조각을 거부하는 것입니다. 해당 모델 항목에 compat.requiresStringContent: true를 설정하고 같은 프롬프트를 다시 실행하세요.

OmniaKey를 사용하는 이유

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

도구별 설정은 코딩 Agent 안내에서 확인하세요. 단계별 설정 방법은 Hermes Agent 설정, Cline 커스텀 API 키 설정, Claude Code 설정 가이드에서 확인할 수 있습니다.

자주 묻는 질문

OmniaKey Provider 설정은 어디에 넣나요?

~/.openclaw/openclaw.json의 models.providers 아래에 넣습니다. "mode": "merge"를 두면 기존 Provider를 교체하지 않고 추가됩니다.

OpenClaw가 model not allowed라고 하는 이유는 무엇인가요?

Provider는 정의됐지만 모델 ref가 OpenClaw의 allowlist에 없어서, key가 맞아도 실행이 실패합니다. omniakey/model-id 전체 ref를 추가한 뒤 openclaw doctor를 실행하세요.

OmniaKey key 하나로 Claude, GPT, Gemini, Grok을 모두 쓸 수 있나요?

네. api: "openai-completions" Provider 항목 하나로 네 패밀리에 닿고, 요청의 model ID가 어느 모델을 실행할지 정합니다.

OpenClaw가 OmniaKey에 연결되는지 어떻게 확인하나요?

openclaw doctor가 설정 파일, Provider, key 형식, 실시간 연결, 모델 접근을 확인합니다. 이어서 openclaw models list에 allowlist에 넣은 OmniaKey 모델이 보입니다.

~/.openclaw/agents/main/agent/models.json을 직접 고쳐야 하나요?

아니요. 그 파일은 openclaw.json에서 다시 생성되므로 Provider와 allowlist는 openclaw.json에서 고치세요.

확인한 출처

• OpenClaw: 모델과 인증 FAQ
• OpenClaw: Skills와 모델 Provider