​

Ferramentas de Sessão

​

Nomes das Ferramentas

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

​

Modelo de Chaves

• O bucket principal de chat direto é sempre a chave literal "main" (resolvida para a chave principal do agente atual).
• Chats em grupo usam agent:<agentId>:<channel>:group:<id> ou agent:<agentId>:<channel>:channel:<id> (passe a chave completa).
• Jobs de cron usam cron:<job.id>.
• Hooks usam hook:<uuid> a menos que seja explicitamente definido.
• Sessões de node usam node-<nodeId> a menos que seja explicitamente definido.

​

sessions_list

• filtro kinds?: string[]: qualquer um de "main" | "group" | "cron" | "hook" | "node" | "other"
• limit?: number máximo de linhas (padrão: padrão do servidor, limitado, por exemplo, a 200)
• activeMinutes?: number apenas sessões atualizadas nos últimos N minutos
• messageLimit?: number 0 = sem mensagens (padrão 0); >0 = incluir as últimas N mensagens

• messageLimit > 0 busca chat.history por sessão e inclui as últimas N mensagens.
• Resultados de ferramentas são filtrados na saída da lista; use sessions_history para mensagens de ferramenta.
• Ao executar em uma sessão de agente em sandbox, as ferramentas de sessão usam por padrão visibilidade apenas das sessões geradas (veja abaixo).

• key: chave da sessão (string)
• kind: main | group | cron | hook | node | other
• channel: whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown
• displayName (rótulo de exibição do grupo, se disponível)
• updatedAt (ms)
• sessionId
• model, contextTokens, totalTokens
• thinkingLevel, verboseLevel, systemSent, abortedLastRun
• sendPolicy (override de sessão, se definido)
• lastChannel, lastTo
• deliveryContext ({ channel, to, accountId } normalizado quando disponível)
• transcriptPath (caminho de melhor esforço derivado do diretório do store + sessionId)
• messages? (somente quando messageLimit > 0)

​

sessions_history

• sessionKey (obrigatório; aceita chave da sessão ou sessionId de sessions_list)
• limit?: number máximo de mensagens (limitado pelo servidor)
• includeTools?: boolean (padrão false)

• includeTools=false filtra mensagens role: "toolResult".
• Retorna um array de mensagens no formato bruto da transcrição.
• Quando fornecido um sessionId, o OpenClaw resolve para a chave de sessão correspondente (erro se id ausente).

​

sessions_send

• sessionKey (obrigatório; aceita chave da sessão ou sessionId de sessions_list)
• message (obrigatório)
• timeoutSeconds?: number (padrão >0; 0 = fire-and-forget)

• timeoutSeconds = 0: enfileira e retorna { runId, status: "accepted" }.
• timeoutSeconds > 0: aguarda até N segundos pela conclusão e então retorna { runId, status: "ok", reply }.
• Se a espera expirar: { runId, status: "timeout", error }. A execução continua; chame sessions_history depois.
• Se a execução falhar: { runId, status: "error", error }.
• Execuções de anúncio de entrega ocorrem após a execução primária concluir e são de melhor esforço; status: "ok" não garante que o anúncio foi entregue.
• Aguarda via agent.wait do gateway (lado do servidor) para que reconexões não interrompam a espera.
• O contexto de mensagem agente‑para‑agente é injetado para a execução primária.
• Mensagens entre sessões são persistidas com message.provenance.kind = "inter_session" para que leitores de transcrições possam distinguir instruções de agentes roteadas de entradas externas de usuários.
• Quando o loop termina, o OpenClaw executa a etapa de anúncio agente‑para‑agente (somente agente alvo):
  • A partir da rodada 2, alterna entre os agentes solicitante e alvo.
  • Responda exatamente REPLY_SKIP para parar o ping‑pong.
  • O máximo de turnos é session.agentToAgent.maxPingPongTurns (0–5, padrão 5).
• Após a execução primária concluir, o OpenClaw executa um loop de resposta de volta:
  • Responda exatamente ANNOUNCE_SKIP para permanecer em silêncio.
  • Qualquer outra resposta é enviada para o canal de destino.
  • A etapa de anúncio inclui a solicitação original + resposta da rodada 1 + a resposta mais recente do ping‑pong.

​

Campo Channel

• Para grupos, channel é o canal registrado na entrada da sessão.
• Para chats diretos, channel mapeia a partir de lastChannel.
• Para cron/hook/node, channel é internal.
• Se ausente, channel é unknown.

​

Segurança / Política de Envio

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

• sendPolicy: "allow" | "deny" (não definido = herda configuração)
• Definível via sessions.patch ou /send on|off|inherit exclusivo do proprietário (mensagem independente).

• chat.send / agent (gateway)
• lógica de entrega de resposta automática

​

sessions_spawn

• task (obrigatório)
• label? (opcional; usado para logs/UI)
• agentId? (opcional; iniciar sob outro id de agente, se permitido)
• model? (opcional; sobrescreve o modelo do sub‑agente; valores inválidos geram erro)
• runTimeoutSeconds? (padrão 0; quando definido, aborta a execução do sub‑agente após N segundos)
• cleanup? (delete|keep, padrão keep)

• agents.list[].subagents.allowAgents: lista de ids de agentes permitidos via agentId (["*"] para permitir qualquer). Padrão: apenas o agente solicitante.

• Use agents_list para descobrir quais ids de agentes são permitidos para sessions_spawn.

• Inicia uma nova sessão agent:<agentId>:subagent:<uuid> com deliver: false.
• Sub‑agentes usam por padrão o conjunto completo de ferramentas menos ferramentas de sessão (configurável via tools.subagents.tools).
• Sub‑agentes não têm permissão para chamar sessions_spawn (sem spawn de sub‑agente → sub‑agente).
• Sempre não bloqueante: retorna { status: "accepted", runId, childSessionKey } imediatamente.
• Após a conclusão, o OpenClaw executa uma etapa de anúncio do sub‑agente e publica o resultado no canal de chat do solicitante.
• Responda exatamente ANNOUNCE_SKIP durante a etapa de anúncio para permanecer em silêncio.
• Respostas de anúncio são normalizadas para Status/Result/Notes; Status vem do resultado em tempo de execução (não do texto do modelo).
• Sessões de sub‑agente são arquivadas automaticamente após agents.defaults.subagents.archiveAfterMinutes (padrão: 60).
• Respostas de anúncio incluem uma linha de estatísticas (tempo de execução, tokens, sessionKey/sessionId, caminho da transcrição e custo opcional).

​

Visibilidade de Sessões em Sandbox

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