Fichier de configuration OpenCode

OpenCode utilise le format JSON pour la configuration.

Nous pouvons d'abord examiner le fichier de configuration global~/.config/opencode/opencode.json：

touch ~/.config/opencode/opencode.json

Contient les informations sur le fournisseur de modèle et la configuration :

{
  // JSON Schema（用于编辑器校验和自动补全）
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    // 自定义 Provider 名称（使用时：deepseek/xxx）
    "deepseek": {

      // 使用 OpenAI 兼容适配器（适用于 DeepSeek 这类兼容接口）
      "npm": "@ai-sdk/openai-compatible",

      "options": {
        // API 基础地址（必须是 OpenAI 兼容格式）
        "baseURL": "https://api.deepseek.com/v1",

        // API Key
        "apiKey": "sk-xxxx",

        // 是否强制设置缓存 key（提升缓存命中率，降低成本）
        "setCacheKey": true
      },

      "models": {
        // 本地模型别名（CLI/TUI 中使用：deepseek/Deepseek-v4）
        "Deepseek-v4": {
          // 实际调用的模型名称（API 层）
          "name": "deepseek-v4-pro"
        }
      }
    }
  }
}

Un exemple de configuration minimale viable

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

Éléments de configuration globale courants :

Élément de configuration	Type	Description
`model`	string	Modèle principal par défaut
`small_model`	string	Modèle pour tâches légères (par ex., génération de titres)
`autoupdate`	booléen / "notify"	Politique de mise à jour automatique
`theme`	string	Thème de l'interface
`provider`	objet	Configuration du fournisseur de modèle

Exemple de fournisseur :

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}

Comprendre le « mécanisme de fusion » de la configuration

La configuration d'OpenCode n'est pas écrasée, mais plutôtFusion en couches。

Ordre de chargement (du plus faible au plus élevé)

Ordre Source Description

1 Distant`.well-known/opencode` Configuration par défaut de l'organisation

2 Configuration globale `~/.config/opencode/opencode.json`

3 Chemin personnalisé `OPENCODE_CONFIG`

4 Configuration du projet Dans le projet`opencode.json`

5 `.opencode/`Répertoire Capacité d'extension

6 Configuration en ligne `OPENCODE_CONFIG_CONTENT`

Ordre	Source	Description
1	Distant`.well-known/opencode`	Configuration par défaut de l'organisation
2	Configuration globale	`~/.config/opencode/opencode.json`
3	Chemin personnalisé	`OPENCODE_CONFIG`
4	Configuration du projet	Dans le projet`opencode.json`
5	`.opencode/`Répertoire	Capacité d'extension
6	Configuration en ligne	`OPENCODE_CONFIG_CONTENT`

Règles de fusion

Champs non conflictuels : tous conservés
Champs en conflit : le dernier remplace le premier

Exemple

Configuration globale :

{
  "autoupdate": true
}

Configuration du projet :

{
  "model": "anthropic/claude-sonnet-4-5"
}

Résultat final :

{
  "autoupdate": true,
  "model": "anthropic/claude-sonnet-4-5"
}

Configuration du projet

Créer dans le répertoire racine du projet :

opencode.json

Objectif :

Définir le comportement de l'IA propre au projet
Peut être commité dans Git
Remplacer la configuration globale

Exemple : Configuration au niveau du projet

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "tools": {
    "write": true,
    "bash": true
  }
}

Explication détaillée des modules de configuration principaux

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Modèles et fournisseurs

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Champ	Description
`model`	Modèle de tâche principal
`small_model`	Modèle de tâche à faible coût

Contrôle des outils

{
  "tools": {
    "write": false,
    "bash": false
  }
}

Outil	Objectif
write	Écrire dans le fichier
bash	Exécuter la commande

Ceci estLa première couche de contrôle de sécurité。

Contrôle des permissions

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Valeur	Signification
autoriser	Exécution automatique
ask	Confirmer à chaque fois
refuser	Interdit

Agent (Capacité principale)

{
  "agent": {
    "code-reviewer": {
      "description": "代码审查",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer",
      "tools": {
        "write": false
      }
    }
  }
}

Essence :Définir le rôle + le périmètre de capacités pour l’IA

Commande (Prompt automatisé)

{
  "command": {
    "test": {
      "template": "Run tests and fix failures",
      "description": "运行测试"
    }
  }
}

Essence:Système de modèles de prompt

Configuration de l'interface TUI

{
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

Configuration du serveur (API / Web)

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true
  }
}

Compression du contexte (Optimisation des tokens)

{
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

Système de plugins

{
  "plugin": [
    "opencode-helicone-session",
    "@my-org/custom-plugin"
  ]
}

MCP (Écosystème d’extensions)

{
  "mcp": {}
}

Utilisé pour intégrer des outils externes (tels que Jira, bases de données, etc.)

Système d’instructions (Règles de l’IA)

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

Contrôle du fournisseur

{
  "enabled_providers": ["anthropic"],
  "disabled_providers": ["openai"]
}

Priorité :

disabled > enabled

Système de variables

Variables d'environnement :

{
  "model": "{env:OPENCODE_MODEL}"
}

Référence de fichier

{
  "apiKey": "{file:~/.secrets/key}"
}

Mécanisme d'extension de répertoire

OpenCode n'est pas seulement une configuration JSON, il prend également en charge les extensions de répertoire :

.opencode/
├── agents/
├── commands/
├── plugins/
├── tools/
├── themes/

Objectif :

Définir des agents avec Markdown
Commandes au niveau du fichier
Extensions de plugins

Configuration de démarrage recommandée

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": "notify",
  "tools": {
    "write": true,
    "bash": true
  },
  "permission": {
    "bash": "ask"
  },
  "compaction": {
    "auto": true,
    "prune": true
  }
}

Résumé (perspective d'architecture)

La configuration d'OpenCode peut être comprise comme une structure à quatre couches :

配置层（多级 merge）
    ↓
能力层（agent / tools / mcp）
    ↓
执行层（model / provider）
    ↓
交互层（tui / server / web）

Essentiellement, il ne s'agit pas d'un simple fichier de configuration, mais d'un :

Centre de configuration d'un système d'exploitation programmable d'agent IA

Autres extensions