OpenCode + OpenRouter
Setup Guide

OpenCode is an open-source AI coding agent that runs directly in your terminal. Think of it like having a coding assistant that can read your files, run commands, edit code, and help you debug, all without leaving your command line.

It supports a Terminal User Interface (TUI), which gives you an interactive, keyboard-driven experience similar to a text editor, right inside your terminal window. It works inside any IDE that has a built-in terminal, including VS Code and Zed.

OpenRouter is a unified AI gateway. Instead of signing up for separate accounts at OpenAI, Anthropic, Google, DeepSeek, and others, you get one API key that gives you access to all of them, including dozens of affordable models like DeepSeek and Qwen.

You pay only for what you use. There is no subscription, no minimum spend, and no lock-in. Pricing is measured in tokens, and some models on OpenRouter cost as little as a fraction of a penny per thousand tokens, making them extremely affordable for development work.

Before installing OpenCode, you’ll need an OpenRouter account and API key. This only takes a few minutes.

• 1
  Create your account

  Go to openrouter.ai and sign up for a free account using your email or Google login.

• 2
  Navigate to API Keys

  Once logged in, click your profile icon in the top right, then select Keys from the menu.

• 3
  Create a new key

  Click Create Key, give it a name (e.g. “OpenCode”), and copy the key that appears. Store it somewhere safe, as you won’t be able to see it again.

• 4
  Add credits

  Go to Credits in your account and add a small amount to start, as even $5 goes a long way with cheap models. OpenRouter only charges for actual usage.

OpenCode requires Node.js version 18 or higher. If you’re not sure what version you have, run node --version in your terminal. If you need to install or upgrade Node.js, visit nodejs.org.

Once Node.js is ready, install OpenCode globally with npm:

npm install -g opencode-ai

Verify the installation worked by checking the version:

opencode --version

If you see a version number printed out, OpenCode is installed correctly. To launch it, navigate to any project folder and run:

cd /path/to/your/project
opencode

With OpenCode running, connecting your OpenRouter account is done entirely through the built-in /connect command. No manual config editing required.

• 1
  Open OpenCode in your project

  In your terminal, cd into your project folder and run opencode to launch the TUI.

• 2
  Type /connect

  In the message input at the bottom of the TUI, type /connect and press Enter. A list of available providers will appear.

• 3
  Search for OpenRouter

  Start typing “openrouter” to filter the list, then select it with your arrow keys and press Enter.

• 4
  Paste your API key

  OpenCode will prompt you to enter your API key. Paste the key you copied from OpenRouter and press Enter.

That’s it. OpenRouter is now connected. Your key is saved to ~/.local/share/opencode/auth.json so you won’t need to re-enter it for future sessions.

Alternatively, if you prefer to set it manually, you can add your key directly to the auth file:

{
  "openrouter": {
    "key": "sk-or-v1-YOUR_KEY_HERE"
  }
}

OpenRouter gives you access to hundreds of models. The most cost-effective options for coding come from labs like DeepSeek and Qwen (by Alibaba). These models perform exceptionally well on coding tasks at a fraction of the cost of GPT-4 or Claude Opus.

Here is a comparison of the best affordable models available through OpenRouter right now:

One of OpenCode’s most powerful features is how easy it is to switch models. You can do this mid-session without restarting, and your OpenRouter key stays the same regardless of which model you choose.

Method 1: Using the /models Command (Recommended)

Inside any active OpenCode session, type the following and press Enter:

/models

A searchable list of all available models will appear. Use your arrow keys to navigate, or start typing a model name to filter. Press Enter to select. The model switches immediately for your next message.

Method 2: Set a Default Model in Your Config File

If you always want to start with a specific model, set it as the default in your opencode.json config file. Create or edit this file in your project root:

{
  "model": "openrouter/deepseek/deepseek-chat-v4-flash"
}

Method 3: Pass a Model via the CLI (One-Off Use)

If you want to run OpenCode with a specific model just for that session without changing your config, pass it as a flag when launching:

opencode --model openrouter/qwen/qwen3-coder

OpenCode runs in any terminal, which means it works seamlessly inside the built-in terminals of both VS Code and Zed. No extension or plugin is needed.

Inside VS Code

• 1
  Open the integrated terminal

  Press Ctrl+` on Windows/Linux, or Cmd+` on macOS, to open the VS Code terminal panel.

• 2
  Navigate to your project

  If your project is already open in VS Code, the terminal should already be in the right folder. Confirm with pwd.

• 3
  Launch OpenCode

  Type opencode and press Enter. The TUI will open inside the terminal panel. You can resize the panel to give it more space.

Inside Zed

• 1
  Open the terminal panel

  Press Ctrl+` or go to View → Terminal to open Zed’s built-in terminal.

• 2
  Launch OpenCode

  Type opencode and press Enter. The TUI launches in the same panel, right alongside your code editor.

OpenCode looks for a config file called opencode.json in your project root or your global config directory. This file lets you set a default model, customize behavior, and persist your preferences across sessions.

Here is a full example showing the most useful settings:

{
  // Set the default model to use on launch
  "model": "openrouter/deepseek/deepseek-chat-v4-flash",

  // Optional: Keep conversation history between sessions
  "autosave": true,

  // Optional: Set the theme (dark, light, or a custom theme name)
  "theme": "dark"
}

You can override the model in config on a per-project basis by placing a different opencode.json in each project folder. This is useful if some projects need a heavier model and others work fine with the cheapest option.

Model ID Format for OpenRouter

When specifying an OpenRouter model in your config or CLI flag, use this format:

openrouter/{provider}/{model-name}

Examples:
openrouter/deepseek/deepseek-chat-v4-flash
openrouter/deepseek/deepseek-chat-v4-pro
openrouter/qwen/qwen3-coder
openrouter/qwen/qwen2.5-32b-instruct
openrouter/moonshot/kimi-k2

You can browse all available model IDs at openrouter.ai/models. Each model’s page shows the exact ID string to use.

A few recommendations to get the most out of OpenCode and keep your costs low:

• ★
  Start cheap, upgrade when needed

  Default to DeepSeek V4 Flash or Qwen3-Coder for routine tasks. Only switch to a more capable model when you’re dealing with complex logic, large refactors, or architecture decisions.

• ★
  Keep context focused

  AI models charge per token, including your input. The more files and context you feed into a session, the more it costs. Open only the files relevant to the task at hand.

• ★
  Use free models for exploration

  OpenRouter has a number of completely free models (like NVIDIA Nemotron). Use these for experimenting, learning, or low-stakes tasks to preserve your credits for real work.

• ★
  Set a spending limit on your key

  In your OpenRouter dashboard, you can cap spending per API key. Set a monthly limit so you never accidentally run up a large bill while experimenting with a new model.

• ★
  Use per-project config files

  Place a custom opencode.json in each project folder to set the best model for that project. A small utility script might use the cheapest model, while a large production codebase gets the more powerful one.

• ★
  Check the activity dashboard

  OpenRouter provides a usage dashboard at openrouter.ai/activity where you can see exactly how many tokens each model consumed and what it cost. Review this periodically to optimize your usage.