Ferramentas da sessão

OpenClaw oferece aos agentes ferramentas para trabalhar entre sessões, inspecionar status e orquestrar subagentes.

# Ferramentas disponíveis

Ferramenta	O que ela faz
sessions_list	Lista sessões com filtros opcionais (tipo, rótulo, agente, recência, prévia)
sessions_history	Lê a transcrição de uma sessão específica
sessions_send	Envia uma mensagem para outra sessão e, opcionalmente, aguarda
sessions_spawn	Cria uma sessão isolada de subagente para trabalho em segundo plano
sessions_yield	Encerra o turno atual e aguarda resultados posteriores do subagente
subagents	Lista, orienta ou encerra subagentes criados para esta sessão
session_status	Mostra um cartão no estilo /status e, opcionalmente, define uma substituição de modelo por sessão

Essas ferramentas ainda estão sujeitas ao perfil de ferramentas ativo e à política de permitir/negar. tools.profile: "coding" inclui o conjunto completo de orquestração de sessões, incluindo sessions_spawn, sessions_yield e subagents. tools.profile: "messaging" inclui ferramentas de mensagens entre sessões (sessions_list, sessions_history, sessions_send, session_status), mas não inclui criação de subagentes. Para manter um perfil de mensagens e ainda permitir delegação nativa, adicione:

{
  tools: {
    profile: "messaging",
    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],
  },
}

Políticas de grupo, provedor, sandbox e por agente ainda podem remover essas ferramentas após a etapa de perfil. Use /tools na sessão afetada para inspecionar a lista efetiva de ferramentas.

# Listando e lendo sessões

sessions_list retorna sessões com chave, agentId, tipo, canal, modelo, contagens de tokens e carimbos de data/hora. Filtre por tipo (main, group, cron, hook, node), label exato, agentId exato, texto de busca ou recência (activeMinutes). Quando você precisa de triagem no estilo caixa de entrada, ela também pode solicitar um título derivado com escopo de visibilidade, um trecho de prévia da última mensagem ou mensagens recentes limitadas em cada linha. Títulos derivados e prévias são produzidos apenas para sessões que o chamador já pode ver de acordo com a política configurada de visibilidade da ferramenta de sessão, portanto sessões não relacionadas permanecem ocultas.

sessions_history busca a transcrição da conversa para uma sessão específica. Por padrão, resultados de ferramentas são excluídos -- passe includeTools: true para vê-los. A visualização retornada é intencionalmente limitada e filtrada por segurança:

• o texto do assistente é normalizado antes da recuperação:
  • tags de raciocínio são removidas
  • blocos estruturais <relevant-memories> / <relevant_memories> são removidos
  • blocos de payload XML de chamada de ferramenta em texto puro, como <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls> e <function_calls>...</function_calls> são removidos, incluindo payloads truncados que nunca fecham corretamente
  • estruturas rebaixadas de chamada/resultado de ferramenta, como [Tool Call: ...], [Tool Result ...] e [Historical context ...], são removidas
  • tokens vazados de controle de modelo, como <|assistant|>, outros tokens ASCII <|...|> e variantes de largura total <｜...｜> são removidos
  • XML malformado de chamada de ferramenta MiniMax, como <invoke ...> / </minimax:tool_call>, é removido
• texto semelhante a credenciais/tokens é redigido antes de ser retornado
• blocos longos de texto são truncados
• históricos muito grandes podem descartar linhas mais antigas ou substituir uma linha grande demais por [sessions_history omitted: message too large]
• a ferramenta informa sinalizadores de resumo, como truncated, droppedMessages, contentTruncated, contentRedacted e bytes

Ambas as ferramentas aceitam uma chave de sessão (como "main") ou um ID de sessão de uma chamada de listagem anterior.

Se você precisa da transcrição exata byte por byte, inspecione o arquivo de transcrição em disco em vez de tratar sessions_history como um despejo bruto.

# Enviando mensagens entre sessões

sessions_send entrega uma mensagem para outra sessão e, opcionalmente, aguarda a resposta:

• Enviar e seguir: defina timeoutSeconds: 0 para enfileirar e retornar imediatamente.
• Aguardar resposta: defina um tempo limite e receba a resposta inline.

