​

Loop do Agente (OpenClaw)

Um loop agêntico é a execução “real” completa de um agente: ingestão → montagem de contexto → inferência do modelo → execução de ferramentas → respostas em streaming → persistência. É o caminho autoritativo que transforma uma mensagem em ações e uma resposta final, mantendo o estado da sessão consistente. No OpenClaw, um loop é uma única execução serializada por sessão que emite eventos de ciclo de vida e de stream conforme o modelo pensa, chama ferramentas e transmite a saída. Este documento explica como esse loop autêntico é conectado de ponta a ponta.

​

Pontos de entrada

• RPC do Gateway: agent e agent.wait.
• CLI: comando agent.

​

Como funciona (alto nível)

1. O RPC agent valida parâmetros, resolve a sessão (sessionKey/sessionId), persiste metadados da sessão e retorna { runId, acceptedAt } imediatamente.
2. O agentCommand executa o agente:
   • resolve o modelo + padrões de thinking/verbose
   • carrega o snapshot de Skills
   • chama runEmbeddedPiAgent (runtime do pi-agent-core)
   • emite lifecycle end/error se o loop incorporado não emitir um
3. O runEmbeddedPiAgent:
   • serializa execuções via filas por sessão + globais
   • resolve o modelo + perfil de autenticação e constrói a sessão do pi
   • assina eventos do pi e transmite deltas do assistente/ferramentas
   • impõe timeout -> aborta a execução se excedido
   • retorna payloads + metadados de uso
4. O subscribeEmbeddedPiSession faz a ponte dos eventos do pi-agent-core para o stream agent do OpenClaw:
   • eventos de ferramenta => stream: "tool"
   • deltas do assistente => stream: "assistant"
   • eventos de ciclo de vida => stream: "lifecycle" (phase: "start" | "end" | "error")
5. O agent.wait usa waitForAgentJob:
   • aguarda lifecycle end/error para runId
   • retorna { status: ok|error|timeout, startedAt, endedAt, error? }

​

Enfileiramento + concorrência

• As execuções são serializadas por chave de sessão (faixa de sessão) e opcionalmente por uma faixa global.
• Isso evita corridas de ferramenta/sessão e mantém o histórico da sessão consistente.
• Canais de mensagens podem escolher modos de fila (collect/steer/followup) que alimentam esse sistema de faixas. Veja Command Queue.

​

Preparação de sessão + workspace

• O workspace é resolvido e criado; execuções em sandbox podem redirecionar para uma raiz de workspace em sandbox.
• Skills são carregadas (ou reutilizadas a partir de um snapshot) e injetadas no env e no prompt.
• Arquivos de bootstrap/contexto são resolvidos e injetados no relatório do prompt do sistema.
• Um bloqueio de escrita da sessão é adquirido; SessionManager é aberto e preparado antes do streaming.

​

Montagem do prompt + prompt do sistema

• O prompt do sistema é construído a partir do prompt base do OpenClaw, prompt de Skills, contexto de bootstrap e substituições por execução.
• Limites específicos do modelo e tokens de reserva para compactação são aplicados.
• Veja System prompt para o que o modelo vê.

​

Pontos de hook (onde você pode interceptar)

O OpenClaw possui dois sistemas de hooks:

• Hooks internos (hooks do Gateway): scripts orientados a eventos para comandos e eventos de ciclo de vida.
• Hooks de plugin: pontos de extensão dentro do ciclo de vida do agente/ferramenta e do pipeline do gateway.

​

Hooks internos (hooks do Gateway)

• agent:bootstrap: executa durante a construção dos arquivos de bootstrap antes do prompt do sistema ser finalizado. Use isso para adicionar/remover arquivos de contexto de bootstrap.
• Hooks de comando: /new, /reset, /stop e outros eventos de comando (veja o doc de Hooks).

Veja Hooks para configuração e exemplos.

​

Hooks de plugin (ciclo de vida do agente + gateway)

Eles executam dentro do agent loop ou do pipeline do gateway:

• before_agent_start: injeta contexto ou sobrescreve o prompt do sistema antes do início da execução.
• agent_end: inspeciona a lista final de mensagens e metadados da execução após a conclusão.
• before_compaction / after_compaction: observa ou anota ciclos de compactação.
• before_tool_call / after_tool_call: intercepta parâmetros/resultados de ferramentas.
• tool_result_persist: transforma sincronicamente resultados de ferramentas antes de serem gravados no transcript da sessão.
• message_received / message_sending / message_sent: hooks de mensagens de entrada + saída.
• session_start / session_end: limites do ciclo de vida da sessão.
• gateway_start / gateway_stop: eventos do ciclo de vida do gateway.

Veja Plugins para a API de hooks e detalhes de registro.

​

Streaming + respostas parciais

• Deltas do assistente são transmitidos a partir do pi-agent-core e emitidos como eventos assistant.
• O streaming em blocos pode emitir respostas parciais em text_end ou message_end.
• O streaming de raciocínio pode ser emitido como um stream separado ou como respostas em bloco.
• Veja Streaming para comportamento de fragmentação e respostas em bloco.

​

Execução de ferramentas + ferramentas de mensagens

• Eventos de início/atualização/fim de ferramentas são emitidos no stream tool.
• Resultados de ferramentas são sanitizados quanto a tamanho e payloads de imagem antes de registrar/emitir.
• Envios por ferramentas de mensagens são rastreados para suprimir confirmações duplicadas do assistente.

​

Modelagem de resposta + supressão

• Payloads finais são montados a partir de:
  • texto do assistente (e raciocínio opcional)
  • resumos inline de ferramentas (quando verbose + permitido)
  • texto de erro do assistente quando o modelo falha
• NO_REPLY é tratado como um token silencioso e filtrado dos payloads de saída.
• Duplicatas de ferramentas de mensagens são removidas da lista final de payloads.
• Se nenhum payload renderizável permanecer e uma ferramenta falhar, uma resposta de erro de ferramenta de fallback é emitida (a menos que uma ferramenta de mensagens já tenha enviado uma resposta visível ao usuário).

​

Compactação + tentativas

• A compactação automática emite eventos de stream compaction e pode disparar uma nova tentativa.
• Na nova tentativa, buffers em memória e resumos de ferramentas são redefinidos para evitar saída duplicada.
• Veja Compaction para o pipeline de compactação.

​

Streams de eventos (hoje)

• lifecycle: emitido por subscribeEmbeddedPiSession (e como fallback por agentCommand)
• assistant: deltas transmitidos do pi-agent-core
• tool: eventos de ferramentas transmitidos do pi-agent-core

​

Tratamento de canais de chat

• Deltas do assistente são armazenados em mensagens de chat delta.
• Uma mensagem de chat final é emitida em lifecycle end/error.

​

Tempos limite

• Padrão de agent.wait: 30s (apenas a espera). O parâmetro timeoutMs substitui.
• Runtime do agente: padrão de agents.defaults.timeoutSeconds 600s; imposto no temporizador de aborto runEmbeddedPiAgent.

​

Onde as coisas podem terminar cedo

• Timeout do agente (aborto)
• AbortSignal (cancelamento)
• Desconexão do Gateway ou timeout de RPC
• Timeout de agent.wait (apenas espera, não interrompe o agente)