Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Ein Agent Harness ist der Low-Level-Executor für einen vorbereiteten OpenClaw-Agenten-Turn. Er ist kein Modell-Provider, kein Kanal und keine Tool-Registry. Für das nutzerorientierte mentale Modell siehe Agent-Runtimes. Verwenden Sie diese Oberfläche nur für gebündelte oder vertrauenswürdige native Plugins. Der Vertrag ist noch experimentell, weil die Parametertypen bewusst den aktuellen eingebetteten Runner widerspiegeln.

​
Wann Sie einen Harness verwenden sollten

Registrieren Sie einen Agent Harness, wenn eine Modellfamilie ihre eigene native Session-Runtime hat und der normale OpenClaw-Provider-Transport die falsche Abstraktion ist. Beispiele:
  • ein nativer Coding-Agent-Server, der Threads und Compaction besitzt
  • eine lokale CLI oder ein Daemon, der native Plan-/Reasoning-/Tool-Events streamen muss
  • eine Modell-Runtime, die zusätzlich zum OpenClaw-Session-Transkript eine eigene Resume-ID benötigt
Registrieren Sie keinen Harness, nur um eine neue LLM-API hinzuzufügen. Für normale HTTP- oder WebSocket-Modell-APIs erstellen Sie ein Provider-Plugin.

​
Was Core weiterhin besitzt

Bevor ein Harness ausgewählt wird, hat OpenClaw bereits Folgendes aufgelöst:
  • Provider und Modell
  • Runtime-Authentifizierungsstatus
  • Denkstufe und Kontextbudget
  • die OpenClaw-Transkript-/Session-Datei
  • Workspace, Sandbox und Tool-Richtlinie
  • Kanal-Antwort-Callbacks und Streaming-Callbacks
  • Modell-Fallback und Richtlinie für Live-Modellwechsel
Diese Trennung ist beabsichtigt. Ein Harness führt einen vorbereiteten Versuch aus; er wählt keine Provider aus, ersetzt keine Kanalauslieferung und wechselt Modelle nicht stillschweigend. Der vorbereitete Versuch enthält außerdem params.runtimePlan, ein von OpenClaw besessenes Richtlinienpaket für Runtime-Entscheidungen, die über Pi und native Harnesses hinweg geteilt bleiben müssen:
  • runtimePlan.tools.normalize(...) und runtimePlan.tools.logDiagnostics(...) für Provider-bewusste Tool-Schema-Richtlinien
  • runtimePlan.transcript.resolvePolicy(...) für Transkriptsanitisierung und Tool-Call-Reparaturrichtlinien
  • runtimePlan.delivery.isSilentPayload(...) für gemeinsame NO_REPLY- und Medienauslieferungsunterdrückung
  • runtimePlan.outcome.classifyRunResult(...) für Modell-Fallback-Klassifizierung
  • runtimePlan.observability für aufgelöste Provider-/Modell-/Harness-Metadaten
Harnesses können den Plan für Entscheidungen verwenden, die dem Pi-Verhalten entsprechen müssen, sollten ihn aber weiterhin als versuchsspezifischen Zustand des Hosts behandeln. Mutieren Sie ihn nicht und verwenden Sie ihn nicht, um innerhalb eines Turns Provider/Modelle zu wechseln.

​
Einen Harness registrieren

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

