Passer au contenu principal

​
Invocation d’outils (HTTP)

La Gateway (passerelle) d’OpenClaw expose un point de terminaison HTTP simple pour invoquer directement un seul outil. Il est toujours activé, mais protégé par l’authentification de la Gateway et la politique d’outils.
  • POST /tools/invoke
  • Même port que la Gateway (multiplexage WS + HTTP) : http://<gateway-host>:<port>/tools/invoke
La taille maximale par défaut de la charge utile est de 2 Mo.

​
Authentification

Utilise la configuration d’authentification de la Gateway. Envoyez un jeton bearer :
  • Authorization: Bearer <token>
Notes :
  • 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).
  • Si gateway.auth.rateLimit est configuré et qu’un trop grand nombre d’échecs d’authentification se produit, le point de terminaison renvoie 429 avec Retry-After.

​
Corps de la requête

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
Champs :
  • tool (string, requis) : nom de l’outil à invoquer.
  • action (string, optionnel) : mappé dans les args si le schéma de l’outil prend en charge action et que la charge utile args l’a omis.
  • args (object, optionnel) : arguments spécifiques à l’outil.
  • sessionKey (string, optionnel) : clé de session cible. Si omise ou "main", la Gateway utilise la clé de session principale configurée (respecte session.mainKey et l’agent par défaut, ou global en portée globale).
  • dryRun (boolean, optionnel) : réservé à un usage futur ; actuellement ignoré.

​
Politique + comportement de routage

La disponibilité des outils est filtrée via la même chaîne de politiques que celle utilisée par les agents de la Gateway :
  • 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’une invocation avec une clé de session de sous‑agent)
Si un outil n’est pas autorisé par la politique, le point de terminaison renvoie 404. Gateway HTTP applique également par défaut une liste de refus stricte (même si la politique de session autorise l’outil) :
  • sessions_spawn
  • sessions_send
  • gateway
  • whatsapp_login
Vous pouvez personnaliser cette liste de refus via gateway.tools : 
{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list
      allow: ["gateway"],
    },
  },
}
Pour aider les politiques de groupe à résoudre le contexte, vous pouvez éventuellement définir :
  • 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 invalide ou erreur d’outil)
  • 401 → non autorisé
  • 429 → authentification limitée par le taux (Retry-After défini)
  • 404 → outil non disponible (introuvable ou non autorisé)
  • 405 → méthode non autorisée
  • 500 → { ok: false, error: { type, message } } (erreur inattendue lors de l’exécution de l’outil ; message assaini)

​
Exemple

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