OpenCode : Vanille → Pro — Guide de configuration

Un guide concret et sans hype pour transformer une installation OpenCode basique en un environnement de codage professionnel. Basé sur des recherches de praticiens (Data Leads Future, DEV.to, Medium) et des tests réels. Dernière mise à jour : 2026-07-29

1. Installation

OpenCode est écrit en Go, distribué sous forme de binaire unique. Il nécessite bun comme dépendance d'exécution.

Installation en une commande

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

En cas d'échec

OpenCode dépend de bun. Si votre environnement bloque l'installation automatique :

npm install -g bun

Puis réessayez le script d'installation, ou installez manuellement depuis opencode.ai.

Ce que vous obtenez

• opencode CLI — TUI terminal (Bubble Tea, piloté au clavier)
• OpenCode Desktop — application graphique autonome (recommandée pour un usage quotidien)
• Extensions VS Code / Cursor / Zed — via le marché des extensions

Application de bureau vs TUI

L'application de bureau est nettement plus efficace pour le travail quotidien. Elle prend nativement en charge les Workspaces (git worktrees), ce que la TUI ne fait pas. Cela justifie à lui seul l'installation.

Cela dit, installez d'abord la CLI — certains plugins et outils de configuration vérifient la présence de la commande OpenCode lors de l'initialisation.

Vérifier l'installation

opencode --version

Vous devriez voir un numéro de version (actuel : 1.15+).

2. Configuration du fournisseur (Critique)

C'est l'erreur la plus courante. OpenCode prend en charge plus de 75 fournisseurs LLM, mais la façon dont vous les configurez est importante.

❌ La mauvaise méthode

Vous voyez que votre modèle n'est pas dans la liste, alors vous cliquez sur "Fournisseur personnalisé" et vous remplissez : l'identifiant du modèle, l'URL de base, la clé API.

Pourquoi cela pose problème : OpenCode n'a aucune information sur la taille de la fenêtre de contexte de votre modèle, son prix ou ses capacités. Des fonctionnalités comme la compression automatique du contexte, la gestion des tokens et la sélection intelligente des modèles cessent de fonctionner.

✅ La bonne méthode

1. Ouvrez OpenCode Desktop → Paramètres → Fournisseurs
2. Faites défiler jusqu'en bas de la liste
3. Cliquez sur "Afficher plus de fournisseurs"
4. Trouvez votre fournisseur réel (ex. OpenRouter, Together, Fireworks, ou un relais)
5. Saisissez la clé API de ce fournisseur

Une fois configuré, tous les modèles de ce fournisseur apparaissent avec leurs métadonnées complètes — taille du contexte, tarifs, tout. Les plugins de gestion de contexte fonctionnent correctement.

Trouver l'ID de votre fournisseur

Après avoir configuré via "Afficher plus de fournisseurs", l'ID du fournisseur n'apparaît pas dans l'interface. Ce n'est pas grave. OpenCode l'enregistre ici :

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

Ouvrez ce fichier. L'ID de votre fournisseur et votre clé API s'y trouvent. Vous aurez besoin de l'ID du fournisseur si vous configurez ultérieurement des agents personnalisés.

Modèles gratuits disponibles

La plateforme OpenCode propose actuellement des modèles gratuits sans clé API requise :

• Big Pickle — un modèle furtif disponible gratuitement
• DeepSeek V4 Flash — MoE optimisé pour l'efficacité (284B total, 13B activés), bon en codage
• Nemotron 3 Super — MoE hybride de NVIDIA (120B, 12B activés)

Ces offres sont limitées dans le temps. Consultez opencode.ai pour connaître le statut actuel.

Fournisseurs payants recommandés

3. Configuration du terminal et de la plateforme

macOS / Linux

OpenCode détecte $SHELL automatiquement. Aucune action nécessaire.

Windows

OpenCode Desktop utilise PowerShell par défaut. Deux problèmes :

1. Certains environnements d'entreprise bloquent PowerShell
2. Les paramètres régionaux non anglais provoquent des erreurs d'encodage des caractères lors de l'exécution de commandes shell

Correctif : Définissez la variable d'environnement SHELL avec votre terminal préféré :

SET SHELL="%windir%\system32\cmd.exe"

Ou utilisez WSL / Git Bash. C'est la variable SHELL qu'OpenCode vérifie.

Configuration shell recommandée

Pour les agents de codage IA, utilisez un shell qui :

