Google Chat（Chat API）

ステータス：Google Chat APIウェブフック（HTTPのみ）によるDM＋スペースに対応。

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

  1. Google Cloudプロジェクトを作成し、Google Chat APIを有効化。
  2. サービスアカウントを作成：
    • Create Credentials > Service Accountを押下。
    • 任意の名前を設定（例：openclaw-chat）。
    • パーミッションは空白のまま（Continueを押下）。
    • アクセスプリンシパルは空白のまま（Doneを押下）。
  3. JSONキーを作成してダウンロード：
    • サービスアカウント一覧から、作成したアカウントをクリック。
    • Keysタブに移動。
    • Add Key > Create new keyをクリック。
    • JSONを選択してCreateを押下。
  4. ダウンロードしたJSONファイルをGatewayホストに保存（例：~/.openclaw/googlechat-service-account.json）。
  5. Google Cloud Console Chat ConfigurationでGoogle Chatアプリを作成：
    • Application infoを入力：
      • App name：（例：OpenClaw）
      • Avatar URL：（例：https://openclaw.ai/logo.png）
      • Description：（例：Personal AI Assistant）
    • Interactive featuresを有効化。
    • FunctionalityでJoin spaces and group conversationsにチェック。
    • Connection settingsでHTTP endpoint URLを選択。
    • TriggersでUse a common HTTP endpoint URL for all triggersを選択し、GatewayのパブリックURLの後に/googlechatを設定。
      • ヒント：openclaw statusでGatewayのパブリックURLを確認できます。
    • Visibilityで**Make this Chat app available to specific people and groups in <Your Domain>**にチェック。
    • メールアドレスを入力（例：[email protected]）。
    • 最下部のSaveをクリック。
  6. アプリステータスを有効化：
    • 保存後、ページを更新。
    • App statusセクションを探す。
    • ステータスをLive - available to usersに変更。
    • 再度Saveをクリック。
  7. OpenClawにサービスアカウントパス＋ウェブフックオーディエンスを設定：
    • 環境変数：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
    • または設定：channels.googlechat.serviceAccountFile: "/path/to/service-account.json"
  8. ウェブフックオーディエンスのタイプ＋値を設定（Chatアプリの設定に合わせます）。
  9. Gatewayを起動。Google Chatがウェブフックパスにリクエストを送信します。

Google Chatへの追加

Gatewayが実行中で、メールアドレスがビジビリティリストに追加された状態で：

  1. Google Chatにアクセス。
  2. ダイレクトメッセージの横にある**+**（プラス）アイコンをクリック。
  3. 検索バーに、Google Cloud Consoleで設定したApp nameを入力。
    • 注意：ボットはプライベートアプリのため「Marketplace」のブラウズリストには表示されません。名前で検索する必要があります。
  4. 結果からボットを選択。
  5. AddまたはChatをクリックして1:1の会話を開始。
  6. 「Hello」を送信してアシスタントを起動。

パブリックURL（ウェブフック専用）

Google ChatウェブフックにはパブリックHTTPSエンドポイントが必要です。セキュリティのため、/googlechatパスのみをインターネットに公開してください。OpenClawのダッシュボードやその他の機密エンドポイントはプライベートネットワーク上に保持してください。

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

Tailscale Serveをプライベートダッシュボードに、Funnelをパブリックウェブフックパスに使用します。これにより/はプライベートのまま、/googlechatのみが公開されます。

  1. Gatewayがバインドされているアドレスを確認：

    ss -tlnp | grep 18789

    IPアドレスを確認（例：127.0.0.1、0.0.0.0、またはTailscale IPの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のみにバインドされている場合（例：100.106.161.80）：
tailscale serve --bg --https 8443 http://100.106.161.80:18789

  3. ウェブフックパスのみをパブリックに公開：

    # 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

  4. Funnelアクセス用にノードを認可： プロンプトが表示された場合、出力に表示される認可URLにアクセスして、tailnetポリシーでこのノードのFunnelを有効化。

  5. 設定を確認：

    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

トンネルのイングレスルールをウェブフックパスのみルーティングするよう設定：

  • Path：/googlechat -> http://localhost:18789/googlechat
  • Default Rule：HTTP 404 (Not Found)

仕組み

  1. Google ChatがGatewayにウェブフックPOSTを送信します。各リクエストにはAuthorization: Bearer <token>ヘッダーが含まれます。
    • OpenClawはヘッダーが存在する場合、完全なウェブフックボディの読み取り/解析前にBearer認証を検証します。
    • authorizationEventObject.systemIdTokenをボディに含むGoogle Workspace Add-onリクエストは、より厳格なプリオースボディバジェットを介してサポートされます。
  2. OpenClawは設定されたaudienceType + audienceに対してトークンを検証します：
    • audienceType: "app-url" → オーディエンスはHTTPSウェブフックURL。
    • audienceType: "project-number" → オーディエンスはCloudプロジェクト番号。
  3. メッセージはスペースごとにルーティングされます：
    • DMはセッションキーagent:<agentId>:googlechat:direct:<spaceId>を使用。
    • スペースはセッションキーagent:<agentId>:googlechat:group:<spaceId>を使用。
  4. DMアクセスはデフォルトでペアリングです。未知の送信者にはペアリングコードが発行されます。以下で承認：
    • openclaw pairing approve googlechat <code>
  5. グループスペースはデフォルトで@メンションが必要です。メンション検出にアプリのユーザー名が必要な場合は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", // オプション。メンション検出に役立ちます
      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でアカウントごとのrefも使用可能。
  • webhookPathが未設定の場合、デフォルトのウェブフックパスは/googlechatです。
  • dangerouslyAllowNameMatchingは可変メールプリンシパルマッチングを許可リストで再有効化します（ブレークグラス互換モード）。
  • リアクションはactions.reactionsが有効な場合、reactionsツールとchannels actionで利用可能です。
  • 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

これはウェブフックハンドラーが登録されていないことを意味します。一般的な原因：

  1. チャンネルが未設定：設定にchannels.googlechatセクションがありません。以下で確認：

    openclaw config get channels.googlechat

    「Config path not found」が返された場合、設定を追加してください（設定のハイライトを参照）。

  2. プラグインが無効：プラグインのステータスを確認：

    openclaw plugins list | grep googlechat

    「disabled」と表示された場合、設定にplugins.entries.googlechat.enabled: trueを追加してください。

  3. Gatewayが再起動されていない：設定追加後、Gatewayを再起動：

    openclaw gateway restart

チャンネルが実行中か確認：

openclaw channels status
# 表示例：Google Chat default: enabled, configured, ...

その他の問題

  • openclaw channels status --probeで認証エラーや不足しているオーディエンス設定を確認。
  • メッセージが届かない場合、Chatアプリのウェブフックurl＋イベントサブスクリプションを確認。
  • メンションゲーティングが返信をブロックする場合、botUserをアプリのユーザーリソース名に設定し、requireMentionを確認。
  • テストメッセージ送信時にopenclaw logs --followを使用してリクエストがGatewayに到達しているか確認。

関連ドキュメント：

arrow_back
前へ
Feishu
次へ
Imessage
arrow_forward