Agentenlaufzeitumgebungen

Eine Agent-Runtime besitzt genau eine vorbereitete Modellschleife: Sie empfängt den Prompt, steuert die Modellausgabe, verarbeitet native Tool-Aufrufe und gibt den abgeschlossenen Turn an OpenClaw zurück.

Runtimes können leicht mit Providern verwechselt werden, da beide in der Nähe der Modellkonfiguration erscheinen. Es handelt sich um unterschiedliche Ebenen:

Ein Harness ist die Implementierung, die eine Agent-Runtime bereitstellt (Codebegriff). Beispielsweise implementiert das gebündelte Codex-Harness die Runtime codex. Die öffentliche Konfiguration verwendet agentRuntime.id in Provider- oder Modelleinträgen; Runtime-Schlüssel für den gesamten Agent sind veraltet und werden ignoriert. openclaw doctor --fix entfernt alte Runtime-Festlegungen für den gesamten Agent und schreibt veraltete Runtime-Modellreferenzen in kanonische Provider-/Modellreferenzen sowie, falls erforderlich, in eine modellbezogene Runtime-Richtlinie um.

Zwei Runtime-Familien:

• Eingebettete Harnesses werden innerhalb der vorbereiteten Agent-Schleife von OpenClaw ausgeführt: die integrierte Runtime openclaw sowie registrierte Plugin-Harnesses wie codex und copilot.
• CLI-Backends führen einen lokalen CLI-Prozess aus, während die Modellreferenz kanonisch bleibt. Beispielsweise bedeutet anthropic/claude-opus-5 mit einem modellbezogenen agentRuntime.id: "claude-cli": „Das Anthropic-Modell auswählen und über die Claude CLI ausführen.“ claude-cli ist keine ID eines eingebetteten Harnesses und darf nicht an die AgentHarness-Auswahl übergeben werden.

Das Harness copilot ist ein separates, optionales externes Plugin-Harness für die GitHub Copilot CLI; Informationen zur nutzerseitigen Entscheidung zwischen PI, Codex und der GitHub-Copilot-Agent-Runtime finden Sie unter GitHub-Copilot-Agent-Runtime.

Codex-Oberflächen

Mehrere Oberflächen verwenden den Namen Codex:

