Google Chat (Chat API)

상태: Google Chat API 웹훅(HTTP 전용)을 통한 DM + 스페이스 지원 준비 완료.

빠른 설정 (초보자)

Google Cloud 프로젝트를 생성하고 Google Chat API를 활성화합니다.
- 이동: Google Chat API Credentials
- API가 아직 활성화되지 않았으면 활성화합니다.
서비스 계정을 생성합니다:
- 자격 증명 만들기 > 서비스 계정을 클릭합니다.
- 원하는 이름을 지정합니다 (예: openclaw-chat).
- 권한은 비워둡니다 (계속 클릭).
- 접근 권한이 있는 주체는 비워둡니다 (완료 클릭).
JSON 키를 생성하고 다운로드합니다:
- 서비스 계정 목록에서 방금 생성한 계정을 클릭합니다.
- 키 탭으로 이동합니다.
- 키 추가 > 새 키 만들기를 클릭합니다.
- JSON을 선택하고 만들기를 클릭합니다.
다운로드한 JSON 파일을 게이트웨이 호스트에 저장합니다 (예: ~/.openclaw/googlechat-service-account.json).
Google Cloud Console Chat 구성에서 Google Chat 앱을 생성합니다:
- 애플리케이션 정보를 작성합니다:
  - 앱 이름: (예: OpenClaw)
  - 아바타 URL: (예: https://openclaw.ai/logo.png)
  - 설명: (예: Personal AI Assistant)
- 대화형 기능을 활성화합니다.
- 기능 아래에서 스페이스 및 그룹 대화에 참여를 선택합니다.
- 연결 설정에서 HTTP 엔드포인트 URL을 선택합니다.
- 트리거에서 모든 트리거에 공통 HTTP 엔드포인트 URL 사용을 선택하고 게이트웨이의 공개 URL 뒤에 /googlechat을 설정합니다.
  - 팁: openclaw status를 실행하여 게이트웨이의 공개 URL을 확인할 수 있습니다.
- 가시성에서 이 Chat 앱을 <도메인>의 특정 사용자 및 그룹에 제공을 선택합니다.
- 이메일 주소를 입력합니다 (예: [email protected]).
- 하단의 저장을 클릭합니다.
앱 상태를 활성화합니다:
- 저장 후 페이지를 새로고침합니다.
- 앱 상태 섹션을 찾습니다 (보통 저장 후 상단이나 하단에 위치).
- 상태를 라이브 - 사용자에게 제공 가능으로 변경합니다.
- 저장을 다시 클릭합니다.
서비스 계정 경로 + 웹훅 대상자로 OpenClaw를 설정합니다:
- 환경 변수: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- 또는 설정: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
웹훅 대상자 유형 + 값을 설정합니다 (Chat 앱 설정과 일치).
게이트웨이를 시작합니다. Google Chat이 웹훅 경로로 POST를 보냅니다.

Google Chat에 추가

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

Google Chat으로 이동합니다.
다이렉트 메시지 옆의 + (더하기) 아이콘을 클릭합니다.
검색창(일반적으로 사람을 추가하는 곳)에 Google Cloud Console에서 설정한 앱 이름을 입력합니다.
- 참고: 봇은 비공개 앱이므로 “마켓플레이스” 탐색 목록에 표시되지 않습니다. 이름으로 검색해야 합니다.
결과에서 봇을 선택합니다.
추가 또는 채팅을 클릭하여 1:1 대화를 시작합니다.
“Hello”를 보내 어시스턴트를 트리거합니다!

공개 URL (웹훅 전용)

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

옵션 A: Tailscale Funnel (권장)

프라이빗 대시보드에는 Tailscale Serve를, 공개 웹훅 경로에는 Funnel을 사용합니다. /는 프라이빗으로 유지하면서 /googlechat만 노출합니다.

게이트웨이가 바인딩된 주소를 확인합니다:
```
ss -tlnp | grep 18789
```
IP 주소를 확인합니다 (예: 127.0.0.1, 0.0.0.0, 또는 Tailscale IP 100.x.x.x).

대시보드를 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

웹훅 경로만 공개로 노출합니다:

# 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

Funnel 접근을 위한 노드 인가: 프롬프트가 표시되면, 출력에 표시된 인가 URL을 방문하여 tailnet 정책에서 이 노드에 대한 Funnel을 활성화합니다.

설정 확인:

tailscale serve status
tailscale funnel status

공개 웹훅 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

터널의 인그레스 규칙을 웹훅 경로만 라우팅하도록 설정합니다:

경로: /googlechat -> http://localhost:18789/googlechat
기본 규칙: HTTP 404 (Not Found)

동작 방식

Google Chat이 게이트웨이로 웹훅 POST를 전송합니다. 각 요청에는 Authorization: Bearer <token> 헤더가 포함됩니다.
- OpenClaw는 헤더가 있을 때 전체 웹훅 본문을 읽기/파싱하기 전에 bearer 인증을 확인합니다.
- 본문에 authorizationEventObject.systemIdToken이 포함된 Google Workspace Add-on 요청은 더 엄격한 사전 인증 본문 한도를 통해 지원됩니다.
OpenClaw가 설정된 audienceType + audience에 대해 토큰을 확인합니다:
- audienceType: "app-url" → audience는 HTTPS 웹훅 URL입니다.
- audienceType: "project-number" → audience는 Cloud 프로젝트 번호입니다.
메시지는 스페이스별로 라우팅됩니다:
- DM은 세션 키 agent:<agentId>:googlechat:direct:<spaceId>를 사용합니다.
- 스페이스는 세션 키 agent:<agentId>:googlechat:group:<spaceId>를 사용합니다.
DM 접근은 기본적으로 페어링입니다. 알 수 없는 발신자는 페어링 코드를 받으며 다음으로 승인합니다:
- openclaw pairing approve googlechat <code>
그룹 스페이스는 기본적으로 @멘션이 필요합니다. 멘션 감지에 앱의 사용자 이름이 필요하면 botUser를 사용합니다.

대상

전달 및 허용 목록에 다음 식별자를 사용합니다:

다이렉트 메시지: users/<userId> (권장).
순수 이메일 [email protected]은 변경 가능하며 channels.googlechat.dangerouslyAllowNameMatching: true일 때만 직접 허용 목록 매칭에 사용됩니다.
폐기됨: users/<email>은 이메일 허용 목록이 아닌 사용자 ID로 처리됩니다.
스페이스: spaces/<spaceId>.

설정 주요 사항

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // 또는 serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // 선택; 멘션 감지에 도움
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      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 문자열)로 인라인 전달할 수도 있습니다.
serviceAccountRef도 지원됩니다(env/file SecretRef). channels.googlechat.accounts.<id>.serviceAccountRef에서 계정별 참조도 가능합니다.
webhookPath가 설정되지 않으면 기본 웹훅 경로는 /googlechat입니다.
dangerouslyAllowNameMatching은 변경 가능한 이메일 주체 매칭을 허용 목록에 다시 활성화합니다(비상 호환성 모드).
actions.reactions가 활성화되면 reactions 도구 및 channels action을 통해 리액션을 사용할 수 있습니다.
typingIndicator는 none, message (기본값), reaction을 지원합니다 (reaction은 사용자 OAuth 필요).
첨부 파일은 Chat API를 통해 다운로드되고 미디어 파이프라인에 저장됩니다 (mediaMaxMb로 크기 제한).

