Aller au contenu
EN 4 QUESTIONSTrouver mon modèle
Code · guide expert · 25 min de lecture

Configurer OpenCode : opencode.json, modèles, agents, permissions

OpenCode se règle dans un fichier JSON lu à plusieurs niveaux, de votre dossier personnel jusqu'au projet. Ce guide décrit l'ordre de lecture, les clés qui comptent et des réglages prudents pour les permissions, le coût et les données.

Disponible en France

Illustration du thème Code

OpenCode, l’agent de code open source d’Anomaly, se règle dans un fichier JSON nommé opencode.json. Le même fichier sert à l’interface en terminal, à l’application de bureau et à l’interface web, car tous passent par le serveur local d’OpenCode. Ce guide décrit la version 2, celle que la documentation présente depuis l’automne 2026, d’après les pages lues le 19 novembre 2026. Les fichiers écrits pour la version 1 restent lus : vous pouvez garder les vôtres et les convertir plus tard.

Installer et se connecter

Installer OpenCode

macOS et Linux · macOS, Linux (script)

curl -fsSL https://opencode.ai/v2/install | bash

Homebrew · macOS, Linux (Homebrew)

brew install anomalyco/tap/opencode-v2

npm · Tous systèmes (npm)

npm install -g @opencode/cli

Bun · Tous systèmes (Bun)

bun install -g --trust @opencode/cli

pnpm · Tous systèmes (pnpm)

pnpm add -g --allow-build=@opencode/cli @opencode/cli

Yarn · Tous systèmes (Yarn)

yarn global add @opencode/cli

Arch Linux · Arch Linux (AUR)

paru -S opencode-beta

D'après opencode.ai, lue le 3 octobre 2026.La fiche de OpenCode →

Sous Windows, la documentation ne prend en charge aucun gestionnaire de paquets : téléchargez le programme autonome (x64 ou ARM64) depuis la page d’accueil de la documentation, ou l’application de bureau. Si une version 1 est installée par un gestionnaire de paquets, retirez-la d’abord : les deux versions utilisent la même commande opencode.

  1. Ouvrez un terminal dans le dossier du projet et lancez opencode.
  2. Tapez /connect, choisissez un fournisseur et suivez ses étapes (clé d’API ou connexion par le navigateur).
  3. Tapez /models et choisissez le modèle de la session.

La même connexion se fait hors de l’interface avec opencode auth login, par exemple opencode auth login anthropic --method key. opencode auth list affiche les comptes enregistrés. Les clés et jetons vont dans la base SQLite du serveur (en général ~/.local/share/opencode/opencode.db) : le fichier opencode.json n’en contient aucun.

Où sont les réglages

  • ~/.config/opencode/opencode.json : vos réglages, pour tous les projets.
  • opencode.json à la racine d’un projet, ou .opencode/opencode.json : les réglages de ce projet, à committer pour que toute l’équipe les partage.
  • /etc/opencode/opencode.json sous Linux, /Library/Application Support/opencode sur macOS, %ProgramData%\opencode sous Windows : les réglages de la machine, imposés à tous ses comptes.
  • ~/.config/opencode/cli.json : le thème et les raccourcis de l’interface en terminal, dans un fichier à part.

Chaque fichier peut s’écrire en JSON ou en JSONC, qui accepte les commentaires et les virgules finales (opencode.jsonc). OpenCode cherche les fichiers de projet du dossier courant jusqu’à la racine du disque et les combine : une couche ne remplace que les clés qu’elle définit, les autres restent.

L'ordre dans lequel OpenCode combine ses fichiers de réglages, du plus fort au plus faible, d'après la page « Config » de la documentation lue le 19 novembre 2026. Une couche ne remplace que les clés qu'elle définit.

Retenez deux pièges. Tout fichier rangé dans un dossier .opencode l’emporte sur tout opencode.json posé directement dans un dossier, même plus proche : choisissez une seule forme par dépôt. Et le fichier système passe devant vos réglages personnels, ce qui permet à un administrateur d’imposer une valeur.

Page Config de la documentation d'OpenCode : tableau des dossiers système, /Library/Application Support/opencode sur macOS, /etc/opencode sous Linux, %ProgramData%\opencode sous Windows, puis l'arborescence de /etc/opencode avec opencode.json, agents, commands et skills.
La section « Locations » de la page « Config », le 19 novembre 2026 : le dossier système de chaque plateforme, qui l'emporte sur vos fichiers (capture opencode.ai).

