Sonoscli guide: start with read-only Sonos checks in OpenClaw

Sonoscli lets OpenClaw query and control Sonos speakers through the separate sonos command. Start with one task: find your room and read playback status and volume. This walkthrough uses macOS with Homebrew already installed. The command host must share the Sonos LAN and reach the speakers on TCP port 1400. This is Peter Steinberger's independent project, not an official Sonos tool.

Check the bundled Skill first

Open a terminal on the OpenClaw host:

openclaw skills info sonoscli
openclaw skills check

Check whether the Skill exists, its prerequisites are satisfied, and it is visible to your Agent. Being listed does not mean it is ready. If sonos is missing, install the CLI below and check again. With multiple Agents, add --agent <id> to check for the Agent you use.

Only if the Skill is absent, consider steipete's ClawHub v1.0.0:

openclaw skills install @steipete/sonoscli --version 1.0.0

The Skill instructions and the sonos executable are installed separately. The current bundled OpenClaw Skill also includes macOS Local Network and sandbox troubleshooting that ClawHub v1.0.0 lacks. An existing bundled copy does not need a same-name replacement.

Install sonos on the command host

In that Mac's terminal:

brew install steipete/tap/sonoscli
sonos --version

The package is sonoscli; the executable is sonos. Record your installed version. The read behavior below is checked against release v0.3.4. Other operating systems have binary and source options in the author's installation guide.

Your Sonos system should already work in the Sonos App. Connect the computer to the same home network rather than an isolated guest Wi-Fi. These status checks need no Sonos API key, Spotify credentials, or video tools. If OpenClaw executes commands on another host or inside a container, that environment also needs the binary and access to the home LAN. Shell success does not establish Agent access.

Read a room from actual discovery results

Discover devices:

sonos discover --format json

Take the actual room name and IP from the results and compare them with the Sonos App. Default discovery lists visible rooms; bonded surrounds may be hidden, so fewer entries do not by themselves prove failure. [] means no rooms were found, even if the command exited successfully.

Replace Kitchen below with the full room name you discovered:

sonos status --name "Kitchen" --format json
sonos volume get --name "Kitchen" --format json
sonos group status --format json

Look for a meaningful transport state such as PLAYING, PAUSED_PLAYBACK, or STOPPED, and compare it with the same group in the Sonos App. Track titles only appear when metadata is available; a missing title alone does not prove connection failure. volume get returns a volume value and coordinatorIP, and reports read errors.

In v0.3.4, status can still exit successfully when some field reads fail. An empty state or zero volume is therefore not enough to establish that every read succeeded. Check the separate volume result and the App, retaining unconfirmed fields as unknown.

A grouped room can return its coordinator, whose identity differs from the requested room. Both status and this version's volume get resolve to the coordinator. Do not present that volume as every member's individual volume. Use group status to check membership and the coordinator; --ip does not force room-local reads. Before later playback or pause actions, establish whether the intended target is one standalone room or a group.

Give OpenClaw the same read-only task

Once terminal results make sense, adapt this request in OpenClaw, replacing Kitchen:

Use the sonoscli Skill to inspect Sonos room Kitchen without changing it.
First discover the actual room, then run status, volume get, and group status.
Report playback state, available track information, returned volume and coordinator,
and explain whether the room is grouped.
Do not play, pause, change volume, change the queue, or regroup speakers this time.
Keep missing fields unknown and report actual command errors instead of guessing.

Completion means the Agent reads the same devices and correctly explains the returned target. If the shell works but the Agent fails, check that Agent's Skill readiness and visibility, its execution PATH, and Local Network access.

Separate discovery failures from permission failures

• Empty discovery or timeout: Check the LAN/VLAN, guest Wi-Fi or client isolation, and TCP 1400 reachability. SSDP, topology, and subnet scanning offer discovery fallbacks, but cannot remove network isolation. If the Sonos App or router provides a known IP, try sonos status --ip 192.168.1.50 --format json, replacing the example address. This skips name discovery and can still resolve the group coordinator.
• macOS sendto: no route to host: The current bundled Skill points to System Settings → Privacy & Security → Local Network for the process hosting the Gateway, such as Terminal, VS Code, or node launched by launchd. Check the process that matches your launch method.
• bind: operation not permitted: Check whether execution is inside a sandbox that blocks networking or UDP. The actual command environment needs configured LAN access; installing a Skill does not remove its network restrictions.

Finish this first path with read-only verification. For later controls, specify the room, group, and permitted actions; prepare music-service dependencies only for the feature you then choose.