Google Chat (Chat API)

상태: Google Chat API webhook (HTTP만)을 통한 DM + 스페이스 준비 완료.

빠른 설정 (초보자)

  1. Google Cloud 프로젝트를 생성하고 Google Chat API를 활성화합니다.
  2. Service Account 생성:
    • Create Credentials > Service Account를 누릅니다.
    • 원하는 이름을 지정합니다 (예: openclaw-chat).
    • 권한은 비워 둡니다 (Continue 누름).
    • 액세스 권한이 있는 주체는 비워 둡니다 (Done 누름).
  3. JSON Key 생성 및 다운로드:
    • 서비스 계정 목록에서 방금 생성한 계정을 클릭합니다.
    • Keys 탭으로 이동합니다.
    • Add Key > Create new key를 클릭합니다.
    • JSON을 선택하고 Create를 누릅니다.
  4. 다운로드한 JSON 파일을 gateway 호스트에 저장합니다 (예: ~/.openclaw/googlechat-service-account.json).
  5. Google Cloud Console Chat Configuration에서 Google Chat 앱을 생성합니다:
    • Application info 작성:
      • App name: (예: OpenClaw)
      • Avatar URL: (예: https://openclaw.ai/logo.png)
      • Description: (예: Personal AI Assistant)
    • Interactive features 활성화.
    • Functionality 아래에서 Join spaces and group conversations 체크.
    • Connection settings 아래에서 HTTP endpoint URL 선택.
    • Triggers 아래에서 Use a common HTTP endpoint URL for all triggers를 선택하고 gateway의 공개 URL 뒤에 /googlechat을 추가하여 설정합니다.
      • 팁: openclaw status를 실행하여 gateway의 공개 URL을 찾으세요.
    • Visibility 아래에서 **Make this Chat app available to specific people and groups in <Your Domain>**을 체크합니다.
    • 텍스트 상자에 이메일 주소를 입력합니다 (예: [email protected]).
    • 하단의 Save를 클릭합니다.
  6. 앱 상태 활성화:
    • 저장 후 페이지를 새로고침합니다.
    • App status 섹션을 찾습니다 (일반적으로 저장 후 상단 또는 하단 근처).
    • 상태를 Live - available to users로 변경합니다.
    • Save를 다시 클릭합니다.
  7. 서비스 계정 경로 + webhook audience로 OpenClaw를 구성합니다:
    • 환경 변수: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
    • 또는 구성: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
  8. Webhook audience 유형 + 값을 설정합니다 (Chat 앱 구성과 일치).
  9. Gateway를 시작합니다. Google Chat이 webhook 경로로 POST합니다.

Google Chat에 추가

Gateway가 실행 중이고 이메일이 가시성 목록에 추가되면:

  1. Google Chat으로 이동합니다.
  2. Direct Messages 옆의 + (더하기) 아이콘을 클릭합니다.
  3. 검색창 (일반적으로 사람을 추가하는 곳)에 Google Cloud Console에서 구성한 App name을 입력합니다.
    • 참고: Bot은 비공개 앱이므로 "Marketplace" 브라우즈 목록에 나타나지 않습니다. 이름으로 검색해야 합니다.
  4. 결과에서 bot을 선택합니다.
  5. Add 또는 Chat을 클릭하여 1:1 대화를 시작합니다.
  6. "Hello"를 전송하여 assistant를 트리거합니다!

공개 URL (Webhook 전용)

Google Chat webhook에는 공개 HTTPS 엔드포인트가 필요합니다. 보안을 위해 인터넷에는 /googlechat 경로만 노출하세요. OpenClaw 대시보드 및 기타 민감한 엔드포인트는 개인 네트워크에 유지하세요.

옵션 A: Tailscale Funnel (권장)

개인 대시보드에는 Tailscale Serve를, 공개 webhook 경로에는 Funnel을 사용합니다. 이렇게 하면 /는 비공개로 유지하면서 /googlechat만 노출됩니다.

  1. Gateway가 바인딩된 주소 확인:

    ss -tlnp | grep 18789

    IP 주소를 확인합니다 (예: 127.0.0.1, 0.0.0.0 또는 100.x.x.x와 같은 Tailscale IP).

  2. Tailnet에만 대시보드 노출 (포트 8443):

    # localhost에 바인딩된 경우 (127.0.0.1 또는 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# Tailscale IP에만 바인딩된 경우 (예: 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789

  3. Webhook 경로만 공개적으로 노출:

    # localhost에 바인딩된 경우 (127.0.0.1 또는 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# Tailscale IP에만 바인딩된 경우 (예: 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

  4. Funnel 액세스를 위해 노드 인증: 프롬프트가 표시되면 출력에 표시된 인증 URL을 방문하여 tailnet 정책에서 이 노드에 대해 Funnel을 활성화합니다.

  5. 구성 확인:

    tailscale serve status
tailscale funnel status

공개 webhook URL은 다음과 같습니다: https://<node-name>.<tailnet>.ts.net/googlechat

비공개 대시보드는 tailnet 전용으로 유지됩니다: https://<node-name>.<tailnet>.ts.net:8443/

Google Chat 앱 구성에서 공개 URL (:8443 없이)을 사용하세요.

참고: 이 구성은 재부팅 후에도 유지됩니다. 나중에 제거하려면 tailscale funnel reset 및 tailscale serve reset을 실행하세요.

옵션 B: 리버스 프록시 (Caddy)

Caddy와 같은 리버스 프록시를 사용하는 경우 특정 경로만 프록시하세요:

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

이 구성을 사용하면 your-domain.com/에 대한 모든 요청은 무시되거나 404로 반환되며, your-domain.com/googlechat은 안전하게 OpenClaw로 라우팅됩니다.

옵션 C: Cloudflare Tunnel

터널의 수신 규칙을 구성하여 webhook 경로만 라우팅하세요:

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

작동 방식

  1. Google Chat은 gateway로 webhook POST를 전송합니다. 각 요청에는 Authorization: Bearer <token> 헤더가 포함됩니다.
  2. OpenClaw는 구성된 audienceType + audience에 대해 토큰을 확인합니다:
    • audienceType: "app-url" → audience는 HTTPS webhook URL입니다.
    • audienceType: "project-number" → audience는 Cloud 프로젝트 번호입니다.
  3. 메시지는 스페이스별로 라우팅됩니다:
    • DM은 세션 키 agent:<agentId>:googlechat:dm:<spaceId>를 사용합니다.
    • 스페이스는 세션 키 agent:<agentId>:googlechat:group:<spaceId>를 사용합니다.
  4. DM 액세스는 기본적으로 pairing입니다. 알 수 없는 발신자는 페어링 코드를 받습니다; 승인:
    • openclaw pairing approve googlechat <code>
  5. 그룹 스페이스는 기본적으로 @-멘션이 필요합니다. 멘션 감지에 앱의 사용자 이름이 필요한 경우 botUser를 사용하세요.

대상

전달 및 허용 목록에 다음 식별자를 사용하세요:

  • 직접 메시지: users/<userId> 또는 users/<email> (이메일 주소 허용).
  • 스페이스: spaces/<spaceId>.

구성 하이라이트

{
  channels: {
    "googlechat": {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // 선택 사항; 멘션 감지에 도움
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890", "[email protected]"]
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          allow: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only."
        }
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20
    }
  }
}

