Konfiguration

Verwendung der OpenCode JSON-Konfiguration.

Sie können OpenCode mit einer JSON-Konfigurationsdatei konfigurieren.

Format

OpenCode unterstützt sowohl JSON als auch JSONC (JSON mit Kommentaren) Formate.

opencode.jsonc

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

Speicherorte

Sie können Ihre Konfiguration an verschiedenen Orten platzieren, die unterschiedliche Prioritätsreihenfolgen haben.

Hinweis: Konfigurationsdateien werden zusammengeführt, nicht ersetzt.

Konfigurationsdateien werden zusammengeführt, nicht ersetzt. Einstellungen aus den folgenden Konfigurationsorten werden kombiniert. Spätere Konfigurationen überschreiben frühere nur bei konfliktierenden Schlüsseln. Nicht-konfliktierende Einstellungen aus allen Konfigurationen bleiben erhalten.

Wenn beispielsweise Ihre globale Konfiguration theme: "opencode" und autoupdate: true setzt und Ihre Projektkonfiguration model: "anthropic/claude-sonnet-4-5" setzt, enthält die endgültige Konfiguration alle drei Einstellungen.

Prioritätsreihenfolge

Konfigurationsquellen werden in dieser Reihenfolge geladen (spätere Quellen überschreiben frühere):

Remote-Konfiguration (von .well-known/opencode) - Organisationsstandards
Globale Konfiguration (~/.config/opencode/opencode.json) - Benutzereinstellungen
Benutzerdefinierte Konfiguration (OPENCODE_CONFIG Umgebungsvariable) - Benutzerdefinierte Überschreibungen
Projektkonfiguration (opencode.json im Projekt) - Projektspezifische Einstellungen
.opencode-Verzeichnisse - Agenten, Befehle, Plugins
Inline-Konfiguration (OPENCODE_CONFIG_CONTENT Umgebungsvariable) - Laufzeit-Überschreibungen

Das bedeutet, dass Projektkonfigurationen globale Standards überschreiben können und globale Konfigurationen Remote-Organisationsstandards überschreiben können.

Hinweis: Die Unterverzeichnisse von .opencode und ~/.config/opencode verwenden Pluralnamen: agents/, commands/, modes/, plugins/, skills/, tools/ und themes/. Singularnamen (z.B. agent/) werden aus Gründen der Abwärtskompatibilität ebenfalls unterstützt.

Remote

Organisationen können Standardkonfigurationen über den .well-known/opencode-Endpunkt bereitstellen. Diese wird automatisch abgerufen, wenn Sie sich bei einem Anbieter authentifizieren, der dies unterstützt.

Die Remote-Konfiguration wird zuerst geladen und dient als Basisschicht. Alle anderen Konfigurationsquellen (global, Projekt) können diese Standards überschreiben.

Wenn Ihre Organisation beispielsweise MCP-Server bereitstellt, die standardmäßig deaktiviert sind:

Remote-Konfiguration von .well-known/opencode

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

Sie können bestimmte Server in Ihrer lokalen Konfiguration aktivieren:

opencode.json

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

Global

Platzieren Sie Ihre globale OpenCode-Konfiguration in ~/.config/opencode/opencode.json. Verwenden Sie die globale Konfiguration für benutzerweite Einstellungen wie Themes, Anbieter oder Tastenkombinationen.

Die globale Konfiguration überschreibt Remote-Organisationsstandards.

Pro Projekt

Fügen Sie opencode.json in Ihrem Projektstammverzeichnis hinzu. Die Projektkonfiguration hat die höchste Priorität unter den Standard-Konfigurationsdateien - sie überschreibt sowohl globale als auch Remote-Konfigurationen.

Tipp: Platzieren Sie projektspezifische Konfigurationen im Stammverzeichnis Ihres Projekts.

Wenn OpenCode startet, sucht es nach einer Konfigurationsdatei im aktuellen Verzeichnis oder traversiert nach oben zum nächsten Git-Verzeichnis.

Diese kann auch sicher in Git eingecheckt werden und verwendet dasselbe Schema wie die globale Konfiguration.

Benutzerdefinierter Pfad

