OpenClaw

OpenClaw Google Chat 채널

엔터프라이즈
보통

Google Chat API의 HTTP 엔드포인트를 통해 OpenClaw를 Google Chat에 연결합니다. 이 엔터프라이즈 통합을 통해 AI 어시스턴트를 Google Workspace 내에서 운영할 수 있습니다 — 다이렉트 메시지와 스페이스(Space) 대화를 처리합니다. 봇은 Google Chat의 HTTP POST 요청을 수신하고, 서비스 계정을 통해 Bearer 토큰을 검증하며, OpenClaw Gateway를 통해 메시지를 라우팅합니다.

기본 정보
난이도보통
카테고리엔터프라이즈
지원 기능 수5 / 6

Google Chat 지원 기능

텍스트 메시지

지원

미디어 및 파일

지원

리액션

지원

스레드

지원

음성 메시지

미지원

그룹 채팅

지원

Google Chat 사전 요구사항

  • Google Workspace 계정(Business 또는 Enterprise 버전). 인증 범위 승인 및 앱 가시성 설정에는 도메인 관리자 권한이 필요할 수 있습니다
  • Google Chat API가 활성화된 Google Cloud 프로젝트
  • JSON 키 파일이 생성된 서비스 계정
  • OpenClaw Gateway가 실행 중이며 구성 완료
  • Webhook용 공개 접근 가능한 HTTPS 엔드포인트(예: Tailscale Funnel, Caddy 또는 Cloudflare Tunnel)

Google Chat 빠른 설정

1

Google Chat API 활성화 및 서비스 계정 생성

Google Cloud Console로 이동하여 Google Chat API를 활성화합니다. 새 서비스 계정(예: 'openclaw-chat')을 생성하고, 권한 구성을 건너뛴 다음 JSON 키 파일을 생성하여 다운로드합니다. 파일을 Gateway 호스트에 저장합니다(예: ~/.openclaw/googlechat-service-account.json).

2

Google Cloud Console에서 Chat 앱 구성

Google Cloud Console의 Chat 구성 페이지에서 앱 이름, 아바타 URL, 설명을 설정합니다. 대화형 기능을 활성화하고 앱이 스페이스와 그룹 대화에 참여할 수 있도록 합니다. 연결 설정으로 'HTTP 엔드포인트 URL'을 선택하고 Gateway의 공개 URL 뒤에 '/googlechat'를 추가하여 입력합니다('openclaw status'로 Gateway URL 확인).

3

가시성 설정, 앱 활성화 및 테스트

앱 가시성을 도메인 내 특정 사용자 또는 그룹으로 제한합니다. 구성을 저장하고 페이지를 새로고침한 후 앱 상태를 '라이브 — 사용자에게 제공 가능'으로 변경합니다. Google Chat에서 '다이렉트 메시지' 옆의 '+' 아이콘을 클릭하고 앱 이름을 검색하여 테스트 메시지를 보냅니다.

Google Chat 구성 예시

config.json
{
  "channels": {
    "googlechat": {
      "serviceAccountFile": "~/.openclaw/googlechat-service-account.json",
      "webhookPath": "/googlechat"
    }
  }
}

Google Chat 상세 문서

아키텍처 개요

OpenClaw는 HTTP 엔드포인트 아키텍처를 통해 Google Chat과 통합됩니다. 흐름은 다음과 같습니다: 1. Google Chat이 'Authorization: Bearer <token>' 헤더가 포함된 HTTP POST 요청을 Gateway 엔드포인트로 보냅니다. 2. OpenClaw가 구성된 오디언스 설정에 따라 Bearer 토큰을 검증합니다. 오디언스가 app-url이면 OIDC ID 토큰이고, project-number이면 자체 서명 JWT입니다. 3. 메시지는 DM과 스페이스를 구분하는 세션 키를 통해 라우팅됩니다. 4. 기본적으로 DM은 페어링 코드로 접근 제어를, 그룹 스페이스는 @멘션으로 활성화됩니다. WebSocket 기반 채널과 달리 Google Chat은 공개 접근 가능한 HTTPS 엔드포인트가 필요합니다. Gateway는 구성된 엔드포인트 경로(기본값: /googlechat)에서 수신 POST 요청을 수신합니다.
'openclaw status'를 사용하여 Gateway의 공개 URL을 확인하고 Webhook 구성에 사용하세요.
서비스 계정 JSON 키 파일에는 민감한 인증 정보가 포함되어 있습니다 — 안전하게 저장하고 파일 권한을 제한하세요.

서비스 계정 설정

