Detaillierte Erklärung der OpenCode-Agent-Konfiguration

Agenten sind spezialisierte KI-Assistenten in OpenCode. Jeder Agent kann mit einem eigenen System-Prompt, Modell, Werkzeugzugriffsberechtigungen und Verhaltensbeschränkungen konfiguriert werden, um bestimmte Arten von Aufgaben und Workflows zu bewältigen. Sie können Agenten jederzeit während einer Sitzung wechseln, oder durch@ProxyNamedirektes Aufrufen eines bestimmten Agenten.

Agententypen

Agenten in OpenCode werden in zwei Typen unterteilt, die jeweils unterschiedliche Aufrufmethoden und Zuständigkeiten haben:

Type Beschreibung Wechselmethode
Primärer Agent Der Hauptassistent, mit dem Sie direkt interagieren und der den primären Gesprächsverlauf steuert. Werkzeugzugriffsberechtigungen erfolgen überpermissionconfiguration drückenTabTasten-Zyklusumschaltung, oder verwenden Sie die konfigurierteagent_cycleTastenkürzel
Subagent Ein Assistent, der vom primären Agenten aufgerufen wird, um spezialisierte Aufgaben auszuführen, und in einer unabhängigen untergeordneten Sitzung läuft, ohne den Kontext der Hauptsitzung zu beeinflussen Automatisch vom primären Agenten aufgerufen oder manuell in einer Nachricht aufgerufen unter Verwendung von@ProxyNamemanuell aufrufen

Integrierte Agenten

OpenCode enthält 4 sofort einsatzbereite Agenten sowie 3 automatisch ausgeführte Systemagenten:

1. Build (Primärer Agent)

Der standardmäßige primäre Agent, bei dem alle Tools aktiviert sind, geeignet für die tägliche Entwicklungsarbeit, die vollständige Dateioperationen und Zugriff auf Systembefehle erfordert. Dies ist der Agent, den Sie am häufigsten verwenden werden.

2. Plan (Primärer Agent)

