QQ Music Browser Control

Community-maintained browser automation for QQ Music's web player (y.qq.com). Supports play/pause/next/prev, search songs/artists/albums, play liked songs, r...

Security Scan

The skill's code and instructions match its stated purpose (controlling QQ Music via a DevTools/CDP endpoint); it asks for no unrelated credentials and contains application-level safeguards, but CDP access is inherently powerful and a few minor implementation mismatches reduce confidence.

Purpose & Capability

The name/description (browser automation for y.qq.com) align with the included Node.js script: it discovers a local DevTools endpoint, lists targets, opens or reuses QQ Music pages, and uses Runtime.evaluate to run page JS. Required resources (Node + a CDP-enabled Chromium) are consistent with the purpose; no unrelated credentials or external services are requested.

Instruction Scope

SKILL.md instructs the agent to connect to a local browser DevTools endpoint, launch Chromium with --remote-debugging-port, and log in to y.qq.com. The skill repeatedly emphasizes a domain whitelist (y.qq.com) and recommends using a separate user-data-dir. This is appropriate, but the whitelist is an application-level guard — CDP itself can access all tabs and browser state. The README acknowledges that limitation. The instructions do not ask the agent to read arbitrary files or unrelated environment variables.

Install Mechanism

No install spec or external downloads are present; the skill is instruction + a local Node.js script. Nothing is written to disk by an installer and no third-party packages are pulled in by an automated installer, which minimizes supply-chain risk.

Credentials

No secrets or credentials are requested. Optional environment variables control which host/ports to probe and output paths. Be aware QQ_MUSIC_DEVTOOLS_URL can point to an arbitrary WebSocket origin — if set to a remote endpoint it could expose a powerful remote browser to the skill. The variables requested are otherwise proportional to the functionality.

Persistence & Privilege

always is false and the skill is user-invocable only. The script does create new browser targets when needed but does not modify other skills or system-wide agent settings. It does not request permanent presence or elevated platform privileges.

Assessment

This skill appears to do what it says: control QQ Music through a Chromium DevTools endpoint. However, CDP is powerful — if you connect the skill to a browser with your main profile it could (in principle) access cookies, tabs, or other state even though the script tries to restrict itself to y.qq.com. Before installing: - Follow the README: launch the browser with --remote-debugging-port and a dedicated --user-data-dir (a throwaway profile) and log in to QQ Music there only. - Keep QQ_MUSIC_DEVTOOLS_URL pointed at a local endpoint (127.0.0.1) and avoid exposing the DevTools port to the network. - Note a minor implementation mismatch: the SKILL.md claims Node 18+ provides both fetch and WebSocket; fetch is built-in but Node does not supply a global WebSocket by default — you may need a small polyfill (or run the script in an environment that provides WebSocket). Test in a safe environment first. - If you must run on a machine that handles sensitive data (email, banking), do not expose your main browser session to remote debugging; instead use a disposable VM or container. If you want higher assurance, request a code review of the full script to confirm it doesn't call CDP methods like Network.getCookies / Storage.getCookies or otherwise send data off-host; the included code appears to use Runtime.evaluate and Target.createTarget only.

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

Capability	In scope?	Notes
Execute JS in y.qq.com tabs	✅	Core functionality — clicks buttons, reads DOM
Execute JS in non-y.qq.com tabs	❌	Blocked by domain whitelist
Read cookies from y.qq.com	⚠️	Technically possible via CDP, but the script never does this
Access other browser tabs	⚠️	CDP can list all tabs, but the script only interacts with y.qq.com tabs
Access filesystem	❌	CDP Runtime.evaluate runs in page sandbox
Install extensions	❌	The script does not use Target.createBrowserContext or extension APIs

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

Variable	Default	Description
QQ_MUSIC_DEVTOOLS_URL	(auto-discover)	Explicit DevTools base URL, e.g. http://127.0.0.1:9222
QQ_MUSIC_DEVTOOLS_HOST	127.0.0.1	Host to probe for DevTools endpoints
QQ_MUSIC_DEVTOOLS_PORTS	9222	Comma-separated ports to probe (single port by default to minimize exposure)
QQ_MUSIC_SCREENSHOT_PATH	qq-music-screenshot.png	Default screenshot output path
QQ_MUSIC_PROBE_TIMEOUT_MS	1200	Per-endpoint probe timeout in ms
QQ_MUSIC_PAGE_WAIT_MS	3500	Wait time after page navigation in ms

Action reference

Playback control

Action	Description
play	Resume playback (idempotent)
pause	Pause playback (idempotent)
toggle	Toggle play/pause
next	Next track
prev	Previous track
status	Current track, artist, time, duration, play state

Search & play

Action	Description
search <keyword>	Search for a song and play best match
search-artist <name>	Search for an artist and open their page
play-artist-all-songs <name>	Play all songs by an artist
search-album <name>	Search for an album and play it

Liked songs

Action	Description
play-liked	Play all liked songs (clicks "播放全部")
play-liked-random	Randomly play one liked song from the visible page
like	Like current song (idempotent; returns already_liked if already liked)
unlike	Unlike current song (idempotent; returns already_unliked if not liked)

Playlists

Action	Description
list-playlists	List all created playlists with name, song count, and numeric ID
create-playlist <name>	Create a new playlist (max 20 characters)
add-to-playlist <name>	Add the currently playing song to a playlist by name
play-playlist <id>	Play a playlist by its numeric ID

Play mode

Action	Description
mode	Show current play mode
mode list	Set to list loop (列表循环)
mode single	Set to single loop (单曲循环)
mode random	Set to shuffle (随机播放)
mode order	Set to sequential (顺序循环)

Utility

Action	Description
screenshot [path]	Capture a screenshot of the QQ Music tab
tabs	List all detectable browser tabs
init	Open QQ Music if no tab exists

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.