Installer OpenCode en local et le brancher sur OpenRouter

À la fin de ce tutoriel, OpenCode tourne dans votre terminal, branché sur un modèle open-weight (Qwen3.6 35B A3B) via une clé OpenRouter, avec des permissions qui vous font valider chaque modification et chaque commande. Il s'adresse aux développeurs et aux équipes techniques qui veulent évaluer un agent de code open source sur leur poste avant d'en généraliser l'usage. En option, vous remplacerez OpenRouter par un modèle servi sur votre propre machine.

OpenCode est un agent de code open source sous licence MIT, développé dans le dépôt GitHub anomalyco/opencode. Il existe en interface terminal, en application de bureau (bêta) et en extension d'éditeur ; ce tutoriel couvre l'interface terminal.

Prérequis

• Un système compatible : macOS, Linux ou Windows. Sous Windows, la documentation d'OpenCode recommande WSL, pour de meilleures performances d'accès aux fichiers et une compatibilité complète du terminal.
• Un émulateur de terminal récent : la documentation cite WezTerm, Alacritty, Ghostty et Kitty.
• Node.js et npm, uniquement si vous installez par npm. La documentation n'impose pas de version.
• Un compte OpenRouter crédité : le modèle choisi est facturé au token, au prix affiché sur sa page.
• Git, pour créer le dépôt de test de la section 4.

1. Installer OpenCode

La méthode mise en avant par la documentation est le script d'installation :

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

Avant d'exécuter un script téléchargé, prenez l'habitude de le lire : téléchargez-le d'abord (curl -fsSL https://opencode.ai/install -o install-opencode.sh), parcourez-le, puis lancez bash install-opencode.sh. Le script installe le binaire dans ~/.opencode/bin et ajoute ce dossier au PATH dans le fichier de configuration de votre shell (.zshrc, .bashrc…), sauf si vous passez l'option --no-modify-path. Ouvrez ensuite un nouveau terminal pour que la commande opencode soit trouvée.

Autres méthodes documentées :

# Avec npm (ou bun, pnpm, yarn)
npm install -g opencode-ai

# Avec Homebrew, sur macOS et Linux
brew install anomalyco/tap/opencode

Pour Homebrew, la documentation recommande le tap anomalyco/tap : la formule officielle brew install opencode est maintenue par l'équipe Homebrew et mise à jour moins souvent. Sous Windows sans WSL, choco install opencode, scoop install opencode et npm install -g opencode-ai sont également documentés.

Vérifiez l'installation :

opencode --version

La commande doit afficher la version installée. Notez qu'OpenCode télécharge ses mises à jour au démarrage : si votre équipe veut figer une version pendant une évaluation, ajoutez "autoupdate": false (ou "notify" pour être seulement prévenu) dans sa configuration.

2. Créer une clé OpenRouter et la brancher

Créer la clé

1. Créez un compte sur openrouter.ai, puis ajoutez du crédit depuis la page Credits.
2. Ouvrez la page Keys et cliquez sur Create API Key.
3. Donnez un nom explicite à la clé (par exemple « opencode-poste-dev ») et fixez une limite de crédit. OpenRouter recommande une limite sur chaque clé : sans elle, une clé qui fuite ou un agent qui boucle peut consommer tout le solde.
4. Copiez la clé.

Pour vérifier la clé et la limite restante, OpenRouter documente un appel à GET /api/v1/key :

curl https://openrouter.ai/api/v1/key -H "Authorization: Bearer $OPENROUTER_API_KEY"

Brancher la clé dans OpenCode

La méthode documentée par OpenCode passe par la commande /connect de l'interface. Lancez opencode, tapez :

/connect

Cherchez OpenRouter, puis collez la clé. Elle est enregistrée dans ~/.local/share/opencode/auth.json, hors de votre dépôt. L'équivalent en ligne de commande est opencode auth login, et opencode auth list affiche les fournisseurs enregistrés.

