NexClaw: Warum ich meinen eigenen Harness baue

Ich nutze Claude Code und OpenCode weiterhin für echte Aufgaben. Gleichzeitig entwickle ich mit NexClaw meinen eigenen Harness. Das hat zwei Gründe: Ich möchte die Abläufe genau an mein System anpassen, und ich möchte verstehen, wie ein Agentenlauf im Inneren funktioniert.

Beim Bauen werden Probleme sichtbar, die in einer fertigen Oberfläche leicht verschwinden. Wie viel Kontext bekommt das Modell tatsächlich? Welche Werkzeuge sieht es? Was passiert nach einem fehlgeschlagenen Aufruf? Und woran entscheidet das System, dass eine Aufgabe erledigt ist?

Was ich mit Harness meine

Ein Sprachmodell allein führt noch keinen verlässlichen Arbeitsprozess aus. Es bekommt Eingaben und erzeugt Ausgaben. Der Harness hält die Sitzung zusammen, ruft Werkzeuge auf, verarbeitet deren Ergebnisse und setzt Regeln für den weiteren Ablauf.

NexClaw ist meine Implementierung dieser Schicht in Go. Es gehört zum NEX-Aufbau und kann über WingQ angesprochen werden. Modelle und Provider sind daran angebunden; der Harness ist selbst kein neues Sprachmodell.

Warum ich diese Ebene selbst gestalten möchte

Meine Arbeit verteilt sich auf lokale Modelle, externe Anbieter und viele Integrationen. Ich möchte nachvollziehen können, welches Modell eine Phase übernimmt und welche Schritte überhaupt ein Modell benötigen.

Ein gefundenes Dokument zusammenzufassen braucht Sprachverarbeitung. Ob ein Werkzeugaufruf einen Fehler gemeldet hat, lässt sich dagegen direkt aus seinem Ergebnis lesen. Wenn ich diese Aufgaben trenne, kann ich Kosten, Laufzeit und Fehlerquellen gezielter behandeln.

Dazu kommt das Lernen durch Implementieren. Wer die Schleife selbst baut, muss Entscheidungen treffen, die sonst schon ein Werkzeughersteller getroffen hat. Genau diese Auseinandersetzung ist für mich ein eigener Wert.

Die Architektur: Phasen mit klaren Ein- und Ausgaben

NexClaw zerlegt den Ablauf in einzelne Schritte. Vereinfacht sieht das so aus:

Auftrag verstehen
  → passenden Kontext laden
  → Vorgehen entscheiden und planen
  → Werkzeuge ausführen
  → Ergebnisse prüfen
  → Antwort bilden und Zustand speichern

Die Phasen bekommen ihre Daten über definierte Eingaben. Zustand wie Sitzung, Lauf und Trace liegt in der Orchestrierung. Dadurch kann ich einzelne Schritte gezielt untersuchen und testen.

Der Code enthält inzwischen mehr Phasen- und Hilfsdateien, als eine einfache Zahl in einem Blogbeitrag sinnvoll abbilden würde. Aussagekräftiger sind konkrete Beispiele: Intent und Planung benötigen ein Modell; das Zusammenführen von Themen, bestimmte Berechtigungsprüfungen und die Auswertung eindeutiger Werkzeugergebnisse können ohne eigenen Modellaufruf erfolgen.

Ein Beispiel: Kontext ohne zusätzlichen Denkauftrag

Die Kontextphase kombiniert Themen aus der aktuellen Anfrage mit hinterlegten Themen und Informationen aus der Sitzung. Ein Vergleich des Themenstands kann einen erneuten Lookup vermeiden.

Für die Wissenssuche gibt es Zeitlimits, eine begrenzte Anzahl betrachteter Themen und eine Zusammenführung der Treffer. Fehlt die MCP-Verbindung oder die passende Berechtigung, wird der Schritt entsprechend übersprungen. Scheitern alle Abfragen, wird der eingeschränkte Zustand im Trace erfasst.

Das ist keine Aufgabe, für die ein weiteres Modell frei überlegen muss. Es ist ein definierter Ablauf. Die Qualität des geladenen Wissens bleibt trotzdem eine eigene Frage: Ein gefundener Text wird durch seine Aufnahme in den Kontext nicht automatisch wahr.