Ein eingeschränkter Agent, der speziell für Codeanalyse und Planung entwickelt wurde. Standardmäßig lösen die folgenden Vorgänge alle eine Genehmigungsaufforderung aus (eingestellt aufask）：

  • Dateibearbeitungen: alle Schreib-, Patch- und Bearbeitungsvorgänge
  • bash: alle bash-Befehle

Wenn Sie möchten, dass das LLM Code analysiert, Vorschläge macht oder einen Ausführungsplan erstellt, aber nicht möchten, dass es tatsächliche Änderungen an der Codebasis vornimmt, wechseln Sie zum Plan-Agenten.

3. General (Subagent)

Ein Allzweck-Subagent mit vollem Tool-Zugriff (außer dem todo-Tool) und der Fähigkeit, Dateien zu ändern. Geeignet für die Untersuchung komplexer Probleme und die Ausführung mehrstufiger Aufgaben; kann außerdem mehrere unabhängige Arbeitseinheiten parallel ausführen.

4. Explore (Subagent)

Ein schreibgeschützter Subagent, der keine Dateien ändern kann. Geeignet, um schnell Dateien zu finden, Code-Schlüsselwörter zu suchen oder Fragen zur Struktur der Codebasis zu beantworten. Er ist schnell und hat keine Nebenwirkungen.

5. System-Agenten (ausgeblendet)

Die folgenden drei Agenten werden automatisch von OpenCode verwaltet,und erscheinen nicht in der Agentenwechsel-ListeEs besteht weder die Notwendigkeit noch die Möglichkeit, sie manuell auszuwählen:

Agentenname Verantwortlichkeit Auslösezeitpunkt
Kompaktierung Komprimiert übermäßig langen Kontext zu einer kleineren Zusammenfassung, um das Überschreiten des Modellkontextlimits zu verhindern Wird automatisch ausgeführt, wenn die Kontextlänge einen Schwellenwert erreicht
Title Erzeugt einen kurzen Titel für die Sitzung Wird automatisch ausgeführt, nachdem eine neue Sitzung gestartet ist
Zusammenfassung Erstellt eine Zusammenfassung für die Sitzung Wird automatisch ausgeführt, wenn eine Sitzungszusammenfassung benötigt wird

So verwendest du Agenten

1. Primäre Agenten wechseln

Drücke während einer SitzungTabTaste, um durch alle primären Agenten zu wechseln; drückeShift+Tabum rückwärts zu wechseln. Du kannst auch<Leader>averwenden, um die Agentenliste zu öffnen und direkt auszuwählen.

2. Subagenten aufrufen

Es gibt zwei Möglichkeiten, Subagenten aufzurufen:

  • Automatischer Aufruf: Wenn der primäre Agent basierend auf der Art der Aufgabe feststellt, dass ein bestimmter Subagent benötigt wird, ruft er den Subagenten automatisch auf und delegiert die Aufgabe an ihn
  • Manueller @-Aufruf: Verwende in einer Nachricht@ProxyNameum direkt anzugeben, welcher Subagent dies übernehmen soll
@general help me search for this function across the codebase

3. Zwischen übergeordneten und untergeordneten Sitzungen navigieren

Wenn ein Subagent ausgeführt wird, erstellt er eine unabhängige untergeordnete Sitzung. Du kannst Tastenkombinationen verwenden, um zwischen der übergeordneten Sitzung und jeder untergeordneten Sitzung zu navigieren:

Tastenkürzel Aktion
<Leader>+→（session_child_cycle） Vorwärts wechseln: Übergeordnete Sitzung → Untergeordnete Sitzung 1 → Untergeordnete Sitzung 2 → … → Übergeordnete Sitzung
<Leader>+←（session_child_cycle_reverse） Rückwärts wechseln: Übergeordnete Sitzung ← Untergeordnete Sitzung 1 ← Untergeordnete Sitzung 2 ← … ← Übergeordnete Sitzung
<Leader>+↑（session_parent） Direkt zur übergeordneten Sitzung zurückkehren

Zwei Konfigurationsmethoden

Agents können entweder über die JSON-Konfiguration oder über Markdown-Dateien definiert werden. Beide Methoden haben die gleiche Wirkung; wähle nach Bedarf:

Methode 1: In opencode.json konfigurieren

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {                                           // Überschreibe die integrierte build-Agent-Konfiguration
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",           // System-Prompt aus Datei laden
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "code-reviewer": {                                   // Benutzerdefinierter Subagent
      "description": "Überprüft Code auf Best Practices und potenzielle Probleme",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "Du bist ein Code-Reviewer. Konzentriere dich auf Sicherheit, Leistung und Wartbarkeit.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Methode 2: Markdown-Datei

Erstellen Sie ein.mdDatei im folgenden Pfad,Der Dateiname ist der Agentenname(e.g.,review.mdentspricht dem Agentennamenreview）：

  • Global:~/.config/opencode/agents/(Gültig für alle Projekte)
  • Projektebene:.opencode/agents/(Nur für das aktuelle Projekt gültig)

Beispiel

# Dateipfad: ~/.config/opencode/agents/review.md
---
description: Überprüft Code auf Qualität und Best Practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

Du bist im Code-Review-Modus. Konzentriere dich auf:

- Codequalität und Best Practices
- Mögliche Fehler und Randfälle
- Auswirkungen auf die Leistung
- Sicherheitsüberlegungen

Konstruktives Feedback geben, ohne direkte Änderungen vorzunehmen.

Konfigurationsoptionen erklärt

description (Beschreibung)

Eine Beschreibung der Funktionalität des Agenten, angezeigt in der Agentenliste und@Autovervollständigungsmenü. Sie hilft Benutzern und dem primären Agenten zu entscheiden, wann dieser Agent aufgerufen werden soll. Bei benutzerdefinierten Agenten ist dieses Felderforderlich：

Beispiel

{
  "agent": {
    "review": {
      "description": "Überprüft Code auf Best Practices und potenzielle Probleme"
    }
  }
}

mode (Modus)

Steuert, wie der Agent verwendet wird. Es kann auf einen der folgenden drei Werte gesetzt werden:

Wert Beschreibung
"primary" Primärer Agent, erscheint in der Tab-Wechselliste, wird für die Hauptkonversation verwendet
"subagent" Subagent, nicht in der Tab-Wechselliste, wird vom primären Agenten oder manuell über @ aufgerufen
"all" Wird sowohl als primärer Agent als auch als Subagent verwendet (Standardwert, wenn mode nicht angegeben ist)

Beispiel

{
  "agent": {
    "review": {
      "mode": "subagent"    // Wird nur als Subagent verwendet, erscheint nicht in der Liste zum Wechseln des primären Agenten
    }
  }
}

model (Modell)

Gibt ein bestimmtes Modell für den Agenten an und überschreibt das Standardmodell in der globalen Konfiguration. Das Format istprovider/model-id. Geeignet, um verschiedene Modelle für verschiedene Aufgaben zu verwenden, zum Beispiel ein schnelleres kleines Modell für Planungsaufgaben und ein leistungsfähigeres großes Modell für die Codegenerierung:

Beispiel

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"    // Verwenden Sie das schnellere Haiku-Modell für Planungsaufgaben
    },
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514"   // Verwenden Sie das leistungsfähigere Sonnet-Modell für Entwicklungsaufgaben
    }
  }
}

