Passer au contenu principal

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.

Un harnais d’agent est l’exécuteur de bas niveau pour un tour d’agent OpenClaw préparé. Ce n’est pas un fournisseur de modèle, ni un canal, ni un registre d’outils. Pour le modèle mental destiné aux utilisateurs, voir Runtimes d’agent. Utilisez cette surface uniquement pour des plugins natifs intégrés ou fiables. Le contrat reste expérimental, car les types de paramètres reflètent intentionnellement l’exécuteur intégré actuel.

​
Quand utiliser un harnais

Enregistrez un harnais d’agent lorsqu’une famille de modèles possède son propre runtime de session natif et que le transport de fournisseur OpenClaw normal n’est pas la bonne abstraction. Exemples :
  • un serveur natif d’agent de codage qui possède les fils et la compaction
  • une CLI ou un démon local qui doit diffuser des événements natifs de plan/raisonnement/outils
  • un runtime de modèle qui a besoin de son propre identifiant de reprise en plus de la transcription de session OpenClaw
N’enregistrez pas un harnais uniquement pour ajouter une nouvelle API de LLM. Pour les API de modèle HTTP ou WebSocket normales, créez un plugin de fournisseur.

​
Ce que le noyau possède encore

Avant qu’un harnais soit sélectionné, OpenClaw a déjà résolu :
  • le fournisseur et le modèle
  • l’état d’authentification du runtime
  • le niveau de réflexion et le budget de contexte
  • le fichier de transcription/session OpenClaw
  • l’espace de travail, le bac à sable et la politique d’outils
  • les rappels de réponse du canal et les rappels de diffusion
  • la politique de solution de repli de modèle et de changement de modèle en direct
Cette séparation est intentionnelle. Un harnais exécute une tentative préparée ; il ne choisit pas les fournisseurs, ne remplace pas la livraison par canal et ne change pas silencieusement de modèle. La tentative préparée inclut aussi params.runtimePlan, un lot de politiques possédé par OpenClaw pour les décisions de runtime qui doivent rester partagées entre les harnais PI et natifs :
  • runtimePlan.tools.normalize(...) et runtimePlan.tools.logDiagnostics(...) pour la politique de schéma d’outils tenant compte du fournisseur
  • runtimePlan.transcript.resolvePolicy(...) pour l’assainissement de la transcription et la politique de réparation des appels d’outils
  • runtimePlan.delivery.isSilentPayload(...) pour la suppression partagée de livraison NO_REPLY et de médias
  • runtimePlan.outcome.classifyRunResult(...) pour la classification de la solution de repli de modèle
  • runtimePlan.observability pour les métadonnées résolues de fournisseur/modèle/harnais
Les harnais peuvent utiliser le plan pour les décisions qui doivent correspondre au comportement PI, mais doivent tout de même le traiter comme un état de tentative possédé par l’hôte. Ne le modifiez pas et ne l’utilisez pas pour changer de fournisseur/modèle pendant un tour.

​
Enregistrer un harnais

Importation : 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);
  },
});

​
Politique de sélection

OpenClaw choisit un harnais après la résolution fournisseur/modèle :
  1. La politique de runtime limitée au modèle l’emporte.
  2. La politique de runtime limitée au fournisseur vient ensuite.
  3. auto demande aux harnais enregistrés s’ils prennent en charge le fournisseur/modèle résolu.
  4. Si aucun harnais enregistré ne correspond, OpenClaw utilise PI, sauf si la solution de repli PI est désactivée.
Les échecs de harnais de plugin apparaissent comme des échecs d’exécution. En mode auto, la solution de repli PI n’est utilisée que lorsqu’aucun harnais de plugin enregistré ne prend en charge le fournisseur/modèle résolu. Une fois qu’un harnais de plugin a revendiqué une exécution, OpenClaw ne rejoue pas ce même tour via PI, car cela peut modifier la sémantique d’authentification/runtime ou dupliquer des effets de bord. Les épingles de runtime pour toute la session et tout l’agent sont ignorées par la sélection. Cela inclut les valeurs agentHarnessId de session obsolètes, agents.defaults.agentRuntime, agents.list[].agentRuntime et OPENCLAW_AGENT_RUNTIME. /status affiche le runtime effectif sélectionné à partir de la route fournisseur/modèle. Si le harnais sélectionné est surprenant, activez la journalisation de débogage agents/harness et inspectez l’enregistrement structuré agent harness selected du Gateway. Il inclut l’identifiant du harnais sélectionné, la raison de sélection, la politique de runtime/solution de repli et, en mode auto, le résultat de prise en charge de chaque plugin candidat. Le plugin Codex intégré enregistre codex comme identifiant de harnais. Le noyau le traite comme un identifiant ordinaire de harnais de plugin ; les alias spécifiques à Codex relèvent du plugin ou de la configuration opérateur, pas du sélecteur de runtime partagé.