Ein zweites Beispiel: „erledigt“ braucht einen Beleg

Im Alltag ist mir eine Fehlerklasse besonders wichtig: Der Agent schreibt, eine Aktion sei erledigt, obwohl das Werkzeug sie nicht erfolgreich ausgeführt hat.

Das Definition-of-Done-Gate betrachtet deshalb echte Ausführungsergebnisse. Erfolgreiche und fehlgeschlagene Werkzeugaufrufe werden getrennt gezählt. Für Schreibaufgaben zählt, ob es tatsächlich passende erfolgreiche Schreibaktionen gab.

Nicht alles lässt sich daraus eindeutig ableiten. Ein erfolgreicher Update-Aufruf beweist zum Beispiel noch nicht jede fachliche Eigenschaft des Endzustands. Deshalb kennt die Prüfung neben bestanden und fehlgeschlagen auch einen ungeprüften Zustand. Interpretationsbedürftige Kriterien gehen an eine weitere Bewertung.

Das ist für mich eine wichtige Entwurfsregel: Eine selbstbewusste Formulierung des Workers ist kein Ersatz für Ausführungsevidenz.

Verschiedene Provider hinter derselben Schnittstelle

Die Provider-Schnittstelle stellt synchrone Aufrufe, Streaming, Fähigkeiten, Namen und das Freigeben von Ressourcen bereit. Adapter kapseln die Unterschiede der konkreten Anbindungen.

Damit kann die Orchestrierung gemeinsame Abläufe verwenden, ohne jedem Provider dieselben Fähigkeiten zu unterstellen. Tool-Nutzung, strukturierte Ausgabe oder Reasoning-Parameter müssen zur jeweiligen Anbindung passen.

Diese Trennung macht lokale Modelle interessant. Ich kann ihre Stärken nutzen und trotzdem nachvollziehen, an welcher Stelle ein Lauf durch das Modell und an welcher Stelle durch meinen eigenen Ablauf begrenzt wird.

Der Tool Router entstand aus einem echten Engpass

Beim Aufbau fiel auf, wie viel Kontext bereits die Werkzeugdefinitionen belegten. Daraus entstand die Trennung in Suchen, Beschreiben und Ausführen.

Das Modell muss nicht bei jedem Start den gesamten Integrationskatalog erhalten. Es findet passende Werkzeuge und lädt bei Bedarf deren genaue Schemas nach. Im heutigen System gehört zusätzlich eine Gedächtnisfunktion zu diesem Einstieg.

Der Router ist auch außerhalb von NexClaw nutzbar, etwa über MCP in OpenCode. Das ist für mich ein gutes Beispiel dafür, wie ein eigenes Projekt eine Lösung hervorbringt, die anschließend mehrere Harnesses verbessert.

Was mich der eigene Harness kostet

Jede zusätzliche Regel muss verständlich bleiben. Zu viele Gates können brauchbare Arbeit unnötig stoppen; zu großzügige Prüfungen können Fehler übersehen. Neue Provider bringen Sonderfälle mit, und Änderungen brauchen nachvollziehbare Tests und Traces.

Ich baue deshalb nicht mit der Erwartung, jede Aufgabe besser als fertige Werkzeuge zu erledigen. Ich möchte für meinen Betrieb bestimmte Abläufe genauer gestalten und verstehen. Fertige Harnesses bleiben dabei Teil meines Alltags.

Was auch ohne eigenen Harness übertragbar ist

Man kann bei jedem Agentensystem fragen: Welche Schritte brauchen wirklich ein Modell? Woher kommt der Kontext? Welche Werkzeuge werden tatsächlich geladen? Welche Belege stehen hinter der Meldung „erledigt“?

Die Antworten sind oft nützlicher als ein weiterer Modellvergleich. Stateless-Phasen machen einzelne Abläufe prüfbar, ein Router hält Werkzeuge bedarfsgerecht verfügbar, und klare Ergebniszustände helfen beim Umgang mit Fehlern.

Das ist der Grund, warum ich NexClaw weiterbaue: Ich lerne, wo ein Modell hilft und welche Verantwortung die Software darum herum übernehmen muss.