const myHarness: AgentHarness = {
  id: "my-harness",
  label: "My native agent harness",

  supports(ctx) {
    return ctx.provider === "my-provider"
      ? { supported: true, priority: 100 }
      : { supported: false };
  },

  async runAttempt(params) {
    // Start or resume your native thread.
    // Use params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent, and the other prepared attempt fields.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "My Native Agent",
  description: "Runs selected models through a native agent daemon.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

​
Auswahlrichtlinie

OpenClaw wählt nach der Provider-/Modellauflösung einen Harness aus:
  1. Modellbezogene Runtime-Richtlinie gewinnt.
  2. Providerbezogene Runtime-Richtlinie kommt als Nächstes.
  3. auto fragt registrierte Harnesses, ob sie den aufgelösten Provider/das aufgelöste Modell unterstützen.
  4. Wenn kein registrierter Harness passt, verwendet OpenClaw Pi, sofern Pi-Fallback nicht deaktiviert ist.
Plugin-Harness-Fehler werden als Laufzeitfehler sichtbar. Im auto-Modus wird Pi-Fallback nur verwendet, wenn kein registrierter Plugin-Harness den aufgelösten Provider/das aufgelöste Modell unterstützt. Sobald ein Plugin-Harness einen Lauf beansprucht hat, spielt OpenClaw denselben Turn nicht erneut über Pi ab, weil das Auth-/Runtime-Semantik ändern oder Seiteneffekte duplizieren kann. Runtime-Pins für die gesamte Session und den gesamten Agenten werden von der Auswahl ignoriert. Dazu gehören veraltete Session-Werte für agentHarnessId, agents.defaults.agentRuntime, agents.list[].agentRuntime und OPENCLAW_AGENT_RUNTIME. /status zeigt die effektive Runtime, die aus der Provider-/Modellroute ausgewählt wurde. Wenn der ausgewählte Harness überraschend ist, aktivieren Sie agents/harness-Debug-Logging und prüfen Sie den strukturierten Gateway-Datensatz agent harness selected. Er enthält die ausgewählte Harness-ID, den Auswahlgrund, die Runtime-/Fallback-Richtlinie und im auto-Modus das Unterstützungsergebnis jedes Plugin-Kandidaten. Das gebündelte Codex-Plugin registriert codex als seine Harness-ID. Core behandelt dies als gewöhnliche Plugin-Harness-ID; Codex-spezifische Aliase gehören in das Plugin oder die Operator-Konfiguration, nicht in den gemeinsamen Runtime-Selector.

​
Provider-plus-Harness-Paarung

Die meisten Harnesses sollten auch einen Provider registrieren. Der Provider macht Modellreferenzen, Auth-Status, Modellmetadaten und /model-Auswahl für den Rest von OpenClaw sichtbar. Der Harness beansprucht diesen Provider dann in supports(...). Das gebündelte Codex-Plugin folgt diesem Muster:
  • bevorzugte Nutzermodellreferenzen: openai/gpt-5.5
  • Kompatibilitätsreferenzen: Legacy-Referenzen codex/gpt-* bleiben akzeptiert, neue Konfigurationen sollten sie aber nicht als normale Provider-/Modellreferenzen verwenden
  • Harness-ID: codex
  • Auth: synthetische Provider-Verfügbarkeit, weil der Codex-Harness den nativen Codex-Login/die native Codex-Session besitzt
  • App-Server-Anfrage: OpenClaw sendet die reine Modell-ID an Codex und lässt den Harness mit dem nativen App-Server-Protokoll kommunizieren
Das Codex-Plugin ist additiv. Einfache openai/gpt-*-Agentenreferenzen beim offiziellen OpenAI-Provider wählen standardmäßig den Codex-Harness aus. Ältere codex/gpt-*-Referenzen wählen aus Kompatibilitätsgründen weiterhin den Codex-Provider und -Harness aus. Für Operator-Einrichtung, Modellpräfix-Beispiele und Codex-only-Konfigurationen siehe Codex Harness. OpenClaw erfordert Codex-App-Server 0.125.0 oder neuer. Das Codex-Plugin prüft den Initialize-Handshake des App-Servers und blockiert ältere oder unversionierte Server, damit OpenClaw nur gegen die Protokolloberfläche läuft, mit der es getestet wurde. Die Untergrenze 0.125.0 enthält die native MCP-Hook-Payload-Unterstützung, die in Codex 0.124.0 eingeführt wurde, während OpenClaw an die neuere getestete stabile Linie gebunden wird.

​
Tool-Ergebnis-Middleware

Gebündelte Plugins können Runtime-neutrale Tool-Ergebnis-Middleware über api.registerAgentToolResultMiddleware(...) anhängen, wenn ihr Manifest die Ziel-Runtime-IDs in contracts.agentToolResultMiddleware deklariert. Diese vertrauenswürdige Schnittstelle ist für asynchrone Tool-Ergebnis-Transformationen gedacht, die ausgeführt werden müssen, bevor Pi oder Codex Tool-Ausgaben wieder in das Modell einspeist. Legacy-gebündelte Plugins können weiterhin api.registerCodexAppServerExtensionFactory(...) für Middleware verwenden, die nur für den Codex-App-Server gilt, neue Ergebnis-Transformationen sollten jedoch die Runtime-neutrale API verwenden. Der Pi-only-Hook api.registerEmbeddedExtensionFactory(...) wurde entfernt; Pi-Tool-Ergebnis-Transformationen müssen Runtime-neutrale Middleware verwenden.

​
Terminale Ergebnisklassifizierung

Native Harnesses, die ihre eigene Protokollprojektion besitzen, können classifyAgentHarnessTerminalOutcome(...) aus openclaw/plugin-sdk/agent-harness-runtime verwenden, wenn ein abgeschlossener Turn keinen sichtbaren Assistententext erzeugt hat. Der Helper gibt empty, reasoning-only oder planning-only zurück, damit die Fallback-Richtlinie von OpenClaw entscheiden kann, ob auf einem anderen Modell erneut versucht werden soll. Er lässt Prompt-Fehler, laufende Turns und beabsichtigte stille Antworten wie NO_REPLY bewusst unklassifiziert.

​
Nativer Codex-Harness-Modus

Der gebündelte codex-Harness ist der native Codex-Modus für eingebettete OpenClaw-Agenten-Turns. Aktivieren Sie zuerst das gebündelte codex-Plugin und nehmen Sie codex in plugins.allow auf, wenn Ihre Konfiguration eine restriktive Allowlist verwendet. Native App-Server-Konfigurationen sollten openai/gpt-* verwenden; OpenAI-Agenten-Turns wählen standardmäßig den Codex-Harness. Legacy-Routen openai-codex/* sollten mit openclaw doctor --fix repariert werden, und Legacy-Modellreferenzen codex/* bleiben Kompatibilitätsaliase für den nativen Harness. Wenn dieser Modus läuft, besitzt Codex die native Thread-ID, das Resume-Verhalten, Compaction und die App-Server-Ausführung. OpenClaw besitzt weiterhin den Chatkanal, den sichtbaren Transkriptspiegel, die Tool-Richtlinie, Genehmigungen, Medienauslieferung und Session-Auswahl. Verwenden Sie Provider/Modell agentRuntime.id: "codex", wenn Sie nachweisen müssen, dass nur der Codex-App-Server-Pfad den Lauf beanspruchen kann. Explizite Plugin-Runtimes schlagen geschlossen fehl; Codex-App-Server-Auswahlfehler und Runtime-Fehler werden nicht über Pi erneut versucht.

​
Runtime-Striktheit

Standardmäßig verwendet OpenClaw die Provider-/Modell-Runtime-Richtlinie auto: Registrierte Plugin-Harnesses können ein Provider-/Modellpaar beanspruchen, und Pi verarbeitet den Turn, wenn keines passt. OpenAI-Agentenreferenzen beim offiziellen OpenAI-Provider verwenden standardmäßig Codex. Verwenden Sie eine explizite Provider-/Modell-Plugin-Runtime wie agentRuntime.id: "codex", wenn eine fehlende Harness-Auswahl fehlschlagen soll, statt über Pi geroutet zu werden. Ausfälle ausgewählter Plugin-Harnesses schlagen immer hart fehl. Dies blockiert keine explizite Provider-/Modell-Konfiguration agentRuntime.id: "pi". Für Codex-only-eingebettete Läufe: 
{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": {
          "id": "codex"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.5"
    }
  }
}
Wenn Sie ein CLI-Backend für ein kanonisches Modell wünschen, legen Sie die Runtime auf diesen Modelleintrag: 
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-7",
      "models": {
        "anthropic/claude-opus-4-7": {
          "agentRuntime": {
            "id": "claude-cli"
          }
        }
      }
    }
  }
}
Pro-Agent-Overrides verwenden dieselbe modellbezogene Form: 
{
  "agents": {
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.5",
        "models": {
          "openai/gpt-5.5": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    ]
  }
}
Legacy-Beispiele für Runtime-Konfigurationen auf Ebene des gesamten Agenten wie dieses werden ignoriert: 
{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}
Mit einer expliziten Plugin-Runtime schlägt eine Session früh fehl, wenn der angeforderte Harness nicht registriert ist, den aufgelösten Provider/das aufgelöste Modell nicht unterstützt oder fehlschlägt, bevor Turn-Seiteneffekte erzeugt wurden. Das ist für Codex-only-Deployments und für Live-Tests beabsichtigt, die nachweisen müssen, dass der Codex-App-Server-Pfad tatsächlich verwendet wird. Diese Einstellung steuert nur den eingebetteten Agent Harness. Sie deaktiviert kein bild-, video-, musik-, TTS-, PDF- oder anderes Provider-spezifisches Modellrouting.

​
Native Sessions und Transkriptspiegel

Ein Harness kann eine native Session-ID, Thread-ID oder ein Resume-Token auf Daemon-Seite behalten. Halten Sie diese Bindung explizit mit der OpenClaw-Session verknüpft und spiegeln Sie nutzersichtbare Assistenten-/Tool-Ausgaben weiterhin in das OpenClaw-Transkript. Das OpenClaw-Transkript bleibt die Kompatibilitätsschicht für:
  • kanalsichtbaren Session-Verlauf
  • Transkriptsuche und Indexierung
  • Wechsel zurück zum eingebauten Pi-Harness in einem späteren Turn
  • generisches Verhalten für /new, /reset und Session-Löschung
Wenn Ihr Harness eine Sidecar-Bindung speichert, implementieren Sie reset(...), damit OpenClaw sie löschen kann, wenn die besitzende OpenClaw-Session zurückgesetzt wird.

​
Tool- und Medienergebnisse

Core erstellt die OpenClaw-Toolliste und übergibt sie an den vorbereiteten Versuch. Wenn ein Harness einen dynamischen Tool-Call ausführt, geben Sie das Tool-Ergebnis über die Harness-Ergebnisform zurück, statt selbst Kanalmedien zu senden. So bleiben Text-, Bild-, Video-, Musik-, TTS-, Genehmigungs- und Messaging-Tool-Ausgaben auf demselben Auslieferungspfad wie Pi-gestützte Läufe.

​
Aktuelle Einschränkungen

  • Der öffentliche Importpfad ist generisch, aber einige Attempt-/Result-Typaliase tragen aus Kompatibilitätsgründen weiterhin Pi-Namen.
  • Die Installation von Drittanbieter-Harnesses ist experimentell. Bevorzugen Sie Provider-Plugins, bis Sie eine native Session-Runtime benötigen.
  • Harness-Wechsel werden über Turns hinweg unterstützt. Wechseln Sie Harnesses nicht mitten in einem Turn, nachdem native Tools, Genehmigungen, Assistententext oder Nachrichtensendungen begonnen haben.

​
Verwandt