Mainstream messaging

Google Chat

상태: Google Chat API Webhook(HTTP 전용)을 통해 DM + 스페이스용으로 다운로드 가능한 Plugin.

설치

채널을 구성하기 전에 Google Chat을 설치합니다.

openclaw plugins install @openclaw/googlechat

로컬 체크아웃(git 저장소에서 실행하는 경우):

openclaw plugins install ./path/to/local/googlechat-plugin

빠른 설정(초보자)

Google Cloud 프로젝트를 만들고 Google Chat API를 활성화합니다.
- 이동: Google Chat API 사용자 인증 정보
- API가 아직 활성화되어 있지 않다면 활성화합니다.
서비스 계정을 만듭니다.
- 사용자 인증 정보 만들기 > 서비스 계정을 누릅니다.
- 원하는 이름을 지정합니다(예: openclaw-chat).
- 권한은 비워 둡니다(계속을 누름).
- 액세스 권한이 있는 주 구성원은 비워 둡니다(완료를 누름).
JSON 키를 만들고 다운로드합니다.
- 서비스 계정 목록에서 방금 만든 계정을 클릭합니다.
- 키 탭으로 이동합니다.
- 키 추가 > 새 키 만들기를 클릭합니다.
- JSON을 선택하고 만들기를 누릅니다.
다운로드한 JSON 파일을 Gateway 호스트에 저장합니다(예: ~/.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 사용을 선택하고, Gateway의 공개 URL 뒤에 /googlechat을 붙여 설정합니다.
  - 팁: Gateway의 공개 URL을 찾으려면 openclaw status를 실행하세요.
- 공개 범위 아래에서 <Your Domain>의 특정 사용자 및 그룹이 이 Chat 앱을 사용할 수 있도록 설정을 선택합니다.
- 텍스트 상자에 이메일 주소를 입력합니다(예: [email protected]).
- 하단의 저장을 클릭합니다.
앱 상태를 활성화합니다.
- 저장한 뒤 페이지를 새로고침합니다.
- 앱 상태 섹션을 찾습니다(저장 후 보통 상단 또는 하단 근처).
- 상태를 실시간 - 사용자가 사용 가능으로 변경합니다.
- 저장을 다시 클릭합니다.
서비스 계정 경로 + Webhook 대상 그룹으로 OpenClaw를 구성합니다.
- Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- 또는 config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Webhook 대상 그룹 유형 + 값을 설정합니다(Chat 앱 구성과 일치해야 함).
Gateway를 시작합니다. Google Chat이 Webhook 경로로 POST를 보냅니다.

Google Chat에 추가

Gateway가 실행 중이고 이메일이 공개 범위 목록에 추가되면:

Google Chat으로 이동합니다.
Direct Messages 옆의 +(더하기) 아이콘을 클릭합니다.
검색창(일반적으로 사용자를 추가하는 곳)에 Google Cloud Console에서 구성한 앱 이름을 입력합니다.
- 참고: 비공개 앱이므로 봇은 "Marketplace" 탐색 목록에 나타나지 않습니다. 이름으로 검색해야 합니다.
결과에서 봇을 선택합니다.
1:1 대화를 시작하려면 추가 또는 채팅을 클릭합니다.
어시스턴트를 트리거하려면 "Hello"를 보냅니다!

공개 URL(Webhook 전용)

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

옵션 A: Tailscale Funnel(권장)

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

Gateway가 어떤 주소에 바인딩되어 있는지 확인합니다.
```
ss -tlnp | grep 18789
```
IP 주소를 기록합니다(예: 127.0.0.1, 0.0.0.0, 또는 100.x.x.x 같은 Tailscale IP).

대시보드를 tailnet에만 노출합니다(포트 8443).

# If bound to localhost (127.0.0.1 or 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# If bound to Tailscale IP only (e.g., 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789

Webhook 경로만 공개적으로 노출합니다.

# If bound to localhost (127.0.0.1 or 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# If bound to Tailscale IP only (e.g., 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

공개 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 경로만 라우팅하도록 터널의 수신 규칙을 구성합니다.

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

작동 방식

Google Chat은 Gateway로 Webhook POST를 보냅니다. 각 요청에는 Authorization: Bearer <token> 헤더가 포함됩니다.
- OpenClaw는 헤더가 있는 경우 전체 Webhook 본문을 읽고 파싱하기 전에 bearer 인증을 확인합니다.
- 본문에 authorizationEventObject.systemIdToken을 포함하는 Google Workspace Add-on 요청은 더 엄격한 사전 인증 본문 예산을 통해 지원됩니다.
OpenClaw는 구성된 audienceType + audience에 대해 토큰을 확인합니다.
- audienceType: "app-url" → 대상 그룹은 HTTPS Webhook URL입니다.
- audienceType: "project-number" → 대상 그룹은 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",
      // or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; helps mention detection
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          enabled: 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 아래의 계정별 ref도 포함됩니다.
webhookPath가 설정되지 않은 경우 기본 Webhook 경로는 /googlechat입니다.
dangerouslyAllowNameMatching은 허용 목록에 대해 변경 가능한 이메일 주 구성원 매칭을 다시 활성화합니다(비상 호환성 모드).
actions.reactions가 활성화되면 reactions 도구 및 channels action을 통해 반응을 사용할 수 있습니다.
메시지 액션은 텍스트용 send와 명시적 첨부 파일 전송용 upload-file을 노출합니다. upload-file은 media / filePath / path와 선택적 message, filename, 스레드 대상을 허용합니다.
typingIndicator는 none, message(기본값), reaction을 지원합니다(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 핸들러가 등록되지 않았다는 의미입니다. 일반적인 원인은 다음과 같습니다.

채널이 구성되지 않음: 구성에 channels.googlechat 섹션이 없습니다. 다음으로 확인합니다.
```
openclaw config get channels.googlechat
```
"Config path not found"를 반환하면 구성을 추가합니다(구성 주요 사항 참조).
Plugin이 활성화되지 않음: Plugin 상태를 확인합니다.
```
openclaw plugins list | grep googlechat
```
"disabled"가 표시되면 구성에 plugins.entries.googlechat.enabled: true를 추가합니다.
Gateway가 재시작되지 않음: 구성을 추가한 뒤 Gateway를 재시작합니다.
```
openclaw gateway restart
```

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

openclaw channels status
# Should show: Google Chat default: enabled, configured, ...

기타 문제

인증 오류 또는 누락된 대상 그룹 구성이 있는지 openclaw channels status --probe를 확인합니다.
메시지가 도착하지 않으면 Chat 앱의 Webhook URL + 이벤트 구독을 확인합니다.
멘션 게이팅이 응답을 차단하면 botUser를 앱의 사용자 리소스 이름으로 설정하고 requireMention을 확인합니다.
테스트 메시지를 보내는 동안 요청이 Gateway에 도달하는지 보려면 openclaw logs --follow를 사용합니다.

Google Chat

설치

빠른 설정(초보자)

Google Chat에 추가

공개 URL(Webhook 전용)

옵션 A: Tailscale Funnel(권장)

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

옵션 C: Cloudflare Tunnel

작동 방식

대상

구성 주요 사항

문제 해결

405 Method Not Allowed

기타 문제

관련 항목

Ask OpenClaw

# 설치

# 빠른 설정(초보자)

# Google Chat에 추가

# 공개 URL(Webhook 전용)

# 옵션 A: Tailscale Funnel(권장)

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

# 옵션 C: Cloudflare Tunnel

# 작동 방식

# 대상

# 구성 주요 사항

# 문제 해결

# 405 Method Not Allowed

# 기타 문제

# 관련 항목

설치

빠른 설정(초보자)

Google Chat에 추가

공개 URL(Webhook 전용)

옵션 A: Tailscale Funnel(권장)

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

옵션 C: Cloudflare Tunnel

작동 방식

대상

구성 주요 사항

문제 해결

405 Method Not Allowed

기타 문제

관련 항목