Konfiguration

Die OpenCode JSON‑Konfiguration verwenden.

Du kannst OpenCode über eine JSON‑Konfigurationsdatei konfigurieren.

Format

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

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

Speicherorte

Du kannst die Konfigurationsdatei an verschiedenen Orten ablegen, die sich in ihrer Priorität unterscheiden.

Die Einstellungen aller gefundenen Konfigurationsdateien werden kombiniert. Später geladene Dateien überschreiben frühere nur bei Konflikten; andere Schlüssel bleiben erhalten.

Beispiel: Setzt deine globale Config theme: "opencode" und autoupdate: true und deine Projekt‑Config model: "anthropic/claude-sonnet-4-5", enthält die effektive Config alle drei Werte.

Reihenfolge der Priorität

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

Remote‑Konfiguration (.well-known/opencode) – Organisations‑Defaults
Globale Config (~/.config/opencode/opencode.json) – Benutzerpräferenzen
Benutzerdefinierte Config (OPENCODE_CONFIG‑Umgebungsvariable)
Projekt‑Config (opencode.json im Projekt)
.opencode‑Verzeichnisse – Agents, Commands, Plugins
Inline‑Config (OPENCODE_CONFIG_CONTENT‑Umgebungsvariable)

Damit können Projekt‑Configs globale Defaults überschreiben, und globale Configs können Organisations‑Defaults überschreiben.

Remote

Organisationen können Standard‑Konfiguration über den Endpunkt .well-known/opencode bereitstellen. Diese wird automatisch geladen, wenn du dich bei einem unterstützten Provider authentifizierst.

Remote‑Config bildet die Basis; alle anderen Konfig‑Quellen können sie überschreiben.

Beispiel: Die Organisation liefert deaktivierte MCP‑Server:

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

Du kannst diese lokal aktivieren:

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

Global

Lege deine globale OpenCode‑Config unter ~/.config/opencode/opencode.json ab. Hier gehören benutzerweite Voreinstellungen hin, z. B. Themes, Provider oder Keybinds.

Die globale Config überschreibt die Remote‑Defaults der Organisation.

Pro Projekt

Füge im Projekt‑Root eine opencode.json hinzu. Projekt‑Config hat die höchste Priorität unter den Standard‑Dateien – sie überschreibt sowohl globale als auch Remote‑Config.

Beim Start sucht OpenCode in der aktuellen Umgebung nach einer Config und läuft nach oben, bis zum nächsten Git‑Root.

Diese Datei kann gefahrlos eingecheckt werden und verwendet dasselbe Schema wie die globale.

Eigener Pfad

Mit der Umgebungsvariablen OPENCODE_CONFIG kannst du einen eigenen Pfad angeben:

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

Diese Config wird zwischen globaler und Projekt‑Config geladen.

Eigenes Verzeichnis

Mit OPENCODE_CONFIG_DIR kannst du ein alternatives Konfig‑Verzeichnis setzen. Dieses Verzeichnis wird wie .opencode behandelt und nach Agents, Commands, Modes und Plugins durchsucht.

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

Das Verzeichnis wird nach der globalen Config und den .opencode‑Verzeichnissen geladen und kann deren Einstellungen überschreiben.

Schema

Das Schema der Config ist unter opencode.ai/config.json definiert.

Dein Editor kann damit Validierung und Autovervollständigung anbieten.

TUI

TUI‑spezifische Optionen stellst du unter tui ein:

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

Optionen:

scroll_acceleration.enabled – macOS‑artige Scroll‑Beschleunigung aktivieren. Hat Vorrang vor scroll_speed.
scroll_speed – Faktor für Scroll‑Geschwindigkeit (Standard: 1, Minimum: 1), ignoriert wenn scroll_acceleration.enabled true ist.
diff_style – Diff‑Darstellung: "auto" passt sich der Terminalbreite an, "stacked" zeigt immer einspaltig.

Mehr zur TUI‑Nutzung.

Server

Server‑Einstellungen für opencode serve und opencode web kommen in server:

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

Optionen:

port – Port, auf dem gelauscht wird
hostname – Hostname; wenn mdns aktiv ist und kein Host gesetzt ist, wird 0.0.0.0 verwendet
mdns – mDNS‑Service‑Discovery aktivieren
cors – zusätzliche erlaubte Browser‑Origins (Schema + Host + optionaler Port), z. B. https://app.example.com

Mehr zum Server.

Modelle

Provider und Modelle konfigurierst du über provider, model und small_model:

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

small_model ist ein separates Modell für leichte Aufgaben (z. B. Titelgenerierung). Standardmäßig versucht OpenCode ein günstigeres Modell beim gleichen Provider zu nutzen, sonst fällt es auf das Hauptmodell zurück.

Provider‑Optionen können u. a. timeout und setCacheKey enthalten:

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

timeout – Timeout in Millisekunden (Standard: 300000). false deaktiviert das Timeout.
setCacheKey – Erzwingt, dass für diesen Provider immer ein Cache‑Key gesetzt wird.

Du kannst auch lokale Modelle konfigurieren. Mehr zu Modellen.

Provider‑spezifische Optionen

Manche Provider unterstützen zusätzliche Optionen.

