O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Como implantar o OpenClaw em instâncias do Cloud Run

1. Introdução

Visão geral

Neste laboratório, você vai implantar uma instância totalmente persistente e segura do OpenClaw, uma estrutura de agente de IA de código aberto, nas instâncias do Cloud Run. Você vai interagir diretamente com seu agente de IA usando a interface da Web integrada do OpenClaw (com a opção de conectar canais de mensagens como Telegram ou WhatsApp), fazer backup do espaço de trabalho inicial com o Google Cloud Storage e gerenciar as credenciais da API com segurança usando o Google Cloud Secret Manager.

Antes de começar, consulte a documentação do OpenClaw para se familiarizar com a arquitetura, as ferramentas e os fluxos de trabalho do agente do OpenClaw.

Atividades deste laboratório

Ative as APIs necessárias do Google Cloud e crie uma conta de serviço dedicada com as permissões necessárias do IAM.
Armazene chaves de API e senhas de gateway com segurança no Secret Manager.
Prepare um arquivo de configuração openclaw.json com as configurações do modelo do Gemini e a interface do gateway ativada.
Prepare um bucket do Cloud Storage para manter o estado do contêiner.
Implante o OpenClaw usando gcloud beta run instances deploy.
Interaja diretamente com seu agente de IA OpenClaw usando a interface da Web integrada.
(Opcional) Configure um canal de mensagens (Telegram ou WhatsApp).
(Opcional) Amplie os recursos do seu agente adicionando habilidades personalizadas ao Cloud Storage.

O que você vai aprender

Como implantar o OpenClaw em instâncias do Cloud Run com a interface da Web de controle integrada.
Como ativar buckets do Cloud Storage em instâncias do Cloud Run.
Como injetar secrets do Secret Manager com segurança como variáveis de ambiente no Cloud Run.
Como executar cargas de trabalho de agentes persistentes e de longa duração em instâncias do Cloud Run.
Como configurar e fazer upload de habilidades do agente personalizadas no Cloud Storage.

2. Configuração e requisitos

Configuração do projeto do GCP

Faça login no Console do Google Cloud.
Crie ou selecione um projeto do Google Cloud.
Confira se o faturamento está ativado para seu projeto do Google Cloud

Abrir o Cloud Shell

Ative o Google Cloud Shell na barra de ferramentas da parte de cima do console do Cloud.

Definir o projeto e instalar o gcloud beta

Primeiro, defina o projeto e a região como variáveis de ambiente.

export PROJECT_ID=<YOUR_PROJECT_ID>
export REGION=<YOUR_REGION>

Agora defina e confirme seu projeto.

gcloud config set project $PROJECT_ID
gcloud config get project

Verifique se o componente beta está instalado para gcloud beta run instances:

gcloud components install beta --quiet

e confira se o gcloud está atualizado.

gcloud components update

Ativar as APIs obrigatórias do Google Cloud

No Cloud Shell, ative as APIs Cloud Run, Secret Manager, Cloud Storage e Gemini:

gcloud services enable \
  run.googleapis.com \
  secretmanager.googleapis.com \
  storage.googleapis.com \
  generativelanguage.googleapis.com \
  compute.googleapis.com

3. (Opcional) Configurar integrações de mensagens (Telegram ou WhatsApp)

Você pode conectar o OpenClaw ao Telegram ou ao WhatsApp. Escolha a Opção A ou a Opção B abaixo.

Opção A: configuração do bot do Telegram

Abra o Telegram e pesquise @BotFather.
Envie o comando /newbot e siga as instruções para especificar um nome e um nome de usuário para o bot.
Copie o token da API HTTP gerado (por exemplo, 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
Pesquise @userinfobot no Telegram, envie /start e copie seu ID de usuário numérico (por exemplo, 8035936176).

Opção B: configuração do WhatsApp

Obtenha seu número de telefone pessoal do WhatsApp no formato internacional, sem espaços ou símbolos (por exemplo, +15551234567).
O OpenClaw se conecta pela política de lista de permissões do canal do WhatsApp.

4. Criar conta de serviço dedicada

Para seguir o princípio de privilégio mínimo, crie uma conta de serviço do IAM dedicada para o OpenClaw:

export SERVICE_ACCOUNT_NAME="openclaw-sa"
gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME} \
  --display-name="OpenClaw Service Account"

export SERVICE_ACCOUNT="${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

5. Armazenar credenciais no Secret Manager

Vamos armazenar credenciais de API sensíveis no Google Cloud Secret Manager para que o Cloud Run possa injetá-las com segurança no contêiner na hora da inicialização.

1. Receber e armazenar a chave da API Gemini

Acesse o Google AI Studio e faça login com sua Conta do Google.
Clique em Criar chave de API e selecione seu projeto do Google Cloud (${PROJECT_ID}).
Copie a chave de API gerada.

Armazene a chave de API no Secret Manager e conceda acesso à conta de serviço:

echo -n "YOUR_GEMINI_API_KEY" | gcloud secrets create gemini-api-key \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding gemini-api-key \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

2. Gerar e armazenar a senha do gateway

Para proteger sua instância do OpenClaw acessível ao público, gere uma senha aleatória segura e armazene-a no Secret Manager:

export OPENCLAW_GATEWAY_PASSWORD=$(openssl rand -hex 16)
echo "Generated Gateway Password: ${OPENCLAW_GATEWAY_PASSWORD}"

echo -n "${OPENCLAW_GATEWAY_PASSWORD}" | gcloud secrets create openclaw-gateway-password \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding openclaw-gateway-password \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

3. (Opcional) Criar um segredo de canal (Telegram ou WhatsApp)

Para o Telegram:

echo -n "YOUR_TELEGRAM_BOT_TOKEN" | gcloud secrets create telegram-bot-token \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding telegram-bot-token \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

Para o WhatsApp:

echo -n "YOUR_WHATSAPP_TOKEN_OR_KEY" | gcloud secrets create whatsapp-token \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding whatsapp-token \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

6. Preparar o bucket do Cloud Storage e a configuração openclaw.json

O OpenClaw exige um arquivo de configuração chamado openclaw.json em /home/node/.openclaw/openclaw.json.

Criar um bucket do Cloud Storage e conceder acesso:

export BUCKET_NAME="openclaw-state-${PROJECT_ID}"
gcloud storage buckets create gs://${BUCKET_NAME} --location=${REGION}

gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/storage.objectUser"

Criar openclaw.json: crie um arquivo chamado openclaw.json no Cloud Shell. Atualize a seção channels para corresponder ao canal escolhido (Telegram ou WhatsApp):

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "trustedProxies": ["0.0.0.0/0"],
    "bind": "lan",
    "auth": {
      "password": "${OPENCLAW_GATEWAY_PASSWORD}"
    },
    "controlUi": {
      "dangerouslyDisableDeviceAuth": true,
      "allowedOrigins": ["*"],
      "enabled": true
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "google/gemini-3.1-pro-preview"
      },
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "enabled": true,
          "dmPolicy": "allowlist",
          "allowFrom": [
            "YOUR_TELEGRAM_USER_ID"
          ]
        }
      }
    },
    "whatsapp": {
      "enabled": false,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "enabled": false,
          "dmPolicy": "allowlist",
          "allowFrom": [
            "+15551234567"
          ]
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "google": { "enabled": true },
      "telegram": { "enabled": true },
      "whatsapp": { "enabled": false }
    }
  }
}

Faça upload de openclaw.json para a raiz do bucket do Cloud Storage:
```
gcloud storage cp openclaw.json gs://${BUCKET_NAME}/openclaw.json
```
Verificar o layout do bucket do Cloud Storage:confirme se a estrutura do bucket contém openclaw.json na raiz:
```
gs://${BUCKET_NAME}/
└── openclaw.json
```

7. Implantar o OpenClaw em instâncias do Cloud Run

