Gmail Pub/Sub -> OpenClaw

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

전제 조건

  • gcloud 설치 및 로그인 (설치 가이드).
  • gog (gogcli) 설치 및 Gmail 계정에 대해 인증 (gogcli.sh).
  • OpenClaw hook 활성화 (Webhook 참조).
  • tailscale 로그인 (tailscale.com). 지원되는 설정은 공개 HTTPS 엔드포인트를 위해 Tailscale Funnel을 사용합니다. 다른 터널 서비스도 작동할 수 있지만 DIY/지원되지 않으며 수동 연결이 필요합니다. 현재 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 레벨을 설정하려면 구성에 hooks.gmail.model / hooks.gmail.thinking을 추가하세요:

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

참고사항:

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

페이로드 처리를 더 사용자 지정하려면 hooks.mappings 또는 hooks.transformsDir 아래의 JS/TS 변환 모듈을 추가하세요 (Webhook 참조).

마법사 (권장)

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

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

기본값:

  • 공개 푸시 엔드포인트를 위해 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와 일치시키세요.

커스텀 엔드포인트를 원하시나요? --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을 가리킵니다 (매핑됨; isolated 실행 + main에 요약).
  • --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
← 문서로 돌아가기