Deutsch
Dokumentation
Agenten

Agenten

Konfigurieren und verwenden Sie spezialisierte Agenten.

Agenten sind spezialisierte KI-Assistenten, die für bestimmte Aufgaben und Workflows konfiguriert werden können. Sie ermöglichen es Ihnen, fokussierte Tools mit benutzerdefinierten Prompts, Modellen und Tool-Zugriff zu erstellen.

Tipp: Verwenden Sie den Plan-Agenten, um Code zu analysieren und Vorschläge zu prüfen, ohne Änderungen am Code vorzunehmen.

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äre Agenten und Subagenten.

Primäre Agenten

Primäre Agenten sind die Hauptassistenten, mit denen Sie direkt interagieren. Sie können mit der Tab-Taste oder Ihrem konfigurierten switch_agent-Tastenkürzel durch sie blättern. Diese Agenten kümmern sich um Ihr Hauptgespräch. Der Tool-Zugriff wird über Berechtigungen konfiguriert – beispielsweise hat Build alle Tools aktiviert, während Plan eingeschränkt ist.

Tipp: Sie können die Tab-Taste verwenden, um während einer Sitzung zwischen primären Agenten zu wechseln.

OpenCode wird mit zwei integrierten primären Agenten geliefert, Build und Plan. Wir sehen uns diese unten an.

Subagenten

Subagenten sind spezialisierte Assistenten, die primäre Agenten für bestimmte Aufgaben aufrufen können. Sie können sie auch manuell aufrufen, indem Sie sie in Ihren Nachrichten mit @ erwähnen.

OpenCode wird mit drei integrierten Subagenten geliefert, General, Explore und Scout. Wir sehen uns diese unten an.

Integriert

OpenCode wird mit zwei integrierten primären Agenten und drei integrierten Subagenten geliefert.

Build verwenden

Modus: primary

Build ist der Standard-primäre Agent mit allen aktivierten Tools. Dies ist der Standard-Agent für Entwicklungsarbeiten, bei denen Sie vollen Zugriff auf Dateioperationen und Systembefehle benötigen.

Plan verwenden

Modus: primary

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

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

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

General verwenden

Modus: subagent

Ein universell einsetzbarer Agent zur Erforschung komplexer Fragen und zur Ausführung mehrstufiger Aufgaben. Hat vollen Tool-Zugriff (außer todo), sodass er bei Bedarf Dateiänderungen vornehmen kann. Verwenden Sie ihn, um mehrere Arbeitseinheiten parallel auszuführen.

Explore verwenden

Modus: subagent

Ein schneller, schreibgeschützter Agent zum Erkunden von Codebasen. Kann keine Dateien ändern. Verwenden Sie ihn, wenn Sie schnell Dateien anhand von Mustern finden, Code nach Schlüsselwörtern durchsuchen oder Fragen zur Codebasis beantworten müssen.

Scout verwenden

Modus: subagent

Ein schreibgeschützter Agent für externe Dokumentation und Abhängigkeitsrecherche. Verwenden Sie ihn, wenn Sie ein Abhängigkeits-Repository in den von OpenCode verwalteten Cache klonen, Bibliotheksquellcode untersuchen oder lokalen Code mit Upstream-Implementierungen abgleichen müssen, ohne Ihren Arbeitsbereich zu ändern.

Compaction verwenden

Modus: primary

Versteckter System-Agent, der langen Kontext in eine kleinere Zusammenfassung komprimiert. Er läuft bei Bedarf automatisch und ist in der UI nicht auswählbar.

Title verwenden

Modus: primary

Versteckter System-Agent, der kurze Sitzungstitel generiert. Er läuft automatisch und ist in der UI nicht auswählbar.

Summary verwenden

Modus: primary

Versteckter System-Agent, der Sitzungszusammenfassungen erstellt. Er läuft automatisch und ist in der UI nicht auswählbar.

Verwendung

  1. Verwenden Sie für primäre Agenten die Tab-Taste, um während einer Sitzung durch sie zu blättern. Sie können auch Ihr konfiguriertes switch_agent-Tastenkürzel verwenden.

  2. Subagenten können aufgerufen werden:

    • Automatisch von primären Agenten für spezialisierte 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 untergeordnete Sitzungen erstellen, verwenden Sie session_child_first (Standard: <Leader>+Down), um vom übergeordneten Element aus die erste untergeordnete Sitzung zu betreten.

  4. Sobald Sie sich in einer untergeordneten Sitzung befinden, verwenden Sie:

    • session_child_cycle (Standard: Right ), um zur nächsten untergeordneten Sitzung zu wechseln
    • session_child_cycle_reverse (Standard: Left ), um zur vorherigen untergeordneten Sitzung zu wechseln
    • session_parent (Standard: Up ), um zur übergeordneten Sitzung zurückzukehren

    Dies ermöglicht es Ihnen, zwischen dem Hauptgespräch und spezialisierter Subagent-Arbeit zu wechseln.

