Gmail Pub/Sub -> OpenClaw

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

사전 준비

  • gcloud 설치 및 로그인 (설치 가이드).
  • gog (gogcli) 설치 및 Gmail 계정 인증 완료 (gogcli.sh).
  • OpenClaw hooks 활성화 (웹훅 참고).
  • tailscale 로그인 (tailscale.com). 지원되는 설정은 공개 HTTPS 엔드포인트를 위해 Tailscale Funnel을 사용합니다. 다른 터널 서비스도 작동할 수 있지만, DIY/지원되지 않으며 수동 연결이 필요합니다. 현재 Tailscale만 공식적으로 지원합니다.

훅 설정 예시 (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 훅에 대해 기본 모델과 사고 레벨을 설정하려면, 설정에 hooks.gmail.model / hooks.gmail.thinking을 추가하세요:

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

참고:

  • 매핑의 훅별 model/thinking은 이 기본값보다 우선합니다.
  • 대체 순서: hooks.gmail.model → agents.defaults.model.fallbacks → 기본 (인증/속도 제한/타임아웃).
  • agents.defaults.models가 설정된 경우, Gmail 모델은 허용 목록에 있어야 합니다.
  • Gmail 훅 콘텐츠는 기본적으로 외부 콘텐츠 안전 경계로 래핑됩니다. 비활성화하려면 (위험) hooks.gmail.allowUnsafeExternalContent: true를 설정하세요.

페이로드 처리를 추가로 커스터마이즈하려면, hooks.mappings를 추가하거나 ~/.openclaw/hooks/transforms 아래에 JS/TS 변환 모듈을 추가하세요 (웹훅 참고).

위자드 (권장)

OpenClaw 헬퍼를 사용하여 모든 것을 연결하세요 (macOS에서는 brew를 통해 의존성 설치):

openclaw webhooks gmail setup \
  --account [email protected]

기본값:

  • 공개 푸시 엔드포인트에 Tailscale Funnel을 사용합니다.
  • openclaw webhooks gmail run용 hooks.gmail 설정을 작성합니다.
  • Gmail 훅 프리셋을 활성화합니다 (hooks.presets: ["gmail"]).

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

커스텀 엔드포인트를 원하시면 --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

일회성 설정

  1. gog에서 사용하는 OAuth 클라이언트를 소유한 GCP 프로젝트를 선택합니다.
gcloud auth login
gcloud config set project <project-id>

참고: Gmail watch는 Pub/Sub 토픽이 OAuth 클라이언트와 같은 프로젝트에 있어야 합니다.

  1. API 활성화:
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
  1. 토픽 생성:
gcloud pubsub topics create gog-gmail-watch
  1. Gmail 푸시가 게시할 수 있도록 허용:
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:[email protected] \
  --role=roles/pubsub.publisher

watch 시작

gog gmail watch start \
  --account [email protected] \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

출력에서 history_id를 저장하세요 (디버깅용).

푸시 핸들러 실행

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

gog gmail watch serve \
  --account [email protected] \
  --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은 푸시 엔드포인트를 보호합니다 (x-gog-token 또는 ?token=).
  • --hook-url은 OpenClaw /hooks/gmail을 가리킵니다 (매핑됨; 격리 실행 + 메인에 요약).
  • --include-body와 --max-bytes는 OpenClaw로 전송되는 본문 스니펫을 제어합니다.

권장: openclaw webhooks gmail run이 동일한 흐름을 래핑하고 watch를 자동 갱신합니다.

핸들러 노출 (고급, 지원되지 않음)

비-Tailscale 터널이 필요한 경우, 수동으로 연결하고 푸시 구독에서 공개 URL을 사용하세요 (지원되지 않음, 가드레일 없음):

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

생성된 URL을 푸시 엔드포인트로 사용:

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

프로덕션: 안정적인 HTTPS 엔드포인트를 사용하고 Pub/Sub OIDC JWT를 설정한 후 실행:

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

테스트

감시 중인 받은편지함으로 메시지를 전송합니다:

gog gmail send \
  --account [email protected] \
  --to [email protected] \
  --subject "watch test" \
  --body "ping"

watch 상태 및 기록 확인:

gog gmail watch status --account [email protected]
gog gmail history --account [email protected] --since <historyId>

트러블슈팅

  • Invalid topicName: 프로젝트 불일치 (토픽이 OAuth 클라이언트 프로젝트에 없음).
  • User not authorized: 토픽에 roles/pubsub.publisher가 누락됨.
  • 빈 메시지: Gmail 푸시는 historyId만 제공합니다. gog gmail history로 가져오세요.

정리

gog gmail watch stop --account [email protected]
gcloud pubsub subscriptions delete gog-gmail-watch-push
gcloud pubsub topics delete gog-gmail-watch
arrow_back
이전
Webhook
다음
Poll
arrow_forward