OpenCode Configuration

1. What OpenCode is and what you need

OpenCode is an open source AI coding agent. It can read repositories, edit code, run commands, and work with desktop, web, and IDE interfaces.

Before connecting OpenCode through RouteAPI, prepare:

A working terminal environment
Your RouteAPI key
A model available in the RouteAPI console and suitable for coding tasks
Prefer a model that supports the OpenAI-compatible protocol and tool calls

2. Install OpenCode

Install the CLI

For macOS / Linux / WSL, the official recommended installation is:

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

If you prefer global Node.js installation:

npm install -g opencode-ai

For native Windows PowerShell:

npm install -g opencode-ai

Verify installation

opencode --version

A version number means OpenCode CLI is installed.

3. Recommended path: save the key, then write project config

OpenCode documentation recommends saving credentials with /connect first, then declaring provider and model in a config file. For RouteAPI, choose Other.

Save the RouteAPI key in OpenCode

Start OpenCode:

opencode

Then run in the session:

/connect

Complete these steps:

Select Other
Set the provider ID to routeapi
Paste your RouteAPI key

OpenCode writes credentials to local ~/.local/share/opencode/auth.json, so manual editing is usually not needed.

Create `opencode.json` in the project root

OpenCode supports both global ~/.config/opencode/opencode.json and project-level opencode.json. For team collaboration, keep non-sensitive configuration in the project root.

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

In this configuration:

routeapi: the custom provider ID, which must match the provider ID used in /connect
npm: use @ai-sdk/openai-compatible for /v1/chat/completions; use @ai-sdk/openai for /v1/responses
options.baseURL: https://www.routeapi.ai/v1
models: use the actual model ID available in the RouteAPI console, not a display name
model: the default model format is provider_id/model_id, here routeapi/your-routeapi-model-id

4. Alternative: use environment variables instead of `/connect`

If you prefer loading the key from an environment variable, set options.apiKey in opencode.json. This variable syntax is supported by OpenCode documentation.

4.1 Set the environment variable

If you use bash, zsh, or sh on macOS / Linux / WSL:

export ROUTEAPI_KEY="your RouteAPI key"

If you use Windows PowerShell:

$env:ROUTEAPI_KEY="your RouteAPI key"

4.2 Reference the environment variable in `opencode.json`

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "routeapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "RouteAPI",
      "options": {
        "baseURL": "https://www.routeapi.ai/v1",
        "apiKey": "{env:ROUTEAPI_KEY}"
      },
      "models": {
        "your-routeapi-model-id": {
          "name": "RouteAPI Model"
        }
      }
    }
  },
  "model": "routeapi/your-routeapi-model-id"
}

5. Select a model and start OpenCode

After configuration, select a model and start:

Start OpenCode:

opencode

Run in the session:

/models

Select a model under routeapi. If model is already set in opencode.json, OpenCode uses it by default.

To temporarily switch the model for the current session, use:

opencode -m routeapi/your-routeapi-model-id

For lightweight tasks such as title generation, you can add a cheaper model:

{
  "small_model": "routeapi/your-small-model-id"
}

6. Common troubleshooting

Run opencode auth list to confirm that routeapi credentials are saved locally
If /models does not show your custom provider, check that the provider ID in /connect exactly matches routeapi in opencode.json
If models appear but requests fail with a protocol error, check the npm package: use @ai-sdk/openai-compatible for /v1/chat/completions and @ai-sdk/openai for /v1/responses
On Windows, if file access is slow, terminal behavior is abnormal, or paths differ, prefer running OpenCode in WSL
To compare other RouteAPI clients, continue with Codex configuration, Cursor configuration, and Claude Code configuration