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

# OpenCode

> OpenCode integration guide: 75+ models in one place via GravitexAI

## 1. Overview

**OpenCode** is an open-source AI coding assistant with first-class support for **75+ models** and self-hosted deployments. Through **GravitexAI**, you can use mainstream models (GPT, Claude, Gemini, Qwen…) inside OpenCode without configuring every vendor separately.

<CardGroup cols={2}>
  <Card title="Unified multi-model" icon="layer-group">
    One provider, full GPT / Claude / Gemini / Qwen family
  </Card>

  <Card title="Self-host friendly" icon="house">
    Supports your own backends and per-project config overrides
  </Card>

  <Card title="Responses API ready" icon="bolt">
    `apiCompatibility: "responses"` works with the GPT Codex series
  </Card>

  <Card title="Open & auditable" icon="github">
    Fully open-source, customize as needed
  </Card>
</CardGroup>

**Download**: [https://opencode.ai/](https://opencode.ai/)

## 2. Quick Setup (GravitexAI)

### 2.1 Get an API key

<Steps>
  <Step title="Sign in">
    Go to the [GravitexAI console](https://maas.gravitex.ai) and register or log in.
  </Step>

  <Step title="Create a token">
    Open [API Keys](https://maas.gravitex.ai/#/keys), click "Create new token", and copy the `sk-xxxxxxxxxx` key.
  </Step>
</Steps>

### 2.2 Configure a custom provider in OpenCode

<Steps>
  <Step title="Open provider settings">
    In OpenCode, go to **Server / Provider** settings and select **Add custom provider** (OpenAI-compatible).
  </Step>

  <Step title="Fill in provider info">
    | Field            | Value                                                  |
    | ---------------- | ------------------------------------------------------ |
    | **Provider ID**  | `gravitex` (lowercase, digits, hyphens or underscores) |
    | **Display name** | `GravitexAI`                                           |
    | **Base URL**     | `https://api.gravitex.ai/v1` (must end with `/v1`)     |
    | **API key**      | Paste your GravitexAI key from the previous step       |
  </Step>

  <Step title="Add models">
    Under **Models**, add model IDs you want to use (e.g. `gpt-5.5`, `claude-sonnet-4-6`, `gemini-3.5-flash`). IDs must match the [GravitexAI model list](https://maas.gravitex.ai/#/models).
  </Step>

  <Step title="Save and use">
    After saving, select via **`providerID/modelID`** in chats and settings, e.g. `gravitex/gpt-5.5`.
  </Step>
</Steps>

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code1.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=58684b86ac98c126d9120754a130347f" alt="OpenCode custom provider setup" width="1920" height="1140" data-path="images/open-code1.png" />

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code2.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=723042c873497ae0187189a37a8f4761" alt="OpenCode provider and API config" width="795" height="526" data-path="images/open-code2.png" />

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code3.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=847981a9c861e6ee7a8117b8a5735503" alt="OpenCode model config" width="784" height="379" data-path="images/open-code3.png" />

### 2.3 Switching models

In chat or settings, pick the configured provider/model (e.g. `gravitex/gpt-5.5`) to switch.

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code4.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=4df30df18c54c4e8ad70838be2895d55" alt="OpenCode switch model" width="1920" height="1140" data-path="images/open-code4.png" />

<Tip>
  * For self-hosted or backup GravitexAI endpoints, change the **Base URL**, e.g. `http://your-server:3003/v1`.
  * Set a default model in project or global `opencode.json` via `"model": "gravitex/modelID"`.
</Tip>

## 3. Some Models Require the Responses API (Important)

Some **Azure / OpenAI** models **only support the Responses API**, not the legacy Chat Completions endpoint. When OpenCode defaults to Chat Completions you'll see:

> The chatCompletion operation does not work with the specified model, **gpt-5.1-codex**. Please choose different model and try again.

The screenshot below shows how this error appears in OpenCode:

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code8.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=fd180e21a6768b154ee4294cc197e230" alt="Error when using gpt-5.1-codex with Chat Completions" width="829" height="269" data-path="images/open-code8.png" />

### 3.1 Models that require Responses API

| Model ID / family        | Notes                                                             |
| ------------------------ | ----------------------------------------------------------------- |
| **gpt-5.1-codex**        | GPT 5.1 Codex (code-focused) — Responses API only                 |
| **gpt-5.2-codex**        | Same as above                                                     |
| **computer-use-preview** | Experimental model used with the Responses API computer-use tools |

For the latest full list, see **Azure / vendor docs**:

* [Azure OpenAI Responses API](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/responses)
* [Which models work with each operation](https://go.microsoft.com/fwlink/?linkid=2197993)

### 3.2 How to configure in OpenCode

Add the `apiCompatibility` parameter to a model in your config — no code changes needed.

<Steps>
  <Step title="Locate the config file">
    * **Windows**: `C:\Users\<username>\.config\opencode\opencode.jsonc`
    * **macOS / Linux**: `~/.config/opencode/opencode.jsonc`

    <img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code5.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=01584ee47c3224031512635d71eebb92" alt="Responses API requirement for some models" width="929" height="375" data-path="images/open-code5.png" />
  </Step>

  <Step title="Add the parameter">
    In your existing custom provider (pointing at GravitexAI or your own API), add **`"apiCompatibility": "responses"`** for models that need it (e.g. `gpt-5.1-codex`):

    <img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code6.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=10f5fd588261bb1683fdd87cb38d5729" alt="opencode.jsonc: apiCompatibility responses for gpt-5.1-codex" width="1920" height="1109" data-path="images/open-code6.png" />

    ```jsonc theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "disabled_providers": [
        "backup_gravitex"
      ],
      "provider": {
        "backup_gravitex": {
          "name": "backup_gravitex",
          "npm": "@ai-sdk/openai-compatible",
          "models": {
            "gpt-5.2": {
              "name": "gpt-5.2"
            },
            "gpt-5.1-codex": {
              "name": "gpt-5.1-codex",
              "apiCompatibility": "responses"
            },
            "gpt-5.1-chat": {
              "name": "gpt-5.1-chat"
            }
          },
          "options": {
            "baseURL": "xxxxxxxx"
          }
        },
        "backup_v1": {
          "name": "backup_v1",
          "npm": "@ai-sdk/openai-compatible",
          "models": {
            "gpt-5.2": {
              "name": "gpt-5.2"
            },
            "gpt-5.1-codex": {
              "name": "gpt-5.1-codex",
              "apiCompatibility": "responses"
            },
            "gpt-5.1-chat": {
              "name": "gpt-5.1-chat"
            }
          },
          "options": {
            "baseURL": "https://api.gravitex.ai/v1"
          }
        }
      }
    }
    ```

    After saving, selecting that provider's `gpt-5.1-codex` (e.g. `backup_v1/gpt-5.1-codex`) will send requests to that baseURL using the **Responses API** format.
  </Step>

  <Step title="Verify the setup">
    Pick a correctly configured model (e.g. `backup_v1/gpt-5.1-chat`) and test a chat — successful reply means you're good:

    <img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code7.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=e6c28ca55abb6264a1f8ad008cfef6e6" alt="OpenCode chat after successful config" width="1920" height="1140" data-path="images/open-code7.png" />
  </Step>
</Steps>

### 3.3 Summary

| Scenario                                                                       | What to do                                                                                                          |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Models that only support Responses (e.g. **gpt-5.1-codex**, **gpt-5.2-codex**) | Add **`"apiCompatibility": "responses"`** to that model under your custom provider's **models** in `opencode.jsonc` |
| Regular models (e.g. **gpt-5.5**, **claude-sonnet-4-6**, **gemini-3.5-flash**) | No `apiCompatibility` needed — follow Quick Setup                                                                   |

## 4. Recommended Models (via GravitexAI)

| Category            | Model ID examples                                                   | Notes                                  |
| ------------------- | ------------------------------------------------------------------- | -------------------------------------- |
| Flagship coding     | `gpt-5.5`, `claude-opus-4-7`                                        | Best overall coding ability            |
| Codex series        | `gpt-5.1-codex`                                                     | Requires Responses API (see Section 3) |
| General chat + code | `gpt-5.4`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`        | Works out of the box                   |
| Fast / low latency  | `gemini-3.5-flash`, `claude-haiku-4-5-20251001`                     | Great for completions & tool use       |
| Cost-effective      | `gpt-5.4-mini`, `gemini-3.1-flash-lite-preview`, `qwen3-coder-plus` | High concurrency / batch               |

See the [GravitexAI model list](https://maas.gravitex.ai/#/models) for complete IDs.

### Success example

A normal chat in OpenCode using GravitexAI:

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code7.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=e6c28ca55abb6264a1f8ad008cfef6e6" alt="OpenCode success with GravitexAI" width="1920" height="1140" data-path="images/open-code7.png" />

## 5. FAQ

<AccordionGroup>
  <Accordion title="`The chatCompletion operation does not work…` error">
    That model only supports the Responses API. Add `"apiCompatibility": "responses"` to it in `opencode.jsonc` — see Section 3.
  </Accordion>

  <Accordion title="401 / invalid API key">
    1. Check the key for completeness and trailing whitespace.
    2. Confirm it isn't deleted/disabled in the [GravitexAI console](https://maas.gravitex.ai/#/keys).
    3. Ensure your balance is positive.
  </Accordion>

  <Accordion title="404 / endpoint not found">
    Make sure the Base URL ends with `/v1`: `https://api.gravitex.ai/v1`.
  </Accordion>

  <Accordion title="`model not found` for a valid-looking ID">
    Model IDs must exactly match the [GravitexAI list](https://maas.gravitex.ai/#/models). Watch the case and version suffix (e.g. `claude-sonnet-4-5-20250929`, not `claude-sonnet-4-5`).
  </Accordion>

  <Accordion title="How to standardize across a team?">
    Commit `opencode.jsonc` to `.config/opencode/` in the repo (or the project root). Each engineer brings their own API key.
  </Accordion>
</AccordionGroup>

## 6. References

* OpenCode site and download: [https://opencode.ai/](https://opencode.ai/)
* OpenCode config and models: [Models](https://opencode.ai/docs/models), [Providers](https://opencode.ai/docs/providers)
* GravitexAI console: [https://maas.gravitex.ai](https://maas.gravitex.ai)
* Model catalog: [https://maas.gravitex.ai/#/models](https://maas.gravitex.ai/#/models)