Implante o OpenClaw usando gcloud beta run instances deploy:

gcloud beta run instances deploy openclaw-instance \
  --image ghcr.io/openclaw/openclaw:2026.7.1 \
  --service-account ${SERVICE_ACCOUNT} \
  --port 18789 \
  --cpu 4 \
  --memory 4Gi \
  --public \
  --add-volume mount-path=/home/node/.openclaw,type=cloud-storage,mount-options="uid=1000;gid=1000;file-mode=0700;dir-mode=0700",bucket=${BUCKET_NAME} \
  --set-secrets GEMINI_API_KEY=gemini-api-key:latest,OPENCLAW_GATEWAY_PASSWORD=openclaw-gateway-password:latest \
  --region ${REGION}

Detalhamento do parâmetro principal:

--image ghcr.io/openclaw/openclaw:2026.7.1: imagem do contêiner OpenClaw (fixada em 2026.7.1, a versão estável mais recente da 1.x).
--service-account ...: anexa a conta de serviço openclaw-sa dedicada.
--add-volume ...: monta o bucket do Cloud Storage diretamente em /home/node/.openclaw. O uso de file-mode=0700;dir-mode=0700 garante as permissões adequadas para o OpenClaw.
--set-secrets ...: injeta credenciais diretamente do Secret Manager em variáveis de ambiente. (Opcional: se você configurou o Telegram nas etapas opcionais, adicione ,TELEGRAM_BOT_TOKEN=telegram-bot-token:latest a --set-secrets.)
--public: permite o acesso público ao URL.

8. Interagir diretamente pela interface da Web do OpenClaw

O OpenClaw inclui uma interface da Web de controle integrada que permite gerenciar e conversar com seu agente de IA diretamente no navegador:

Recupere o URL da instância do Cloud Run: no Cloud Shell, execute:

gcloud beta run instances describe openclaw-instance \
  --region ${REGION} \
  --format="value(status.urls[0])"

Acesse a interface de controle do OpenClaw:
- Abra o URL de saída no navegador da Web.
- Quando for solicitada a autenticação na interface de controle do OpenClaw:
  - Insira a senha do gateway gerada (${OPENCLAW_GATEWAY_PASSWORD}) do Secret Manager.
  - Se a caixa de diálogo de login mostrar campos separados de Nome de usuário e Senha, deixe o campo de nome de usuário em branco (ou digite admin) e forneça ${OPENCLAW_GATEWAY_PASSWORD} no campo de senha.
Comandar seu agente (instâncias em ação):
- Depois da autenticação, você vai acessar o painel de controle do OpenClaw.
- Teste o agente OpenClaw enviando um comando na interface do chat, como "Olá".
- Para testar o ciclo de vida de longa duração da instância do Cloud Run, peça ao agente OpenClaw para realizar uma tarefa mais sofisticada e de longa duração. Por exemplo, você pode pedir para ele acompanhar um feed de notícias ou o mercado de ações e gerar relatórios:
```
Track the USD-to-EUR exchange rate every 15 minutes for the next 24 hours, while also checking for any recent news updates in the US or the EU that may have an impact on the exchange rate. Generate an end-of-day report for me in this chat that tells me what you expect tomorrow's exchange rate will be.
```
- O agente vai realizar essa tarefa nas próximas 24 horas.

9. (Opcional) Verificar as integrações do canal de mensagens

Se você configurou o Telegram ou o WhatsApp nas etapas de configuração opcionais acima, verifique a entrega de mensagens:

Verifique os registros da instância no Cloud Shell:

gcloud run instances logs read openclaw-instance --region ${REGION} --limit 20

Abra o Telegram (ou WhatsApp) e envie uma mensagem (por exemplo, /start ou Hello OpenClaw!).
O bot vai autenticar seu ID de usuário na lista de permissão em openclaw.json e responder usando o Gemini.

10. Monitorar e inspecionar registros de instâncias

