Gateway no macOS

OpenClaw.app não inclui o Node nem o runtime do Gateway. O aplicativo para macOS espera uma instalação externa da CLI openclaw, não inicia o Gateway como um processo filho e gerencia um serviço launchd por usuário para manter o Gateway em execução (ou se conecta a um Gateway local que já esteja em execução).

Configuração automática

Em um Mac novo, escolha Este Mac durante a integração inicial. O aplicativo executa seu script de instalação assinado e incluído antes do assistente do Gateway: ele instala um runtime do Node no espaço do usuário e a CLI openclaw correspondente em ~/.openclaw, depois instala e inicia o serviço launchd por usuário. Esse processo não exige Terminal, Homebrew nem acesso de administrador.

O aplicativo inclui apenas o script de instalação, não o payload do Node ou do Gateway; a configuração exige conexão com a internet para baixar o runtime e o pacote OpenClaw correspondente.

Recuperação manual

O Node 24.15+ é recomendado para uma instalação manual; o Node 22.22.3+ também funciona. Instale openclaw globalmente:

npm install -g openclaw@<version>

Use Tentar configurar novamente após uma falha na configuração automática. Se isso ainda falhar, instale a CLI manualmente com o comando acima e escolha Verificar novamente na integração inicial.

Launchd (Gateway como LaunchAgent)

Rótulo: ai.openclaw.gateway (perfil padrão) ou ai.openclaw.<profile> para um perfil nomeado.

Local do plist (por usuário): ~/Library/LaunchAgents/ai.openclaw.gateway.plist (ou ai.openclaw.<profile>.plist).

O aplicativo para macOS gerencia a instalação/atualização do LaunchAgent para o perfil padrão no modo Local. A CLI também pode instalá-lo diretamente: openclaw gateway install (os perfis nomeados são selecionados pela variável de ambiente OPENCLAW_PROFILE).

Comportamento:

• "OpenClaw ativo" ativa/desativa o LaunchAgent.
• Encerrar o aplicativo não interrompe o Gateway (o launchd o mantém em execução).
• Se um Gateway já estiver em execução na porta configurada, o aplicativo se conecta a ele em vez de iniciar um novo.

Registro:

• stdout do launchd: ~/Library/Logs/openclaw/gateway.log (os perfis usam gateway-<profile>.log)
• stderr do launchd: suprimido
• Se o host entrar em um ciclo com EADDRINUSE repetidos ou reinicializações rápidas, verifique se há LaunchAgents ai.openclaw.gateway / ai.openclaw.node duplicados e a solução alternativa do marcador do launchd em Solução de problemas do Gateway.

Compatibilidade de versões

O aplicativo para macOS verifica a versão do Gateway em relação à sua própria versão. A integração inicial executa automaticamente a configuração gerenciada quando uma CLI existente está ausente ou é incompatível. Use Tentar configurar novamente para repetir a instalação ou Verificar novamente após reparar uma CLI externa.

Diretório de estado no macOS

Mantenha o estado do OpenClaw em um disco local não sincronizado. Evite o iCloud Drive e outras pastas sincronizadas com a nuvem; a latência de sincronização e os bloqueios de arquivos podem afetar sessões, credenciais e o estado do Gateway.

Defina OPENCLAW_STATE_DIR como um caminho local somente quando precisar de uma substituição. openclaw doctor alerta sobre caminhos comuns de estado sincronizados com a nuvem e recomenda mover o estado de volta para o armazenamento local. Consulte variáveis de ambiente e Doctor.

Depurar a conectividade do aplicativo

Use a CLI de depuração do macOS a partir de um checkout do código-fonte para exercitar a mesma lógica de handshake e descoberta do WebSocket do Gateway usada pelo aplicativo:

cd apps/macosswift run openclaw-mac connect --jsonswift run openclaw-mac discover --timeout 3000 --json

connect aceita --url, --token, --timeout, --probe e --json (além de substituições da identidade do cliente; execute com --help para obter a lista completa). discover aceita --timeout, --json e --include-local. Compare a saída da descoberta com openclaw gateway discover --json quando precisar separar a descoberta da CLI dos problemas de conexão do aplicativo.

Verificação rápida

openclaw --version OPENCLAW_SKIP_CHANNELS=1 \OPENCLAW_SKIP_CANVAS_HOST=1 \openclaw gateway --port 18999 --bind loopback

Em seguida:

openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000

Relacionados

• aplicativo para macOS
• Guia operacional do Gateway