​
Association fournisseur et harnais

La plupart des harnais devraient aussi enregistrer un fournisseur. Le fournisseur rend les références de modèle, l’état d’authentification, les métadonnées de modèle et la sélection /model visibles pour le reste d’OpenClaw. Le harnais revendique ensuite ce fournisseur dans supports(...). Le plugin Codex intégré suit ce modèle :
  • références de modèle utilisateur préférées : openai/gpt-5.5
  • références de compatibilité : les références héritées codex/gpt-* restent acceptées, mais les nouvelles configurations ne devraient pas les utiliser comme références fournisseur/modèle normales
  • identifiant de harnais : codex
  • authentification : disponibilité synthétique du fournisseur, car le harnais Codex possède la connexion/session Codex native
  • requête au serveur d’application : OpenClaw envoie l’identifiant de modèle nu à Codex et laisse le harnais communiquer avec le protocole natif du serveur d’application
Le plugin Codex est additif. Les références d’agent openai/gpt-* simples sur le fournisseur OpenAI officiel sélectionnent le harnais Codex par défaut. Les anciennes références codex/gpt-* sélectionnent toujours le fournisseur et le harnais Codex pour compatibilité. Pour la configuration opérateur, les exemples de préfixes de modèle et les configurations propres à Codex, voir Harnais Codex. OpenClaw requiert le serveur d’application Codex 0.125.0 ou plus récent. Le plugin Codex vérifie l’échange d’initialisation du serveur d’application et bloque les serveurs plus anciens ou sans version, afin qu’OpenClaw ne s’exécute que contre la surface de protocole avec laquelle il a été testé. Le plancher 0.125.0 inclut la prise en charge de la charge utile native du hook MCP arrivée dans Codex 0.124.0, tout en épinglant OpenClaw sur la ligne stable plus récente testée.

​
Intergiciel de résultats d’outils

Les plugins intégrés peuvent attacher un intergiciel de résultats d’outils neutre vis-à-vis du runtime via api.registerAgentToolResultMiddleware(...) lorsque leur manifeste déclare les identifiants de runtime ciblés dans contracts.agentToolResultMiddleware. Cette jointure fiable est destinée aux transformations asynchrones de résultats d’outils qui doivent s’exécuter avant que PI ou Codex renvoie la sortie d’outil au modèle. Les plugins intégrés hérités peuvent encore utiliser api.registerCodexAppServerExtensionFactory(...) pour l’intergiciel propre au serveur d’application Codex, mais les nouvelles transformations de résultats devraient utiliser l’API neutre vis-à-vis du runtime. Le hook propre à Pi api.registerEmbeddedExtensionFactory(...) a été supprimé ; les transformations de résultats d’outils Pi doivent utiliser l’intergiciel neutre vis-à-vis du runtime.

​
Classification du résultat terminal

Les harnais natifs qui possèdent leur propre projection de protocole peuvent utiliser classifyAgentHarnessTerminalOutcome(...) depuis openclaw/plugin-sdk/agent-harness-runtime lorsqu’un tour terminé n’a produit aucun texte d’assistant visible. L’assistant renvoie empty, reasoning-only ou planning-only afin que la politique de solution de repli d’OpenClaw puisse décider s’il faut réessayer sur un autre modèle. Il laisse intentionnellement non classés les erreurs de prompt, les tours en cours et les réponses silencieuses intentionnelles telles que NO_REPLY.

​
Mode de harnais Codex natif

