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

# OpenCode

> 将 AIOHub 配置为 OpenCode 的模型服务商。

[OpenCode](https://opencode.ai/docs) 是开源 AI 编程助手，支持终端 TUI、桌面应用和 IDE 扩展。AIOHub 接入 OpenCode 时，优先把 AIOHub 配成独立模型服务商，避免和官方 OpenAI、Anthropic 或其它服务商凭据混用。

## 前置条件

* 已安装 OpenCode
* 已 [创建 AIOHub API 令牌](/cn/account/create-token)
* API 令牌的分组包含你要使用的模型
* 账户有充足余额

可以先确认 OpenCode 已安装：

```bash theme={"system"}
opencode --version
opencode --help
```

## 配置位置

OpenCode 支持全局配置和项目配置。全局配置适合个人默认服务商，项目配置适合随项目共享模型列表。

| 场景     | 文件                                 |
| ------ | ---------------------------------- |
| 用户全局配置 | `~/.config/opencode/opencode.json` |
| 当前项目配置 | `opencode.json`                    |

<Note>项目级 `opencode.json` 会覆盖全局配置中的同名字段。不要把真实 API 令牌提交到 Git；需要共享项目配置时，用 `/connect` 保存本机凭据，或用环境变量引用 API 令牌。</Note>

## 配置 Chat Completions 模型

OpenCode 的 `@ai-sdk/openai-compatible` 适合走 OpenAI Chat Completions 的模型。Base URL 填 `https://api.aiohub.org/v1`，不要填完整请求路径。

### 1. 添加凭据

在 OpenCode TUI 中运行：

```bash theme={"system"}
/connect
```

选择 Other，输入模型服务商 ID：

```text theme={"system"}
aiohub
```

然后输入完整的 AIOHub API 令牌。

### 2. 添加模型服务商配置

在 `opencode.json` 中加入：

```json theme={"system"}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aiohub": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AIOHub",
      "options": {
        "baseURL": "https://api.aiohub.org/v1"
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o"
        }
      }
    }
  },
  "model": "aiohub/gpt-4o"
}
```

把 `gpt-4o` 换成当前 API 令牌分组可用的 Chat Completions 模型。需要轻量模型时，可以加 `small_model`：

```json theme={"system"}
{
  "model": "aiohub/gpt-4o",
  "small_model": "aiohub/gpt-4o-mini"
}
```

## 配置 Responses 模型

如果你要在 OpenCode 里使用要求 OpenAI Responses 的模型或工作流，使用 `@ai-sdk/openai`。可以创建第二个模型服务商 ID，避免和 Chat Completions 配置混在一起。

先把 API 令牌放进环境变量：

```bash theme={"system"}
export AIOHUB_API_KEY="sk-你的API令牌"
```

再配置 Responses 模型服务商：

```json theme={"system"}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aiohub-responses": {
      "npm": "@ai-sdk/openai",
      "name": "AIOHub Responses",
      "options": {
        "baseURL": "https://api.aiohub.org/v1",
        "apiKey": "{env:AIOHUB_API_KEY}"
      },
      "models": {
        "gpt-5.3-codex": {
          "name": "GPT-5.3 Codex"
        }
      }
    }
  },
  "model": "aiohub-responses/gpt-5.3-codex"
}
```

<Note>同一个 OpenCode 配置可以保留多个模型服务商。Chat Completions 和 Responses 的请求路径不同；如果模型在一个配置下报端点或格式错误，先确认 `npm` 包和模型实际协议匹配。</Note>

## 验证配置

先用 OpenCode 查看模型列表：

```bash theme={"system"}
opencode
```

在 TUI 中运行：

```bash theme={"system"}
/models
```

选择 `aiohub/...` 或 `aiohub-responses/...` 下的模型，然后发送一条短消息。正常回复即表示配置成功。

也可以先用 HTTP 验证 API 令牌和模型是否可用：

```bash theme={"system"}
curl https://api.aiohub.org/v1/models \
  -H "Authorization: Bearer sk-你的API令牌"
```

## 常见问题

<AccordionGroup>
  <Accordion title="模型列表看不到 AIOHub">
    确认 `/connect` 中输入的模型服务商 ID 与 `opencode.json` 的 `provider` key 完全一致，例如都使用 `aiohub`。修改配置后重启 OpenCode。
  </Accordion>

  <Accordion title="404 或路径重复">
    Base URL 填 `https://api.aiohub.org/v1`。不要填 `https://api.aiohub.org/v1/chat/completions` 或 `https://api.aiohub.org/v1/responses`。
  </Accordion>

  <Accordion title="API 令牌未生效">
    使用 `/connect` 时，确认凭据保存到同一个模型服务商 ID。使用环境变量时，先运行 `test -n "$AIOHUB_API_KEY" && echo "api key configured"`，再启动 OpenCode。
  </Accordion>

  <Accordion title="Responses 模型返回格式错误">
    确认该模型服务商使用 `@ai-sdk/openai`，不是 `@ai-sdk/openai-compatible`。如果只需要普通对话，先用 Chat Completions 模型验证基础连通性。
  </Accordion>
</AccordionGroup>

## 官方参考

* [OpenCode install](https://opencode.ai/docs)
* [OpenCode config](https://opencode.ai/docs/config)
* [OpenCode providers](https://opencode.ai/docs/providers)