Configuration

Utiliser le fichier de configuration JSON OpenCode.

Vous pouvez configurer OpenCode à l’aide d’un fichier de configuration JSON.

Format

OpenCode prend en charge les formats JSON et JSONC (JSON avec commentaires).

{
  "$schema": "https://opencode.ai/config.json",
  // Configuration du thème
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
}

Emplacements

Vous pouvez placer votre configuration dans plusieurs emplacements différents qui ont un ordre de priorité différent.

Les fichiers de configuration sont fusionnés ensemble, non remplacés. Les paramètres des emplacements de configuration suivants sont combinés. Les configurations ultérieures ne remplacent les précédentes que pour les clés en conflit. Les paramètres non conflictuels de toutes les configurations sont conservés.

Par exemple, si votre configuration globale définit theme: "opencode" et autoupdate: true, et que votre configuration de projet définit model: "anthropic/claude-sonnet-4-5", la configuration finale inclura les trois paramètres.

Ordre de priorité

Les sources de configuration sont chargées dans cet ordre (les sources ultérieures remplacent les précédentes) :

Configuration distante (depuis .well-known/opencode) - paramètres organisationnels par défaut
Configuration globale (~/.config/opencode/opencode.json) - préférences utilisateur
Configuration personnalisée (variable d’environnement OPENCODE_CONFIG) - substitutions personnalisées
Configuration de projet (opencode.json dans le projet) - paramètres spécifiques au projet
Répertoires .opencode - agents, commandes, plugins
Configuration en ligne (variable d’environnement OPENCODE_CONFIG_CONTENT) - substitutions à l’exécution

Cela signifie que les configurations de projet peuvent remplacer les paramètres globaux par défaut, et que les configurations globales peuvent remplacer les paramètres organisationnels distants.

Distante

Les organisations peuvent fournir une configuration par défaut via le endpoint .well-known/opencode. Elle est récupérée automatiquement lorsque vous vous authentifiez auprès d’un fournisseur qui la prend en charge.

La configuration distante est chargée en premier, servant de couche de base. Toutes les autres sources de configuration (globale, projet) peuvent remplacer ces valeurs par défaut.

Par exemple, si votre organisation fournit des serveurs MCP qui sont désactivés par défaut :

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

Vous pouvez activer des serveurs spécifiques dans votre configuration locale :

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Globale

Placez votre configuration globale OpenCode dans ~/.config/opencode/opencode.json. Utilisez la configuration globale pour les préférences à l’échelle de l’utilisateur telles que les thèmes, les fournisseurs ou les raccourcis clavier.

La configuration globale remplace les paramètres organisationnels distants par défaut.

Par projet

Ajoutez opencode.json à la racine de votre projet. La configuration de projet a la priorité la plus élevée parmi les fichiers de configuration standard - elle remplace à la fois les configurations globales et distantes.

Lorsqu’OpenCode démarre, il recherche un fichier de configuration dans le répertoire actuel ou remonte jusqu’au répertoire Git le plus proche.

Il est également sûr de le commit dans Git et utilise le même schéma que celui global.

Chemin personnalisé

Spécifiez un chemin de fichier de configuration personnalisé à l’aide de la variable d’environnement OPENCODE_CONFIG.

export OPENCODE_CONFIG=/chemin/vers/ma/config-personnalisee.json
opencode run "Bonjour le monde"

La configuration personnalisée est chargée entre les configurations globales et de projet dans l’ordre de priorité.

Répertoire personnalisé

Spécifiez un répertoire de configuration personnalisé à l’aide de la variable d’environnement OPENCODE_CONFIG_DIR. Ce répertoire sera recherché pour les agents, commandes, modes et plugins tout comme le répertoire standard .opencode, et doit suivre la même structure.

export OPENCODE_CONFIG_DIR=/chemin/vers/mon-repertoire-config
opencode run "Bonjour le monde"

Le répertoire personnalisé est chargé après la configuration globale et les répertoires .opencode, il peut donc remplacer leurs paramètres.

Schéma

Le fichier de configuration a un schéma défini dans opencode.ai/config.json.

Votre éditeur devrait pouvoir valider et autocompléter en fonction du schéma.

TUI

Vous pouvez configurer les paramètres spécifiques à la TUI via l’option tui.

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

Options disponibles :

scroll_acceleration.enabled - Activer l’accélération de défilement style macOS. Prend le pas sur scroll_speed.
scroll_speed - Multiplicateur de vitesse de défilement personnalisé (défaut : 1, minimum : 1). Ignoré si scroll_acceleration.enabled est true.
diff_style - Contrôler le rendu des différences. "auto" s’adapte à la largeur du terminal, "stacked" affiche toujours une seule colonne.

