Migrer vers OpenCode 2 : ce qui casse et comment adapter sa configuration

OpenCode 2 (V2) est sorti sans notes de version, et votre configuration V1 continue de marcher : OpenCode lit les mêmes fichiers opencode.json et traduit l'ancienne syntaxe en mémoire. Anomaly annonce trois ruptures volontaires : une nouvelle API de plugins, un nouveau contrat pour l'API serveur et ses clients, et un fichier unique cli.json pour la configuration du terminal. Deux autres changements ne figurent dans aucune liste et n'affichent aucun message : la V2 ne lit plus CLAUDE.md en repli et ne lance plus de serveur de langage. Tout le reste doit continuer à fonctionner. La documentation va plus loin : si une fonction V1 prise en charge ne marche plus en V2, l'équipe la traite comme un bug de compatibilité. En revanche, la V2 ignore volontairement quelques champs V1, avec un avertissement, dont logLevel, server et compaction.tail_turns.

La V1 et la V2 utilisent la même commande, opencode. L'installeur curl V2 (curl -fsSL https://opencode.ai/v2/install | bash) remplace le binaire V1, et les deux versions ne s'installent plus côte à côte par défaut. Si vous avez installé la V1 par un gestionnaire de paquets, Homebrew ou npm, désinstallez-la avant de lancer l'installeur. La V2 s'installe aussi par brew install anomalyco/tap/opencode-v2 ou npm install -g @opencode/cli.