Geben Sie einen benutzerdefinierten Konfigurationsdateipfad mit der OPENCODE_CONFIG-Umgebungsvariable an.

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

Die benutzerdefinierte Konfiguration wird in der Prioritätsreihenfolge zwischen globaler und Projektkonfiguration geladen.

Benutzerdefiniertes Verzeichnis

Geben Sie ein benutzerdefiniertes Konfigurationsverzeichnis mit der OPENCODE_CONFIG_DIR-Umgebungsvariable an. Dieses Verzeichnis wird wie das Standard-.opencode-Verzeichnis nach Agenten, Befehlen, Modi und Plugins durchsucht und sollte derselben Struktur folgen.

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

Das benutzerdefinierte Verzeichnis wird nach der globalen Konfiguration und den .opencode-Verzeichnissen geladen, sodass es deren Einstellungen überschreiben kann.

Schema

Die Konfigurationsdatei hat ein Schema, das in opencode.ai/config.json (opens in a new tab) definiert ist.

Ihr Editor sollte basierend auf dem Schema validieren und automatisch vervollständigen können.

TUI

Sie können TUI-spezifische Einstellungen über die tui-Option konfigurieren.

opencode.json

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

Verfügbare Optionen:

scroll_acceleration.enabled - Aktiviert macOS-ähnliche Scroll-Beschleunigung. Hat Vorrang vor scroll_speed.
scroll_speed - Benutzerdefinierter Scroll-Geschwindigkeitsmultiplikator (Standard: 3, Minimum: 1). Wird ignoriert, wenn scroll_acceleration.enabled true ist.
diff_style - Steuert das Diff-Rendering. "auto" passt sich der Terminalbreite an, "stacked" zeigt immer eine einzelne Spalte.

Erfahren Sie hier mehr über die Verwendung der TUI.

Server

Sie können Servereinstellungen für die Befehle opencode serve und opencode web über die server-Option konfigurieren.

opencode.json

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

Verfügbare Optionen:

port - Port zum Abhören.
hostname - Hostname zum Abhören. Wenn mdns aktiviert ist und kein Hostname gesetzt ist, ist der Standard 0.0.0.0.
mdns - Aktiviert mDNS-Diensterkennung. Dies ermöglicht anderen Geräten im Netzwerk, Ihren OpenCode-Server zu entdecken.
mdnsDomain - Benutzerdefinierter Domainname für den mDNS-Dienst. Standard ist opencode.local. Nützlich für den Betrieb mehrerer Instanzen im selben Netzwerk.
cors - Zusätzliche Origins, die für CORS erlaubt werden sollen, wenn der HTTP-Server von einem browserbasierten Client verwendet wird. Werte müssen vollständige Origins sein (Schema + Host + optionaler Port), z.B. https://app.example.com.

Erfahren Sie hier mehr über den Server.

Werkzeuge

Sie können die Werkzeuge, die ein LLM verwenden kann, über die tools-Option verwalten.

opencode.json

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

Erfahren Sie hier mehr über Werkzeuge.

Modelle

Sie können die Anbieter und Modelle, die Sie verwenden möchten, in Ihrer OpenCode-Konfiguration über die Optionen provider, model und small_model konfigurieren.

opencode.json

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

Die small_model-Option konfiguriert ein separates Modell für leichtgewichtige Aufgaben wie Titelgenerierung. Standardmäßig versucht OpenCode, ein günstigeres Modell zu verwenden, wenn eines von Ihrem Anbieter verfügbar ist, andernfalls fällt es auf Ihr Hauptmodell zurück.

Anbieteroptionen können timeout und setCacheKey enthalten:

opencode.json

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

timeout - Anfrage-Timeout in Millisekunden (Standard: 300000). Auf false setzen zum Deaktivieren.
setCacheKey - Stellt sicher, dass für den angegebenen Anbieter immer ein Cache-Schlüssel gesetzt wird.

Sie können auch lokale Modelle konfigurieren. Erfahren Sie mehr.

Anbieterspezifische Optionen

Einige Anbieter unterstützen zusätzliche Konfigurationsoptionen über die generischen timeout- und apiKey-Einstellungen hinaus.

Amazon Bedrock

Amazon Bedrock unterstützt AWS-spezifische Konfiguration:

opencode.json

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

region - AWS-Region für Bedrock (Standard ist AWS_REGION-Umgebungsvariable oder us-east-1)
profile - AWS-benanntes Profil aus ~/.aws/credentials (Standard ist AWS_PROFILE-Umgebungsvariable)
endpoint - Benutzerdefinierte Endpunkt-URL für VPC-Endpunkte. Dies ist ein Alias für die generische baseURL-Option mit AWS-spezifischer Terminologie. Wenn beide angegeben sind, hat endpoint Vorrang.

Hinweis: Bearer-Token (AWS_BEARER_TOKEN_BEDROCK oder /connect) haben Vorrang vor profilbasierter Authentifizierung. Siehe Authentifizierungspriorität für Details.

Erfahren Sie mehr über die Amazon Bedrock-Konfiguration.

Themes

Sie können das Theme, das Sie verwenden möchten, in Ihrer OpenCode-Konfiguration über die theme-Option konfigurieren.

opencode.json

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

Erfahren Sie hier mehr.

Agenten

Sie können spezialisierte Agenten für bestimmte Aufgaben über die agent-Option konfigurieren.

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Dateiänderungswerkzeuge für Nur-Review-Agent deaktivieren
        "write": false,
        "edit": false
      }
    }
  }
}

Sie können Agenten auch mit Markdown-Dateien in ~/.config/opencode/agents/ oder .opencode/agents/ definieren. Erfahren Sie hier mehr.

Standard-Agent

Sie können den Standard-Agenten mit der default_agent-Option festlegen. Dies bestimmt, welcher Agent verwendet wird, wenn keiner explizit angegeben ist.

opencode.json

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

Der Standard-Agent muss ein primärer Agent sein (kein Subagent). Dies kann ein eingebauter Agent wie "build" oder "plan" sein, oder ein benutzerdefinierter Agent, den Sie definiert haben. Wenn der angegebene Agent nicht existiert oder ein Subagent ist, fällt OpenCode mit einer Warnung auf "build" zurück.

Diese Einstellung gilt für alle Schnittstellen: TUI, CLI (opencode run), Desktop-App und GitHub Action.

Sie können die Teilen-Funktion über die share-Option konfigurieren.

opencode.json

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

Dies akzeptiert:

"manual" - Manuelles Teilen über Befehle erlauben (Standard)
"auto" - Neue Konversationen automatisch teilen
"disabled" - Teilen vollständig deaktivieren

Standardmäßig ist das Teilen auf manuellen Modus eingestellt, bei dem Sie Konversationen explizit mit dem /share-Befehl teilen müssen.

Befehle

Sie können benutzerdefinierte Befehle für wiederkehrende Aufgaben über die command-Option konfigurieren.

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

Sie können Befehle auch mit Markdown-Dateien in ~/.config/opencode/commands/ oder .opencode/commands/ definieren. Erfahren Sie hier mehr.

Tastenkombinationen

Sie können Ihre Tastenkombinationen über die keybinds-Option anpassen.

opencode.json

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

Erfahren Sie hier mehr.

Automatische Updates

OpenCode lädt beim Start automatisch neue Updates herunter. Sie können dies mit der autoupdate-Option deaktivieren.

opencode.json

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

Wenn Sie keine Updates möchten, aber benachrichtigt werden möchten, wenn eine neue Version verfügbar ist, setzen Sie autoupdate auf "notify". Beachten Sie, dass dies nur funktioniert, wenn es nicht über einen Paketmanager wie Homebrew installiert wurde.

Formatierer

Sie können Code-Formatierer über die formatter-Option konfigurieren.

opencode.json

{
  "$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"]
    }
  }
}

Erfahren Sie hier mehr über Formatierer.

Berechtigungen

Standardmäßig erlaubt opencode alle Operationen ohne explizite Genehmigung. Sie können dies mit der permission-Option ändern.

Um beispielsweise sicherzustellen, dass die edit- und bash-Werkzeuge eine Benutzergenehmigung erfordern:

opencode.json

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

Erfahren Sie hier mehr über Berechtigungen.

Komprimierung

