Loop do agente

O loop do agente é a execução serializada por sessão que transforma uma mensagem em ações e uma resposta: recebimento, montagem do contexto, inferência do modelo, execução de ferramentas, streaming e persistência.

​

Pontos de entrada

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

​

Sequência de execução

1. O RPC agent valida os parâmetros, resolve a sessão (sessionKey/sessionId), persiste os metadados da sessão e retorna { runId, acceptedAt } imediatamente.
2. agentCommand executa o turno: resolve o modelo e os padrões de thinking/verbose/trace, carrega o snapshot de Skills, chama runEmbeddedAgent e emite um fim/erro de ciclo de vida de contingência se o loop incorporado ainda não tiver emitido um.
3. runEmbeddedAgent: serializa as execuções por meio de filas por sessão e globais, resolve o modelo e o perfil de autenticação, cria a sessão do OpenClaw, assina eventos de runtime, transmite deltas do assistente/das ferramentas, aplica o tempo limite da execução (interrompendo-a quando expira) e retorna payloads junto com metadados de uso. Para turnos do app-server do Codex, também interrompe um turno aceito que deixa de produzir progresso no app-server antes de um evento terminal.
4. subscribeEmbeddedAgentSession conecta eventos de runtime ao fluxo agent: eventos de ferramentas para stream: "tool", deltas do assistente para stream: "assistant" e eventos de ciclo de vida para stream: "lifecycle" (phase: "start" | "end" | "error").
5. agent.wait (waitForAgentRun) aguarda o fim/erro do ciclo de vida de um runId e retorna { status: ok|error|timeout, startedAt, endedAt, error? }.

​

Enfileiramento e concorrência

As execuções são serializadas por chave de sessão (faixa da sessão) e, opcionalmente, por uma faixa global, evitando condições de corrida entre ferramentas e sessões. Os canais de mensagens escolhem um modo de fila (steer/followup/collect/interrupt) que alimenta esse sistema de faixas; consulte Fila de comandos. As gravações da transcrição também são protegidas por um bloqueio de gravação da sessão no arquivo da sessão. O bloqueio reconhece processos e é baseado em arquivo, portanto detecta gravadores que contornam a fila dentro do processo ou que vêm de outro processo. Os gravadores aguardam até session.writeLock.acquireTimeoutMs (padrão de 60000 ms; substituição pela variável de ambiente OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS) antes de informar que a sessão está ocupada. Por padrão, os bloqueios de gravação de sessão não são reentrantes. Um auxiliar que aninha intencionalmente a aquisição do mesmo bloqueio, preservando um único gravador lógico, deve habilitar allowReentrant: true.

​

Preparação da sessão e do espaço de trabalho

• O espaço de trabalho é resolvido e criado; execuções em sandbox podem ser redirecionadas para a raiz de um espaço de trabalho de sandbox.
• As Skills são carregadas (ou reutilizadas de um snapshot) e injetadas no ambiente e no prompt.
• Os arquivos de inicialização/contexto são resolvidos e injetados no prompt do sistema.
• Um bloqueio de gravação da sessão é adquirido, e o destino da transcrição da sessão é preparado antes do início do streaming. Qualquer caminho posterior de regravação, Compaction ou truncamento da transcrição deve adquirir o mesmo bloqueio antes de modificar as linhas da transcrição no SQLite.

​

Montagem do prompt

O prompt do sistema é criado com base no prompt-base do OpenClaw, no prompt de Skills, no contexto de inicialização e nas substituições por execução. Os limites específicos do modelo e os tokens reservados para Compaction são aplicados. Consulte Prompt do sistema para saber o que o modelo recebe.

​

Hooks

O OpenClaw tem 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/das ferramentas e do pipeline do Gateway.

​

Hooks internos (hooks do Gateway)

• agent:bootstrap: é executado durante a criação dos arquivos de inicialização, antes da finalização do prompt do sistema. Use-o para adicionar ou remover arquivos de contexto de inicialização.
• Hooks de comando: /new, /reset, /stop e outros eventos de comando (consulte a documentação de Hooks).

Consulte Hooks para ver a configuração e exemplos.

​

Hooks de Plugin

Eles são executados dentro do loop do agente ou do pipeline do Gateway: Regras de decisão dos hooks para proteções de saída/ferramentas:

• before_tool_call: { block: true } é terminal e interrompe os manipuladores de menor prioridade. { block: false } não realiza nenhuma ação e não remove um bloqueio anterior.
• before_install: mesmas semânticas de terminal/nenhuma ação descritas acima. Use security.installPolicy, e não before_install, para decisões de permissão/bloqueio de instalação controladas pelo operador que precisem abranger os caminhos de instalação e atualização pela CLI.
• message_sending: { cancel: true } é terminal e interrompe os manipuladores de menor prioridade. { cancel: false } não realiza nenhuma ação e não remove um cancelamento anterior.

