OpenCode Custom Provider: Connect Tokenhot and Fix Missing Models

To connect Tokenhot as an OpenCode custom provider, choose a model that supports the API format you need, provide your Tokenhot key, and use the configuration for your installed OpenCode version. V1 and V2 use different native provider fields. Mixing them can send you looking for an authentication problem before the provider is configured correctly.

This guide covers OpenAI Chat Completions models. The examples are based on official documentation checked on November 3, 2026; they have not been tested against a live Tokenhot account.

1. Check your OpenCode version

Run this in the terminal where you use OpenCode:

opencode --version

Both major versions use the opencode command. Choose the matching example below; the command name alone does not identify the version. See the official V1 introduction and V2 migration guide.

Installed version	Native provider map	Package field	Connection options
OpenCode 1.x	provider	npm	options
OpenCode 2.x	providers	package	settings

V2 also accepts supported V1 configuration through its compatibility layer. That does not make native V2 configuration suitable for V1. Keep a backup before migrating, and avoid maintaining two competing definitions for the same provider. The shared online schema includes both shapes, so schema validation alone cannot establish which one your installed binary supports. V2 migration guidance, configuration schema.

2. Choose a model and prepare your API key

Open our model catalog and confirm the exact model ID and its supported protocol. Use a model explicitly supporting OpenAI Chat Completions for these examples. A familiar model name is not enough to establish compatibility.

Obtain or select your key in our API key console. Set TOKENHOT_API_KEY in the same terminal that will launch OpenCode. For example, these interactive prompts keep the key out of the command you type into shell history.

In Bash on macOS or Linux:

read -r -s -p "Tokenhot API key: " TOKENHOT_API_KEY
printf '\n'
export TOKENHOT_API_KEY

In PowerShell:

$tokenhotSecret = Read-Host "Tokenhot API key" -AsSecureString
$env:TOKENHOT_API_KEY = [System.Net.NetworkCredential]::new("", $tokenhotSecret).Password
Remove-Variable tokenhotSecret

These assignments apply to the current terminal and processes started from it. OpenCode V2 normally connects to a shared background server, which may already be running without this variable. Use the standalone first-run command in step 4 so its private server starts from the terminal containing your key. For a shared-server setup, the credential must reach the server process, not just a new terminal client. V2 background-service behavior. Keep real keys out of configuration files committed to Git, screenshots, and support messages.

3. Save the configuration for your version

Create opencode.jsonc in the project directory, or merge the relevant provider into your existing file. The usual global location is ~/.config/opencode/opencode.jsonc; on Windows, ~ refers to your user home. Project and global settings can combine, so inspect both when the result differs from the file you just edited. Managed settings can also take precedence. V1 configuration, V2 configuration.

Replace YOUR_CHAT_COMPLETIONS_MODEL_ID with the exact ID from our catalog. It is a placeholder, not a model you can call. The display name can be changed independently.

OpenCode V2

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "tokenhot": {
      "name": "Tokenhot",
      "env": ["TOKENHOT_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.tokenhot.ai/v1"
      },
      "models": {
        "YOUR_CHAT_COMPLETIONS_MODEL_ID": {
          "name": "My Tokenhot coding model"
        }
      }
    }
  }
}

The package path is @opencode/ai/providers/openai-compatible, including the scope and slash exactly as shown. The env list names the variable supplying the credential; it does not contain the key itself. This follows the official V2 custom-provider example.

OpenCode V1

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenhot": {
      "name": "Tokenhot",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.tokenhot.ai/v1",
        "apiKey": "{env:TOKENHOT_API_KEY}"
      },
      "models": {
        "YOUR_CHAT_COMPLETIONS_MODEL_ID": {
          "name": "My Tokenhot coding model"
        }
      }
    }
  }
}

Here, OpenCode substitutes the environment variable into options.apiKey. An unset variable becomes an empty string. See V1 custom providers and variable substitution.

The base URL ends in /v1; do not append /chat/completions to it. A model that only accepts OpenAI Responses needs a different provider configuration. Do not treat a successful Chat Completions setup as evidence that Responses, images, reasoning, or tools work on the same route.

4. Select the model and check a first response

For V2, start a private server from the terminal containing the key:

opencode --standalone

This documented mode avoids reconnecting your first test to an older shared server with a different environment. It does not change the default shared-service setting. For V1, start from the same terminal with:

opencode

Inside OpenCode, open the model picker:

/models

Select the model under Tokenhot. Its full identifier combines the provider ID and model ID: tokenhot/YOUR_CHAT_COMPLETIONS_MODEL_ID, with your actual model ID substituted. V1 model selection, V2 models.

For your first request, use a disposable project without private files and ask for a short text response without tools. A normal reply establishes that this request worked. Before using the setup for coding, separately check the tool calls, streaming, context size, and image input your workflow requires. Those capabilities differ by model and route.

If the provider or model does not appear

Work through these checks before replacing the key:

1. Version and fields: compare opencode --version with the chosen block. In V2, check the package path; in V1, check npm and options.
2. File location: confirm you started in the intended project. Check project, global, and custom-path configuration for another definition.
3. Model entry: replace the placeholder key under models, not just its name. The display label does not change the upstream model ID.
4. Credential source: confirm the variable exists without printing its value. For V1, restart OpenCode from that terminal. For V2, run opencode --standalone there for the isolated check above, or verify that your shared server receives the credential. Reopening only the V2 client may reuse an older server environment.
5. Visibility controls: inspect provider/model filtering and managed policy. V1 documents enabled_providers, disabled_providers, and model allow/block lists; V2 supports model disabled flags and provider policies. Do not remove an organizational restriction to make a model appear. V1 configuration, V2 models, V2 providers.

If you use V1's /connect credential route instead of the environment-variable example, its provider ID must match the configuration key exactly. Saving a credential alone does not define a custom provider's endpoint and models. V1 provider setup.

If the model appears but the request fails

Symptom	What to inspect next
Authentication error	The key's validity, the terminal that launched OpenCode, and whether the configured credential belongs to Tokenhot
Unknown model or unsupported route	Exact model ID, account access, and Chat Completions support in our catalog
Package-loading error	The version-specific package identifier, then the error's package-resolution details
Timeout or interrupted stream	Network/proxy settings and the request's error details; use our streaming timeout guide
Text works but tools fail	The model's tool support and the actual tool exchange; text success is only the first check

If you need help, retain the OpenCode version, operating system, redacted provider configuration, model ID, and exact error text. Remove credentials and private prompts before sharing. Start with our API setup guide to verify the account and endpoint details.