​

Presença

A “presença” do OpenClaw é uma visão leve e de melhor esforço de:

• o próprio Gateway, e
• clientes conectados ao Gateway (app para macOS, WebChat, CLI, etc.)

A presença é usada principalmente para renderizar a aba Instances do app para macOS e para fornecer visibilidade rápida ao operador.

​

Campos de presença (o que aparece)

As entradas de presença são objetos estruturados com campos como:

• instanceId (opcional, mas fortemente recomendado): identidade estável do cliente (geralmente connect.client.instanceId)
• host: nome do host amigável
• ip: endereço IP de melhor esforço
• version: string de versão do cliente
• deviceFamily / modelIdentifier: indícios de hardware
• mode: ui, webchat, cli, backend, probe, test, node, …
• lastInputSeconds: “segundos desde a última entrada do usuário” (se conhecido)
• reason: self, connect, node-connected, periodic, …
• ts: carimbo de data/hora da última atualização (ms desde a época)

​

Produtores (de onde a presença vem)

As entradas de presença são produzidas por várias fontes e mescladas.

​

1. Entrada do próprio Gateway

O Gateway sempre inicializa uma entrada “self” na inicialização para que as UIs mostrem o host do gateway mesmo antes de qualquer cliente se conectar.

​

2. Conexão WebSocket

Todo cliente WS começa com uma solicitação connect. Em um handshake bem-sucedido, o Gateway faz um upsert de uma entrada de presença para essa conexão.

​

Por que comandos pontuais da CLI não aparecem

A CLI frequentemente se conecta para comandos curtos e pontuais. Para evitar poluir a lista de Instances, client.mode === "cli" não é transformado em uma entrada de presença.

​

3. Beacons system-event

Os clientes podem enviar beacons periódicos mais ricos por meio do método system-event. O app para macOS usa isso para relatar nome do host, IP e lastInputSeconds.

​

4. Conexões de node (papel: node)

Quando um node se conecta pelo WebSocket do Gateway com role: node, o Gateway faz um upsert de uma entrada de presença para esse node (mesmo fluxo de outros clientes WS).

​

Regras de mesclagem + deduplicação (por que instanceId importa)

As entradas de presença são armazenadas em um único mapa em memória:

• As entradas são indexadas por uma chave de presença.
• A melhor chave é um instanceId estável (de connect.client.instanceId) que sobrevive a reinicializações.
• As chaves não diferenciam maiúsculas de minúsculas.

Se um cliente se reconectar sem um instanceId estável, ele pode aparecer como uma linha duplicada.

​

TTL e tamanho limitado

A presença é intencionalmente efêmera:

• TTL: entradas com mais de 5 minutos são removidas
• Máx. de entradas: 200 (as mais antigas são descartadas primeiro)

Isso mantém a lista atualizada e evita crescimento de memória sem limites.

​

Observação sobre remoto/túnel (IPs de loopback)

Quando um cliente se conecta por um túnel SSH / encaminhamento de porta local, o Gateway pode ver o endereço remoto como 127.0.0.1. Para evitar sobrescrever um IP informado corretamente pelo cliente, endereços remotos de loopback são ignorados.

​

Consumidores

​

Aba Instances do macOS

O app para macOS renderiza a saída de system-presence e aplica um pequeno indicador de status (Ativo/Ocioso/Obsoleto) com base na idade da última atualização.

​

Dicas de depuração

• Para ver a lista bruta, chame system-presence no Gateway.
• Se você vir duplicatas:
  • confirme que os clientes enviam um client.instanceId estável no handshake
  • confirme que os beacons periódicos usam o mesmo instanceId
  • verifique se a entrada derivada da conexão está sem instanceId (duplicatas são esperadas)