Wenn nicht angegebenmodel, verwendet der primäre Agent das Standardmodell aus der globalen Konfiguration, und Subagenten erben das Modell, das vom primären Agenten verwendet wird, der sie aufgerufen hat. Ausführungopencode modelsSie können die Liste aller verfügbaren Modelle anzeigen.

prompt (System-Prompt)

Geben Sie einen benutzerdefinierten System-Prompt für den Agenten an. Sie können eine Zeichenkette direkt schreiben oder die{file:./路径}Syntax zum Laden aus einer externen Datei. Der Pfad ist relativ zum Speicherort der Konfigurationsdatei:

Beispiel

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
      // Den Prompt aus prompts/code-review.txt im selben Verzeichnis wie opencode.json lesen
      // Geeignet für lange Prompts; diese sollten separat in einer Textdatei gepflegt werden
    }
  }
}

temperature

Steuert die Zufälligkeit der Modellausgabe. Niedrigere Werte erzeugen deterministischere Ausgaben, geeignet für Aufgaben, die präzise Ergebnisse erfordern; höhere Werte erzeugen vielfältigere Ausgaben, geeignet für kreative Aufgaben:

Temperaturbereich Ausgabemerkmale Anwendbare Szenarien
0.0 – 0.2 Sehr fokussiert, sehr deterministisch Codeanalyse, Planung, Debugging, Review
0.3 – 0.5 Ausgewogen, kombiniert Genauigkeit und Flexibilität Allgemeine Entwicklungsaufgaben, Dokumentationserstellung
0.6 – 1.0 Kreativer und vielfältiger Brainstorming, Lösungsfindung, kreatives Schreiben

Beispiel

{
  "agent": {
    "analyze": {
      "temperature": 0.1,                          // Analyseaufgaben: hoher Determinismus
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3                           // Entwicklungsaufgaben: ausgewogen
    },
    "brainstorm": {
      "temperature": 0.7,                          // Brainstorming: kreativer
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Wenn nicht angegebentemperature, verwendet OpenCode den Standardwert des Modells — die meisten Modelle verwenden standardmäßig0, während Qwen-Serienmodelle standardmäßig0.55。

steps (Maximale Schritte)

Steuert die maximale Anzahl von Iterationen (d. h. Runden von Tool-Aufrufen), die der Agent ausführen kann, bevor er gezwungen wird, mit einfachem Text zu antworten. Geeignet für Szenarien, in denen Sie Kosten kontrollieren oder verhindern möchten, dass der Agent endlos weiterläuft:

Beispiel

{
  "agent": {
    "quick-thinker": {
      "description": "Schnelles Schlussfolgern mit begrenzten Iterationen",
      "prompt": "Du bist ein schneller Denker. Löse Probleme mit minimalen Schritten.",
      "steps": 5    // Führe höchstens 5 Iterationen aus; danach gibt der Agent eine Zusammenfassung des aktuellen Fortschritts und der verbleibenden vorgeschlagenen Aufgaben aus.
    }
  }
}

Wenn nicht gesetztsteps, wird der Agent weiter iterieren, bis das Modell von selbst stoppt oder der Benutzer manuell unterbricht.

VeraltetmaxStepsFeld ist veraltet, bitte verwenden Siesteps。

tools (Tool-Zugriff)

Steuert, welche Tools dieser Agent verwenden kann. Setzen Sie den Tool-Namen auftrueoderfalse. Die Konfiguration auf Agent-Ebene wirddie globale Konfiguration überschreiben：

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,     // Global: Dateischreiben erlauben
    "bash": true       // Global: Bash-Befehle erlauben
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,    // plan agent: globale Einstellungen überschreiben, Dateischreiben deaktivieren
        "bash": false      // plan agent: globale Einstellungen überschreiben, bash deaktivieren
      }
    }
  }
}

Sie können auch Wildcards verwenden, um Tools in großen Mengen zu steuern, zum Beispiel alle Tools von einem bestimmten MCP-Server deaktivieren:

