# OpenClaw (/docs/guides/openclaw)

Run the OpenClaw personal AI assistant on cheapaimodel models through a custom model provider.



OpenClaw adds OpenAI-compatible services as custom providers under `models.providers` in `~/.openclaw/openclaw.json`. Agents then refer to the models as `cheapaimodel/<model-id>`.

|          | OpenClaw setting                            | Value                                                                                                                |
| -------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Base URL | `models.providers.cheapaimodel.baseUrl`     | `https://api.cheapaimodel.ai/v1`                                                                                     |
| API key  | `models.providers.cheapaimodel.apiKey`      | `${CHEAPAIMODEL_API_KEY}`, holding your key from the console's [API Keys](https://console.cheapaimodel.ai/keys) page |
| Model ID | `models.providers.cheapaimodel.models[].id` | `glm-5.3`, or any ID from the [catalog](/models)                                                                     |

## Set it up [#set-it-up]

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

    Put the key in OpenClaw's global env file, which the Gateway reads even when it runs as a background service:

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

    If the Gateway is already running, restart it with `openclaw gateway restart` so it picks up the file.
  </Step>

  <Step>
    ### Add the provider [#add-the-provider]

    Merge this into your config:

    ```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"` sends requests to `/v1/chat/completions`.
    * Add one entry to `models` per model ID. `id` is the catalog ID; `name` is a label, and OpenClaw requires it.
    * Add `contextWindow` and `maxTokens` to each entry from the model's page, for example [/models/glm-5.3](/models/glm-5.3). Without them, OpenClaw budgets context with its own fallback and leaves the output limit to the server.
    * `compat.supportsUsageInStreaming` makes OpenClaw ask for token usage in streams, which cheapaimodel returns (see [Streaming](/docs/concepts/streaming)). Without it, OpenClaw estimates context use and logs `returned no token usage`.

    The Gateway watches the file and applies the change without a restart.
  </Step>

  <Step>
    ### Check it [#check-it]

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

    `cheapaimodel/glm-5.3` should be listed. To change the default model later, run `openclaw models set cheapaimodel/<model-id>`.
  </Step>
</Steps>

OpenClaw's agents rely on the model's tool calling. If a model handles tools poorly, try another model from the catalog.

## Common mistakes [#common-mistakes]

* **OpenClaw warns that `CHEAPAIMODEL_API_KEY` is missing.** The Gateway process doesn't have the variable, so `${CHEAPAIMODEL_API_KEY}` stays unresolved. Put it in `~/.openclaw/.env` and restart the Gateway.
* **`401`.** The key is wrong, expired or out of budget. Check it in the console.
* **The config is rejected with `custom model providers must declare models`.** A custom provider needs a `models` array, and each entry needs both `id` and `name`.
* **`404`.** With the body `fault filter abort`, `baseUrl` is missing `/v1`; with `Invalid URL (POST /v1/chat/completions/chat/completions)`, it includes the endpoint path. Set `https://api.cheapaimodel.ai/v1`.
* **`503` with `model_not_found`.** `id` must be a catalog ID, spelled exactly. The `cheapaimodel/` prefix is only OpenClaw's model ref and is not sent.