Merge pull request #1 from iHildy/feat/googlechat-user-oauth

Feat/googlechat user oauth
This commit is contained in:
Ian Hildebrand authored and GitHub committed 2026-01-26 20:46:17 -06:00
commit 538c41d2a9
18 files changed
+986 -42

No files matched your search

+82 -3
View File
@@ -5,9 +5,7 @@ read_when:
---
# Google Chat (Chat API)
Status: ready for DMs + spaces via Google Chat API webhooks (HTTP only).
## Quick setup (beginner)
## Service Account Setup
1) Create a Google Cloud project and enable the **Google Chat API**.
- Go to: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
- Enable the API if it is not already enabled.
@@ -46,6 +44,71 @@ Status: ready for DMs + spaces via Google Chat API webhooks (HTTP only).
8) Set the webhook audience type + value (matches your Chat app config).
9) Start the gateway. Google Chat will POST to your webhook path.
## User OAuth (optional, enables reactions)
Service account covers almost all features, but **reactions and user-attributed actions require user OAuth**.
### Option A: Use gog OAuth (recommended if you already use `gog`)
If you already use `gog` for Google Workspace, you can reuse its OAuth client + refresh token.
`gog` stores the OAuth client credentials JSON in your config directory and the refresh token in your system keyring.
1) Ensure `gog` is already authorized:
```bash
gog auth list
```
2) Configure Google Chat to reuse `gog`:
```json5
{
channels: {
googlechat: {
oauthFromGog: true,
// Optional when multiple gog clients or accounts are configured:
gogAccount: "you@example.com",
gogClient: "work"
}
}
}
```
3) Ensure `gog` can access its keyring on the gateway host.
- `gog` stores refresh tokens in the system keychain by default (not inside `credentials.json`).
- For headless systems (systemd, SSH-only), switch to file keyring + password (see `gog` docs).
- Set `GOG_KEYRING_BACKEND=file` and `GOG_KEYRING_PASSWORD=...` for the gateway service.
- The file keyring lives under your gog config directory (for example `~/.config/gogcli/keyring/`).
4) Verify `gog` is visible to clawdbot and ask it to run:
```bash
Run `gog auth tokens list --json` and tell me if you can access services.
```
This lists token keys only (no secrets). If this fails, install `gog` on the gateway host and ensure the keyring is accessible.
For non-interactive services, set `GOG_KEYRING_PASSWORD` in the gateway environment so `gog` can unlock the keyring.
5) Set `typingIndicator` to "reaction" in your clawdbot config.
```json5
{
channels: {
"googlechat": {
actions: { reactions: true },
typingIndicator: "reaction",
}
}
}
```
Clawdbot reads `gog` OAuth client files from:
- `~/.config/gogcli/credentials.json`
- `~/.config/gogcli/credentials-<client>.json`
- `~/.config/gogcli/credentials-<domain>.json` (or macOS equivalent)
Clawdbot queries `gog auth tokens list --json` to discover which account to use, then runs `gog auth tokens export <email> --out <tmp>` to read the refresh token. If you have multiple gog accounts, set `gogAccount` (or `GOG_ACCOUNT`) to pick the right one. If this fails, set `oauthRefreshToken` manually.
### Option B: Manual OAuth
1) Configure OAuth consent + create OAuth client credentials in your Google Cloud project (desktop app recommended).
2) Use an OAuth 2.0 flow to request **offline** access and collect a refresh token.
- Required scopes for reactions include:
- `https://www.googleapis.com/auth/chat.messages.reactions.create`
- `https://www.googleapis.com/auth/chat.messages.reactions`
- (or) `https://www.googleapis.com/auth/chat.messages`
3) Save the client credentials + refresh token in your config or env vars (examples below).
**Tip:** user OAuth actions are attributed to the user in Google Chat.
## Add to Google Chat
Once the gateway is running and your email is added to the visibility list:
1) Go to [Google Chat](https://chat.google.com/).
@@ -144,6 +207,17 @@ Use these identifiers for delivery and allowlists:
"googlechat": {
enabled: true,
serviceAccountFile: "/path/to/service-account.json",
// Optional: user OAuth for reactions + user-attributed actions
oauthClientFile: "/path/to/oauth-client.json",
oauthRefreshToken: "1//0g...",
// Or reuse gog:
// oauthFromGog: true,
// gogAccount: "you@example.com",
// gogClient: "work",
// Or explicit fields:
// oauthClientId: "123456.apps.googleusercontent.com",
// oauthClientSecret: "GOCSPX-...",
// oauthRedirectUri: "https://your.host/googlechat/oauth/callback",
audienceType: "app-url",
audience: "https://gateway.example.com/googlechat",
webhookPath: "/googlechat",
@@ -171,6 +245,11 @@ Use these identifiers for delivery and allowlists:
Notes:
- Service account credentials can also be passed inline with `serviceAccount` (JSON string).
- User OAuth can be provided via `oauthClientFile` + `oauthRefreshToken` or the explicit client fields.
- Env options (default account): `GOOGLE_CHAT_OAUTH_CLIENT_ID`, `GOOGLE_CHAT_OAUTH_CLIENT_SECRET`,
`GOOGLE_CHAT_OAUTH_REDIRECT_URI`, `GOOGLE_CHAT_OAUTH_CLIENT_FILE`,
`GOOGLE_CHAT_OAUTH_REFRESH_TOKEN`, `GOOGLE_CHAT_OAUTH_REFRESH_TOKEN_FILE`.
- `oauthFromGog` reuses the `gog` keyring. Use `gogAccount`/`gogClient` (or `GOG_ACCOUNT`/`GOG_CLIENT`) when multiple accounts or clients exist.
- Default webhook path is `/googlechat` if `webhookPath` isn’t set.
- Reactions are available via the `reactions` tool and `channels action` when `actions.reactions` is enabled.
- `typingIndicator` supports `none`, `message` (default), and `reaction` (reaction requires user OAuth).
+12
View File
@@ -1140,6 +1140,12 @@ Multi-account support lives under `channels.googlechat.accounts` (see the multi-
"googlechat": {
enabled: true,
serviceAccountFile: "/path/to/service-account.json",
oauthClientFile: "/path/to/oauth-client.json",
oauthRefreshToken: "1//0g...",
// Or reuse gog OAuth:
// oauthFromGog: true,
// gogAccount: "you@example.com",
// gogClient: "work",
audienceType: "app-url", // app-url | project-number
audience: "https://gateway.example.com/googlechat",
webhookPath: "/googlechat",
@@ -1164,6 +1170,12 @@ Multi-account support lives under `channels.googlechat.accounts` (see the multi-
Notes:
- Service account JSON can be inline (`serviceAccount`) or file-based (`serviceAccountFile`).
- Env fallbacks for the default account: `GOOGLE_CHAT_SERVICE_ACCOUNT` or `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
- User OAuth can be provided via `oauthClientFile` + `oauthRefreshToken` (or explicit client fields).
- Env fallbacks for user OAuth (default account): `GOOGLE_CHAT_OAUTH_CLIENT_ID`,
`GOOGLE_CHAT_OAUTH_CLIENT_SECRET`, `GOOGLE_CHAT_OAUTH_REDIRECT_URI`,
`GOOGLE_CHAT_OAUTH_CLIENT_FILE`, `GOOGLE_CHAT_OAUTH_REFRESH_TOKEN`,
`GOOGLE_CHAT_OAUTH_REFRESH_TOKEN_FILE`.
- `oauthFromGog` reuses `gog` OAuth credentials; `gogAccount`/`gogClient` (or `GOG_ACCOUNT`/`GOG_CLIENT`) select the account/client.
- `audienceType` + `audience` must match the Chat app’s webhook auth config.
- Use `spaces/<spaceId>` or `users/<userId|email>` when setting delivery targets.