# OpenCode 接入指南

OpenCode 是一款开源的终端 AI 编程工具，提供交互式 TUI 界面，支持多模型切换与工作区代码修改。本文介绍如何让它通过 UModelverse 平台调用模型。

## **系统要求**

| 平台 | 要求 |
| --- | --- |
| Windows | Windows 10 或 Windows 11 |
| macOS | macOS 10.15 (Catalina) 或更高版本 |
| Linux | 主流发行版（Ubuntu、Debian 等） |

所有平台均需要网络连接。

## **1. 安装 OpenCode**

### macOS（推荐使用 Homebrew）

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

### npm（跨平台）

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

安装后验证：

```
opencode --version
```

## **2. 配置 UModelverse API**

### 2.1 获取 API Key

访问 [UModelverse 控制台](https://console.ucloud.cn/modelverse/api) 获取您的 API 密钥。可用模型见 UModelverse 平台[支持的模型](https://api.modelverse.cn/v1/models)。

### 2.2 写入配置文件

OpenCode 通过 `opencode.json` 完成配置，各平台路径如下：

| 平台 | 路径 |
| --- | --- |
| macOS / Linux | `~/.config/opencode/opencode.json` |
| Windows | `%APPDATA%\opencode\opencode.json` |

将以下内容写入配置文件（将 `YOUR_API_KEY` 替换为实际 Key）：

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

> **注意：** `models` 中的键名即模型 ID，可按需替换为 UModelverse 平台[支持的模型](https://api.modelverse.cn/v1/models)中的任意一个，`name` 字段仅影响界面显示。如需接入多个模型，在 `models` 对象中并列添加即可。

## **3. 启动 OpenCode**

配置完成后，进入项目目录启动：

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

首次启动后在模型选择界面选择 **UModelverse** 下的模型即可开始编程。

## **常见问题**

### 提示认证失败或无法连接？

请逐项确认：

1.  `apiKey` 来自 UModelverse 平台，复制完整且无空格。

2.  `baseURL` 为 `https://api.modelverse.cn/v1`（带 `/v1` 后缀）。

3.  `models` 中填写的模型 ID 是 UModelverse 平台[支持的模型](https://api.modelverse.cn/v1/models)之一。

4.  修改配置文件后，重启 OpenCode 使其生效。

### 如何切换模型？

在 OpenCode 交互界面中按 `M` 键（或对应快捷键）打开模型选择面板，切换到 UModelverse 下已配置的任意模型。