QQ Music Browser Control

Use this community-maintained skill to control QQ Music's web player (y.qq.com) through a browser DevTools/CDP endpoint.

Security model

This skill uses the Chrome DevTools Protocol (CDP) to automate QQ Music's web UI. It is not affiliated with Tencent or QQ Music. CDP is a powerful protocol — the following safeguards are in place to minimize its blast radius:

Domain whitelist

The script only operates on y.qq.com tabs. Before every Runtime.evaluate call, the target tab's URL is validated against an allow-list (y.qq.com). Tabs on any other domain are rejected with an error. This prevents the script from reading or manipulating content on other websites (email, banking, etc.).

Isolated browser profile (recommended)

We strongly recommend launching the browser with --user-data-dir pointing to a dedicated directory:

chrome --remote-debugging-port=9222 --user-data-dir=/path/to/qq-music-profile

This ensures:

• The CDP-enabled browser instance has no access to your main browser's cookies, passwords, or sessions
• Only QQ Music login state exists in this profile
• Closing this browser leaves your main browser unaffected

Single-port binding

The script probes only port 9222 by default (configurable via QQ_MUSIC_DEVTOOLS_PORTS). It does not scan port ranges. This minimizes the chance of accidentally connecting to unrelated DevTools endpoints.

No SSRF policy changes required

This skill does not use OpenClaw's built-in browser tool. It connects to CDP directly via WebSocket from a local Node.js script. No SSRF policy relaxation is needed in OpenClaw's configuration.

What CDP can and cannot do

Honest limitations

• CDP inherently has access to all tabs in the connected browser. The domain whitelist is an application-level guard, not a browser-level sandbox. Using --user-data-dir for isolation is the strongest mitigation.
• The script runs Runtime.evaluate with arbitrary JavaScript on QQ Music pages. This is equivalent to using the browser's DevTools console on that page.
• This is a community automation tool for a music player, not a security-critical application. Use common sense: don't run it on a machine you don't trust.

What it supports

• Cross-platform: Windows, macOS, Linux
• Cross-browser: Chrome, Chromium, Edge, Brave, Arc, or any browser exposing a DevTools/CDP endpoint
• Transport: play, pause, toggle, next, previous
• Search & play: songs, artists, albums
• Liked songs: play all, play random, like/unlike current track
• Playlists: list created playlists, create new playlists, add current song to a playlist, play a playlist by ID
• Mode control: list loop, single loop, shuffle, sequential
• Status: current track, artist, time, play state
• Screenshot capture

Requirements

• Node.js 18+ (uses built-in fetch and WebSocket)
• A Chromium-based browser with remote debugging enabled (see setup below)
• A QQ Music account logged in at y.qq.com (needed for liked songs, playlists, and like/unlike)

Setup guide

The skill communicates with the browser via the Chrome DevTools Protocol (CDP). You need to launch your browser with remote debugging enabled so the skill can connect.

Step 1: Launch browser with remote debugging

Pick one port (e.g. 9222) and launch your browser with that port. Only one instance can bind to a port.

Windows

Chrome:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

Edge:

"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222

Brave:

"C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe" --remote-debugging-port=9222

On Windows you can also create a desktop shortcut with the flag appended.

macOS

Chrome:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Edge:

/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge --remote-debugging-port=9222

Brave:

/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser --remote-debugging-port=9222

Linux

google-chrome --remote-debugging-port=9222
# or
chromium-browser --remote-debugging-port=9222
# or
brave-browser --remote-debugging-port=9222

Security best practice: Always use a dedicated browser profile with --user-data-dir to isolate the CDP-enabled instance from your main browsing data:

--user-data-dir=/tmp/qq-music-profile --remote-debugging-port=9222

This is the single most important step to limit CDP's blast radius. Close all existing instances of the browser before launching with these flags.

Step 2: Log in to QQ Music

1. Open https://y.qq.com/ in the browser you just launched.
2. Log in with your QQ / WeChat account.
3. Optionally open https://y.qq.com/n/ryqq_v2/player in another tab for a dedicated player view.

Step 3: Verify the connection

node qq-music-ctl.js tabs

You should see your browser tabs listed, including the QQ Music ones.

Step 4 (optional): Verify domain whitelist

The script only operates on y.qq.com tabs. You can verify this by running:

node qq-music-ctl.js tabs

Any tab not on y.qq.com will show isQQMusic: false and will be ignored by all commands.

Note: This skill does NOT require any OpenClaw SSRF policy changes. It connects to CDP directly, not through OpenClaw's browser tool.

Controller script

All actions go through the bundled script:

node qq-music-ctl.js <action> [args...]

All output is JSON on stdout. Exit code 0 = success, 1 = error.

Environment variables

Action reference

Playback control

Search & play

Liked songs

Playlists

Play mode

Utility

How it works

1. Endpoint discovery: The script probes localhost ports for a DevTools HTTP endpoint (/json/version + /json/list). It prefers the endpoint that already has QQ Music tabs open.
2. Tab selection: Player-tab (/player URL) is preferred for transport controls (play/pause/next/prev/status). A separate browse-tab is used for search, navigation, and playlist operations.
3. DOM automation: All interactions use Runtime.evaluate over CDP to run JavaScript in the page context. No Puppeteer or Playwright dependency.
4. No external dependencies: The script is a single file using only Node.js built-ins (fs, WebSocket, fetch). No npm install needed.

Selection rules

• Prefer the player tab for transport controls.
• Prefer the browse tab for search and playlist discovery.
• If there is no QQ Music tab, init opens a blank tab and navigates to https://y.qq.com/.
• For song search, the first exact or containing title match wins; otherwise the first visible result is played.
• For liked songs, random play picks from the currently visible page (~10 songs; the web version does not expose all liked songs without scrolling).
• For add-to-playlist, if a newly created playlist is not yet visible in the player's menu, the player page is automatically reloaded to refresh the cache and retry.
• like and unlike are idempotent and report the current state.
• create-playlist accepts names up to 20 characters (QQ Music web limit).

Limitations

• The QQ Music web version shows at most ~10 liked songs per page. play-liked uses the "播放全部" button which queues all liked songs in the player, but play-liked-random can only pick from the visible ~10.
• System audio volume control is out of scope (OS-level, not browser-controlled).
• Some features (like VIP-only songs) depend on the user's QQ Music subscription.
• The skill does not handle QQ Music login; the user must log in manually first.

Troubleshooting

• "No DevTools endpoint found": Make sure the browser is running with --remote-debugging-port=<port> and no other instance is using that port.
• "Player not found": Play a song first (via search or play-liked) to make the player tab appear.
• Timeouts: Increase QQ_MUSIC_PAGE_WAIT_MS for slow connections, or QQ_MUSIC_PROBE_TIMEOUT_MS for slow endpoint discovery.
• "CDP connection closed": The page may have navigated or crashed. Retry the command.

Notes

• The skill does not assume a specific browser brand or OS.
• The skill does not hardcode any personal paths, usernames, or tokens.
• If the browser exposes multiple DevTools endpoints, the controller probes common ports and prefers the one with QQ Music tabs.

Disclaimer

This is a community-maintained tool for personal learning and research. It automates the QQ Music web UI through a user's own browser — equivalent to manual DevTools console usage. It is not an official QQ Music/Tencent plugin.

It does not reverse-engineer server APIs, extract music files, or bypass payment restrictions.

Users are responsible for complying with QQ Music's Terms of Service. If you receive a takedown notice from the rights holder, stop using this skill immediately.

Open-source, non-commercial, and provided as-is with no warranty.