# OpenCode: install, configure and troubleshoot LYRouter access

Source: https://platform.lyrouter.com/ai_gateway/docs/opencode/en
Last updated: 2026-10-14

OpenCode can connect to LYRouter as a custom model service. This page starts with the installation prerequisites, then shows how to configure the tool and make your first call.

Already installed? Go straight to [Configure LYRouter](#configure-lyrouter).

## Prerequisites

The configuration on this page applies to the CLI in the official OpenCode 1 documentation, installed with npm. OpenCode 1 and OpenCode 2 share the `opencode` command, so check the target version and any existing installation before you install.

**Choose your operating system**

Windows:
#### 1. Choose a terminal environment

OpenCode officially recommends using it in **WSL**. If you already have WSL, check it first:

```powershell
wsl --status
```

When you install in WSL, prepare the dependencies and run all later commands in the Linux terminal; do not use the Windows Node.js / npm. On native Windows you can use the official npm installation.

#### 2. Check Node.js and npm

On native Windows, first install Node.js LTS as described in [Your first model call](https://platform.lyrouter.com/ai_gateway/docs/quickstart/en), then check in PowerShell:

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

Prepare a terminal that supports interactive interfaces, network access and a writable global installation directory. On Windows, use `npm.cmd`.

Linux:
#### 1. Prepare the terminal and installation directories

Use a terminal that supports interactive interfaces with Bash, and prepare network access and readable and writable project and tool installation directories:

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

#### 2. Check Node.js and npm

Prepare Node.js LTS as described in [Your first model call](https://platform.lyrouter.com/ai_gateway/docs/quickstart/en), then check the environment that the npm installation needs:

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

If you use the native installation script, also prepare cURL as described in the [official installation guide](https://opencode.ai/docs/). The npm path on this page does not require the native script.

macOS:
#### 1. Prepare the terminal

Open a terminal that supports interactive interfaces, use Bash / Zsh, and check your system and processor architecture:

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

#### 2. Check Node.js and npm

Prepare Node.js LTS as described in [Your first model call](https://platform.lyrouter.com/ai_gateway/docs/quickstart/en), and make sure the global installation directory is writable:

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

If you choose Homebrew or another installation method, follow the [official guide](https://opencode.ai/docs/). You still need to check the OpenCode version after installation.

To connect to LYRouter you also need an enabled API key and a model available in the current workspace. Replace `MODEL_ID` in the examples with an actual system model identifier. Your tool account and your LYRouter account are two separate identities.

## Install the app

**Install for your operating system**

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
```

Reopen the terminal after installation and check the version. For other installation methods, see the official guides below.

## Configure LYRouter

First run `opencode`, then use `/connect` → Other to add the provider ID `lyrouter` with your LYRouter API key. Then create or update `~/.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" } }
    }
  }
}
```

The provider ID must match the one you entered in `/connect`. Run `/models` and choose a model under `lyrouter`. This configuration uses Chat Completions; for a Responses source, choose the matching adapter package as described in the official provider guide.

## Verify your first call

Start the app, explicitly select the model you just configured, and send a minimal task such as "Reply OK". Then check the generation endpoint, status and actual model in LYRouter's [request logs](https://platform.lyrouter.com/ai_gateway/docs/logs/en). A successful connection test does not mean that full generation or tool calling works.

## Everyday use and troubleshooting

### The command is not found after installation. What should I do?

**Answer:** Reopen the terminal, run the version check command from this page's installation steps, and check whether the installation directory is on PATH. Use the same terminal and runtime environment as in the installation steps. If it still does not work, check the installation against the official installation guide.

### The custom provider is configured, but calls fail. What should I check?

**Answer:** Check the protocol of the adapter package you chose, `baseURL`, the API key and the system model identifier. For the OpenAI-compatible configuration on this page, the address is `https://api.lyrouter.com/v1`. When you switch adapter packages, do not keep a protocol configuration that does not match.

### What should I check before switching models?

**Answer:** Make sure the new model is enabled in the current workspace, has at least one valid service source, and supports the protocol and tool capabilities the app needs. Use the system model identifier, not the display name.

### Why does my configuration stop working after an app update?

**Answer:** First check the current app version and which configuration location it actually reads, then check the provider, address, key and model against "Configure LYRouter" on this page. The official resources linked on this page define the configuration requirements of each version.

### A request returns 401 / 403. What should I check first?

**Answer:** Make sure you entered an enabled LYRouter API key, and check the model sources and access policies of the workspace the key belongs to. Use the specific error and the logs to find what rejected the request; see [401 / 403: authentication and access](https://platform.lyrouter.com/ai_gateway/docs/auth-errors/en).

### A request returns 429. Does retrying repeatedly help?

**Answer:** First find out whether a platform limit or an exhausted upstream quota caused it, then adjust concurrency, call frequency or resource configuration. Retry with bounded backoff instead of retrying immediately and repeatedly; see [429: rate limits and quotas](https://platform.lyrouter.com/ai_gateway/docs/rate-errors/en).

### The app replies, but I cannot find the request in the LYRouter logs. What should I do?

**Answer:** Make sure the LYRouter provider and model configured on this page are the ones in effect, and check the gateway address. After verifying with a minimal generation task, search the [request logs](https://platform.lyrouter.com/ai_gateway/docs/logs/en) in the correct workspace by time and key. Listing models alone does not appear in the regular call list.

## Official resources

The requirements and installation methods below come from the tool's official documentation. For later versions, the official instructions take precedence.

- [Installation guide](https://opencode.ai/docs/)
- [Custom providers](https://docs.opencode.ai/docs/providers/)
- [Configuration locations](https://docs.opencode.ai/docs/config/)