La première ligne de chaque fichier doit appeler le schéma. Votre éditeur valide alors les clés et propose les valeurs possibles :

{
  "$schema": "https://opencode.ai/config.json"
}

Deux écritures évitent de recopier un secret dans le fichier : {env:NOM} reprend une variable d’environnement, {file:~/.secrets/cle} le contenu d’un fichier. Une variable absente ou un fichier introuvable donnent une chaîne vide, sans message d’erreur : vérifiez avec /models que le fournisseur répond.

Bon à savoir : la version 2 a renommé plusieurs clés (permissions au pluriel, agents, providers, mcp.servers, snapshots). Les anciennes formes restent comprises, et un même fichier peut mêler les deux au premier niveau. À l’intérieur d’un agent, d’un fournisseur, d’une commande ou d’un modèle, gardez une seule version. La documentation conseille de demander la conversion à OpenCode lui-même, qui ne touche pas aux autres réglages.

Un fichier de départ

Ce fichier personnel reprend les clés de la documentation avec des valeurs prudentes. Remplacez le modèle par celui que vous utilisez :

// ~/.config/opencode/opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",

  // Modèle par défaut, au format fournisseur/modèle
  "model": "anthropic/claude-sonnet-5-5",
  "default_agent": "build",

  // Prévenir des mises à jour sans les installer seul (lu dans le fichier global seulement)
  "update": "notify",

  // Mettre en forme les fichiers modifiés avec les outils déjà installés
  "formatter": true,

  // La dernière règle qui correspond l'emporte : la règle large d'abord, les exceptions ensuite
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git log *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" }
  ]
}

OpenCode recharge ses fichiers tout seul. Une requête déjà partie garde les réglages de son départ.

Fournisseurs et modèles

Un modèle se désigne toujours sous la forme fournisseur/modèle, éventuellement suivie d’une variante après un # : openai/gpt-6.1-sol#high. Le catalogue vient de models.dev, des fournisseurs connectés et de votre configuration. Prenez les identifiants dans /models plutôt que de les deviner : la casse compte.

Le choix fait dans /models vaut pour la session et ne réécrit pas le fichier. La clé model fixe le modèle des nouvelles sessions, et opencode run --model … celui d’une seule exécution. Les variantes (souvent l’effort de réflexion) se choisissent par Ctrl+T dans l’interface ou par #variante dans un agent ou une commande ; la clé model du fichier, elle, ignore la variante.

La console d’OpenCode, à l’usage

Anomaly vend un accès à l’usage à une liste de modèles qu’elle a testés, avec un solde prépayé. Cette offre s’appelait OpenCode Zen ; l’ancienne page de documentation renvoie désormais vers la console. Créez un compte sur la console, ajoutez du crédit, copiez la clé puis connectez-la avec /connect. La console pose des budgets mensuels et une recharge automatique : réglez un budget avant la recharge.

La console sert aussi des modèles gratuits pour un temps limité. Lisez leurs conditions : pendant leur gratuité, les échanges avec plusieurs d’entre eux servent à améliorer ou à entraîner le modèle. Pour les retirer du catalogue, lancez le serveur avec OPENCODE_DISABLE_FREE_MODELS=1, ou, pour le serveur partagé en arrière-plan :

opencode service set env OPENCODE_DISABLE_FREE_MODELS 1

OpenCode Go, l’abonnement

Go donne accès à des modèles ouverts de code contre un abonnement mensuel : 10 $ pour Go, 40 $ pour Go Plus, 20 $ par membre pour Go Teams, d’après la documentation lue le 19 novembre 2026 (les prix suivis par le site sont sur la page OpenCode Go). L’usage est plafonné : 20 % de l’enveloppe du mois sur cinq heures, 50 % sur la semaine. Une fois la limite atteinte, il reste les modèles gratuits, ou l’option Extra Usage, qui puise dans le solde de la console. Laissez-la coupée si vous voulez une dépense fixe.

L’espace de travail filtre par défaut les modèles qui s’entraînent sur les requêtes et limite les régions à l’Europe et aux États-Unis. Les modèles exclus par ce filtre s’activent dans Settings › Privacy : faites-le en connaissance de cause.

Votre propre clé, ou votre abonnement ChatGPT

