Poser OpenCode sur un dépôt existant : AGENTS.md, opencode.json, modèles, MCP et permissions

À la fin de ce guide, votre dépôt porte une configuration OpenCode partagée par toute l'équipe : règles dans AGENTS.md, modèles, serveurs MCP et permissions dans opencode.json, agents et skills dans .opencode/, versionnés avec le code.

OpenCode lit sa configuration à trois endroits : ~/.config/opencode/opencode.json pour vos réglages personnels, opencode.json à la racine du projet, et .opencode/opencode.json. La version 1 et la version 2 partagent ces emplacements. Tout ce que vous committez dans le dépôt s'applique donc à chaque développeur qui clone le projet, quelle que soit sa version.

Chaque exemple de configuration existe en deux syntaxes. La V2 lit encore la syntaxe V1 : si votre équipe mélange les deux versions, restez en V1. Le détail des renommages est dans le guide pour migrer vers OpenCode 2.

1. Installer OpenCode, en V1 ou en V2

Si vous n'avez jamais lancé l'outil, le profil d'OpenCode, l'agent de code open source d'Anomaly situe le projet, son éditeur et ses offres d'inférence.

En V1, le script officiel suffit : curl -fsSL https://opencode.ai/install | bash, ou npm install -g opencode-ai, ou brew install anomalyco/tap/opencode. En V2, vous avez le choix entre curl -fsSL https://opencode.ai/v2/install | bash, brew install anomalyco/tap/opencode-v2 ou npm install -g @opencode/cli. L'installeur curl V2 remplace le binaire V1, car les deux versions utilisent la même commande opencode. Si votre V1 vient d'un gestionnaire de paquets (Homebrew, npm), désinstallez-la avant.

Sous Windows, la documentation recommande WSL. La V2 ne prend pas en charge les gestionnaires de paquets Windows, mais sa page d'installation propose des binaires autonomes (x64 et ARM64). Lancez ensuite /connect dans l'agent pour choisir un fournisseur et saisir votre clé. Vos propres clés, le forfait Go ou Zen : vous choisirez sur le prix, et l'article combien coûte OpenCode pose les chiffres.

2. Créer ou reprendre AGENTS.md

Lancez /init à la racine. OpenCode lit le dépôt et rédige un AGENTS.md : commandes de build et de test, conventions, structure du code. Relisez-le, corrigez-le, puis committez-le.

Votre dépôt contient déjà un CLAUDE.md ? La V1 le lit en repli quand AGENTS.md manque. La V2 ne le lit plus. Placez les règles dans AGENTS.md et gardez dans CLAUDE.md une seule ligne, @AGENTS.md, pour que Claude Code lise le même contenu. Le comparatif OpenCode ou Claude Code détaille ce partage, et c'est le premier test de votre contexte : un fichier de règles que deux harnais lisent sans adaptation vous laisse libre de faire cohabiter plusieurs harnais.

Pour ajouter d'autres fichiers de règles sans les recopier, utilisez le champ instructions :

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/conventions.md"]
}

Attention en V2 : le champ instructions est accepté mais ne charge encore aucun fichier. Si une partie de l'équipe est passée en V2, copiez ces règles dans AGENTS.md.

3. Configurer un modèle local Ollama dans opencode.json

Le champ model fixe le modèle par défaut du projet, au format fournisseur/modèle. Pour un modèle local servi par Ollama, déclarez un fournisseur compatible OpenAI. Adaptez le nom du modèle à celui que vous avez téléchargé.

Syntaxe V1 :

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama local",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "qwen3-coder": { "name": "Qwen3 Coder" } }
    }
  },
  "model": "ollama/qwen3-coder"
}

Syntaxe V2 (le champ devient providers, npm devient package avec le préfixe aisdk:, l'adresse passe dans settings) :

{
  "providers": {
    "ollama": {
      "package": "aisdk:@ai-sdk/openai-compatible",
      "settings": { "baseURL": "http://localhost:11434/v1" }
    }
  }
}

Côté Ollama, la documentation V1 des fournisseurs donne la règle et son motif : si les appels d'outils ne fonctionnent pas, augmentez la fenêtre de contexte du modèle (paramètre num_ctx), en commençant entre 16k et 32k tokens. La valeur par défaut est trop courte pour un agent qui lit plusieurs fichiers.

Le même bloc sert pour une passerelle LLM d'entreprise : remplacez l'adresse locale par celle de la passerelle. Une organisation qui veut déployer OpenCode en entreprise avec des fournisseurs et des permissions fixés centralement passe par ce même bloc. Pour Claude, utilisez une clé API Anthropic, Amazon Bedrock ou Google Cloud (ex-Vertex AI). L'abonnement Claude Pro ou Max n'est pas autorisé dans OpenCode.

4. Brancher un serveur MCP dans OpenCode

Déclarez les serveurs MCP du projet dans opencode.json. La V2 les regroupe sous mcp.servers, remplace enabled par son inverse disabled et sépare deux délais.

Syntaxe V1 :

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp"],
      "enabled": true
    }
  }
}

Syntaxe V2 :

