Utiliser opencode : le guide pas à pas

Pour utiliser opencode, installez-le avec une seule commande, lancez opencode dans un dossier de projet, connectez un fournisseur de modèles avec /connect, choisissez un modèle avec /models, puis décrivez ce que vous voulez. L’agent Build, actif par défaut, lit votre code, modifie des fichiers et lance des commandes. Appuyez sur Tab pour passer à l’agent Plan quand vous voulez réfléchir à un changement sans toucher au code.

Voilà la boucle de base. Ce guide couvre le reste : les fournisseurs et les modèles locaux, les commandes de la TUI que vous utiliserez tous les jours, les deux agents intégrés, opencode.json, AGENTS.md, les serveurs MCP, les commandes personnalisées et l’utilisation d’opencode à côté d’autres agents. Tout ce qui suit s’appuie sur la documentation officielle d’opencode, telle qu’elle était en octobre 2026.

Ce qu’est opencode

opencode est un agent de code pour le terminal qui n’est lié à aucune entreprise d’IA en particulier. Claude Code utilise les modèles d’Anthropic et Codex ceux d’OpenAI. opencode repose sur l’AI SDK et Models.dev, ce qui lui permet de fonctionner avec des dizaines de fournisseurs et avec des modèles locaux. Vous pouvez utiliser un modèle pour planifier et un autre pour construire, et changer de fournisseur sans apprendre un nouvel outil.

Un mot sur les versions : opencode 2 est sorti, avec sa propre documentation. Les deux versions installent une commande appelée opencode, et vous ne pouvez pas garder les deux sous ce nom. Ce guide suit la version 1, celle qu’installe le paquet npm opencode-ai. L’essentiel vaut aussi pour la version 2. Si vous avez installé opencode via la formule core de Homebrew ou le dépôt principal d’Arch, vous avez probablement la version 2 ; consultez alors la documentation correspondante.

Étape 1 : installer opencode

bun, pnpm et yarn global add opencode-ai fonctionnent aussi. Sous Windows, la documentation recommande de lancer opencode dans WSL pour une meilleure expérience. Un terminal moderne comme WezTerm, Alacritty, Ghostty ou Kitty affiche le mieux la TUI.

opencode ne se met jamais à jour tout seul en arrière-plan. Dans une session, /update installe une version 1 plus récente, ou propose de passer à la version 2 si vous avez déjà la dernière version 1. Depuis le shell, opencode upgrade fait la même chose.

Étape 2 : connecter un fournisseur et choisir un modèle

Placez-vous dans un projet et lancez opencode :

cd my-project
opencode

Lancez ensuite /connect et choisissez un fournisseur. Vous pouvez faire la même chose depuis le shell avec opencode auth login. Les identifiants sont enregistrés dans ~/.local/share/opencode/auth.json, et opencode auth list montre ce qui est connecté. opencode récupère aussi les clés API dans les variables d’environnement et dans un fichier .env du projet.

Quelques choix courants :

• OpenCode Zen : une liste choisie de modèles que l’équipe d’opencode a testés avec l’agent. Connectez-vous sur opencode.ai/auth, ajoutez un moyen de paiement, copiez la clé et collez-la dans /connect. La documentation le conseille aux nouveaux utilisateurs.
• Anthropic : collez une clé API de la Claude Console. La connexion avec un abonnement Claude Pro ou Max n’est pas proposée. Anthropic n’autorise pas les outils tiers à utiliser ces offres de cette façon, et opencode a cessé de fournir les plugins qui le faisaient.
• OpenAI : choisissez « ChatGPT Plus/Pro » pour vous connecter dans le navigateur, ou saisissez une clé API à la main.
• GitHub Copilot : connectez-vous avec un code d’appareil sur github.com/login/device. Certains modèles demandent une offre Copilot supérieure.
• Modèles locaux : ajoutez un fournisseur personnalisé qui pointe vers un serveur compatible OpenAI (voir plus bas).

Une fois un fournisseur connecté, /models (ou ctrl+x m) ouvre le sélecteur de modèles. Depuis le shell, opencode models liste tous les modèles proposés par vos fournisseurs, et opencode models anthropic ceux d’un seul fournisseur. Les modèles s’écrivent sous la forme provider/model, par exemple anthropic/claude-sonnet-5-5. Beaucoup de modèles ont des variantes, comme un effort de raisonnement plus élevé, et ctrl+t passe de l’une à l’autre.

Modèles locaux avec Ollama

Un modèle local est un fournisseur personnalisé 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": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

Si les appels d’outils échouent avec un modèle local, la documentation conseille de porter le num_ctx d’Ollama à environ 16k–32k. Une fenêtre de contexte trop petite en est la cause habituelle. Pour choisir un modèle local au départ, lisez les agents de code avec un LLM local.

Étape 3 : les bases de la TUI

L’écran d’opencode est une conversation avec votre projet. Les quelques éléments que vous utiliserez sans arrêt :

