> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode | AI Gateway

> Route OpenCode model calls through the Orq.ai AI Gateway for unified observability, cost tracking, and model governance.

Route every model call OpenCode makes through the [**AI Gateway**](/docs/ai-studio/ai-gateway/quickstart) by editing a single configuration file. Requests appear in [**Traces**](/docs/ai-studio/observability/traces) automatically, and API key usage limits are enforced per workspace.

## Prerequisites

* [OpenCode](https://opencode.ai) installed:

<CodeGroup>
  ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
  npm i -g opencode-ai
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -fsSL https://opencode.ai/install | bash
  ```
</CodeGroup>

* Active **Orq.ai** account
* [Orq.ai API key](/docs/ai-studio/organization/api-keys) exported as `ORQ_API_KEY`

## Setup

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "$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"
}
```

<Warning>
  **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.
</Warning>

## Auto Router

Point OpenCode at an [Auto Router](/docs/ai-studio/ai-gateway/auto-router) to let the **AI Gateway** select the best model automatically:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "$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](/docs/ai-studio/ai-gateway/auto-router)**.

## Verification

Send a prompt in OpenCode. The response appears in the editor and the trace appears in [**Traces**](/docs/ai-studio/observability/traces) with the model identifier and cost breakdown.

<Frame caption="An OpenCode request routed through the AI Gateway, visible in Traces.">
  <img src="https://mintcdn.com/orqai/9d2EH-67RWgmerCN/images/example-opencode-trace.png?fit=max&auto=format&n=9d2EH-67RWgmerCN&q=85&s=01a86f98a30b69fa1050858004624064" alt="Trace detail showing an OpenCode request with model identifier, token counts, latency, and cost breakdown." width="1492" height="734" data-path="images/example-opencode-trace.png" />
</Frame>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>