OpenCode 第三方 API 渠道接入配置详解

OpenCode 第三方 API 渠道接入配置详解

# OpenCode 第三方 API 渠道接入配置详解

本文档旨在说明如何将符合 **OpenAI 接口规范**的第三方中转服务（API Proxy）集成至 OpenCode 环境中。

## 0. 环境准备

确保你的 OpenCode CLI 环境已就绪（版本建议更新至最新）：

```bash
pnpm install -g @opencode/cli
```

## 1. 凭证注册（CLI 侧）

在修改配置文件前，需先在本地密钥管理器中注册一个服务商别名（Provider ID）。这一步是为了安全地托管 API Key，避免在配置文件中明文硬编码。

1. 执行认证指令：
```bash
opencode auth login
```

2. **选择类型**：在列表中定位并选中底部的 **`other`**(可以直接打字搜索)。
3. **定义 ID**：输入一个自定义标识符（例如 `local`）。
4. **录入密钥**：输入你的中转站 API Key（sk-xxxx）。

## 2. 路由配置（JSON 侧）

OpenCode 通过 `opencode.json` 文件来解析服务商参数。请根据你的操作系统定位并新建/编辑该文件。

**配置文件路径：**

* **Linux / macOS**: `~/.config/opencode/opencode.json`
* **Windows**: `%USERPROFILE%\.config\opencode\opencode.json`

**配置模版：**

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "local",
      "options": {
        "baseURL": "http://localhost:8317/v1",
      },
      "models": {
        "gpt-4o": { "name": "GPT-4o" },
        "claude-3-5-sonnet": { "name": "Claude 3.5 Sonnet" }
      }
    }
  }
}
```

### 参数映射详解

| 参数节点 | 说明 |
| --- | --- |
| **根键名** (`custom_proxy`) | **必须**与 CLI 注册时的 **Provider ID** 完全一致（大小写敏感）。 |
| **npm** | 固定使用 `@ai-sdk/openai-compatible` 以适配通用协议。 |
| **baseURL** | 填写中转站的 API 接入点，通常需包含 `/v1` 后缀。 |
| **apiKey** | 使用 `"{cred:ID}"` 语法。系统会自动从本地凭证库中提取对应 ID 的密钥，实现无明文配置。 |
| **models** | 需手动声明中转站支持的模型列表，键名（Key）需对应真实的 Model ID。 |

## 3. 加载与验证

配置完成后，重启客户端以加载新的映射关系。

1. 启动主程序：
```bash
opencode
```

2. 在交互栏输入指令调出模型菜单：
```text
/models
```

3. 若配置无误，你将在列表中看到自定义的“私有中转节点”及其模型。

## 🛠 排错核对清单

* [ ] **ID 锚点检查**：JSON 中的键名是否与 `opencode auth login` 时输入的 Provider ID 字面量完全相等？
* [ ] **接口路径**：`baseURL` 是否正确？部分中转站可能不需要 `/v1`，或者需要特定的路径前缀，请先使用 Curl 或 Postman 验证 `/v1/models` 接口连通性。
* [ ] **模型映射**：`models` 下定义的模型 ID 是否存在于你的中转商套餐中？
* [ ] **缓存清理**：若修改未生效，请尝试彻底关闭终端进程后再次启动。