Zum Hauptinhalt springen

Referenz der Client-Optionen

Sie konfigurieren den Client in config/copilot.php. Dieselben Optionen können Sie auch als Array an Copilot::client(), useStdio() / useTcp() oder new Client([...]) übergeben. Diese Seite listet die Optionen der Konfigurationsdatei sowie die Optionen auf, die Sie nur aus dem Code übergeben können.

Optionen der Konfigurationsdatei

Verbindung

  • mode: der Client-Modus, entweder 'copilot-cli' (normal) oder 'empty'. empty deaktiviert die impliziten Funktionen der CLI. In diesem Modus müssen Sie ein Basisverzeichnis, SessionFs oder eine TCP-URL explizit festlegen.
  • url: die URL eines bestehenden Copilot-CLI-Servers (zum Beispiel tcp://127.0.0.1:12345). Wenn Sie sie setzen, verbindet sich das SDK mit diesem Server, statt einen neuen CLI-Prozess zu starten. Details finden Sie unter TCP-Modus.
  • cli_path: der Pfad zur ausführbaren CLI-Datei. Setzen Sie ihn auf null, um die CLI automatisch zu finden.
  • cli_args: zusätzliche Argumente, die beim Start der CLI übergeben werden (zum Beispiel ['--yolo']).
  • cwd: das Arbeitsverzeichnis des CLI-Prozesses.
  • log_level: das Log-Level des CLI-Servers. Wählen Sie none, error, warning, info, debug oder all.

Standardwerte

  • timeout: das Standard-Timeout in Sekunden für sendAndWait(). Copilot::run() verwendet es ebenfalls.
  • model: das Standardmodell, wenn Sie eine Session ohne Angabe eines Modells erstellen.
  • permission_approve: wie Berechtigungsanfragen automatisch behandelt werden, wenn Sie die Facade verwenden (Copilot::run() und Ähnliches). Wählen Sie 'deny-all' (alles ablehnen), 'approve-safety' (alles außer shell und write genehmigen), 'approve-all' (alles genehmigen) oder false (keinen Handler einfügen). Wenn Sie den Client direkt verwenden, ist immer ein onPermissionRequest-Handler erforderlich. Details finden Sie unter Berechtigungsanfragen.

Speicherort der Daten

  • copilot_home: das Basisverzeichnis für Copilot-Daten (Session-Zustand und Einstellungen). Das SDK übergibt es dem gestarteten CLI-Prozess als Umgebungsvariable COPILOT_HOME. Ist es nicht gesetzt, gilt der CLI-Standard (~/.copilot).
  • base_directory: ein Alias für copilot_home mit dem Namen aus dem offiziellen SDK. Wenn Sie beide setzen, hat base_directory Vorrang.
  • session_fs: die Einstellungen für einen SessionFs-Provider, der den Session-Zustand (Dateien und SQLite) an Ihren eigenen Speicher delegiert. initialCwd, sessionStatePath und conventions sind erforderlich. Wenn Sie ihn setzen, muss jede Session zusätzlich createSessionFsProvider angeben.
  • builtin_plugin_directories: ein Array absoluter Pfade zu vertrauenswürdigen integrierten Plugin-Verzeichnissen. Das SDK registriert sie beim Start des Clients in der Runtime. Details finden Sie unter Plugin Directories.

Weitere Optionen

  • telemetry: ein Array mit OpenTelemetry-Einstellungen (otlpEndpoint, filePath, exporterType, sourceName, captureContent). Das SDK wandelt es in Umgebungsvariablen für den gestarteten CLI-Prozess um. Details finden Sie unter Telemetrie.
  • session_idle_timeout_seconds: das serverweite Leerlauf-Timeout für Sessions in Sekunden. 0 (der Standard) deaktiviert es, sodass Sessions unbegrenzt bestehen bleiben.
  • request_handler: ein CopilotRequestHandler oder eine Closure, die HTTP-Anfragen an die Modellebene abfängt (experimentell). Für WebSocket-Anfragen gilt er nicht.

Optionen außerhalb der Konfigurationsdatei

Die folgenden Optionen stehen nicht in der Konfigurationsdatei, Sie können sie aber als Argumente an useStdio(), Copilot::client() oder new Client([...]) übergeben. Im TCP-Modus können Sie github_token und use_logged_in_user nicht verwenden, weil der externe Server seine eigene Authentifizierung verwaltet. Wenn Sie eine der beiden Optionen setzen und sich über TCP verbinden, wirft das SDK eine Exception. Zum Wechseln von Tokens zur Laufzeit siehe auch GitHub-Token. Viele Optionen akzeptieren sowohl snake_case- als auch camelCase-Namen (zum Beispiel session_fs und sessionFs, builtin_plugin_directories und builtinPluginDirectories, request_handler und requestHandler).
Zuletzt geändert am 16. November 2026