Where do I store the OpenCode API key?

In the process environment variable ({env:NORMAHUB_API_KEY}), never as plain text in the config. The config can be committed, the secret never.

Which model is better for coding?

Flagships for architecture, smaller models for routine. Current IDs and prices are in the models catalog.

Agent hit 402. What is it?

Either the owner balance or the key spend limit is exhausted. Check both in the dashboard — they are different entities.

Does it work from Russia without VPN?

Yes. OpenCode talks to api.normahub.cc directly, billing comes from your balance.

How do I switch models?

Run /models and pick a NormaHub entry such as normahub/gpt-5.6-sol. The choice applies to the current session; the model field in opencode.json sets the default for new work. One-shot runs accept opencode run --model provider/model.

What is small_model for?

A cheaper model for lightweight background tasks like title generation. Set it alongside model so routine calls stop burning flagship tokens.

Project config vs global config — which wins?

Project opencode.json overrides the global ~/.config/opencode/opencode.json for matching fields. Keep the key in the environment in both cases and never commit secrets.

No model is available / Model unavailable — what now?

No model available means nothing enabled is selectable — finish the provider setup and pick a model in /models. Model unavailable means the provider is inactive or the ID is wrong — check the models map key, not just the sent ID.

OpenCode with NormaHub: custom provider, no VPN

What is OpenCode

OpenCode is an AI coding assistant that runs in the terminal and IDE. It supports many model providers through one configuration.

You can connect NormaHub as a provider and use GPT, Claude and other models right inside OpenCode. Russian version: Подключение OpenCode.

1. Get an API key

Create a dedicated agent key in the NormaHub dashboard and keep it in the OpenCode process environment. Copy the key once — it is not shown again.

2. Environment variable

Linux/macOS:

export NORMAHUB_API_KEY="your_api_key"

Windows (PowerShell):

$env:NORMAHUB_API_KEY="your_api_key"

For persistence add the variable to ~/.bashrc, ~/.zshrc or Windows system variables.

3. OpenCode config

Open the OpenCode config (~/.config/opencode/opencode.json) and add the NormaHub provider:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "normahub/gpt-5.6-sol",
  "provider": {
    "normahub": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "NormaHub",
      "options": {
        "baseURL": "https://api.normahub.cc/v1",
        "apiKey": "{env:NORMAHUB_API_KEY}"
      },
      "models": {
        "gpt-5.6-sol": {
          "name": "GPT 5.6 Sol",
          "limit": { "context": 200000, "output": 65536 }
        }
      }
    },
    "normahub-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "NormaHub (Claude)",
      "options": {
        "baseURL": "https://api.normahub.cc/v1",
        "apiKey": "{env:NORMAHUB_API_KEY}",
        "headers": {
          "Authorization": "Bearer {env:NORMAHUB_API_KEY}"
        }
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6",
          "limit": { "context": 200000, "output": 8192 }
        }
      }
    }
  }
}

This config adds two providers:

normahub — GPT models via the OpenAI-compatible API
normahub-anthropic — Claude models via the Anthropic API

Replace model names with current ones from the models catalog. Field names vary by OpenCode release: newer builds use providers, settings.baseURL and package where older configs show provider, options and npm — the values (endpoint, key reference, model IDs) stay the same.

4. Restart and verify

Fully restart OpenCode after saving. You can now pick NormaHub models in the interface:

normahub/gpt-5.6-sol
normahub-anthropic/claude-sonnet-4-6
normahub-anthropic/claude-opus-4-6

Run OpenCode, select a NormaHub model and send a test request. Prefer the install script for automatic setup.

Agent cost control

An agent session is dozens of calls: file reads, planning, edits, checks. Every call bills full project context as input plus output at the model rate — long flagship sessions are the most expensive configuration possible. Recipe: short sessions, a small default model, the flagship used sparingly, controlled max_tokens, and a usage history review after the first days. Exact rates are in the catalog, the formula in the token cost guide.

5. Selecting models

Selectors use provider/model: normahub/gpt-5.6-sol or normahub-anthropic/claude-sonnet-4-6. Run /models instead of guessing IDs — it lists only enabled models whose provider is available in the current project. Set model for the default and small_model for cheap background tasks; switching a session never rewrites the config file.

6. Config locations and precedence

Global config lives at ~/.config/opencode/opencode.json; a project opencode.json or .opencode/opencode.json overrides matching global fields. The OPENCODE_CONFIG variable points at a custom override file. Non-conflicting settings merge; the key itself always stays in the environment (NORMAHUB_API_KEY), never as plain text next to a committed config.

Common errors

401 Unauthorized — invalid or revoked API key
402 Payment Required — insufficient balance
403 Forbidden — model unavailable to your key
429 Too Many Requests — rate or spend limit exceeded
503 Service Unavailable — model provider temporarily down
No model is available — nothing enabled is selectable; finish provider setup and choose a model in /models
Model unavailable — provider inactive or wrong ID; check the models map key and restart OpenCode so the config reloads

On errors check balance and available models in the dashboard, and keep the errors guide at hand for 401/402/429.

Connecting OpenCode