# OpenCode 接入 OfoxAI 配置指南

Source: https://ofox.io/zh/docs/integrations/opencode

[OpenCode](https://opencode.ai?utm=ofox_ai) 是一款开源 AI 编程智能体，提供终端 TUI、桌面客户端和 IDE 插件。**Ofox 已内置在 OpenCode 的提供商目录中**（数据来自 [models.dev](https://models.dev/providers/ofox/?utm=ofox_ai)），无需自定义 Base URL，选中 Ofox、填入 API Key 即可使用 GPT、Claude、Gemini、DeepSeek 等模型。

## 前提条件

- 已注册 OfoxAI 账号并获取 API Key（[前往获取](https://app.ofox.io/manage/api-keys)）
- 已安装 OpenCode：

```bash
# 任选其一
curl -fsSL https://opencode.ai/install | bash
npm i -g opencode-ai@latest
brew install anomalyco/tap/opencode
```

桌面客户端可在 [opencode.ai/download](https://opencode.ai/download?utm=ofox_ai) 下载。

## 方式一：桌面客户端

### 1. 打开提供商设置

打开 OpenCode，点击左侧栏的 **设置 → 提供商**，在「热门提供商」列表底部点击 **查看更多提供商**。

![设置 → 提供商](https://ofox.io/screenshots/opencode/01-providers.png)

### 2. 搜索并选择 Ofox

在搜索框输入 `ofox`，点击 **Ofox**。

![搜索 Ofox](https://ofox.io/screenshots/opencode/02-search-ofox.png)

### 3. 填入 API Key

粘贴你的 OfoxAI API Key，点击 **继续**。连接成功后，Ofox 会出现在「已连接的提供商」中。

![填入 Ofox API Key](https://ofox.io/screenshots/opencode/03-api-key.png)

### 4. 启用 Ofox 模型

进入 **设置 → 模型**，搜索 `ofox`，把需要用的模型开关打开。只有开启的模型才会出现在会话的模型选择器里。

![设置 → 模型，开启 Ofox 下的模型](https://ofox.io/screenshots/opencode/04-models.png)

### 5. 选择模型开始对话

新建会话，点击输入框下方的模型选择器，在 **Ofox** 分组下选择刚才开启的模型即可开始对话。点击底部的 **管理模型** 可随时回到第 4 步增减模型。

![在模型选择器的 Ofox 分组下选择模型](https://ofox.io/screenshots/opencode/05-select-model.png)

## 方式二：终端 TUI

在项目目录下启动 OpenCode，输入 `/connect`：

```bash
opencode
```

```text
/connect
```

在提供商列表中搜索 `Ofox` 并回车，粘贴 API Key。然后输入 `/models`，选择 Ofox 下的模型即可。

凭据保存在 `~/.local/share/opencode/auth.json`，桌面端与终端共用，只需配置一次。

也可以直接用命令行完成登录并验证：

```bash
opencode auth login          # 选择 Ofox，粘贴 API Key
opencode models ofox         # 列出 Ofox 下可用模型
opencode run -m ofox/anthropic/claude-sonnet-5.5 "你好，介绍一下你自己"
```

## 可选：环境变量与配置文件

OpenCode 会自动读取 `OFOX_API_KEY` 环境变量，适合 CI 或不想把 Key 存在本地文件里的场景：

```bash filename="~/.zshrc"
export OFOX_API_KEY=<你的 OFOXAI_API_KEY>
```

如需把 Ofox 设为默认模型，在项目根目录或 `~/.config/opencode/` 下的 `opencode.json` 中写入：

```json filename="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "model": "ofox/anthropic/claude-sonnet-5.5"
}
```

模型 ID 格式为 `ofox/<OfoxAI 模型 ID>`，完整列表见 [模型广场](https://ofox.io/zh/models)。

## 协议说明：内置提供商 vs 自定义提供商

走内置 Ofox 提供商时，**每个模型默认使用其对应的原生协议**，无需手动选择：

| 模型 | 协议 | 端点 |
| --- | --- | --- |
| Claude 系列（`anthropic/*`） | Anthropic 原生协议 | `https://api.ofox.io/anthropic/v1` |
| Gemini 系列（`google/*`） | Gemini 原生协议 | `https://api.ofox.io/gemini/v1beta` |
| GPT 系列（`openai/*`） | OpenAI 协议 | `https://api.ofox.io/v1` |
| 其他模型（DeepSeek、Qwen、GLM 等） | OpenAI 兼容协议 | `https://api.ofox.io/v1` |

如果需要**自己指定协议**——例如用 OpenAI 协议调用 Claude——就不能走内置提供商，需要添加一个自定义提供商，手动设置 Base URL、API Key 和模型。

### 在桌面客户端添加自定义提供商

**设置 → 提供商 → 查看更多提供商**，选择 **自定义 OpenAI 兼容提供商**，按下表填写后点击 **提交**：

| 字段 | 填写内容 |
| --- | --- |
| 提供商 ID | 自定义，如 `ofox-openai`（不要与内置的 `ofox` 重名） |
| 显示名称 | 自定义，如 `Ofox (OpenAI 协议)` |
| 基础 URL | `https://api.ofox.io/v1` |
| API 密钥 | 你的 OfoxAI API Key |
| 模型 | ID 填 OfoxAI 模型 ID（如 `anthropic/claude-sonnet-5.5`），名称自定义；可点击「添加模型」添加多个 |

![自定义提供商：用 OpenAI 协议接入 Claude](https://ofox.io/screenshots/opencode/06-custom-provider.png)

添加后，模型选择器里会多出一个 **Ofox (OpenAI 协议)** 分组，其中的模型都通过 OpenAI 兼容协议调用。

### 或者写在 opencode.json 中

```json filename="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ofox-openai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ofox (OpenAI 协议)",
      "options": {
        "baseURL": "https://api.ofox.io/v1",
        "apiKey": "{env:OFOX_API_KEY}"
      },
      "models": {
        "anthropic/claude-sonnet-5.5": { "name": "Claude Sonnet 5.5" }
      }
    }
  }
}
```

使用时模型 ID 写作 `ofox-openai/anthropic/claude-sonnet-5.5`。

## 推荐模型

推荐模型请参考 [模型广场](https://ofox.io/zh/models)。