Passer à OpenCode 2.0 : migrer votre config v1, vos plugins et vos sessions

Name

Soren Atelier

Mis à jour le 04/11/2026

La réponse courte : sauvegardez vos dossiers OpenCode, passez à la dernière version 1.x, puis lancez la mise à jour majeure.

# 1. Sauvegarder la config et les données (les sessions sont dans le dossier data)
cp -R ~/.config/opencode ~/opencode-v1-config-backup
cp -R ~/.local/share/opencode ~/opencode-v1-data-backup
 
# 2. Passer d'abord à la dernière 1.x (--major existe depuis la v1.19.0)
opencode upgrade
 
# 3. Passer à OpenCode 2
opencode upgrade --major

Dans l’interface terminal, /update fait la même chose. Si vous préférez une installation propre, supprimez d’abord le paquet v1, puis utilisez l’une des commandes d’installation v2 de l’étape 3.

La plupart des réglages v1 continuent de fonctionner. Trois choses cassent volontairement : les plugins v1 ne se chargent pas, l’API serveur est nouvelle, et tui.json est remplacé par cli.json. Deux changements plus discrets surprennent souvent : la v2 ne lit plus CLAUDE.md, et elle autorise par défaut l’accès aux dossiers hors du projet. La suite du guide traite chacun de ces points, ainsi que les bugs connus des premières semaines de la 2.x.

Ce que nous avons vérifié, et ce que nous n’avons pas vérifié : le 25 octobre 2026, nous avons vérifié le côté v1 sur macOS avec OpenCode 1.18.19 installé. Nous avons lu ses commandes upgrade, export, session et debug paths. Nous avons aussi lu les données du registre npm pour @opencode/cli 2.1.4, ainsi que les issues GitHub et les réponses des mainteneurs citées plus bas. Nous n’avons pas exécuté OpenCode 2 pour ce guide. Tout ce qui concerne le comportement de la v2 vient du guide de migration (opens in a new tab) officiel, de la documentation v2 (opens in a new tab), de l’annonce d’OpenCode 2.0 (opens in a new tab) et de ces réponses des mainteneurs. Chaque source est liée. Le 4 novembre 2026, nous avons revérifié les versions, les pages de release et les fils d’issues avec @opencode/cli 2.2.5 et opencode-ai 1.19.5.

Faut-il mettre à jour maintenant ?

OpenCode 2.0 est arrivé sur npm le 11 septembre 2026, sous le nom @opencode/cli. Beaucoup d’utilisateurs v1 qui l’avaient installé via npm ou le script d’installation ne l’ont vu qu’en octobre (les utilisateurs de Homebrew core l’ont reçu plus tôt ; voir le piège Homebrew à l’étape 3). La raison : la commande opencode upgrade --major est arrivée dans la v1.19.0 le 11 octobre, et l’équipe a annoncé la 2.0 le 14 octobre. L’annonce a atteint 888 points sur Hacker News. Depuis le 11 octobre, le dépôt a reçu plus de 4 000 nouvelles issues, dont 130 mentionnent la 2.0.

