Configuration OpenCode

1. Qu’est-ce qu’OpenCode et que faut-il préparer ?

OpenCode est un agent de codage IA open source. Il peut lire un dépôt, modifier du code et exécuter des commandes dans le terminal. Il peut aussi être utilisé avec une application de bureau, une interface Web ou des extensions IDE.

Avant de connecter OpenCode via RouteAPI, préparez de préférence :

Un terminal fonctionnel
Votre clé RouteAPI
Un modèle disponible dans la console RouteAPI et adapté aux tâches de codage
Choisissez en priorité un modèle compatible OpenAI-compatible et prenant en charge les appels d’outils.

2. Installer OpenCode

Installer la CLI

Si vous utilisez macOS / Linux / WSL, la méthode d’installation officiellement recommandée est :

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

Si vous préférez une installation globale via Node.js, vous pouvez aussi utiliser :

npm install -g opencode-ai

Si vous utilisez un environnement Windows PowerShell natif, exécutez directement :

npm install -g opencode-ai

Vérifier l’installation

opencode --version

Si un numéro de version s’affiche, OpenCode CLI est installé correctement.

3. Méthode recommandée : enregistrer d’abord la clé, puis écrire la configuration du projet

La documentation officielle OpenCode recommande d’enregistrer d’abord les identifiants avec /connect, puis de déclarer le provider et le model dans le fichier de configuration. Pour une passerelle comme RouteAPI qui n’est pas dans la liste intégrée, choisissez simplement Other.

Enregistrer la clé RouteAPI dans OpenCode

Lancez d’abord OpenCode :

opencode

Puis exécutez dans la session :

/connect

Terminez ensuite les étapes dans l’ordre :

Choisissez Other.
Renseignez routeapi comme provider ID.
Collez votre clé RouteAPI.

Les identifiants sont automatiquement écrits par OpenCode dans le fichier local ~/.local/share/opencode/auth.json. En général, il n’est pas nécessaire de le modifier manuellement.

Créer `opencode.json` à la racine du projet

La documentation officielle OpenCode prend en charge à la fois la configuration globale ~/.config/opencode/opencode.json et le fichier opencode.json à la racine du projet. Pour le travail en équipe, il est généralement préférable de placer la configuration non sensible à la racine du projet.

{
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "routeapi": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "RouteAPI",
          "options": {
            "baseURL": "https://www.routeapi.ai/v1"
          },
          "models": {
            "your-routeapi-model-id": {
              "name": "RouteAPI Model"
            }
          }
        }
      },
      "model": "routeapi/your-routeapi-model-id"
}

Dans cette configuration :

routeapi : ID unique du provider personnalisé, qui doit correspondre exactement au provider ID saisi pendant /connect.
npm : utilisez @ai-sdk/openai-compatible pour /v1/chat/completions ; utilisez @ai-sdk/openai pour /v1/responses.
options.baseURL : https://www.routeapi.ai/v1
models : la clé doit être l’ID réel du modèle disponible dans la console RouteAPI, pas son nom d’affichage.
model : le format du modèle par défaut est provider_id/model_id, ici routeapi/your-routeapi-model-id.

4. Si vous ne voulez pas utiliser `/connect` : utiliser une variable d’environnement

Si vous préférez que la clé provienne d’une variable d’environnement, vous pouvez aussi renseigner directement options.apiKey dans opencode.json. Cette notation de variable est prise en charge par la documentation officielle OpenCode.

4.1 Définir la variable d’environnement

Si vous utilisez bash, zsh ou sh sous macOS / Linux / WSL :

export ROUTEAPI_KEY="votre clé RouteAPI"

Si vous utilisez Windows PowerShell :

$env:ROUTEAPI_KEY="votre clé RouteAPI"

4.2 Référencer la variable d’environnement dans `opencode.json`

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
"routeapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "RouteAPI",
      "options": {
        "baseURL": "https://www.routeapi.ai/v1",
        "apiKey": "{env:ROUTEAPI_KEY}"
      },
      "models": {
        "your-routeapi-model-id": {
          "name": "RouteAPI Model"
        }
      }
}
  },
  "model": "routeapi/your-routeapi-model-id"
}

5. Choisir le modèle et lancer OpenCode

Une fois la configuration terminée, vous pouvez choisir le modèle et lancer OpenCode ainsi :

Lancez OpenCode :

opencode

Exécutez dans la session :

/models

Choisissez le modèle sous routeapi. Si model est déjà défini dans opencode.json, OpenCode l’utilise par défaut.

Pour changer temporairement de modèle uniquement dans la session courante, vous pouvez aussi utiliser un argument de ligne de commande :

opencode -m routeapi/your-routeapi-model-id

Si vous voulez définir un modèle moins coûteux pour des tâches légères comme la génération de titres, vous pouvez ajouter :

{
  "small_model": "routeapi/your-small-model-id"
}

6. Dépannage courant

Exécutez opencode auth list pour vérifier que les identifiants routeapi ont bien été enregistrés localement.
Si votre provider personnalisé n’apparaît pas dans /models, vérifiez d’abord que le provider ID saisi pendant /connect correspond exactement à routeapi dans opencode.json.
Si le modèle apparaît mais que les requêtes retournent une erreur de protocole, vérifiez en priorité le paquet npm choisi : /v1/chat/completions utilise @ai-sdk/openai-compatible, tandis que /v1/responses utilise @ai-sdk/openai.
Si vous rencontrez sous Windows des accès fichiers lents, un comportement de terminal anormal ou des chemins incohérents, privilégiez l’exécution d’OpenCode dans WSL.
Pour comparer avec d’autres méthodes d’intégration client RouteAPI, consultez aussi le guide de configuration Codex, le guide de configuration Cursor et le guide de configuration Claude Code.