# OpenCode 接入 LYRouter：安装、配置与故障排查

来源: https://platform.lyrouter.com/ai_gateway/docs/opencode
更新日期: 2026-10-13

OpenCode 可以通过自定义模型服务接入 LYRouter。本文从安装前提开始，说明如何配置并完成第一次调用。

已安装应用？直接查看[配置 LYRouter](#配置-lyrouter)。

## 前提条件

本页配置适用于官方 OpenCode 1 文档中的 CLI，使用 npm 安装。OpenCode 1 与 OpenCode 2 共用 `opencode` 命令，安装前先确认目标版本与已有安装。

**选择操作系统**

Windows:
#### 1. 选择终端环境

官方推荐在 **WSL** 中使用 OpenCode。已有 WSL 时可先检查：

```powershell
wsl --status
```

在 WSL 中安装时，依赖和后续命令均在 Linux 终端准备，不使用 Windows 的 Node.js / npm。原生 Windows 可使用官方提供的 npm 安装方式。

#### 2. 检查 Node.js 与 npm

原生 Windows 用户先按[快速开始](https://platform.lyrouter.com/ai_gateway/docs/quickstart)安装 Node.js LTS，然后在 PowerShell 中检查：

```powershell
node --version
npm.cmd --version
npm.cmd config get prefix
```

准备支持交互界面的终端、联网环境及可写的全局安装目录；Windows 使用 `npm.cmd`。

Linux:
#### 1. 准备终端与安装目录

使用支持交互界面的终端和 Bash，准备联网环境、可读写的项目与工具安装目录：

```bash
cat /etc/os-release
uname -m
```

#### 2. 检查 Node.js 与 npm

按[快速开始](https://platform.lyrouter.com/ai_gateway/docs/quickstart)准备 Node.js LTS，再检查 npm 安装所需环境：

```bash
node --version
npm --version
npm config get prefix
```

采用原生安装脚本时，另按[官方安装指南](https://opencode.ai/docs/)准备 cURL；本页 npm 路径不要求先使用原生脚本。

macOS:
#### 1. 准备终端

打开支持交互界面的终端，使用 Bash / Zsh，并确认系统与处理器架构：

```bash
sw_vers -productVersion
uname -m
```

#### 2. 检查 Node.js 与 npm

按[快速开始](https://platform.lyrouter.com/ai_gateway/docs/quickstart)准备 Node.js LTS，确认全局安装目录可写：

```bash
node --version
npm --version
npm config get prefix
```

若选择 Homebrew 或其他安装方式，按[官方指南](https://opencode.ai/docs/)操作；安装后仍需核对 OpenCode 版本。

接入 LYRouter 还需要一把已启用的 API Key 和当前工作空间可用的模型。示例中的 `MODEL_ID` 必须替换为实际系统模型标识；工具账号与 LYRouter 账号是两个独立身份。

## 安装应用

**按系统安装**

Windows PowerShell:
```powershell
npm.cmd install -g opencode-ai
opencode --version
```

Linux / WSL:
```bash
npm install -g opencode-ai
opencode --version
```

macOS:
```bash
npm install -g opencode-ai
opencode --version
```

安装后重新打开终端并检查版本。采用其他安装方式时，参见下方官方指南。

## 配置 LYRouter

先运行 `opencode`，通过 `/connect` → Other 添加提供商 ID `lyrouter` 及 LYRouter API Key。随后创建或更新 `~/.config/opencode/opencode.json`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lyrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LYRouter",
      "options": { "baseURL": "https://api.lyrouter.com/v1" },
      "models": { "MODEL_ID": { "name": "MODEL_ID" } }
    }
  }
}
```

提供商 ID 必须与 `/connect` 一致。运行 `/models` 选择 `lyrouter` 下的模型。此配置使用 Chat Completions；若使用 Responses 来源，按官方提供商指南选择对应适配包。

## 验证首次调用

启动应用，显式选择刚配置的模型，发送“请回复 OK”这样的最小任务。再到 LYRouter 的[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)检查生成端点、状态和实际模型。连接测试成功不等于完整生成或工具调用已通过。

## 日常使用与故障排查

### 安装后提示找不到命令，怎么办？

**答：** 重新打开终端，执行本页安装步骤中的版本检查命令，并核对安装目录是否在 PATH 中。使用与安装步骤一致的终端和运行环境；仍不可用时，按官方安装指南检查安装结果。

### 自定义提供商配置了却调用失败，应该检查什么？

**答：** 核对所选适配包对应的协议、`baseURL`、API Key 和系统模型标识。本页 OpenAI 兼容配置的地址是 `https://api.lyrouter.com/v1`；切换适配包时不能沿用不匹配的协议配置。

### 切换模型前需要检查什么？

**答：** 确认新模型已在当前工作空间启用、至少有一个有效服务来源，并支持应用所需的协议和工具能力。使用系统模型标识，不使用展示名称。

### 应用更新后，原来的配置为什么不生效？

**答：** 先核对当前应用版本和实际读取的配置位置，再对照本页“配置 LYRouter”检查提供商、地址、密钥和模型。不同版本的配置要求以本页链接的官方资料为准。

### 请求返回 401 / 403，应该先检查什么？

**答：** 确认填写的是已启用的 LYRouter API Key，并检查该 Key 所属工作空间的模型来源与访问策略。结合具体错误和日志判断拒绝来源，详见[鉴权与权限 FAQ](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)。

### 请求返回 429，反复重试有用吗？

**答：** 先确认是平台限制还是上游额度耗尽，再调整并发、调用频率或资源配置。使用有上限的退避重试，避免立即密集重试，详见[限流与配额 FAQ](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。

### 应用有回复，但 LYRouter 日志里找不到请求，怎么办？

**答：** 确认当前生效的是本页配置的 LYRouter 提供商和模型，并核对网关地址。用最小生成任务验证后，在正确工作空间按时间和 Key 查询[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)。仅拉取模型列表不会出现在普通调用列表中。

## 官方资料

下列要求和安装方式来自工具官方资料，后续版本以官方说明为准。

- [安装指南](https://opencode.ai/docs/)
- [自定义提供商](https://docs.opencode.ai/docs/providers/)
- [配置位置](https://docs.opencode.ai/docs/config/)