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

Agenten

Konfigurieren und verwenden Sie spezielle Agenten.

Agenten sind spezialisierte AI-Assistenten, die für bestimmte Aufgaben und Arbeitsabläufe konfiguriert werden können. Sie ermöglichen Ihnen die Erstellung gezielter Werkzeuge mit benutzerdefinierten Eingabeaufforderungen, Modellen und Werkzeugzugriff.

Sie können während einer Sitzung zwischen Agenten wechseln oder sie mit der Erwähnung @ aufrufen.

Typen

Es gibt zwei Arten von Agenten in OpenCode; Primäragenten und Subagenten.

Primäragenten

Primäragenten sind die Hauptassistenten, mit denen Sie direkt interagieren. Sie können sie mit der Tabulatortaste oder Ihrer konfigurierten Tastenkombination switch_agent durchblättern. Diese Agenten kümmern sich um Ihr Hauptgespräch. Der Werkzeugzugriff wird über Berechtigungen konfiguriert – zum Beispiel sind bei „Build“ alle Werkzeuge aktiviert, während „Plan“ eingeschränkt ist.

OpenCode verfügt über zwei integrierte Primäragenten: Build und Plan. Auch Schauen Sie sich diese unten an.

Subagenten

Unteragenten sind spezialisierte Assistenten, die Primäragenten für bestimmte Aufgaben aufrufen können. Sie können sie auch manuell aufrufen, indem Sie sie in Ihren Nachrichten @erwähnen.

OpenCode verfügt über zwei integrierte Subagenten: General und Explore. Wir werden uns das weiter unten ansehen.

Eingebaut

OpenCode verfügt über zwei integrierte Primäragenten und zwei integrierte Subagenten.

Use Build

Modus: primary

Build ist der Standard-Primäragent mit allen aktivierten Tools. Dies ist der Standardagent für Entwicklungsarbeiten, bei dem Sie vollen Zugriff auf Dateioperationen und Systembefehle benötigen.

Use Plan

Modus: primary

Ein eingeschränkter Agent, der für Planung und Analyse entwickelt wurde. Wir verwenden ein Berechtigungssystem, um Ihnen mehr Kontrolle zu geben und unbeabsichtigte Änderungen zu verhindern. Standardmäßig sind alle folgenden Elemente auf ask gesetzt:

  • file edits: Alle Schreibvorgänge, Patches und Bearbeitungen
  • bash: Alle Bash-Befehle

Dieser Agent ist nützlich, wenn Sie möchten, dass LLM Code analysiert, Änderungen vorgeschlagen oder Pläne erstellt werden, ohne tatsächliche Änderungen an Ihrer Codebasis vorzunehmen.

Use General

Modus: subagent

Ein Allzweckagent zur Recherche komplexerer Fragen und zur Ausführung mehrstufiger Aufgaben. Verfügt über vollständigen Zugriff auf das Tool (außer Todo), sodass bei Bedarf Dateiänderungen vorgenommen werden können. Verwenden Sie Matrizen, um mehrere Arbeitseinheiten parallel auszuführen.

Use Explore

Modus: subagent

Ein schneller, schreibgeschützter Agent zum Erkunden von Codebasen. Dateien können nicht geändert werden. Verwenden Sie dies, wenn Sie Dateien schnell anhand von Mustern finden, Code nach Schlüsselwörtern durchsuchen oder Fragen zur Codebasis beantworten müssen.

Use Compaction

Modus: primary

Versteckter Systemagent, der lange Kontext in einer kleineren Zusammenfassung komprimiert. Es wird bei Bedarf automatisch ausgeführt und ist im UI nicht auswählbar.

Use Title

Modus: primary

Versteckter Systemagent, der kurze Sitzungstitel generiert. Es läuft automatisch und ist im UI nicht auswählbar.

Use Summary

Modus: primary

Versteckter Systemagent, der Sitzungszusammenfassungen erstellt. Es läuft automatisch und ist im UI nicht auswählbar.

Verwendung

  1. Verwenden Sie für primäre Agenten die Tabulatortaste, um während einer Sitzung durch sie zu blättern. Sie können auch Ihre konfigurierte switch_agent-Tastenkombination verwenden.

  2. Subagenten können aufgerufen werden:

    • Automatisch durch primäre Agenten für spezielle Aufgaben basierend auf ihren Beschreibungen.

    • Manuell durch @ Erwähnung eines Subagenten in Ihrer Nachricht. Zum Beispiel.

      @general help me search for this function

  3. Navigation zwischen Sitzungen: Wenn Subagenten ihre eigenen untergeordneten Sitzungen erstellen, können Sie zwischen der übergeordneten Sitzung und allen untergeordneten Sitzungen sorgfältig handeln, indem Sie Folgendes verwenden:

    • <Leader>+Rechts (oder Ihre konfigurierte session_child_cycle-Tastenkombination), um vorwärts durch Eltern → Kind1 → Kind2 → … → Eltern zu blättern
    • <Leader>+Links (oder Ihre konfigurierte session_child_cycle_reverse-Tastenkombination), um rückwärts durch übergeordnetes Element ← untergeordnetes Element1 ← untergeordnetes Element2 ← … ← übergeordnetes Element zu blättern

    Dadurch können Sie nahtlos zwischen der Hauptkonversation und der spezialisierten Subagentenarbeit wechseln.

