OpenCode
Add RouterPlex as a custom provider in OpenCode.
On this page
Set it up with your coding agent
Paste your key into the prompt's key field, then copy the prompt into Claude Code, Codex, Cursor, or any coding agent. It configures the tool and keeps testing until a real request goes through RouterPlex, fixing environment problems along the way. Prefer to do it by hand? Follow the manual setup below; your key fills those commands too.
Optional. It stays in this browser tab and is never saved or sent. No key yet? Create one in guided setup.
Set up OpenCode on this machine to use RouterPlex, an OpenAI- and Anthropic-compatible AI gateway. Keep working until a real request from OpenCode succeeds through RouterPlex.My RouterPlex API key: YOUR_ROUTERPLEX_API_KEYKey handling:- If the key line above is a placeholder rather than a real key (real keys start with sk-), use my ROUTERPLEX_API_KEY environment variable. If that is empty too, ask me for the key once, then continue.- Store the key only in user-level config or my user environment. Never put it in a project file, never commit it, and do not repeat the full key in your replies (show at most its first 8 characters).Config handling:- Before changing an existing config file or shell startup file, copy it to a .bak file next to it and show me the diff. Merge into what is there; never replace my other settings, providers, or MCP servers.- If a step needs something only I can do, such as a click in a settings window, print the exact steps instead of guessing.Full guide: https://docs.routerplex.com/opencodeStep 1. Prove the key and the RouterPlex gateway work before changing anything else. Run:curl -sS https://api.routerplex.com/v1/chat/completions -H "Authorization: Bearer YOUR_ROUTERPLEX_API_KEY" -H "Content-Type: application/json" -d '{"model":"claude-sonnet-4-6","max_tokens":32,"messages":[{"role":"user","content":"Reply with exactly: RouterPlex connected."}]}'On Windows PowerShell, use curl.exe with the body in a file, or Invoke-RestMethod.- A reply containing "RouterPlex connected.": go on.- 401: the key is wrong or revoked. Stop and ask me for a correct key.- 402: my balance or trial credit is used up. 403: this key reached its own spending limit. Stop and tell me; retrying cannot fix these.- Network, DNS, TLS, or proxy errors: find and fix the cause (proxy variables, VPN, firewall, system clock, outdated CA certificates), then run it again.Step 2. Configure OpenCode:- Run opencode --version (opencode.cmd for Windows npm installs). If OpenCode is missing, install it (curl -fsSL https://opencode.ai/install | bash; Windows: npm.cmd install -g opencode-ai).- Merge this into my user-level ~/.config/opencode/opencode.json (Windows: %USERPROFILE%\.config\opencode\opencode.json; use $XDG_CONFIG_HOME/opencode if XDG_CONFIG_HOME is set). Keep my other providers:{"$schema": "https://opencode.ai/config.json","model": "routerplex/claude-sonnet-4-6","small_model": "routerplex/claude-sonnet-4-6","provider": {"routerplex": {"npm": "@ai-sdk/openai-compatible","name": "RouterPlex","options": {"baseURL": "https://api.routerplex.com/v1","apiKey": "{env:ROUTERPLEX_API_KEY}"},"models": {"claude-sonnet-4-6": {"name": "claude-sonnet-4-6","limit": {"context": 1000000,"output": 64000},"cost": {"input": 3,"output": 15,"cache_read": 0.25}}}}}}- Make ROUTERPLEX_API_KEY permanent for my user so new terminals get it:- macOS/Linux: add export ROUTERPLEX_API_KEY='<key>' (keep the word export: a plain ROUTERPLEX_API_KEY=... line is invisible to programs started from the shell) to the startup file of the shell I use (check $SHELL: zsh uses ~/.zshrc; bash uses ~/.bashrc, plus ~/.bash_profile or ~/.profile if they do not source ~/.bashrc). Update an existing line instead of adding a second one.- Windows: run [Environment]::SetEnvironmentVariable('ROUTERPLEX_API_KEY', '<key>', 'User'). Only terminals and apps started after this see it.- WSL, SSH, or a dev container: set it inside that environment, where the tool actually runs.- For every model I add, fill limit (context = context_tokens, output = max_output_tokens) and cost (input_per_1m, output_per_1m, cache_read_per_1m, in USD per million tokens) from https://routerplex.com/api/models. OpenCode cannot look these up for a custom provider; without them it never compacts in time and shows $0 spend.- If the variable still does not reach OpenCode, replace {env:ROUTERPLEX_API_KEY} with the key itself in that user-level file.Step 3. Test OpenCode itself from a new terminal or a restarted app, so you test the saved setup rather than the shell you changed:From an empty temporary folder: opencode run --model 'routerplex/claude-sonnet-4-6' 'Reply with exactly: RouterPlex connected. Do not read files or run tools.'The first run may download the provider adapter.Expected reply: "RouterPlex connected."Step 4. If step 1 works but step 3 fails, the problem is OpenCode's configuration or environment, not RouterPlex. Check these, fix what is wrong, and repeat step 3:- The key or base URL is set in one place but not where OpenCode starts: zsh vs bash startup files, login vs non-login shells, a desktop launcher, a background service, Windows vs WSL, or a remote SSH or container environment.- Another setting wins: OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_API_BASE, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, or a project-level config that overrides the user-level one.- OpenCode is outdated, or still needs a full restart to read the new settings.- If an environment variable cannot be made to reach OpenCode reliably and OpenCode accepts a key in its user-level config, put the key there instead.Keep repeating steps 3 and 4 until the test reply comes back.Step 5. The test above sends no tools, but real sessions send every tool, MCP server, and plugin schema with each request, and that is where models differ. From a folder with a README.md (create a temporary one containing "# RouterPlex tool check" if needed), run:opencode run --model routerplex/claude-sonnet-4-6 "List your available tools, then read ./README.md and reply with its first heading."It passes when the reply lists the tools and quotes the heading. If it fails while step 3 passes, the tool schemas are the problem, not the connection. Tell me the exact error; the chosen model may not handle OpenCode's tools, so suggest another tool-capable model from https://routerplex.com/models.Stop early only for a 401, 402, or 403, or for a step only I can do, such as a click in a settings window or a login. Then tell me exactly what to do, wait for me, and continue testing afterwards.When it works, tell me exactly which files you changed and which values you set (key shown by its first 8 characters only) so I can undo it, where the key is stored, and the final test output. Remind me that every request shows up in https://routerplex.com/dashboard/usage.
Manual setup
Use RouterPlex as a custom OpenAI-compatible provider in OpenCode. The configuration is shared with guided setup.
1. Install
macOS / Linux
curl -fsSL https://opencode.ai/install | bash
Windows PowerShell
Install Node.js LTS first if needed, then:
npm.cmd install -g opencode-ai
Reopen your terminal and run opencode --version, or opencode.cmd --version for the Windows npm install. The .cmd launcher avoids PowerShell script-policy errors.
2. Save the configuration
- macOS/Linux:
~/.config/opencode/opencode.json - Windows:
%USERPROFILE%\.config\opencode\opencode.json - If
XDG_CONFIG_HOMEis set, use itsopencodedirectory instead.
Create the folder if needed. Merge this into the existing file; keep other providers.
{"$schema": "https://opencode.ai/config.json","model": "routerplex/claude-sonnet-4-6","small_model": "routerplex/claude-sonnet-4-6","provider": {"routerplex": {"npm": "@ai-sdk/openai-compatible","name": "RouterPlex","options": {"baseURL": "https://api.routerplex.com/v1","apiKey": "{env:ROUTERPLEX_API_KEY}"},"models": {"claude-sonnet-4-6": {"name": "claude-sonnet-4-6","limit": {"context": 1000000,"output": 64000},"cost": {"input": 3,"output": 15,"cache_read": 0.25}}}}}}
The @ai-sdk/openai-compatible adapter uses Chat Completions. OpenCode cannot look up a custom provider's models, so set limit and cost yourself for each model you add. Take limit.context from context_tokens and limit.output from max_output_tokens in the public catalog. Take cost from the same entry's input_per_1m, output_per_1m, and cache_read_per_1m, in USD per million tokens. Without limit, OpenCode cannot tell when to compact a long session. Without cost, it shows $0 spend. Both model and small_model point at the selected route, including background work. The config reads the key from your environment, so /connect is unnecessary for this example. A project opencode.json can override global settings.
3. Set your key and test
Replace YOUR_ROUTERPLEX_API_KEY with your key and use an empty folder for the first test.
macOS / Linux
export ROUTERPLEX_API_KEY='YOUR_ROUTERPLEX_API_KEY'opencode run --model 'routerplex/claude-sonnet-4-6' 'Reply with exactly: RouterPlex connected. Do not read files or run tools.'
Windows PowerShell
$env:ROUTERPLEX_API_KEY = 'YOUR_ROUTERPLEX_API_KEY'opencode.cmd run --model 'routerplex/claude-sonnet-4-6' 'Reply with exactly: RouterPlex connected. Do not read files or run tools.'
The first run may download the provider adapter. Look for the reply and the matching request in Usage. Run opencode --model routerplex/claude-sonnet-4-6 for an interactive session (opencode.cmd for Windows npm).
The environment variable applies only to that terminal session. For a desktop OpenCode app, use its provider/key UI or arrange for its process to inherit the variable; a terminal export does not automatically configure an already-running desktop app.
Troubleshooting
A 401 often means the environment variable is missing. A model error means the provider/model ID or key allowance differs. A budget error means available credit or the key limit has been exhausted. Check Errors and environment setup. Native executable installations can use opencode instead of opencode.cmd.
A longer walkthrough of the same custom provider is in OpenCode custom provider.
Official references: custom providers, configuration and variables, CLI.