• @ fait une recherche approximative de fichiers et les ajoute à votre message.
• ! en début de ligne lance une commande shell, par exemple !npm test, et place la sortie dans la conversation.
• ctrl+x est la touche leader. La plupart des raccourcis sont ctrl+x suivi d’une lettre.
• Vous pouvez glisser des images dans le terminal pour les inclure.

/undo s’appuie sur Git pour annuler les modifications de fichiers, donc le projet doit être un dépôt Git. Pour reprendre là où vous en étiez depuis le shell, opencode -c rouvre la dernière session et opencode -s <id> en ouvre une précise. Pour les scripts et la CI, opencode run "your prompt" exécute une seule tâche sans la TUI.

Étape 4 : les agents Build et Plan

opencode a deux agents principaux, et Tab bascule de l’un à l’autre :

• Build est l’agent par défaut. Tous ses outils sont activés : il modifie des fichiers, lance des commandes shell et appelle des serveurs MCP.
• Plan est restreint. Il ne peut pas modifier votre code ; les seuls fichiers qu’il peut écrire sont des plans Markdown dans .opencode/plans/. Il peut vous poser des questions pour clarifier.

Pour tout ce qui n’est pas trivial, une bonne habitude consiste à commencer dans Plan, à vous mettre d’accord sur une approche, puis à appuyer sur Tab et à demander à Build de la mettre en œuvre. Il existe aussi deux sous-agents que vous appelez avec @ : @general pour des recherches et des modifications en plusieurs étapes, et @explore pour des recherches rapides en lecture seule dans le code. Chacun s’exécute dans une session enfant. ctrl+x puis la flèche bas permet d’y entrer, et la flèche haut ramène à la session parente. L’entrée du glossaire sous-agent explique pourquoi cela économise du contexte.

Un piège : Plan ne limite pas bash à lui seul. Les commandes shell suivent vos réglages de permissions. De plus, un "edit": "allow" au premier niveau de votre configuration s’applique aussi à Plan, car les règles correspondantes les plus tardives l’emportent. Si vous voulez verrouiller Plan, définissez directement ses permissions :

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": "ask"
      }
    }
  }
}

Vous pouvez créer vos propres agents avec opencode agent create, ou sous forme de fichiers Markdown dans .opencode/agents/ (par projet) ou ~/.config/opencode/agents/ (global). Le nom du fichier devient le nom de l’agent. Le frontmatter définit sa description, son mode (primary ou subagent), son model et sa permission.

Étape 5 : le fichier de configuration

opencode lit opencode.json (ou opencode.jsonc, qui accepte les commentaires). Il y a deux emplacements courants :

• Global : ~/.config/opencode/opencode.json, pour vos valeurs par défaut.
• Projet : opencode.json à la racine du projet, commité avec le code.

Les fichiers sont fusionnés, pas remplacés, et les réglages du projet l’emportent en cas de chevauchement. Une configuration de projet pratique :

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "small_model": "anthropic/claude-haiku-5-5",
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "npm test *": "allow"
    }
  },
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

• model est le modèle par défaut. small_model sert aux tâches légères, comme les titres de session.
• permission prend allow, ask ou deny pour chaque outil, avec des motifs pour bash. Le dernier motif correspondant l’emporte, donc placez "*" en premier.
• instructions ajoute d’autres fichiers de règles en plus d’AGENTS.md. Les globs et les URL fonctionnent.

Les valeurs peuvent venir de l’environnement avec {env:VAR} ou d’un fichier avec {file:path}, si bien que les clés n’ont jamais besoin de figurer dans la configuration. Par défaut, la plupart des actions sont autorisées. La lecture des fichiers .env et l’accès à des dossiers hors du projet demandent d’abord votre accord. opencode --auto approuve tout ce qui n’est pas explicitement refusé ; ne l’utilisez donc que là où vous seriez à l’aise de laisser l’agent travailler sans surveillance.

Les réglages de la TUI, comme le thème et les raccourcis clavier, se trouvent dans un fichier tui.json séparé.

Étape 6 : AGENTS.md

AGENTS.md contient les règles de votre projet : comment builder, tester et lancer le lint, les conventions à suivre, les dossiers à ne pas toucher. Lancez /init et opencode analyse le projet et en écrit un pour vous. Relisez-le, élaguez-le et commitez-le.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- API handlers live in src/api/; one file per route.
- Never edit files in src/generated/.

Les règles globales valables pour tous les projets vont dans ~/.config/opencode/AGENTS.md. Si vous venez de Claude Code, opencode se replie sur le CLAUDE.md du projet quand il n’y a pas d’AGENTS.md, et lit aussi ~/.claude/CLAUDE.md et ~/.claude/skills/. Définissez OPENCODE_DISABLE_CLAUDE_CODE=1 pour désactiver ce comportement. Écrire CLAUDE.md et AGENTS.md explique ce qui a sa place dans le fichier.

Étape 7 : les serveurs MCP

