Agent-Harness-Plugins

​

Wann ein Harness verwendet werden sollte

• ein nativer Coding-Agent-Server, der Threads und Compaction verwaltet
• eine lokale CLI oder ein Daemon, die bzw. der native Planungs-, Reasoning- und Tool-Ereignisse streamen muss
• eine Modell-Runtime, die zusätzlich zum OpenClaw- Session-Transkript eine eigene Fortsetzungs-ID benötigt

​

Wofür Core weiterhin zuständig ist

• Provider und Modell
• Runtime-Authentifizierungsstatus, sofern das Harness nicht angibt, den Authentifizierungs-Bootstrap selbst zu verwalten
• Thinking-Level und Kontextbudget
• die OpenClaw-Transkript-/Session-Datei
• Workspace-, Sandbox- und Tool-Richtlinie
• Callbacks für Kanalantworten und Streaming
• Richtlinie für Modell-Fallback und Live-Modellwechsel

​

Harness-eigener Authentifizierungs-Bootstrap

​

Verifizierte Runtime-Artefakte der Einrichtung

• runtimePlan.tools.normalize(...) und runtimePlan.tools.logDiagnostics(...) für Provider-spezifische Tool-Schema-Richtlinien
• runtimePlan.transcript.resolvePolicy(...) für Transkriptbereinigung und Richtlinien zur Reparatur von Tool-Aufrufen
• runtimePlan.delivery.isSilentPayload(...) für gemeinsame NO_REPLY und die Unterdrückung der Medien- zustellung
• runtimePlan.outcome.classifyRunResult(...) für die Klassifizierung von Modell-Fallbacks
• runtimePlan.observability für aufgelöste Provider-/Modell-/Harness-Metadaten

​

Vertrag für den Anfrage-Transport

• runtimePolicy.compatibleIds listet die Runtime-IDs auf, die der Provider als mit dieser konkreten Route kompatibel deklariert. Eine fehlende Richtlinie bedeutet, dass der Provider keine Kompatibilität auf Routenebene deklariert hat; sie ist keine Berechtigung, Unterstützung anzunehmen.
• requestTransportOverrides: "none" bedeutet, dass keine vom Autor festgelegte Provider-/Modellanfrage- Überschreibung reproduziert werden muss. "present" bedeutet, dass vom Autor festgelegte Header, Authentifizierungs- transport-, Proxy-, TLS-, lokaler Dienst-, privates Netzwerk-Verhalten oder Anfrage- parameter vorhanden sind. Das Faktum legt diese Werte nicht offen.

​

Ein Harness registrieren

import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

const myHarness: AgentHarness = {
  id: "my-harness",
  label: "Mein natives Agent-Harness",

  supports(ctx) {
    const routeSupportsHarness =
      ctx.modelProvider?.runtimePolicy?.compatibleIds.includes("my-harness") === true;
    const canReproduceRequest = ctx.modelProvider?.requestTransportOverrides !== "present";
    return ctx.provider === "my-provider" && routeSupportsHarness && canReproduceRequest
      ? { supported: true, priority: 100 }
      : { supported: false, reason: "Die effektive Route ist nicht Harness-kompatibel" };
  },

  async runAttempt(params) {
    // Starten Sie Ihren nativen Thread oder setzen Sie ihn fort.
    // Verwenden Sie params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent und die anderen Felder des vorbereiteten Versuchs.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "Mein nativer Agent",
  description: "Führt ausgewählte Modelle über einen nativen Agent-Daemon aus.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

​

Delegierte Ausführung

​

Auswahlrichtlinie

1. Die modellspezifische Runtime-Richtlinie hat Vorrang.
2. Danach folgt die Provider-spezifische Runtime-Richtlinie.
3. auto fragt registrierte Harnesses, ob sie die aufgelöste effektive Route unterstützen. Provider-/Modellpräfixe allein wählen niemals ein Harness aus.
4. Wenn kein registriertes Harness übereinstimmt, verwendet OpenClaw seine eingebettete Runtime.

​

Kopplung von Provider und Harness

• bevorzugte Benutzer-Modellreferenzen: openai/gpt-5.6-sol
• Kompatibilitätsreferenzen: Veraltete codex/gpt-*-Referenzen werden weiterhin akzeptiert, neue Konfigurationen sollten sie jedoch nicht als normale Provider-/Modellreferenzen verwenden
• Harness-ID: codex
• Authentifizierung: synthetische Provider-Verfügbarkeit, da das Codex-Harness die native Codex-Anmeldung/-Session verwaltet
• App-Server-Anfrage: OpenClaw sendet die reine Modell-ID an Codex und lässt das Harness mit dem nativen App-Server-Protokoll kommunizieren

​

Tool-Ergebnis-Middleware

​

Klassifizierung des terminalen Ergebnisses

​

Nebeneffekte am Agentenende

​

Benutzereingabe- und Werkzeugoberflächen

​

Nativer Codex-Harness-Modus

​

Laufzeitstrenge

{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": {
          "id": "codex"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.6-sol"
    }
  }
}

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