Beispiel

{
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,    // Alle Tools vom mymcp-Server deaktivieren (Glob-Matching)
        "write": false,
        "edit": false
      }
    }
  }
}

Berechtigung (Berechtigungen)

Konfigurieren Sie eine feinere Berechtigungssteuerung für den Agenten. Sie können jede Operation einstellen auf"allow"(allow),"ask"(ask), oder"deny"(deny):

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"         // Global: standardmäßig alle Dateibearbeitung verweigern
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"      // Build-Agent: globale Einstellungen überschreiben, Genehmigung vor Bearbeitung erforderlich
      }
    }
  }
}

FürbashTools, können Sie weiter auf bestimmte Befehle verfeinern, mit Glob-Wildcard-Unterstützung, unddie letzte übereinstimmende Regel hat Vorrang(Es wird empfohlen,*Wildcard-Regeln zuerst und spezifische Regeln später):

Beispiel

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",             // Fallback: Alle Bash-Befehle erfordern standardmäßig eine Genehmigung
          "git status *": "allow",// git-status-bezogene Befehle sind direkt erlaubt (spezifischer, hat Vorrang)
          "grep *": "allow"       // grep-Suchbefehle sind direkt erlaubt
        }
      }
    }
  }
}

In einer Markdown-Agent-Datei können Sie Berechtigungen auch im Frontmatter konfigurieren:

Beispiel

# Dateipfad: ~/.config/opencode/agents/review.md
---
description: Code-Review ohne Änderungen
mode: subagent
permission:
  edit: deny          # Alle Dateibearbeitungen verweigern
  bash:
    "*": ask          # bash-Befehle erfordern standardmäßig eine Genehmigung
    "git diff": allow # git diff erlauben
    "git log*": allow # git log und seine Varianten erlauben
    "grep *": allow   # grep-Suche erlauben
  webfetch: deny      # Zugriff auf externe URLs verweigern
---

Nur Code analysieren und Änderungen vorschlagen.

permission.task (Task-Berechtigungen)

Steuert, welche Subagenten dieser Agent über das Task-Tool aufrufen kann. Unterstützt Glob-Matching. Auf"deny"gesetzt, wird der Subagent vollständig aus der Beschreibung des Task-Tools entfernt, und das Modell wird nicht versuchen, ihn aufzurufen:

Beispiel

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",                  // Fallback: Aufruf aller Subagenten standardmäßig verweigern
          "orchestrator-*": "allow",   // Erlaubt das Aufrufen von Subagenten, die mit orchestrator- beginnen
          "code-reviewer": "ask"        // Das Aufrufen von code-reviewer erfordert eine Benutzerbestätigung
          // Die letzte übereinstimmende Regel hat Vorrang: orchestrator-planner matcht sowohl * als auch orchestrator-*,
          // Da orchestrator-* später kommt, ist das Ergebnis allow
        }
      }
    }
  }
}

hidden (Versteckt)

Verbirgt den Subagenten vor dem@Autovervollständigungsmenü und erlaubt nur, ihn programmgesteuert über das Task-Tool aufzurufen. Geeignet für Tool-Subagenten, die nur intern von anderen Agenten aufgerufen werden sollten:

Beispiel

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",    // hidden funktioniert nur bei Subagenten
      "hidden": true         // Nach dem Ausblenden erscheint dieser Agent nicht im @-Vervollständigungsmenü des Benutzers,
                             // aber wenn Berechtigungen es zulassen, kann das Modell es weiterhin über das Task-Tool aufrufen
    }
  }
}

color

Passt die Anzeigefarbe des Agenten in der UI an. Unterstützt Hex-Farbwerte oder Theme-Farb-Schlüsselwörter (primary、secondary、accent、success、warning、error、info）：

Beispiel

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"      // Hex-Farbe verwenden
    },
    "code-reviewer": {
      "color": "accent"       // Ein Theme-Farb-Schlüsselwort verwenden
    }
  }
}

top_p (Sampling-Diversität)

top_pJatemperatureEin weiterer Parameter zur Steuerung der Ausgabediversität, mit einem Wertebereich von 0.0 – 1.0. Niedrigere Werte erzeugen fokussiertere Ausgaben, höhere Werte erzeugen vielfältigere Ausgaben:

Beispiel

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9    // Höheres top_p erhöht die Ausgabediversität
    }
  }
}

disable (Deaktivieren)

