OpenCode : clé API, authentification, Astra, Grok, proxy et mot de passe Web

Les questions d’authentification dans OpenCode se ressemblent souvent, mais elles concernent des couches différentes. La clé API d’un fournisseur de modèles n’est ni une connexion OpenCode Go, ni un flux OAuth xAI, ni le mot de passe qui protège opencode web.

Ce guide sépare clairement ces mécanismes et fournit une configuration fonctionnelle de fournisseur personnalisé pour BetterToken. Vous y trouverez un exemple prêt à copier pour gpt-6-astra, les réglages réseau pour Linux et Astra Linux, l’authentification directe de Grok et la bonne méthode pour sécuriser l’interface Web d’OpenCode.

OpenCode évolue rapidement. Avant tout usage en production, comparez les commandes ci-dessous à la documentation OpenCode actuelle et vérifiez l’identifiant exact du modèle dans le catalogue BetterToken.

Réponse rapide

Votre objectif	Emplacement ou commande correcte
Enregistrer interactivement la clé API d’un fournisseur	Exécuter /connect dans OpenCode
Voir les fournisseurs enregistrés	Exécuter opencode auth list
Définir un fournisseur personnalisé, une Base URL et des modèles	opencode.json ou opencode.jsonc
Utiliser BetterToken	Base URL : https://www.bettertoken.ai/v1
Utiliser GPT-6 Astra	ID du modèle : gpt-6-astra, s’il est disponible pour votre compte
Se connecter à OpenCode Go	/connect → OpenCode Go → https://opencode.ai/auth
S’authentifier directement auprès de xAI/Grok	/connect → xAI → abonnement OAuth ou clé API
Protéger OpenCode Web	Définir OPENCODE_SERVER_PASSWORD avant opencode web
Utiliser un proxy régional ou d’entreprise	Définir HTTP_PROXY, HTTPS_PROXY et NO_PROXY

Avant de commencer

Préparez les éléments suivants :

• une version récente d’OpenCode ;
• une clé API réservée aux tests plutôt qu’une clé de production partagée ;
• l’identifiant exact du modèle affiché dans le catalogue du fournisseur ;
• un petit dépôt de test dans lequel l’agent ne pourra pas modifier de fichiers importants ;
• un terminal pouvant joindre l’installateur OpenCode et le point de terminaison API.

Traitez une clé API comme un mot de passe. Ne collez jamais une vraie clé dans un prompt, une capture d’écran, une issue, un article ou un dépôt Git.

Installer OpenCode

L’installateur officiel fonctionne sous macOS et Linux :

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

Vous pouvez aussi utiliser npm :

npm install -g opencode-ai

Sous Windows, OpenCode recommande WSL pour une meilleure compatibilité. Chocolatey et Scoop sont également documentés :

choco install opencode

scoop install opencode

Vérifiez l’installation :

opencode --version

Un numéro de version doit s’afficher. Si le shell indique command not found, rouvrez le terminal et vérifiez que le répertoire d’installation figure bien dans PATH.

Comprendre les quatre couches d’authentification

1. Clé API du fournisseur

Cette clé autorise les appels à BetterToken, xAI, OpenAI ou à un autre fournisseur de modèles. OpenCode peut l’enregistrer via /connect ou la lire depuis une variable d’environnement référencée dans le fichier de configuration.

2. Authentification OpenCode Go ou OpenCode Zen

OpenCode Go et Zen sont des services de modèles exploités par OpenCode. Leur flux ouvre https://opencode.ai/auth, où vous vous connectez, terminez si nécessaire la configuration de facturation, copiez une clé API et la collez dans /connect.

Cette clé est indépendante de votre clé BetterToken.

3. Authentification xAI/Grok

Le flux fournisseur actuel d’OpenCode accepte soit un abonnement xAI éligible via OAuth avec code d’appareil, soit une clé API xAI en paiement à l’usage. Il s’agit d’une connexion directe à xAI, pas d’une connexion BetterToken.

4. Mot de passe OpenCode Web

OPENCODE_SERVER_PASSWORD protège le serveur HTTP local et l’interface navigateur d’OpenCode avec une authentification basique. Il n’autorise aucun appel de modèle et ne remplace pas la clé API d’un fournisseur.

Comment définir une clé API dans OpenCode

OpenCode accepte JSON et JSONC. Les exemples officiels utilisent souvent opencode.json ; JSONC est pratique lorsque vous souhaitez ajouter des commentaires. Retenez surtout que le stockage des identifiants et la définition du fournisseur sont deux choses distinctes.

Méthode 1 : enregistrer la clé avec /connect