Autre possibilité : au démarrage, OpenCode charge aussi les clés présentes dans les variables d'environnement. Le nom attendu pour OpenRouter est OPENROUTER_API_KEY, celui que déclare le registre Models.dev sur lequel s'appuie OpenCode :

export OPENROUTER_API_KEY="sk-or-v1-..."

OpenCode lit également un fichier .env placé dans le projet. Si vous l'utilisez, vérifiez qu'il figure dans le .gitignore.

Choisir le modèle

De nombreux modèles OpenRouter sont préchargés. Dans l'interface, /models ouvre le sélecteur ; en ligne de commande, opencode models openrouter liste les identifiants disponibles. Ce tutoriel utilise Qwen3.6 35B A3B, un modèle open-weight publié sous licence Apache 2.0 sur Hugging Face et signalé comme compatible avec l'appel d'outils dans le catalogue d'OpenRouter. OpenCode désigne un modèle sous la forme <fournisseur>/<modèle> : ici openrouter/qwen/qwen3.6-35b-a3b.

Pour en faire le modèle par défaut du projet, créez un fichier opencode.json à la racine du dépôt :

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openrouter/qwen/qwen3.6-35b-a3b"
}

La configuration globale se trouve dans ~/.config/opencode/opencode.json ; celle du projet a la priorité sur elle.

3. (Option) Utiliser un modèle local

OpenCode documente l'usage de serveurs locaux compatibles OpenAI, dont Ollama et LM Studio. Avec Ollama, téléchargez le même modèle en version locale (environ 23 Go selon sa page sur ollama.com), puis démarrez le serveur avec une fenêtre de contexte d'au moins 64 000 tokens, le minimum que la documentation d'Ollama indique pour OpenCode :

ollama pull qwen3.6:35b-a3b
OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Si l'application Ollama tourne déjà, réglez plutôt la longueur de contexte dans ses paramètres. Déclarez ensuite le fournisseur dans opencode.json :

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3.6:35b-a3b": {
          "name": "Qwen3.6 35B A3B (local)"
        }
      }
    }
  }
}

Le modèle apparaît alors dans /models sous ollama/qwen3.6:35b-a3b. La documentation d'Ollama propose aussi un raccourci, ollama launch opencode, qui lance OpenCode avec une configuration en ligne sans modifier votre fichier. Pour LM Studio, la structure est identique avec "baseURL": "http://127.0.0.1:1234/v1". Comptez sur une machine bien dotée : la documentation d'Ollama indique environ 24 Go de mémoire vidéo pour faire tourner qwen3.6 en local.

4. Premier lancement

Créez un dépôt jetable, avec un bug volontaire. Avant de lancer OpenCode, copiez-y le fichier opencode.json présenté dans la section « Sécurité et confidentialité » : l'agent vous demandera alors votre accord avant chaque modification et chaque commande.

mkdir ~/essai-opencode && cd ~/essai-opencode
git init
printf 'def add(a, b):\n    return a - b\n\nprint(add(2, 3))\n' > calc.py
git add calc.py && git commit -m "État initial"
opencode