En savoir plus sur l’utilisation de la TUI ici.

Serveur

Vous pouvez configurer les paramètres du serveur pour les commandes opencode serve et opencode web via l’option server.

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["http://localhost:5173"]
  }
}

Options disponibles :

port - Port d’écoute.
hostname - Nom d’hôte d’écoute. Lorsque mdns est activé et qu’aucun nom d’hôte n’est défini, la valeur par défaut est 0.0.0.0.
mdns - Activer la découverte de service mDNS. Cela permet aux autres appareils du réseau de découvrir votre serveur OpenCode.
cors - Origines supplémentaires à autoriser pour CORS lors de l’utilisation du serveur HTTP depuis un client basé sur un navigateur. Les valeurs doivent être des origines complètes (schéma + hôte + port optionnel), par exemple https://app.example.com.

En savoir plus sur le serveur ici.

Outils

Vous pouvez gérer les outils qu’un LLM peut utiliser via l’option tools.

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

En savoir plus sur les outils ici.

Modèles

Vous pouvez configurer les fournisseurs et modèles que vous souhaitez utiliser dans votre configuration OpenCode via les options provider, model et small_model.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

L’option small_model configure un modèle séparé pour les tâches légères comme la génération de titres. Par défaut, OpenCode essaie d’utiliser un modèle moins coûteux si un est disponible chez votre fournisseur, sinon il revient à votre modèle principal.

Les options du fournisseur peuvent inclure timeout et setCacheKey :

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}

timeout - Délai d’expiration de la requête en millisecondes (défaut : 300000). Définissez sur false pour désactiver.
setCacheKey - S’assurer qu’une clé de cache est toujours définie pour le fournisseur désigné.

Vous pouvez également configurer des modèles locaux. En savoir plus.

Options spécifiques au fournisseur

Certains fournisseurs prennent en charge des options de configuration supplémentaires au-delà des paramètres génériques timeout et apiKey.

Amazon Bedrock

Amazon Bedrock prend en charge la configuration AWS spécifique :

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "mon-profil-aws",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}

region - Région AWS pour Bedrock (défaut : variable d’environnement AWS_REGION ou us-east-1)
profile - Profil AWS nommé depuis ~/.aws/credentials (défaut : variable d’environnement AWS_PROFILE)
endpoint - URL de endpoint personnalisé pour les endpoints VPC. Il s’agit d’un alias pour l’option générique baseURL utilisant une terminologie spécifique à AWS. Si les deux sont spécifiés, endpoint prend le pas.

En savoir plus sur la configuration Amazon Bedrock.

Thèmes

Vous pouvez configurer le thème que vous souhaitez utiliser dans votre configuration OpenCode via l’option theme.

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

En savoir plus ici.

Agents

Vous pouvez configurer des agents spécialisés pour des tâches spécifiques via l’option agent.

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Examine le code pour les meilleures pratiques et problèmes potentiels",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "Vous êtes un réviseur de code. Concentrez-vous sur la sécurité, les performances et la maintenabilité.",
      "tools": {
        // Désactiver les outils de modification de fichiers pour l'agent de révision uniquement
        "write": false,
        "edit": false,
      },
    },
  },
}

Vous pouvez également définir des agents en utilisant des fichiers markdown dans ~/.config/opencode/agent/ ou .opencode/agent/. En savoir plus ici.

Agent par défaut

Vous pouvez définir l’agent par défaut à l’aide de l’option default_agent. Cela détermine quel agent est utilisé lorsqu’aucun n’est explicitement spécifié.

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

L’agent par défaut doit être un agent principal (pas un sous-agent). Il peut s’agir d’un agent intégré comme "build" ou "plan", ou d’un agent personnalisé que vous avez défini. Si l’agent spécifié n’existe pas ou est un sous-agent, OpenCode reviendra à "build" avec un avertissement.

Ce paramètre s’applique à toutes les interfaces : TUI, CLI (opencode run), application de bureau et GitHub Action.

Partage

Vous pouvez configurer la fonctionnalité de partage via l’option share.

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

Cela accepte :

"manual" - Autoriser le partage manuel via les commandes (défaut)
"auto" - Partager automatiquement les nouvelles conversations
"disabled" - Désactiver entièrement le partage

Par défaut, le partage est en mode manuel où vous devez explicitement partager les conversations en utilisant la commande /share.

Commandes

