# OpenCode Integration Guide

OpenCode is an open-source terminal AI coding tool that provides an interactive TUI interface, supports multi-model switching, and workspace code editing. This guide explains how to use it to call models through the UModelverse platform.

## **System Requirements**

| Platform | Requirement |
| --- | --- |
| Windows | Windows 10 or Windows 11 |
| macOS | macOS 10.15 (Catalina) or later |
| Linux | Mainstream distributions (Ubuntu, Debian, etc.) |

A network connection is required on all platforms.

## **1. Install OpenCode**

### macOS (Homebrew recommended)

```
brew install sst/tap/opencode
```

### npm (cross-platform)

```
npm install -g opencode-ai
```

Verify the installation:

```
opencode --version
```

## **2. Configure the UModelverse API**

### 2.1 Obtain an API Key

Visit the [UModelverse Console](https://console.ucloud.cn/modelverse/api) to get your API key. For available models, see the [supported models](https://api-us-ca.umodelverse.ai/v1/models) on the UModelverse platform.

### 2.2 Write the Configuration File

OpenCode is configured via `opencode.json`. The file path on each platform is as follows:

| Platform | Path |
| --- | --- |
| macOS / Linux | `~/.config/opencode/opencode.json` |
| Windows | `%APPDATA%\opencode\opencode.json` |

Write the following content to the configuration file (replace `YOUR_API_KEY` with your actual key):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "modelverse": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "UModelverse",
      "options": {
        "baseURL": "https://api-us-ca.umodelverse.ai/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "deepseek-v4-pro": {
          "name": "DeepSeek V4 Pro",
          "limit": {
            "context": 1000000,
            "output": 65536
          }
        }
      }
    }
  }
}
```

> **Note:** The key name in `models` is the model ID. You can replace it with any model from the [supported models](https://api-us-ca.umodelverse.ai/v1/models) on the UModelverse platform. The `name` field only affects the display in the interface. To add multiple models, list them as separate entries inside the `models` object.

## **3. Start OpenCode**

Once configuration is complete, navigate to your project directory and start OpenCode:

```
cd your-project-folder
opencode
```

On first launch, select a model under **UModelverse** in the model selection screen to start coding.

## **Frequently Asked Questions**

### Authentication failure or unable to connect?

Check each of the following:

1.  The `apiKey` is from the UModelverse platform, copied in full with no extra spaces.

2.  The `baseURL` is `https://api-us-ca.umodelverse.ai/v1` (with the `/v1` suffix).

3.  The model ID entered in `models` is one of the [supported models](https://api-us-ca.umodelverse.ai/v1/models) on the UModelverse platform.

4.  After modifying the configuration file, restart OpenCode for the changes to take effect.

### How do I switch models?

In the OpenCode interactive interface, press the `M` key (or the corresponding shortcut) to open the model selection panel, then switch to any model you have configured under UModelverse.