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

# 在 OpenCode 中使用

> 将 HubTo 接入 OpenCode，通过自定义 OpenAI 兼容提供方使用统一模型网关。

## 概述

OpenCode 是一个面向开发者的 AI 编码工具，支持通过配置文件接入自定义模型提供方。

将 OpenCode 接入 HubTo 后，你可以用统一的 API Key、基础地址和模型名完成编码问答、重构和命令行协作。

## 前置条件

* 已安装并可以正常使用 OpenCode
* 已拥有可用的 HubTo API Key
* 网络环境可以访问 `https://api.hubto.ai`

## 配置方式

OpenCode 支持全局配置和项目级配置：

* 全局配置：`~/.config/opencode/opencode.json`
* 项目级配置：项目根目录下的 `opencode.json`

如果你希望所有项目都走 HubTo，建议先使用全局配置。

## 配置步骤

### 步骤 1：设置 API Key

先在终端中写入环境变量：

```bash theme={null}
export HUBTO_API_KEY="YOUR_API_KEY"
```

### 步骤 2：写入 OpenCode 配置

在 `~/.config/opencode/opencode.json` 中添加如下内容：

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "hubto": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "HubTo",
      "options": {
        "baseURL": "https://api.hubto.ai/v1",
        "apiKey": "{env:HUBTO_API_KEY}"
      },
      "models": {
        "glm-5.1": {
          "name": "GLM-5.1"
        }
      }
    }
  },
  "model": "hubto/glm-5.1"
}
```

### 步骤 3：启动 OpenCode

```bash theme={null}
opencode
```

### 步骤 4：切换模型

如果你已经在 HubTo 中开通了其他模型，可以把默认模型改成对应值，例如：

```json theme={null}
{
  "model": "hubto/deepseek-v3.1"
}
```

## 推荐验证方式

启动后先发一个简单请求，例如“解释一下当前项目结构”。如果能正常返回内容，说明 HubTo 接入已经生效。

## 使用建议

* 先用一个基础模型验证链路，再切换到日常使用的主模型
* 如果你希望按项目隔离配置，可以把 `opencode.json` 放到项目根目录
* 如果你需要多人协作，建议为 OpenCode 单独创建一个 API Key

## 常见问题

### 启动后看不到自定义模型

请确认配置文件路径正确，并检查 JSON 语法是否有效。

### 返回认证失败

请确认 `HUBTO_API_KEY` 已生效，并且值来自 HubTo 控制台。

### 返回 404 或请求地址错误

请确认 `baseURL` 使用的是：

```txt theme={null}
https://api.hubto.ai/v1
```

## 下一步

* 获取 API Key：参见 [快速上手](/cn/quickstart)
* 查看接口文档：参见 [接口参考](/cn/api-reference/introduction)