Google Chat（Chat API）

狀態：私訊和空間已就緒，透過 Google Chat API webhook（僅 HTTP）。

快速設定（入門）

  1. 建立 Google Cloud 專案並啟用 Google Chat API。
  2. 建立服務帳號：
    • 按下建立憑證 > 服務帳號。
    • 命名為任意名稱（例如 openclaw-chat）。
    • 權限留空（按繼續）。
    • 存取主體留空（按完成）。
  3. 建立並下載 JSON 金鑰：
    • 在服務帳號清單中，點擊你剛建立的帳號。
    • 前往金鑰分頁。
    • 點擊新增金鑰 > 建立新金鑰。
    • 選擇 JSON 並按建立。
  4. 將下載的 JSON 檔案存放在 Gateway 主機上（例如 ~/.openclaw/googlechat-service-account.json）。
  5. 在 Google Cloud Console Chat Configuration 中建立 Google Chat 應用程式：
    • 填寫應用程式資訊：
      • 應用程式名稱：（例如 OpenClaw）
      • 頭像 URL：（例如 https://openclaw.ai/logo.png）
      • 說明：（例如 Personal AI Assistant）
    • 啟用互動功能。
    • 在功能下，勾選加入空間和群組對話。
    • 在連接設定下，選擇HTTP 端點 URL。
    • 在觸發條件下，選擇為所有觸發條件使用通用 HTTP 端點 URL，並設定為你的 Gateway 公開 URL 加上 /googlechat。
      • 提示：執行 openclaw status 以查詢你的 Gateway 公開 URL。
    • 在可見性下，勾選讓此 Chat 應用程式僅供 <你的網域> 中的特定人員和群組使用。
    • 在文字框中輸入你的電子郵件地址（例如 [email protected]）。
    • 按底部的儲存。
  6. 啟用應用程式狀態：
    • 儲存後重新整理頁面。
    • 尋找應用程式狀態區段（通常在儲存後的頂部或底部）。
    • 將狀態變更為上線 - 可供使用者使用。
    • 再次按儲存。
  7. 使用服務帳號路徑和 webhook audience 設定 OpenClaw：
    • 環境變數：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
    • 或設定：channels.googlechat.serviceAccountFile: "/path/to/service-account.json"
  8. 設定 webhook audience 類型和值（與你的 Chat 應用程式設定匹配）。
  9. 啟動 Gateway。Google Chat 將 POST 到你的 webhook 路徑。

加入 Google Chat

當 Gateway 正在運行且你的電子郵件已加入可見性清單後：

  1. 前往 Google Chat。
  2. 點擊私訊旁的 +（加號）圖示。
  3. 在搜尋列中（通常用於新增人員的地方），輸入你在 Google Cloud Console 中設定的應用程式名稱。
    • 注意：機器人_不會_出現在「Marketplace」瀏覽清單中，因為它是私人應用程式。你必須按名稱搜尋。
  4. 從結果中選擇你的機器人。
  5. 點擊新增或聊天開始一對一對話。
  6. 發送「Hello」來觸發助理！

公開 URL（僅 Webhook）

Google Chat webhook 需要公開 HTTPS 端點。為了安全，只將 /googlechat 路徑暴露到網際網路。將 OpenClaw 儀表板和其他敏感端點保留在私人網路上。

選項 A：Tailscale Funnel（推薦）

使用 Tailscale Serve 作為私人儀表板，使用 Funnel 作為公開 webhook 路徑。這樣可以保持 / 私密，只暴露 /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. 僅公開暴露 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（例如 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

你的公開 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

設定你的 tunnel 入口規則，只路由 webhook 路徑：

  • 路徑：/googlechat -> http://localhost:18789/googlechat
  • 預設規則：HTTP 404（Not Found）

運作方式

  1. Google Chat 向 Gateway 發送 webhook POST。每個請求都包含 Authorization: Bearer <token> 標頭。
    • 當標頭存在時，OpenClaw 在讀取/解析完整 webhook 本體前先驗證 bearer 認證。
    • 在本體中攜帶 authorizationEventObject.systemIdToken 的 Google Workspace Add-on 請求透過更嚴格的預認證本體預算支援。
  2. OpenClaw 根據設定的 audienceType + audience 驗證 token：
    • audienceType: "app-url" → audience 是你的 HTTPS webhook URL。
    • audienceType: "project-number" → audience 是 Cloud 專案編號。
  3. 訊息按空間路由：
    • 私訊使用工作階段鍵 agent:<agentId>:googlechat:direct:<spaceId>。
    • 空間使用工作階段鍵 agent:<agentId>:googlechat:group:<spaceId>。
  4. 私訊存取預設為配對模式。未知發送者會收到配對代碼；透過以下方式核准：
    • 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",
      // 或 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（環境變數/檔案 SecretRef），包括 channels.googlechat.accounts.<id>.serviceAccountRef 下的按帳號參考。
  • 如果未設定 webhookPath，預設 webhook 路徑為 /googlechat。
  • dangerouslyAllowNameMatching 重新啟用可變電子郵件主體匹配用於許可清單（緊急相容模式）。
  • 表情回應可透過 reactions 工具和 channels action（當 actions.reactions 啟用時）使用。
  • typingIndicator 支援 none、message（預設）和 reaction（reaction 需要使用者 OAuth）。
  • 附件透過 Chat API 下載並儲存在媒體管線中（大小受 mediaMaxMb 限制）。

Secrets 參考詳情：Secrets 管理。

疑難排解

405 Method Not Allowed

如果 Google Cloud Logs Explorer 顯示如下錯誤：

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

這表示 webhook 處理器未註冊。常見原因：

  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 以查看認證錯誤或缺少的 audience 設定。
  • 如果沒有訊息送達，確認 Chat 應用程式的 webhook URL 和事件訂閱。
  • 如果提及管控封鎖了回覆，設定 botUser 為應用程式的使用者資源名稱並驗證 requireMention。
  • 發送測試訊息時使用 openclaw logs --follow 查看請求是否到達 Gateway。

相關文件：

arrow_back
上一頁
Feishu
下一頁
Imessage
arrow_forward