Konfiguration

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}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "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.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

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
permission:
  edit: deny
  bash: deny
---
 
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. Zum Beispiel erstellt review.md einen review-Agenten.

Optionen

Sehen wir uns diese Konfigurationsoptionen im Detail an.

Description

Verwenden Sie die Option description, um eine kurze Beschreibung dessen zu geben, 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 LLM-Antworten mit der temperature-Konfiguration.

Niedrigere Werte machen Antworten fokussierter und deterministischer, während höhere Werte Kreativität und Variabilität erhöhen.

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 Codeanalyse 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.

Max steps

Steuern Sie die maximale Anzahl an agentischen Iterationen, die ein Agent ausführen kann, bevor er gezwungen wird, nur mit Text zu antworten. Dies ermöglicht es Benutzern, die Kosten kontrollieren möchten, ein Limit für agentische Aktionen festzulegen.

Wenn dies nicht gesetzt ist, fährt der Agent fort zu iterieren, bis das Modell beschließt anzuhalten 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 einen speziellen System-Prompt, der ihn anweist, mit einer Zusammenfassung seiner Arbeit und empfohlenen verbleibenden Aufgaben zu antworten.

Achtung: Das veraltete Feld maxSteps wird nicht mehr empfohlen. Verwenden Sie stattdessen steps.

Disable

Setzen Sie dies auf true, um den Agenten zu deaktivieren.

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

Prompt

Geben Sie mit der prompt-Konfiguration eine benutzerdefinierte System-Prompt-Datei für diesen Agenten an. Die Prompt-Datei sollte Anweisungen enthalten, die spezifisch für den Zweck des Agenten sind.

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

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

Model

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

Tipp: Wenn Sie kein Modell angeben, verwenden primäre Agenten das global konfigurierte Modell, während Subagenten das Modell des primären Agenten verwenden, der den Subagenten aufgerufen hat.

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 zum Beispiel OpenCode Zen verwenden, würden Sie opencode/gpt-5.1-codex für GPT 5.1 Codex verwenden.

Tools (veraltet)

tools ist veraltet. Bevorzugen Sie für neue Konfigurationen, Aktualisierungen und feiner abgestufte Kontrolle das permission-Feld des Agenten.

Ermöglicht es Ihnen zu steuern, welche Tools in diesem Agenten verfügbar sind. Sie können bestimmte Tools aktivieren oder deaktivieren, indem Sie sie auf true oder false setzen. In der tools-Konfiguration eines Agenten entspricht true der Berechtigung {"*": "allow"} und false der Berechtigung {"*": "deny"}.

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

Hinweis: Die agentenspezifische Konfiguration überschreibt die globale Konfiguration.

Sie können auch Wildcards in veralteten tools-Einträgen verwenden, um mehrere Tools auf einmal zu steuern. Zum Beispiel, um alle Tools von einem MCP-Server zu deaktivieren:

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

Erfahren Sie mehr über Tools.

Berechtigungen

Sie können Berechtigungen konfigurieren, um zu verwalten, welche Aktionen ein Agent ausführen kann. Jeder Berechtigungsschlüssel kann auf Folgendes gesetzt werden:

  • "ask" — Vor dem Ausführen des Tools zur Genehmigung auffordern
  • "allow" — Alle Operationen ohne Genehmigung zulassen
  • "deny" — Das Tool deaktivieren

Die verfügbaren Berechtigungsschlüssel sind:

SchlüsselTools, die er steuert
readread
editwrite, edit, apply_patch
globglob
grepgrep
listlist
bashbash
tasktask
external_directoryJedes Tool, das Dateien außerhalb des Projekt-Worktrees liest oder schreibt
todowritetodowrite, todoread
webfetchwebfetch
websearchwebsearch
lsplsp
skillskill
questionquestion
doom_loopWiederherstellungs-Prompts, wenn ein Agent feststeckt

read, edit, glob, grep, list, bash, task, external_directory, lsp und skill akzeptieren entweder eine Kurzform-Aktion ("allow" | "ask" | "deny") oder ein Objekt aus Glob/Muster → Aktion für feiner abgestufte Kontrolle. Die verbleibenden Schlüssel akzeptieren nur die Kurzform-Aktion.