Konfigurieren

Sie können die integrierten Agenten anpassen oder über die Konfiguration eigene erstellen. Agenten können auf zwei Arten konfiguriert werden:

JSON

Konfigurieren Sie Agenten in Ihrer opencode.json-Konfigurationsdatei:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

Sie können Agenten auch mithilfe von Markdown-Dateien definieren. Platzieren Sie sie in:

  • Global: ~/.config/opencode/agents/
  • Pro Projekt: .opencode/agents/
~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---


You are in code review mode. Focus on:


- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations


Provide constructive feedback without making direct changes.

Der Name der Markdown-Datei wird zum Agentennamen. Beispielsweise erstellte review.md einen review-Agenten.

Options

Schauen Sie sich diese Konfigurationsmöglichkeiten im Detail an.

Beschreibung

Verwenden Sie die Option description, um eine kurze Beschreibung darüber bereitzustellen, was der Agent tut und wann er verwendet werden soll.

opencode.json
{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Dies ist eine erforderliche Konfigurationsoption.

Temperature

Steuern Sie die Zufälligkeit und Kreativität der Antworten von LLM mit der temperature-Konfiguration.

Höchste Werte machen die Antworten fokussierter und deterministischer, während höhere Werte die Kreativität und Variabilität steigern.

opencode.json
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Temperaturwerte liegen typischerweise zwischen 0.0 und 1.0:

  • 0.0-0.2: Sehr fokussierte und deterministische Antworten, ideal für Code-Analyse und Planung
  • 0.3-0.5: Ausgewogene Antworten mit etwas Kreativität, gut für allgemeine Entwicklungsaufgaben
  • 0.6-1.0: Kreativere und vielfältigere Antworten, nützlich für Brainstorming und Erkundung
opencode.json
{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Wenn keine Temperatur angegeben ist, verwendet OpenCode modellspezifische Standardwerte; typischerweise 0 für die meisten Modelle, 0.55 für Qwen-Modelle.

Maximale Schritte

Steuern Sie die maximale Anzahl an Agenteniterationen, die ein Agent durchführen kann, bevor er gezwungen wird, nur mit Text zu antworten. Dadurch können Benutzer, die die Kosten kontrollieren möchten, ein Limit für Agentenaktionen festlegen.

Wenn dies nicht festgelegt ist, iteriert der Agent weiter, bis das Modell den Stopp beschließt oder der Benutzer die Sitzung unterbricht.

opencode.json
{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

Wenn das Limit erreicht ist, erhält der Agent eine spezielle Systemaufforderung, die ihn anweist, mit einer Zusammenfassung seiner Arbeit und empfohlenen verbleibenden Aufgaben zu antworten.

Disable

Auf true setzen, um den Agenten zu deaktivieren.

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Geben Sie mit der prompt-Konfiguration eine benutzerdefinierte Systemaufforderungsdatei für diese Agenten an. Die Eingabeaufforderungsdatei sollte Anweisungen enthalten, die speziell auf den Zweck des Agenten zugeschnitten sind.

opencode.json
{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Dieser Pfad ist relativ zum Speicherort der Konfigurationsdatei. Dies funktioniert sowohl für die globale OpenCode-Konfiguration als auch für die projektspezifische Konfiguration.

Modell

Verwenden Sie die model-Konfiguration, um das Modell für diese Agenten zu überschreiben. Nützlich für die Verwendung verschiedener Modelle, die für verschiedene Aufgaben optimiert sind. Zum Beispiel ein schnelleres Modell für die Planung, ein leistungsfähigeres Modell für die Umsetzung.

opencode.json
{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

Die Modell-ID in Ihrer OpenCode-Konfiguration verwendet das Format provider/model-id. Wenn Sie beispielsweise OpenCode Zen verwenden, würden Sie opencode/gpt-5.1-codex für GPT 5.1 Codex verwenden.

Tools

Steuern Sie mit der tools-Konfiguration, welche Tools in diesem Agent verfügbar sind. Sie können bestimmte Tools aktivieren oder deaktivieren, indem Sie sie auf true oder false setzen.

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

Sie können Platzhalter auch verwenden, um mehrere Werkzeuge gleichzeitig zu steuern. So deaktivieren Sie beispielsweise alle Tools von einem MCP-Server:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

Learn more about tools.

Permissions

Sie können Berechtigungen konfigurieren, um zu verwalten, welche Aktionen ein Agent ausführen kann. Derzeit können die Berechtigungen für die Tools edit, bash und webfetch wie folgt konfiguriert werden:

  • "ask" – Bitten Sie um Genehmigung, bevor Sie das Tool ausführen
  • "allow" – Alle Vorgänge ohne Genehmigung zulassen
  • "deny" – Deaktivieren Sie das Tool
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

Sie können diese Berechtigungen pro Agent überschreiben.

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

Sie können Berechtigungen auch in Markdown-Agenten festlegen.

~/.config/opencode/agents/review.md
---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---


Only analyze code and suggest changes.

Sie können Berechtigungen für bestimmte Bash-Befehle festlegen.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

Dies kann ein Glob-Muster annehmen.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

Und Sie können den Platzhalter * auch verwenden, um Berechtigungen für alle Befehle zu verwalten. Da die letzte übereinstimmende Regel Vorrang hat, setzen Sie zuerst den Platzhalter * und danach bestimmte Regeln.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Learn more about permissions.

Mode

Steuern Sie den Modus des Agenten mit der mode-Konfiguration. Mit der Option mode wird festgelegt, wie der Agent verwendet werden kann.

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

Die Option mode kann auf primary, subagent oder all gesetzt werden. Wenn kein mode angegeben ist, wird standardmäßig all verwendet.

Hidden

Verstecken Sie einen Subagenten im Autovervollständigungsmenü @ mit hidden: true. Nützlich für interne Subagenten, die nur programmgesteuert von anderen Agenten über das Task-Tool aufgerufen werden sollten.

opencode.json
{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Dies wirkt sich nur auf die Benutzersichtbarkeit im Autovervollständigungsmenü aus. Versteckte Agenten können weiterhin vom Modell über das Aufgabentool aufgerufen werden, sofern die Berechtigungen dies zulassen.

Aufgabenberechtigungen

Steuern Sie, welche Subagenten ein Agent über das Task-Tool mit permission.task aufrufen kann. Verwendet Glob-Muster für eine flexible Zuordnung.

opencode.json
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Bei der Einstellung deny wird der Subagent vollständig aus der Beschreibung des Aufgabentools entfernt, sodass das Modell nicht versucht, ihn aufzurufen.

Color

Passen Sie das visuelle Erscheinungsbild des Agenten im UI mit der Option color an. Dies wirkt sich darauf aus, wie der Agent in der Benutzeroberfläche angezeigt wird.

Verwenden Sie eine gültige Hex-Farbe (e.g., #FF5733) oder Themenfarbe: primary, secondary, accent, success, warning, error, info.

opencode.json
{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

Steuern Sie die Antwortvielfalt mit der Option top_p. Alternative zur Temperatur zur Kontrolle des Zufalls.

opencode.json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

Die Werte reichen von 0.0 bis 1.0. Niedrigere Werte sind fokussierter, höhere Werte vielfältiger.

Additional

Alle anderen Optionen, die Sie in Ihrer Agentenkonfiguration angeben, werden als Modelloptionen direkt an den Anbieter weitergeleitet. Dadurch können Sie anbieterspezifische Funktionen und Parameter nutzen.

Mit den Argumentationsmodellen von OpenAI können Sie beispielsweise den Argumentationsaufwand steuern:

opencode.json
{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

Diese zusätzlichen Optionen sind modell- und anbieterspezifisch. Überprüfen Sie die Dokumentation Ihres Anbieters auf verfügbare Parameter.

Erstellen Sie Agenten

Mit dem folgenden Befehl können Sie neue Agenten erstellen:

Terminal-Fenster
opencode agent create

Dieser interaktive Befehl führt zu Folgendem:

  1. Fragen Sie, wo der Agent gespeichert werden soll. global oder projektspezifisch.
  2. Beschreibung dessen, was der Agent tun soll.
  3. Generieren Sie eine entsprechende Systemaufforderung und -kennung.
  4. Hier können Sie auswählen, auf welche Tools der Agent zugreifen kann.
  5. Erstellen Sie abschließend eine Markdown-Datei mit der Agentenkonfiguration.

Anwendungsfälle

Hier sind einige häufige Anwendungsfälle für verschiedene Agenten.

  • Build-Agent: Vollständige Entwicklungsarbeit mit allen aktivierten Tools
  • Planagent: Analyse und Planung ohne Änderungen
  • Review-Agent: Codeüberprüfung mit schreibgeschütztem Zugriff plus Dokumentationstools
  • Debug-Agent: Konzentriert sich auf die Untersuchung mit aktivierten Bash- und Lesetools
  • Docs-Agent: Schreiben von Dokumentationen mit Dateioperationen, aber ohne Systembefehle

Examples

Hier sind einige Beispielagenten, die für Sie nützlich sein könnten.

Dokumentationsagent

~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---


You are a technical writer. Create clear, comprehensive documentation.


Focus on:


- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Sicherheitsprüfer

~/.config/opencode/agents/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---


You are a security expert. Focus on identifying potential security issues.


Look for:


- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues