OpenCode

Connect OpenCode to RealRelay.ai as a custom OpenAI-compatible provider: install it, add a provider block to opencode.json, check the connection and add models with their limits.

Create an API key Browse the catalog

Protocol: OpenAI Chat Completions · OpenAI Responses
Base URL: https://www.realrelay.ai/v1
Official docs: opencode.ai
Checked against the tool’s docs: 2026-10

Overview

OpenCode is an open source coding agent that runs in your terminal. It reads your project, edits files and runs commands. You add RealRelay.ai to it as a custom provider, and it sends requests to the Chat Completions endpoint, /v1/chat/completions.

An API key from the API keys page of the console.
The base URL with /v1 at the end. OpenCode appends /chat/completions to it.
A model ID exactly as GET /v1/models lists it, for example z-ai/glm-5.2. The model needs tool calling.

This page covers OpenCode 1, the current stable release documented at opencode.ai/docs. The OpenCode 2 preview uses a different configuration shape for providers, so the file below does not apply to it.

Install

Use one of the methods from OpenCode's own documentation. All of them install the same opencode command.

macOS · Linux · WSL

curl -fsSL https://opencode.ai/install | bashopencode --version

Homebrew (macOS · Linux)

brew install anomalyco/tap/opencode

OpenCode recommends its own tap. The plain brew install opencode formula is maintained by Homebrew and updates less often.

npm

npm install -g opencode-ai

Windows PowerShell

choco install opencode# orscoop install opencode

If opencode --version prints a version number, the install worked. OpenCode's docs recommend a modern terminal such as WezTerm, Alacritty, Ghostty or Kitty.

Configure

1
Save your key in an environment variable
The config file reads the key from REALRELAY_API_KEY, so the file itself holds no secret.
~/.zshrc · ~/.bashrc
export REALRELAY_API_KEY="sk-***"
Run source ~/.zshrc, or open a new terminal.
Windows PowerShell
[Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")
Close and reopen the terminal so it sees the new variable.

Add RealRelay.ai as a provider

Put this in your global config. To use it in one project only, put the same content in opencode.json at the project root instead.

~/.config/opencode/opencode.json

1{2  "$schema": "https://opencode.ai/config.json",3  "provider": {4    "realrelay": {5      "npm": "@ai-sdk/openai-compatible",6      "name": "RealRelay.ai",7      "options": {8        "baseURL": "https://www.realrelay.ai/v1",9        "apiKey": "{env:REALRELAY_API_KEY}"10      },11      "models": {12        "z-ai/glm-5.2": {13          "name": "z-ai/glm-5.2",14          "limit": {15            "context": 200000,16            "output": 3200017          }18        }19      }20    }21  },22  "model": "realrelay/z-ai/glm-5.2"23}

realrelay is the provider ID. It can be any name, but every model reference starts with it, as in realrelay/z-ai/glm-5.2.
npm picks the client OpenCode loads. @ai-sdk/openai-compatible sends Chat Completions requests.
{env:REALRELAY_API_KEY} is replaced with the variable's value when OpenCode starts. If the variable is not set, the key is empty and requests fail with 401.
Each key under models is the model ID sent to RealRelay.ai. limit tells OpenCode the context window and the maximum output, because RealRelay.ai's model list does not include them.
model sets the default model for new sessions.

You can also store the key with OpenCode's /connect command instead of an environment variable. Choose Other and enter the same provider ID as in the file. Then remove the apiKey line.

OpenCode

1/connect2# Select provider → Other3# Enter provider id → realrelay4# Enter your API key → sk-***

Verify

Call the endpoint directly

Run this with your key. A JSON reply with a choices array means the address, key and model work.

Terminal

1curl -sS "https://www.realrelay.ai/v1/chat/completions" \2  -H "Authorization: Bearer sk-***" \3  -H "content-type: application/json" \4  -d '{"model": "z-ai/glm-5.2", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'

2
Check that OpenCode sees the provider
The first command should list your model as realrelay/…. The second sends one message and prints the reply.
Terminal
opencode models realrelayopencode run -m "realrelay/z-ai/glm-5.2" "Reply with OK"
3
Start a session in a project
Run /models and choose the RealRelay.ai model, then send a short message. The request appears in the console's usage logs.
OpenCode
cd /path/to/your/projectopencode/models

Models

OpenCode only shows the models you list under the provider. To add one, add another entry with its ID and limits, then pick it with /models or start with opencode -m realrelay/<model-id>.

~/.config/opencode/opencode.json → provider.realrelay.models

1"z-ai/glm-5.2": {2  "name": "z-ai/glm-5.2",3  "limit": { "context": 200000, "output": 32000 }4},5"<another-model-id>": {6  "name": "<another-model-id>",7  "limit": { "context": 128000, "output": 16000 }8}

The limits in these examples are safe starting values. Set limit.context and limit.output to the real numbers from the model's catalog page, so OpenCode compacts the conversation at the right time.

A few OpenAI models are served on the Responses endpoint, /v1/responses. OpenCode reaches that endpoint through the @ai-sdk/openai client. Add a second provider with the same key for those models, and keep the Chat Completions provider for everything else:

~/.config/opencode/opencode.json → provider

1"realrelay-responses": {2  "npm": "@ai-sdk/openai",3  "name": "RealRelay.ai (Responses)",4  "options": {5    "baseURL": "https://www.realrelay.ai/v1",6    "apiKey": "{env:REALRELAY_API_KEY}"7  },8  "models": {9    "openai/gpt-5.3-codex": {10      "name": "openai/gpt-5.3-codex",11      "limit": { "context": 400000, "output": 128000 }12    }13  }14}

Which models suit an agent, and which ones the Responses endpoint serves, is under Choosing a model.

Troubleshooting

The provider or model is missing from /models. The JSON did not load or the models map is empty. Check which config OpenCode resolved; a project opencode.json overrides the global file for the same keys.
Terminal
```
opencode auth listopencode debug config
```
401. The key is empty or wrong. Make sure REALRELAY_API_KEY is set in the terminal that starts OpenCode. If you used /connect, opencode auth list should show your provider ID, and it must match the ID in the file.
404. The base URL is missing /v1, or it already ends in /chat/completions. Use the address ending in /v1.
Model not found. The key under models must match the ID from GET /v1/models exactly, including the part before the slash.
Errors on a Responses-only model, or on a model you moved to the Responses provider. Only the models listed under Choosing a model are served on /v1/responses. Other models stay on the @ai-sdk/openai-compatible provider.
The conversation grows until the request is rejected. limit.context is missing or larger than the model's real window. Set it from the model's catalog page and run /compact.
The agent describes changes but does not make them. The model is not calling tools. Pick a model that supports tool calling.