Lancez OpenCode dans un répertoire de test sûr :

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

Dans la TUI, exécutez :

/connect

Pour BetterToken :

1. Choisissez Other.
2. Saisissez l’identifiant de fournisseur bettertoken.
3. Collez votre clé API BetterToken dans le champ d’identification.
4. Quittez ou redémarrez OpenCode après avoir ajouté la configuration du fournisseur.

OpenCode stocke les identifiants ajoutés par /connect dans :

~/.local/share/opencode/auth.json

Vérifiez que le fournisseur est enregistré sans afficher le secret :

opencode auth list

L’identifiant utilisé dans /connect doit correspondre exactement à celui de la configuration. Si vous avez saisi bettertoken, la clé du fournisseur dans le fichier doit également être bettertoken.

Méthode 2 : configurer opencode.json ou opencode.jsonc

Utilisez le fichier global si le fournisseur doit être disponible dans tous les projets :

~/.config/opencode/opencode.json

Utilisez un fichier opencode.json ou opencode.jsonc au niveau du projet si un seul dépôt a besoin de son propre modèle ou point de terminaison.

L’exemple suivant utilise BetterToken et l’identifiant API actuel gpt-6-astra :

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

Avant de l’utiliser, vérifiez que gpt-6-astra figure dans le catalogue BetterToken actuel et dans le groupe d’accès de votre compte. Si le catalogue affiche un autre identifiant, remplacez à la fois bettertoken/gpt-6-astra et la clé gpt-6-astra dans models.

N’ajoutez pas /chat/completions à la Base URL. L’adaptateur construit lui-même le chemin de la requête.

Utiliser une variable d’environnement à la place de /connect

Sous macOS ou Linux :

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

Dans PowerShell :

$env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"

Référencez ensuite la variable dans les options du fournisseur :

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/gpt-6-astra",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1",
        "apiKey": "{env:BETTERTOKEN_API_KEY}"
      },
      "models": {
        "gpt-6-astra": {
          "name": "GPT-6 Astra"
        }
      }
    }
  }
}

Cette méthode est plus sûre que l’écriture du secret en clair dans le fichier JSON. Si la variable d’environnement manque, OpenCode la remplace par une chaîne vide, ce qui entraîne généralement une erreur 401.

Pourquoi OpenCode peut ignorer votre configuration

OpenCode fusionne plusieurs sources de configuration. Lorsque le même champ entre en conflit, les sources chargées plus tard remplacent les précédentes. L’ordre le plus utile à connaître est le suivant :

1. valeurs distantes par défaut de l’organisation ;
2. configuration globale dans ~/.config/opencode/opencode.json ;
3. fichier personnalisé indiqué par OPENCODE_CONFIG ;
4. opencode.json ou opencode.jsonc du projet ;
5. contenu inline dans OPENCODE_CONFIG_CONTENT ;
6. paramètres administrés, susceptibles de remplacer les fichiers utilisateur.

Si OpenCode choisit le mauvais modèle ou endpoint, ne supprimez pas des fichiers au hasard. Recherchez toutes les configurations actives et comparez :

• la valeur model de premier niveau ;
• provider.bettertoken.options.baseURL ;
• les clés de modèles dans provider.bettertoken.models ;
• OPENCODE_CONFIG et OPENCODE_CONFIG_CONTENT dans le shell actuel.

Redémarrez OpenCode après toute modification des paramètres du fournisseur.

OpenCode Astra : nom de modèle ou Astra Linux ?

La requête « OpenCode Astra » peut désigner deux choses différentes.

Utiliser GPT-6 Astra dans OpenCode

Si vous parlez du modèle OpenAI, utilisez l’identifiant API exact gpt-6-astra. Avec le fournisseur BetterToken défini plus haut, sélectionnez :

bettertoken/gpt-6-astra

Ouvrez le sélecteur de modèles dans OpenCode :

/models

Si le modèle n’apparaît pas, vérifiez l’identifiant du fournisseur, la table models, votre groupe d’accès BetterToken et le catalogue actuel. Ne déduisez pas un identifiant de modèle à partir de son nom d’affichage.

Exécuter OpenCode sur Astra Linux

La documentation d’OpenCode présente des méthodes d’installation Linux, mais ne publie pas de garantie de prise en charge propre à Astra Linux. Traitez Astra Linux comme un environnement Linux et testez la machine réelle au lieu de supposer sa compatibilité.

Vérifiez l’architecture et les outils nécessaires :

uname -m
command -v curl
command -v bash

