OpenCode

OpenCode is an open source AI coding agent for the terminal, desktop, and IDEs. For AIOHub, configure a separate provider so AIOHub API keys stay isolated from your official OpenAI, Anthropic, or other provider credentials.

Prerequisites

OpenCode installed
An AIOHub sk- API key
A group assigned to the API key that can access the model you want to use
A positive account balance

Check that OpenCode is available:

opencode --version
opencode --help

Config location

OpenCode supports global and project config. Use global config for your personal defaults and project config when you want to share model IDs with a repository.

Use case	File
User-wide config	`~/.config/opencode/opencode.json`
Current project config	`opencode.json`

Project opencode.json overrides matching fields from global config. Do not commit real API keys. For shared project config, save credentials locally with /connect or reference an environment variable.

Configure Chat Completions models

OpenCode uses @ai-sdk/openai-compatible for OpenAI Chat Completions-compatible models. Set the Base URL to https://api.aiohub.org/v1, not a full endpoint URL.

1. Add the credential

In the OpenCode TUI, run:

/connect

Choose Other, enter this provider ID:

aiohub

Then enter your full AIOHub API key.

2. Add the provider config

Add this to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aiohub": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AIOHub",
      "options": {
        "baseURL": "https://api.aiohub.org/v1"
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o"
        }
      }
    }
  },
  "model": "aiohub/gpt-4o"
}

Replace gpt-4o with a Chat Completions model available to the group assigned to your API key. If you want a lightweight model for smaller tasks, add small_model:

{
  "model": "aiohub/gpt-4o",
  "small_model": "aiohub/gpt-4o-mini"
}

Configure Responses models

If you want to use a model or workflow that requires OpenAI Responses, use @ai-sdk/openai. A separate provider ID keeps the Chat Completions and Responses paths clear. Put the API key in an environment variable:

export AIOHUB_API_KEY="sk-your-api-key"

Then configure a Responses provider:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aiohub-responses": {
      "npm": "@ai-sdk/openai",
      "name": "AIOHub Responses",
      "options": {
        "baseURL": "https://api.aiohub.org/v1",
        "apiKey": "{env:AIOHUB_API_KEY}"
      },
      "models": {
        "gpt-5.3-codex": {
          "name": "GPT-5.3 Codex"
        }
      }
    }
  },
  "model": "aiohub-responses/gpt-5.3-codex"
}

You can keep multiple providers in one OpenCode config. Chat Completions and Responses use different request paths. If a model fails with endpoint or response-format errors, check that the npm package matches the model protocol.

Verify

Open OpenCode:

opencode

Run this in the TUI:

/models

Choose a model under aiohub/... or aiohub-responses/..., then send a short message. A normal reply means the setup is working. You can also verify API key and model visibility with HTTP:

curl https://api.aiohub.org/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

Troubleshooting

AIOHub does not appear in the model list

Confirm the provider ID entered through /connect exactly matches the provider key in opencode.json, for example aiohub. Restart OpenCode after editing config.

404 or duplicated path

Set the Base URL to https://api.aiohub.org/v1. Do not set it to https://api.aiohub.org/v1/chat/completions or https://api.aiohub.org/v1/responses.

API key is not used

If you use /connect, confirm the credential is saved under the same provider ID. If you use an environment variable, run test -n "$AIOHUB_API_KEY" && echo "api key configured" before starting OpenCode.

Responses model returns a format error

Confirm the provider uses @ai-sdk/openai, not @ai-sdk/openai-compatible. If you only need basic chat, verify basic connectivity with a Chat Completions model first.

Choose a client

Developer tools

OpenAI-compatible apps

Image clients

Chat clients

Prerequisites

Config location

Configure Chat Completions models

1. Add the credential

2. Add the provider config

Configure Responses models

Verify

Troubleshooting

Official references

​Prerequisites

​Config location

​Configure Chat Completions models

​1. Add the credential

​2. Add the provider config

​Configure Responses models

​Verify

​Troubleshooting

​Official references

Prerequisites

Config location

Configure Chat Completions models

1. Add the credential

2. Add the provider config

Configure Responses models

Verify

Troubleshooting

Official references