API d’invocation des outils

Documentation Index

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

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

• POST /tools/invoke
• Même port que le Gateway (multiplexage WS + HTTP) : http://<gateway-host>:<port>/tools/invoke

​

Authentification

• authentification par secret partagé (gateway.auth.mode="token" ou "password") : Authorization: Bearer <token-or-password>
• authentification HTTP de confiance portant une identité (gateway.auth.mode="trusted-proxy") : passer par le proxy configuré avec prise en charge de l’identité et le laisser injecter les en-têtes d’identité requis
• authentification ouverte sur ingress privé (gateway.auth.mode="none") : aucun en-tête d’authentification requis

• Lorsque gateway.auth.mode="token", utilisez gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN).
• Lorsque gateway.auth.mode="password", utilisez gateway.auth.password (ou OPENCLAW_GATEWAY_PASSWORD).
• Lorsque gateway.auth.mode="trusted-proxy", la requête HTTP doit provenir d’une source de proxy de confiance configurée ; les proxies loopback sur le même hôte nécessitent gateway.auth.trustedProxy.allowLoopback = true explicitement.
• Si gateway.auth.rateLimit est configuré et qu’un trop grand nombre d’échecs d’authentification se produit, l’endpoint renvoie 429 avec Retry-After.

​

Frontière de sécurité (important)

• L’authentification bearer HTTP ici n’est pas un modèle de portée étroite par utilisateur.
• Un token/mot de passe Gateway valide pour cet endpoint doit être traité comme un identifiant propriétaire/opérateur.
• Pour les modes d’authentification par secret partagé (token et password), l’endpoint restaure les valeurs par défaut normales d’opérateur complet même si l’appelant envoie un en-tête x-openclaw-scopes plus étroit.
• L’authentification par secret partagé traite également les invocations directes d’outils sur cet endpoint comme des tours envoyés par le propriétaire.
• Les modes HTTP de confiance portant une identité (par exemple l’authentification par proxy de confiance ou gateway.auth.mode="none" sur un ingress privé) respectent x-openclaw-scopes lorsqu’il est présent et reviennent sinon à l’ensemble normal de portées opérateur par défaut.
• Gardez cet endpoint uniquement sur loopback/tailnet/ingress privé ; ne l’exposez pas directement à l’internet public.

• gateway.auth.mode="token" ou "password" + Authorization: Bearer ...
  • prouve la possession du secret partagé d’opérateur du gateway
  • ignore les x-openclaw-scopes plus étroits
  • restaure l’ensemble complet des portées opérateur par défaut : operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • traite les invocations directes d’outils sur cet endpoint comme des tours envoyés par le propriétaire
• modes HTTP de confiance portant une identité (par exemple l’authentification par proxy de confiance, ou gateway.auth.mode="none" sur ingress privé)
  • authentifient une identité externe de confiance ou une frontière de déploiement
  • respectent x-openclaw-scopes lorsque l’en-tête est présent
  • reviennent à l’ensemble normal des portées opérateur par défaut lorsque l’en-tête est absent
  • ne perdent la sémantique de propriétaire que lorsque l’appelant restreint explicitement les portées et omet operator.admin

​

Corps de la requête

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

• tool (chaîne, requis) : nom de l’outil à invoquer.
• action (chaîne, facultatif) : mappé dans les arguments si le schéma de l’outil prend en charge action et que la charge utile des arguments l’a omis.
• args (objet, facultatif) : arguments propres à l’outil.
• sessionKey (chaîne, facultatif) : clé de session cible. Si elle est omise ou vaut "main", le Gateway utilise la clé de session principale configurée (respecte session.mainKey et l’agent par défaut, ou global dans la portée globale).
• dryRun (booléen, facultatif) : réservé à une utilisation future ; actuellement ignoré.

​

Comportement de politique et de 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 de l’invocation avec une clé de session de sous-agent)

• Les approbations exec sont des garde-fous opérateur, pas une frontière d’autorisation distincte pour cet endpoint HTTP. Si un outil est accessible ici via l’authentification du Gateway + la politique d’outils, /tools/invoke n’ajoute pas de demande d’approbation supplémentaire par appel.
• Si exec est accessible ici, traitez-le comme une surface shell mutative. Refuser write, edit, apply_patch ou des outils HTTP d’écriture dans le système de fichiers ne rend pas l’exécution shell en lecture seule.
• Ne partagez pas les identifiants bearer du Gateway avec des appelants non approuvés. Si vous avez besoin de séparation entre frontières de confiance, exécutez des gateways distincts (et idéalement des utilisateurs/hôtes OS distincts).

• exec - exécution directe de commandes (surface RCE)
• spawn - création arbitraire de processus enfants (surface RCE)
• shell - exécution de commandes shell (surface RCE)
• fs_write - mutation arbitraire de fichiers sur l’hôte
• fs_delete - suppression arbitraire de fichiers sur l’hôte
• fs_move - déplacement/renommage arbitraire de fichiers sur l’hôte
• apply_patch - l’application de patchs peut réécrire des fichiers arbitraires
• sessions_spawn - orchestration de sessions ; générer des agents à distance est une RCE
• sessions_send - injection de messages entre sessions
• cron - plan de contrôle d’automatisation persistante
• gateway - plan de contrôle du gateway ; empêche la reconfiguration via HTTP
• nodes - le relais de commandes de Node peut atteindre system.run sur les hôtes appairés
• whatsapp_login - configuration interactive nécessitant le scan d’un QR code dans le terminal ; bloque sur HTTP

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list
      allow: ["gateway"],
    },
  },
}

• x-openclaw-message-channel: <channel> (exemple : slack, telegram)
• x-openclaw-account-id: <accountId> (lorsque plusieurs comptes existent)

​

Réponses

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (requête non valide ou erreur d’entrée de l’outil)
• 401 → non autorisé
• 429 → authentification limitée par débit (Retry-After défini)
• 404 → outil non disponible (introuvable ou non présent dans la liste d’autorisation)
• 405 → méthode non autorisée
• 500 → { ok: false, error: { type, message } } (erreur inattendue d’exécution de l’outil ; message assaini)

​

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": {}
  }'

​

Connexe

• Protocole du Gateway
• Outils et plugins