Testez ensuite séparément l’installateur et les routes API. Le fait que l’API du modèle soit joignable ne garantit pas que l’installateur OpenCode, le registre npm, GitHub ou le serveur de mise à jour le soient également.

Pour un proxy classique :

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,::1
opencode

NO_PROXY est important, car la TUI communique avec un serveur HTTP OpenCode local. Faire passer le trafic de boucle locale par le proxy peut créer une boucle de connexion ou donner l’impression que l’interface est bloquée.

Si votre organisation utilise une autorité de certification privée :

export NODE_EXTRA_CA_CERTS=/etc/company/ca.pem
opencode

N’inscrivez pas de vraies informations d’identification du proxy dans des scripts shell partagés. Utilisez le gestionnaire de secrets de l’organisation ou une configuration d’environnement protégée.

Authentification Grok dans OpenCode : xAI directe ou passerelle ?

Connexion directe à xAI

Exécutez :

/connect

Choisissez xAI. La documentation actuelle d’OpenCode présente deux méthodes d’authentification :

• un abonnement xAI pris en charge via OAuth avec code d’appareil ;
• une clé API xAI saisie manuellement depuis la console xAI.

Après autorisation, exécutez :

/models

puis sélectionnez un modèle Grok disponible.

Grok via BetterToken ou une autre passerelle

Une passerelle personnalisée ne fonctionne que si elle expose actuellement un modèle Grok valide et le bon protocole. N’inventez pas d’identifiant Grok et ne supposez pas que toutes les passerelles compatibles OpenAI proposent des modèles xAI.

Consultez d’abord le catalogue actif du fournisseur. Si Grok n’y figure pas, utilisez le fournisseur xAI direct d’OpenCode. Les plugins communautaires, comme les extensions d’authentification Grok, sont distincts du flux officiel et doivent être évalués quant à leur maintenance, leurs permissions et leur traitement des identifiants avant installation.

Authentification OpenCode Go

OpenCode Go n’est pas une commande qui authentifie tous les fournisseurs. Il s’agit d’un service d’abonnement d’OpenCode.

Pour le connecter :

1. Exécutez /connect.
2. Choisissez OpenCode Go.
3. Ouvrez https://opencode.ai/auth.
4. Connectez-vous, terminez la facturation si nécessaire et copiez la clé générée.
5. Collez la clé dans OpenCode.
6. Exécutez /models pour choisir l’un des modèles inclus dans l’offre.

Utilisez ce flux uniquement si vous comptez utiliser OpenCode Go. Pour BetterToken, conservez l’identifiant et la clé sous bettertoken.

Mot de passe OpenCode Web : utiliser la variable d’environnement

La recherche opencode web password est fréquente, et certains exemples suggèrent à tort un indicateur de mot de passe -p. La méthode documentée repose sur la variable d’environnement OPENCODE_SERVER_PASSWORD.

Sous macOS ou Linux :

OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' opencode web

Pour définir aussi un nom d’utilisateur personnalisé :

OPENCODE_SERVER_USERNAME='developer' \
OPENCODE_SERVER_PASSWORD='replace-with-a-strong-password' \
opencode web

Dans PowerShell :

$env:OPENCODE_SERVER_USERNAME = "developer"
$env:OPENCODE_SERVER_PASSWORD = "replace-with-a-strong-password"
opencode web

Le nom d’utilisateur par défaut est opencode. Sans mot de passe, un usage strictement local sur 127.0.0.1 peut être acceptable, mais tout accès réseau doit être protégé. Ne liez pas le service à 0.0.0.0 et ne l’exposez pas par tunnel avant d’avoir mis en place l’authentification et les contrôles réseau.

Le mot de passe Web protège le serveur OpenCode. Il ne protège pas votre compte fournisseur si la clé API a fuité ailleurs.

Vérifier la première requête

Redémarrez OpenCode après avoir modifié le JSON :

opencode

Ouvrez le sélecteur de modèles :

/models

Choisissez bettertoken/gpt-6-astra, puis envoyez un prompt court et facile à vérifier :

Retourne uniquement ce JSON et ne modifie aucun fichier : {"tool":"opencode","sum":4}

Une configuration correcte doit satisfaire tous les points suivants :

• OpenCode renvoie un JSON valide ;
• aucun fichier du projet n’est modifié ;
• le modèle sélectionné est bettertoken/gpt-6-astra ;
• une requête correspondante apparaît dans le tableau de bord BetterToken ;
• le modèle, le statut, les tokens d’entrée et de sortie ainsi que le coût semblent cohérents.

Si OpenCode répond mais qu’aucune requête n’apparaît chez BetterToken, une configuration plus prioritaire envoie peut-être l’appel vers un autre fournisseur.

