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 Werkzeuge mit benutzerdefinierten Prompts, Modellen und Werkzeugzugriff zu erstellen.

Tipp: Verwenden Sie den plan-Agenten, um Code zu analysieren und Vorschläge zu überprüfen, ohne Codeänderungen 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 Ihrer konfigurierten switch_agent-Tastenkombination zwischen ihnen wechseln. Diese Agenten führen Ihre Hauptkonversation. Der Werkzeugzugriff wird über Berechtigungen konfiguriert — zum Beispiel hat Build alle Werkzeuge 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 werden diese unten betrachten.

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 @ erwähnen.

OpenCode wird mit zwei integrierten Subagenten geliefert: General und Explore. Wir werden diese unten betrachten.

Integriert

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

Build verwenden

Modus: primary

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

Plan verwenden

Modus: primary

Ein eingeschränkter Agent für Planung und Analyse. 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 Bearbeitungen
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 Allzweck-Agent für die Recherche komplexer Fragen und die Ausführung mehrstufiger Aufgaben. Hat vollen Werkzeugzugriff (außer todo), kann also bei Bedarf Dateiänderungen vornehmen. Verwenden Sie diesen, 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 diesen, wenn Sie schnell Dateien nach Mustern finden, Code nach Schlüsselwörtern durchsuchen oder Fragen zur Codebasis beantworten müssen.

Compaction verwenden

Modus: primary

Versteckter Systemagent, der langen Kontext in eine kleinere Zusammenfassung komprimiert. Er läuft automatisch bei Bedarf und ist in der Benutzeroberfläche nicht auswählbar.

Title verwenden

Modus: primary

Versteckter Systemagent, der kurze Sitzungstitel generiert. Er läuft automatisch und ist in der Benutzeroberfläche nicht auswählbar.

Summary verwenden

Modus: primary

Versteckter Systemagent, der Sitzungszusammenfassungen erstellt. Er läuft automatisch und ist in der Benutzeroberfläche nicht auswählbar.

Verwendung

