Google Chat (Chat API)

Status: pronto para DMs + espaços via webhooks da Google Chat API (somente HTTP).

Configuração rápida (iniciante)

  1. Crie um projeto Google Cloud e habilite a Google Chat API.
  2. Crie uma Service Account:
    • Clique em Create Credentials > Service Account.
    • Nomeie como quiser (ex.: openclaw-chat).
    • Deixe permissões em branco (clique Continue).
    • Deixe principals com acesso em branco (clique Done).
  3. Crie e baixe a Chave JSON:
    • Na lista de service accounts, clique na que você acabou de criar.
    • Vá até a aba Keys.
    • Clique Add Key > Create new key.
    • Selecione JSON e clique Create.
  4. Armazene o arquivo JSON baixado no host do gateway (ex.: ~/.openclaw/googlechat-service-account.json).
  5. Crie um app do Google Chat no Google Cloud Console Chat Configuration:
    • Preencha as Application info:
      • App name: (ex.: OpenClaw)
      • Avatar URL: (ex.: https://openclaw.ai/logo.png)
      • Description: (ex.: Assistente pessoal de IA)
    • Habilite Interactive features.
    • Em Functionality, marque Join spaces and group conversations.
    • Em Connection settings, selecione HTTP endpoint URL.
    • Em Triggers, selecione Use a common HTTP endpoint URL for all triggers e defina como a URL pública do seu gateway seguida de /googlechat.
      • Dica: Execute openclaw status para encontrar a URL pública do seu gateway.
    • Em Visibility, marque Make this Chat app available to specific people and groups in <Seu Domínio>.
    • Insira seu endereço de email (ex.: [email protected]) na caixa de texto.
    • Clique Save no final.
  6. Habilite o status do app:
    • Após salvar, atualize a página.
    • Procure a seção App status (geralmente perto do topo ou final após salvar).
    • Altere o status para Live - available to users.
    • Clique Save novamente.
  7. Configure o OpenClaw com o caminho da service account + audience do webhook:
    • Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/caminho/para/service-account.json
    • Ou config: channels.googlechat.serviceAccountFile: "/caminho/para/service-account.json".
  8. Defina o tipo de audience do webhook + valor (correspondente à configuração do seu app Chat).
  9. Inicie o gateway. O Google Chat fará POST para o caminho do seu webhook.

Adicionar ao Google Chat

Quando o gateway estiver rodando e seu email estiver na lista de visibilidade:

  1. Acesse o Google Chat.
  2. Clique no ícone + (mais) ao lado de Direct Messages.
  3. Na barra de busca (onde você normalmente adiciona pessoas), digite o App name que você configurou no Google Cloud Console.
    • Nota: O bot não aparecerá na lista “Marketplace” porque é um app privado. Você precisa buscá-lo pelo nome.
  4. Selecione seu bot nos resultados.
  5. Clique Add ou Chat para iniciar uma conversa 1:1.
  6. Envie “Olá” para acionar o assistente!

URL pública (somente Webhook)

Webhooks do Google Chat requerem um endpoint público HTTPS. Por segurança, exponha apenas o caminho /googlechat para a internet. Mantenha o dashboard do OpenClaw e outros endpoints sensíveis na sua rede privada.

Opção A: Tailscale Funnel (Recomendado)

Use Tailscale Serve para o dashboard privado e Funnel para o caminho público do webhook. Isso mantém / privado enquanto expõe apenas /googlechat.

  1. Verifique em qual endereço seu gateway está vinculado:

    ss -tlnp | grep 18789

    Anote o endereço IP (ex.: 127.0.0.1, 0.0.0.0, ou seu IP Tailscale como 100.x.x.x).

  2. Exponha o dashboard apenas para a tailnet (porta 8443):

    # Se vinculado a localhost (127.0.0.1 ou 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# Se vinculado apenas ao IP Tailscale (ex.: 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789

  3. Exponha apenas o caminho do webhook publicamente:

    # Se vinculado a localhost (127.0.0.1 ou 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# Se vinculado apenas ao IP Tailscale (ex.: 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

  4. Autorize o nó para acesso Funnel: Se solicitado, visite a URL de autorização mostrada na saída para habilitar o Funnel para este nó na sua política de tailnet.

  5. Verifique a configuração:

    tailscale serve status
tailscale funnel status

Sua URL pública de webhook será: https://<nome-do-nó>.<tailnet>.ts.net/googlechat

Seu dashboard privado permanece apenas na tailnet: https://<nome-do-nó>.<tailnet>.ts.net:8443/

Use a URL pública (sem :8443) na configuração do app Google Chat.

Nota: Esta configuração persiste entre reinicializações. Para removê-la depois, execute tailscale funnel reset e tailscale serve reset.

Opção B: Proxy Reverso (Caddy)

Se você usa um proxy reverso como Caddy, faça proxy apenas do caminho específico:

your-domain.com {
    reverse_proxy /googlechat* localhost:18789
}

Com esta configuração, qualquer requisição para your-domain.com/ será ignorada ou retornará 404, enquanto your-domain.com/googlechat é roteado com segurança para o OpenClaw.

Opção C: Cloudflare Tunnel

Configure as regras de ingress do seu tunnel para rotear apenas o caminho do webhook:

  • Path: /googlechat -> http://localhost:18789/googlechat
  • Default Rule: HTTP 404 (Not Found)

Como funciona

  1. O Google Chat envia POSTs de webhook para o gateway. Cada requisição inclui um header Authorization: Bearer <token>.
    • O OpenClaw verifica auth bearer antes de ler/parsear os corpos completos do webhook quando o header está presente.
    • Requisições de Google Workspace Add-on que incluem authorizationEventObject.systemIdToken no corpo são suportadas via um orçamento de corpo pré-auth mais estrito.
  2. O OpenClaw verifica o token contra o audienceType + audience configurados:
    • audienceType: "app-url" -> audience é sua URL de webhook HTTPS.
    • audienceType: "project-number" -> audience é o número do projeto Cloud.
  3. Mensagens são roteadas por espaço:
    • DMs usam chave de sessão agent:<agentId>:googlechat:direct:<spaceId>.
    • Espaços usam chave de sessão agent:<agentId>:googlechat:group:<spaceId>.
  4. Acesso a DM é pareamento por padrão. Remetentes desconhecidos recebem um código de pareamento; aprove com:
    • openclaw pairing approve googlechat <code>
  5. Espaços de grupo requerem @menção por padrão. Use botUser se a detecção de menção precisar do nome de usuário do app.

Alvos

Use estes identificadores para entrega e allowlists:

  • Mensagens diretas: users/<userId> (recomendado).
  • Email bruto [email protected] é mutável e só é usado para correspondência direta de allowlist quando channels.googlechat.dangerouslyAllowNameMatching: true.
  • Obsoleto: users/<email> é tratado como user id, não como allowlist de email.
  • Espaços: spaces/<spaceId>.

Destaques da configuração

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/caminho/para/service-account.json",
      // ou serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // opcional; ajuda na detecção de menção
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          allow: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Apenas respostas curtas.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

Observações:

  • Credenciais de service account também podem ser passadas inline com serviceAccount (string JSON).
  • serviceAccountRef também é suportado (SecretRef de env/arquivo), incluindo refs por conta em channels.googlechat.accounts.<id>.serviceAccountRef.
  • O caminho padrão do webhook é /googlechat se webhookPath não estiver definido.
  • dangerouslyAllowNameMatching reabilita correspondência mutável por email principal para allowlists (modo de compatibilidade de emergência).
  • Reações estão disponíveis via a ferramenta reactions e channels action quando actions.reactions está habilitado.
  • typingIndicator suporta none, message (padrão) e reaction (reaction requer OAuth de usuário).
  • Anexos são baixados pela Chat API e armazenados no pipeline de mídia (tamanho limitado por mediaMaxMb).

Detalhes de referência de segredos: Gerenciamento de Segredos.

Resolução de problemas

405 Method Not Allowed

Se o Google Cloud Logs Explorer mostrar erros como:

status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed

Significa que o handler de webhook não está registrado. Causas comuns:

  1. Canal não configurado: A seção channels.googlechat está ausente do seu config. Verifique com:

    openclaw config get channels.googlechat

    Se retornar “Config path not found”, adicione a configuração (veja Destaques da configuração).

  2. Plugin não habilitado: Verifique o status do plugin:

    openclaw plugins list | grep googlechat

    Se mostrar “disabled”, adicione plugins.entries.googlechat.enabled: true ao seu config.

  3. Gateway não reiniciado: Após adicionar config, reinicie o gateway:

    openclaw gateway restart

Verifique se o canal está rodando:

openclaw channels status
# Deve mostrar: Google Chat default: enabled, configured, ...

Outros problemas

  • Verifique openclaw channels status --probe para erros de auth ou audience não configurado.
  • Se nenhuma mensagem chegar, confirme a URL do webhook + assinaturas de evento do app Chat.
  • Se o gating de menção bloquear respostas, defina botUser com o nome de recurso de usuário do app e verifique requireMention.
  • Use openclaw logs --follow enquanto envia uma mensagem de teste para ver se as requisições chegam ao gateway.

Documentação relacionada:

arrow_back
Anterior
Feishu
Próximo
Imessage
arrow_forward