Zum Inhalt springen
OpenCode
app.header.homeapp.header.docs

Konfiguration

Verwenden Sie die Konfiguration OpenCode JSON.

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

Format

OpenCode unterstützt die Formate JSON und JSONC (JSON mit Kommentaren).

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

Speicherorte

Sie können Ihre Konfiguration an verschiedenen Orten platzieren und sie haben eine andere Rangfolge.

Konfigurationsdateien werden zusammengeführt und nicht ersetzt. Einstellungen aus den folgenden Konfigurationsspeicherorten werden kombiniert. Spätere Konfigurationen überschreiben frühere nur bei Schlüsselkonflikten. Es bleiben keine widersprüchlichen Einstellungen aus allen Konfigurationen erhalten.

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

Rangfolge

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

  1. Remote-Konfiguration (von .well-known/opencode) – Organisationsstandards
  2. Globale Konfiguration (~/.config/opencode/opencode.json) – Benutzereinstellungen
  3. Benutzerdefinierte Konfiguration (OPENCODE_CONFIG env var) – benutzerdefinierte Überschreibungen
  4. Projektkonfiguration (opencode.json im Projekt) – projektspezifische Einstellungen
  5. .opencode Verzeichnisse – Agenten, Befehle, Plugins
  6. Inline-Konfiguration (OPENCODE_CONFIG_CONTENT env var) – Laufzeitüberschreibungen

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

Remote

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

Zuerst wird die Remote-Konfiguration geladen, die als Basisschicht dient. Alle anderen Konfigurationsquellen (global, Projekt) können diese Standardeinstellungen überschreiben.

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

Remote config from .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 Themen, Anbieter oder Tastenkombinationen.

Die globale Konfiguration überschreibt die Standardeinstellungen der Remote-Organisation.

Pro Projekt

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

Wenn OpenCode gestartet wird, sucht es im aktuellen Verzeichnis nach einer Konfigurationsdatei oder durchsucht das nächstgelegene Git-Verzeichnis.

Dies kann auch sicher in Git eingecheckt werden und dasselbe Schema wie das globale verwenden.

Benutzerdefinierter Pfad

Geben Sie mithilfe der Umgebungsvariablen OPENCODE_CONFIG einen benutzerdefinierten Konfigurationsdateipfad an.

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

Die benutzerdefinierte Konfiguration wird in der Rangfolge zwischen globalen und Projektkonfigurationen geladen.

Benutzerdefiniertes Verzeichnis

Geben Sie mit OPENCODE_CONFIG_DIR ein benutzerdefiniertes Konfigurationsverzeichnis an. Umgebungsvariable. Dieses Verzeichnis wird nach Agenten, Befehlen, Modi und Plugins genau wie das Standardverzeichnis .opencode und sollten folgen der gleichen Struktur.

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

Das benutzerdefinierte Verzeichnis wird nach den Verzeichnissen global config und .opencode geladen, sodass es deren Einstellungen überschreiben kann.

Schema

Die Konfigurationsdatei verfügt über ein Schema, das in opencode.ai/config.json definiert ist.

Ihr Editor sollte in der Lage sein, basierend auf dem Schema zu validieren und automatisch zu vervollständigen.

TUI

Sie können TUI-spezifische Einstellungen über die Option tui 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 – Scrollbeschleunigung im macOS-Stil aktivieren. Hat Vorrang vor scroll_speed.
  • scroll_speed – Benutzerdefinierter Scrollgeschwindigkeitsmultiplikator (Standard: 3, Minimum: 1). Wird ignoriert, wenn scroll_acceleration.enabled gleich true ist.
  • diff_style – Steuern Sie das Diff-Rendering. "auto" passt sich der Terminalbreite an, "stacked" zeigt immer eine einzelne Spalte an.

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 Option server 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 festgelegt ist, wird standardmäßig 0.0.0.0 verwendet.
  • mdns – mDNS-Diensterkennung aktivieren. Dadurch können andere Geräte im Netzwerk Ihres OpenCode-Servers erkannt werden.
  • mdnsDomain – Benutzerdefinierter Domänenname für den mDNS-Dienst. Standardmäßig ist opencode.local. Nützlich für die Ausführung mehrerer Instanzen im selben Netzwerk.
  • cors – Zusätzliche Ursprünge, um CORS zu ermöglichen, wenn der HTTP-Server von einem browserbasierten Client aus verwendet wird. Die Werte müssen vollständige Ursprünge haben (Schema + Host + optionaler Port), z. B. https://app.example.com.

