Les outils appellent l’API

• POST /tools/invoke
• Même port que le Gateway (multiplexage WS + HTTP) : http://<gateway-host>:<port>/tools/invoke
• Taille maximale par défaut du corps de la requête : 2 Mo

​

Authentification

• authentification par secret partagé (gateway.auth.mode="token" ou "password") : Authorization: Bearer <token-or-password>
• authentification HTTP de confiance porteuse d’identité (gateway.auth.mode="trusted-proxy") : acheminez la requête via le proxy configuré prenant en charge les identités et laissez-le injecter les en-têtes d’identité requis
• authentification ouverte sur un point d’entrée privé (gateway.auth.mode="none") : aucun en-tête d’authentification requis

• mode="token" utilise gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN).
• mode="password" utilise gateway.auth.password (ou OPENCLAW_GATEWAY_PASSWORD).
• mode="trusted-proxy" exige que la requête HTTP provienne d’une source de proxy de confiance configurée ; les proxys local loopback sur le même hôte nécessitent la définition explicite de gateway.auth.trustedProxy.allowLoopback = true.
• Les appelants internes sur le même hôte qui contournent le proxy peuvent utiliser gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD comme solution de repli locale directe. Toute présence des en-têtes Forwarded, X-Forwarded-* ou X-Real-IP maintient plutôt la requête sur le chemin du proxy de confiance.
• Si gateway.auth.rateLimit est configuré et qu’un trop grand nombre d’échecs d’authentification survient, le point de terminaison renvoie 429 avec Retry-After.

​

Périmètre de sécurité (important)

• Ici, l’authentification HTTP par jeton porteur ne constitue pas un modèle de portée restreinte par utilisateur.
• Un jeton ou mot de passe Gateway valide pour ce point de terminaison doit être considéré comme un identifiant de propriétaire ou d’opérateur.
• Pour les modes d’authentification par secret partagé (token et password), le point de terminaison rétablit les portées complètes par défaut de l’opérateur, même si l’appelant envoie un en-tête x-openclaw-scopes plus restrictif.
• L’authentification par secret partagé considère également les appels directs d’outils sur ce point de terminaison comme des tours provenant du propriétaire.
• Les modes HTTP de confiance porteurs d’identité (authentification par proxy de confiance, ou gateway.auth.mode="none" sur un point d’entrée privé) respectent x-openclaw-scopes lorsqu’il est présent et utilisent sinon l’ensemble normal des portées par défaut de l’opérateur.
• Limitez ce point de terminaison au local loopback, au réseau Tailscale ou à un point d’entrée privé ; ne l’exposez pas directement à l’Internet public.

​

Corps de la requête

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}

• tool / name (chaîne, obligatoire) : nom de l’outil à appeler. name est prioritaire si les deux sont envoyés.
• action (chaîne, facultatif) : fusionné dans args.action si le schéma de l’outil prend en charge une propriété action et si args ne l’a pas déjà définie.
• args (objet, facultatif) : arguments propres à l’outil.
• sessionKey (chaîne, facultatif) : clé de la session cible. Si elle est omise ou vaut "main", le Gateway utilise la clé de session principale configurée (en respectant session.mainKey et l’agent par défaut, ou global dans la portée de session globale).
• agentId (chaîne, facultatif) : résout la clé de session de cet agent. Renvoie une erreur 400 en cas de conflit avec une valeur sessionKey explicite déjà associée à un autre agent.
• idempotencyKey (chaîne, facultatif) : utilisée pour dériver un identifiant stable d’appel d’outil pour cette invocation.
• dryRun (booléen, facultatif) : réservé à un usage futur ; actuellement ignoré.

​

Comportement de la politique et du routage

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• politiques de groupe (si la clé de session correspond à un groupe ou à un canal)
• politique de sous-agent (lors d’un appel avec une clé de session de sous-agent)

• Les approbations d’exécution sont des garde-fous destinés aux opérateurs, et non un périmètre d’autorisation distinct pour ce point de terminaison HTTP. Si un outil est accessible ici par l’authentification du Gateway et la politique des outils, /tools/invoke n’ajoute aucune demande d’approbation supplémentaire par appel.
• Si exec est accessible ici, considérez-le comme une surface d’interpréteur de commandes capable d’effectuer des modifications. Refuser write, edit, apply_patch ou les outils HTTP d’écriture dans le système de fichiers ne rend pas l’exécution de commandes accessible en lecture seule.
• Ne partagez pas les identifiants porteurs du Gateway avec des appelants non fiables. Si vous devez séparer plusieurs périmètres de confiance, exécutez des Gateways distincts, idéalement avec des utilisateurs ou des hôtes de système d’exploitation distincts.

{
  gateway: {
    tools: {
      // Outils supplémentaires à bloquer via HTTP /tools/invoke
      deny: ["browser"],
      // Retirer des outils de la liste de refus par défaut pour les appelants propriétaires/administrateurs
      allow: ["gateway"],
    },
  },
}

• x-openclaw-message-channel: <channel> (exemple : slack, telegram)
• x-openclaw-account-id: <accountId> (lorsque plusieurs comptes existent)
• x-openclaw-message-to: <target> (cible de livraison pour la politique des outils de messagerie)
• x-openclaw-thread-id: <threadId> (contexte du fil pour la politique des outils de messagerie)

​

Réponses

​

Exemple

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'

​

Voir aussi

• Protocole du Gateway
• Outils et plugins