Les deux versions sont désormais publiées en parallèle. opencode-ai sur npm reste la v1 (1.19.5 au 28 octobre). @opencode/cli est la v2 (2.2.5 au 30 octobre). Depuis la v2.2.0 (27 octobre), les builds 2.x apparaissent aussi sur GitHub Releases (opens in a new tab), mais la release marquée Latest reste une 1.x. C’est voulu : la v1 cherche ses mises à jour via la release Latest, et l’équipe ne veut pas que la mise à jour automatique de la v1 fasse basculer les utilisateurs vers la 2.x (#57675 (opens in a new tab)).

Étape 1 : sauvegarder avant de toucher à quoi que ce soit

Le guide de migration officiel recommande de garder une copie de votre installation v1 pendant les tests. Il ne précise pas quoi copier. Sur macOS et Linux, opencode debug paths liste les dossiers. Notre installation 1.18.19 affichait :

Copiez les deux premiers (les commandes en haut de cette page). Quittez d’abord OpenCode, pour que la base de sessions (opencode.db et son fichier -wal) soit copiée dans un état cohérent. Copiez aussi les opencode.json et dossiers .opencode/ de niveau projet qui comptent pour vous. Ils restent dans vos dépôts, donc git les suit déjà dans la plupart des cas.

Pour garder une copie portable d’une conversation importante, exportez-la depuis la v1 avant la mise à jour :

opencode session list
opencode export <sessionID> > my-session.json

opencode export écrit la session au format JSON. Ajoutez --sanitize pour retirer les données sensibles de la transcription et des fichiers avant de partager le fichier.

Étape 2 : passer à la dernière 1.x

opencode upgrade --major n’existe qu’à partir de la v1.19.0. Sur notre installation 1.18.19, opencode upgrade --help n’affichait aucun flag --major. Si vous êtes en 1.18 ou plus ancien, lancez d’abord une mise à jour simple :

opencode --version
opencode upgrade

Vérifiez ensuite que opencode --version affiche 1.19.x. Depuis la v1.19.0, les mises à jour ne s’installent plus toutes seules : une installation ancienne reste ancienne tant que vous ne lancez pas cette commande.

Étape 3 : mettre à jour ou installer la v2

Mise à jour sur place (depuis la 1.19.x) :

opencode upgrade --major

Installation propre. Le guide de migration demande de supprimer d’abord une installation v1 gérée par un gestionnaire de paquets, car la v1 et la v2 ne s’installent pas côte à côte par défaut. Choisissez ensuite l’une des commandes v2 officielles :

# Installeur officiel (remplace le binaire v1)
curl -fsSL https://opencode.ai/v2/install | bash
 
# Homebrew (notez la formule -v2 ; supprimez d'abord une installation v1 via brew)
brew uninstall opencode
brew install anomalyco/tap/opencode-v2
 
# npm (nouveau nom de paquet)
npm uninstall -g opencode-ai
npm install -g @opencode/cli

Les pièges des gestionnaires de paquets :

• Nom du paquet npm. La v1 s’appelle opencode-ai. La v2 s’appelle @opencode/cli. Si vous lancez npm install -g opencode-ai aujourd’hui, vous obtenez toujours la 1.19.5.
• Homebrew core ou le tap. brew install opencode (sans tap) installe OpenCode 2 depuis le 28 septembre, donc brew upgrade fait déjà passer cette installation à la 2.x sans --major. La formule 1.x est anomalyco/tap/opencode et la formule 2.x est anomalyco/tap/opencode-v2. Elles entrent en conflit, donc lancez brew uninstall opencode avant d’installer l’autre.
• Scripts d’installation. Le paquet npm v2 utilise un script postinstall pour choisir le binaire natif. Avec Bun ou pnpm, ajoutez --trust (Bun) ou --allow-build=@opencode/cli (pnpm). Sans ce flag, le binaire manque.
• Deux noms de commande. Le paquet npm enregistre à la fois opencode et opencode2 dans son champ bin (nous avons vérifié les métadonnées du registre).
• mise n’installe la v2 qu’à partir de mise 2026.10.9. Les versions plus anciennes de mise installent OpenCode 1.
• Les gestionnaires de paquets Windows (Scoop, Chocolatey) ne sont pas pris en charge pour la v2, et opencode upgrade --major ne peut pas faire basculer ces installations. Téléchargez le binaire CLI Windows autonome ou l’application desktop depuis la page d’installation v2 (opens in a new tab), ou utilisez WSL. Un signalement en chinois d’une v2 qui se fige sous WSL (#55033 (opens in a new tab)) a été fermé le 16 octobre faute de détails.
• Docker : des images versionnées existent, par exemple ghcr.io/anomalyco/opencode:2.0.0.

Lancez opencode --version et vérifiez qu’il affiche 2.x.

Étape 4 : vérifier ce que la v2 a repris de votre config v1

Vous n’avez pas à réécrire votre config. La v1 et la v2 lisent les mêmes emplacements (~/.config/opencode/opencode.json, le opencode.json du projet, .opencode/). La v2 convertit les noms de champs v1 en mémoire et ne réécrit pas vos fichiers. Au premier démarrage de la v2, les réglages globaux de tui.json passent dans un nouveau ~/.config/opencode/cli.json. Vos fichiers v1 restent tels quels.

Ouvrez un vrai projet et vérifiez cinq points avant de lui faire confiance : modèles, identifiants des fournisseurs, agents, permissions et serveurs MCP. Le guide de migration utilise la même liste.

Si vous voulez plus tard une config v2 native, voici les changements de champs les plus importants :

Deux règles du guide évitent la plupart des erreurs de migration :

1. Gardez chaque entrée dans un seul format. Vous pouvez mélanger la syntaxe v1 et v2 au niveau racine. À l’intérieur d’une même entrée d’agent, de fournisseur, de commande ou de modèle, choisissez un seul format.
2. Ne faites pas lire un fichier converti à la v1. Les deux versions lisent les mêmes chemins. Une fois un fichier converti en syntaxe v2 uniquement, la v1 ne peut plus le lire. Si vous prévoyez un retour arrière, convertissez en dernier.

Le guide propose aussi de laisser OpenCode faire la conversion lui-même. Lancez la v2 dans le projet et donnez-lui ce prompt : "Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format. Preserve its behavior and all unrelated settings." (en clair : migrer la config, y compris les définitions sous forme de fichiers, du format V1 au format V2 natif, en conservant le comportement et les réglages sans rapport). Relisez le diff avant de le garder.

Champs v1 ignorés par la v2

Ceux-ci affichent un avertissement et n’ont aucun effet :

Les champs temperature, top_p et options au niveau de l’agent cessent aussi de fonctionner. La v2 les conserve dans le request.body de l’agent mais ne les envoie pas. Définissez-les plutôt sur une variante de modèle.

Ces champs v1 ont l’air obsolètes mais fonctionnent toujours, sans avertissement, car la v2 les convertit pour vous. Ne les supprimez pas lors du nettoyage :

La config LSP est conservée mais n’est pas exécutée. Si vous comptiez sur les diagnostics LSP d’OpenCode, donnez plutôt à l’agent des commandes explicites de lint, de vérification de types ou de compilation (par exemple dans AGENTS.md).

Étape 5 : les changements de comportement qui piègent plus tard

Ces changements ne produisent aucune erreur, et c’est pour cela qu’ils surprennent le plus.

La v2 ne lit pas CLAUDE.md

La v1 se rabattait sur CLAUDE.md en l’absence d’AGENTS.md. La v2 ne le fait plus. Si les règles de votre projet sont dans CLAUDE.md, la v2 démarre sans elles, et rien ne vous avertit. La correction prend une minute :

# Dans chaque dépôt qui n'a que CLAUDE.md
git mv CLAUDE.md AGENTS.md

La v1 utilisait aussi ~/.claude/CLAUDE.md comme règles globales quand ~/.config/opencode/AGENTS.md manquait. La v2 a également supprimé ce repli. Si vous n’avez pas d’AGENTS.md global, copiez-le à cet endroit :

cp ~/.claude/CLAUDE.md ~/.config/opencode/AGENTS.md

Claude Code lit désormais AGENTS.md en l’absence de CLAUDE.md, donc un seul fichier peut encore servir aux deux outils. La demande pour rétablir ce repli est ouverte en #53402 (opens in a new tab).

Les dossiers hors du projet sont autorisés par défaut

En v1, l’agent demandait avant de toucher un répertoire hors du projet. En v2, l’accès aux répertoires externes est autorisé par défaut. Pour retrouver le comportement v1, ajoutez cette règle dans permissions :

{
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}

Si vous lancez OpenCode en approbation automatique, ou sur une machine avec des fichiers sensibles hors de vos dépôts, ajoutez cette règle avant votre première session v2.

Les todos sont désactivés

La liste de todos était activée par défaut en v1. En v2, elle est désactivée. Réactivez-la avec "experimental": { "todo": true }.

Un service en arrière-plan tourne désormais pour tout votre compte utilisateur

La v2 démarre un serveur d’arrière-plan partagé. Le TUI, l’interface web et l’application desktop s’y connectent tous. C’est ce qui fait fonctionner opencode pair (un lien à usage unique qui expire après 5 minutes) et les tâches en arrière-plan (Ctrl+B). Si vous n’en voulez pas :

opencode service set disabled true   # l'arrêter et couper le démarrage auto
opencode service unset disabled      # le réactiver
opencode --standalone                # un serveur privé pour cette exécution seulement

L’appairage ne fonctionne pas tant que le service est désactivé. Le service ne lit pas non plus cli.json : les réglages de l’interface terminal ne s’appliquent qu’au client terminal.

Étape 6 : plugins, Oh My OpenCode et l’extension VS Code

Les plugins v1 ne se chargent pas en v2. L’API des plugins est nouvelle. Renommer plugin en plugins dans la config ne suffit pas. Le code de chaque plugin doit être porté (voir le guide officiel de migration des plugins (opens in a new tab)).

L’échec le plus courant concernait Oh My OpenCode (oh-my-openagent). Sur OpenCode 2.0.27, la version 5.1.32 échouait avec Plugin must export a default definition with an id and an effect or setup function (oh-my-openagent #10089 (opens in a new tab)). Le correctif (#10439 (opens in a new tab)) a été fusionné le 18 octobre, et la 5.1.38 est la première release npm qui l’inclut. Le 2 novembre, le mainteneur a confirmé que les versions actuelles se chargent sur OpenCode 2 et affichent un avis qui renvoie vers OmO Native, l’application autonome omo. Mettez oh-my-openagent à jour en 5.1.38 ou plus avant de mettre à jour OpenCode. Si vous préférez passer à omo, son README indique de lancer omo setup une fois pour reprendre vos clés de fournisseurs, serveurs MCP, skills et choix de modèles. Si vous découvrez l’outil lui-même, commencez par Oh My OpenCode et OpenCode : installation, configuration et correctifs.

Erreur de l’extension VS Code Unrecognized flag: --port. Les anciennes versions de l’extension lancent la CLI avec opencode --port <port>. La v2 a supprimé ce flag. Mettez l’extension à jour en v1.0.0 ou plus (Marketplace ou Open VSX). D’ici là, ouvrez un terminal dans VS Code et lancez opencode vous-même (#55219 (opens in a new tab)).

Vos propres scripts qui appellent le serveur. L’API serveur v1 n’existe plus. Portez-les vers le paquet @opencode/client, qui trouve aussi le service d’arrière-plan tout seul. Depuis le shell, opencode api appelle la même API. OPENCODE_SERVER_USERNAME n’est plus pris en charge ; le nom d’utilisateur est toujours opencode. La GitHub Action d’OpenCode a été supprimée dans la 2.2.0.

Problèmes connus après la mise à jour

Voici des issues GitHub ouvertes ou récemment corrigées, issues des premières semaines de la 2.x. Les correctifs viennent des mainteneurs, des auteurs ou du bot du projet dans chaque fil.

Revenir à la 1.x

Le guide de migration ne couvre pas le retour arrière. Voici l’ordre sûr :

1. Supprimez la v2. opencode uninstall --dry-run montre ce qui sera supprimé. opencode uninstall supprime ensuite le programme et laisse sessions, config et état sur le disque.
2. Réinstallez la v1 avec une version figée : npm install -g opencode-ai@1.19.5, ou brew install anomalyco/tap/opencode (la formule sans -v2).
3. Si vous avez converti un fichier de config en syntaxe v2 uniquement, restaurez-le depuis ~/opencode-v1-config-backup.
4. Si la v1 ne peut pas lire la base de sessions après son utilisation par la v2, restaurez ~/opencode-v1-data-backup. Nous n’avons pas testé si la v1 ouvre une base dans laquelle la v2 a écrit. Comptez sur la sauvegarde.

Note de sécurité : la fuite de l’OpenCode Console

Ce n’est pas lié à la mise à jour, mais c’est arrivé la même semaine. Le 17 octobre, l’équipe OpenCode a indiqué qu’une personne avait obtenu un accès non autorisé à un ancien système en cours de démantèlement (déclaration citée sur Hacker News (opens in a new tab)). Les clés de fournisseurs tiers enregistrées dans un espace de travail Console "may have been exposed" (ont pu être exposées). Leur conseil : révoquer et remplacer ces clés dans le tableau de bord de chaque fournisseur, et vérifier l’usage récent. Un message ultérieur a chiffré la part d’utilisateurs Console concernés à 1,4 %, et le cofondateur Dax Raad a déclaré que la CLI et l’application desktop n’étaient pas touchées (TechCrunch (opens in a new tab)). Si vous avez déjà enregistré des clés OpenAI, Anthropic ou autres dans la Console, renouvelez-les avant ou après la mise à jour.

Ce qui est vraiment nouveau dans la 2.0

Rien de tout cela n’est nécessaire pour terminer la mise à jour. Ce sont les fonctionnalités qui expliquent le changement d’architecture :

• Service d’arrière-plan partagé par le TUI, l’interface web et l’application desktop, plus opencode pair pour l’accès web.
• Tâches en arrière-plan : appuyez sur Ctrl+B pour envoyer une commande shell ou un sous-agent en cours d’exécution en arrière-plan pendant que l’agent principal continue.
• Code Mode : transforme les serveurs MCP et les endpoints OpenAPI en fonctions que l’agent peut enchaîner en une seule étape. Les serveurs MCP l’utilisent par défaut.
• Rechargement à chaud : OpenCode peut écrire un plugin pour lui-même en cours de session et l’utiliser immédiatement.
• @opencode/sdk et @opencode/client : le code derrière la CLI, pour construire vos propres clients.

Si vous choisissez un agent terminal de zéro plutôt que d’en mettre un à jour, Comment utiliser Codex couvre l’alternative la plus proche.

Guides associés

• Oh My OpenCode et OpenCode : installation, configuration et correctifs
• Comment utiliser Codex
• Comment utiliser DeepSeek Harness
• Les agents de code parallèles expliqués