OpenCode

Connect OpenCode to CoffeeRouter with stored credentials and an OpenAI-compatible custom provider.

Before you begin

  • Create an active CoffeeRouter token and note the exact model IDs available to it.
  • This guide uses OpenAI Chat Completions with the base URL https://www.coffeerouter.ai/v1.
  • Windows users can install with npm, Chocolatey, or Scoop; OpenCode officially recommends WSL for the best Windows experience.

Configuration steps

1. Install OpenCode

On macOS or Linux, use the official installer:

curl -fsSL https://opencode.ai/install | bash

You can also install OpenCode with npm, Bun, or pnpm:

npm install -g opencode-ai

bun install -g opencode-ai

pnpm install -g opencode-ai

Run opencode to open the terminal UI after installation.

2. Save the CoffeeRouter credential

In OpenCode, enter:

/connect

Scroll to the bottom of the provider list, choose Other, and enter:

FieldValue
Provider IDcoffeerouter
API Keysk-your-api-key

The provider ID must exactly match the key used in opencode.json in the next step. /connect only stores the credential in ~/.local/share/opencode/auth.json; it does not configure the CoffeeRouter endpoint or models.

3. Configure the CoffeeRouter provider

For all projects, add the provider to ~/.config/opencode/opencode.json. For the current project only, create opencode.json in the project root. Project configuration has higher precedence than global configuration.

{
    "$schema": "https://opencode.ai/config.json",
    "provider": {
        "coffeerouter": {
            "npm": "@ai-sdk/openai-compatible",
            "name": "CoffeeRouter",
            "options": {
                "baseURL": "https://www.coffeerouter.ai/v1"
            },
            "models": {
                "your-model-id": {
                    "name": "Your Model"
                }
            }
        }
    }
}

Replace your-model-id with the complete model ID shown in CoffeeRouter. @ai-sdk/openai-compatible uses /v1/chat/completions. If a model explicitly requires /v1/responses, use @ai-sdk/openai instead; do not mix the two API formats.

4. Select a CoffeeRouter model

Restart OpenCode and enter:

/models

Choose your-model-id under CoffeeRouter. The provider ID, credential ID, and the coffeerouter key in the configuration must all match.

Verify the connection

First confirm that the credential is stored:

opencode auth list

After coffeerouter appears in the list, start OpenCode, select the CoffeeRouter model, and send a test request. A normal response that can use the project context confirms the connection.

Troubleshooting

Why is CoffeeRouter missing after I run /connect?

/connect only stores a credential. You must also add provider.coffeerouter, the base URL, and the model list to a global or project opencode.json, then restart OpenCode.

Why does OpenCode report a missing credential?

Make sure the Provider ID entered under /connect exactly matches coffeerouter in the configuration, and run opencode auth list to confirm the credential was saved.

Why does the base URL include /v1?

@ai-sdk/openai-compatible expects an OpenAI-compatible base URL and calls Chat Completions beneath it. The CoffeeRouter base URL is https://www.coffeerouter.ai/v1.

Why is the model missing from /models?

Check the model ID in the models object, the JSON syntax, and the configuration file location. The model ID must exactly match a model available to your CoffeeRouter token.

Security

Use /connect to store credentials instead of placing a real token in project configuration that may be committed. Do not share auth.json, configuration screenshots, or logs. Create a dedicated OpenCode token with model, quota, and IP restrictions.

Official resources