OpenCode | OpenModels Documentation

Use OpenModels as a custom OpenAI-compatible provider for OpenCode. OpenCode keeps its terminal UI, CLI, agents, tools, permissions, and project configuration. OpenModels provides the model endpoint, API key, model IDs, and credit-based billing.

This guide focuses on OpenCode calling OpenModels through https://api.getopenmodels.com/v1.

When to use this

Use this setup when you want:

OpenCode as an AI coding agent for a local repository.
OpenModels as the upstream model marketplace.
One ale-... OpenModels API key for OpenCode model calls.
OpenAI-compatible chat completions through @ai-sdk/openai-compatible.
Project-level config you can commit without committing secrets.

Prerequisites

OpenCode installed on the machine where you will work.
An OpenModels API key in the ale-... format.
Available credits in your OpenModels account.
A supported OpenModels chat or coding model ID, such as qwen3.5-flash or kimi-k2.7-code.

1. Install OpenCode

Install OpenCode with the official install script:

curl -fsSL https://opencode.ai/install | bash

Other supported install paths include npm, Bun, pnpm, Yarn, Homebrew, Arch Linux packages, Chocolatey, Scoop, Docker, and release binaries.

2. Add the OpenModels credential

The most direct way is to use OpenCode’s /connect flow and choose Other:

/connect

Use this provider ID:

openmodels

Then paste your OpenModels API key:

ale-...

OpenCode stores credentials in its auth store, not in opencode.json.

For headless or project-local setups, you can also use an environment variable:

export OM_API_KEY="ale-..."

Do not commit real ale-... keys to an application repository.

3. Configure OpenModels as a provider

Create or update opencode.json in the project root:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openmodels/kimi-k2.7-code",
  "small_model": "openmodels/qwen3.5-flash",
  "provider": {
    "openmodels": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenModels",
      "options": {
        "baseURL": "https://api.getopenmodels.com/v1"
      },
      "models": {
        "kimi-k2.7-code": {
          "name": "kimi-k2.7-code",
          "limit": {
            "context": 256000,
            "output": 8192
          }
        },
        "qwen3.5-flash": {
          "name": "qwen3.5-flash",
          "limit": {
            "context": 1000000,
            "output": 8192
          }
        }
      }
    }
  }
}

If you are using OM_API_KEY instead of /connect, add apiKey under options:

"options": {
  "baseURL": "https://api.getopenmodels.com/v1",
  "apiKey": "{env:OM_API_KEY}"
}

Notes:

openmodels is the provider ID. It must match the ID used in /connect.
npm: "@ai-sdk/openai-compatible" tells OpenCode to use the OpenAI-compatible chat completions adapter.
model uses the provider_id/model_id format.
small_model is used for cheaper lightweight tasks, such as title generation.
limit.context and limit.output help OpenCode understand available context. Check the OpenModels Models page before updating these values.

4. Start OpenCode

Run OpenCode from your project directory:

opencode

If this is a new project, initialize project instructions:

/init

Then verify the selected model:

/models

Choose openmodels/kimi-k2.7-code or another OpenModels model from your config.

5. Use OpenModels model IDs

The model IDs in opencode.json must match OpenModels model IDs.

Good starting points:

Use case	Model
Low-cost smoke tests	`qwen3.5-flash`
Coding-heavy repository work	`kimi-k2.7-code`
Larger context or reasoning	Pick a high-context chat or coding model from the Models page

For production-like usage, check pricing, context, routes, supply, and live status in the Models page before relying on a model.

6. Keep secrets out of project config

Project-level opencode.json can be committed when it only contains provider config, model IDs, and limits. Do not commit API keys.

Use one of these instead:

/connect, which stores credentials in OpenCode’s auth store.
options.apiKey: "{env:OM_API_KEY}", with OM_API_KEY set outside the repository.

Troubleshooting

Symptom	Check
OpenCode cannot find the provider	Confirm the `provider.openmodels` key exists in `opencode.json`
Authentication fails	Confirm `/connect` used provider ID `openmodels`, or set `OM_API_KEY` when using `{env:OM_API_KEY}`
OpenModels returns `401`	Confirm the API key is a valid `ale-...` key and still active
Balance or billing failure	Add credits to the OpenModels account before sending requests
Model does not appear in `/models`	Confirm the model is listed under `provider.openmodels.models`
Model call fails	Confirm `options.baseURL` is exactly `https://api.getopenmodels.com/v1`
Context warnings or truncation	Update `limit.context` based on the OpenModels Models page