인증을 위해 Google Cloud 서비스 계정이 필요합니다. 다음 단계를 따르세요: 1. Google Cloud Console → IAM 및 관리 → 서비스 계정으로 이동 2. '서비스 계정 만들기' 클릭 3. 이름 지정(예: 'openclaw-chat') 후 선택적 권한 구성 건너뛰기 4. 생성된 서비스 계정 클릭 → 키 탭 → 키 추가 → 새 키 만들기 5. JSON 형식 선택 후 키 파일 다운로드 6. Gateway 호스트의 안전한 위치에 파일 배치(예: ~/.openclaw/googlechat-service-account.json) 서비스 계정 인증 정보는 Google Chat의 Webhook 요청 검증과 Google Chat API를 통한 발신 메시지에 사용됩니다.
openclaw.json
{
  "channels": {
    "googlechat": {
      "serviceAccountFile": "~/.openclaw/googlechat-service-account.json"
    }
  }
}
서비스 계정 JSON 키 파일을 버전 관리에 커밋하지 마세요. 파일 경로를 .gitignore에 추가하고 파일 권한을 Gateway 프로세스 사용자로 제한하세요.

Chat 앱 구성

Google Cloud Console에서 Chat 앱을 구성합니다: 1. Google Cloud Console → API 및 서비스 → Google Chat API → 구성으로 이동 2. 앱 이름, 아바타 URL, 설명 설정 3. '대화형 기능'에서 대화형 기능 활성화 4. 앱이 스페이스와 그룹 대화에 참여할 수 있도록 허용 5. 연결 설정을 'HTTP 엔드포인트 URL'로 선택 6. Gateway의 공개 Webhook URL 입력(예: https://your-domain.com/googlechat) 7. '가시성'에서 도메인 내 특정 사용자 또는 그룹으로 제한 8. 구성을 저장하고 페이지를 새로고침한 후 앱 상태를 '라이브 — 사용자에게 제공 가능'으로 설정 참고: 비공개 앱은 Google Chat 마켓플레이스에 표시되지 않습니다. 사용자는 정확한 앱 이름을 검색하여 찾아야 합니다.
구성을 저장한 후 상태 토글을 보려면 페이지 새로고침이 필요할 수 있습니다.
사용자는 Google Chat에서 '다이렉트 메시지' 옆의 '+' 아이콘을 클릭하고 구성된 앱 이름을 검색하여 봇을 추가합니다.

공개 URL 및 Webhook 구성

Google Chat은 Webhook 이벤트를 보내기 위해 공개 접근 가능한 HTTPS 엔드포인트가 필요합니다. 세 가지 옵션을 권장합니다: 옵션 A — Tailscale Funnel(권장): • Gateway 바인드 주소 확인: ss -tlnp | grep 18789 • Webhook 공개 노출: tailscale funnel --set-path=/googlechat localhost:18789 • 공개 URL 형식: https://<노드명>.<tailnet>.ts.net/googlechat 옵션 B — Caddy 리버스 프록시: • 특정 경로만 프록시: reverse_proxy /googlechat* localhost:18789 옵션 C — Cloudflare Tunnel: • /googlechat 경로만 Gateway로 라우팅하고 다른 요청은 404를 반환하도록 인그레스 규칙을 구성. 어떤 옵션을 선택하든 생성된 공개 URL은 Google Chat 앱 구성의 HTTP 엔드포인트 URL에 입력해야 합니다.
터미널 / 구성 파일
# Tailscale Funnel 예시:
tailscale funnel --set-path=/googlechat localhost:18789

# Caddy 예시:
reverse_proxy /googlechat* localhost:18789

# Cloudflare Tunnel 인그레스 구성:
- hostname: your-domain.com
  path: /googlechat
  service: http://localhost:18789
- service: http_status:404
Tailscale Funnel을 권장합니다. HTTPS 인증서를 자동으로 처리하며 최소한의 구성만 필요합니다.
/googlechat 경로만 공개하세요 — 전체 Gateway를 인터넷에 노출하지 마세요.

DM 및 그룹 정책

OpenClaw는 DM 및 그룹 정책을 통해 Google Chat 봇에 대한 접근을 제어합니다: DM 정책(기본값: pairing): • pairing — 새 연락처는 CLI에서 승인하는 페어링 코드를 사용한 페어링 과정을 거쳐야 합니다 • allowlist — 명시적으로 나열된 사용자만 봇에 메시지를 보낼 수 있습니다 • open — 누구나 봇에 메시지를 보낼 수 있습니다(주의하여 사용) 그룹 정책: • 기본적으로 봇은 그룹 스페이스에서 @멘션될 때만 응답합니다 • 특정 스페이스의 허용 목록을 구성할 수 있습니다 • 스페이스별 구성에서 사용자 정의 시스템 프롬프트를 지원합니다 DM과 스페이스의 접근 제어가 다릅니다: DM은 기본적으로 페어링 코드를, 스페이스는 @멘션 활성화를 사용합니다.
openclaw.json
{
  "channels": {
    "googlechat": {
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "groupAllowList": ["spaces/AAAA1234"]
    }
  }
}

타겟 및 세션 라우팅

Google Chat 타겟은 발신 메시지와 세션 식별에 사용됩니다: • 다이렉트 메시지: users/<userId> 또는 users/<email> • 스페이스: spaces/<spaceId> 세션 키가 DM과 스페이스를 구분하여 각 대화가 독립된 컨텍스트를 갖도록 합니다. 봇 사용자 식별자(botUser)는 그룹 스페이스에서 @멘션 감지에 사용됩니다. 시스템 프롬프트와 접근 제어를 포함한 개별 스페이스의 사용자 정의 설정도 구성할 수 있습니다.
openclaw.json
{
  "channels": {
    "googlechat": {
      "botUser": "users/123456789",
      "spaces": {
        "spaces/AAAA1234": {
          "systemPrompt": "당신은 엔지니어링 팀을 위한 유용한 어시스턴트입니다."
        }
      }
    }
  }
}
botUser 필드를 설정하여 그룹 스페이스에서 정확한 @멘션 감지를 활성화하세요.
스페이스 ID는 Google Chat URL 또는 스페이스 메시지를 수신할 때 Gateway 로그에서 확인할 수 있습니다.

Google Chat 구성 참조

serviceAccountFile
Type: stringDefault: ""

Google Cloud 서비스 계정 JSON 키 파일 경로

audience
Type: stringDefault: "app-url"

Bearer 토큰 검증의 오디언스 유형. app-url이면 Google Chat이 OIDC ID 토큰을 보내고, project-number이면 자체 서명 JWT를 보냅니다. 옵션: app-url, project-number

audienceValue
Type: stringDefault: ""

토큰 검증에 사용되는 오디언스 값(URL 또는 프로젝트 번호)

webhookPath
Type: stringDefault: "/googlechat"

Google Chat Webhook 수신을 위한 HTTP 엔드포인트 경로

botUser
Type: stringDefault: ""

봇 사용자 식별자(users/<id>), 스페이스에서의 @멘션 감지용

dmPolicy
Type: stringDefault: "pairing"

봇에 DM을 보낼 수 있는 사용자를 제어. 옵션: pairing, allowlist, open, disabled

allowFrom
Type: string[]Default: []

봇에 메시지를 보낼 수 있는 사용자 ID 또는 이메일(dmPolicy가 allowlist일 때 적용)

groupPolicy
Type: stringDefault: "disabled"

그룹 스페이스 정책. 옵션: disabled, allowlist, open

groupAllowList
Type: string[]Default: []

groupPolicy가 allowlist일 때 허용되는 스페이스 ID

spaces.<id>.systemPrompt
Type: stringDefault: ""

특정 Google Chat 스페이스의 사용자 정의 AI 시스템 프롬프트

mediaMaxMb
Type: numberDefault: 20

최대 미디어 파일 크기(메가바이트)

actions.typing
Type: booleanDefault: true

AI가 응답을 생성하는 동안 타이핑 표시기 전송

Google Chat 자주 묻는 질문

Google Chat 문제 해결

Webhook에서 405 Method Not Allowed 오류

Google Chat 플러그인이 활성화되지 않았거나, channels.googlechat 구성 섹션이 누락되었거나, 구성 변경 후 Gateway가 재시작되지 않음.

구성 확인: 'openclaw config get channels.googlechat'를 실행하여 구성이 있는지 확인. 'openclaw plugins list | grep googlechat'를 실행하여 플러그인이 활성화되어 있는지 확인. 'openclaw gateway restart'로 Gateway를 재시작하고 'openclaw channels status'로 상태 확인.
인증 오류 또는 토큰 검증 실패

서비스 계정 파일 경로가 올바르지 않거나, 오디언스 설정이 일치하지 않거나, Bearer 토큰이 만료됨.

'openclaw channels status --probe'를 실행하여 인증 오류를 진단. serviceAccountFile 경로가 유효한 JSON 키 파일을 가리키는지 확인. 오디언스 유형과 값이 Google Cloud 프로젝트 구성과 일치하는지 확인.
봇이 스페이스의 메시지에 응답하지 않음

@멘션 감지를 위한 봇 사용자 식별자가 구성되지 않았거나 스페이스가 허용 목록에 없음.

구성에서 botUser 필드를 설정하여 정확한 @멘션 감지를 활성화. groupPolicy: allowlist를 사용하는 경우 스페이스 ID가 groupAllowList에 포함되어 있는지 확인. 테스트 메시지를 보내면서 'openclaw logs --follow'로 Gateway 로그 확인.
Webhook URL에 Google Chat에서 접근할 수 없음

공개 URL이 올바르게 구성되지 않았거나, 방화벽이 수신 연결을 차단하거나, SSL 인증서가 유효하지 않음.

Chat 앱의 Webhook URL이 Gateway의 공개 엔드포인트와 일치하는지 확인. URL이 인터넷에서 접근 가능한지 테스트. Tailscale Funnel을 사용하는 경우 'tailscale funnel status'를 실행하여 구성 확인. Caddy 또는 Cloudflare의 경우 리버스 프록시 로그 확인.
전체 문서 보기모든 채널로 돌아가기

관련 채널

Feishu / Lark

Medium

OpenClaw WebSocket을 통한 Feishu/Lark 통합

설정 가이드

Slack

Medium

OpenClaw Bolt SDK를 통한 워크스페이스 앱 통합

설정 가이드

Microsoft Teams

Medium

OpenClaw Bot Framework를 통한 엔터프라이즈 통합

설정 가이드