OpenCode

OpenCode connects to TokenFlux through a custom OpenAI-compatible provider. Requests are charged to your TokenFlux balance.

This guide was tested with OpenCode 1.19.3 and gpt-6-luna for streaming replies.

Before you startCopy Anchor Link

1. Start with OpenCode installed. Configuration details are in the official custom provider guide and configuration reference.
2. Create and copy a key on the web app’s API keys page. The full key is shown only once.
3. Check that your balance is above zero on Billing.
4. Copy a model ID from Models and pricing and check its supported protocols.

Configure the providerCopy Anchor Link

Set the key in Bash or Zsh:

export TOKENFLUX_API_KEY="YOUR_TOKENFLUX_KEY"

Create or update opencode.json in your project directory:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenflux": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenFlux",
      "options": {
        "baseURL": "https://tokenflux.ai/v1",
        "apiKey": "{env:TOKENFLUX_API_KEY}"
      },
      "models": {
        "YOUR_MODEL_ID": { "name": "YOUR_MODEL_ID" }
      }
    }
  }
}

Replace YOUR_TOKENFLUX_KEY with the key you copied. Keep the key out of Git.

OpenCode reads the key through {env:TOKENFLUX_API_KEY}. The @ai-sdk/openai-compatible provider sends Chat Completions requests. Merge the tokenflux entry into the existing provider object if you already have a configuration.

Choose a modelCopy Anchor Link

Replace both YOUR_MODEL_ID values with a catalog model that supports Chat Completions and tool calls. Use tokenflux/YOUR_MODEL_ID with --model, or start OpenCode and select the model with /models.

Verify the connectionCopy Anchor Link

Run these commands in a scratch directory. If the client asks for file access, check the path before you approve it.

printf 'TOKENFLUX_GUIDE_OK\n' > marker.txt
opencode run --model tokenflux/YOUR_MODEL_ID \
  "Read marker.txt with the read tool and return its contents"

The reply should contain TOKENFLUX_GUIDE_OK. Check the model, key, token count and cost on Usage. Delete marker.txt after the test.

TroubleshootingCopy Anchor Link

The provider does not appear. Check that the file is named opencode.json and contains provider.tokenflux.models. Run OpenCode from that project directory.

401. Check that the environment variable is available to the process. If you previously used /connect, check the saved credential with opencode auth list and update it with /connect.

The request uses Responses. Use @ai-sdk/openai-compatible for this Chat Completions setup. The @ai-sdk/openai adapter has different protocol behavior.

401, 429 or a model error. Check that the key is enabled, the full model ID is correct, and your account has balance and available rate limits. Do not switch models automatically.

API referenceCopy Anchor Link

See Chat Completions, Models and API overview.