Manage SandboxesMessaging Channels

Set Up Google Chat

View as Markdown

Google Chat support is experimental for OpenClaw and Hermes sandboxes.

Hermes pulls events from a Google Cloud Pub/Sub subscription over REST.

Both agents send replies through the Google Chat API.

Prepare the Google Cloud Configuration

Prepare the Google Cloud resources before you enable the channel.

  • Enable the Google Chat API and configure the Chat app that the sandbox will run.
  • Create a service account and download a JSON key. The JSON must contain non-empty client_email and private_key string fields.
  • Minify the service-account JSON to one line before you paste it at the GOOGLECHAT_SERVICE_ACCOUNT prompt.

Keep the JSON key available on the trusted host during enrollment. Do not copy it into the sandbox or the agent configuration.

Prepare Pub/Sub Delivery

Create or select a Pub/Sub topic for Google Chat events and bind a pull subscription to that topic. Record the Google Cloud project ID and the complete subscription name in the form projects/<project>/subscriptions/<subscription>. The service account must be authorized to pull and acknowledge messages from the subscription.

Grant the Chat app’s publisher principal the roles/pubsub.publisher role on the topic. Use the principal that matches the app type:

  • Interactive features: service-<projectNumber>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com
  • Classic bot: chat-api-push@system.gserviceaccount.com

Google Chat shows the applicable connection in Google Chat API > Configuration > Connection settings. A missing publisher grant can leave the channel connected without delivering events.

Configure Hermes Access

Set GOOGLECHAT_ALLOWED_USERS to a comma-separated list of Google account email addresses that may message the bot. Hermes ignores OpenClaw-style users/NNN identifiers.

Enable Google Chat

For a new sandbox, run nemohermes onboard and select Google Chat in the messaging picker. For an existing sandbox, run:

$nemohermes my-assistant channels add googlechat

Paste the service-account JSON, configure the agent-specific inputs, and rebuild the sandbox. NemoClaw applies the googlechat network policy preset and registers a sandbox-scoped <sandbox>-googlechat-bridge provider with OpenShell.

OpenShell uses the service-account key as gateway-side refresh material to mint short-lived tokens. NemoClaw passes the private key to the OpenShell command through an ephemeral child-process environment value, not through a command-line argument. The service-account private key does not enter the sandbox, and the OpenShell proxy inserts the minted bearer token into approved Google API requests. The Google Chat policy does not rewrite request bodies with credentials.

Follow the prompts for the Google Cloud project ID, complete Pub/Sub subscription name, and email sender allowlist. Hermes does not create or require a public webhook endpoint. OpenShell mints one token with the chat.bot and pubsub scopes and inserts it into approved requests to chat.googleapis.com and pubsub.googleapis.com. The policy permits only Pub/Sub pull and acknowledge operations for the configured transport, plus the Google Chat REST operations used for replies.

Verify the Channel

After the rebuild, send a direct message from an email address in GOOGLECHAT_ALLOWED_USERS and confirm that Hermes replies. If no event arrives, inspect the sandbox logs and confirm the project ID, complete subscription name, subscription access, and topic publisher grant. Hermes retries transient REST pull failures, and Pub/Sub redelivers a message when Hermes does not acknowledge it.

Refer to Manage Messaging Channels to stop, start, or remove Google Chat after setup. That page explains how each command affects the bridge provider, service-account refresh material, and agent-specific inbound path.