/connect propose les grands fournisseurs (Anthropic, OpenAI, Google, Bedrock, Azure, OpenRouter, GitHub Copilot…). OpenAI accepte aussi une connexion avec un compte ChatGPT Plus ou Pro : l’usage est alors décompté de l’abonnement, et OpenCode plafonne le contexte comme le fait Codex. Une clé peut aussi venir d’une variable d’environnement du serveur, sans être enregistrée :

opencode service set env ANTHROPIC_API_KEY sk-ant-...
opencode auth list

Pour un service qui suit l’API d’OpenAI sans figurer au catalogue, déclarez-le sous providers, en nommant la variable qui porte la clé :

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "acme": {
      "name": "Acme",
      "env": ["ACME_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": { "baseURL": "https://llm.acme.example/v1" },
      "models": {
        "qwen3-coder": { "name": "Qwen 3 Coder" }
      }
    }
  }
}

Le modèle s’appelle ensuite acme/qwen3-coder.

Un modèle local

La version 2 trouve seule les modèles d’Ollama (127.0.0.1:11434), de LM Studio (127.0.0.1:1234) et de vLLM (127.0.0.1:8000) à leurs adresses par défaut. Il suffit alors de nommer le modèle :

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen3.5"
}

Pour un serveur sur une autre adresse, changez seulement l’adresse ; la découverte continue :

{
  "providers": {
    "ollama": {
      "settings": { "baseURL": "http://127.0.0.1:5678/v1" }
    }
  }
}

Le choix du modèle, le réglage du contexte (64 000 jetons au moins) et les limites d’un modèle local sont détaillés dans le guide Brancher Ollama dans un agent de code. Son exemple de fichier est écrit à la manière de la version 1, que la version 2 lit toujours.

Agents : Build, Plan et les vôtres

Page Agents de la documentation d'OpenCode : tableau Built-ins avec Build et Plan en mode primary, General et Explore en mode subagent, et leur rôle, puis un exemple JSONC qui demande une confirmation avant git push pour l'agent build.
Le tableau des agents fournis avec OpenCode, page « Agents », le 19 novembre 2026 : Build et Plan pour la session, General et Explore comme sous-agents (capture opencode.ai).

Build est l’agent par défaut : il lit, écrit et lance des commandes. Plan explore et propose sans modifier les fichiers du projet. Maj+Tab passe de l’un à l’autre. Les deux sous-agents, General et Explore, sont lancés par l’agent principal dans une session à part, qui lui rend un compte rendu.

Un agent à vous tient dans un fichier Markdown, dans ~/.config/opencode/agents/ pour tous vos projets ou .opencode/agents/ pour un seul. Celui-ci relit le code sans rien toucher :

---
description: Relit les changements en cours et signale les erreurs
mode: subagent
model: anthropic/claude-sonnet-5-5#high
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Relis les changements en cours. Classe les problèmes du plus grave au moins grave,
avec le fichier et la ligne.

Enregistré sous .opencode/agents/relecteur.md, il s’appelle relecteur ; demandez à l’agent principal « utilise le sous-agent relecteur sur mes changements ». Écrivez toujours la description d’un sous-agent : c’est elle que lit le modèle pour décider de l’appeler. mode vaut primary (agent de session, la valeur par défaut), subagent ou all, et steps borne le nombre d’étapes d’un agent.

Le même agent s’écrit aussi dans opencode.json, sous agents, avec le texte des consignes dans system. Un agent fourni se modifie en reprenant son nom :

{
  "agents": {
    "build": {
      "permissions": [
        { "action": "shell", "resource": "git push *", "effect": "ask" }
      ]
    }
  }
}

Bon à savoir : hidden: true retire un agent des listes, sans rien interdire. Pour restreindre un agent, passez par ses permissions.

Permissions : qui décide de quoi

Le trajet d'une demande d'action dans OpenCode : trois listes de règles mises bout à bout, la dernière règle qui correspond décide, puis une policy peut encore refuser. D'après les pages « Permissions » et « Policies » lues le 19 novembre 2026.

Chaque règle porte trois champs : action (l’outil : shell, edit, read, webfetch, subagent, skill, external_directory, ou serveur_outil pour un outil MCP), resource (la commande, le chemin ou l’adresse visés, avec * et ? comme jokers) et effect (allow, ask ou deny). OpenCode met bout à bout les règles de base, celles de vos fichiers puis celles de l’agent, et applique la dernière qui correspond. Écrivez donc la règle large en premier et les exceptions après.

