opencode 配置教程（接入中转站）

# opencode 配置教程（接入中转站）

> **适用对象**：想在终端里用 opencode 写代码，但模型走中转站而不是 Anthropic 官方  
> **中转站地址**：`https://api.zaimod.com`  
> **接口链路**：`POST /v1/messages`（Anthropic 原生协议）  
> **目标**：改一个 `baseURL`、放一个令牌，启动后 `/models` 里能选到 Claude，提问有正常回复

---

## 一、这篇教程在讲什么

原文只有 1094 个字符、4 张截图，讲两件事：**改 `baseURL` 指向中转站**、**把令牌放进 `auth.json`**，然后启动、`/models` 选模型。

![打开终端并输入 opencode](images/opencode/618577.png)

准确地说，opencode 的配置被拆成了两个文件，各管一件事：

| 文件              | 管什么                                  | 原文给的路径                              |
| --------------- | ------------------------------------ | ----------------------------------- |
| `opencode.json` | **地址**：把 anthropic 提供者的 `baseURL` 换掉 | `~/.config/opencode/opencode.json`  |
| `auth.json`     | **密钥**：存各提供者的 API Key                | `~/.local/share/opencode/auth.json` |

`~` 在 Windows 上就是 `C:\Users\你的用户名`（原文举的例子是 `C:\Users\admin`）。所以这两个文件在 Windows 上分别是：

```
C:\Users\你的用户名\.config\opencode\opencode.json
C:\Users\你的用户名\.local\share\opencode\auth.json
```

> **⚠️ 两个目录默认都不存在，必须自己建**  
> 原文写「没有这个文件就新建」，但没说 `.config` 和 `.local` 这两层目录本身也不存在。在资源管理器里直接新建文件会失败——要先建文件夹，或者用命令一次建好（见第四节）。

---

## 二、先说结论：原文那个 `/v1` 是对的，但别和 Claude Code 教程互抄

原文的地址是**带 `/v1`** 的写法（完整对照见附录 B）。这个写法在 `api.zaimod.com` 上同样正确，我在本站实测过：

| 请求                               | 结果                  | 说明             |
| -------------------------------- | ------------------- | -------------- |
| `POST /v1/messages`              | `401 Invalid token` | 路径存在，只差鉴权 ✅    |
| `POST /v1/messages/count_tokens` | `404 Invalid URL`   | 上游未实现，正常流程不会用到 |
| `POST /v1/v1/messages`           | `404`               | 多写一段版本号就会这样    |

**为什么 opencode 要带、而 Claude Code 不用带？** 因为「谁负责拼 `/v1/messages`」不同：

| 客户端          | 要填的字段                                | 该填什么                                        | 谁拼后半段                  |
| ------------ | ------------------------------------ | ------------------------------------------- | ---------------------- |
| **opencode** | `provider.anthropic.options.baseURL` | `https://api.zaimod.com/v1`                  | 客户端只补 `/messages`      |
| Claude Code  | `ANTHROPIC_BASE_URL`                 | `https://api.zaimod.com`                     | SDK 自己补 `/v1/messages` |
| 沉浸式翻译        | 自定义 API 地址                           | `https://api.zaimod.com/v1/chat/completions` | 谁都不补                   |

opencode 官方文档里 `baseURL` 的默认值就写成 `https://api.anthropic.com/v1`，说明这一段是**由你提供的**。所以看到别的教程让 Claude Code 填纯域名，别照搬过来——那会变成 `/v1/v1/messages`。

---

## 三、开工之前

| 项目      | 要求                                                     |
| ------- | ------------------------------------------------------ |
| Node.js | 20 LTS 及以上（npm 用来自动装对应平台的二进制）                          |
| 终端      | Windows 用 PowerShell 即可（截图里就是 Windows PowerShell）      |
| 中转站令牌   | 在控制台新建，**分组要选 Claude 相关的**（如 `claude 专属`）              |
| 磁盘      | 约 200 MB（npm 包按平台分包，会拉 `opencode-windows-x64` 之类的二进制包） |

**令牌一定要选对分组**。中转站的令牌绑定分组，Claude 分组才能调 Claude 模型；拿一个 GPT 分组的令牌去配 anthropic，结果是一路 `401`，看起来像地址填错了，其实跟地址无关。

---

## 四、步骤 1 · 安装 opencode

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

装完验证：

```bash
opencode --version
```

能打印版本号就成功。**如果提示"无法将 opencode 项识别为 cmdlet"**，说明 npm 的全局 bin 目录不在 PATH 里，先看它在哪：

```bash
npm config get prefix
```

把输出路径（Windows 上通常是 `C:\Users\你的用户名\AppData\Roaming\npm`）加进系统 PATH，然后**重开一个终端**。

