OpenCode Routes Coding Prompts to OpenRouter Models

OpenCode can send coding prompts to models available through OpenRouter, letting you choose a model in OpenCode while using OpenRouter as the provider. You will configure an OpenRouter API key, select the provider and model, then verify the route with a test prompt.

What You’ll Need

• OpenCode installed and able to start in your terminal.
• An OpenRouter account with an API key. Keep the key private; do not paste it into prompts, source files, or a shared configuration.
• The exact model identifier shown in OpenRouter’s model catalog, such as a provider/model name. Availability and identifiers can change, so check the catalog rather than relying on an old example.
• A project directory where you can safely test OpenCode.

Step-by-Step

1. Check the OpenCode command and configuration options. In a terminal, run opencode --help. OpenCode’s configuration and command options can evolve; use the help output and current OpenCode documentation if your installed version differs from the steps below. Start OpenCode in the project you intend to use, not in a directory containing unrelated or sensitive files.
2. Create an OpenRouter API key. Sign in to OpenRouter, create a key in its account settings, and copy it once into a password manager or another appropriate secret store. Do not commit the key to Git. If it has already been exposed, revoke it and create a replacement.
3. Authenticate the OpenRouter provider. OpenCode supports provider authentication through its provider login flow. Run opencode auth login, choose OpenRouter when prompted, and follow the displayed instructions to supply the key. If the command offers a different interactive sequence in your version, follow its prompts rather than guessing at flags. Some releases also let you configure credentials through the OpenCode configuration; consult the current documentation for the supported method. Avoid putting a raw key in a project-level file that may be shared or committed.
4. Find a model identifier in OpenRouter. Browse OpenRouter’s model catalog and copy the model’s exact identifier, including its provider prefix where shown. Check that the model is currently available and suitable for coding. The model’s context size, tool support, and cost vary; OpenCode’s agent workflows may depend on tool calling, so check compatibility if a model responds but cannot use tools.
5. Set the model in OpenCode. Start OpenCode with opencode. Use its model-selection command or picker—commonly opened with /models in the TUI—to choose OpenRouter, then select the model. If it is not listed, use the current OpenCode documentation to add or select a custom model using the exact OpenRouter identifier. Do not assume every model in OpenRouter is automatically listed in every OpenCode release.
6. Make the choice persistent if needed. If you want the same model selected when you reopen OpenCode, use its configuration interface or edit the OpenCode configuration file following the schema for your installed version. Set the provider to OpenRouter and the model to the exact catalog identifier. Configuration locations and accepted field names can change, so verify them against the current documentation rather than copying an unverified JSON or YAML snippet. Keep credentials separate from project files wherever possible.
7. Send a small test prompt. Ask OpenCode to explain a short code snippet or make a harmless change in a disposable project. Confirm the answer appears and, if you requested an edit, inspect the diff before accepting it. Avoid using a prompt that contains secrets or private code until you have reviewed the provider’s data and privacy terms.
8. Confirm the request used OpenRouter. Check OpenCode’s selected provider and model in its interface or status display. If available, review the request in your OpenRouter activity or usage page. A successful response alone does not prove the intended model was selected; verify the displayed identifier and check for fallback or routing settings.

Common Mistakes

• Using a display name instead of the model ID: A friendly catalog label may not be accepted as the identifier. Copy the exact ID.
• Choosing the wrong provider: Selecting a similarly named model from another provider can route requests elsewhere. Check the provider label as well as the model name.
• Assuming the key is configured because it exists in an account: OpenCode still needs access to the key through its authentication flow or supported configuration.
• Putting secrets in a repository: A committed key can be copied by others. Remove it from the file, revoke it, and replace it; deleting the visible line alone may not remove it from Git history.
• Expecting every model to support agent tools: Text generation may work while tool use does not. Check OpenRouter’s model details and OpenCode’s compatibility notes.
• Ignoring usage limits: OpenRouter requests may fail when a key, account, model, or provider has a limit or availability issue. Review the service’s usage and error details.

Tips

• Test model changes in a small project first, and review code changes before running them.
• Keep a known-working model selection available so you can distinguish a model-specific issue from a general authentication or network problem.
• Use separate keys for different environments if that helps you manage access, and revoke keys you no longer need.
• Check both OpenCode and OpenRouter documentation when configuration syntax, model availability, or authentication behavior changes.
• Be deliberate about sending proprietary code. Understand the provider’s handling and retention terms before routing sensitive material through a third party.

Troubleshooting

OpenRouter does not appear in the provider picker: Update OpenCode using its documented installation method, restart it, and check the provider list again. If it remains absent, consult the version-specific provider setup instructions; do not substitute an unrelated provider name.

Authentication fails or requests report an invalid key: Confirm the key was copied completely, without surrounding spaces, and that you selected OpenRouter during login. Re-authenticate using opencode auth login. If the key may have been exposed, revoke it and create a new one rather than repeatedly retrying the old key.

The model is missing or rejected: Check the exact identifier in OpenRouter’s current catalog, including punctuation and provider prefix. Confirm OpenCode supports selecting that model, then follow its documented custom-model configuration steps if needed.

The model answers but does not perform edits or tools: Verify the active model and check whether it supports the tool-calling features OpenCode needs. Try another compatible model. Also confirm you approved any requested tool action in OpenCode; a model selection does not automatically authorize every operation.

Requests time out or fail intermittently: Check your internet connection, OpenRouter’s service status, account limits, and the model’s current availability. Retry a small prompt after a short wait. If the failure persists, record the non-secret error details and consult the relevant provider documentation or support channel. Never include your API key in a support post.

Frequently Asked Questions

Does OpenCode route prompts through OpenRouter automatically?
No. You need to authenticate with OpenRouter and select an OpenRouter model in OpenCode. Confirm the active provider and model before relying on the route.

Where do I get the model name?
Use the model’s exact identifier in OpenRouter’s current catalog. The identifier may differ from the readable display name.

Can I use any model listed on OpenRouter?
Not necessarily. OpenCode must be able to select it, and agent tasks may require tool support. Check both services’ current compatibility details.

Do I need to add my API key to the project configuration?
Usually you should authenticate through OpenCode’s provider login flow or another documented secret-handling method. Avoid storing a key in a file that might be committed or shared.

How can I tell which model answered?
Check OpenCode’s active model display and, where available, the request or usage details in OpenRouter. Do not infer the route from the answer alone.

Will this setup make requests free?
No. Model access and any applicable limits depend on your OpenRouter account and the selected model. Check current usage details before sending large or repeated prompts.

Related

• Google AI and Romance Novels: Can It Speak Naturally?
• Skills, MCP Servers, and Plugins: What Each Does
• Slack Huddles: What They Are and How to Use Them