Hinweis: Berechtigungsschlüssel werden als Wildcard-Muster gegen den zugrunde liegenden Tool-Namen abgeglichen, sodass dieselbe Syntax für integrierte, benutzerdefinierte und MCP-Tools funktioniert — zum Beispiel verweigert "mymcp_*": "deny" jedes Tool von einem MCP-Server, und "mymcp_search": "ask" zielt auf ein einzelnes ab.

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 auch die *-Wildcard verwenden, um Berechtigungen für alle Befehle zu verwalten. Da die letzte übereinstimmende Regel Vorrang hat, platzieren Sie die *-Wildcard zuerst und spezifische Regeln danach.

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

Erfahren Sie mehr über Berechtigungen.

Mode

Steuern Sie den Modus des Agenten mit der mode-Konfiguration. Die Option mode wird verwendet, um zu bestimmen, 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

Blenden Sie einen Subagenten aus dem @-Autovervollständigungsmenü mit hidden: true aus. Nützlich für interne Subagenten, die nur programmatisch von anderen Agenten über das Task-Tool aufgerufen werden sollen.

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

Dies betrifft nur die Sichtbarkeit für den Benutzer im Autovervollständigungsmenü. Versteckte Agenten können weiterhin vom Modell über das Task-Tool aufgerufen werden, sofern es die Berechtigungen erlauben.

Hinweis: Gilt nur für Agenten mit mode: subagent.

Task-Berechtigungen

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

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

Wenn auf deny gesetzt, wird der Subagent vollständig aus der Beschreibung des Task-Tools entfernt, sodass das Modell nicht versucht, ihn aufzurufen.

Tipp: Regeln werden der Reihe nach ausgewertet, und die letzte übereinstimmende Regel gewinnt. Im obigen Beispiel passt orchestrator-planner sowohl auf * (deny) als auch auf orchestrator-* (allow), aber da orchestrator-* nach * kommt, ist das Ergebnis allow.

Tipp: Benutzer können jeden Subagenten jederzeit direkt über das @-Autovervollständigungsmenü aufrufen, selbst wenn die Task-Berechtigungen des Agenten dies verweigern würden.

Color

Passen Sie das visuelle Erscheinungsbild des Agenten in der UI mit der Option color an. Dies beeinflusst, wie der Agent in der Oberfläche erscheint.

Verwenden Sie eine gültige Hex-Farbe (z. B. #FF5733) oder eine Theme-Farbe: 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 Steuerung der Zufälligkeit.

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

Die Werte liegen zwischen 0.0 und 1.0. Niedrigere Werte sind fokussierter, höhere Werte vielfältiger.

Zusätzliche Optionen

Alle anderen Optionen, die Sie in Ihrer Agentenkonfiguration angeben, werden direkt an den Anbieter durchgereicht als Modelloptionen. Dies ermöglicht es Ihnen, anbieterspezifische Funktionen und Parameter zu verwenden.

Zum Beispiel können Sie mit den Reasoning-Modellen von OpenAI den Reasoning-Aufwand 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. Prüfen Sie die Dokumentation Ihres Anbieters auf verfügbare Parameter.

Tipp: Führen Sie opencode models aus, um eine Liste der verfügbaren Modelle zu sehen.

Agenten erstellen

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

opencode agent create

Dieser interaktive Befehl wird:

  1. Fragen, wo der Agent gespeichert werden soll; global oder projektspezifisch.
  2. Eine Beschreibung dessen, was der Agent tun soll.
  3. Einen passenden System-Prompt und Bezeichner generieren.
  4. Sie auswählen lassen, welche Berechtigungen dem Agenten erlaubt sein sollen (alles, was Sie nicht auswählen, wird verweigert).
  5. Schließlich eine Markdown-Datei mit der Agentenkonfiguration erstellen.

Anwendungsfälle

Hier sind einige gängige Anwendungsfälle für verschiedene Agenten.

  • Build-Agent : Vollständige Entwicklungsarbeit mit allen aktivierten Tools
  • Plan-Agent : Analyse und Planung ohne Änderungen
  • Review-Agent : Code-Review mit schreibgeschütztem Zugriff plus Dokumentationstools
  • Debug-Agent : Fokussiert auf Untersuchung mit aktivierten Bash- und Read-Tools
  • Docs-Agent : Dokumentationserstellung mit Dateioperationen, aber ohne Systembefehle

Beispiele

Hier sind einige Beispielagenten, die Sie nützlich finden könnten.

Tipp: Haben Sie einen Agenten, den Sie teilen möchten? Reichen Sie einen PR ein (opens in a new tab).

Dokumentationsagent

~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---
 
You are a technical writer. Create clear, comprehensive documentation.
 
Focus on:
 
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Security-Auditor

~/.config/opencode/agents/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
---
 
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
RegelnModelle