Page Permissions de la documentation d'OpenCode, section Defaults : la liste JSONC qui autorise toute action, demande pour la lecture de *.env et *.env.*, autorise *.env.example, puis le tableau des règles ajoutées par les agents build, plan, general, explore, title et summary.
Les règles de départ de chaque agent, page « Permissions », le 19 novembre 2026 : tout est permis, sauf la lecture des fichiers .env, qui est demandée (capture opencode.ai).

Les règles de base autorisent tout : c’est le premier réglage à revoir. Sans règle de votre part, Build lance n’importe quelle commande et modifie les fichiers sans vous demander. Deux points demandent votre attention.

  • Les dossiers hors du projet. La version 1 demandait avant d’y toucher. La version 2 ne le fait plus : ajoutez { "action": "external_directory", "resource": "*", "effect": "ask" } pour retrouver la question, puis autorisez les dossiers de référence un par un.
  • « Allow always ». Ce choix enregistre une règle allow durable pour le projet, souvent un préfixe de commande. Relisez de temps en temps ce que vous avez accordé. Une règle deny écrite dans un fichier reste toujours prioritaire sur ces accords.

Une règle shell porte sur le texte de la commande. OpenCode découpe les commandes composées et vérifie chaque morceau, mais la documentation prévient que cette analyse reste approximative : préférez une courte liste de commandes autorisées à une longue liste de commandes interdites.

Les policies passent après les permissions. Elles ne demandent jamais rien et ne peuvent que refuser : interdire un fournisseur, un serveur MCP ou une commande, même si un projet l’autorise. Une policy du fichier global l’emporte sur celle d’un projet, et celle du fichier système sur toutes :

{
  "policies": [
    { "action": "tool.use", "resource": "shell:sudo *", "effect": "deny" },
    { "action": "provider.use", "resource": "openai", "effect": "deny" }
  ]
}

Les règles du projet : AGENTS.md

OpenCode lit un fichier AGENTS.md pour connaître le projet : commandes de construction et de test, conventions, fichiers à ne pas modifier. Il charge le fichier global ~/.config/opencode/AGENTS.md, puis chaque AGENTS.md du dossier courant jusqu’à la racine du projet, et ceux des sous-dossiers au fil de son exploration. Les fichiers s’additionnent : OpenCode ne tranche pas entre deux consignes contraires.

# Consignes du projet

- Lancer `npm test` après chaque modification du code.
- Les requêtes à la base restent dans `src/database`.
- Ne jamais modifier les fichiers générés de `dist/`.

Dans un dossier sans AGENTS.md, OpenCode lit CLAUDE.md, et sans fichier global, ~/.claude/CLAUDE.md. La variable OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 coupe cette reprise. La clé instructions ajoute d’autres fichiers, des motifs ou des adresses web :

{
  "instructions": ["CONTRIBUTING.md", "docs/regles/*.md"]
}

Serveurs MCP

Un serveur MCP donne de nouveaux outils à l’agent. La commande opencode mcp add l’écrit dans la configuration du projet, ou dans la vôtre avec --global :

opencode mcp add context7 --url https://mcp.context7.com/mcp
opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything
opencode mcp list

Un serveur distant se connecte par OAuth : si mcp list affiche needs authentication, ouvrez /mcps dans l’interface et connectez-vous. À la main, les serveurs vont sous mcp.servers :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "playwright": {
        "type": "local",
        "command": ["npx", "-y", "@playwright/mcp"]
      },
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "oauth": false,
        "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" }
      }
    }
  }
}

"disabled": true garde un serveur dans le fichier sans le lancer. Chaque outil prend le nom serveur_outil (playwright_browser_navigate, par exemple), ce qui permet de lui donner sa propre permission. La documentation rappelle que les outils MCP occupent le contexte du modèle : n’activez que les serveurs utiles au projet. Le guide MCP explique le protocole et les précautions à prendre avec un serveur inconnu.

Commandes personnalisées

Un fichier Markdown dans .opencode/commands/ (ou ~/.config/opencode/commands/) devient une commande. .opencode/commands/revue.md crée /revue :

---
description: Relire un fichier
agent: plan
---

Relis $ARGUMENTS. Signale d'abord les erreurs, puis les tests manquants.

/revue src/auth.ts remplace $ARGUMENTS par src/auth.ts ; $1, $2 prennent les arguments un par un. Une commande peut aussi choisir son modèle (model) ou tourner en tâche de fond (subagent: true). Le motif !`git diff` insère la sortie d’une commande dans la consigne. Attention : cette commande s’exécute en dehors des permissions de l’agent. N’installez que des fichiers de commandes dont vous connaissez l’origine, et n’y placez jamais un argument venu d’ailleurs.