Consulte Hooks de Plugin para ver a API de hooks e os detalhes de registro. Os harnesses podem adaptar esses hooks. O harness do app-server do Codex mantém os hooks de Plugin do OpenClaw como o contrato de compatibilidade para as superfícies espelhadas documentadas; os hooks nativos do Codex são um mecanismo separado do Codex, de nível mais baixo.

​

Streaming

• Os deltas do assistente são transmitidos pelo runtime do agente como eventos assistant.
• O streaming em blocos pode emitir respostas parciais em text_end ou message_end.
• O streaming de raciocínio pode ser um fluxo separado ou bloquear respostas.
• Consulte Streaming para saber mais sobre a divisão em partes e o comportamento das respostas em blocos.

​

Execução de ferramentas

• Os eventos de início/atualização/fim de ferramentas são emitidos no fluxo tool.
• Os resultados das ferramentas são higienizados quanto ao tamanho e aos payloads de imagens antes do registro/emissão.
• Os envios por ferramentas de mensagens são rastreados para suprimir confirmações duplicadas do assistente.

​

Formatação da resposta

Os payloads finais são montados com o texto do assistente (mais o raciocínio opcional), resumos inline das ferramentas (quando o modo detalhado está habilitado e é permitido) e o texto de erro do assistente quando ocorre um erro no modelo.

• O token silencioso exato NO_REPLY é filtrado dos payloads de saída.
• As duplicatas das ferramentas de mensagens são removidas da lista final de payloads.
• Se nenhum payload renderizável permanecer e uma ferramenta tiver apresentado erro, uma resposta de erro de ferramenta de contingência será emitida, a menos que uma ferramenta de mensagens já tenha enviado uma resposta visível ao usuário.

​

Compaction e novas tentativas

A Compaction automática emite eventos de fluxo compaction e pode acionar uma nova tentativa. Na nova tentativa, os buffers em memória e os resumos de ferramentas são redefinidos para evitar saída duplicada. Consulte Compaction.

​

Fluxos de eventos

• lifecycle: emitido por subscribeEmbeddedAgentSession (e, como contingência, por agentCommand).
• assistant: deltas transmitidos pelo runtime do agente.
• tool: eventos de ferramentas transmitidos pelo runtime do agente.

O Gateway projeta eventos de ciclo de vida e de início/terminal de ferramentas no livro-razão de auditoria limitado, que contém somente metadados. Essa projeção registra a proveniência e os códigos de resultado sem copiar prompts, mensagens, argumentos de ferramentas, resultados de ferramentas ou erros brutos para fora do caminho da transcrição/runtime.

​

Tratamento de canais de chat

Os deltas do assistente são armazenados em buffer nas mensagens delta do chat. Uma mensagem final do chat é emitida no fim/erro do ciclo de vida.

​

Tempos limite

​

Diagnóstico de sessões travadas

Com o diagnóstico ativado, diagnostics.stuckSessionWarnMs (padrão: 120000 ms) classifica sessões longas em processing sem resposta, ferramenta, status, bloqueio ou progresso de ACP observado:

• Execuções incorporadas, chamadas de modelo e chamadas de ferramenta ativas são relatadas como session.long_running. Chamadas silenciosas de modelo com proprietário permanecem como session.long_running até diagnostics.stuckSessionAbortMs, para que provedores lentos ou sem streaming não sejam sinalizados como paralisados cedo demais.
• Trabalho ativo sem progresso recente é relatado como session.stalled. Chamadas de modelo com proprietário mudam para session.stalled ao atingir ou ultrapassar o limite de cancelamento; atividade obsoleta de modelo/ferramenta sem proprietário não fica oculta como execução longa.
• session.stuck é reservado para registros obsoletos e recuperáveis de sessão, incluindo sessões ociosas na fila com atividade obsoleta de modelo/ferramenta sem proprietário.

O padrão de diagnostics.stuckSessionAbortMs é de pelo menos 5 minutos e 3 vezes o limite de aviso. Registros obsoletos de sessão liberam a fila da sessão afetada imediatamente após a aprovação das verificações de recuperação; execuções incorporadas paralisadas são canceladas e drenadas somente após o limite de cancelamento, para que o trabalho na fila seja retomado sem interromper execuções meramente lentas. A recuperação emite resultados estruturados de solicitação/conclusão; o estado de diagnóstico é marcado como ocioso somente se a mesma geração de processamento ainda for a atual, e diagnósticos repetidos de session.stuck aumentam progressivamente o intervalo enquanto a sessão permanece inalterada.

​

Onde as operações podem terminar antecipadamente

• Tempo limite do agente (cancelamento)
• AbortSignal (cancelamento)
• Desconexão do Gateway ou tempo limite de RPC
• Tempo limite de agent.wait (apenas aguarda, não interrompe o agente)

​

Relacionado

• Ferramentas - ferramentas disponíveis para o agente
• Hooks - scripts orientados a eventos acionados por eventos do ciclo de vida do agente
• Compaction - como conversas longas são resumidas
• Aprovações de execução - controles de aprovação para comandos do shell
• Raciocínio - configuração do nível de raciocínio/pensamento