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

> OpenClaw에 OmniaKey를 OpenAI 호환 Provider로 연결하는 방법을 안내합니다. openclaw.json, 모델 allowlist, doctor 확인과 자주 발생하는 설정 오류를 설명합니다.

- Canonical HTML: https://omniakey.com/ko/blog/openclaw-setup
- Markdown: https://omniakey.com/ko/blog/openclaw-setup.md
- Published: 2026-05-19 (updated 2026-10-30)
- Author: Kiki, COO at OmniaKey
- Language: ko
- Category: Guide
- Reading time: 5 min
- All posts: https://omniakey.com/blog/llms.txt

---

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

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

## OmniaKey를 Provider로 추가하기

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

```json
{
  "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`를 추가합니다.

```json
{
  "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`가 발생합니다.

## 확인하기

```bash
openclaw doctor
```

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

> `~/.openclaw/agents/main/agent/models.json`은 직접 편집하지 마세요. `openclaw.json`에서 다시 생성됩니다. JSON 오류가 나면 괄호와 쉼표부터 확인하세요.

## 자주 나는 설정 오류

- `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](https://docs.openclaw.ai/help/faq-models#why-do-i-see-model-is-not-allowed-and-then-no-reply)).

- 같은 model ID를 직접 호출하면 되는데 `model_not_found`나 404가 납니다. 사용자 정의 항목은 `baseUrl`이 `/v1`로 끝나고, `api`가 `"openai-completions"`이고, 카탈로그에는 접두사 없는 ID를 그대로 두고 선택할 때만 Provider 접두사를 붙이는 세 가지가 맞을 때만 해석됩니다. 세 가지를 확인하고 Provider 접두사를 붙여 한 번 선택한 뒤 같은 프롬프트를 다시 실행하세요([로컬 백엔드 문제 해결](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers#local-openai-compatible-backend-passes-direct-checks-but-agent-runs-fail)).

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

- 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는 [모델 목록](https://omniakey.com/ko/models)에, 토큰 단가는 [가격 페이지](https://omniakey.com/ko/pricing)에 있습니다.

- **OpenAI-compatible**: <https://api.omniakey.com/v1>
- **Anthropic-native**: <https://api.omniakey.com>
- **Gemini-native**: <https://api.omniakey.com/v1beta>

도구별 설정은 [코딩 Agent 안내](https://docs.omniakey.com/ko/coding)에서 확인하세요. 단계별 설정 방법은 [Hermes Agent 설정](https://omniakey.com/ko/blog/hermes-setup), [Cline 커스텀 API 키 설정](https://omniakey.com/ko/blog/cline-custom-api-key), [Claude Code 설정](https://omniakey.com/ko/blog/claude-code-setup) 가이드에서 확인할 수 있습니다.

## 자주 묻는 질문

### 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](https://docs.openclaw.ai/help/faq-models)
- [OpenClaw: Skills와 모델 Provider](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers)