Google Chat을 AI 어시스턴트로 연결하기

매번 AI를 사용하기 위해 새로운 브라우저 탭을 열거나 별도의 앱을 실행하는 일은 꽤 번거로운 작업이에요. 우리가 매일 사용하는 업무용 메신저 안에서 AI가 바로 대답해준다면 업무 흐름을 끊지 않고도 필요한 도움을 받을 수 있죠. 하지만 막상 직접 연결하려고 하면 Webhook 설정이나 보안 인증 단계에서 막막함을 느끼기 쉽습니다.

필요한 것

시작하기 전에 소스 문서에서 언급된 다음 항목들이 준비되었는지 확인해 주세요.

• Google Cloud 프로젝트
• 활성화된 Google Chat API
• Service Account (JSON 키 파일)
• OpenClaw가 실행될 Gateway 호스트

빠른 시작

5분 안에 Google Chat과 AI를 연결하는 최소 경로입니다. 단계를 차근차근 따라와 주세요.

1. Google Cloud 프로젝트 설정: Google Chat API Credentials 페이지로 이동해서 API를 활성화하세요.
2. Service Account 생성: Create Credentials > Service Account를 선택하세요. 이름은 openclaw-chat처럼 자유롭게 정하고, 권한과 액세스 설정은 비워둔 채로 완료하세요.
3. JSON 키 다운로드: 생성한 서비스 계정의 Keys 탭에서 Add Key > Create new key를 누르세요. JSON 형식을 선택하고 파일을 다운로드합니다.
4. 키 저장: 다운로드한 JSON 파일을 Gateway 호스트의 특정 경로(예: ~/.openclaw/googlechat-service-account.json)에 저장하세요.
5. Chat 앱 구성: Google Cloud Console Chat Configuration에서 앱 정보를 입력하세요.
   • Interactive features를 활성화하세요.
   • Functionality에서 Join spaces and group conversations를 체크하세요.
   • Connection settings에서 HTTP endpoint URL을 선택하고, Gateway의 퍼블릭 URL 뒤에 /googlechat을 붙여 입력하세요.
   • Visibility에서 본인의 이메일을 추가하세요.
6. 앱 상태 변경: 저장을 누른 후 페이지를 새로고침하세요. App status를 Live - available to users로 변경하고 다시 저장하세요.
7. OpenClaw 설정: 환경 변수나 설정 파일에 서비스 계정 경로를 추가하세요.
   • Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
   • Config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json"
8. Audience 설정: Chat 앱 설정과 일치하도록 audienceType과 값을 설정하세요.
9. Gateway 시작: 이제 Google Chat이 여러분의 Webhook 경로로 POST 요청을 보낼 거예요.

Google Chat에서 대화 시작하기

Gateway가 실행 중이고 이메일이 등록되었다면 바로 테스트해 볼 수 있어요.

1. Google Chat에 접속하세요.
2. Direct Messages 옆의 + 아이콘을 클릭하세요.
3. 설정한 App name을 검색하세요. (비공개 앱이라 목록에 바로 뜨지 않으니 이름을 직접 입력해야 해요.)
4. 봇을 선택하고 Chat을 눌러 대화를 시작하세요. “Hello”라고 보내면 AI가 응답할 거예요!

Public URL 설정하기 (추천 방식)

Google Chat Webhook은 퍼블릭 HTTPS 엔드포인트가 꼭 필요해요. 보안을 위해 /googlechat 경로만 인터넷에 노출하는 것이 좋습니다.

Tailscale Funnel 사용 (권장)

Tailscale을 사용하면 대시보드는 비공개로 유지하면서 Webhook 경로만 안전하게 공개할 수 있어요.

1. Gateway 바인딩 주소 확인:

   ss -tlnp | grep 18789

2. Webhook 경로만 공개:

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

3. 상태 확인:

   tailscale funnel status

   퍼블릭 URL은 https://<node-name>.<tailnet>.ts.net/googlechat 형태가 됩니다. 이 주소를 Google Chat 앱 설정에 입력하세요.

Config Highlights

설정 파일의 주요 예시입니다.

{
  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", "name@example.com"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          allow: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

문제 해결

405 Method Not Allowed

Google Cloud 로그에 405 Method Not Allowed 에러가 보인다면 Webhook 핸들러가 제대로 등록되지 않은 상태예요.

1. 채널 설정 확인: channels.googlechat 섹션이 설정 파일에 있는지 확인하세요.

   openclaw config get channels.googlechat

2. 플러그인 활성화 확인: 플러그인이 비활성화되어 있는지 확인하세요.

   openclaw plugins list | grep googlechat

3. Gateway 재시작: 설정을 변경했다면 반드시 재시작해야 합니다.

   openclaw gateway restart

설정이나 인증에 문제가 있다면 openclaw channels status --probe 명령어로 더 자세한 정보를 확인할 수 있어요.

설정 과정에서 도움이 더 필요하신가요? AI Setup Assistant에게 질문해 보세요.

다음 단계

• Gateway configuration
• Security
• Reactions