# OpenClaw

> Add Deference to OpenClaw as a custom model provider in openclaw.json.

OpenClaw reads its config from `~/.openclaw/openclaw.json`, a JSON5 file. A custom provider names an API format and a base URL. This guide uses Chat Completions with `https://deference.si/v1`.

## Set up

1. Create a key in [API keys](https://deference.si/keys).
2. Add the key to `~/.openclaw/.env`. The Gateway runs as a background service, so a variable exported in your shell may not reach it.

```bash
DEFERENCE_API_KEY=sk-df-...
```

3. Add the provider and the model to `~/.openclaw/openclaw.json`.

```json5
{
  agents: {
    defaults: {
      model: { primary: "deference/anthropic/claude-sonnet-5.5" },
      models: {
        "deference/anthropic/claude-sonnet-5.5": { alias: "Sonnet" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      deference: {
        baseUrl: "https://deference.si/v1",
        apiKey: "${DEFERENCE_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "anthropic/claude-sonnet-5.5",
            name: "Claude Sonnet 5.5",
            reasoning: false,
            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 64000,
          },
        ],
      },
    },
  },
}
```

Provider changes apply without a restart. If OpenClaw does not pick them up, run `openclaw gateway restart`.

Each model needs its own entry in `models`. An alias under `agents.defaults.models` does not register a model by itself. `cost` stays at zero because Activity tracks the real cost.

## Verify

1. Run `openclaw models list --provider deference`. The model you declared is listed.
2. Run `openclaw models status --probe`. It makes a live call and reports `ok`, or a bucket such as `auth`, `billing` or `timeout`.
3. Send a message to the agent.
4. Open [Activity](https://deference.si/activity). The request is the top row, with the model you chose.

## Pick a model

* A model reference is `provider/model-id`. OpenClaw splits on the first slash, so `deference/anthropic/claude-sonnet-5.5` is provider `deference` and model `anthropic/claude-sonnet-5.5`.
* Pin a model with `openclaw models set deference/anthropic/claude-sonnet-5.5`, or `/model deference/anthropic/claude-sonnet-5.5` in chat.
* `api` is `openai-completions` (the default), `openai-responses` or `anthropic-messages`. For `anthropic-messages`, set `baseUrl` to `https://deference.si`: OpenClaw adds `/v1`. Implicit beta headers are off on a custom host, so set `headers: { "anthropic-beta": "..." }` if a model needs them.
* Raise `timeoutSeconds` on the provider for slow models.

## Troubleshooting

| You see                        | Cause                                                                        | Fix                                                                                       |
| ------------------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `401 invalid_api_key`          | The Gateway cannot see `DEFERENCE_API_KEY`                                   | Put it in `~/.openclaw/.env` and restart the Gateway                                      |
| The model is not listed        | It has no entry in `models`, only an alias                                   | Add it under `models.providers.deference.models`                                          |
| The model does not change      | The config was invalid, so OpenClaw kept the last good one                   | Run `openclaw doctor`, fix the file, and check again                                      |
| `404 model_not_found`          | The `id` differs from the catalog                                            | Copy the id from the Models page                                                          |
| `402 insufficient_credit`      | No available credit                                                          | [Add credit](https://deference.si/wallet?tab=add)                                                             |
| `402 free_credit_not_eligible` | The account has only free credit, and this model or request does not qualify | Use an open-weight text model, set a lower `max_tokens`, or [add credit](https://deference.si/wallet?tab=add) |
| `402 key_limit_reached`        | The key reached the credit limit set on it                                   | Raise the key's limit in API keys, or use another key                                     |