# Utiliser opencode : le guide pas à pas URL: https://agentvera.dev/fr/blog/how-to-use-opencode/ · Publié: 2026-10-27 Comment utiliser opencode : installation, connexion d’un fournisseur, choix du modèle, Build et Plan, opencode.json, AGENTS.md, serveurs MCP et commandes. **En bref:** - Installez opencode avec le script officiel ou npm, lancez opencode dans un projet, connectez un fournisseur avec /connect et choisissez un modèle avec /models ; tout fournisseur convient, modèles locaux compris. - Tab bascule entre l’agent Build, qui modifie le code et lance des commandes, et l’agent Plan, qui ne peut pas modifier votre code et sert à réfléchir à un changement avant de le faire. - Les réglages vont dans opencode.json (global et par projet), les règles du projet dans AGENTS.md ; les serveurs MCP sous la clé mcp et les commandes personnalisées dans .opencode/commands/. 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](/fr/glossary/coding-agent/ "Qu’est-ce qu’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 | Plateforme | Commande | | --- | --- | | macOS, Linux | `curl -fsSL https://opencode.ai/install \| bash` | | Toute plateforme avec Node.js | `npm install -g opencode-ai` | | macOS, Linux (Homebrew, version 1) | `brew install anomalyco/tap/opencode` | | Windows | `choco install opencode` ou `scoop install 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 : ```bash 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` : ```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](/fr/blog/local-llm-coding-agent/ "Agent 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. | Commande | Raccourci | Ce qu’elle fait | | --- | --- | --- | | `/connect` | | Ajoute un fournisseur | | `/models` | `ctrl+x m` | Choisit un modèle | | `/new` | `ctrl+x n` | Démarre une nouvelle session | | `/sessions` | `ctrl+x l` | Ouvre une session précédente | | `/compact` | `ctrl+x c` | Résume la session pour libérer du contexte | | `/undo` | `ctrl+x u` | Annule le dernier message et ses modifications de fichiers | | `/redo` | `ctrl+x r` | Rétablit ce que vous avez annulé | | `/editor` | `ctrl+x e` | Écrire un long prompt dans votre `$EDITOR` | | `/export` | `ctrl+x x` | Exporte la conversation en Markdown | | `/init` | | Crée ou met à jour `AGENTS.md` | | `/exit` | `ctrl+x q` | Quitte | `/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 ` 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](/fr/glossary/subagent/ "Qu’est-ce qu’un 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 : ```json { "$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 : ```json { "$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. ```markdown # 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](/fr/blog/claude-md-agents-md/ "Écrire CLAUDE.md et AGENTS.md") explique ce qui a sa place dans le fichier. ## Étape 7 : les serveurs MCP [Les serveurs MCP](/fr/blog/what-is-mcp-server/ "Qu’est-ce qu’un serveur 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 : ```json { "$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 ` permet de se connecter à la main. `opencode mcp debug ` 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 : ```markdown --- 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](/fr/agents/opencode/ "opencode dans AgentVera") 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](/fr/features/mcp-manager/ "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](/fr/features/workspace/ "Workspace"), chaque agent dans son propre [git worktree](/fr/glossary/git-worktree/ "Qu’est-ce qu’un git worktree"), pour qu’ils ne se marchent pas sur les fichiers. - **Revue et flows.** Les agents opencode fonctionnent avec la [code review automatique](/fr/features/code-review/ "Code review automatique"), et dans les [flows](/fr/features/flows/ "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](/fr/download/ "Télécharger AgentVera") pour l’essayer. Si votre équipe exécute aussi Claude en CI, [Claude Code GitHub Actions](/fr/blog/claude-code-github-actions/ "Claude Code GitHub Actions") couvre ce côté, et [Utiliser Codex CLI](/fr/blog/how-to-use-codex-cli/ "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. ## Questions fréquentes **opencode est-il gratuit ?** L’installation du CLI est gratuite. Vous payez les modèles que vous utilisez via votre fournisseur : une clé API facturée au token, un abonnement que vous avez déjà comme GitHub Copilot ou ChatGPT Plus/Pro, ou OpenCode Zen. Les modèles locaux via Ollama ne coûtent rien d’autre que votre propre matériel. **Quels modèles opencode peut-il utiliser ?** Ceux de n’importe quel fournisseur pris en charge : Anthropic, OpenAI, Google, GitHub Copilot, OpenRouter, OpenCode Zen et bien d’autres, plus des modèles locaux via un serveur compatible OpenAI comme Ollama. Lancez opencode models pour lister ce que proposent vos fournisseurs connectés. **Quelle différence entre les agents Build et Plan ?** Build est l’agent par défaut et dispose de tous les outils : il modifie des fichiers et lance des commandes. Plan ne peut pas modifier votre code ; il peut seulement écrire des plans Markdown dans .opencode/plans/. Utilisez Plan pour réfléchir à un changement, puis appuyez sur Tab pour passer à Build et le réaliser. **opencode lit-il CLAUDE.md ?** Oui, en solution de repli. Si un projet n’a pas d’AGENTS.md, opencode lit CLAUDE.md, et il se replie aussi sur ~/.claude/CLAUDE.md pour les règles globales. Définissez OPENCODE_DISABLE_CLAUDE_CODE=1 pour désactiver ces replis vers Claude Code. **Où opencode garde-t-il ses réglages et ses connexions ?** Les réglages globaux sont dans ~/.config/opencode/opencode.json et ceux du projet dans opencode.json à la racine du projet ; les deux sont fusionnés. Les identifiants des fournisseurs ajoutés avec /connect sont stockés dans ~/.local/share/opencode/auth.json. --- **À propos d’AgentVera.** AgentVera est une app de bureau pour macOS, Windows et Linux, développée par Solviera Teknoloji. Elle exécute 18 agents de code IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) côte à côte, par projet, dans de vrais terminaux avec les installations et connexions CLI de l’utilisateur. L’offre gratuite inclut des agents illimités. Télécharger: https://agentvera.dev/fr/download/ · Tarifs: https://agentvera.dev/fr/pricing/