Set Up Google Chat

Google Chat support is experimental for OpenClaw and Hermes sandboxes.

OpenClaw receives events at /googlechat on its dashboard port.

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.

Choose an HTTP endpoint connection in Google Chat API > Configuration > Connection settings.

Prepare the Public Webhook

The default app-url audience flow starts a dedicated cloudflared service in front of a loopback-only webhook proxy. The proxy forwards only POST /googlechat to OpenClaw and limits webhook request bodies to 1 MiB. It is separate from nemoclaw tunnel start, which remains the explicit full-dashboard tunnel command. Install cloudflared on the host before enrollment when you do not already have a public endpoint.

When the dedicated Google Chat tunnel is not running, NemoClaw starts it and prints the HTTPS endpoint ending in /googlechat. Copy that complete URL into the Google Chat API HTTP endpoint field without adding a trailing slash, then confirm the prompt. NemoClaw stops the dedicated tunnel and webhook proxy if you do not confirm the endpoint or if enrollment fails before confirmation.

If a later enrollment step fails after you confirm the endpoint, stop the public endpoint from the host:

nemoclaw my-assistant channels remove googlechat

Replace my-assistant with your sandbox name. The command attempts endpoint teardown even when interrupted enrollment left no Google Chat registry record. If the command reports that it could not stop the tunnel, correct the host service and run the command again before retrying enrollment. A removal that completes without cleanup warnings stops the dedicated tunnel and webhook proxy, removes any partial bridge provider and policy preset, and removes Google Chat from the durable messaging plan.

If GOOGLECHAT_AUDIENCE already contains the public webhook URL, NemoClaw uses it and does not start or change cloudflared. Do not point the public tunnel directly at the OpenClaw dashboard on 127.0.0.1:18789. Put a route-restricted proxy between the public tunnel and OpenClaw.

Before enrollment, run this check from the trusted host:

(
  set -eu
  webhook_origin="$(
    node -e '
      try {
        const url = new URL(process.argv[1]);
        if (url.protocol !== "https:" || url.pathname !== "/googlechat") process.exit(1);
        process.stdout.write(url.origin);
      } catch {
        process.exit(1);
      }
    ' "${GOOGLECHAT_AUDIENCE:?Set GOOGLECHAT_AUDIENCE first.}"
  )"
  check_denied_route() {
    label="$1"
    shift
    status="$(curl --silent --show-error --max-time 10 --output /dev/null --write-out '%{http_code}' "$@" || true)"
    if [ "$status" != "404" ]; then
      printf '%s failed route restriction: HTTP %s\n' "$label" "${status:-no-status}" >&2
      exit 1
    fi
    printf '%s denied: HTTP 404\n' "$label"
  }
  check_denied_route "Control UI" "$webhook_origin/"
  check_denied_route "Health route" "$webhook_origin/health"
  check_denied_route "GET /googlechat" "$GOOGLECHAT_AUDIENCE"
  check_denied_route "WebSocket route" \
    --http1.1 \
    --header 'Connection: Upgrade' \
    --header 'Upgrade: websocket' \
    --header 'Sec-WebSocket-Key: MDAwMDAwMDAwMDAwMDAwMA==' \
    --header 'Sec-WebSocket-Version: 13' \
    "$webhook_origin/ws"
)

Expected output:

Control UI denied: HTTP 404
Health route denied: HTTP 404
GET /googlechat denied: HTTP 404
WebSocket route denied: HTTP 404

The automatic NemoClaw proxy returns HTTP 404 for all four checks. Accept an operator-managed endpoint only when all four checks print HTTP 404. Do not enroll Google Chat if a check returns another status or no status.

Google Chat enrollment always requires an interactive terminal. Supported non-interactive onboarding skips the channel, because the Console endpoint and app principal steps need an operator.

Configure Access

Leave GOOGLECHAT_ALLOWED_USERS empty to use OpenClaw’s manual DM pairing flow. To use an allowlist, set it to comma-separated Google Chat user IDs such as users/123456789, not email addresses. Google Chat email addresses do not match this ID-based allowlist.

Google Workspace accounts do not need GOOGLECHAT_APP_PRINCIPAL. Leave that prompt empty unless you use a personal or standalone Google account.

Enable Google Chat

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

nemoclaw 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 to confirm the public endpoint and configure the optional app principal. OpenShell mints the token with the chat.bot scope. The channel policy permits Node.js to read the Google Chat REST API and to create, update, or delete messages under the /v1/spaces/ tree. It also permits Node.js GET requests to any path on www.googleapis.com because the Google authentication library controls the public certificate URL used to verify inbound event tokens.

Complete Personal Account Discovery

Personal or standalone Google accounts need the add-on’s numeric app principal. This value is a Google-assigned numeric ID, not an email address.

If you do not know the value, leave GOOGLECHAT_APP_PRINCIPAL empty during the first enrollment, then start the rebuilt sandbox and follow these steps:

1. Watch the OpenClaw logs for the discovery message.

   nemoclaw my-assistant logs --follow | grep "unexpected add-on principal"

2. Send one direct message to the bot. The bot does not reply during this discovery attempt.

3. Copy the numeric value from unexpected add-on principal: <value>.

4. Re-add the channel with the value and accept the rebuild prompt.

   GOOGLECHAT_APP_PRINCIPAL="<numeric-id>" nemoclaw my-assistant channels add googlechat

The re-add flow prompts for the service-account JSON again when it is not already present in the current host environment.

Verify the Channel

After the rebuild, send a direct message from an allowed or paired account and confirm that OpenClaw replies. If an unknown sender receives a pairing code, approve it through the registered OpenClaw sandbox that has a selected owning managed gateway:

nemoclaw my-assistant exec -- openclaw pairing approve googlechat <code>

After OpenClaw commits the sender to its owner allowlist, NemoClaw verifies the mutable config permissions and automatically restarts that selected gateway. An exit status of 0 means activation completed, so the sender’s next message should receive a reply without another manual restart. If permission cleanup or gateway restart fails after the approval commits, exec exits with status 1 and reports that the approval was not rolled back. For a selected owning gateway, it prints the managed recovery command; correct any reported permission problem, then run nemoclaw my-assistant gateway restart before testing the next message. If no owning managed gateway is registered, NemoClaw does not attempt activation or print that command; register and select the sandbox’s owning gateway before recovery. Do not submit the pairing code again unless OpenClaw reports that it was not accepted.

If the webhook returns an error, verify that the public endpoint still ends in /googlechat, the dedicated tunnel and webhook proxy are running, and the Google Chat API configuration contains the same URL.

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.