> **⚠️ 两个常见卡点**
>
> 1. **换过 npm 镜像的机器**：npm 包本身很小，真正的二进制在 `opencode-windows-x64` 这类平台分包里，由 `postinstall` 脚本拉取。镜像如果没同步这些分包，`npm install` 会卡住或报 `postinstall` 失败——这时临时切回官方源再装一次通常就好。
> 2. **装完不生效**：Windows 的 PATH 改动只对新开的终端生效，老窗口里永远找不到命令。

---

## 五、步骤 2 · 写地址：`opencode.json`

### 5.1 建目录、建文件

PowerShell 里一条命令搞定（不用手动一层层建文件夹）：

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\opencode" | Out-Null
```

然后在里面新建 `opencode.json`。**用记事本另存时，文件名要带引号**：

```powershell
notepad "$env:USERPROFILE\.config\opencode\opencode.json"
```

不加引号的话，记事本会自动补 `.txt`，你得到的是一个叫 `opencode.json.txt` 的文件——opencode **读不到，也不报错**，表现为"配置明明改了却没生效"。这是本篇最高频的踩坑点。

### 5.2 内容

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.zaimod.com/v1"
      }
    }
  }
}
```

三个要点：

- **`baseURL` 结尾不要加斜杠**。`.../v1/` 有的客户端会拼成 `//messages`。
- **不能写注释**。这是 `.json` 不是 `.jsonc`；写 `// 中转站` 直接解析失败。想加注释就把文件改名成 `opencode.jsonc`（opencode 两种都认，注释在 jsonc 里合法）。
- **别把文件路径写进 JSON 里**。原文的代码块是这样：
  ```
  ~/.config/opencode/opencode.json

{
    "$schema": ...
  }
  ```
  照着复制会得到一个以 `~/.config/...` 开头的非法文件。原文的路径应该当作**标题**看，不是文件内容的一部分（这条在附录 A 第 1 条）。

### 5.3 想固定默认模型（可选）

在同一个文件里加一行，省掉每次启动都要选模型：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.zaimod.com/v1"
      }
    }
  }
}
```

格式是 `提供者ID/模型ID`。

---

## 六、步骤 3 · 放密钥：三种写法，选一种

原文是**手写 `auth.json`**。它能用，但不是最稳的一种，先看三种方式的区别：

| 方式             | 怎么做                                 | 适合                        |
| -------------- | ----------------------------------- | ------------------------- |
| **A. 交互式（推荐）** | 启动后输入 `/connect`，搜 `Anthropic`，粘贴令牌 | 大多数人；opencode 自己写文件，格式不会错 |
| **B. 命令行**     | `opencode auth login`，交互同上          | 不想进 TUI、或在远程机器上配          |
| **C. 手写文件**    | 直接编辑 `auth.json`（原文做法）              | 批量部署；但要自己保证 JSON 严格合法     |

方式 A/B 的密钥同样落在 `~/.local/share/opencode/auth.json`，和手写是同一个文件。

![输入 /models 打开命令面板](images/opencode/618580.png)

### 6.1 手写 `auth.json`（原文方式）

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.local\share\opencode" | Out-Null
notepad "$env:USERPROFILE\.local\share\opencode\auth.json"
```

内容最少只需要这一段：

```json
{
  "anthropic": {
    "type": "api",
    "key": "sk-这里换成你中转站的令牌"
  }
}
```

> **⚠️ 原文那份示例里多了一个 `google` 条目**  
> 原文写的是：
>
> ```json
> {
>   "google": { "type": "api", "key": "1111111111111111111" },
>   "anthropic": { "type": "api", "key": "sk-xxxxxxxxxxxxx" }
> }
> ```
>
> 那串 `1111...` 是占位符，不是真令牌。整段复制过去，opencode 会认为你已经登录了 Google，`/models` 里凭空多出一串 Gemini 模型，选中就报错。**用不到的直接删掉**——`auth.json` 里只留你真正要用的提供者。

### 6.2 校验写对了没有

```bash
opencode auth list
```

能列出 `anthropic` 就说明文件被正确读取了。这条命令比"重启试试"有效得多——**文件路径错、JSON 语法错、字段名错，三种情况都表现为"没登录"，而这一条命令能立刻区分**。

> **安全提示**：`auth.json` 是**明文**。不要把整个 `.local` 目录提交进 Git，也不要丢进同步盘。另外，之后任何一次 `/connect` 或 `opencode auth login` 都会**整个重写**这个文件——手改的内容可能被覆盖，这是原文没说的一个隐患。

---

## 七、步骤 4 · 启动，选模型

```bash
opencode
```

进去后输入 `/models` 打开选择器：

![模型选择器里的 Anthropic 分组](images/opencode/618581.png)

