Implantação no Fly.io

Objetivo: Gateway OpenClaw em execução em uma máquina do Fly.io com armazenamento persistente, HTTPS automático e acesso a Discord/canais.

O que você precisa

CLI flyctl instalada
Conta do Fly.io (o nível gratuito funciona)
Autenticação de modelo: chave de API do provedor de modelo escolhido
Credenciais de canal: token de bot do Discord, token do Telegram etc.

Caminho rápido para iniciantes

Clone o repositório → personalize fly.toml
Crie app + volume → defina segredos
Implante com fly deploy
Entre por SSH para criar a configuração ou use a interface de Control

Crie o app no Fly

# Clone the repo
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Create a new Fly app (pick your own name)
fly apps create my-openclaw

# Create a persistent volume (1GB is usually enough)
fly volumes create openclaw_data --size 1 --region iad

Dica: escolha uma região perto de você. Opções comuns: lhr (Londres), iad (Virgínia), sjc (San Jose).

Configure o fly.toml

Edite fly.toml para corresponder ao nome do seu app e aos seus requisitos.Observação de segurança: a configuração padrão expõe uma URL pública. Para uma implantação reforçada sem IP público, consulte Implantação privada ou use fly.private.toml.

app = "my-openclaw"  # Your app name
primary_region = "iad"

[build]
  dockerfile = "Dockerfile"

[env]
  NODE_ENV = "production"
  OPENCLAW_PREFER_PNPM = "1"
  OPENCLAW_STATE_DIR = "/data"
  NODE_OPTIONS = "--max-old-space-size=1536"

[processes]
  app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = false
  auto_start_machines = true
  min_machines_running = 1
  processes = ["app"]

[[vm]]
  size = "shared-cpu-2x"
  memory = "2048mb"

[mounts]
  source = "openclaw_data"
  destination = "/data"

Principais definições:

Setting	Why
`--bind lan`	Faz bind em `0.0.0.0` para que o proxy do Fly possa alcançar o gateway
`--allow-unconfigured`	Inicia sem um arquivo de configuração (você criará um depois)
`internal_port = 3000`	Deve corresponder a `--port 3000` (ou `OPENCLAW_GATEWAY_PORT`) para as verificações de integridade do Fly
`memory = "2048mb"`	512MB é pouco; 2GB é recomendado
`OPENCLAW_STATE_DIR = "/data"`	Persiste o estado no volume

Defina os segredos

# Required: Gateway token (for non-loopback binding)
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

# Model provider API keys
fly secrets set ANTHROPIC_API_KEY=sk-ant-...

# Optional: Other providers
fly secrets set OPENAI_API_KEY=sk-...
fly secrets set GOOGLE_API_KEY=...

# Channel tokens
fly secrets set DISCORD_BOT_TOKEN=MTQ...

Observações:

Binds sem loopback (--bind lan) exigem um caminho válido de autenticação do gateway. Este exemplo do Fly.io usa OPENCLAW_GATEWAY_TOKEN, mas gateway.auth.password ou uma implantação trusted-proxy sem loopback configurada corretamente também satisfazem esse requisito.
Trate esses tokens como senhas.
Prefira variáveis de ambiente em vez de arquivo de configuração para todas as chaves de API e tokens. Isso mantém segredos fora de openclaw.json, onde poderiam ser expostos ou registrados acidentalmente.

Implante

fly deploy

A primeira implantação compila a imagem Docker (~2-3 minutos). As implantações seguintes são mais rápidas.Após a implantação, verifique:

fly status
fly logs

Você deverá ver:

[gateway] listening on ws://0.0.0.0:3000 (PID xxx)
[discord] logged in to discord as xxx

Crie o arquivo de configuração

Entre na máquina por SSH para criar uma configuração adequada:

fly ssh console

Crie o diretório e o arquivo de configuração:

mkdir -p /data
cat > /data/openclaw.json << 'EOF'
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-6",
        "fallbacks": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.4"]
      },
      "maxConcurrent": 4
    },
    "list": [
      {
        "id": "main",
        "default": true
      }
    ]
  },
  "auth": {
    "profiles": {
      "anthropic:default": { "mode": "token", "provider": "anthropic" },
      "openai:default": { "mode": "token", "provider": "openai" }
    }
  },
  "bindings": [
    {
      "agentId": "main",
      "match": { "channel": "discord" }
    }
  ],
  "channels": {
    "discord": {
      "enabled": true,
      "groupPolicy": "allowlist",
      "guilds": {
        "YOUR_GUILD_ID": {
          "channels": { "general": { "allow": true } },
          "requireMention": false
        }
      }
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "auto"
  },
  "meta": {}
}
EOF

Observação: com OPENCLAW_STATE_DIR=/data, o caminho de configuração é /data/openclaw.json.Observação: o token do Discord pode vir de:

Variável de ambiente: DISCORD_BOT_TOKEN (recomendado para segredos)
Arquivo de configuração: channels.discord.token

Se usar variável de ambiente, não é necessário adicionar o token à configuração. O gateway lê DISCORD_BOT_TOKEN automaticamente.Reinicie para aplicar:

exit
fly machine restart <machine-id>

Acesse o Gateway

Interface de Control

Abra no navegador:

fly open

Ou visite https://my-openclaw.fly.dev/Autentique-se com o segredo compartilhado configurado. Este guia usa o token do gateway de OPENCLAW_GATEWAY_TOKEN; se você mudou para autenticação por senha, use essa senha.

Logs

fly logs              # Logs ao vivo
fly logs --no-tail    # Logs recentes

Console SSH

fly ssh console

Solução de problemas

”App is not listening on expected address”

O gateway está fazendo bind em 127.0.0.1 em vez de 0.0.0.0. Correção: adicione --bind lan ao comando do processo no seu fly.toml.

Verificações de integridade falhando / conexão recusada

O Fly não consegue alcançar o gateway na porta configurada. Correção: verifique se internal_port corresponde à porta do gateway (defina --port 3000 ou OPENCLAW_GATEWAY_PORT=3000).

OOM / problemas de memória

O contêiner continua reiniciando ou sendo encerrado. Sinais: SIGABRT, v8::internal::Runtime_AllocateInYoungGeneration ou reinicializações silenciosas. Correção: aumente a memória em fly.toml:

[[vm]]
  memory = "2048mb"

Ou atualize uma máquina existente:

fly machine update <machine-id> --vm-memory 2048 -y

Observação: 512MB é pouco. 1GB pode funcionar, mas pode causar OOM sob carga ou com logging detalhado. 2GB é recomendado.

Problemas de lock do Gateway

O gateway se recusa a iniciar com erros de “already running”. Isso acontece quando o contêiner reinicia, mas o arquivo de lock de PID persiste no volume. Correção: exclua o arquivo de lock:

fly ssh console --command "rm -f /data/gateway.*.lock"
fly machine restart <machine-id>

O arquivo de lock fica em /data/gateway.*.lock (não em um subdiretório).

A configuração não está sendo lida

--allow-unconfigured apenas ignora a proteção de inicialização. Ele não cria nem repara /data/openclaw.json, então verifique se sua configuração real existe e inclui gateway.mode="local" quando você quiser uma inicialização local normal do gateway. Verifique se a configuração existe:

fly ssh console --command "cat /data/openclaw.json"

Gravando configuração via SSH

O comando fly ssh console -C não oferece suporte a redirecionamento de shell. Para gravar um arquivo de configuração:

# Use echo + tee (pipe do local para o remoto)
echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json"

# Or use sftp
fly sftp shell
> put /local/path/config.json /data/openclaw.json

Observação: fly sftp pode falhar se o arquivo já existir. Exclua-o antes:

fly ssh console --command "rm /data/openclaw.json"

O estado não persiste

Se você perder perfis de autenticação, estado de canal/provedor ou sessões após uma reinicialização, o diretório de estado está gravando no sistema de arquivos do contêiner. Correção: verifique se OPENCLAW_STATE_DIR=/data está definido em fly.toml e implante novamente.

Atualizações

# Pull latest changes
git pull

# Redeploy
fly deploy

# Check health
fly status
fly logs

Atualizando o comando da máquina

Se você precisar alterar o comando de inicialização sem uma reimplantação completa:

# Get machine ID
fly machines list

# Update command
fly machine update <machine-id> --command "node dist/index.js gateway --port 3000 --bind lan" -y

# Or with memory increase
fly machine update <machine-id> --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y

Observação: após fly deploy, o comando da máquina pode voltar ao que está em fly.toml. Se você fez alterações manuais, reaplique-as após a implantação.

Implantação privada (reforçada)

Por padrão, o Fly aloca IPs públicos, tornando seu gateway acessível em https://your-app.fly.dev. Isso é conveniente, mas significa que sua implantação pode ser descoberta por scanners da internet (Shodan, Censys etc.). Para uma implantação reforçada sem exposição pública, use o modelo privado.

Quando usar implantação privada

Você só faz chamadas/mensagens de saída (sem webhooks de entrada)
Você usa túneis ngrok ou Tailscale para qualquer callback de webhook
Você acessa o gateway via SSH, proxy ou WireGuard em vez do navegador
Você quer que a implantação fique oculta de scanners da internet

Configuração

Use fly.private.toml em vez da configuração padrão:

# Deploy with private config
fly deploy -c fly.private.toml

Ou converta uma implantação existente:

# List current IPs
fly ips list -a my-openclaw

# Release public IPs
fly ips release <public-ipv4> -a my-openclaw
fly ips release <public-ipv6> -a my-openclaw

