# OpenClaw (/id/docs/guides/openclaw)

Jalankan asisten AI pribadi OpenClaw dengan model cheapaimodel lewat penyedia model kustom.



OpenClaw menambahkan layanan yang kompatibel dengan OpenAI sebagai penyedia kustom di `models.providers` dalam `~/.openclaw/openclaw.json`. Setelah itu, agent merujuk ke model sebagai `cheapaimodel/<model-id>`.

|          | Pengaturan OpenClaw                         | Nilai                                                                                                                  |
| -------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Base URL | `models.providers.cheapaimodel.baseUrl`     | `https://api.cheapaimodel.ai/v1`                                                                                       |
| API key  | `models.providers.cheapaimodel.apiKey`      | `${CHEAPAIMODEL_API_KEY}`, yang berisi key kamu dari halaman [API key](https://console.cheapaimodel.ai/keys) di Konsol |
| ID model | `models.providers.cheapaimodel.models[].id` | `glm-5.3`, atau ID apa pun dari [katalog](/id/models)                                                                  |

## Penyiapan [#set-it-up]

<Steps>
  <Step>
    ### Simpan key [#store-the-key]

    Taruh key di file env global OpenClaw, yang dibaca Gateway bahkan saat berjalan sebagai layanan di latar belakang:

    ```bash title="~/.openclaw/.env"
    CHEAPAIMODEL_API_KEY=sk-...
    ```

    Kalau Gateway sudah berjalan, mulai ulang dengan `openclaw gateway restart` supaya file itu terbaca.
  </Step>

  <Step>
    ### Tambahkan penyedia [#add-the-provider]

    Gabungkan ini ke konfigurasimu:

    ```json5 title="~/.openclaw/openclaw.json"
    {
      agents: {
        defaults: {
          model: { primary: "cheapaimodel/glm-5.3" },
        },
      },
      models: {
        mode: "merge",
        providers: {
          cheapaimodel: {
            baseUrl: "https://api.cheapaimodel.ai/v1",
            apiKey: "${CHEAPAIMODEL_API_KEY}",
            api: "openai-completions",
            models: [
              {
                id: "glm-5.3",
                name: "GLM-5.3",
                compat: { supportsUsageInStreaming: true },
              },
            ],
          },
        },
      },
    }
    ```

    * `api: "openai-completions"` mengirim permintaan ke `/v1/chat/completions`.
    * Tambahkan satu entri di `models` untuk setiap ID model. `id` adalah ID katalog; `name` adalah label, dan OpenClaw mewajibkannya.
    * Tambahkan `contextWindow` dan `maxTokens` ke setiap entri sesuai halaman model, misalnya [halaman glm-5.3](/id/models/glm-5.3). Tanpa keduanya, OpenClaw menghitung jatah konteks dengan nilai cadangannya sendiri dan menyerahkan batas output ke server.
    * `compat.supportsUsageInStreaming` membuat OpenClaw meminta data pemakaian token di streaming, yang memang dikembalikan cheapaimodel (lihat [Streaming](/id/docs/concepts/streaming)). Tanpa opsi ini, OpenClaw memperkirakan pemakaian konteks dan mencatat `returned no token usage` di log.

    Gateway memantau file itu dan menerapkan perubahan tanpa perlu dimulai ulang.
  </Step>

  <Step>
    ### Cek hasilnya [#check-it]

    ```bash title="Terminal"
    openclaw models list
    ```

    `cheapaimodel/glm-5.3` seharusnya muncul di daftar. Untuk mengganti model default nanti, jalankan `openclaw models set cheapaimodel/<model-id>`.
  </Step>
</Steps>

Agent OpenClaw mengandalkan kemampuan tool calling modelnya. Kalau sebuah model kurang bagus menangani tool, coba model lain dari katalog.

## Kesalahan umum [#common-mistakes]

* **OpenClaw memperingatkan bahwa `CHEAPAIMODEL_API_KEY` tidak ada.** Proses Gateway tidak punya variabel itu, jadi `${CHEAPAIMODEL_API_KEY}` tidak terisi. Taruh di `~/.openclaw/.env`, lalu mulai ulang Gateway.
* **`401`.** Key-nya salah, sudah kedaluwarsa, atau anggarannya habis. Cek di Konsol.
* **Konfigurasi ditolak dengan `custom model providers must declare models`.** Penyedia kustom butuh array `models`, dan setiap entri butuh `id` dan `name`.
* **`404`.** Kalau isi responsnya `fault filter abort`, `baseUrl` tidak menyertakan `/v1`; kalau `Invalid URL (POST /v1/chat/completions/chat/completions)`, `baseUrl` menyertakan path endpoint. Atur ke `https://api.cheapaimodel.ai/v1`.
* **`503` dengan `model_not_found`.** `id` harus berupa ID katalog, ditulis persis sama. Awalan `cheapaimodel/` hanya referensi model di OpenClaw dan tidak ikut dikirim.