Erfahren Sie hier mehr über den Server.

Werkzeuge

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

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

Erfahren Sie hier mehr über Tools.

Modelle

Sie können die Anbieter und Modelle, die Sie in Ihrer OpenCode-Konfiguration verwenden möchten, ü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 Option small_model konfiguriert ein separates Modell für einfache Aufgaben wie die Titelgenerierung. Standardmäßig versucht OpenCode, ein günstigeres Modell zu verwenden, sofern eines bei Ihrem Anbieter verfügbar ist, andernfalls greift es auf Ihr Hauptmodell zurück.

Zu den Anbieteroptionen können timeout und setCacheKey gehören:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}
  • timeout – Anforderungszeitlimit in Millisekunden (Standard: 300000). Zum Deaktivieren auf false setzen.
  • setCacheKey – Stellen Sie sicher, dass immer ein Cache-Schlüssel für den angegebenen Anbieter festgelegt ist.

Sie können auch lokale Modelle konfigurieren. Mehr erfahren.

Anbieterspezifische Optionen

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

Amazon Bedrock

Amazon Bedrock unterstützt AWS-spezifische Konfigurationen:

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 (standardmäßig AWS_REGION env var oder us-east-1)
  • profile – AWS benanntes Profil von ~/.aws/credentials (standardmäßig AWS_PROFILE Umgebungsvariable)
  • endpoint – Benutzerdefinierter Endpunkt URL für VPC-Endpunkte. Dies ist ein Alias ​​​​für die generische Option baseURL unter Verwendung der AWS-spezifischen Terminologie. Wenn beide angegeben sind, hat endpoint Vorrang.

Erfahren Sie mehr über die Amazon Bedrock-Konfiguration.

Themen

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

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

Mehr erfahren.

Agenten

Über die Option agent können Sie spezielle Agenten für bestimmte Aufgaben 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": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

Sie können Agenten auch mithilfe von Markdown-Dateien in ~/.config/opencode/agents/ oder .opencode/agents/ definieren. Mehr erfahren.

Standardagent

Sie können den Standardagenten mit der Option default_agent festlegen. Dadurch wird bestimmt, welcher Agent verwendet wird, wenn keiner explizit angegeben wird.

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

Der Standardagent muss ein Primäragent (kein Subagent) sein. Dies kann ein integrierter Agent wie "build" oder "plan" oder ein von Ihnen definierter custom agent sein. Wenn der angegebene Agent nicht existiert oder ein Subagent ist, greift OpenCode mit einer Warnung auf "build" zurück.

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

Teilen

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

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

Dazu braucht es:

  • "manual" – Manuelles Teilen über Befehle zulassen (Standard)
  • "auto" – Neue Konversationen automatisch teilen
  • "disabled" – Teile vollständig deaktivieren

Standardmäßig ist die Freigabe auf den manuellen Modus eingestellt, in dem Sie Konversationen explizit mit dem Befehl /share teilen müssen.

Befehle

Sie können benutzerdefinierte Befehle für sich wiederholende Aufgaben über die Option command 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 mithilfe von Markdown-Dateien in ~/.config/opencode/commands/ oder .opencode/commands/ definieren. Mehr erfahren.

Tastenkombinationen

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

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

Mehr erfahren.

Automatisches Update

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