OpenCode en Russie : configuration de l'API et première requête

Ce qu'il faut pour démarrer OpenCode en Russie

OpenCode est un agent de programmation pour le terminal. Il lit les fichiers du projet, utilise le modèle sélectionné et peut agir dans le dépôt. Pour le premier lancement, il vous faut :

• macOS, Linux ou Windows avec accès à une méthode d'installation officielle ;
• votre propre API Key BetterToken ;
• le Model ID actuel du catalogue de modèles BetterToken ;
• un répertoire de test où vérifier sans risque la réponse de l'agent.

Dans ce schéma, BetterToken traite la requête API externe. Cela ne garantit pas la disponibilité du site OpenCode, du fichier d'installation, de GitHub ou des mises à jour. Depuis la Russie, vous pouvez vous connecter au BetterToken API Endpoint sans VPN ; cela ne s'applique pas aux sites et téléchargements tiers.

Installer OpenCode depuis une source officielle

Choisissez une méthode. Node.js n'est nécessaire que pour l'installation par npm.

macOS et Linux : installateur officiel

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

npm

npm install -g opencode-ai

Homebrew

brew install anomalyco/tap/opencode

OpenCode recommande son propre tap, car la formule brew install opencode maintenue par Homebrew peut évoluer ultérieurement.

Windows

La documentation officielle propose Chocolatey ou Scoop :

choco install opencode

scoop install opencode

Après l'installation, vérifiez que la commande est disponible :

opencode --version

La version doit s'afficher sans command not found. Cet article ne fixe pas de numéro précis, car il change avec les versions publiées.

Fonctionnement de /connect et de opencode.json

OpenCode stocke séparément les credentials et les réglages de provider.

• /connect enregistre l'API Key dans ~/.local/share/opencode/auth.json.
• Le fichier global ~/.config/opencode/opencode.json définit les providers et les modèles de l'utilisateur.
• Un opencode.json à la racine du projet ne modifie que ce projet.

Les fichiers de configuration sont fusionnés. En cas de conflit, la source appliquée plus tard remplace la précédente. Pour une configuration locale ordinaire, l'ordre important est : configuration globale → fichier indiqué par OPENCODE_CONFIG → opencode.json du projet. Les réglages gérés par une organisation ont leur propre priorité maximale.

1. Enregistrer l'API Key avec /connect

Lancez OpenCode dans le répertoire de test :

mkdir opencode-first-test
cd opencode-first-test
opencode

Dans la TUI, exécutez :

/connect

Choisissez Other, saisissez l'identifiant de provider bettertoken, puis collez votre API Key dans le champ de credential. N'ajoutez pas la vraie clé au prompt, à opencode.json, à une capture d'écran ou à Git.

Après l'enregistrement, quittez OpenCode et assurez-vous que le provider est enregistré :

opencode auth list

La commande doit afficher le provider sans révéler la clé.

2. Ajouter un provider BetterToken

Pour configurer tous les projets, créez ou mettez à jour :

~/.config/opencode/opencode.json

Si le provider ne sert qu'à un dépôt, placez opencode.json à sa racine. Configuration minimale :

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/YOUR_MODEL_ID",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

Remplacez YOUR_MODEL_ID par l'identifiant exact du catalogue BetterToken actuel. La même valeur doit apparaître dans model, comme clé de l'objet models et dans son name. N'ajoutez pas /chat/completions à la Base URL : OpenCode et le package @ai-sdk/openai-compatible construisent la requête eux-mêmes.

Les commandes de configuration automatique détaillées et les limites actuelles des groupes de modèles sont dans la documentation BetterToken pour OpenCode. Le Model ID reste un espace réservé, car la liste des modèles disponibles change.

3. Vérifier quel fichier a priorité

Un opencode.json de projet peut remplacer le modèle ou le provider global. Si OpenCode choisit un endpoint inattendu, vérifiez dans cet ordre :

