Skip to content

docs: expand Troubleshooting section for common connection issues #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kbaker827 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: expand Troubleshooting section for common connection issues #52

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b1431bc
docs: expand Troubleshooting section for common connection issues
kbaker827 Apr 16, 2026
d97d45e
docs: fix placement and scope of troubleshooting entries
kbaker827 Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -345,8 +345,31 @@ 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:
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" 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.


**"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.
Expand Down