Commencez en mode Plan : appuyez sur Tab (un indicateur s'affiche en bas à droite). Ce mode est restreint : il sert à analyser et à proposer, et ne modifie pas le code sans votre accord. Demandez :

Lis calc.py, explique ce que fait le script et identifie le bug. Ne modifie rien.

Revenez ensuite en mode Build avec Tab et demandez la correction, puis, si Python 3 est installé, l'exécution de python3 calc.py pour vérifier que le script affiche 5.

Ce qu'il faut observer :

• les appels d'outils (lecture, édition, commande) affichés au fil de l'eau ;
• les demandes d'approbation avant chaque écriture et chaque commande ;
• le résultat réel, que vous contrôlez vous-même avec git diff après être sorti d'OpenCode.

Si la modification ne vous convient pas, /undo l'annule (et /redo la rétablit). OpenCode s'appuie pour cela sur Git : ces commandes ne fonctionnent que dans un dépôt Git, d'où le git init ci-dessus. La commande /init génère un fichier AGENTS.md décrivant le projet, que la documentation recommande de versionner.

Sécurité et confidentialité

Où vont les données. Avec OpenRouter, chaque requête contient vos instructions, le contenu des fichiers que l'agent a lus et la sortie des commandes exécutées. Elle transite par OpenRouter, puis par l'un des fournisseurs qui servent le modèle (la liste figure sur la page du modèle). Selon sa documentation, OpenRouter ne conserve ni les prompts ni les réponses sauf activation explicite de la journalisation, mais conserve des métadonnées (tokens, latence). La conservation côté fournisseur varie : dans les paramètres de confidentialité, vous pouvez limiter le routage aux fournisseurs à conservation nulle (ZDR). Avec Ollama ou LM Studio, l'inférence se fait sur localhost : le contenu envoyé au modèle ne quitte pas la machine.

Ce qu'OpenCode garde en local. Les sessions et messages sont stockés dans ~/.local/share/opencode/. La commande /share crée en revanche un lien public et synchronise la conversation sur les serveurs d'OpenCode. Pour l'interdire sur un projet, ajoutez "share": "disabled" dans son opencode.json et versionnez le fichier.

La clé. Jamais dans le dépôt : gardez-la dans auth.json ou dans une variable d'environnement, avec une limite de crédit. En cas de fuite, supprimez-la depuis la page Keys et créez-en une autre.

Les permissions. Par défaut, OpenCode est permissif : la plupart des actions, dont l'édition de fichiers et les commandes bash, s'exécutent sans demander. Seuls l'accès hors du dossier de travail (external_directory) et les boucles répétitives (doom_loop) déclenchent une question, et la lecture des fichiers .env est refusée. Pour une évaluation, faites valider chaque action :

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openrouter/qwen/qwen3.6-35b-a3b",
  "share": "disabled",
  "permission": {
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow"
    }
  }
}

La dernière règle qui correspond l'emporte : placez toujours "*" en premier. N'utilisez pas l'option --auto (approbation automatique) hors d'un environnement jetable.

L'isolement. Travaillez sur un dépôt de test ou un clone dédié. Pour aller plus loin, OpenCode publie une image Docker (ghcr.io/anomalyco/opencode) : l'exécuter dans un conteneur ou une machine virtuelle qui ne voit que le dépôt de test limite ce que l'agent peut atteindre.

Dépannage

• ProviderModelNotFoundError : l'identifiant du modèle est mal formé. Il doit suivre le format <fournisseur>/<modèle>, par exemple openrouter/qwen/qwen3.6-35b-a3b. opencode models liste ceux auxquels vous avez accès.
• Erreur d'authentification : relancez /connect, vérifiez la clé et opencode auth list. Une erreur 402 d'OpenRouter signale un crédit ou une limite de clé épuisés.
• AI_APICallError : les paquets de fournisseurs mis en cache peuvent être obsolètes. Supprimez ~/.cache/opencode et relancez OpenCode.
• OpenCode ne démarre pas : consultez les journaux dans ~/.local/share/opencode/log/, lancez opencode --print-logs, puis mettez à jour avec opencode upgrade.
• Le modèle local n'appelle pas d'outils : la fenêtre de contexte d'Ollama est probablement trop petite. Relancez le serveur avec OLLAMA_CONTEXT_LENGTH=64000 et vérifiez la colonne CONTEXT de ollama ps.

Aller plus loin

• Comparer OpenCode avec les autres harness : Claude Code vs Hermes vs Opencode : lequel choisir ?
• Installer les deux autres harness de cette série : Hermes Agent et pi.
• Apprendre à cadrer, relire et sécuriser le travail d'un agent de code en équipe, sur votre propre dépôt : formation Claude Code pour les équipes de développement.