OpenCode CLI

This guide shows how to install and configure OpenCode CLI with WorldRouter. OpenCode is a terminal-based AI coding agent that accepts custom OpenAI-compatible providers via opencode.jsonc.

Prerequisites

Steps

1. 1Install OpenCode.
2. 2Export OPENAI_API_KEY and OPENAI_BASE_URL in your shell.
3. 3If ~/.config/opencode/opencode.jsonc does not exist yet, create it and add a WorldRouter provider.
4. 4Launch opencode, pick the WorldRouter model with /model, and send a test prompt.

Install

curl -fsSL https://opencode.ai/install | bash

After the installer finishes, verify the binary is on your PATH:

opencode --version

A successful install prints a single version line (for example, 0.x.y). If you see opencode: command not found, open a fresh terminal so the new PATH entry is picked up, or follow the installer’s manual PATH instructions.

Environment (macOS / Linux)

Add these exports to your shell profile (~/.zshrc or ~/.bashrc), or run them directly in your current session.

export OPENAI_API_KEY="your_api_key"
export OPENAI_BASE_URL="https://inference-api.worldrouter.ai/v1"

If you edited your shell profile, reload it so the new values take effect in the current terminal (or just open a fresh one).

source ~/.zshrc  # or: source ~/.bashrc

Verify the variables are set

First, confirm the values are present in the current shell — they should print your key and the WorldRouter base URL:

printenv OPENAI_API_KEY
printenv OPENAI_BASE_URL

If either command prints nothing, the variable is not set in this terminal.

Next, confirm they are also written to your shell profile so new terminals pick them up automatically. Match against ~/.zshrc (zsh) or ~/.bashrc (bash):

# Use ripgrep if you have it:
rg -n "OPENAI_API_KEY|OPENAI_BASE_URL" ~/.zshrc
# Or with grep (always installed):
grep -nE "OPENAI_API_KEY|OPENAI_BASE_URL" ~/.zshrc

• If grep prints two matching lines, the exports are persisted — every new shell will get them for free.
• If grep prints nothing, the values only live in the current terminal session. Re-open the file in your editor and add the two export lines from above so the next terminal you open also has them.

Environment (Windows PowerShell)

Set the variables for the current session.

$env:OPENAI_API_KEY = "your_api_key"
$env:OPENAI_BASE_URL = "https://inference-api.worldrouter.ai/v1"

To persist them across sessions, run setx instead and restart PowerShell.

setx OPENAI_API_KEY "your_api_key"
setx OPENAI_BASE_URL "https://inference-api.worldrouter.ai/v1"

Verify the variables are set

Confirm both values are present in the current PowerShell session:

echo $env:OPENAI_API_KEY
echo $env:OPENAI_BASE_URL

If you used setx, also open a fresh PowerShell window and re-run the same two commands — setx only takes effect in newly-spawned shells, never the one you ran it in.

OpenCode provider

OpenCode reads provider settings from a plain-text JSON file at:

• macOS / Linux: ~/.config/opencode/opencode.jsonc
• Windows: %USERPROFILE%\.config\opencode\opencode.jsonc

The first time you set up OpenCode this file (and usually the parent folder) does not exist yet — you have to create it. Open it with any plain-text editor afterwards (VS Code, Notepad, TextEdit set to Format → Make Plain Text, nano, vim, etc.).

Create the file (first-time setup)

On macOS / Linux, the easiest path is one mkdir plus one editor command:

mkdir -p ~/.config/opencode
nano ~/.config/opencode/opencode.jsonc  # or: code, vim, etc.

On Windows PowerShell:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode" | Out-Null
notepad "$env:USERPROFILE\.config\opencode\opencode.jsonc"

Paste the provider block

Inside the editor, paste the block below. Replace "your_api_key" with your WorldRouter key — OpenCode reads the key from this file rather than from OPENAI_API_KEY. If the file already had unrelated settings, add the new "worldrouter" entry under provider instead of replacing the whole file.

{
  // OpenCode configuration
  // Docs: https://opencode.ai/docs
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "worldrouter": {
      "name": "WorldRouter",
      "npm": "@ai-sdk/openai-compatible",
      "models": {
        "gpt-5.4": {
          "name": "WorldRouter gpt-5.4"
        },
        "claude-opus-4-6": {
          "name": "WorldRouter claude-opus-4-6"
        },
        "claude-sonnet-4-6": {
          "name": "WorldRouter claude-sonnet-4-6"
        }
      },
      "options": {
        "baseURL": "https://inference-api.worldrouter.ai/v1",
        "apiKey": "your_api_key"
      }
    }
  }
}

Save the file and exit the editor (in nano: Ctrl-O, Enter, Ctrl-X).

The fields you actually need to know

Most of the block is boilerplate you can paste as-is. Only three fields matter:

• options.apiKey — your WorldRouter API key. OpenCode reads it from here, not from OPENAI_API_KEY.
• options.baseURL — the WorldRouter endpoint. Must include the /v1 suffix.
• models — which WorldRouter models to expose to /model inside OpenCode. The keys must match WorldRouter model IDs exactly (case-sensitive); the name is just the cosmetic label OpenCode shows in its picker.

Add more models

The block above ships a small starter set. To use other models on WorldRouter — Gemini, Qwen, Kimi, GLM, DeepSeek, etc. — open the Models page, copy the model ID exactly (case-sensitive), and add another entry under provider.worldrouter.models. For example, to add gemini-3.1-pro-preview:

"models": {
  "gpt-5.4": { "name": "WorldRouter gpt-5.4" },
  "claude-opus-4-6": { "name": "WorldRouter claude-opus-4-6" },
  "gemini-3.1-pro-preview": { "name": "WorldRouter gemini-3.1-pro-preview" }
}

Save the file again and OpenCode will surface the new entries the next time you run /model.

Launch

This is a three-action sequence — the first one is in your terminal, the next two are inside the OpenCode TUI.

1. Start OpenCode from your project directory (in your terminal):

cd your-project
opencode

2. Once OpenCode opens, you will see its interactive prompt. Type the following slash command and press Enter:

/model

3. A model picker appears. Use the arrow keys to highlight one of the WorldRouter entries (for example, WorldRouter gpt-5.4) and press Enter to select it. OpenCode will route subsequent prompts through WorldRouter using that model.

Verify

> Reply with 'ok' if you can see this.

A short reply (typically just ok) confirms three things at once: OpenCode loaded the WorldRouter provider from opencode.jsonc, the base URL is reachable, and your API key is valid. The call shows up on the Activity dashboard within a few seconds, and your credit balance on the Credits page should drop accordingly.

If OpenCode shows an error banner instead of a reply, jump to Troubleshooting below — the most common causes are a missing or mistyped apiKey in opencode.jsonc, a model key that is not on the Models page, or a baseURL missing the /v1 suffix.

Troubleshooting

Resources