---
title: "OpenCode"
description: "在 opencode.json 里加一个 OpenAI 兼容的 pirouter provider，base URL 填 https://api.pirouter.ai/v1，OpenCode 就能用 pirouter 上的 Claude、GPT 和 Gemini，工具调用也能用。"
canonical: "https://pirouter.ai/zh/docs/integrations/opencode"
last-updated: "2026-10-18"
lang: "zh"
source: "content/docs/zh/integrations/opencode.mdx"
---

# OpenCode

在 opencode.json 里加一个 OpenAI 兼容的 pirouter provider，base URL 填 https://api.pirouter.ai/v1，OpenCode 就能用 pirouter 上的 Claude、GPT 和 Gemini，工具调用也能用。

[OpenCode](https://github.com/anomalyco/opencode) 通过自定义 provider 接入 pirouter：在 `opencode.json` 里写一个 `pirouter` provider，用 OpenAI 兼容协议，base URL 填 `https://api.pirouter.ai/v1`。Claude、GPT 和 Gemini 都接受 OpenAI 协议，一个 provider 就能覆盖这三家的模型。

## 前提

- 一个 pirouter API key。还没有的话，按[快速开始](https://pirouter.ai/zh/docs/quickstart.md)创建一个，并存进环境变量：

```bash
export PIROUTER_API_KEY="sk-pi-..."
```

- 已安装 OpenCode。本页按 OpenCode 1.18 验证，用 `opencode --version` 查看版本。

## 配置

把下面的内容存到 `~/.config/opencode/opencode.json`。只想在某个项目里用的话，存到项目根目录的 `opencode.json`。

`~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "pirouter/anthropic/claude-sonnet-5.5",
  "small_model": "pirouter/anthropic/claude-haiku-5.5",
  "provider": {
    "pirouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "pirouter",
      "options": {
        "baseURL": "https://api.pirouter.ai/v1",
        "apiKey": "{env:PIROUTER_API_KEY}"
      },
      "models": {
        "anthropic/claude-sonnet-5.5": {
          "name": "Claude Sonnet 5.5",
          "limit": { "context": 1000000, "output": 128000 }
        },
        "anthropic/claude-haiku-5.5": {
          "name": "Claude Haiku 5.5",
          "limit": { "context": 1000000, "output": 128000 }
        },
        "openai/gpt-6.1-sol": {
          "name": "GPT-6.1 Sol",
          "limit": { "context": 1050000, "output": 128000 }
        },
        "google/gemini-4-argon": {
          "name": "Gemini 4 Argon",
          "limit": { "context": 1048576, "output": 65536 }
        }
      }
    }
  }
}
```

这份配置里几项的作用：

- `npm` 填 `@ai-sdk/openai-compatible`，请求发到 `POST /v1/chat/completions`。`baseURL` 要带 `/v1`。
- `apiKey` 写成 `{env:PIROUTER_API_KEY}`，OpenCode 启动时从环境变量读 key，配置文件里不存明文。
- `models` 要逐个手写。OpenCode 不会去拉网关的模型列表，没写进来的模型在 OpenCode 里选不到。能用哪些模型，见[模型与协议](https://pirouter.ai/zh/docs/models.md#每个模型接受哪些协议)的协议表里 OpenAI 一列，图像模型不要写进来。
- 每个模型都写 `limit`：`context` 是上下文上限，`output` 是输出上限，数值和 `GET https://api.pirouter.ai/v1/models` 返回的一致。
- `small_model` 设成 Claude Haiku 5.5。OpenCode 每开一个新会话会额外发一次请求生成会话标题，这次请求用 `small_model`，不设的话就用主模型。

在 OpenCode 里，模型名写成 `pirouter/` 加 pirouter 的完整模型 ID，例如 `pirouter/anthropic/claude-sonnet-5.5`。命令行用 `-m` 指定，配置里用 `model` 指定。

工具调用在这三家模型上都能用，Gemini 4 Argon 走 OpenAI 协议同样能调用 OpenCode 的读文件工具。

## 验证

在设置了 `PIROUTER_API_KEY` 的终端里运行：

```bash
opencode run -m pirouter/anthropic/claude-sonnet-5.5 "Reply with the single word: ok"
```

你应该看到一行 `> build · anthropic/claude-sonnet-5.5`，然后是模型的回复 `ok`。

在控制台[日志](https://pirouter.ai/zh/docs/guides/logs.md)里能看到这次请求，**端点** 一栏是 `/v1/chat/completions`。旁边还会有一条 `anthropic/claude-haiku-5.5` 的请求，那是 OpenCode 生成会话标题的请求。

## 排障

### 401 invalid\_api\_key

返回 `401`，错误码 `invalid_api_key`：多半是运行 OpenCode 的终端里没有设置 `PIROUTER_API_KEY`。环境变量不存在时，`{env:PIROUTER_API_KEY}` 会被替换成空字符串，请求不带 key。先 `echo $PIROUTER_API_KEY` 确认，再重新运行。

### 用 `@ai-sdk/google` 时返回 401

不要把 `npm` 换成 `@ai-sdk/google`。这个包只把 key 放在 `x-goog-api-key` 请求头里，网关不读这个头，只读 `Authorization` 和 `x-api-key`，请求会返回 `401`。Gemini 模型留在上面的 OpenAI 兼容 provider 里即可。

### 每次请求都带 `max_tokens: 32000`

模型没写 `limit.output` 时，OpenCode 每次请求都带 `max_tokens: 32000`。没写 `limit.context` 时，长会话不会自动压缩。给每个模型都写上 `limit`，数值取 `GET https://api.pirouter.ai/v1/models` 返回的上下文上限与输出上限。

### 每个新会话多一笔旗舰模型的费用

OpenCode 每开一个新会话会额外发一次生成标题的请求。没设 `small_model` 时，这次请求用主模型，在[日志](https://pirouter.ai/zh/docs/guides/logs.md)里表现为每个会话多一条主模型的请求。把 `small_model` 设成 `pirouter/anthropic/claude-haiku-5.5` 这类便宜的模型即可。

## 相关链接

- [OpenCode](https://github.com/anomalyco/opencode)（GitHub）
- [Providers](https://opencode.ai/docs/providers/)：OpenCode 文档里自定义 provider 的写法
- [Config](https://opencode.ai/docs/config/)：配置文件的位置与变量替换
- [CLI](https://opencode.ai/docs/cli/)：`opencode run` 的参数