비밀 관리 세부사항: Secrets Management.

문제 해결

405 Method Not Allowed

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

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

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

채널 미설정: 설정에 channels.googlechat 섹션이 없습니다. 다음으로 확인합니다:
```
openclaw config get channels.googlechat
```
“Config path not found”가 반환되면 설정을 추가합니다 (설정 주요 사항 참조).
플러그인 미활성화: 플러그인 상태를 확인합니다:
```
openclaw plugins list | grep googlechat
```
“disabled”로 표시되면 설정에 plugins.entries.googlechat.enabled: true를 추가합니다.
게이트웨이 미재시작: 설정 추가 후 게이트웨이를 재시작합니다:
```
openclaw gateway restart
```

채널이 실행 중인지 확인합니다:

openclaw channels status
# 표시 예상: Google Chat default: enabled, configured, ...

기타 문제

openclaw channels status --probe로 인증 오류나 누락된 audience 설정을 확인합니다.
메시지가 도착하지 않으면 Chat 앱의 웹훅 URL + 이벤트 구독을 확인합니다.
멘션 게이팅이 응답을 차단하면 botUser를 앱의 사용자 리소스 이름으로 설정하고 requireMention을 확인합니다.
테스트 메시지를 보내면서 openclaw logs --follow로 요청이 게이트웨이에 도달하는지 확인합니다.