Au 30 septembre 2026, la dernière V1 est la 1.18.33, publiée le 28 septembre, et la V2 en est à la 2.0.20, publiée sur npm le 29 septembre. Les versions V2 ne publient pas encore de notes de version, et le changelog d'opencode.ai s'arrête à la V1 (l'issue #52184, ouverte, le signale) : vérifiez le numéro de version le jour où vous migrez. Pour situer l'éditeur et le produit, lisez le profil d'OpenCode, l'agent de code open source d'Anomaly.

Ce qui casse

Les plugins. Une implémentation de plugin V1 ne s'exécute pas en V2. Déplacer le fichier ou renommer l'entrée de configuration ne suffit pas : il faut porter le code vers la nouvelle API, un export par défaut avec un id et une fonction setup(ctx). Un même paquet peut servir les deux versions : la V1 appelle server(), la V2 appelle setup(). Cette double entrée fonctionne à partir d'OpenCode 1.18.29.

Les intégrations qui appellent l'API serveur. Scripts, extensions internes, tableaux de bord : tout ce qui interroge opencode serve doit passer sur l'API V2, via le paquet @opencode/client. Pour le fonctionnement du mode serveur, son port, son mot de passe et les politiques qui l'encadrent, lisez déployer OpenCode en entreprise.

La configuration du terminal. Les fichiers tui.json superposés laissent place à un seul fichier global, ~/.config/opencode/cli.json. Au premier lancement, la V2 migre vos réglages globaux sans toucher aux fichiers V1. Elle ne migre pas les réglages de terminal propres à un projet.

Ce qui disparaît sans message d'erreur

Deux changements ne figurent pas dans la liste des ruptures, et vos développeurs les remarqueront en premier.

La V2 ne lit plus CLAUDE.md en repli. Elle découvre uniquement AGENTS.md, du dossier courant jusqu'au dossier personnel, plus le fichier global ~/.config/opencode/AGENTS.md. Si votre projet n'a qu'un CLAUDE.md, l'agent démarre sans vos règles. Placez les règles dans AGENTS.md et laissez CLAUDE.md pointer dessus ; OpenCode ou Claude Code : lequel choisir détaille le partage d'un même fichier de règles entre les deux harnais.

La V2 garde votre configuration lsp mais ne lance plus de serveur de langage. L'agent ne voit donc plus les diagnostics du compilateur en cours de session. La documentation conseille de remplacer ces usages par les commandes de lint, de typecheck ou de compilation du projet. Écrivez-les dans AGENTS.md.

Ce qui continue de marcher

La V2 lit les mêmes fichiers que la V1 : ~/.config/opencode/opencode.json, opencode.json à la racine, .opencode/opencode.json. Elle traduit la syntaxe V1 en mémoire sans réécrire vos fichiers. Les agents, commandes et skills définis dans .opencode/ fonctionnent sans modification. Les champs enabled_providers et disabled_providers deviennent des politiques internes, sans action de votre part.

Les renommages de la syntaxe native V2

Passer à la syntaxe native est facultatif. Si vous le faites, voici les changements les plus fréquents. Les blocs complets de fournisseurs, de serveurs MCP et de permissions, écrits dans les deux syntaxes, sont dans le guide pour poser OpenCode sur un dépôt existant.

Champ V1	Équivalent V2
permission (groupé par outil)	permissions (tableau ordonné de règles)
action bash	action shell
actions write, patch	action edit
action task	action subagent
agent, mode	agents
prompt d'un agent	system
disable	disabled
maxSteps	steps
temperature, top_p, options d'un agent	request.body
model + variant	fournisseur/modèle#variante
provider, npm, api	providers, package (préfixe aisdk:), settings.baseURL
options d'un fournisseur	réparti entre settings, headers et body, selon la nature de chaque option
mcp.<serveur>, enabled	mcp.servers.<serveur>, disabled
command, subtask	commands, subagent
skills.paths, skills.urls	skills (tableau unique)
compaction.preserve_recent_tokens, reserved	compaction.keep.tokens, buffer
autoshare: true	share: "auto"
autoupdate	update, une politique à trois valeurs : auto, notify, disable
small_model	agents.title.model
snapshot	snapshots
attachment	media
reference	references
plugin	plugins

Une précaution si votre équipe mélange les deux versions. Les notes de la version 1.18.24 indiquent que la V1 lit désormais les champs V2 pris en charge (« V1 now reads supported V2 config fields »), sans en donner la liste. Des utilisateurs signalent que les V1 antérieures à la 1.18.24 rejettent les champs V2 qu'elles ne connaissent pas, comme plugins au pluriel ; nous n'avons pas retrouvé ce comportement dans une source officielle. Tant qu'un seul poste reste en V1, gardez la syntaxe V1 dans les fichiers partagés.

La méthode en cinq étapes

La documentation d'OpenCode propose cet ordre :

1. Gardez votre configuration et vos définitions de fichiers telles quelles.
2. Lancez la V2 et vérifiez les modèles, les identifiants, les agents, les permissions et les serveurs MCP.
3. Portez les plugins.
4. Portez les intégrations qui appellent l'API serveur.
5. Convertissez la configuration en syntaxe native V2, si vous le souhaitez.

Pour l'étape 5, l'éditeur conseille de demander la conversion à OpenCode lui-même, avec une consigne de ce type : « Migre ma configuration OpenCode, y compris les définitions de fichiers, du format V1 vers le format natif V2, en préservant son comportement et tous les réglages sans rapport. » Relisez le diff avant de committer.

Une anomalie encore ouverte sur le mode serveur

Fin septembre 2026, deux issues visaient le mode serveur de la V2. La première est réglée : depuis la 2.0.6 environ, opencode serve renvoyait une erreur 401 quand aucun mot de passe n'était défini ; l'issue #50370 a été fermée le 29 septembre, la régression corrigée. La seconde reste ouverte au 30 septembre : le terminal n'arrive pas à se connecter à un serveur protégé via --server (issue #49427). Si vos équipes se connectent à un serveur partagé protégé par mot de passe, gardez un poste V1 le temps que ce correctif arrive.

Faut-il migrer maintenant ?

Un poste individuel, sans plugin ni script sur l'API serveur. Oui. Votre opencode.json et votre dossier .opencode/ sont lus tels quels. Avant de lancer l'installeur, désinstallez une V1 posée par Homebrew ou npm. Vérifiez ensuite deux points que rien ne signalera : votre projet a un AGENTS.md, pas seulement un CLAUDE.md, et vos commandes de lint, de typecheck et de compilation y sont écrites, puisque le serveur de langage ne tourne plus. Si vous aviez un tui.json dans le projet, ses réglages sont à reporter à la main dans cli.json.

Une équipe mixte, où des postes restent en V1. Migrez poste par poste, mais ne convertissez pas les fichiers partagés : la V2 lit la syntaxe V1, l'inverse dépend de la version de chaque V1 installée. Convertissez en syntaxe native une fois le dernier poste basculé. Fixez aussi la version V1 de référence à la 1.18.33 ou, au minimum, à une version qui lit les champs V2 pris en charge.

Une équipe qui dépend de plugins ou de l'API serveur. Pas encore, sauf à porter d'abord. Un plugin V1 ne s'exécute pas en V2, et les intégrations qui interrogent opencode serve doivent passer sur @opencode/client. La double entrée server() / setup(), disponible depuis la 1.18.29, permet de livrer les plugins portés avant de basculer les postes. Si vous utilisez un serveur partagé protégé par mot de passe, l'issue #49427 vous concerne : gardez un poste V1 tant qu'elle est ouverte.

Sources

1. OpenCode, Migrate from V1 (ruptures, compatibilité, champs ignorés, renommages, méthode, consigne de migration, installeur), consulté le 30 septembre 2026.
2. OpenCode, Migrate plugins from V1 (export par défaut, id, setup(ctx), double entrée depuis 1.18.29), consulté le 30 septembre 2026.
3. OpenCode, Client JavaScript V2 (@opencode/client), consulté le 30 septembre 2026.
4. OpenCode, Instructions V2 (AGENTS.md seul), consulté le 30 septembre 2026.
5. OpenCode, Documentation V2 (installation par curl, Homebrew, npm), consulté le 30 septembre 2026.
6. GitHub anomalyco/opencode, Release v1.18.33, 28 septembre 2026.
7. GitHub anomalyco/opencode, Release v1.18.24 (« V1 now reads supported V2 config fields »).
8. npm, @opencode/cli, version 2.0.20 publiée le 29 septembre 2026.
9. GitHub anomalyco/opencode, issue #52184 (absence de notes de version V2), ouverte au 30 septembre 2026.
10. GitHub, timrichardson/opencode-planner (rejet de plugins par les V1 antérieures à 1.18.24), source secondaire.
11. GitHub anomalyco/opencode, issue #50370 (erreur 401 de opencode serve sans mot de passe), fermée le 29 septembre 2026.
12. GitHub anomalyco/opencode, issue #49427 (connexion du terminal à un serveur protégé via --server), ouverte au 30 septembre 2026.