Vous pouvez configurer des commandes personnalisées pour les tâches répétitives via l’option command.

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Exécutez la suite de tests complète avec le rapport de couverture et affichez les échecs.\nConcentrez-vous sur les tests échouant et suggérez des corrections.",
      "description": "Exécuter les tests avec couverture",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
    "component": {
      "template": "Créez un nouveau composant React nommé $ARGUMENTS avec la prise en charge TypeScript.\nIncluez la typage approprié et la structure de base.",
      "description": "Créer un nouveau composant",
    },
  },
}

Vous pouvez également définir des commandes en utilisant des fichiers markdown dans ~/.config/opencode/command/ ou .opencode/command/. En savoir plus ici.

Raccourcis clavier

Vous pouvez personnaliser vos raccourcis clavier via l’option keybinds.

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

En savoir plus ici.

Mise à jour automatique

OpenCode téléchargera automatiquement les nouvelles mises à jour au démarrage. Vous pouvez désactiver cela avec l’option autoupdate.

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

Si vous ne voulez pas de mises à jour mais souhaitez être notifié lorsqu’une nouvelle version est disponible, définissez autoupdate sur "notify".

Formateurs

Vous pouvez configurer les formateurs de code via l’option formatter.

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

En savoir plus sur les formateurs ici.

Permissions

Par défaut, opencode autorise toutes les opérations sans exiger d’approbation explicite. Vous pouvez changer cela avec l’option permission.

Par exemple, pour garantir que les outils edit et bash nécessitent l’approbation de l’utilisateur :

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

En savoir plus sur les permissions ici.

Compactage

Vous pouvez contrôler le comportement de compactage du contexte via l’option compaction.

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}

auto - Compacter automatiquement la session lorsque le contexte est plein (défaut : true).
prune - Supprimer les anciennes sorties d’outils pour économiser des tokens (défaut : true).

Observateur

Vous pouvez configurer les modèles d’ignorage de l’observateur de fichiers via l’option watcher.

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Les modèles suivent la syntaxe glob. Utilisez ceci pour exclure les répertoires bruyants de la surveillance des fichiers.

Serveurs MCP

Vous pouvez configurer les serveurs MCP que vous souhaitez utiliser via l’option mcp.

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

En savoir plus ici.

Plugins

Les plugins étendent OpenCode avec des outils, hooks et intégrations personnalisés.

Placez les fichiers de plugin dans .opencode/plugin/ ou ~/.config/opencode/plugin/. Vous pouvez également charger des plugins depuis npm via l’option plugin.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

En savoir plus ici.

Instructions

Vous pouvez configurer les instructions pour le modèle que vous utilisez via l’option instructions.

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

Cela accepte un tableau de chemins et de modèles glob vers des fichiers d’instructions. En savoir plus sur les règles ici.

Fournisseurs désactivés

Vous pouvez désactiver les fournisseurs qui sont chargés automatiquement via l’option disabled_providers. C’est utile lorsque vous voulez empêcher certains fournisseurs d’être chargés même si leurs identifiants sont disponibles.

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

L’option disabled_providers accepte un tableau d’ID de fournisseur. Lorsqu’un fournisseur est désactivé :

Il ne sera pas chargé même si des variables d’environnement sont définies.
Il ne sera pas chargé même si les clés API sont configurées via la commande /connect.
Les modèles du fournisseur n’apparaîtront pas dans la liste de sélection des modèles.

Fournisseurs activés

Vous pouvez spécifier une liste autorisée de fournisseurs via l’option enabled_providers. Lorsqu’elle est définie, seuls les fournisseurs spécifiés seront activés et tous les autres seront ignorés.

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

C’est utile lorsque vous voulez restreindre OpenCode à n’utiliser que des fournisseurs spécifiques plutôt que de les désactiver un par un.

Si un fournisseur apparaît à la fois dans enabled_providers et disabled_providers, disabled_providers prend le pas pour la compatibilité descendante.

Expérimental

La clé experimental contient des options qui sont en développement actif.

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

Variables

Vous pouvez utiliser la substitution de variables dans vos fichiers de configuration pour référencer des variables d’environnement et le contenu des fichiers.

Variables d’environnement

Utilisez {env:VARIABLE_NAME} pour substituer les variables d’environnement :

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Si la variable d’environnement n’est pas définie, elle sera remplacée par une chaîne vide.

Fichiers

Utilisez {file:chemin/vers/fichier} pour substituer le contenu d’un fichier :

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Les chemins de fichiers peuvent être :

Relatifs au répertoire du fichier de configuration
Ou des chemins absolus commençant par / ou ~

C’est utile pour :

Garder des données sensibles comme les clés API dans des fichiers séparés.
Inclure de grands fichiers d’instructions sans encombrer votre configuration.
Partager des extraits de configuration courants entre plusieurs fichiers de configuration.