OpenClaw korrigiert Recovery-Hinweis für Legacy-Codex-Modelle

OpenClaw arbeitet an einem Fix für einen Recovery-Hinweis, der bei Legacy-Codex-Modellen in die falsche Richtung zeigte. Pull Request #100161 soll Issue #100066 schließen: Wer ein openai-codex/*-Modell in agents.defaults.models referenziert, soll künftig keine Anleitung mehr bekommen, models.providers["openai-codex"].models[] zu ergänzen.

Das klingt erst einmal nach einer kleinen Textkorrektur. Im gemeldeten Fall hing daran aber ein realer Betriebsfehler. Die Fehlermeldung schob Betreiber erst in eine Konfigurationsänderung und danach direkt in die nächste Validierungsstörung. Aus einem unbekannten Modell wurde so ein Gateway, das beim Start in einen Crash-Loop laufen konnte.

Der eigentliche Fehler saß im Rettungsweg

Im GitHub-Issue beschreibt Jason-Vaughan einen Ablauf, bei dem ein gebündelter OAuth-Provider wie openai-codex für openai-codex/gpt-5.4 zur Laufzeit einen FailoverError lieferte. Das Modell galt als unbekannt, obwohl es unter agents.defaults.models["openai-codex/gpt-5.4"] stand. Die Recovery-Anweisung forderte daraufhin dazu auf, einen Eintrag unter models.providers["openai-codex"].models[] nachzutragen.

Genau dort kippte die Lage. Nach dem Eintrag unter models.mode: "merge" stoppte der Gateway-Start mit einer Validierungsfehlermeldung, weil für models.providers.openai-codex.baseUrl ein Pflichtwert fehlte. Für den gemeldeten Fall war das die falsche Ebene: openai-codex lief über einen gebündelten OAuth-Pfad, die vorgeschlagene Reparatur drückte den Betreiber aber in ein Schema für Custom Provider.

Das Problem war also größer als ein verpasstes Modellrouting. Die Runtime schlug eine Reparatur vor, die der eigene Validator anschließend wieder zurückwies. Wer der Fehlermeldung vertraute, konnte den Ausfall vergrößern, obwohl er eigentlich nur dem Rettungsweg folgte.

Der Fix lenkt zurück auf Auth und Migration

Pull Request #100161 ändert laut Beschreibung nicht das Config-Schema. OpenClaw soll openai-codex also nicht nachträglich als gültige Overlay-Form akzeptieren. Der Fix setzt früher an: Der neue Hinweis behandelt den Fall als Legacy-Codex-Pfad und verweist auf die bestehenden Reparaturwege.

Laut PR-Proof gehören dazu ein Lauf über openclaw doctor --fix, ein Check via openclaw models status und bei fehlendem Profil eine erneute OpenAI/Codex-OAuth-Anmeldung über openclaw models auth login --provider openai. Zusätzlich verweist der PR auf die reparierte Route openai/gpt-5.4 mit Codex-Runtime-Metadaten.

Das passt zur Root-Cause-Beschreibung im Issue. Dort stellte sich der unbekannte Modellfehler im gemeldeten Fall als fehlende Provider-Authentifizierung nach einem Upgrade heraus. Wenn das OAuth-Profil fehlt, werden die Modelle des Providers zur Laufzeit nicht registriert. Ein Provider-Overlay löst diese Ursache nicht.

Gerade in Docker-Setups sieht ein Startfehler schnell wie ein generisches Config-Problem aus. Das Issue nennt als Umgebung einen OpenClaw-Upgradefall mit einem Image aus ghcr.io und zusätzlich einen Custom Provider unter models.mode: "merge". In so einer Lage ist ein präziser Hinweis keine Komfortfunktion. Er entscheidet darüber, ob die Diagnose enger wird oder der Betreiber den nächsten Fehler selbst einbaut.

Was der Pull Request schon belastbar zeigt

Der Pull Request verweist auf zwei Commits und zwei geänderte Dateien. Als Nachweis dient ein isolierter CLI-Lauf, in dem agents.defaults.models["openai-codex/gpt-5.4"] = {} gesetzt war, aber kein models.providers["openai-codex"]-Overlay existierte. Die Ausgabe enthielt danach keinen alten Hinweis zur Provider-Registrierung mehr, sondern einen Migrations- und Auth-Hinweis.

Zusätzlich nennt der PR eine Regression im Vitest-Bereich für genau diesen Pfad. Vor dem Fix scheiterte der Test laut PR daran, dass die Fehlermeldung weiter zum Eintrag unter models.providers["openai-codex"].models[] aufforderte. Nach dem Fix liefert derselbe Ablauf die neue Recovery-Anleitung.

Wichtig ist auch die Grenze des Fixes. Der PR öffnet keine neue Legacy-Konfigurationsform. Er kappt nur einen Hinweis, der Betreiber in die falsche Richtung schob. Aus Betriebssicht ist genau das entscheidend: Die Runtime hört auf, eine Reparatur vorzuschlagen, die sie später selbst wieder verwirft.

Damit bleibt die Verantwortung klar verteilt. Der Validator muss weiterhin verhindern, dass ein Legacy-Provider wie ein unvollständiger Custom Provider eingetragen wird. Die Runtime muss vorher sauber erklären, warum das Modell nicht verfügbar ist und welcher Reparaturpfad dazu passt.

Warum dieser Fall größer ist als ein Text-Fix

Fehlermeldungen gehören in Agenten-Runtimes zum produktiven Verhalten. Wenn eine Recovery-Anweisung auf die falsche Ebene zeigt, ist das kein kosmetischer Bug. Dann wird aus einem Routing- oder Auth-Problem schnell ein zweiter Ausfall durch eine gut gemeinte Reparatur.

Genau das macht diesen Fall interessant. Bei unbekannten openai-codex/*-Modellen sollte der Blick nicht zuerst auf eine neue Provider-Struktur fallen. Sinnvoller ist die nüchterne Reihenfolge: Auth prüfen, Migration prüfen, Modellstatus prüfen. Wenn ein gebündelter Legacy-Provider plötzlich wie ein Custom Provider behandelt wird, ist Misstrauen gegenüber der ersten Reparaturidee gesünder als Konfigurationsfleiß.

Die praktische Regel bis zu einem Merge ist deshalb eng, aber brauchbar: Bei openai-codex/*-Fehlern keine Config-Reparatur blind übernehmen, wenn sie einen Legacy-Provider in Richtung Custom-Provider-Overlay schiebt. Erst Auth prüfen, dann Migration, dann Routing. Ein Gateway, das wieder startet, ist im Zweifel mehr wert als eine Fehlermeldung, die nur plausibel klingt.