Le harnais intégré codex est le mode Codex natif pour les tours d’agent OpenClaw intégrés. Activez d’abord le plugin intégré codex, et incluez codex dans plugins.allow si votre configuration utilise une liste d’autorisation restrictive. Les configurations de serveur d’application natif devraient utiliser openai/gpt-* ; les tours d’agent OpenAI sélectionnent le harnais Codex par défaut. Les routes héritées openai-codex/* devraient être réparées avec openclaw doctor --fix, et les références de modèle héritées codex/* restent des alias de compatibilité pour le harnais natif. Lorsque ce mode s’exécute, Codex possède l’identifiant de fil natif, le comportement de reprise, la compaction et l’exécution du serveur d’application. OpenClaw possède toujours le canal de chat, le miroir de transcription visible, la politique d’outils, les approbations, la livraison des médias et la sélection de session. Utilisez le fournisseur/modèle agentRuntime.id: "codex" lorsque vous devez prouver que seul le chemin du serveur d’application Codex peut revendiquer l’exécution. Les runtimes de plugin explicites échouent de manière fermée ; les échecs de sélection du serveur d’application Codex et les échecs de runtime ne sont pas réessayés via PI.

​
Rigueur du runtime

Par défaut, OpenClaw utilise la politique de runtime fournisseur/modèle auto : les harnais de plugin enregistrés peuvent revendiquer une paire fournisseur/modèle, et PI gère le tour lorsqu’aucun ne correspond. Les références d’agent OpenAI sur le fournisseur OpenAI officiel utilisent Codex par défaut. Utilisez un runtime de plugin fournisseur/modèle explicite tel que agentRuntime.id: "codex" lorsque l’absence de sélection de harnais devrait échouer au lieu d’être routée via PI. Les échecs de harnais de plugin sélectionné échouent toujours durement. Cela ne bloque pas un fournisseur/modèle explicite agentRuntime.id: "pi". Pour les exécutions intégrées propres à Codex : 
{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": {
          "id": "codex"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.5"
    }
  }
}
Si vous voulez un backend CLI pour un modèle canonique, placez le runtime sur cette entrée de modèle : 
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-7",
      "models": {
        "anthropic/claude-opus-4-7": {
          "agentRuntime": {
            "id": "claude-cli"
          }
        }
      }
    }
  }
}
Les remplacements par agent utilisent la même forme limitée au modèle : 
{
  "agents": {
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.5",
        "models": {
          "openai/gpt-5.5": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    ]
  }
}
Les exemples de runtime hérités pour tout l’agent comme celui-ci sont ignorés : 
{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}
Avec un runtime de plugin explicite, une session échoue tôt lorsque le harnais demandé n’est pas enregistré, ne prend pas en charge le fournisseur/modèle résolu, ou échoue avant de produire des effets de bord du tour. C’est intentionnel pour les déploiements propres à Codex et pour les tests en direct qui doivent prouver que le chemin du serveur d’application Codex est réellement utilisé. Ce paramètre contrôle uniquement le harnais d’agent intégré. Il ne désactive pas le routage de modèles propre au fournisseur pour l’image, la vidéo, la musique, la TTS, les PDF ou autre.

​
Sessions natives et miroir de transcription

Un harnais peut conserver un identifiant de session natif, un identifiant de fil ou un jeton de reprise côté démon. Gardez cette liaison explicitement associée à la session OpenClaw, et continuez à refléter la sortie assistant/outil visible par l’utilisateur dans la transcription OpenClaw. La transcription OpenClaw reste la couche de compatibilité pour :
  • l’historique de session visible par le canal
  • la recherche et l’indexation de transcriptions
  • le retour au harnais PI intégré lors d’un tour ultérieur
  • le comportement générique de /new, /reset et de suppression de session
Si votre harnais stocke une liaison annexe, implémentez reset(...) afin qu’OpenClaw puisse l’effacer lorsque la session OpenClaw propriétaire est réinitialisée.

​
Résultats d’outils et de médias

Le noyau construit la liste d’outils OpenClaw et la transmet à la tentative préparée. Lorsqu’un harnais exécute un appel d’outil dynamique, renvoyez le résultat de l’outil via la forme de résultat du harnais au lieu d’envoyer vous-même des médias de canal. Cela maintient les sorties de texte, image, vidéo, musique, TTS, approbation et outil de messagerie sur le même chemin de livraison que les exécutions adossées à PI.

​
Limitations actuelles

  • Le chemin d’importation public est générique, mais certains alias de types de tentative/résultat portent encore des noms Pi pour compatibilité.
  • L’installation de harnais tiers est expérimentale. Préférez les plugins de fournisseur jusqu’à ce que vous ayez besoin d’un runtime de session natif.
  • Le changement de harnais est pris en charge entre les tours. Ne changez pas de harnais au milieu d’un tour après que les outils natifs, les approbations, le texte d’assistant ou les envois de messages ont commencé.

​
Connexe