Les serveurs MCP donnent de nouveaux outils à opencode : un navigateur, un gestionnaire de tickets, une recherche dans la documentation. Ils se déclarent sous la clé mcp. Un serveur local est une commande qu’opencode démarre ; un serveur distant est une URL :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    },
    "my-remote": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_MCP_TOKEN}"
      }
    }
  }
}

opencode mcp add ajoute un serveur de façon interactive, et opencode mcp list affiche ce qui est configuré et si la connexion fonctionne. Les serveurs distants qui utilisent OAuth se connectent automatiquement, et opencode mcp auth <name> permet de se connecter à la main. opencode mcp debug <name> aide quand un serveur refuse de se connecter.

Chaque serveur ajoute ses outils au contexte de chaque requête, et certains gros serveurs, comme le serveur MCP de GitHub, en ajoutent beaucoup. N’activez que les serveurs dont vous avez besoin, et utilisez "enabled": false pour garder un serveur configuré mais désactivé.

Étape 8 : les commandes personnalisées

Une commande personnalisée est un prompt que vous devriez sinon retaper. Placez un fichier Markdown dans .opencode/commands/ (par projet) ou ~/.config/opencode/commands/ (global) ; le nom du fichier devient la commande :

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

Enregistré sous .opencode/commands/test.md, ce fichier devient /test. Les commandes acceptent des arguments : $ARGUMENTS correspond à tout ce qui suit le nom de la commande, $1, $2 et ainsi de suite sont des arguments individuels, !`git diff --staged` insère la sortie d’une commande shell, et @src/file.ts inclut un fichier. Vous pouvez aussi définir des commandes sous la clé command dans opencode.json avec un template. Si une commande personnalisée porte le même nom qu’une commande intégrée, c’est la commande intégrée qui l’emporte.

Pièges courants

• « No provider » au premier lancement. Rien n’est encore connecté. Lancez /connect.
• Des modifications en mode Plan. Un "edit": "allow" global atteint aussi Plan. Définissez agent.plan.permission explicitement.
• /undo n’annule pas les fichiers. Le dossier n’est pas un dépôt Git.
• Deux versions d’opencode en conflit. Homebrew core installe la version 2 et npm la version 1, sous le même nom de commande. Vérifiez opencode --version et n’en gardez qu’une.
• Des sessions lentes et coûteuses. Trop de serveurs MCP, ou une session trop longue. Désactivez des serveurs et utilisez /compact ou /new.

opencode dans les panneaux d’AgentVera

Une seule session opencode se suit facilement. Plusieurs agents à la fois, certains sur opencode, d’autres sur Claude Code ou Codex, c’est là que les onglets du terminal deviennent gênants. AgentVera est une application de bureau qui exécute ces CLI côte à côte dans de vrais terminaux, avec vos propres installations et connexions. Sa prise en charge d’opencode fonctionne ainsi :

• Vos fournisseurs, votre connexion. Vous vous connectez aux fournisseurs dans opencode lui-même (/connect ou opencode auth login), et chaque fournisseur connecté, modèles locaux compris, apparaît dans la liste de modèles d’AgentVera, regroupé par fournisseur. Les variantes de modèles apparaissent comme options d’effort. Si opencode n’est pas installé, AgentVera l’installe avec npm i -g opencode-ai.
• Une session par agent. Chaque agent opencode a sa propre session, donc dupliquer un agent crée une branche de sa conversation au lieu de la partager. /compact fonctionne comme d’habitude.
• Votre opencode.json reste intact. Le rôle de l’agent, les serveurs MCP ajoutés dans le MCP manager d’AgentVera et le navigateur d’AgentVera sont transmis sous forme de configuration supplémentaire et fusionnés avec la vôtre.
• Panneaux et worktrees. Lancez opencode à côté de Claude Code dans la grille du workspace, chaque agent dans son propre git worktree, pour qu’ils ne se marchent pas sur les fichiers.
• Revue et flows. Les agents opencode fonctionnent avec la code review automatique, et dans les flows (Pro et Team), la réponse d’un agent peut être transmise automatiquement à un autre. Par exemple, un modèle bon marché planifie et un modèle plus puissant construit.

La grille, les worktrees, la code review et le MCP manager sont dans l’offre gratuite. Téléchargez AgentVera pour l’essayer. Si votre équipe exécute aussi Claude en CI, Claude Code GitHub Actions couvre ce côté, et Utiliser Codex CLI est le même guide pour l’agent d’OpenAI.

En résumé

Pour utiliser opencode, installez-le, lancez opencode dans un projet, connectez un fournisseur avec /connect et choisissez un modèle avec /models. Utilisez Plan pour réfléchir et Build pour modifier le code, et passez de l’un à l’autre avec Tab. Mettez vos valeurs par défaut dans opencode.json, les règles du projet dans AGENTS.md, vos outils sous mcp et vos prompts récurrents dans .opencode/commands/. Ensuite, utiliser opencode consiste surtout à choisir le bon modèle pour chaque tâche, et il vous laisse en changer quand vous le voulez.