# Cara mengatur OpenClaw dengan OmniaKey: Provider dan allowlist model

> Tambahkan OmniaKey sebagai Provider OpenAI-compatible di OpenClaw. Atur openclaw.json, allowlist model, doctor, dan error model not allowed.

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

---

Diperbarui 30 Oktober 2026: empat kesalahan penyiapan OpenClaw dengan OmniaKey yang umum ada di bawah, masing-masing dengan gejala, penyebab, dan perbaikan dari dokumentasi OpenClaw.

Jika Anda mencari **cara mengatur OpenClaw API**, bedakan dua langkah: mendefinisikan Provider dan mengizinkan model. OpenClaw menyediakan agent loop dan tools; Provider menyediakan model yang memberi jawaban.

## Tambahkan OmniaKey sebagai Provider

Konfigurasi berada di `~/.openclaw/openclaw.json`. Tambahkan OmniaKey di bawah `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` menambahkan Provider tanpa mengganti konfigurasi yang ada. Gunakan key asli, tetapi jangan commit atau membagikannya. Satu Provider yang kompatibel dengan OpenAI mencakup empat keluarga model: OmniaKey mencari model lewat ID, jadi `claude-opus-4-8`, `gpt-5.5`, `gemini-3.1-pro-preview`, dan `grok-4.5` berjalan melalui entri yang sama.

## Langkah yang sering terlupakan: allowlist model

Definisi Provider saja belum cukup. OpenClaw juga mengharuskan model ada di allowlist. Di file yang sama, tambahkan `agents` sejajar dengan `models`:

```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"
    }
  }
}
```

Request body memakai model ID; `provider/model-id` adalah referensi internal OpenClaw. Keduanya wajib. Tanpa allowlist, Anda bisa mendapat `model not allowed` meski key benar.

## Verifikasi

```bash
openclaw doctor
```

`doctor` memeriksa file konfigurasi OpenClaw untuk OmniaKey, Provider, format key, koneksi langsung, dan akses model. Setelah itu Anda dapat memilih `omniakey/gpt-5.5` di `agents.defaults`.

> Jangan mengedit `~/.openclaw/agents/main/agent/models.json` secara manual; file tersebut dibuat ulang dari `openclaw.json`.

## Kesalahan penyiapan yang umum

- `Model override "provider/model" is not allowed by agents.defaults.modelPolicy.allow.` Ref yang Anda pilih tidak ada di daftar `agents.defaults.modelPolicy.allow` yang tidak kosong, dan daftar itulah yang diperiksa OpenClaw untuk `/model`, penggantian di dalam sesi, dan `--model`. Tambahkan ref persisnya atau wildcard Provider seperti `omniakey/*`, kosongkan daftarnya, atau pilih model dari `/model list` ([FAQ model OpenClaw](https://docs.openclaw.ai/help/faq-models#why-do-i-see-model-is-not-allowed-and-then-no-reply)).

- `model_not_found` atau 404, padahal panggilan langsung dengan model ID yang sama berhasil. Entri khusus hanya bisa diresolusikan bila `baseUrl` berakhir dengan `/v1`, `api` bernilai `"openai-completions"`, dan katalog menyimpan ID tanpa awalan sementara Anda memilihnya dengan awalan Provider. Periksa ketiganya, pilih model sekali dengan awalan Provider, lalu jalankan ulang prompt yang sama ([pemecahan masalah backend lokal](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers#local-openai-compatible-backend-passes-direct-checks-but-agent-runs-fail)).

- 403 polos dengan "Your request was blocked" di isi respons. Teks ini biasanya berasal dari lapisan keamanan di depan endpoint — CDN, WAF, aturan bot, atau reverse proxy — bukan dari `openclaw.json`, dan `openclaw logs --follow` menunjukkan apakah beberapa model di Provider yang sama gagal dengan cara yang sama. Perbaiki sisi Provider dulu dengan aturan izin yang hanya mencakup jalur yang dipanggil OpenClaw, dan biarkan perlindungan tetap aktif untuk bagian situs lainnya ([pemecahan masalah 403 di upstream](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers#upstream-403-blocked-responses)).

- `messages[...].content: invalid type: sequence, expected a string` pada setiap eksekusi agent. Backend menolak bagian content terstruktur gaya OpenAI. Setel `compat.requiresStringContent: true` pada entri model itu dan jalankan ulang prompt yang sama.

## Mengapa menggunakan OmniaKey

Satu key dan satu saldo untuk Claude, GPT, Gemini, dan Grok, dengan biaya per token. Model ID yang diizinkan adalah model yang dijalankan, tanpa penggantian diam-diam. [Katalog model](https://omniakey.com/id/models) mencantumkan semua id yang bisa Anda izinkan, dan [harga](https://omniakey.com/id/pricing) menunjukkan tarif per token.

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

[Panduan coding agent](https://docs.omniakey.com/id/coding) mencakup alat lainnya. Untuk penyiapan langkah demi langkah, lihat panduan [Penyiapan Hermes Agent](https://omniakey.com/id/blog/hermes-setup), [API key kustom di Cline](https://omniakey.com/id/blog/cline-custom-api-key), dan [Penyiapan Claude Code](https://omniakey.com/id/blog/claude-code-setup).

## Pertanyaan yang sering diajukan

### Di mana blok Provider OmniaKey diletakkan?

Di `~/.openclaw/openclaw.json`, di bawah `models.providers`. Pertahankan `"mode": "merge"` agar blok itu ditambahkan ke Provider yang sudah ada, bukan menggantikannya.

### Mengapa OpenClaw bilang sebuah model tidak diizinkan?

Provider sudah didefinisikan, tetapi ref modelnya tidak ada di allowlist OpenClaw, jadi eksekusi gagal meski key benar. Tambahkan ref lengkap `omniakey/model-id`, lalu jalankan `openclaw doctor`.

### Bisakah satu key OmniaKey menjalankan Claude, GPT, Gemini, dan Grok di OpenClaw?

Bisa. Satu entri Provider dengan `api: "openai-completions"` menjangkau keempat keluarga, dan model ID di request yang menentukan mana yang berjalan.

### Bagaimana memeriksa koneksi OpenClaw ke OmniaKey?

`openclaw doctor` memeriksa file konfigurasi, Provider, format key, koneksi langsung, dan akses model. Setelah itu `openclaw models list` menampilkan model OmniaKey yang Anda izinkan.

### Apakah saya perlu mengedit \~/.openclaw/agents/main/agent/models.json?

Tidak. File itu dibuat ulang dari `openclaw.json`, jadi ubah Provider dan allowlist di `openclaw.json`.

## Sumber yang diperiksa

- [OpenClaw: FAQ model dan autentikasi](https://docs.openclaw.ai/help/faq-models)
- [OpenClaw: Skills dan Provider model](https://docs.openclaw.ai/gateway/troubleshooting/skills-and-model-providers)