> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiohub.org/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode

> Use AIOHub as a model provider in OpenCode.

[OpenCode](https://opencode.ai/docs) 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:

```bash theme={"system"}
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`                    |

<Note>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.</Note>

## 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:

```bash theme={"system"}
/connect
```

Choose Other, enter this provider ID:

```text theme={"system"}
aiohub
```

Then enter your full AIOHub API key.

### 2. Add the provider config

Add this to `opencode.json`:

```json theme={"system"}
{
  "$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`:

```json theme={"system"}
{
  "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:

```bash theme={"system"}
export AIOHUB_API_KEY="sk-your-api-key"
```

Then configure a Responses provider:

```json theme={"system"}
{
  "$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"
}
```

<Note>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.</Note>

## Verify

Open OpenCode:

```bash theme={"system"}
opencode
```

Run this in the TUI:

```bash theme={"system"}
/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:

```bash theme={"system"}
curl https://api.aiohub.org/v1/models \
  -H "Authorization: Bearer sk-your-api-key"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Official references

* [OpenCode install](https://opencode.ai/docs)
* [OpenCode config](https://opencode.ai/docs/config)
* [OpenCode providers](https://opencode.ai/docs/providers)