docs(google-meet): add setup troubleshooting

2026-05-06 09:30:43 +00:00 · 2026-04-24 20:27:55 +01:00
parent b9cc293167
commit ef9ca09b8e
1 changed files with 217 additions and 0 deletions
--- a/docs/plugins/google-meet.md
+++ b/docs/plugins/google-meet.md
@@ -71,6 +71,11 @@ Check setup:
 openclaw googlemeet setup
 ```

+The setup output is meant to be agent-readable. It reports Chrome profile,
+audio bridge, node pinning, delayed realtime intro, and, when Twilio delegation
+is configured, whether the `voice-call` plugin and Twilio credentials are ready.
+Treat any `ok: false` check as a blocker before asking an agent to join.
+
 Join a meeting:

 ```bash
@@ -294,6 +299,58 @@ instead of silently joining without an audio path.
 Twilio transport is a strict dial plan delegated to the Voice Call plugin. It
 does not parse Meet pages for phone numbers.

+Use this when Chrome participation is not available or you want a phone dial-in
+fallback. Google Meet must expose a phone dial-in number and PIN for the
+meeting; OpenClaw does not discover those from the Meet page.
+
+Enable the Voice Call plugin on the Gateway host, not on the Chrome node:
+
+```json5
+{
+  plugins: {
+    allow: ["google-meet", "voice-call"],
+    entries: {
+      "google-meet": {
+        enabled: true,
+        config: {
+          defaultTransport: "chrome-node",
+          // or set "twilio" if Twilio should be the default
+        },
+      },
+      "voice-call": {
+        enabled: true,
+        config: {
+          provider: "twilio",
+        },
+      },
+    },
+  },
+}
+```
+
+Provide Twilio credentials through environment or config. Environment keeps
+secrets out of `openclaw.json`:
+
+```bash
+export TWILIO_ACCOUNT_SID=AC...
+export TWILIO_AUTH_TOKEN=...
+export TWILIO_FROM_NUMBER=+15550001234
+```
+
+Restart or reload the Gateway after enabling `voice-call`; plugin config changes
+do not appear in an already running Gateway process until it reloads.
+
+Then verify:
+
+```bash
+openclaw config validate
+openclaw plugins list | grep -E 'google-meet|voice-call'
+openclaw googlemeet setup
+```
+
+When Twilio delegation is wired, `googlemeet setup` includes successful
+`twilio-voice-call-plugin` and `twilio-voice-call-credentials` checks.
+
 ```bash
 openclaw googlemeet join https://meet.google.com/abc-defg-hij \
  --transport twilio \
@@ -447,6 +504,11 @@ Twilio-only config:
 }
 ```

+`voiceCall.enabled` defaults to `true`; with Twilio transport it delegates the
+actual PSTN call and DTMF to the Voice Call plugin. If `voice-call` is not
+enabled, Google Meet can still validate and record the dial plan, but it cannot
+place the Twilio call.
+
 ## Tool

 Agents can use the `google_meet` tool:
@@ -526,6 +588,161 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
  --message "Say exactly: I'm here and listening."
 ```

+## Live test checklist
+
+Use this sequence before handing a meeting to an unattended agent:
+
+```bash
+openclaw googlemeet setup
+openclaw nodes status
+openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
+  --transport chrome-node \
+  --message "Say exactly: Google Meet speech test complete."
+```
+
+Expected Chrome-node state:
+
+- `googlemeet setup` is all green.
+- `nodes status` shows the selected node connected.
+- The selected node advertises both `googlemeet.chrome` and `browser.proxy`.
+- The Meet tab joins the call and `test-speech` returns Chrome health with
+  `inCall: true`.
+
+For a Twilio smoke, use a meeting that exposes phone dial-in details:
+
+```bash
+openclaw googlemeet setup
+openclaw googlemeet join https://meet.google.com/abc-defg-hij \
+  --transport twilio \
+  --dial-in-number +15551234567 \
+  --pin 123456
+```
+
+Expected Twilio state:
+
+- `googlemeet setup` includes green `twilio-voice-call-plugin` and
+  `twilio-voice-call-credentials` checks.
+- `voicecall` is available in the CLI after Gateway reload.
+- The returned session has `transport: "twilio"` and a `twilio.voiceCallId`.
+- `googlemeet leave <sessionId>` hangs up the delegated voice call.
+
+## Troubleshooting
+
+### Agent cannot see the Google Meet tool
+
+Confirm the plugin is enabled in the Gateway config and reload the Gateway:
+
+```bash
+openclaw plugins list | grep google-meet
+openclaw googlemeet setup
+```
+
+If you just edited `plugins.entries.google-meet`, restart or reload the Gateway.
+The running agent only sees plugin tools registered by the current Gateway
+process.
+
+### No connected Google Meet-capable node
+
+On the node host, run:
+
+```bash
+openclaw plugins enable google-meet
+openclaw plugins enable browser
+OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
+  openclaw node run --host <gateway-lan-ip> --port 18789 --display-name parallels-macos
+```
+
+On the Gateway host, approve the node and verify commands:
+
+```bash
+openclaw devices list
+openclaw devices approve <requestId>
+openclaw nodes status
+```
+
+The node must be connected and list `googlemeet.chrome` plus `browser.proxy`.
+The Gateway config must allow those node commands:
+
+```json5
+{
+  gateway: {
+    nodes: {
+      allowCommands: ["browser.proxy", "googlemeet.chrome"],
+    },
+  },
+}
+```
+
+### Browser opens but agent cannot join
+
+Run `googlemeet test-speech` and inspect the returned Chrome health. If it
+reports `manualActionRequired: true`, show `manualActionMessage` to the operator
+and stop retrying until the browser action is complete.
+
+Common manual actions:
+
+- Sign in to the Chrome profile.
+- Admit the guest from the Meet host account.
+- Grant Chrome microphone/camera permissions.
+- Close or repair a stuck Meet permission dialog.
+
+### Agent joins but does not talk
+
+Check the realtime path:
+
+```bash
+openclaw googlemeet setup
+openclaw googlemeet status
+```
+
+Use `mode: "realtime"` for listen/talk-back. `mode: "transcribe"` intentionally
+does not start the duplex realtime voice bridge.
+
+Also verify:
+
+- A realtime provider key is available on the Gateway host, such as
+  `OPENAI_API_KEY` or `GEMINI_API_KEY`.
+- `BlackHole 2ch` is visible on the Chrome host.
+- `rec` and `play` exist on the Chrome host.
+- Meet microphone and speaker are routed through the virtual audio path used by
+  OpenClaw.
+
+### Twilio setup checks fail
+
+`twilio-voice-call-plugin` fails when `voice-call` is not allowed or not enabled.
+Add it to `plugins.allow`, enable `plugins.entries.voice-call`, and reload the
+Gateway.
+
+`twilio-voice-call-credentials` fails when the Twilio backend is missing account
+SID, auth token, or caller number. Set these on the Gateway host:
+
+```bash
+export TWILIO_ACCOUNT_SID=AC...
+export TWILIO_AUTH_TOKEN=...
+export TWILIO_FROM_NUMBER=+15550001234
+```
+
+Then restart or reload the Gateway and run:
+
+```bash
+openclaw googlemeet setup
+```
+
+### Twilio call starts but never enters the meeting
+
+Confirm the Meet event exposes phone dial-in details. Pass the exact dial-in
+number and PIN or a custom DTMF sequence:
+
+```bash
+openclaw googlemeet join https://meet.google.com/abc-defg-hij \
+  --transport twilio \
+  --dial-in-number +15551234567 \
+  --dtmf-sequence ww123456#
+```
+
+Use leading `w` or commas in `--dtmf-sequence` if the provider needs a pause
+before entering the PIN.
+
 ## Notes

 Google Meet's official media API is receive-oriented, so speaking into a Meet