Amazon Bedrock

{
  "$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 (Standard: AWS_REGION oder us-east-1)
profile – Named Profile aus ~/.aws/credentials (Standard: AWS_PROFILE)
endpoint – eigenes Endpoint‑URL (Alias für baseURL; wenn beides gesetzt ist, gewinnt endpoint).

Mehr zu Amazon‑Bedrock‑Konfiguration.

Themes

Das Theme stellst du über theme ein:

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

Mehr zu Themes.

Agents

Spezialisierte Agents für bestimmte Aufgaben definierst du über agent:

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

Agents können auch als Markdown‑Dateien unter ~/.config/opencode/agent/ oder .opencode/agent/ definiert werden. Mehr dazu.

Standard‑Agent

Mit default_agent wählst du den Standard‑Agent, der verwendet wird, wenn keiner explizit gesetzt ist:

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

Der Standard‑Agent muss ein primärer Agent sein (kein Sub‑Agent). Das kann ein Built‑in wie "build" oder "plan" sein oder ein eigener Custom‑Agent. Ist der Agent unbekannt oder ein Sub‑Agent, fällt OpenCode mit Warnung auf "build" zurück.

Gilt für alle Oberflächen: TUI, CLI (opencode run), Desktop‑App und GitHub‑Action.

Die Share‑Funktion steuerst du über share:

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

Mögliche Werte:

"manual" – Nur manuelles Teilen über Befehle (Standard)
"auto" – Neue Sessions automatisch teilen
"disabled" – Sharing komplett deaktivieren

Standard ist "manual", d. h. du musst mit /share explizit teilen.

Commands

Wiederkehrende Aufgaben kannst du über command kapseln:

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

Commands kannst du auch als Markdown‑Dateien unter ~/.config/opencode/command/ oder .opencode/command/ anlegen. Mehr dazu.

Keybinds

Eigene Tastenkürzel definierst du unter keybinds:

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

Mehr zu Keybinds.

Autoupdate

OpenCode lädt beim Start standardmäßig automatisch Updates herunter. Das kannst du mit autoupdate ändern:

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

Wenn du kein Auto‑Update möchtest, aber über neue Versionen informiert werden willst, setze autoupdate auf "notify".

Formatter

Code‑Formatter stellst du über formatter ein:

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

Mehr zu Formattern.

Berechtigungen

Standardmäßig erlaubt OpenCode alle Operationen, ohne dich zu fragen. Über permission kannst du das ändern, z. B. um edit und bash zu bestätigen:

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

Mehr zu Berechtigungen.

Kompaktierung

Das Verhalten der Kontext‑Kompaktierung steuerst du über compaction:

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

auto – Session automatisch komprimieren, wenn der Kontext voll ist (Standard: true).
prune – Alte Tool‑Ausgaben entfernen, um Tokens zu sparen (Standard: true).

Watcher

File‑Watcher‑Ignore‑Patterns kommen in watcher:

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

Patterns folgen der Glob‑Syntax.

MCP‑Server

MCP‑Server konfigurierst du über mcp:

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

Mehr dazu.

Plugins

Plugins erweitern OpenCode um eigene Tools, Hooks und Integrationen.

Lege Plugin‑Dateien nach .opencode/plugin/ oder ~/.config/opencode/plugin/. NPM‑Plugins lädst du über plugin:

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

Mehr zu Plugins.

Instructions

Zusätzliche Anweisungsdateien kannst du über instructions referenzieren:

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

Das ist eine Liste von Pfaden oder Glob‑Mustern. Mehr zu Regeln.

Deaktivierte Provider

Über disabled_providers kannst du bestimmte Provider komplett deaktivieren – sie werden dann nicht geladen, selbst wenn Credentials vorhanden sind:

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

Wenn ein Provider deaktiviert ist:

wird er nicht geladen, auch wenn Umgebungsvariablen gesetzt sind;
werden über /connect gesetzte Keys ignoriert;
tauchen seine Modelle nicht in der Modell‑Liste auf.

Erlaubte Provider

Mit enabled_providers kannst du eine Allow‑List definieren. Wenn gesetzt, werden nur diese Provider geladen, alle anderen ignoriert:

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

Das ist hilfreich, wenn du nur bestimmte Provider erlauben möchtest.

Steht ein Provider in beiden Listen, gewinnt aus Kompatibilitätsgründen disabled_providers.

Experimental

Unter experimental stehen Optionen, die sich noch im aktiven Experiment befinden:

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

Variablen

In Config‑Dateien kannst du Platzhalter verwenden, um Umgebungsvariablen oder Dateiinhalte einzubinden.

Env‑Variablen

Mit {env:VARIABLE_NAME} greifst du auf Umgebungsvariablen zu:

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

Ist die Variable nicht gesetzt, wird sie durch einen leeren String ersetzt.

Dateien

Mit {file:path/to/file} kannst du Dateiinhalte injizieren:

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

Pfade können relativ zur Config‑Datei oder absolut (/ oder ~) sein.

Das ist nützlich, um

Secrets wie API‑Keys in separaten Dateien zu halten,
große Prompt‑Dateien auszulagern,
wiederverwendbare Konfig‑Snippets zwischen Projekten zu teilen.