Pular para o conteúdo principal

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.

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

​
Ferramentas disponíveis

FerramentaO que ela faz
sessions_listLista sessões com filtros opcionais (tipo, rótulo, agente, recência, prévia)
sessions_historyLê a transcrição de uma sessão específica
sessions_sendEnvia uma mensagem para outra sessão e opcionalmente aguarda
sessions_spawnGera uma sessão isolada de subagente para trabalho em segundo plano
sessions_yieldEncerra o turno atual e aguarda resultados de acompanhamento do subagente
subagentsLista, direciona ou encerra subagentes gerados para esta sessão
session_statusMostra 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 permissão/negação. 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 a geraçã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 depois da etapa de perfil. Use /tools a partir da sessão afetada para inspecionar a lista efetiva de ferramentas.

​
Listando e lendo sessões

sessions_list retorna sessões com sua 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ê precisar 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 sob a política de visibilidade configurada para ferramentas de sessão, de modo que sessões não relacionadas permaneçam ocultas. sessions_history busca a transcrição da conversa de uma sessão específica. Por padrão, os 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 pensamento são removidas
    • blocos de estrutura <relevant-memories> / <relevant_memories> são removidos
    • blocos de payload XML de chamada de ferramenta em texto simples, 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 do modelo, como <|assistant|>, outros tokens ASCII <|...|> e variantes em largura total <｜...｜> são removidos
    • XML malformado de chamada de ferramenta do MiniMax, como <invoke ...> / </minimax:tool_call>, é removido
  • texto semelhante a credenciais/tokens é redigido antes de ser retornado
  • blocos de texto longos 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 relata 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 lista anterior. Se você precisar da transcrição exata byte a byte, inspecione o arquivo de transcrição no disco em vez de tratar sessions_history como um despejo bruto.

​
Enviando mensagens entre sessões

sessions_send entrega uma mensagem a outra sessão e opcionalmente aguarda a resposta:
  • Disparar e esquecer: defina timeoutSeconds: 0 para enfileirar e retornar imediatamente.
  • Aguardar resposta: defina um tempo limite e obtenha a resposta em linha.
Sessões de chat com escopo de thread, como chaves do Slack ou Discord terminando em :thread:<id>, não são destinos válidos para sessions_send. Use a chave de 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 de acompanhamento A2A são marcadas como dados entre sessões no prompt de recebimento ([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 escrita diretamente pelo usuário final. Depois que o destino responde, o OpenClaw pode executar um loop de resposta de volta, em que os agentes alternam mensagens (até session.agentToAgent.maxPingPongTurns, intervalo de 0 a 20, padrão 5). O agente de destino 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 relata uso, tempo, estado de modelo/runtime e contexto vinculado de tarefa em segundo plano quando presente. Como /status, ela pode preencher retroativamente 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 de acompanhamento que você está aguardando. Use-a depois de gerar subagentes quando quiser que os resultados de conclusão cheguem como a próxima mensagem, em vez de criar loops de sondagem. subagents é o auxiliar do plano de controle para subagentes OpenClaw já gerados. Ele oferece suporte a:
  • action: "list" para inspecionar execuções ativas/recentes
  • action: "steer" para enviar orientação de acompanhamento a um filho em execução
  • action: "kill" para interromper um filho ou all

​
Gerando 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 externos.
  • Substituições de model e thinking para a sessão filha.
  • thread: true para vincular a geraçã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 thread 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 de conclusão preserva o roteamento de thread/tópico vinculado quando disponível e, se a origem da conclusão identificar apenas um canal, o OpenClaw ainda pode reutilizar a rota armazenada da sessão solicitante (lastChannel / lastTo) para entrega direta. Para comportamento específico de ACP, consulte Agentes ACP.

​
Visibilidade

As ferramentas de sessão têm escopo para limitar o que o agente pode ver:
NívelEscopo
selfApenas a sessão atual
treeSessão atual + subagentes gerados
agentTodas as sessões deste agente
allTodas 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

​
Relacionados