참고사항:

  • 서비스 계정 자격 증명은 serviceAccount (JSON 문자열)로 인라인으로 전달할 수도 있습니다.
  • webhookPath가 설정되지 않은 경우 기본 webhook 경로는 /googlechat입니다.
  • 반응은 actions.reactions가 활성화된 경우 reactions 도구 및 channels action을 통해 사용할 수 있습니다.
  • typingIndicator는 none, message (기본값), reaction (반응은 사용자 OAuth 필요)을 지원합니다.
  • 첨부 파일은 Chat API를 통해 다운로드되고 미디어 파이프라인에 저장됩니다 (mediaMaxMb로 크기 제한).

문제 해결

405 Method Not Allowed

Google Cloud Logs Explorer에 다음과 같은 오류가 표시되면:

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

이는 webhook 핸들러가 등록되지 않았음을 의미합니다. 일반적인 원인:

  1. 채널이 구성되지 않음: 구성에 channels.googlechat 섹션이 없습니다. 확인:

    openclaw config get channels.googlechat

    "Config path not found"를 반환하면 구성을 추가하세요 (Config highlights 참조).

  2. Plugin이 활성화되지 않음: Plugin 상태 확인:

    openclaw plugins list | grep googlechat

    "disabled"가 표시되면 구성에 plugins.entries.googlechat.enabled: true를 추가하세요.

  3. Gateway가 다시 시작되지 않음: 구성을 추가한 후 gateway를 다시 시작하세요:

    openclaw gateway restart

채널이 실행 중인지 확인:

openclaw channels status
# 다음이 표시되어야 함: Google Chat default: enabled, configured, ...

기타 문제

  • 인증 오류 또는 누락된 audience 구성에 대해 openclaw channels status --probe를 확인하세요.
  • 메시지가 도착하지 않으면 Chat 앱의 webhook URL + 이벤트 구독을 확인하세요.
  • 멘션 게이팅이 답장을 차단하면 botUser를 앱의 사용자 리소스 이름으로 설정하고 requireMention을 확인하세요.
  • 테스트 메시지를 보내는 동안 openclaw logs --follow를 사용하여 요청이 gateway에 도달하는지 확인하세요.

관련 문서:

← 문서로 돌아가기