Google Chat

​

インストール

openclaw plugins install @openclaw/googlechat

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

​

クイックセットアップ（初心者向け）

1. Google Cloud プロジェクトを作成し、Google Chat API を有効にします。
   • 移動先: Google Chat API 認証情報
   • API がまだ有効でない場合は有効にします。
2. サービスアカウントを作成します:
   • 認証情報を作成 > サービスアカウントを押します。
   • 任意の名前を付けます（例: openclaw-chat）。
   • 権限とプリンシパルは空のままにします（続行、次に 完了）。
3. JSON キーを作成してダウンロードします:
   • 新しいサービスアカウント > キータブ > キーを追加 > 新しいキーを作成 > JSON > 作成をクリックします。
4. ダウンロードした JSON ファイルを Gateway ホストに保存します（例: ~/.openclaw/googlechat-service-account.json）。
5. Google Cloud Console Chat Configuration で Google Chat アプリを作成します:
   • アプリケーション情報（アプリ名、アバター URL、説明）を入力します。
   • インタラクティブ機能を有効にします。
   • 機能で、スペースとグループ会話に参加するにチェックを入れます。
   • 接続設定で、HTTP エンドポイント URLを選択します。
   • トリガーで、すべてのトリガーに共通の HTTP エンドポイント URL を使用するを選択し、公開 Gateway URL の後に /googlechat を付けたものに設定します（公開 URL を参照）。
   • 公開設定で、この Chat アプリを <Your Domain> 内の特定のユーザーとグループに公開するにチェックを入れ、メールアドレスを入力します。
   • 保存をクリックします。
6. アプリのステータスを有効にします: ページを更新し、アプリのステータスを見つけ、ライブ - ユーザーが利用可能に設定し、もう一度保存します。
7. サービスアカウントと Webhook オーディエンス（Chat アプリ設定と一致している必要があります）で OpenClaw を設定します:
   • 環境変数: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json（デフォルトアカウントのみ）、または
   • 設定: 設定の要点 を参照してください。openclaw channels add --channel googlechat は --audience-type、--audience、--webhook-path、--webhook-url も受け付けます。
8. Gateway を起動します。Google Chat は Webhook パス（デフォルト /googlechat）に POST します。

​

Google Chat に追加

1. Google Chat に移動します。
2. ダイレクト メッセージの横にある +（プラス）アイコンをクリックします。
3. Google Cloud Console で設定したアプリ名を検索します。
   • 非公開アプリであるため、ボットは Marketplace の参照リストには表示されません。名前で検索してください。
4. ボットを選択し、追加またはチャットをクリックして、メッセージを送信します。

​

公開 URL（Webhook のみ）

​

オプション A: Tailscale Funnel（推奨）

1. Gateway がバインドされているアドレスを確認します:
   ss -tlnp | grep 18789
   
   IP をメモします（例: 127.0.0.1、0.0.0.0、または Tailscale の 100.x.x.x アドレス）。
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 のみにバインドされている場合:
   tailscale serve --bg --https 8443 http://100.x.x.x: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 のみにバインドされている場合:
   tailscale funnel --bg --set-path /googlechat http://100.x.x.x:18789/googlechat
   
4. プロンプトが表示された場合は、出力に表示された認可 URL にアクセスして、このノードで Funnel を有効にします。
5. 確認します:
   tailscale serve status
   tailscale funnel status
   

注: この設定は再起動後も保持されます。後で削除するには tailscale funnel reset と tailscale serve reset を使用します。

​

オプション B: リバースプロキシ（Caddy）

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

​

オプション C: Cloudflare Tunnel

• パス: /googlechat -> http://localhost:18789/googlechat
• デフォルトルール: HTTP 404（Not Found）

​

仕組み

1. Google Chat は Gateway Webhook パスに JSON を POST します（POST のみ、JSON content type が必須、IP ごとのレート制限あり）。
2. OpenClaw はディスパッチ前にすべてのリクエストを認証します:
   • Chat アプリイベントは Authorization: Bearer <token> を保持します。完全な本文が解析される前にトークンが検証されます。
   • Google Workspace アドオンイベントは本文内（authorizationEventObject.systemIdToken）にトークンを保持し、検証前により厳しい事前認証予算（16 KB、3 秒）の下で読み取られます。
3. トークンは audienceType + audience に対してチェックされます:
   • audienceType: "app-url" → オーディエンスは HTTPS Webhook URL です。
   • audienceType: "project-number" → オーディエンスは Cloud プロジェクト番号です。
   • app-url 下のアドオントークンでは、さらに appPrincipal をアプリの数値 OAuth 2.0 クライアント ID（21 桁、メールではありません）に設定する必要があります。設定されていない場合、検証はログ警告付きで失敗します。
4. メッセージはスペースごとにルーティングされます:
   • スペースはスペースごとのセッション agent:<agentId>:googlechat:group:<spaceId> を取得します。返信はメッセージスレッドに送られます。
   • DM はデフォルトでエージェントのメインセッションに統合されます。ピアごとの DM セッションには session.dmScope を設定します（セッション を参照）。
5. DM アクセスはデフォルトでペアリングです。不明な送信者にはペアリングコードが送信されます。次で承認します:
   • openclaw pairing approve googlechat <code>
6. グループスペースではデフォルトで @メンションが必要です。メンションはアプリを対象とする Chat USER_MENTION アノテーションから検出されます。検出にアプリのユーザーリソース名が必要な場合は botUser（例: users/1234567890）を設定します。
7. Google Chat から exec または Plugin 承認が開始され、安定した users/<id> 承認者が設定されている場合、OpenClaw は発生元のスペースまたはスレッドにネイティブ承認カード（cardsV2）を投稿します。カードボタンは不透明なコールバックトークンを持ちます。ネイティブ配信を利用できない場合にのみ、手動の /approve <id> <decision> プロンプトが表示されます。

​

ターゲット

• ダイレクトメッセージ: users/<userId>（推奨）。
• スペース: spaces/<spaceId>。
• 生のメール name@example.com は可変であり、channels.googlechat.dangerouslyAllowNameMatching: true の場合にのみ許可リスト照合に使用されます。
• 非推奨: users/<email> はメール許可リストエントリではなく、ユーザー ID として扱われます。
• プレフィックス googlechat:、google-chat:、gchat: は受け付けられ、取り除かれます。

​

設定の要点

{
  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",
      appPrincipal: "123456789012345678901", // add-on verification only; numeric OAuth client ID
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; helps mention detection
      allowBots: false,
      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,
    },
  },
}

• サービスアカウント認証情報: serviceAccountFile（パス）、serviceAccount（インライン JSON 文字列またはオブジェクト）、または serviceAccountRef（env/file SecretRef）。環境変数 GOOGLE_CHAT_SERVICE_ACCOUNT（インライン JSON）と GOOGLE_CHAT_SERVICE_ACCOUNT_FILE（パス）はデフォルトアカウントにのみ適用されます。複数アカウント設定では、アカウントごとの serviceAccountRef を含め、同じキーで channels.googlechat.accounts.<id> を使用します。
• デフォルトの Webhook パスは、webhookPath が未設定の場合 /googlechat です。webhookUrl は代わりにパスを提供できます。
• グループキーは安定したスペース ID（spaces/<spaceId>）である必要があります。表示名キーは非推奨であり、その旨がログに記録されます。
• dangerouslyAllowNameMatching は、許可リストに対する可変メールプリンシパル照合を再度有効にします（緊急互換モード）。doctor はメールエントリについて警告します。
• リアクションはデフォルトで有効で、reactions ツールと channels action を通じて公開されます。無効にするには actions.reactions: false を使用します。
• ネイティブ承認カードは、リアクションイベントではなく Google Chat cardsV2 ボタンクリックを使用します。承認者は dm.allowFrom または defaultTo から取得され、安定した数値の users/<id> 値である必要があります。
• メッセージアクションは、テキスト用の send と、明示的な添付送信用の upload-file を公開します。upload-file は media / filePath / path に加え、任意の message、filename、スレッドターゲット（threadId / replyTo）を受け付けます。
• typingIndicator: message（デフォルト）は _<Bot> is typing..._ プレースホルダーを投稿し、最初の返信に編集します。none は無効化します。reaction はユーザー OAuth が必要で、現在はサービスアカウント認証ではログエラー付きで message にフォールバックします。
• 受信添付（メッセージごとの最初の添付）は Chat API 経由でメディアパイプラインにダウンロードされ、mediaMaxMb（デフォルト 20）で上限設定されます。
• ボット作成メッセージはデフォルトで無視されます。allowBots: true の場合、受け付けられたボットメッセージは共有のボットループ保護を使用します。channels.defaults.botLoopProtection を設定し、次に channels.googlechat.botLoopProtection または channels.googlechat.groups.<space>.botLoopProtection で上書きします。

​

トラブルシューティング

​

405 Method Not Allowed

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

1. チャンネルが設定されていない: channels.googlechat セクションがありません。次で確認します:
   openclaw config get channels.googlechat
   
   “Config path not found” が返る場合は、設定を追加します（設定の要点 を参照）。
2. Plugin が有効でない: Plugin のステータスを確認します:
   openclaw plugins list | grep googlechat
   
   “disabled” が表示される場合は、設定に plugins.entries.googlechat.enabled: true を追加します。
3. 設定変更後に Gateway が再起動されていない:
   openclaw gateway restart
   

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

​

その他の問題

• openclaw channels status --probe は認証エラーと不足しているオーディエンス設定を表示します（audience と audienceType はどちらも必須です）。
• メッセージが届かない場合は、Chat アプリの Webhook URL とトリガー設定を確認します。
• メンションゲーティングが返信をブロックする場合は、botUser をアプリのユーザーリソース名に設定し、requireMention を確認します。
• テストメッセージの送信中に openclaw logs --follow を実行すると、リクエストが Gateway に到達しているかどうかが表示されます。

​

関連

• チャネル概要 — サポートされているすべてのチャネル
• チャネルルーティング — メッセージのセッションルーティング
• Gateway 設定
• グループ — グループチャットの動作とメンションによるゲート制御
• ペアリング — DM 認証とペアリングフロー
• リアクション
• セキュリティ — アクセスモデルと堅牢化