Cara mengatur OpenClaw dengan OmniaKey: Provider dan allowlist model

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:

{
  "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:

{
  "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

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.

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).

• 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).

• 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).

• 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 mencantumkan semua id yang bisa Anda izinkan, dan harga menunjukkan tarif per token.

Panduan coding agent mencakup alat lainnya. Untuk penyiapan langkah demi langkah, lihat panduan Penyiapan Hermes Agent, API key kustom di Cline, dan Penyiapan Claude Code.

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
• OpenClaw: Skills dan Provider model