Complete Guide to Installing and Configuring OpenCode

⚠️ Pending Update · 2026-08-29 Verification · Content may be outdated, please refer to official docs Updated: 2026-08-29 · Status: Pending Verification

Introduction

OpenCode is an open-source terminal AI coding assistant in the spirit of Claude Code, but it works with any OpenAI-compatible model. It can read and write files, run shell commands, and iterate on code autonomously, and it ships a built-in MCP (Model Context Protocol) client so external tools can be plugged in. It is well suited to SSH sessions, containers, and pure command-line workflows where an IDE is overkill. This guide walks through installation, configuration, and the first chat session, and covers the common pitfalls when wiring in free models.

flowchart LR A["Install OpenCode"] --> B["Configure Model"] B --> C["Start Session"] C --> D["AI Reads Files"] D --> E["AI Edits Code"] E --> F["Run Commands"] F --> D

Installation

Three mainstream install paths, all cross-platform (Linux, macOS, Windows/WSL). Pick one.

Option 1: installer script (recommended)

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

The script detects the architecture, drops the binary into ~/.local/bin, and offers to update your PATH. When opencode --version prints a version, the install is successful.

Option 2: npm global install

npm install -g opencode-ai

Convenient if you already live in the Node toolchain. The npm release can lag the official script by a day or two.

Option 3: Homebrew (macOS/Linux)

brew install sst/tap/opencode

Homebrew's win is brew upgrade keeping OpenCode in sync with the rest of your packages.

Model Configuration

On startup OpenCode looks for opencode.json in the current directory or ~/.config/opencode/. Minimum viable config:

{
  "provider": {
    "openrouter": {
      "type": "openai",
      "baseURL": "https://openrouter.ai/api/v1",
      "apiKey": "sk-or-v1-..."
    }
  },
  "model": "deepseek/deepseek-chat:free",
  "smallModel": "google/gemini-2.0-flash:free"
}

Notes:

provider is a namespace — name it anything, as long as the prefix on model matches.
The :free suffix routes through OpenRouter's free tier — zero cost.
smallModel is used for summarization and lightweight completions; pinning it separately saves quota.
Put apiKey in an env var OPENROUTER_API_KEY and reference as "${OPENROUTER_API_KEY}" so the key never enters Git.

Wiring Groq / DeepSeek Direct

Groq is fast, ideal for day-to-day coding:

{
  "provider": {
    "groq": {
      "type": "openai",
      "baseURL": "https://api.groq.com/openai/v1",
      "apiKey": "${GROQ_API_KEY}"
    }
  },
  "model": "llama-3.3-70b-versatile"
}

DeepSeek is strong at reasoning — algorithm problems and code review:

{
  "provider": {
    "deepseek": {
      "type": "openai",
      "baseURL": "https://api.deepseek.com/v1",
      "apiKey": "${DEEPSEEK_API_KEY}"
    }
  },
  "model": "deepseek-reasoner"
}

Starting a Session

cd my-project
opencode

Inside the interactive UI, common commands:

add file path — include a file in the AI context
/model groq/llama-3.3-70b — switch model at runtime
/clear — wipe the current conversation history
exit or Ctrl+D — quit

Common Pitfalls

PATH not picked up: re-source ~/.bashrc or restart the shell before retrying opencode.
401 Unauthorized: check that OPENROUTER_API_KEY is exported into the current shell and that the config uses the ${ENV_VAR} reference syntax.
429 Too Many Requests: free tiers have RPM and TPM limits. Don't fire dozens of requests in a single burst, or rotate :free models.
Streaming stalls: Groq is consistently fast; OpenRouter :free can lag during peak hours — switch to Groq or DeepSeek direct.
Windows WSL path confusion: always use /mnt/c/... to reach the Windows drive from WSL; do not mix backslashes.

With OpenCode wired to free models, you have a zero-cost, scriptable, SSH-friendly AI coding assistant that behaves almost identically to Claude Code — at a bill of zero.

🚀 Get Started: One-Click Free API Access

Want to call all the free models above with a single API key, no need to sign up for each provider? Apishare.cc provides a unified API Key — one key, 100+ models, free models at zero cost.

👉 Register on Apishare.cc → Get your unified API Key

📊 Want to see more free model rankings? Check out the Sep 2026 Free LLM API Rankings →

Get Started: APIShare Free API Directory

🆓 Claim your free credits：Register on APIShare · Sign in to console
🔍 Browse every free API and live ranking：APIShare Free API Directory
📊 See the leaderboard：Free LLM API Rankings

About the Free API Aggregator

The models covered in this guide are all served through the APIShare free API aggregator, which gives you one key for the whole catalog.

Full model catalog: APIShare free API directory
Sign up for a free trial key: Register and claim your API key