Sessões de chat com escopo de thread, como chaves do Slack ou Discord terminadas em :thread:<id>, não são alvos válidos de sessions_send. Use a chave da sessão do canal pai para coordenação entre agentes, para que mensagens roteadas por ferramenta não apareçam dentro de uma thread ativa voltada a humanos.

Mensagens e respostas posteriores A2A são marcadas como dados entre sessões no prompt receptor ([Inter-session message ... isUser=false]) e na proveniência da transcrição. O agente receptor deve tratá-las como dados roteados por ferramenta, não como uma instrução direta escrita pelo usuário final.

Depois que o alvo responde, o OpenClaw pode executar um loop de resposta de volta em que os agentes alternam mensagens (até 5 turnos). O agente alvo pode responder REPLY_SKIP para parar antecipadamente.

# Auxiliares de status e orquestração

session_status é a ferramenta leve equivalente a /status para a sessão atual ou outra sessão visível. Ela informa uso, tempo, estado de modelo/runtime e contexto vinculado de tarefa em segundo plano quando presente. Como /status, ela pode preencher contadores esparsos de token/cache a partir da entrada de uso mais recente da transcrição, e model=default limpa uma substituição por sessão. Use sessionKey="current" para a sessão atual do chamador; rótulos de cliente visíveis, como openclaw-tui, não são chaves de sessão.

sessions_yield encerra intencionalmente o turno atual para que a próxima mensagem possa ser o evento posterior que você está aguardando. Use-a após criar subagentes quando você quiser que os resultados de conclusão cheguem como a próxima mensagem, em vez de criar loops de polling.

subagents é o auxiliar de plano de controle para subagentes OpenClaw já criados. Ele aceita:

• action: "list" para inspecionar execuções ativas/recentes
• action: "steer" para enviar orientação posterior a um filho em execução
• action: "kill" para parar um filho ou all

# Criando subagentes

sessions_spawn cria, por padrão, uma sessão isolada para uma tarefa em segundo plano. Ela é sempre não bloqueante -- retorna imediatamente com um runId e childSessionKey.

Opções principais:

• runtime: "subagent" (padrão) ou "acp" para agentes de harness externo.
• Substituições de model e thinking para a sessão filha.
• thread: true para vincular a criação a uma thread de chat (Discord, Slack etc.).
• sandbox: "require" para impor sandboxing ao filho.
• context: "fork" para subagentes nativos quando o filho precisa da transcrição atual do solicitante; omita ou use context: "isolated" para um filho limpo. Subagentes nativos vinculados a threads usam context: "fork" por padrão, a menos que threadBindings.defaultSpawnContext diga o contrário.

Subagentes folha padrão não recebem ferramentas de sessão. Quando maxSpawnDepth >= 2, subagentes orquestradores de profundidade 1 recebem adicionalmente sessions_spawn, subagents, sessions_list e sessions_history para que possam gerenciar seus próprios filhos. Execuções folha ainda não recebem ferramentas de orquestração recursiva.

Após a conclusão, uma etapa de anúncio publica o resultado no canal do solicitante. A entrega da conclusão preserva o roteamento de thread/tópico vinculado quando disponível, e se a origem da conclusão identifica apenas um canal, o OpenClaw ainda pode reutilizar a rota armazenada da sessão do solicitante (lastChannel / lastTo) para entrega direta.

Para comportamento específico de ACP, consulte Agentes ACP.

# Visibilidade

Ferramentas de sessão têm escopo para limitar o que o agente pode ver:

Nível	Escopo
self	Apenas a sessão atual
tree	Sessão atual + subagentes criados
agent	Todas as sessões deste agente
all	Todas as sessões (entre agentes, se configurado)

O padrão é tree. Sessões em sandbox são limitadas a tree, independentemente da configuração.

# Leitura adicional

• Gerenciamento de sessões -- roteamento, ciclo de vida, manutenção
• Agentes ACP -- criação de harness externo
• Multiagente -- arquitetura multiagente
• Configuração do Gateway -- controles de configuração de ferramentas de sessão

# Relacionado

• Gerenciamento de sessões
• Poda de sessões