Set up OpenCode

Open-source terminal coding agent. Add one custom provider to opencode.json

API format: OpenAI Chat Completions
Base URL format: Up to /v1 (https://gpt.cherrychat.org/v1)
Recommended model: claude-sonnet-5-5, gpt-6.1-sol
Platforms: macOS, Windows, Linux

Steps

Install OpenCode (skip if installed)
On macOS / Linux use the official script or npm. On Windows the docs recommend WSL, or install with npm directly. Check with opencode --version.
macOS / Linux
```
curl -fsSL https://opencode.ai/install | bash
```
Windows
```
npm install -g opencode-ai
```
Store the key in an environment variable
The config refers to the key as {env:CHERRYCHAT_API_KEY}, so the key itself lives in an environment variable. Reopen the terminal afterwards.
- CHERRYCHAT_API_KEY (API key): sk-your-key
macOS / Linux (append to ~/.zshrc)
```
echo 'export CHERRYCHAT_API_KEY="sk-your-key"' >> ~/.zshrc
source ~/.zshrc
```
Windows (reopen PowerShell afterwards)
```
setx CHERRYCHAT_API_KEY "sk-your-key"
```

Write opencode.json

The global config lives at ~/.config/opencode/opencode.json (open it with the command below). On native Windows, put opencode.json in the project root instead; it applies to that project only. Paste the content and save. Add more models in models the same way.

options.baseURL (API address): https://gpt.cherrychat.org/v1 (Stop at /v1)
Model name: claude-sonnet-5-5

Open the file (macOS)

mkdir -p ~/.config/opencode && touch ~/.config/opencode/opencode.json && open -e ~/.config/opencode/opencode.json

opencode.json content

{
  "$schema": "https://opencode.ai/config.json",
  "model": "cherrychat/claude-sonnet-5-5",
  "provider": {
    "cherrychat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CherryChat",
      "options": {
        "baseURL": "https://gpt.cherrychat.org/v1",
        "apiKey": "{env:CHERRYCHAT_API_KEY}"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "claude-sonnet-5-5" }
      }
    }
  }
}

Start and verify
Open a new terminal in your project folder and run the command below; a reply means it works. For interactive use run opencode and type /models to switch between the CherryChat models.

Common pitfalls

Set baseURL to /v1 (https://gpt.cherrychat.org/v1) and use @ai-sdk/openai-compatible, which calls the Chat API.
The top-level "model" is written as provider/model, i.e. cherrychat/claude-sonnet-5-5, and that model must also be listed under models.
{env:…} is OpenCode syntax (single braces). Alternatively run /connect → "Other" → enter cherrychat → paste the key, and drop apiKey from options.
OpenCode 2 still accepts this format; just do not mix V2 fields (providers / package / settings) into the same provider.
A project-level opencode.json overrides the global one when both exist.

Error → cause → fix

What you see	Why	What to do
HTTP 401 / invalid API key	The variable is not loaded (terminal not reopened), or the key is wrong or disabled	Reopen the terminal and run opencode auth list; copy the key again from My Keys if needed
HTTP 404 Not Found	baseURL is missing /v1 or was set to https://gpt.cherrychat.org/v1/chat/completions (path doubled)	Change it to https://gpt.cherrychat.org/v1
ProviderModelNotFoundError or model not found	The model in "model" is not listed under models, or the name does not match the Models page	Add the model under models and match the Models page exactly (all lowercase)
HTTP 402 or "insufficient balance" (billing_error in Claude format)	Your credits cannot cover this call. API calls are paid from credits only; memberships and unlimited plans do not apply	Top up any amount in the CherryChat Store, then retry after a few seconds
HTTP 429 Too Many Requests	Too many requests: by default 120 per minute per key and 8 at a time per account	Lower the concurrency or requests per second in the tool and wait for the Retry-After seconds; most tools retry on their own

Guide checked 2026-11-02. The tool's screens may change; the official docs win if they differ.

API · API Pricing

Operated by UK Company CHERRYCHAT LTD · Company Number 16096119 · Support WeChat: JsnonoChat · Content is AI-generated — please verify before relying on it

Set up OpenCode

Steps

Install OpenCode (skip if installed)

Store the key in an environment variable

Write opencode.json

Start and verify

Common pitfalls

Error → cause → fix