Diese Oberflächen sind bewusst voneinander unabhängig. Durch Aktivieren des Plugins codex werden native App-Server-Funktionen verfügbar; openclaw doctor --fix ist für die Reparatur veralteter Codex-Routen und die Bereinigung überholter Sitzungsfestlegungen zuständig. Die Auswahl von openai/* für ein Agent-Modell bedeutet nun „dies über Codex ausführen“, sofern keine Nicht-Agent-Oberfläche der OpenAI API verwendet wird.

Die übliche Einrichtung mit einem ChatGPT-/Codex-Abonnement verwendet Codex OAuth zur Authentifizierung, behält jedoch openai/* als Modellreferenz bei und wählt die Runtime codex aus:

{  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },}

Das bedeutet, dass OpenClaw eine OpenAI-Modellreferenz auswählt und anschließend die Codex-App-Server-Runtime auffordert, den eingebetteten Agent-Turn auszuführen. Es bedeutet weder „API-Abrechnung verwenden“, noch dass der Kanal, der Modell-Provider-Katalog oder der Sitzungsspeicher von OpenClaw zu Codex wird.

Wenn das gebündelte Plugin codex aktiviert ist, verwenden Sie zur natürlichsprachlichen Codex-Steuerung anstelle von ACP die native Befehlsoberfläche /codex (/codex bind, /codex threads, /codex resume, /codex steer, /codex stop). Verwenden Sie ACP für Codex nur, wenn ausdrücklich ACP/acpx angefordert oder der Pfad des ACP-Adapters getestet wird. Claude Code, Gemini CLI, OpenCode, Cursor und ähnliche externe Harnesses verwenden weiterhin ACP.

Entscheidungsbaum:

1. Codex binden/steuern/Thread fortsetzen/lenken/beenden -> native Befehlsoberfläche /codex, wenn das gebündelte Plugin codex aktiviert ist.
2. Codex als eingebettete Runtime oder die normale abonnementgestützte Codex-Agent-Erfahrung -> openai/<model>.
3. OpenClaw ausdrücklich für ein OpenAI-Modell ausgewählt -> Modellreferenz als openai/<model> beibehalten und die Provider-/Modell-Runtime-Richtlinie auf agentRuntime.id: "openclaw" festlegen. Ein ausgewähltes OAuth-Profil openai wird intern über den Codex-Authentifizierungstransport von OpenClaw geleitet.
4. Veraltete Codex-Modellreferenzen in der Konfiguration -> mit openclaw doctor --fix zu openai/<model> reparieren; Doctor behält die Codex-Authentifizierungsroute bei, indem bei Bedarf ein provider-/modellbezogenes agentRuntime.id: "codex" hinzugefügt wird, sofern die alte Modellreferenz dies implizierte. Veraltete codex-cli/*-Modellreferenzen werden zur gleichen Codex-App-Server-Route openai/<model> repariert; OpenClaw enthält kein gebündeltes Codex-CLI-Backend mehr.
5. ACP, acpx oder Codex-ACP-Adapter ausdrücklich angefordert -> runtime: "acp" und agentId: "codex".
6. Claude Code, Gemini CLI, OpenCode, Cursor, Droid oder ein anderes externes Harness -> ACP/acpx, nicht die native Sub-Agent-Runtime.

Informationen zur Aufteilung der Präfixe der OpenAI-Familie finden Sie unter OpenAI und Modell-Provider. Informationen zum Supportvertrag der Codex-Runtime finden Sie unter Codex-Harness-Runtime.

Runtime-Zuständigkeit

Unterschiedliche Runtimes sind für unterschiedliche Teile der Schleife zuständig:

Entwurfsregel: Wenn OpenClaw für die Oberfläche zuständig ist, kann es das normale Verhalten von Plugin-Hooks bereitstellen. Wenn die native Runtime für die Oberfläche zuständig ist, benötigt OpenClaw Runtime-Ereignisse oder native Hooks. Wenn die native Runtime für den kanonischen Thread-Status zuständig ist, spiegelt OpenClaw den Kontext und projiziert ihn, anstatt nicht unterstützte Interna umzuschreiben.

Runtime-Auswahl

OpenClaw löst nach der Provider- und Modellauflösung eine eingebettete Runtime in dieser Reihenfolge auf:

1. Modellbezogene Runtime-Richtlinie hat Vorrang. Sie befindet sich in einem konfigurierten Provider-Modelleintrag oder in agents.defaults.models["provider/model"].agentRuntime / agents.entries.*.models["provider/model"].agentRuntime. Ein Provider- Platzhalter wie agents.defaults.models["vllm/*"].agentRuntime greift nach der exakten Modellrichtlinie, sodass dynamisch ermittelte Provider-Modelle dieselbe Runtime verwenden können, ohne exakte modellspezifische Ausnahmen zu überschreiben.
2. Provider-bezogene Runtime-Richtlinie: models.providers.<provider>.agentRuntime.
3. Modus auto: Registrierte Plugin-Runtimes können unterstützte Provider-/Modellpaare beanspruchen.
4. Wenn im Modus auto nichts den Turn beansprucht, fällt OpenClaw auf openclaw als Kompatibilitäts-Runtime zurück. Verwenden Sie eine explizite Runtime-ID, wenn die Ausführung strikt sein muss.

Runtime-Festlegungen für die gesamte Sitzung und den gesamten Agent werden ignoriert: OPENCLAW_AGENT_RUNTIME, der Sitzungsstatus agentHarnessId/agentRuntimeOverride, agents.defaults.agentRuntime und agents.entries.*.agentRuntime. Führen Sie openclaw doctor --fix aus, um veraltete Runtime-Konfigurationen für den gesamten Agent zu entfernen und veraltete Runtime-Modellreferenzen zu konvertieren, sofern die Absicht beibehalten werden kann.

Explizite Provider-/Modell-Plugin-Runtimes schlagen geschlossen fehl: agentRuntime.id: "codex" bei einem Provider oder Modell bedeutet Codex oder einen eindeutigen Auswahl-/Runtime-Fehler – es wird niemals stillschweigend zu OpenClaw zurückgeleitet. Nur auto darf einen nicht zugeordneten Turn an OpenClaw leiten.

CLI-Backend-Aliasse unterscheiden sich von IDs eingebetteter Harnesses. Bevorzugte Form für die Claude CLI:

{  agents: {    defaults: {      model: "anthropic/claude-opus-5",      models: {        "anthropic/claude-opus-5": {          agentRuntime: { id: "claude-cli" },        },      },    },  },}

Veraltete Referenzen wie claude-cli/claude-opus-4-7 werden aus Kompatibilitätsgründen weiterhin unterstützt, neue Konfigurationen sollten jedoch Provider und Modell kanonisch halten und das Ausführungs-Backend in der Provider-/Modell-Runtime-Richtlinie angeben.

Veraltete Referenzen codex-cli/* unterscheiden sich davon: Doctor migriert sie zu openai/*, sodass sie über das Codex-App-Server-Harness ausgeführt werden, anstatt ein Codex- CLI-Backend beizubehalten.

Der Modus auto ist für die meisten Provider bewusst konservativ. OpenAI-Agent- Modelle bilden die Ausnahme: Sowohl eine nicht festgelegte Runtime als auch auto werden zum Codex- Harness aufgelöst. Eine explizite OpenClaw-Runtime-Konfiguration bleibt eine optionale Kompatibilitätsroute für Agent-Turns openai/*; in Kombination mit einem ausgewählten OAuth- Profil openai leitet OpenClaw diesen Pfad intern über den Codex-Authentifizierungstransport, während die öffentliche Modellreferenz openai/* bleibt. Veraltete OpenAI- Runtime-Sitzungsfestlegungen werden bei der Runtime-Auswahl ignoriert und können mit openclaw doctor --fix bereinigt werden.

Wenn openclaw doctor davor warnt, dass das Plugin codex aktiviert ist, während veraltete Codex-Modellreferenzen in der Konfiguration verbleiben, behandeln Sie dies als veralteten Routing-Zustand und führen Sie openclaw doctor --fix aus, um ihn auf openai/* mit der Codex-Runtime umzuschreiben.

GitHub-Copilot-Agent-Runtime

Das externe Plugin @openclaw/copilot registriert eine optionale copilot-Runtime, die auf der GitHub Copilot CLI (@github/copilot-sdk) basiert. Es beansprucht den kanonischen Abonnement-Provider github-copilot und wird von auto niemals ausgewählt. Aktivieren Sie es über agentRuntime.id je Modell oder Provider:

{  agents: {    defaults: {      model: "github-copilot/gpt-5.5",      models: {        "github-copilot/gpt-5.5": {          agentRuntime: { id: "copilot" },        },      },    },  },}

Der Harness beansprucht seinen Provider, seine Runtime, seinen CLI-Sitzungsschlüssel und sein Authentifizierungsprofilpräfix in extensions/copilot/doctor-contract-api.ts, das openclaw doctor automatisch lädt. Informationen zur Konfiguration, Authentifizierung, Transkriptspiegelung, Compaction, zum deklarativen Doctor-Vertrag und zur umfassenderen SDK-Entscheidung zwischen PI, Codex und Copilot finden Sie unter GitHub-Copilot-Agent-Runtime.

Kompatibilitätsvertrag

Wenn eine Runtime nicht OpenClaw ist, sollte ihre Dokumentation angeben, welche OpenClaw-Oberflächen sie unterstützt:

Der Unterstützungsvertrag der Codex-Runtime ist unter Codex-Harness-Runtime dokumentiert.

Statusbezeichnungen

Die Statusausgabe kann sowohl Execution- als auch Runtime-Bezeichnungen anzeigen. Verstehen Sie diese als Diagnoseangaben, nicht als Providernamen:

• Eine Modellreferenz wie openai/gpt-5.6-sol bezeichnet den ausgewählten Provider und das ausgewählte Modell.
• Eine Runtime-ID wie codex bezeichnet die Schleife, die den Durchlauf ausführt.
• Eine Kanalbezeichnung wie Telegram oder Discord gibt an, wo die Unterhaltung stattfindet.

Wenn ein Durchlauf eine unerwartete Runtime anzeigt, prüfen Sie zuerst die Runtime-Richtlinie des ausgewählten Providers/Modells. Veraltete Runtime-Festlegungen für Sitzungen bestimmen das Routing nicht mehr.

Verwandte Themen

• Codex-Harness
• Codex-Harness-Runtime
• GitHub-Copilot-Agent-Runtime
• OpenAI
• Agent-Harness-Plugins
• Agentenschleife
• Modelle
• Status