选 `Anthropic` 分组下的任一 Claude 模型即可。列表里有个 `Recent` 分区（最近用过的），还有 opencode 自家的 `OpenCode Zen`（标注 `Free`），跟中转站无关，别选错。

选中后底部状态栏会显示当前模型，例如 `Build  Claude Opus 4  Anthropic`。

![正常对话与代码输出](images/opencode/618584.png)

上图是跑通之后的样子：左上角是会话标题与时间戳，右上角是 `14,748  7% ($0.57)`——分别是**上下文用量、占用比例、估算成本**。

> **⚠️ 那个 `$0.57` 不是你的账单**  
> opencode 用模型目录里**官方定价**× token 数算出来的，它不知道中转站的实际倍率。看余额请以中转站控制台为准，这个数字只能当"这次对话花了多少 token"的参考。

---

## 八、步骤 5 · 验收

三步，从底层到界面：

**① 直连测接口**（PowerShell 里必须写 `curl.exe`，直接写 `curl` 会走到 `Invoke-WebRequest` 的别名上，参数全不对）：

```powershell
curl.exe https://api.zaimod.com/v1/messages -H "x-api-key: sk-你的令牌" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d "{\"model\":\"claude-sonnet-4-5\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}"
```

- 回一段 `{"content":[...]}` → 令牌和分组都没问题，问题一定在客户端配置
- 回 `401 Invalid token` → 令牌错 / 分组不含该模型 / 令牌来自旧域名
- 回 `404 Invalid URL` → 路径写错了（少 `/v1` 或多 `/v1`）
- 回 `model not found` → 令牌对，但你的分组里没有这个模型 ID

**② 看 opencode 认到了哪些提供者**：`opencode auth list`

**③ 发一句话**：在 TUI 里随便问一句，能出字就通了。想不开 TUI 也可以：

```bash
opencode run "用一句话说明你是什么模型"
```

**最可靠的验收还是在控制台**：调一次，去中转站后台看调用记录有没有新增。有记录 = 请求确实走的中转站；没记录 = 你的配置没生效，界面上的"能聊"可能发生在别处。

---

## 九、可选 · 想把 GPT / Gemini 也接进来

opencode 的 `provider` 是按提供者配的，改 `anthropic` 只影响 Claude。要用同一台中转站的 GPT 模型，再覆盖 `openai` 的地址即可：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": { "options": { "baseURL": "https://api.zaimod.com/v1" } },
    "openai":    { "options": { "baseURL": "https://api.zaimod.com/v1" } }
  }
}
```

然后 `/connect` 里选 `OpenAI`，粘**同一个**中转站令牌。

> **⚠️ 令牌分组决定能调什么**  
> 中转站的令牌绑定分组。一个 `claude 专属` 分组的令牌，配到 `openai` 提供者下并不会让 GPT 变得可用——请求会以 `401` 或"无可用渠道"结束。要跨厂商，就在控制台为对应分组**各建一个令牌**。

---

## 十、常见问题

**Q1：`/models` 里选到的模型，一问就报 `model not found`。**  
opencode 的模型列表来自 models.dev 的**通用目录**（ID 形如 `claude-sonnet-4-5`），不是你中转站分组里的实际清单。先用 `curl.exe https://api.zaimod.com/v1/models -H "Authorization: Bearer sk-你的令牌"` 看真实 ID，如果带日期后缀（如 `claude-sonnet-4-5-20250929`），就在配置里做一层映射：

```json
{
  "provider": {
    "anthropic": {
      "options": { "baseURL": "https://api.zaimod.com/v1" },
      "models": {
        "claude-sonnet-4-5": { "id": "claude-sonnet-4-5-20250929" }
      }
    }
  }
}
```

**Q2：配置改了，重启还是走官方。**  
按概率排：① 文件存成了 `opencode.json.txt`；② 目录是 `.config`，不是 `AppData\Roaming\opencode`；③ 当前项目根目录里也有一个 `opencode.json`，**项目级优先级更高**，把你改的盖掉了；④ JSON 里有注释导致整份文件解析失败。

**Q3：一进 TUI 就在后台报错，但对话是好的。**  
多半是 `small_model`（生成会话标题用的小模型）在你分组里不存在。默认会挑同提供者下更便宜的模型，挑不到就回落到主模型，但中间那次请求会失败。想干净点，显式指定：

```json
{ "small_model": "anthropic/claude-haiku-4-5" }
```

前提是这个模型你的分组里有。

**Q4：`/connect` 里让选 Claude Pro/Max，我该选哪个？**  
选 **API key**。opencode 从 1.3.0 起移除了内置的 Claude Pro/Max 订阅插件（官方明确禁止把订阅用于第三方客户端），老教程里那套 OAuth 登录已经走不通了。