Versetzt den Agenten in einen deaktivierten Zustand. Sobald deaktiviert, erscheint der Agent nicht in der Auswahlliste:

Beispiel

{
  "agent": {
    "review": {
      "disable": true    // Diesen Agenten deaktivieren, ohne andere Agenten zu beeinflussen.
    }
  }
}

Weitere Modellparameter

Alle nicht erkannten Felder in der Agent-Konfiguration werden direkt als Modellparameter an den Dienstanbieter weitergegeben. Dies ermöglicht die Nutzung anbieterspezifischer erweiterter Funktionen:

Beispiel

{
  "agent": {
    "deep-thinker": {
      "description": "Agent, der hohen Reasoning-Aufwand für komplexe Probleme verwendet",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",    // OpenAI Reasoning-Aufwand-Parameter, direkt an die OpenAI-API übergeben
      "textVerbosity": "low"        // OpenAI-Parameter für Antwort-Ausführlichkeit
    }
  }
}

Durchgereichte Parameter variieren je nach Dienstanbieter und Modell. Bitte konsultieren Sie die API-Dokumentation des entsprechenden Anbieters, um die verfügbaren Parameternamen zu überprüfen.

Agenten schnell erstellen

Zusätzlich zum manuellen Schreiben von Konfigurationsdateien können Sie auch das interaktive Kommandozeilen-Tool verwenden, um schnell einen Agenten zu generieren:

opencode agent create

Dieser Befehl führt Sie nacheinander durch die folgenden Schritte:

  1. Wählen Sie, wo der Agent gespeichert werden soll (global~/.config/opencode/agents/oder auf Projektebene).opencode/agents/）
  2. Beschreiben Sie die Verantwortlichkeiten und Ziele des Agenten
  3. Automatisch einen passenden System-Prompt und Agentenbezeichner generieren
  4. Wählen Sie, auf welche Tools der Agent zugreifen kann
  5. Generieren Sie eine Markdown-Datei mit der vollständigen Konfiguration am ausgewählten Speicherort

Agenten-Beispiele

Agent zum Schreiben von Dokumentation

Beispiel

# Dateipfad: ~/.config/opencode/agents/docs-writer.md
---
description: Schreibt und pflegt Projektdokumentation
mode: subagent
tools:
  bash: false    # bash deaktivieren; Dokumentationserstellung muss keine Befehle ausführen
---

Sie sind ein technischer Redakteur. Erstellen Sie klare, umfassende Dokumentation.

Fokus auf:
- Klare Erklärungen
- Saubere Struktur
- Codebeispiele
- Benutzerfreundliche Sprache

Sicherheits-Audit-Agent

Beispiel

# Dateipfad: ~/.config/opencode/agents/security-auditor.md
---
description: Führt Sicherheitsaudits durch und identifiziert Schwachstellen
mode: subagent
tools:
  write: false    # Schreibgeschützt: keine Dateien schreiben
  edit: false     # Schreibgeschützt: keine Dateien bearbeiten
---

Du bist ein Sicherheitsexperte. Konzentriere dich auf das Erkennen potenzieller Sicherheitsprobleme.

Suchen Sie nach:
- Schwachstellen bei der Eingabevalidierung
- Schwachstellen bei Authentifizierung und Autorisierung
- Risiken der Datenoffenlegung
- Schwachstellen in Abhängigkeiten
- Sicherheitsprobleme in der Konfiguration

Häufige Anwendungsfälle

Szenario Empfohlene Agent-Konfiguration
Tägliche Entwicklung, erfordert vollständige Tool-Berechtigungen Den integriertenBuildAgent verwenden
Code analysieren und Pläne erstellen, ohne Dateien zu ändern Zum integriertenPlanAgent wechseln
Schreibgeschützte Abfrage der Codebasisstruktur oder Schlüsselwörter Über@exploreDen integriertenExploreSubagent aufrufen
Mehrere unabhängige Aufgaben parallel ausführen Über@generalmehrereGeneral-Subagenten für parallele Verarbeitung aufrufen
Sicherheits- oder Qualitätsprüfung von Code durchführen Benutzerdefinierter schreibgeschützter Subagent (Schreiben/Bearbeiten deaktivieren), niedrige Temperatur festlegen (0.1)
Kosten kontrollieren, KI-Ausführungsschritte begrenzen KonfigurierenstepsParameter zur Begrenzung der maximalen Anzahl von Iterationen
Weitere Erweiterungen