OpenClaw Gmail 연동 가이드: 1분 만에 이메일 자동화 설정

이메일 알림을 실시간으로 처리하고 싶은데, Gmail API와 Pub/Sub을 직접 연결하는 과정이 생각보다 까다로울 때가 많죠? 설정해야 할 것도 많고 인증 문제로 씨름하다 보면 시간이 금방 지나가 버리곤 해요. 오늘은 Gmail의 변경 사항을 Pub/Sub을 통해 OpenClaw webhook으로 매끄럽게 연결하는 방법을 알아볼게요.

목표: Gmail watch -> Pub/Sub push -> gog gmail watch serve -> OpenClaw webhook.

필수 준비물 (Prereqs)

gcloud 설치 및 로그인 (설치 가이드).
gog (gogcli) 설치 및 Gmail 계정 인증 (gogcli.sh).
OpenClaw hooks 활성화 (Webhooks 참고).
tailscale 로그인 (tailscale.com). 퍼블릭 HTTPS endpoint를 위해 Tailscale Funnel을 사용하는 설정을 지원합니다. 다른 터널 서비스도 작동할 수 있지만, 직접 설정해야 하며 공식적으로 지원하지는 않습니다. 현재는 Tailscale을 기본으로 지원하고 있어요.

Hook 설정 예시 (Gmail 프리셋 매핑 활성화):

{
  hooks: {
    enabled: true,
    token: "OPENCLAW_HOOK_TOKEN",
    path: "/hooks",
    presets: ["gmail"],
  },
}

Gmail 요약 내용을 채팅 화면으로 전달하려면, deliver와 선택 사항인 channel/to를 설정하여 프리셋을 오버라이드하세요.

{
  hooks: {
    enabled: true,
    token: "OPENCLAW_HOOK_TOKEN",
    presets: ["gmail"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
        model: "openai/gpt-5.2-mini",
        deliver: true,
        channel: "last",
        // to: "+15551234567"
      },
    ],
  },
}

고정된 채널을 원한다면 channel과 to를 설정하세요. 그렇지 않으면 channel: "last"가 마지막 전달 경로를 사용합니다(기본값은 WhatsApp입니다).

Gmail 실행 시 더 저렴한 모델을 강제하려면 매핑에서 model(provider/model 또는 별칭)을 설정하세요. 만약 agents.defaults.models를 사용 중이라면 해당 모델이 허용 리스트에 포함되어야 합니다.

Gmail hook 전용 기본 모델과 thinking level을 설정하려면 설정 파일에 hooks.gmail.model / hooks.gmail.thinking을 추가하세요.

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

참고 사항:

매핑에 설정된 개별 hook의 model/thinking이 이 기본값보다 우선합니다.
Fallback 순서: hooks.gmail.model → agents.defaults.model.fallbacks → primary (인증/rate-limit/타임아웃).
agents.defaults.models가 설정된 경우, Gmail 모델은 반드시 허용 리스트에 있어야 합니다.
Gmail hook 콘텐츠는 기본적으로 외부 콘텐츠 안전 경계(safety boundaries)로 감싸집니다. 이를 비활성화하려면(위험함) hooks.gmail.allowUnsafeExternalContent: true로 설정하세요.

페이로드 처리를 더 커스터마이징하려면 hooks.mappings를 추가하거나 hooks.transformsDir 아래에 JS/TS 변환 모듈을 추가하세요 (Webhooks 참고).

마법사 도구 사용 (Wizard (recommended))

OpenClaw 헬퍼를 사용하면 모든 것을 한 번에 연결할 수 있어요 (macOS에서는 brew를 통해 의존성을 설치합니다).

openclaw webhooks gmail setup \
  --account openclaw@gmail.com

기본 동작:

퍼블릭 push endpoint로 Tailscale Funnel을 사용합니다.
openclaw webhooks gmail run을 위한 hooks.gmail 설정을 작성합니다.
Gmail hook 프리셋을 활성화합니다 (hooks.presets: ["gmail"]).

경로 참고: tailscale.mode가 활성화되면 OpenClaw는 자동으로 hooks.gmail.serve.path를 /로 설정하고, 퍼블릭 경로는 hooks.gmail.tailscale.path(기본값 /gmail-pubsub)로 유지합니다. 이는 Tailscale이 프록시하기 전에 설정된 경로 접두사를 제거하기 때문입니다. 백엔드에서 접두사가 포함된 경로를 받아야 한다면, hooks.gmail.tailscale.target(또는 --tailscale-target)을 http://127.0.0.1:8788/gmail-pubsub과 같은 전체 URL로 설정하고 hooks.gmail.serve.path와 일치시키세요.