# Switch to private config so future deploys don't re-allocate public IPs
# (remove [http_service] or deploy with the private template)
fly deploy -c fly.private.toml

# Allocate private-only IPv6
fly ips allocate-v6 --private -a my-openclaw

Depois disso, fly ips list deverá mostrar apenas um IP do tipo private:

VERSION  IP                   TYPE             REGION
v6       fdaa:x:x:x:x::x      private          global

Acessando uma implantação privada

Como não há URL pública, use um destes métodos: Opção 1: proxy local (mais simples)

# Forward local port 3000 to the app
fly proxy 3000:3000 -a my-openclaw

# Then open http://localhost:3000 in browser

Opção 2: VPN WireGuard

# Create WireGuard config (one-time)
fly wireguard create

# Import to WireGuard client, then access via internal IPv6
# Example: http://[fdaa:x:x:x:x::x]:3000

Opção 3: somente SSH

fly ssh console -a my-openclaw

Webhooks com implantação privada

Se você precisar de callbacks de webhook (Twilio, Telnyx etc.) sem exposição pública:

Túnel ngrok - execute o ngrok dentro do contêiner ou como sidecar
Tailscale Funnel - exponha caminhos específicos via Tailscale
Somente saída - alguns provedores (Twilio) funcionam bem para chamadas de saída sem webhooks

Exemplo de configuração de chamada de voz com ngrok:

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio",
          tunnel: { provider: "ngrok" },
          webhookSecurity: {
            allowedHosts: ["example.ngrok.app"],
          },
        },
      },
    },
  },
}

O túnel ngrok é executado dentro do contêiner e fornece uma URL pública de webhook sem expor o próprio app do Fly. Defina webhookSecurity.allowedHosts para o nome de host do túnel público para que cabeçalhos de host encaminhados sejam aceitos.

Benefícios de segurança

Aspect	Público	Privado
Scanners da internet	Detectável	Oculto
Ataques diretos	Possíveis	Bloqueados
Acesso à interface de Control	Navegador	Proxy/VPN
Entrega de webhook	Direta	Via túnel

Observações

O Fly.io usa arquitetura x86 (não ARM)
O Dockerfile é compatível com ambas as arquiteturas
Para onboarding de WhatsApp/Telegram, use fly ssh console
Os dados persistentes ficam no volume em /data
O Signal exige Java + signal-cli; use uma imagem personalizada e mantenha a memória em 2GB+.

Custo

Com a configuração recomendada (shared-cpu-2x, 2GB RAM):

~US$10-15/mês dependendo do uso
O nível gratuito inclui alguma franquia

Consulte preços do Fly.io para detalhes.

Próximos passos

Configure canais de mensagens: Canais
Configure o Gateway: Configuração do gateway
Mantenha o OpenClaw atualizado: Atualização

Install overview

Containers

Hosting

Maintenance

Fly.io

Implantação no Fly.io

O que você precisa

Caminho rápido para iniciantes

Interface de Control

Logs

Console SSH

Solução de problemas

”App is not listening on expected address”

Verificações de integridade falhando / conexão recusada

OOM / problemas de memória

Problemas de lock do Gateway

A configuração não está sendo lida

Gravando configuração via SSH

O estado não persiste

Atualizações

Atualizando o comando da máquina

Implantação privada (reforçada)

Quando usar implantação privada

Configuração

Acessando uma implantação privada

Webhooks com implantação privada

Benefícios de segurança

Observações

Custo

Próximos passos

Install overview

Containers

Hosting

Maintenance

​Implantação no Fly.io

​O que você precisa

​Caminho rápido para iniciantes

​Interface de Control

​Logs

​Console SSH

​Solução de problemas

​”App is not listening on expected address”

​Verificações de integridade falhando / conexão recusada

​OOM / problemas de memória

​Problemas de lock do Gateway

​A configuração não está sendo lida

​Gravando configuração via SSH

​O estado não persiste

​Atualizações

​Atualizando o comando da máquina

​Implantação privada (reforçada)

​Quando usar implantação privada

​Configuração

​Acessando uma implantação privada

​Webhooks com implantação privada

​Benefícios de segurança

​Observações

​Custo

​Próximos passos

Implantação no Fly.io

O que você precisa

Caminho rápido para iniciantes

Interface de Control

Logs

Console SSH

Solução de problemas

”App is not listening on expected address”

Verificações de integridade falhando / conexão recusada

OOM / problemas de memória

Problemas de lock do Gateway

A configuração não está sendo lida

Gravando configuração via SSH

O estado não persiste

Atualizações

Atualizando o comando da máquina

Implantação privada (reforçada)

Quando usar implantação privada

Configuração

Acessando uma implantação privada

Webhooks com implantação privada

Benefícios de segurança

Observações

Custo

Próximos passos