Skip to content
Nexus Docs
↑↓Navigate↵SelectescClose

OpenCode → Nexus

Route OpenCode through the Nexus OpenAI-compatible edge

Last updated on:

Route OpenCode through the Nexus OpenAI-compatible edge (/v1). OpenCode talks chat completions (and optionally Responses, depending on the adapter); Nexus verifies a gateway API key (nxs_…) and dispatches to the configured upstream.

Shared prerequisites (gateway URL, nxs_… key, registry model, BYOK/PTB): Client Integrations.

1. Choose config location

Section titled “1. Choose config location”

OpenCode reads project and/or user config. A project file keeps the Nexus provider with the repo; a user file applies globally.

Scope Typical path
Project opencode.json or opencode.jsonc at the repo root
User ~/.config/opencode/opencode.json

2. Add a Nexus provider

Section titled “2. Add a Nexus provider”

Use the OpenAI-compatible adapter and list every model id you intend to select. Model keys must match ids from GET /v1/models on your gateway.

{
    "$schema": "https://opencode.ai/config.json",
    "provider": {
        "nexus": {
            "npm": "@ai-sdk/openai-compatible",
            "name": "Nexus",
            "options": {
                "baseURL": "https://api.example.com/v1",
                "apiKey": "{env:NEXUS_API_KEY}",
            },
            "models": {
                "openai/gpt-5.4-mini": {
                    "name": "GPT-5.4 mini (via Nexus)",
                },
                "anthropic/claude-sonnet-4-6": {
                    "name": "Claude Sonnet 4.6 (via Nexus)",
                },
            },
        },
    },
}

Local Compose example — set baseURL to http://127.0.0.1:14450/v1.

Notes:

  • options.baseURL must end at /v1 (no /chat/completions).
  • Keep the secret in the environment (NEXUS_API_KEY=nxs_…), not in the JSON file.
  • A models block is required for custom providers; without it OpenCode often fails to resolve nexus/<model>.
  • For models that must use /v1/responses instead of chat completions, use the OpenAI adapter (@ai-sdk/openai) for that provider or model per OpenCode’s provider docs. Nexus supports both /v1/chat/completions and /v1/responses.

3. Authenticate and select the model

Section titled “3. Authenticate and select the model”
Terminal window
export NEXUS_API_KEY='nxs_…'
# Optional: some OpenCode builds also accept `opencode auth` for the provider id.
opencode

In the TUI / model picker, choose a model under the Nexus provider (for example nexus/openai/gpt-5.4-mini).

4. Smoke test outside OpenCode

Section titled “4. Smoke test outside OpenCode”
Terminal window
GATEWAY_URL="${GATEWAY_URL:-https://api.example.com}"
curl -sS "$GATEWAY_URL/v1/chat/completions" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 16
  }' | jq .

If this fails, fix the gateway URL, key, or model id before debugging OpenCode.

Common failures

Section titled “Common failures”
Symptom Likely cause
Provider / model not found Missing models entries, or id not in GET /v1/models
401 from gateway Wrong secret, nxd_… used instead of nxs_…, or revoked key
Connection refused Wrong host/port; local gateway not published on 14450
Upstream / routing errors No BYOK/PTB provider key for the org/project, or model not in registry
Section titled “Related”