# OpenCode config for Claude: opencode.json setup, models and common errors

OpenCode reads its settings from `opencode.json`. To run it on Claude through this gateway you change one value, the Anthropic provider's `baseURL`, and give it a key. Below are two working configs, the model and context settings that matter, and fixes for the errors OpenCode users run into on this gateway, taken from our own request logs.

## Where opencode.json lives

OpenCode merges a global config with a per-project one: `~/.config/opencode/opencode.json` for settings you want everywhere, and `opencode.json` in a project root for that repository. Adding the `$schema` line gives you autocompletion and validation in most editors.

Keep the key out of the file. Put it in an environment variable and reference it as `{env:AIPRIME_API_KEY}`. Keys you add with `/connect` inside OpenCode are stored in `~/.local/share/opencode/auth.json`; `opencode auth list` shows what is stored there.

```bash
export AIPRIME_API_KEY=your_gateway_key   # add to ~/.bashrc or ~/.zshrc
opencode auth list                         # credentials OpenCode already knows about
```

## Option 1: point the built-in Anthropic provider at the gateway

The smallest change: keep OpenCode's own Anthropic provider and its model list, and override where it sends requests.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://aiprimetech.io/v1",
        "apiKey": "{env:AIPRIME_API_KEY}"
      }
    }
  },
  "model": "anthropic/claude-sonnet-5",
  "small_model": "anthropic/claude-haiku-4-5"
}
```

> The `baseURL` must end in `/v1`. OpenCode's Anthropic provider is the AI SDK's `@ai-sdk/anthropic`, whose default is `https://api.anthropic.com/v1`; it appends `/messages` to whatever you give it. Without `/v1` the request lands on the website and returns HTML, which OpenCode reports as a parse error.

## Option 2: a custom provider with your own model list

A separate provider entry keeps the gateway apart from any Anthropic login, lets you list exactly the models you want in the picker, and lets you set context limits per model.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aiprime": {
      "npm": "@ai-sdk/anthropic",
      "name": "AI Prime Tech",
      "options": {
        "baseURL": "https://aiprimetech.io/v1",
        "apiKey": "{env:AIPRIME_API_KEY}"
      },
      "models": {
        "claude-sonnet-5":  { "name": "Claude Sonnet 5",  "limit": { "context": 200000, "output": 64000 } },
        "claude-opus-5-5":  { "name": "Claude Opus 5.5",  "limit": { "context": 200000, "output": 64000 } },
        "claude-haiku-4-5": { "name": "Claude Haiku 4.5", "limit": { "context": 200000, "output": 32000 } }
      }
    }
  },
  "model": "aiprime/claude-sonnet-5",
  "small_model": "aiprime/claude-haiku-4-5"
}
```

Prefer `@ai-sdk/anthropic` for Claude: it speaks the native Messages API, so prompt caching and thinking work as Anthropic designed them. The gateway also serves the OpenAI shape, so `@ai-sdk/openai-compatible` with the same `https://aiprimetech.io/v1` base URL works too, and it is the route to use for GPT models on the same key.

## Models and context limits

| Model ID | Use it for |
| --- | --- |
| `claude-sonnet-5` | Default for coding and agent work: fast, strong, mid-priced. |
| `claude-opus-5-5` | Harder reasoning, large refactors, long agent runs. |
| `claude-fable-5-1` | Most capable and most expensive; save it for the hardest tasks. |
| `claude-haiku-4-5` | Cheap and quick: titles, summaries, classification, small steps. |

`model` is what the main agent uses; `small_model` handles cheap side jobs such as session titles. The `limit.context` number tells OpenCode when to compact the session. If a long session fails with `prompt is too long`, lower it (200000 is a safe value) so OpenCode summarises earlier instead of sending more than the endpoint accepts.

Model IDs are exact strings. Older names such as `claude-3-5-sonnet-20241022` or dated snapshots are not served; use the IDs above or the list in your dashboard.

## Check the key and URL before starting OpenCode

One request from the terminal tells you whether the key and URL are right, independently of OpenCode's config:

```bash
curl -s https://aiprimetech.io/v1/messages \
  -H "x-api-key: $AIPRIME_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":20,"messages":[{"role":"user","content":"ping"}]}'
```

A JSON reply with a `content` array means the gateway side is fine and any remaining problem is in `opencode.json`. `Invalid API key` means the variable is empty or holds the wrong key.

## Troubleshooting: errors OpenCode users hit

These are the errors that show up most for OpenCode on this gateway, with the fix for each.

| What you see | Cause | Fix |
| --- | --- | --- |
| A JSON parse error, response starting with `<` | `baseURL` without `/v1`: the request reached the website, not the API | End `baseURL` with `/v1` |
| `404 page not found` | `/v1` twice, so the path becomes `/v1/v1/messages` | Use exactly `https://aiprimetech.io/v1` |
| `Invalid API key` | The variable is not exported in the shell OpenCode started from, or a different key is in use | `echo $AIPRIME_API_KEY`, `opencode auth list`, restart OpenCode |
| Model not supported / model not found | An ID the endpoint does not serve, often an old dated name | Use an ID from the table above |
| `prompt is too long: N tokens > N tokens` | The session outgrew what the model accepts | `/compact`, and lower `limit.context` |
| `Concurrency limit exceeded for user` | Parallel subagents exceed your key's concurrency | Run fewer subagents at once, or ask support for higher concurrency |
| `Insufficient account balance` | Balance is empty | [Top up](/topup/) and retry |
| `No available accounts` or `This request could not be completed` | Temporary capacity problem upstream | Send the message again; switch model if it persists |

For errors that come from the model side rather than the client, see the [Claude API errors guide](/learn/claude-api-errors-troubleshooting/).

## FAQ

### Where is the OpenCode config file?

Globally at ~/.config/opencode/opencode.json and per project as opencode.json in the repository root. OpenCode merges the two.

### How do I use Claude in OpenCode with an API key?

Set provider.anthropic.options.baseURL to the gateway URL ending in /v1 and apiKey to {env:YOUR_VAR}, or add a custom provider with npm @ai-sdk/anthropic, then choose the model with model: provider/model-id.

### Why does OpenCode fail with a parse error or a response starting with '<'?

The baseURL is missing /v1, so requests reach the website instead of the API. @ai-sdk/anthropic expects the full prefix, e.g. https://aiprimetech.io/v1.

### Can OpenCode use a Claude Pro or Max login?

OpenCode's docs note that Anthropic prohibits third-party Pro/Max plugins and that OpenCode stopped bundling them in 1.3.0. An API key is the supported route.

---

Source: https://aiprimetech.io/learn/use-claude-api-with-opencode/
Provider: AI Prime Tech — independent Anthropic-compatible API gateway (not affiliated with Anthropic).