1. ~/.config/opencode/opencode.json ;
2. la valeur de OPENCODE_CONFIG, si la variable est définie ;
3. opencode.json du projet actuel ou du répertoire parent le plus proche jusqu'à la racine Git.

Ne supprimez pas des fichiers au hasard. Comparez les champs model, provider.bettertoken.options.baseURL et provider.bettertoken.models dans toutes les configurations trouvées.

Exécuter et vérifier la première requête

Redémarrez OpenCode après une modification du JSON :

opencode

Ouvrez le sélecteur de modèles avec :

/models

Choisissez bettertoken/YOUR_MODEL_ID, puis envoyez une requête courte dont le résultat est facile à vérifier :

Renvoyez uniquement du JSON : {"tool":"opencode","sum":4}. Ne modifiez pas les fichiers.

La première requête est confirmée lorsque quatre contrôles concordent :

• OpenCode renvoie du JSON valide et ne modifie pas les fichiers ;
• le modèle bettertoken/YOUR_MODEL_ID est sélectionné dans la TUI ;
• une requête avec le modèle et le statut attendus apparaît dans le BetterToken Dashboard ;
• le Dashboard montre les tokens d'entrée, de sortie et de cache applicables, ainsi que le débit correspondant.

Le Dashboard ne doit pas servir de dépôt pour le prompt ou la réponse complète : il s'agit des métadonnées de consommation et d'usage des tokens. Si l'entrée n'apparaît pas, la réponse a pu venir d'un autre provider à cause d'un remplacement de configuration.

Corriger les erreurs courantes

opencode: command not found

Fermez puis rouvrez le terminal. Après une installation npm, vérifiez que le répertoire global de npm est dans PATH. Ne lancez pas un second installateur avant d'avoir déterminé où le premier binaire a été installé.

401 ou erreur de credential

Exécutez de nouveau /connect et choisissez l'identifiant de provider bettertoken. Vérifiez le résultat avec opencode auth list. Ne collez pas la clé dans la ligne de commande ou le JSON pour un test rapide.

404 ou erreur d'API

provider.bettertoken.options.baseURL doit contenir cette Base URL :

https://www.bettertoken.ai/v1

N'ajoutez pas /chat/completions. Si l'URL est correcte, redémarrez OpenCode et répétez la courte requête.

model not found

Vérifiez le Model ID exact dans la documentation actuelle et le catalogue. Le champ supérieur model doit être bettertoken/YOUR_MODEL_ID, et provider.bettertoken.models doit contenir une clé avec le même YOUR_MODEL_ID.

OpenCode utilise un autre modèle ou endpoint

Cela indique généralement un remplacement de configuration. Comparez le fichier global, OPENCODE_CONFIG et le fichier du projet. Le réglage du projet a la priorité la plus élevée parmi les fichiers standard. Après correction, redémarrez complètement OpenCode et vérifiez à nouveau /models et le Dashboard.

FAQ

Faut-il enregistrer l'API Key dans opencode.json ?

Non. Pour une configuration normale, utilisez /connect : OpenCode enregistre le credential dans ~/.local/share/opencode/auth.json. Le fichier de configuration peut rester sans clé réelle.

Quelle Base URL faut-il pour OpenCode ?

Pour le provider OpenAI-compatible BetterToken, utilisez https://www.bettertoken.ai/v1. C'est une Base URL : /chat/completions n'est pas ajouté manuellement.

Faut-il choisir le opencode.json global ou de projet ?

Le fichier global convient à un provider et à un modèle communs. Un fichier de projet convient lorsqu'un dépôt nécessite un autre Model ID ou un autre ensemble d'autorisations. En cas de conflit, le fichier de projet remplace le global.

Faut-il un compte OpenCode pour le provider BetterToken ?

Un Custom Provider utilise le credential du service API sélectionné. BetterToken fournit votre propre API Key, mais ne remplace ni le site, ni le compte, ni les autres services OpenCode. Vérifiez les exigences actuelles de l'outil dans la documentation officielle d'OpenCode.