**Q5：模型列表一直转圈／拉不下来。**  
opencode 启动时要拉 models.dev 的目录。网络不稳时可以用本地缓存绕过：

```powershell
$env:OPENCODE_MODELS_PATH="C:\path\to\models.json"
```

或直接关掉远端拉取：`$env:OPENCODE_DISABLE_MODELS_FETCH="true"`。

**Q6：每次启动都提示更新，还打断当前操作。**  
`$env:OPENCODE_DISABLE_AUTOUPDATE="true"`。升级建议手动做，别在赶活的时候被它打断。

---

## 附录 A · 原文勘误

| #  | 原文写法                                                  | 问题                                                        | 本版处理                        |
| -- | ----------------------------------------------------- | --------------------------------------------------------- | --------------------------- |
| 1  | 代码块第一行是 `~/.config/opencode/opencode.json`，下面直接跟 JSON | 路径和内容混在一个块里，整段复制即语法错误                                     | 路径改成小节标题，代码块只放 JSON         |
| 2  | "配置两个地方"没说是全局还是项目级                                    | 项目级 `opencode.json` 优先级更高，读者会以为改完就生效                      | 明确"全局配置"，并说明项目级会覆盖          |
| 3  | `auth.json` 示例里带 `google` + `1111111111111111111`     | 占位符被当成真令牌，凭空多出一串不可用的 Gemini 模型                            | 只保留 `anthropic` 一条，并点名这是占位符 |
| 4  | 未提 `auth.json` 是明文、且会被 `/connect` 重写                  | 手改内容可能在下次登录时被覆盖，排查时极易误判                                   | 第 6.2 节加安全提示                |
| 5  | "没有这个文件就新建"                                           | `.config` / `.local` 这两层目录本身不存在，资源管理器里建不了文件               | 给出 `New-Item -Force` 一条命令   |
| 6  | 未提记事本会存成 `.json.txt`                                  | 最常见的"配置不生效"原因，且完全无提示                                      | 第 5.1 节强调文件名加引号             |
| 7  | 未说明 `baseURL` 为什么带 `/v1`                              | 读者照 Claude Code 教程填纯域名 → `/v1/v1/messages` → 404          | 第二节给三派系对照表                  |
| 8  | 未提 JSON 不能写注释                                         | 加一行 `// 中转站` 整份配置失效                                       | 说明需要注释请改用 `.jsonc`          |
| 9  | 未提模型列表来自 models.dev 而非中转站                             | 选到分组里没有的模型，报错像是"地址错了"                                     | Q1 给映射写法                    |
| 10 | 未提 `small_model` 会额外发一次请求                             | 后台静默失败，日志里一堆看不出原因的错                                       | Q3                          |
| 11 | 未提成本显示按官方定价算                                          | 读者以为 `$0.57` 是真扣费                                         | 第七节加提示                      |
| 12 | 未提版本差异                                                | 截图是 `v1.1.36`（2026-01）；当前 `1.19.x`，1.3.0 起移除了 Claude 订阅插件 | Q4                          |
| 13 | 没有验收方法                                                | 只能靠"感觉通了"                                                 | 第八节给四类返回值的含义 + 控制台对账        |
| 14 | 标题层级从 `###` 直接跳到 `######`                             | 结构塌陷，`#####` 与 `######` 混用导致目录层级看不出主次                     | 重排为 5 个步骤 + FAQ + 附录        |
| 15 | 只教手写 `auth.json`                                      | 漏了官方推荐的 `/connect` 与 `opencode auth login`                | 第六节给三种方式对比                  |

> **另外记一笔**：opencode 的 GitHub 仓库已从 `sst/opencode` **301 跳转**到 `anomalyco/opencode`。照老链接找源码、提 issue 会被跳转，不影响使用，但提 issue 前先确认自己在哪个仓库。

---

## 附录 B · 地址对照与迁移提示

| 项目                        | 原地址                         | 现地址                        |
| ------------------------- | --------------------------- | -------------------------- |
| Anthropic 接口基址（`baseURL`） | `https://api.openlux.ai/v1` | `https://api.zaimod.com/v1` |
| 实际请求路径                    | `POST /v1/messages`         | `POST /v1/messages`（不变）    |
| 令牌                        | 旧站控制台生成                     | `api.zaimod.com` 控制台重新生成    |

> **迁移提示**：旧站令牌在新域名下一律 `401 Invalid token`，必须重新生成。另外别忘了**新令牌要选 Claude 相关分组**——分组错了同样 401，但报错文字一模一样，很容易误判成地址没改对。

上一篇：n8n工作流：本地图片生成视频{else}上一篇：没有了下一篇：Node.js 环境安装教程{else}下一篇：没有了