Dépannage

Erreur 401 ou erreur d’identifiants

• Relancez /connect avec l’identifiant de fournisseur bettertoken.
• Exécutez opencode auth list.
• Si vous utilisez {env:BETTERTOKEN_API_KEY}, vérifiez uniquement que la variable existe, sans afficher sa valeur.
• Confirmez que la clé est active et dispose d’un solde ou de permissions suffisants.

Erreur 404 ou chemin API incorrect

La Base URL BetterToken doit être :

https://www.bettertoken.ai/v1

N’ajoutez pas manuellement /chat/completions.

model not found

Vérifiez l’identifiant exact et actuel dans le catalogue de modèles. La valeur model de premier niveau et la clé sous models doivent correspondre au fournisseur et au modèle que vous souhaitez appeler.

Mauvais endpoint ou mauvais modèle

Vérifiez les configurations globale, personnalisée, de projet, inline et administrée. Redémarrez ensuite OpenCode et resélectionnez le modèle avec /models.

OpenCode se bloque lorsque le proxy est actif

Assurez-vous d’exclure les adresses de boucle locale :

export NO_PROXY=localhost,127.0.0.1,::1

OpenCode Web renvoie Unauthorized

Vérifiez que le navigateur utilise le nom d’utilisateur et le mot de passe configurés. Contrôlez aussi si une ancienne valeur de OPENCODE_SERVER_PASSWORD reste dans l’environnement du shell ou si un processus client a hérité d’une valeur différente.

opencode: command not found

Rouvrez le terminal, contrôlez PATH et exécutez la commande de votre gestionnaire de paquets qui affiche le répertoire global des exécutables. Évitez d’installer le même binaire avec plusieurs gestionnaires tant que vous ne savez pas lequel est actif.

Questions fréquentes

Comment définir une clé API dans OpenCode ?

La méthode interactive recommandée est /connect. Pour un fournisseur personnalisé, choisissez Other, saisissez l’identifiant du fournisseur et collez la clé. Vous devez tout de même définir le fournisseur et les modèles dans opencode.json ou opencode.jsonc.

Le fichier s’appelle-t-il opencode.json ou opencode.jsonc ?

OpenCode prend en charge JSON et JSONC. Utilisez JSONC si vous avez besoin de commentaires. Ne gardez qu’une seule configuration de projet active, sauf si vous maîtrisez volontairement la fusion de plusieurs sources.

Où OpenCode stocke-t-il les clés API ?

Les identifiants ajoutés par /connect sont enregistrés dans ~/.local/share/opencode/auth.json. Ne publiez, ne synchronisez et ne commitez pas ce fichier.

Puis-je placer la clé API directement dans la configuration ?

OpenCode accepte options.apiKey, mais un secret en clair dans un fichier JSON suivi par Git présente un risque. Préférez /connect, {env:VARIABLE_NAME} ou {file:path/to/secret}.

L’authentification OpenCode Go est-elle la même que celle du fournisseur ?

Non. OpenCode Go est un service OpenCode distinct. Une clé BetterToken, xAI ou d’un autre fournisseur reste indépendante.

Comment définir un mot de passe OpenCode Web ?

Définissez OPENCODE_SERVER_PASSWORD avant d’exécuter opencode web. La méthode documentée utilise une variable d’environnement, et non un indicateur de mot de passe générique -p.

Comment authentifier Grok dans OpenCode ?

Exécutez /connect, choisissez xAI, puis utilisez soit le flux OAuth d’abonnement pris en charge, soit la saisie manuelle d’une clé API xAI. Une passerelle n’est valable que si elle propose réellement un modèle Grok.

« OpenCode Astra » signifie-t-il GPT-6 Astra ou Astra Linux ?

Les deux sont possibles. Pour le modèle, utilisez gpt-6-astra. Pour Astra Linux, suivez les vérifications d’installation et de réseau Linux, puis validez la version précise de la distribution.

Faut-il un VPN pour utiliser OpenCode depuis la Russie ?

Il n’existe pas de réponse unique, car les téléchargements d’installation, GitHub, npm, le site OpenCode et l’API du modèle empruntent des chemins réseau distincts. Testez chaque chemin séparément et utilisez, si nécessaire, une configuration régionale ou d’entreprise conforme aux règles applicables.

Références officielles

• Présentation et installation d’OpenCode
• Fournisseurs OpenCode et configuration personnalisée
• Configuration, JSONC, priorité et variables
• Réseau et paramètres de proxy
• Authentification OpenCode Web
• Authentification du serveur OpenCode
• Configuration OpenCode avec BetterToken