{
  "agents": {
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.6-sol",
        "models": {
          "openai/gpt-5.6-sol": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    ]
  }
}

{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}

​

Native Sitzungen und Transkriptspiegelung

• im Kanal sichtbaren Sitzungsverlauf
• Transkriptsuche und -indizierung
• den Wechsel zurück zum integrierten OpenClaw-Harness bei einem späteren Turn
• generisches Verhalten von /new, /reset und beim Löschen von Sitzungen

​

Werkzeug- und Medienergebnisse

​

Terminale Werkzeugergebnisse

• Übergeben Sie die Protokollaufruf-ID, sofern vorhanden, den kanonischen Werkzeugnamen und die Argumente, die nach der Vorbereitung oder Umschreibung durch Hooks tatsächlich beim Werkzeug ankamen.
• Setzen Sie executionStarted: false, wenn Validierung, Genehmigung oder eine andere Schutzmaßnahme den Aufruf gestoppt hat, bevor die Werkzeugimplementierung begann. Sobald eine Weiterleitung stattgefunden haben könnte, melden Sie konservativ true.
• Melden Sie outcome: "success" oder outcome: "failure". Nehmen Sie die strukturierten Fehlerfelder auf, die von der Laufzeit verfügbar sind, anstatt einen Fehler aus dem Anzeigetext abzuleiten.
• Verwenden Sie nativeMutation nur für native Werkzeuge, die keine OpenClaw-Werkzeug- definition verwenden. Geben Sie dort protokolleigene Mutations- und Wiedergabefakten an; kopieren Sie den Mutationsklassifizierer von OpenClaw nicht in das Harness.

​

Finalisierung abgeschlossener Werkzeuge

• entweder das exakt eingeschränkte native Transkript oder ein vollständiges Anwendungs- transkript verwenden, das bis einschließlich der Grenze des abgeschlossenen Werkzeugergebnisses eingefroren ist;
• keine Werkzeuge, Funktionen zum Erteilen von Berechtigungen oder für Benutzereingaben, native Ausführungs- Hooks, Agenten, Skills, Speicher, Zeitplanung, Erweiterungen oder Fernsteuerung bereitstellen;
• ausschließlich den vom Host bereitgestellten Finalisierungs-Prompt senden; und
• geschlossen fehlschlagen, wenn die ausgewählte Transkript-/Isolationsstrategie diese Einschränkungen nicht durchsetzen kann.

​

Aktuelle Einschränkungen

• Der öffentliche Importpfad ist generisch, einige Typaliase für Versuche und Ergebnisse tragen aus Kompatibilitätsgründen jedoch weiterhin veraltete Namen.
• Die Installation von Harnesses von Drittanbietern ist experimentell. Bevorzugen Sie Provider-Plugins, bis Sie eine native Sitzungs-Runtime benötigen.
• Der Wechsel zwischen Harnesses wird über mehrere Turns hinweg unterstützt. Wechseln Sie den Harness nicht mitten in einem Turn, nachdem native Tools, Genehmigungen, Assistententext oder das Senden von Nachrichten begonnen haben.

​

Verwandte Themen

• SDK-Übersicht
• Runtime-Hilfsfunktionen
• Provider-Plugins
• Codex-Harness
• Modell-Provider