Skills: add SonosCLI troubleshooting guidance (openclaw#21316) thanks @huntharo

Verified:
- pnpm build
- pnpm check
- pnpm test:macmini

Co-authored-by: huntharo <5617868+huntharo@users.noreply.github.com>
Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

CHANGELOG.md

@@ -74,6 +74,7 @@ Docs: https://docs.openclaw.ai
 - Security/Net: strip sensitive headers (`Authorization`, `Proxy-Authorization`, `Cookie`, `Cookie2`) on cross-origin redirects in `fetchWithSsrFGuard` to prevent credential forwarding across origin boundaries. (#20313) Thanks @afurm.
 - Security/Systemd: reject CR/LF in systemd unit environment values and fix argument escaping so generated units cannot be injected with extra directives. Thanks @thewilloftheshadow.
 - Skills/Security: sanitize skill env overrides to block unsafe runtime injection variables and only allow sensitive keys when declared in skill metadata, with warnings for suspicious values. Thanks @thewilloftheshadow.
+- Skills/SonosCLI: add troubleshooting guidance for `sonos discover` failures on macOS direct mode (`sendto: no route to host`) and sandbox network restrictions (`bind: operation not permitted`). (#21316) Thanks @huntharo.
 - Auto-reply/Runner: emit `onAgentRunStart` only after agent lifecycle or tool activity begins (and only once per run), so fallback preflight errors no longer mark runs as started. (#21165) Thanks @shakkernerd.
 - Agents/Failover: treat non-default override runs as direct fallback-to-configured-primary (skip configured fallback chain), normalize default-model detection for provider casing/whitespace, and add regression coverage for override/auth error paths. (#18820) Thanks @Glucksberg.
 - Auto-reply/Tool results: serialize tool-result delivery and keep the delivery chain progressing after individual failures so concurrent tool outputs preserve user-visible ordering. (#21231) thanks @ahdernasr.

skills/sonoscli/SKILL.md

@@ -26,21 +26,40 @@ metadata:
 
 Use `sonos` to control Sonos speakers on the local network.
 
-Quick start
+## Quick start
 
 - `sonos discover`
 - `sonos status --name "Kitchen"`
 - `sonos play|pause|stop --name "Kitchen"`
 - `sonos volume set 15 --name "Kitchen"`
 
-Common tasks
+## Common tasks
 
 - Grouping: `sonos group status|join|unjoin|party|solo`
 - Favorites: `sonos favorites list|open`
 - Queue: `sonos queue list|play|clear`
 - Spotify search (via SMAPI): `sonos smapi search --service "Spotify" --category tracks "query"`
 
-Notes
+## Notes
 
 - If SSDP fails, specify `--ip <speaker-ip>`.
 - Spotify Web API search is optional and requires `SPOTIFY_CLIENT_ID/SECRET`.
+- If there is an error, check the troubleshooting section and offer advice if there is a decent match.
+
+## Troubleshooting
+
+### `sonos discover` - `no route to host`
+
+- On error `Error: write udp4 0.0.0.0:64326->239.255.255.250:1900: sendto: no route to host (Command exited with code 1)`
+  - Note that the port number after `0.0.0.0:` is ephemeral and will change and the netmask may not match exactly either
+  - The `sendto: no route to host` should stay consistent
+- Advise the user that in `direct` (no Docker sandbox) mode on Mac OS that Settings -> Privacy & Security -> Local Network will need to be enabled for the top-level host parent process of the Gateway
+  - `node` if running via `launchd`
+  - `Terminal` if running the gateway directly in the terminal
+  - `Visual Studio Code` if running via terminal in VS Code
+- An alternative option is to use `sandbox` (docker container) with network access allowed for that sandbox
+
+### `sonos discover` - `bind: operation not permitted`
+
+- On error `Error: listen udp4 0.0.0.0:0: bind: operation not permitted`
+- Advise the user that they may be running via a Codex or other sandbox that does not permit network access (this can be replicated by running `sonos discover` within a Codex CLI session with sandbox enabled and not approving the escalation request)