# OpenCode

> Define Deference as a provider in opencode.json.

OpenCode loads OpenAI-compatible providers through `@ai-sdk/openai-compatible`. It speaks Chat Completions, so the base URL is `https://deference.si/v1`. This guide uses the 1.x config format.

## Set up

1. Create a key in [API keys](https://deference.si/keys) and export it as `DEFERENCE_API_KEY` in the shell that starts OpenCode.
2. Add the provider to `opencode.json` in your project, or to `~/.config/opencode/opencode.json` for every project. On Windows the global file is `%USERPROFILE%\.config\opencode\opencode.jsonc`.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "deference": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Deference",
      "options": {
        "baseURL": "https://deference.si/v1",
        "apiKey": "{env:DEFERENCE_API_KEY}"
      },
      "models": {
        "anthropic/claude-sonnet-5.5": {
          "name": "Claude Sonnet 5.5",
          "limit": { "context": 200000, "output": 64000 }
        }
      }
    }
  },
  "model": "deference/anthropic/claude-sonnet-5.5"
}
```

3. Start `opencode`.

To store the key instead of reading it from the environment, run `/connect`, choose **Other**, enter the provider id `deference` and paste the key. OpenCode saves it in `~/.local/share/opencode/auth.json`.

## Verify

1. Run `opencode models deference`. It lists the models you declared.
2. Run a one-off prompt.

```bash
opencode run -m deference/anthropic/claude-sonnet-5.5 \
  "Reply with exactly: gateway-ok"
```

3. Open [Activity](https://deference.si/activity). The request is the top row, with the model you chose.

`opencode auth list` shows keys saved with `/connect`. A key read from `{env:DEFERENCE_API_KEY}` does not appear there.

## Pick a model

* List each model you want under `models`, keyed by its exact id. Select one with `-m deference/<id>`, the `model` setting, or `/models`.
* A model reference is `provider/model`. OpenCode splits on the first slash, so the model id can contain slashes.
* Set `limit.context` and `limit.output` for every model. OpenCode takes limits from a public registry for its built-in providers and has none for yours.
* Use `@ai-sdk/openai` as the package for models served through `POST /v1/responses`. You can set a different package on one model.
* OpenCode 2 renames some config fields. Keep to one format per file and follow OpenCode's migration guide when you move.

## Troubleshooting

| You see                            | Cause                                                                     | Fix                                          |
| ---------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------- |
| `ProviderModelNotFoundError`       | The reference is not `provider/model`, or the model is not under `models` | Run `opencode models` and copy the reference |
| The model is not in the list       | It is missing from `models`                                               | Add it, keyed by its exact id                |
| `401 missing_api_key`              | The variable is not set where OpenCode starts, so the key is empty        | Export `DEFERENCE_API_KEY` in that shell     |
| The config is ignored              | The file is not valid JSON                                                | Check commas and quotes                      |
| `AI_APICallError` after an upgrade | OpenCode cached an old provider package                                   | Delete `~/.cache/opencode` and restart       |
| `404 model_not_found`              | The key under `models` differs from the catalog id                        | Copy the id from the Models page             |