OpenCode with AIXHUB

Use this guide to connect OpenCode to an AIXHUB model through an OpenAI-compatible provider. The API key stays in an environment variable, while opencode.json contains the provider and model route.

What you will accomplish

By the end of this guide, you will have:

1. Installed OpenCode through npm and confirmed which version runs.
2. Supplied a dedicated AIXHUB API key without displaying it or saving it in opencode.json.
3. Added a complete aixhub provider and selected aixhub/panel-model-id.
4. Completed one read-only request and matched it with AIXHUB Usage.
5. Kept a backup and a clear route back to the previous configuration.

System requirements

• Windows, macOS, or Linux with a supported Node.js release and npm available on PATH.
• Permission to install an npm package globally for the current user or Node.js environment.
• An AIXHUB account, a dedicated AIXHUB API key, and an OpenAI-compatible model ID copied from Model routes. Every model field in this guide uses panel-model-id.
• A text editor that preserves valid JSON.

OpenCode reads the user configuration from:

• Windows: %USERPROFILE%\.config\opencode\opencode.json
• macOS and Linux: ~/.config/opencode/opencode.json

Back up an existing user file before editing it. Also inspect the project root for opencode.json: project configuration can override the user configuration, including its provider and selected model.

Install

Install the OpenCode npm package:

npm install -g opencode-ai

Open a new terminal and confirm the executable and version:

opencode --version

Resolve npm permission or PATH errors before adding AIXHUB settings. This keeps installation problems separate from provider problems.

AIXHUB configuration

Set the key for the current terminal

Use the block for the shell that will start OpenCode. Each block accepts the key without echoing it and avoids placing the real value in shell history.

Bash

read -r -s -p "AIXHUB API key: " AIXHUB_KEY
printf '\n'
export AIXHUB_API_KEY="$AIXHUB_KEY"
unset AIXHUB_KEY

zsh

read -r -s "AIXHUB_KEY?AIXHUB API key: "
printf '\n'
export AIXHUB_API_KEY="$AIXHUB_KEY"
unset AIXHUB_KEY

Windows PowerShell

$secureKey = Read-Host "AIXHUB API key" -AsSecureString
$plainKey = [System.Net.NetworkCredential]::new("", $secureKey).Password
$env:AIXHUB_API_KEY = $plainKey
Remove-Variable plainKey, secureKey

The variable exists only in this terminal process and programs launched from it. Close the terminal after testing to clear it from the process environment.

Save the provider configuration

Save the following complete JSON as the user-level opencode.json. If the file already contains unrelated providers, plugins, or options, merge the provider.aixhub object and top-level model property instead of replacing those settings.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aixhub": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AIXHUB",
      "options": {
        "baseURL": "https://api.aixhub.org/v1",
        "apiKey": "{env:AIXHUB_API_KEY}"
      },
      "models": {
        "panel-model-id": {
          "name": "AIXHUB model"
        }
      }
    }
  },
  "model": "aixhub/panel-model-id"
}

Property names are case-sensitive: use baseURL, with uppercase URL, and include exactly one /v1. The apiKey value is an OpenCode environment reference, not the key itself. The model key under models and the suffix of the top-level model route must remain identical.

If a project has its own opencode.json, either remove the conflicting provider and model values for this test or make them match the user configuration. Restart OpenCode after changing either file.

First run

From a small test project, start OpenCode in the terminal where AIXHUB_API_KEY is set:

opencode

Before sending a request, open OpenCode's model selector and confirm that aixhub/panel-model-id is selected. If another model is shown, select the AIXHUB model explicitly and check the project-level opencode.json for an override.

Send this bounded, read-only task:

Inspect the current directory without changing any file or running a state-changing command. Reply with OK only.

Review any tool permission request before approving it. The first connection test does not require file writes or access outside the test project.

Verification

A successful response should contain this output:

OK

Then open AIXHUB Usage and find a new OpenAI-compatible request for panel-model-id. Confirm that its time matches the test and that the selected route was aixhub/panel-model-id rather than an official account or another provider.

Troubleshooting

AIXHUB or the model is missing

Confirm that the JSON file is in the correct user path, has valid syntax, and contains provider.aixhub. Restart OpenCode after saving it. If the provider appears outside the project but not inside it, a project opencode.json is overriding the user file.

401 or authentication failed

Start OpenCode from the same terminal where AIXHUB_API_KEY was entered. The JSON must contain {env:AIXHUB_API_KEY} exactly; do not replace it with an official OpenAI login or an AIXHUB dashboard password. Re-enter a current dedicated key without printing it, then start a new OpenCode process.

404 or an endpoint error

Keep baseURL exactly https://api.aixhub.org/v1. A missing /v1, a duplicated /v1/v1, or the wrong property spelling can send the request to the wrong endpoint. Also check whether a project configuration replaces provider.aixhub.options.

model not found

Copy the exact ID again from Model routes. Replace both models.panel-model-id and the suffix in model: "aixhub/panel-model-id"; do not change only one location or add the provider prefix twice.

A response works but Usage has no matching request

Check the active provider and selected model in OpenCode. Another user setting, project opencode.json, or official-account route may have won. Fully close OpenCode, make the two configuration scopes consistent, and repeat the small request.

Upgrade and restore

Upgrade the global npm package, then confirm the version that is now on PATH:

npm install -g opencode-ai@latest
opencode --version

After an upgrade, repeat the read-only verification before allowing write-capable work.

To restore the previous setup, close OpenCode and restore the backup of the user opencode.json. If there is no backup, remove only provider.aixhub and the top-level model property added by this guide, preserving unrelated settings and valid JSON. Restore or remove any conflicting project opencode.json changes as well. Clear AIXHUB_API_KEY by closing the temporary terminal, then start OpenCode again and confirm the provider before granting tool access.

Security

• Keep the real API key out of both user and project JSON. {env:AIXHUB_API_KEY} is a reference and can remain in the configuration.
• Create a dedicated AIXHUB key for OpenCode so it can be rotated or revoked without affecting other clients.
• Do not print the environment variable, paste the key into a prompt, commit it, or include it in screenshots and support logs.
• Review a repository's opencode.json before trusting the project because it can override the provider, model, and other OpenCode behavior.
• Keep the first request read-only and continue reviewing tool permissions after the network route has been verified.
• Rotate the key immediately if it appears in terminal history, a repository, a patch, or a shared log.

Official sources

• OpenCode documentation
• OpenCode provider configuration

Last verified: 2026-07-14