• A accès à vos outils de développement (git, node, npm, python, etc.)
• Ne déforme pas la sortie UTF-8
• Peut gérer de longues sorties de commandes

Sur toutes les plateformes, bash ou zsh avec les outils de développement standards installés est le choix le plus sûr.

4. AGENTS.md — Votre mémoire à long terme

C'est la chose la plus impactante que vous puissiez mettre en place. Cela s'appelle "Règles" dans l'interface d'OpenCode, mais c'est en réalité la mémoire à long terme du projet pour l'IA.

Ce que fait AGENTS.md

Trois choses :

1. Verrouille les faits et décisions du projet. Sans AGENTS.md, chaque nouvelle session oblige le LLM à analyser l'intégralité du projet pour comprendre l'architecture. C'est un énorme gaspillage de tokens.

2. Réduit les distributions de probabilité (diminue les hallucinations). Les LLM génèrent des réponses de manière probabiliste. AGENTS.md déplace les distributions vers vos conventions.

3. Évite les erreurs de dépendances. Si vous utilisez uv avec --prerelease=allow, écrivez-le dans AGENTS.md. Le LLM ne retombera pas sur pip install.

Créer AGENTS.md

Exécutez /init dans OpenCode. L'IA analyse votre projet et génère une base de référence. Modifiez-la ensuite manuellement.

Ce que contient un bon AGENTS.md

# Présentation du projet

Eva est une plateforme d'assistant IA personnel. Monorepo avec :
- Backend Python (FastAPI) dans `/backend`
- Frontend React + TypeScript dans `/frontend`
- Plugins serveur MCP dans `/mcp-servers`

# Pile technologique

- Python 3.14+ avec async/await partout
- React 19 + Tailwind CSS 4 pour l'interface
- Bun comme environnement d'exécution JavaScript

# Commandes

- `uv sync --prerelease=allow` — synchroniser les dépendances Python
- `bun install` — installer les dépendances frontend
- `pytest` — exécuter les tests Python

# Conventions de codage

- Indications de type : toujours utiliser `str | None`, jamais `Optional[str]`
- Imports : bibliothèque standard d'abord, puis tiers, puis locale
- Async : utiliser `async def` pour toutes les fonctions liées aux E/S

# Règles d'architecture

- Les services backend communiquent par passage de messages, pas par imports directs
- Les serveurs MCP sont des processus autonomes, pas des modules embarqués

5. Les deux agents intégrés : Plan vs Build

Agent Build (par défaut)

Accès complet aux outils. À utiliser pour les tâches claires et sans ambiguïté. Ne pas utiliser pour les tâches complexes ou ambiguës.

Agent Plan

Mode d'analyse en lecture seule. Pose des questions de clarification. Produit un plan d'exécution.

Flux de travail professionnel : Chaque nouvelle exigence → Agent Plan → fichier plan → nouvelle session → Agent Build

6. Mode flux de travail de planification (v1.15+)

Activer le mode

export OPENCODE_EXPERIMENTAL_PLAN_MODE=true

Les 5 phases

7. Workspaces — Développement parallèle

L'application de bureau dispose des Workspaces, basés sur les git worktrees. Clic droit sur l'icône du projet → Activer le Workspace.

8. Discipline des sessions

Le problème : La pourriture du contexte — les LLM ont un biais de primauté et de récence.

La règle : Après chaque étape importante, commencez une nouvelle session.

9. Commandes personnalisées

Définissez des commandes slash personnalisées avec des fichiers .opencode/commands/<nom>.md contenant un frontmatter et le paramètre $ARGUMENTS.

10. Agents personnalisés

• Global : ~/.config/opencode/agents/<nom>.md
• Projet : <projet>/.opencode/agents/<nom>.md

11. Flux de travail pour les projets complexes

Matin : Synchronisation et planification → Exécution : Build → Révision : Boucler

12. Estimation des coûts

OpenCode Go : 10 $/mois d'abonnement.

13. Parcours de progression

Étape 2 : OpenSpec (SDD) → Étape 3 : Réflexion → Étape 4 : Ingénierie de boucles

Liste de vérification pour démarrer rapidement

• OpenCode CLI + Desktop installés
• Fournisseur configuré via "Afficher plus de fournisseurs"
• /init exécuté pour créer AGENTS.md
• OPENCODE_EXPERIMENTAL_PLAN_MODE=true activé
• Au moins un agent personnalisé créé