# OpenCode with OpenCheese

> Add OpenCheese to OpenCode: Auto-sync with a personal link, the generated opencode.json, a minimal manual setup, model variants, OpenCode 2 and troubleshooting.
>
> Web page: https://opencheese.dev/en/docs/opencode/ · Every docs page: https://opencheese.dev/llms.txt

OpenCode connects to OpenCheese as an OpenAI-compatible provider at
`https://api.opencheese.dev/v1`. OpenCode 1.x and 2.x read the same configuration.

## Recommended: Auto-sync

With Auto-sync, OpenCode downloads its OpenCheese settings by itself: models you switch on or
off on the **Prices** page, and new models, arrive without copying any file.

1. Sign in, open **Configuration**, choose the **OpenCode** tab and go to the Auto-sync steps.
2. Pick the API key OpenCode should use, enter that key's password and create your personal
   link.
3. Run the one command the page shows, once, in a terminal:

```bash
opencode auth login https://opencheese.dev/c/YOUR_PERSONAL_LINK
```

OpenCode stores the key and loads its configuration from OpenCheese from then on. The login
runs a small Node.js command, so Node.js 18 or newer must be on your `PATH` (it is when you
installed OpenCode with npm).

- **Updates:** OpenCode 2 picks up changes within 10 minutes, or at once with
  `opencode reload` (best while it is idle). OpenCode 1 picks them up when it starts, and can
  only start while OpenCheese is reachable.
- **Your own settings:** keep a small `opencode.json` with only your own things, such as an
  `mcp` section. Do not list models in it: models listed there stay visible even after you
  switch them off. Delete or trim an `opencode.json` you copied earlier.
- **The link is a password:** anyone who has it can use the key. It is shown once. Revoke it
  under **Your personal links**; an OpenCode that already logged in keeps the key, so disable or
  delete the API key to stop it. After changing the key's password, run the login again.

## Or copy the generated file

Sign in, open **Configuration**, choose the **OpenCode** tab, pick an API key and confirm your
password, then merge the generated file into your user configuration:

| System | File |
| --- | --- |
| macOS and Linux | `~/.config/opencode/opencode.json` |
| Windows | `%USERPROFILE%\.config\opencode\opencode.json` |

The generated file lists every text model your key can use, with its display name, context
and output limits, per-token costs (OpenCode shows the cost of each message), reasoning
variants and the right AI SDK package for each model. Prefer it to a hand-written one, and
copy it again after your plan or model list changes.

## Manual setup with one model

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "opencheese": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenCheese",
      "options": {
        "baseURL": "https://api.opencheese.dev/v1",
        "apiKey": "{env:OPENCHEESE_API_KEY}"
      },
      "models": {
        "MODEL_ID": { "name": "Model name", "variants": {} }
      }
    }
  },
  "model": "opencheese/MODEL_ID"
}
```

- `baseURL` must end in `/v1`.
- `{env:OPENCHEESE_API_KEY}` reads the key from your environment; the generated file contains
  the key itself.
- Keep `"variants": {}` on every model you add by hand. Without it OpenCode 2.x offers
  low, medium and high reasoning variants of its own, which a model may not support.
- Take the model IDs from `GET /v1/models` with your key (see [Models](https://opencheese.dev/en/docs/models.md)).

## OpenCode 2

OpenCode 2 is the recommended version. Step 2 of the **OpenCode** tab switches between OpenCode 2
(the default) and OpenCode 1, which is legacy and supported until 1 November; both read the same
settings. Moving up from OpenCode 1: OpenCode 2 is a different package and moves your session
history over the first time it starts, so back that history up first. The tab shows the exact
commands, including the way back to OpenCode 1.

## Usage and costs

Every request appears under **Transactions** in the dashboard, grouped as one session per
conversation, with its token usage and cost.

## Troubleshooting

- **"Invalid or disabled OpenCheese API key"**: check the key on the **API keys** page and that
  `OPENCHEESE_API_KEY` is set where OpenCode starts. With Auto-sync, run the login again.
- **A model is missing**: models depend on your plan and key restrictions. With Auto-sync,
  restart OpenCode 1 or run `opencode reload` in OpenCode 2; with a copied file, copy it again.
- **A switched-off model still shows**: a model listed in your local `opencode.json` stays
  visible; remove it there.
- **"Not included in your current plan"**: choose another model, or keep **Use balance for
  Credit Models** on in the Overview page to pay for it from your balance.