Für primäre Agenten verwenden Sie die Tab-Taste, um während einer Sitzung zwischen ihnen zu wechseln. Sie können auch Ihre konfigurierte switch_agent-Tastenkombination verwenden.
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
```
Navigation zwischen Sitzungen: Wenn Subagenten ihre eigenen Untersitzungen erstellen, können Sie zwischen der übergeordneten Sitzung und allen Untersitzungen navigieren mit:
- <Leader>+Right (oder Ihrer konfigurierten session_child_cycle-Tastenkombination) um vorwärts zu wechseln: Eltern → Kind1 → Kind2 → … → Eltern
- <Leader>+Left (oder Ihrer konfigurierten session_child_cycle_reverse-Tastenkombination) um rückwärts zu wechseln: Eltern ← Kind1 ← Kind2 ← … ← Eltern
Dies ermöglicht es Ihnen, nahtlos zwischen der Hauptkonversation und spezialisierter Subagenten-Arbeit zu wechseln.

Konfigurieren

Sie können die integrierten Agenten anpassen oder Ihre eigenen durch Konfiguration 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 mit 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 Markdown-Dateiname wird zum Agentennamen. Zum Beispiel erstellt review.md einen review-Agenten.

Optionen

Schauen wir uns diese Konfigurationsoptionen im Detail an.

Description

Verwenden Sie die description-Option, 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
    }
  }
}

Temperature-Werte reichen typischerweise von 0.0 bis 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 variablere Antworten, nützlich für Brainstorming und Exploration

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 Temperature 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 von Agenteniterationen, 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 Agentenaktionen festzulegen.

Wenn dies nicht gesetzt ist, wird der Agent weiter iterieren, bis das Modell sich entscheidet aufzuhören 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 Systemprompt, der ihn anweist, mit einer Zusammenfassung seiner Arbeit und empfohlenen verbleibenden Aufgaben zu antworten.

Achtung: Das Legacy-Feld maxSteps ist veraltet. Verwenden Sie stattdessen steps.

Disable

Setzen Sie auf true, um den Agenten zu deaktivieren.

opencode.json

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Geben Sie eine benutzerdefinierte Systemprompt-Datei für diesen Agenten mit der prompt-Konfiguration 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 für die Verwendung verschiedener Modelle, die für verschiedene Aufgaben optimiert sind. Zum Beispiel ein schnelleres Modell für Planung, ein leistungsfähigeres Modell für 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 beispielsweise OpenCode Zen verwenden, würden Sie opencode/gpt-5.1-codex für GPT 5.1 Codex verwenden.

Tools

Steuern Sie, welche Werkzeuge in diesem Agenten verfügbar sind, mit der tools-Konfiguration. Sie können bestimmte Werkzeuge 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
      }
    }
  }
}

Hinweis: Die agentenspezifische Konfiguration überschreibt die globale Konfiguration.

Sie können auch Wildcards verwenden, um mehrere Werkzeuge auf einmal zu steuern. Zum Beispiel, um alle Werkzeuge 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 Werkzeuge.

Permissions

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

"ask" — Vor dem Ausführen des Werkzeugs um Genehmigung bitten
"allow" — Alle Operationen ohne Genehmigung erlauben
"deny" — Das Werkzeug deaktivieren

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 auch Berechtigungen in Markdown-Agenten setzen.

~/.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 setzen.

opencode.json

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

Dies kann ein Glob-Muster verwenden.

opencode.json

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

Und Sie können auch den *-Wildcard verwenden, um Berechtigungen für alle Befehle zu verwalten. Da die letzte übereinstimmende Regel Vorrang hat, setzen Sie den *-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 mode-Option wird verwendet, um zu bestimmen, wie der Agent verwendet werden kann.

opencode.json

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

Die mode-Option kann auf primary, subagent oder all gesetzt werden. Wenn kein mode angegeben ist, ist der Standard all.

Hidden

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

opencode.json

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

Dies betrifft nur die Benutzersichtbarkeit im Autovervollständigungsmenü. Versteckte Agenten können immer noch vom Modell über das Task-Werkzeug aufgerufen werden, wenn die Berechtigungen es erlauben.

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

Task permissions

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

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 Task-Werkzeugbeschreibung entfernt, sodass das Modell nicht versucht, ihn aufzurufen.

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

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

Color

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

Verwenden Sie eine gültige Hex-Farbe (z.B. #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 top_p-Option. Alternative zu Temperature zur Steuerung der Zufälligkeit.

opencode.json

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

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 direkt an den Anbieter als Modelloptionen weitergegeben. Dies ermöglicht es Ihnen, anbieterspezifische Funktionen und Parameter zu verwenden.

Zum Beispiel können Sie bei OpenAIs Reasoning-Modellen 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. Überprüfen Sie die Dokumentation Ihres Anbieters für 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:

Fragen, wo der Agent gespeichert werden soll: global oder projektspezifisch.
Beschreibung dessen, was der Agent tun soll.
Einen geeigneten Systemprompt und Bezeichner generieren.
Sie auswählen lassen, auf welche Werkzeuge der Agent zugreifen kann.
Schließlich eine Markdown-Datei mit der Agentenkonfiguration erstellen.

Anwendungsfälle

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

Build-Agent: Vollständige Entwicklungsarbeit mit allen aktivierten Werkzeugen
Plan-Agent: Analyse und Planung ohne Änderungen vorzunehmen
Review-Agent: Code-Review mit schreibgeschütztem Zugriff plus Dokumentationswerkzeuge
Debug-Agent: Fokussiert auf Untersuchung mit aktivierten bash- und Lesewerkzeugen
Docs-Agent: Dokumentation schreiben 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
tools:
  bash: false
---
 
You are a technical writer. Create clear, comprehensive documentation.
 
Focus on:
 
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Sicherheitsauditor

~/.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

Regeln Modelle