# OpenCode 集成

OpenCode 是开源的终端 AI 编程助手。使用 GPT 系列模型时，推荐通过 `@ai-sdk/openai` 接入 Responses API，即 `POST /v1/responses` 协议。

配置时需要特别注意：

- `provider` 必须使用 `openai`，不要改成 `tokenflows` 或其他名称。
- 必须设置 `"setCachekey": true`，否则 GPT 模型的缓存可能失效，造成额度浪费。
- `@ai-sdk/openai` 会按 Responses API 与兼容端点通信，不需要再改成 `openai-compatible`。

## 前置条件

- **OpenCode**：如未安装，可使用 `npm install -g opencode-ai` 或参考 [OpenCode 安装文档](https://opencode.ai/docs/)。
- **API Key**：在 [TokenFlows 控制台](https://dash.tokenflows.org/) 创建一个 API Key。
- **模型 ID**：在 [模型列表](/models) 页面选择你要在 OpenCode 中使用的模型。

## 方式一：CC Switch 可视化配置

如果你已经使用 CC Switch 管理 Claude Code 或 Codex，也可以继续用它管理 OpenCode。

1. 打开 [CC Switch](https://github.com/farion1231/cc-switch/releases)。
2. 选择 `OpenCode`。
3. 新增 TokenFlows Provider：
   - API Base URL：`https://api.tokenflows.org/v1`
   - API Key：填入你的 TokenFlows API Key
   - Provider：`openai`
   - Model：填写要使用的 GPT 模型 ID
   - Cache Key：启用
4. 启用该 Provider。
5. 在项目目录运行 `opencode`，执行 `/models` 确认模型已出现。

## 方式二：手动配置

### 1. 安装 OpenCode

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

验证安装：

```bash
opencode --version
```

### 2. 找到配置文件

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

- macOS / Linux 全局配置：`~/.config/opencode/opencode.json`
- Windows 全局配置：`C:\Users\你的用户名\.config\opencode\opencode.json`
- 项目配置：项目根目录下的 `opencode.json`

如果文件不存在，可以手动创建。使用项目配置时，项目根目录下的 `opencode.json` 会覆盖同名全局配置。

### 3. 添加 Provider

在 `opencode.json` 中添加或合并以下配置，并将 `YOUR_API_KEY` 替换为你的 TokenFlows API Key：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/gpt-5.3-codex",
  "provider": {
    "openai": {
      "npm": "@ai-sdk/openai",
      "name": "TokenFlows",
      "options": {
        "baseURL": "https://api.tokenflows.org/v1",
        "apiKey": "YOUR_API_KEY",
        "setCachekey": true,
        "options": {
          "reasoningEffort": "high",
          "textVerbosity": "low",
          "reasoningSummary": "auto"
        }
      },
      "models": {
        "gpt-5.4": {
          "name": "GPT 5.4"
        },
        "gpt-5.3-codex": {
          "name": "GPT 5.3 Codex"
        }
      }
    }
  }
}
```

`models` 中的键需要与 TokenFlows 支持的模型 ID 一致。你可以按需增删 GPT 模型。

### 4. 启动 OpenCode

配置完成后重启 OpenCode。进入项目目录，运行：

```bash
opencode
```

在 TUI 中执行：

```text
/models
```

选择 `TokenFlows` 下的 GPT 模型后，即可开始使用。

## 常见问题

**Q：`/models` 中看不到 TokenFlows？**

确认配置文件位置正确、JSON 语法合法，并重启 OpenCode。注意逗号、引号和括号是否完整。

**Q：返回 401 或提示未授权？**

检查 `apiKey` 是否复制完整，确认密钥未过期且账号可正常使用。

**Q：缓存没有生效或额度消耗异常？**

确认 Provider 名称为 `openai`，并且 `options` 中包含 `"setCachekey": true`。