커스텀 endpoint를 원하시나요? --push-endpoint <url> 또는 --tailscale off를 사용하세요.

플랫폼 참고: macOS에서 마법사는 Homebrew를 통해 gcloud, gogcli, tailscale을 설치합니다. Linux에서는 먼저 수동으로 설치해 주세요.

Gateway 자동 시작 (권장):

hooks.enabled=true이고 hooks.gmail.account가 설정되면, Gateway가 부팅 시 gog gmail watch serve를 시작하고 watch를 자동으로 갱신합니다.
직접 데몬을 실행하려면 OPENCLAW_SKIP_GMAIL_WATCHER=1을 설정하여 이 기능을 끄세요.
수동 데몬을 동시에 실행하지 마세요. listen tcp 127.0.0.1:8788: bind: address already in use 오류가 발생할 수 있습니다.

수동 데몬 (gog gmail watch serve 시작 + 자동 갱신):

openclaw webhooks gmail run

일회성 설정 (One-time setup)

gog에서 사용하는 OAuth client를 소유한 GCP 프로젝트를 선택하세요.

gcloud auth login
gcloud config set project <project-id>

참고: Gmail watch를 사용하려면 Pub/Sub topic이 OAuth client와 동일한 프로젝트에 있어야 합니다.

API 활성화:

gcloud services enable gmail.googleapis.com pubsub.googleapis.com

Topic 생성:

gcloud pubsub topics create gog-gmail-watch

Gmail push가 메시지를 게시할 수 있도록 허용:

gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher

Watch 시작하기 (Start the watch)

gog gmail watch start \
  --account openclaw@gmail.com \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

출력된 내용 중 history_id를 저장해 두세요 (디버깅용).

Push 핸들러 실행 (Run the push handler)

로컬 예시 (공유 토큰 인증):

gog gmail watch serve \
  --account openclaw@gmail.com \
  --bind 127.0.0.1 \
  --port 8788 \
  --path /gmail-pubsub \
  --token <shared> \
  --hook-url http://127.0.0.1:18789/hooks/gmail \
  --hook-token OPENCLAW_HOOK_TOKEN \
  --include-body \
  --max-bytes 20000

참고 사항:

--token은 push endpoint를 보호합니다 (x-gog-token 또는 ?token=).
--hook-url은 OpenClaw의 /hooks/gmail을 가리킵니다.
--include-body와 --max-bytes는 OpenClaw로 전송되는 본문 스니펫을 제어합니다.

권장 사항: openclaw webhooks gmail run은 동일한 흐름을 래핑하고 watch를 자동으로 갱신해 줍니다.

핸들러 외부 노출 - 고급, 비지원 (Expose the handler (advanced, unsupported))

Tailscale 이외의 터널이 필요한 경우 직접 연결하고 push subscription에서 퍼블릭 URL을 사용하세요 (비지원, 안전장치 없음):

cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate

생성된 URL을 push endpoint로 사용하세요:

gcloud pubsub subscriptions create gog-gmail-watch-push \
  --topic gog-gmail-watch \
  --push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"

프로덕션 환경: 안정적인 HTTPS endpoint를 사용하고 Pub/Sub OIDC JWT를 구성한 뒤 다음을 실행하세요.

gog gmail watch serve --verify-oidc --oidc-email <svc@...>

테스트 (Test)

감시 중인 받은 편지함으로 메시지를 보내보세요.

gog gmail send \
  --account openclaw@gmail.com \
  --to openclaw@gmail.com \
  --subject "watch test" \
  --body "ping"

Watch 상태와 히스토리를 확인합니다.

gog gmail watch status --account openclaw@gmail.com
gog gmail history --account openclaw@gmail.com --since <historyId>

문제 해결 (Troubleshooting)

Invalid topicName: 프로젝트 불일치 (topic이 OAuth client 프로젝트에 없음).
User not authorized: topic에 roles/pubsub.publisher 권한이 없음.
메시지가 비어 있음: Gmail push는 historyId만 제공합니다. gog gmail history를 통해 가져와야 합니다.

정리하기 (Cleanup)

gog gmail watch stop --account openclaw@gmail.com
gcloud pubsub subscriptions delete gog-gmail-watch-push
gcloud pubsub topics delete gog-gmail-watch

설정 중에 궁금한 점이 생기면 언제든 물어봐 주세요!

AI Setup Assistant

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.