​

Outils de session

​

Noms des outils

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

​

Modèle de clé

• Le compartiment de discussion directe principal est toujours la cle litterale "main" (resolue vers la cle principale de l’agent courant).
• Les discussions de groupe utilisent agent:<agentId>:<channel>:group:<id> ou agent:<agentId>:<channel>:channel:<id> (fournir la cle complete).
• Les taches cron utilisent cron:<job.id>.
• Les hooks utilisent hook:<uuid> sauf configuration explicite.
• Les sessions Node utilisent node-<nodeId> sauf configuration explicite.

​

sessions_list

• filtre kinds?: string[] : l’un de "main" | "group" | "cron" | "hook" | "node" | "other"
• limit?: number nombre maximal de lignes (defaut : defaut serveur, limite p. ex. 200)
• activeMinutes?: number uniquement les sessions mises a jour dans les N dernieres minutes
• messageLimit?: number 0 = aucun message (defaut 0) ; >0 = inclure les N derniers messages

• messageLimit > 0 recupere chat.history par session et inclut les N derniers messages.
• Les resultats d’outils sont filtres dans la sortie de liste ; utilisez sessions_history pour les messages d’outil.
• Lorsqu’elle s’execute dans une session d’agent en sandbox, les outils de session adoptent par defaut une visibilite limitee aux sessions engendrees (voir ci‑dessous).

• key : cle de session (string)
• kind : main | group | cron | hook | node | other
• channel : whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown
• displayName (libelle d’affichage de groupe si disponible)
• updatedAt (ms)
• sessionId
• model, contextTokens, totalTokens
• thinkingLevel, verboseLevel, systemSent, abortedLastRun
• sendPolicy (surcharge de session si definie)
• lastChannel, lastTo
• deliveryContext ({ channel, to, accountId } normalise lorsque disponible)
• transcriptPath (chemin « best‑effort » derive du repertoire de stockage + sessionId)
• messages? (uniquement lorsque messageLimit > 0)

​

sessions_history

• sessionKey (requis ; accepte une cle de session ou sessionId depuis sessions_list)
• limit?: number nombre maximal de messages (limite par le serveur)
• includeTools?: boolean (defaut false)

• includeTools=false filtre les messages role: "toolResult".
• Retourne un tableau de messages au format brut de transcription.
• Lorsqu’un sessionId est fourni, OpenClaw le resout vers la cle de session correspondante (erreur si identifiants manquants).

​

sessions_send

• sessionKey (requis ; accepte une cle de session ou sessionId depuis sessions_list)
• message (requis)
• timeoutSeconds?: number (defaut >0 ; 0 = fire‑and‑forget)

• timeoutSeconds = 0 : met en file d’attente et retourne { runId, status: "accepted" }.
• timeoutSeconds > 0 : attend jusqu’a N secondes l’achevement, puis retourne { runId, status: "ok", reply }.
• Si l’attente expire : { runId, status: "timeout", error }. L’execution continue ; appelez sessions_history plus tard.
• Si l’execution echoue : { runId, status: "error", error }.
• Les executions d’annonce de livraison sont lancees apres l’execution principale et sont « best‑effort » ; status: "ok" ne garantit pas que l’annonce a ete livree.
• L’attente passe par la Gateway (passerelle) agent.wait (cote serveur) afin que les reconnexions n’interrompent pas l’attente.
• Le contexte de message agent‑a‑agent est injecte pour l’execution principale.
• Les messages inter-session sont persistés avec message.provenance.kind = "inter_session" afin que les lecteurs de transcription puissent distinguer les instructions d’agent routées des entrées utilisateur externes.
• Une fois la boucle terminee, OpenClaw lance l’etape d’annonce agent‑a‑agent (agent cible uniquement) :
  • Les tours 2+ alternent entre l’agent demandeur et l’agent cible.
  • Repondez exactement REPLY_SKIP pour arreter le ping‑pong.
  • Le nombre maximal de tours est session.agentToAgent.maxPingPongTurns (0–5, defaut 5).
• Apres l’achevement de l’execution principale, OpenClaw lance une boucle de reponse‑retour :
  • Repondez exactement ANNOUNCE_SKIP pour rester silencieux.
  • Toute autre reponse est envoyee au canal cible.
  • L’etape d’annonce inclut la demande originale + la reponse du tour 1 + la derniere reponse de ping‑pong.

​

Champ Channel

• Pour les groupes, channel est le canal enregistre sur l’entree de session.
• Pour les discussions directes, channel est mappe depuis lastChannel.
• Pour cron/hook/node, channel est internal.
• S’il est manquant, channel est unknown.

​

Securite / Politique d’envoi

{
  "session": {
    "sendPolicy": {
      "rules": [
        {
          "match": { "channel": "discord", "chatType": "group" },
          "action": "deny"
        }
      ],
      "default": "allow"
    }
  }
}

• sendPolicy: "allow" | "deny" (non defini = herite de la configuration)
• Definissable via sessions.patch ou /send on|off|inherit reserve au proprietaire (message autonome).

• chat.send / agent (Gateway)
• logique de livraison des reponses automatiques

​

sessions_spawn

• task (requis)
• label? (optionnel ; utilise pour les logs/UI)
• agentId? (optionnel ; lancer sous un autre identifiant d’agent si autorise)
• model? (optionnel ; remplace le modele du sous‑agent ; valeurs invalides = erreur)
• runTimeoutSeconds? (defaut 0 ; si defini, interrompt l’execution du sous‑agent apres N secondes)
• cleanup? (delete|keep, defaut keep)

• agents.list[].subagents.allowAgents : liste des identifiants d’agent autorises via agentId (["*"] pour autoriser tous). Defaut : uniquement l’agent demandeur.

• Utilisez agents_list pour decouvrir quels identifiants d’agent sont autorises pour sessions_spawn.

• Demarre une nouvelle session agent:<agentId>:subagent:<uuid> avec deliver: false.
• Les sous‑agents disposent par defaut de l’ensemble complet d’outils moins les outils de session (configurable via tools.subagents.tools).
• Les sous‑agents ne sont pas autorises a appeler sessions_spawn (pas de sous‑agent → lancement de sous‑agent).
• Toujours non bloquant : retourne immediatement { status: "accepted", runId, childSessionKey }.
• Apres l’achevement, OpenClaw lance une etape d’annonce du sous‑agent et publie le resultat dans le canal de discussion du demandeur.
• Repondez exactement ANNOUNCE_SKIP pendant l’etape d’annonce pour rester silencieux.
• Les reponses d’annonce sont normalisees en Status/Result/Notes ; Status provient du resultat a l’execution (pas du texte du modele).
• Les sessions de sous‑agent sont archivees automatiquement apres agents.defaults.subagents.archiveAfterMinutes (defaut : 60).
• Les reponses d’annonce incluent une ligne de statistiques (duree d’execution, tokens, sessionKey/sessionId, chemin de transcription et cout optionnel).

​

Visibilite des sessions en sandbox

{
  agents: {
    defaults: {
      sandbox: {
        // default: "spawned"
        sessionToolsVisibility: "spawned", // or "all"
      },
    },
  },
}