OpenCode

Connect an existing OpenCode install to GonkaGate. Start with the official installer if you want the narrowest verified path. Use the manual custom-provider route only when you need to review or control the OpenCode config yourself.

Quick setup with the GonkaGate installer

Run the official installer:

npx @gonkagate/opencode-setup

This tool configures an existing local opencode install. It does not install OpenCode itself.

Use this path when you want GonkaGate to manage the safe OpenCode wiring for you:

• keeps the secret out of repo-local opencode.json
• writes only the minimum safe config
• verifies the effective OpenCode result with opencode debug config --pure
• returns you to plain opencode

Before you start

• OpenCode is already installed locally and available on PATH.
• Node >=22.14.0 is available for the npx installer.
• You already have a GonkaGate API key in gp-... format.
• The current validated public OpenCode model is qwen/qwen3-235b-a22b-instruct-2507-fp8.

Non-interactive installer path

Use this for scripts, automation, or a repo you want to bind in project scope:

GONKAGATE_API_KEY=gp-... npx @gonkagate/opencode-setup --scope project --yes

If you do not want to pass the key through an environment variable, use stdin:

printf '%s' "$GONKAGATE_API_KEY" | npx @gonkagate/opencode-setup --api-key-stdin --scope project --yes --json

Verify the installer path

Run:

opencode debug config --pure

Confirm that the resolved config includes:

• provider.gonkagate
• https://api.gonkagate.com/v1
• qwen/qwen3-235b-a22b-instruct-2507-fp8 as the starting GonkaGate model

Then start OpenCode and run:

/models

Pick the GonkaGate model if needed and send this prompt:

Reply with exactly: OpenCode connected to GonkaGate

That confirms the provider, base URL, and model routing before a longer session.

Manual custom-provider path

Use this path only if you want to configure OpenCode yourself or compare the installer result with the official custom-provider flow documented by OpenCode.

1. Store the credential in OpenCode

Start OpenCode, run /connect, choose Other, then enter:

• Provider id: gonkagate
• API key: your gp-... key

OpenCode stores /connect credentials in ~/.local/share/opencode/auth.json.

2. Add the provider config

OpenCode reads global config from ~/.config/opencode/opencode.json and can also read a project ./opencode.json. Project config has higher precedence.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gonkagate": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "GonkaGate",
      "options": {
        "baseURL": "https://api.gonkagate.com/v1"
      },
      "models": {
        "qwen/qwen3-235b-a22b-instruct-2507-fp8": {
          "name": "GonkaGate Qwen3 235B"
        }
      }
    }
  },
  "model": "gonkagate/qwen/qwen3-235b-a22b-instruct-2507-fp8",
  "small_model": "gonkagate/qwen/qwen3-235b-a22b-instruct-2507-fp8"
}

Keep these boundaries straight:

• Use @ai-sdk/openai-compatible because the current GonkaGate OpenCode path is the OpenAI-compatible chat/completions flow.
• Keep /v1 in the baseURL.
• The provider id in /connect and the provider key in opencode.json must match exactly.
• Start with qwen/qwen3-235b-a22b-instruct-2507-fp8, then switch only after you confirm another current model ID in Get Models.

If you prefer environment-based auth instead of /connect, OpenCode also supports options.apiKey, for example "{env:GONKAGATE_API_KEY}". Keep that value out of repo-local config.

3. Verify the manual path

Run:

opencode auth list
opencode debug config --pure

Then start OpenCode and run:

/models

Confirm that gonkagate and your configured model appear before you send a real prompt.

Common first failures

Current boundaries

• This guide configures an existing OpenCode install. It does not install OpenCode itself.
• The current verified GonkaGate OpenCode path is the OpenAI-compatible /chat/completions flow.
• The installer currently starts from the validated public model qwen/qwen3-235b-a22b-instruct-2507-fp8.
• Project opencode.json has higher precedence than global config, so local overrides can hide a correct user-level provider setup.

Official references

• GonkaGate OpenCode installer
• OpenCode providers docs
• OpenCode config docs

See also

• Claude Code for the curated Anthropic-compatible path
• Cursor setup for Cursor’s OpenAI settings path
• OpenClaw setup for another custom-provider route
• Authentication and API Keys for key creation, storage, and rotation
• Get Models for current machine-readable model IDs
• GonkaGate Quickstart if you still want one direct request from scratch