As instâncias do Cloud Run capturam stdout e stderr do contêiner e transmitem diretamente para o Google Cloud Logging. Use o Cloud Shell ou o console do Cloud para monitorar o tráfego do gateway e inspecionar as execuções de ferramentas do agente em tempo real.

1. Ler registros de instâncias recentes

Para buscar entradas de registro recentes da instância no Cloud Shell:

gcloud beta run instances logs read openclaw-instance \
  --region ${REGION} \
  --limit 50

2. Principais assinaturas de registros a serem observadas

Ao observar o agente em execução, procure os seguintes eventos principais de registro de tempo de execução:

[gateway] ready: confirma que o gateway HTTP e WebSocket do OpenClaw foi inicializado e está detectando na porta 18789.
[gateway] agent model: ...: mostra o modelo do Gemini ativo (por exemplo, google/gemini-3.1-pro-preview ou google/gemini-3.5-flash).
[agents/tool-policy]: mostra as ferramentas permitidas ou restritas de acordo com sua política.
[agent/embedded]: rastreia a execução e a invocação de ferramentas pelo agente.

3. Inspecionar registros no console do Google Cloud

Também é possível ver e filtrar registros usando o Análise de registros no Console do Cloud:

resource.type="cloud_run_instance"
resource.labels.instance_name="openclaw-instance"

11. (Opcional) Ampliar seu agente com habilidades

O OpenClaw oferece suporte a habilidades, que são pacotes de recursos modulares que ensinam ao seu agente fluxos de trabalho específicos, ferramentas de CLI especializadas e instruções específicas do domínio.

Como as habilidades funcionam

Cada habilidade é um diretório que contém um arquivo SKILL.md. Ele começa com o frontmatter YAML especificando metadados (name e description), seguido por instruções em Markdown:

---
name: summarize-logs
description: Summarize Cloud Run error logs into actionable bullet points.
---

# Log Summarizer Skill

When asked to analyze or summarize logs:
1. Parse error stack traces and group similar errors by frequency.
2. Identify root causes such as memory limits, timeouts, or permission errors.
3. Propose concrete remediation steps.

name: o identificador da habilidade, que também pode ser chamado diretamente como um comando de barra, por exemplo, /summarize-logs.
description: informa ao modelo do OpenClaw quando invocar automaticamente essa habilidade em uma conversa natural.

Adicionar uma habilidade personalizada ao bucket do Cloud Storage

Como o bucket do Cloud Storage é montado diretamente em /home/node/.openclaw, as habilidades colocadas em gs://${BUCKET_NAME}/skills/ são carregadas automaticamente na inicialização e mantidas nas reinicializações da instância:

Criar um diretório de habilidades local:

mkdir -p my-skill
cat << 'EOF' > my-skill/SKILL.md
---
name: summarize-logs
description: Summarize Cloud Run error logs into actionable bullet points.
---

# Log Summarizer Skill

When asked to analyze or summarize logs, group errors by frequency and suggest actionable fixes.
EOF

Faça upload da habilidade para o Cloud Storage:

gcloud storage cp -r my-skill gs://${BUCKET_NAME}/skills/

Usar a skill no chat:
- Volte para a interface da Web de controle do OpenClaw.
- Agora você pode usar o /summarize-logs ou fazer perguntas em linguagem natural que correspondam à descrição da habilidade.

12. Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste codelab:

Exclua a instância do Cloud Run:

gcloud beta run instances delete openclaw-instance --region ${REGION} --quiet

Excluir secrets do Secret Manager:

gcloud secrets delete gemini-api-key --quiet
gcloud secrets delete telegram-bot-token --quiet
gcloud secrets delete openclaw-gateway-password --quiet

Excluir bucket do Cloud Storage:

gcloud storage rm -r gs://${BUCKET_NAME}

Excluir conta de serviço dedicada:

gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet

13. Conclusão

Parabéns! Você implantou com sucesso uma instância segura e totalmente persistente do OpenClaw em instâncias do Cloud Run com suporte do Cloud Storage, do Secret Manager e do seu canal de mensagens preferido.