From b1431bc936eef070118983dba55baa680cde136d Mon Sep 17 00:00:00 2001 From: goofoo Date: Thu, 16 Apr 2026 12:08:11 -0400 Subject: [PATCH 1/2] docs: expand Troubleshooting section for common connection issues Add entries covering the four most frequently reported problems: - Xcode build stalls at 70/82: SPM cache issue, fix via Reset Package Caches and clearing DerivedData (#26) - "XPC connection invalid": DAT SDK <-> Meta AI app trust failure, with step-by-step resolution (Developer Mode, accept trust prompt, update app) (#7) - "Permission error / Error opening link": registration deep-link failure, with common causes and workarounds (#10) - OpenClaw fails on mobile data: .local hostname only resolves on local Wi-Fi; adds Tailscale and public-bind options, and notes that the in-app Settings screen can change the host without a rebuild (#35) Co-Authored-By: Claude Sonnet 4.6 --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index 91455686..220e3c26 100644 --- a/README.md +++ b/README.md @@ -347,6 +347,28 @@ For full details, see [`samples/CameraAccess/CameraAccess/WebRTC/README.md`](sam ### iOS-specific +**Xcode build stalls at 70/82 (or any step near the end)** -- This is almost always an SPM package resolution issue. Fix: +1. In Xcode: **File > Packages > Reset Package Caches** +2. If that does not help: close Xcode, delete `~/Library/Developer/Xcode/DerivedData`, then reopen. +3. Make sure you have a stable internet connection -- SPM fetches the DAT SDK from GitHub during the first build. + +**"XPC connection invalid" when connecting glasses** -- The DAT SDK communicates with the Meta AI companion app via XPC. This error means the companion app rejected the connection. Check: +1. Developer Mode is enabled in the Meta AI app (Settings > App Info > tap version 5 times) +2. The VisionClaw app is trusted: after the first registration attempt, the Meta AI app may show a permission prompt -- accept it. +3. The Meta AI app is up to date on the App Store. +4. Try force-quitting the Meta AI app and reconnecting. + +**"Permission error" or "Error opening link" when connecting glasses** -- The registration deep-link from VisionClaw to the Meta AI app failed. This can happen when: +- Developer Mode is not yet enabled (see above). +- The app has not been granted the association in the Meta AI app -- tap **Allow** on any prompt that appears after tapping "Connect my glasses". +- On a fresh install, wait a few seconds after the Meta AI app opens before tapping anything. + +**OpenClaw tool calls work at home but fail on mobile data** -- The `.local` Bonjour hostname only resolves on the same Wi-Fi network. To reach OpenClaw from anywhere: +- **Tailscale (recommended):** Install [Tailscale](https://tailscale.com) on your Mac and phone, then replace the hostname in Settings (or `Secrets.swift`) with your Mac's Tailscale IP (e.g. `http://100.x.x.x`). +- **Public bind:** Set `bind: "public"` in `openclaw.json` and use your Mac's public IP -- only do this with a strong auth token. + +Note: the in-app Settings screen (gear icon) lets you change the gateway host at runtime without editing source code. + **"Gemini API key not configured"** -- Add your API key in Secrets.swift or in the in-app Settings. **Echo/feedback in iPhone mode** -- The app mutes the mic while the AI is speaking. If you still hear echo, try turning down the volume. From d97d45ecaa4f437ffd7f8f1513396d5529114f37 Mon Sep 17 00:00:00 2001 From: goofoo Date: Thu, 16 Apr 2026 12:14:54 -0400 Subject: [PATCH 2/2] docs: fix placement and scope of troubleshooting entries Two corrections spotted during test-plan review: 1. Tailscale / remote OpenClaw entry was under iOS-specific, but the Android app has identical host configuration and the same problem. Move it to the General section and update the Secrets reference to cover both Secrets.swift and Secrets.kt. 2. 'Error opening link' (Erreur lors de l'ouverture du lien) is the Android string-resource bug fixed separately. Remove it from the iOS 'Permission error' entry so it does not mislead iOS users. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 220e3c26..c0cc3c64 100644 --- a/README.md +++ b/README.md @@ -345,6 +345,12 @@ For full details, see [`samples/CameraAccess/CameraAccess/WebRTC/README.md`](sam **OpenClaw opens duplicate browser tabs** -- This is a known upstream issue in OpenClaw's CDP (Chrome DevTools Protocol) connection management ([#13851](https://github.com/nichochar/openclaw/issues/13851), [#12317](https://github.com/nichochar/openclaw/issues/12317)). Using `profile: "openclaw"` (managed Chrome) instead of the default extension relay may improve stability. +**OpenClaw tool calls work at home but fail on mobile data** -- The `.local` Bonjour hostname only resolves on the same Wi-Fi network. To reach OpenClaw from anywhere: +- **Tailscale (recommended):** Install [Tailscale](https://tailscale.com) on your Mac and phone, then replace the gateway hostname in the in-app Settings (or `Secrets.swift` / `Secrets.kt`) with your Mac's Tailscale IP (e.g. `http://100.x.x.x`). +- **Public bind:** Set `bind: "public"` in `openclaw.json` and use your Mac's public IP -- only do this with a strong auth token. + +Both iOS and Android have an in-app Settings screen where you can change the gateway host at runtime without editing source code. + ### iOS-specific **Xcode build stalls at 70/82 (or any step near the end)** -- This is almost always an SPM package resolution issue. Fix: @@ -358,16 +364,11 @@ For full details, see [`samples/CameraAccess/CameraAccess/WebRTC/README.md`](sam 3. The Meta AI app is up to date on the App Store. 4. Try force-quitting the Meta AI app and reconnecting. -**"Permission error" or "Error opening link" when connecting glasses** -- The registration deep-link from VisionClaw to the Meta AI app failed. This can happen when: +**"Permission error" when returning from the Meta AI app** -- The glasses association was not granted. This can happen when: - Developer Mode is not yet enabled (see above). - The app has not been granted the association in the Meta AI app -- tap **Allow** on any prompt that appears after tapping "Connect my glasses". - On a fresh install, wait a few seconds after the Meta AI app opens before tapping anything. -**OpenClaw tool calls work at home but fail on mobile data** -- The `.local` Bonjour hostname only resolves on the same Wi-Fi network. To reach OpenClaw from anywhere: -- **Tailscale (recommended):** Install [Tailscale](https://tailscale.com) on your Mac and phone, then replace the hostname in Settings (or `Secrets.swift`) with your Mac's Tailscale IP (e.g. `http://100.x.x.x`). -- **Public bind:** Set `bind: "public"` in `openclaw.json` and use your Mac's public IP -- only do this with a strong auth token. - -Note: the in-app Settings screen (gear icon) lets you change the gateway host at runtime without editing source code. **"Gemini API key not configured"** -- Add your API key in Secrets.swift or in the in-app Settings.