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

Konfig

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,
}

Locations

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.

Learn more about using the TUI here.

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.

Learn more about the server here.

Tools

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
  }
}

Learn more about tools here.

Models

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 local models konfigurieren. Learn more.

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.

Learn more about Amazon Bedrock configuration.

Themes

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": ""
}

Learn more here.

Agents

Ü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. Learn more here.

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.

Sharing

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. Learn more here.

Keybinds

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

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

Learn more here.

Autoupdate

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

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

Wenn Sie keine Updates wünschen, aber dringend möchten, wenn eine neue Version verfügbar ist, setzen Sie autoupdate auf "notify". Beachten Sie, dass dies nur funktioniert, wenn es nicht mit einem Paketmanager wie Homebrew installiert wurde.

Formatters

Sie können Codeformatierer über die Option formatter 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"]
    }
  }
}

Learn more about formatters here.

Permissions

OpenCode erlaubt standardmäßig alle Vorgänge, ohne dass eine ausdrückliche Genehmigung erforderlich ist. Sie können dies mit der Option permission ändern.

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

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

Learn more about permissions here.

Compaction

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

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}
  • auto – Die Sitzung wird automatisch komprimieren, wenn der Kontext voll ist (Standard: true).
  • prune – Alte Tool-Ausgaben entfernen, um Token zu sparen (Standard: true).

Watcher

Sie können Datei-Watcher-Ignoriermuster über die Option watcher konfigurieren.

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

Muster folgen der Glob-Syntax. Verwenden Sie diese Option, um verrauschte Verzeichnisse von der Dateiüberwachung auszuschließen.

MCP Server

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

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

Learn more here.

Plugins

Plugins erweitert OpenCode mit benutzerdefinierten Tools, Hooks und Integrationen.

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

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

Learn more here.

Instructions

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

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

Dies erfordert eine Reihe von Pfaden und Glob-Mustern zu Anweisungsdateien. Erfahren Sie mehr über Regeln hier.

Deaktivierte Anbieter

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

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

Die Option disabled_providers akzeptiert ein Array des Anbieters IDs. Wenn ein Anbieter deaktiviert ist:

  • Es wird nicht geladen, selbst wenn Umgebungsvariablen festgelegt sind.
  • Es wird nicht geladen, selbst wenn API-Schlüssel über den Befehl /connect konfiguriert werden.
  • Die Modelle des Anbieters erscheinen nicht in der Modellauswahlliste.

Aktivierte Anbieter

Sie können über die Option enabled_providers eine Zulassungsliste für Anbieter angeben. Wenn diese Option festgelegt ist, 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 darauf beschränken möchten, nur bestimmte Anbieter zu verwenden, anstatt sie einzeln zu deaktivieren.

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

Experimental

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

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

Variablen

Sie können die 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 eine leere Zeichenfolge 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 beginnend mit / oder ~

Diese sind nützlich für:

  • Bewahren Sie vertrauliche Daten wie API-Schlüssel in separaten Dateien auf.
  • Einschließlich große Anweisungsdateien, ohne Ihre Konfiguration zu überladen.
  • Gemeinsame Nutzung gemeinsamer Konfigurationsausschnitte über mehrere Konfigurationsdateien hinweg.