{
  "mcp": {
    "servers": {
      "playwright": {
        "type": "local",
        "command": ["npx", "@playwright/mcp"],
        "disabled": false,
        "timeout": { "catalog": 30000, "execution": 30000 }
      }
    }
  }
}

Ne committez jamais de clé dans ce fichier. Passez chaque clé par variable d'environnement avec la notation {env:NOM_VARIABLE}.

5. Régler les permissions d'OpenCode

Par défaut, OpenCode autorise la plupart des actions sans vous demander. Il demande confirmation dans deux cas : agir hors du dossier du projet (external_directory) et répéter trois fois de suite le même appel (doom_loop). Il refuse de lire les fichiers *.env et *.env.*, à l'exception de *.env.example. Sur un dépôt partagé, fixez au minimum une règle pour les commandes shell qui publient ou suppriment.

En V1, les règles se regroupent par outil :

{
  "permission": {
    "bash": { "git push *": "ask", "rm -rf *": "deny" },
    "edit": "allow"
  }
}

En V2, un tableau ordonné remplace les groupes, et bash s'appelle désormais shell :

{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "shell", "resource": "rm -rf *", "effect": "deny" },
    { "action": "edit", "resource": "*", "effect": "allow" }
  ]
}

6. Ajouter agents, commandes et skills dans .opencode/

Tout ce que l'équipe partage vit dans .opencode/ et se committe avec le code :

• .opencode/agents/<nom>.md pour un agent spécialisé (relecteur, rédacteur de tests). Le corps du fichier Markdown sert d'instructions.
• .opencode/commands/<nom>.md pour une commande réutilisable, appelée avec /<nom>.
• .opencode/skills/<nom>/SKILL.md pour une skill, avec ses scripts et références dans le même dossier.

La V2 découvre aussi les anciens noms de dossiers au singulier (agent/, command/, skill/). Préférez le pluriel dès maintenant.

7. Vérifier avant de généraliser

Ouvrez une session sur une tâche simple et vérifiez que le bon modèle répond, que les serveurs MCP apparaissent, qu'une commande protégée déclenche une demande de confirmation, et que l'agent cite une règle de votre AGENTS.md quand vous lui demandez comment lancer les tests.

Si vous passez en V2, elle garde votre configuration lsp mais ne lance plus de serveur de langage. Donnez à l'agent vos commandes de lint et de typecheck dans AGENTS.md.

Ce qui casse

Sur les dépôts que nous avons équipés, cinq pannes reviennent. L'étape 7 les révèle, et la correction tient en quelques lignes.

• L'agent démarre sans aucune règle en V2. Le dépôt n'a qu'un CLAUDE.md. La V1 le lisait en repli, la V2 ne lit que AGENTS.md. Créez AGENTS.md et réduisez CLAUDE.md à la ligne @AGENTS.md.
• Les règles de CONTRIBUTING.md sont ignorées par une partie de l'équipe. Elles arrivent par le champ instructions, que la V2 accepte sans rien charger. Tant que les deux versions cohabitent, recopiez ces règles dans AGENTS.md.
• Une clé de fournisseur se retrouve dans l'historique Git. Elle a été écrite en clair dans opencode.json. Révoquez-la, puis remplacez-la par {env:NOM_VARIABLE} et fournissez la variable à chaque poste.
• Avec Ollama, le modèle répond mais n'appelle aucun outil. La fenêtre de contexte par défaut est trop courte. Montez num_ctx côté Ollama, en commençant entre 16k et 32k, comme le conseille la documentation des fournisseurs.
• Plus aucun diagnostic de type ou de lint après le passage en V2. La configuration lsp est conservée mais aucun serveur de langage n'est lancé. Donnez à l'agent les commandes de lint et de typecheck dans AGENTS.md, et demandez-lui de les exécuter avant de conclure.

Sources

1. OpenCode, Intro (documentation V1), installation et /init, consulté le 30 septembre 2026.
2. OpenCode, Intro (documentation V2), installation V2, gestionnaires de paquets Windows et binaires autonomes, consulté le 30 septembre 2026.
3. OpenCode, Migrate from V1, remplacement du binaire V1, emplacements, syntaxes V1/V2 des fournisseurs, MCP, permissions, dossiers, LSP, consulté le 30 septembre 2026.
4. OpenCode, Config (V1) et Config (V2), notation {env:…} et fusion des fichiers, consultés le 30 septembre 2026.
5. OpenCode, Windows (WSL), consulté le 30 septembre 2026.
6. OpenCode, Rules (V1), AGENTS.md et champ instructions, consulté le 30 septembre 2026.
7. OpenCode, Instructions (V2), lecture d'AGENTS.md seul et champ instructions sans effet, consulté le 30 septembre 2026.
8. OpenCode, Providers (V1), Ollama et conseil num_ctx (« si les appels d'outils ne fonctionnent pas »), consulté le 30 septembre 2026.
9. OpenCode, Providers (V2), /connect, syntaxe providers, package et settings, consulté le 30 septembre 2026.
10. OpenCode, MCP servers, consulté le 30 septembre 2026.
11. OpenCode, Permissions, valeurs par défaut, doom_loop, external_directory et fichiers .env, consulté le 30 septembre 2026.
12. OpenCode, Agent Skills, consulté le 30 septembre 2026.