Les skills suivent le même principe pour des consignes longues : un dossier .opencode/skills/<nom>/SKILL.md, chargé seulement quand l’agent en a besoin. OpenCode lit aussi les dossiers .claude/skills et .agents/skills. Le guide Skills et plugins détaille le format.

Thème et raccourcis

L’apparence de l’interface en terminal se règle dans ~/.config/opencode/cli.json, un fichier global sans équivalent de projet. Le plus simple : Ctrl+P, puis Open settings.

Page Settings de la documentation d'OpenCode : une image de l'interface en terminal, fond noir, avec la fenêtre Settings ouverte sur les rubriques Appearance (Theme opencode, Color mode system, Animations on) et Session.
La page « Settings » de la documentation de l'interface en terminal, le 19 novembre 2026, avec l'image de la fenêtre de réglages qu'ouvre Ctrl+P puis Open settings (capture opencode.ai).
{
  "$schema": "https://opencode.ai/v2/cli.json",
  "theme": { "name": "tokyonight", "mode": "system" },
  "keybinds": {
    "leader": "ctrl+x",
    "command.palette.show": "ctrl+k"
  }
}

Quelques raccourcis par défaut à connaître : Maj+Tab change d’agent, Ctrl+T change de variante, F2 revient au modèle précédent, et la touche de tête (leader) suivie de u annule la dernière réponse, comme /undo.

Sécurité et coût : les réglages à poser

  1. Demander avant les commandes. shell sur ask, puis quelques exceptions en allow pour la lecture de Git et les tests.
  2. Retrouver la question hors du projet avec la règle external_directory sur ask.
  3. Laisser les secrets hors du fichier. {env:…} ou {file:…} pour les clés, /connect pour les comptes ; ne committez jamais une clé dans un opencode.json de projet.
  4. Garder les instantanés. /undo annule à la fois la dernière réponse et ses changements de fichiers, /redo revient en arrière. La documentation conseille de garder Git pour tout ce qui compte.
  5. Bannir ce qui ne doit jamais passer par une policy dans le fichier global : un dépôt cloné ne pourra pas la lever.
  6. Choisir où partent vos données. Retirez les modèles gratuits (OPENCODE_DISABLE_FREE_MODELS=1) si le code est confidentiel, ou passez à un modèle local.
  7. Tenir la dépense. Un budget mensuel sur la console, Extra Usage coupé sur Go, et peu de serveurs MCP actifs, car chaque outil coûte du contexte à chaque requête. Le maintien du cache (warming) est coupé par défaut : il envoie des requêtes à intervalles réguliers, chacune facturée.

Quel réglage pour quel usage

Profil Modèle Agent par défaut Permissions
Je découvre un modèle gratuit de la console ou Go plan, puis build une fois le plan validé shell et external_directory sur ask
Code confidentiel Ollama ou LM Studio, gratuits de la console retirés build webfetch et websearch sur deny, shell sur ask
Équipe celui de l’équipe, fixé dans le opencode.json du dépôt build règles communes dans le dépôt, policies dans le fichier système ou la console
Script ou intégration continue opencode run --model … un agent dédié avec steps liste courte d’allow, tout le reste en deny (personne ne répond à un ask)

Pour comparer les modèles avant d’en fixer un, le classement Code et la fiche OpenCode montrent ce que chaque modèle donne dans cet outil.

Pour aller plus loin

Sur mini lab AI, un guide du même auteur reprend ce sujet pour monter son atelier d'IA à la maison.

Tous les guides →

Sources

  1. opencode.ai, lue le
  2. opencode.ai, lue le
  3. opencode.ai, lue le
  4. opencode.ai, lue le
  5. opencode.ai, lue le
  6. opencode.ai, lue le
  7. opencode.ai, lue le
  8. opencode.ai, lue le
  9. opencode.ai, lue le
  10. opencode.ai, lue le
  11. opencode.ai, lue le
  12. opencode.ai, lue le
  13. opencode.ai, lue le
  14. opencode.ai, lue le
  15. opencode.ai, lue le
  16. opencode.ai, lue le
  17. opencode.ai, lue le
  18. opencode.ai, lue le
  19. opencode.ai, lue le
  20. opencode.ai, lue le