OpenCode | AI Gateway - Orq.ai Documentation

Route every model call OpenCode makes through the AI Gateway by editing a single configuration file. Requests appear in Traces automatically, and API key usage limits are enforced per workspace.

Prerequisites

OpenCode installed:

npm i -g opencode-ai

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

Active Orq.ai account
Orq.ai API key exported as ORQ_API_KEY

Setup

Edit ~/.config/opencode/config.json and add an Orq.ai provider using the @ai-sdk/openai-compatible package:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "orq": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Orq Gateway",
      "options": {
        "baseURL": "https://api.orq.ai/v3/router",
        "apiKey": "{env:ORQ_API_KEY}"
      },
      "models": {
        "openai/gpt-5-mini": { "name": "GPT-5 Mini" },
        "anthropic/claude-opus-4-8": { "name": "Claude Opus 4.8" },
        "anthropic/claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" }
      }
    }
  },
  "model": "orq/openai/gpt-5-mini"
}

Model key must match the AI Gateway model ID exactly. The key in models (e.g. openai/gpt-5-mini) is sent verbatim to the AI Gateway as the model field. Using any other alias returns Model not found. Copy the exact model ID from AI Gateway > Models. The name field is display-only in OpenCode’s model picker and has no effect on routing.

Auto Router

Point OpenCode at an Auto Router to let the AI Gateway select the best model automatically:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "orq": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Orq Gateway",
      "options": {
        "baseURL": "https://api.orq.ai/v3/router",
        "apiKey": "{env:ORQ_API_KEY}"
      },
      "models": {
        "orquesta-demos@orq/company-approved-models": { "name": "Cost-optimised router" }
      }
    }
  },
  "model": "orq/orquesta-demos@orq/company-approved-models"
}

Replace orquesta-demos@orq/company-approved-models with the router name shown in AI Gateway > Auto Router.

Troubleshooting

Model not found

The model key in config.json does not match the model ID in the AI Gateway. Open AI Gateway > Models, copy the exact model ID (e.g. openai/gpt-5-mini), and use it as the key in the models object.

401 Unauthorized

Confirm echo $ORQ_API_KEY returns the expected value. The {env:ORQ_API_KEY} placeholder reads the variable at launch time. If the variable is not set, OpenCode sends an empty key.

Verification

Send a prompt in OpenCode. The response appears in the editor and the trace appears in Traces with the model identifier and cost breakdown.

Trace detail showing an OpenCode request with model identifier, token counts, latency, and cost breakdown.

​Prerequisites

​Setup

​Auto Router

​Troubleshooting

​Verification

Prerequisites

Setup

Auto Router

Troubleshooting

Verification