Sie können das Verhalten der Kontextkomprimierung über die compaction-Option steuern.

opencode.json

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

auto - Sitzung automatisch komprimieren, wenn der Kontext voll ist (Standard: true).
prune - Alte Werkzeugausgaben entfernen, um Token zu sparen (Standard: true).

Watcher

Sie können Ignorier-Muster für den Datei-Watcher über die watcher-Option konfigurieren.

opencode.json

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

Muster folgen der Glob-Syntax. Verwenden Sie dies, um störende Verzeichnisse von der Dateiüberwachung auszuschließen.

MCP-Server

Sie können MCP-Server, die Sie verwenden möchten, über die mcp-Option konfigurieren.

opencode.json

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

Erfahren Sie hier mehr.

Plugins

Plugins erweitern OpenCode mit benutzerdefinierten Werkzeugen, Hooks und Integrationen.

Platzieren Sie Plugin-Dateien in .opencode/plugins/ oder ~/.config/opencode/plugins/. Sie können Plugins auch über die plugin-Option von npm laden.

opencode.json

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

Erfahren Sie hier mehr.

Anweisungen

Sie können die Anweisungen für das von Ihnen verwendete Modell über die instructions-Option konfigurieren.

opencode.json

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

Dies akzeptiert ein Array von Pfaden und Glob-Mustern zu Anweisungsdateien. Erfahren Sie hier mehr über Regeln.

Deaktivierte Anbieter

Sie können Anbieter, die automatisch geladen werden, über die disabled_providers-Option deaktivieren. Dies ist nützlich, wenn Sie verhindern möchten, dass bestimmte Anbieter geladen werden, auch wenn ihre Anmeldedaten verfügbar sind.

opencode.json

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

Hinweis: disabled_providers hat Vorrang vor enabled_providers.

Die disabled_providers-Option akzeptiert ein Array von Anbieter-IDs. Wenn ein Anbieter deaktiviert ist:

Er wird nicht geladen, auch wenn Umgebungsvariablen gesetzt sind.
Er wird nicht geladen, auch wenn API-Schlüssel über den /connect-Befehl konfiguriert sind.
Die Modelle des Anbieters erscheinen nicht in der Modellauswahlliste.

Aktivierte Anbieter

Sie können eine Erlaubnisliste von Anbietern über die enabled_providers-Option angeben. Wenn gesetzt, werden nur die angegebenen Anbieter aktiviert und alle anderen werden ignoriert.

opencode.json

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

Dies ist nützlich, wenn Sie OpenCode auf bestimmte Anbieter beschränken möchten, anstatt sie einzeln zu deaktivieren.

Hinweis: disabled_providers hat Vorrang vor enabled_providers.

Wenn ein Anbieter sowohl in enabled_providers als auch in disabled_providers erscheint, hat disabled_providers aus Gründen der Abwärtskompatibilität Vorrang.

Experimentell

Der experimental-Schlüssel enthält Optionen, die sich in aktiver Entwicklung befinden.

opencode.json

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

Vorsicht: Experimentelle Optionen sind nicht stabil. Sie können ohne Vorankündigung geändert oder entfernt werden.

Variablen

Sie können Variablenersetzung in Ihren Konfigurationsdateien verwenden, um auf Umgebungsvariablen und Dateiinhalte zu verweisen.

Umgebungsvariablen

Verwenden Sie {env:VARIABLE_NAME}, um Umgebungsvariablen zu ersetzen:

opencode.json

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

Wenn die Umgebungsvariable nicht gesetzt ist, wird sie durch einen leeren String ersetzt.

Dateien

Verwenden Sie {file:path/to/file}, um den Inhalt einer Datei zu ersetzen:

opencode.json

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

Dateipfade können sein:

Relativ zum Konfigurationsdateiverzeichnis
Oder absolute Pfade, die mit / oder ~ beginnen

Diese sind nützlich für:

Aufbewahrung sensibler Daten wie API-Schlüssel in separaten Dateien.
Einbindung großer Anweisungsdateien ohne Ihre Konfiguration zu überladen.
Teilen gemeinsamer Konfigurationsschnipsel über mehrere Konfigurationsdateien.

Einleitung Anbieter