Spotify Controller Skill

Control Spotify playback from your AI agent using the official Spotify Web API.

This works across setups (local machine, Docker, VPS, and hybrid environments). It is especially useful for fixing Spotify control pain in headless VPS deployments. The server does not need a browser or a local Spotify client.

What this skill provides

• A CLI workflow around spotify.py
• Playback control (play, pause, next, prev)
• Track lookup (search) and quick play (playsearch)
• Direct URI playback (playtrack spotify:track:...)
• Device management (devices, setdevice)
• Volume control (volume 0-100, where supported)

Requirements

• Python 3 available in runtime/container
• requests package installed
• Spotify Premium account
• Spotify Developer app credentials
• Environment variables:
  • SPOTIFY_CLIENT_ID
  • SPOTIFY_CLIENT_SECRET
  • SPOTIFY_REFRESH_TOKEN

Install dependency:

uv pip install requests --system

(Alternative: pip install requests)

If you build OpenClaw in Docker, add this to your Dockerfile when requests is not already present:

RUN uv pip install requests --system

Setup (Step-by-step)

1) Create a Spotify Developer App

1. Go to: https://developer.spotify.com/dashboard
2. Click Create App
3. Enter any app name/description
4. Add Redirect URI:
   • http://127.0.0.1:8888/callback
5. Enable Web API access
6. Save and copy:
   • Client ID
   • Client Secret

2) Get a refresh token (one-time, on local machine)

Open this URL in your browser (replace YOUR_CLIENT_ID):

https://accounts.spotify.com/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http://127.0.0.1:8888/callback&scope=user-modify-playback-state%20user-read-playback-state%20user-read-currently-playing

Approve access, then copy the code value from the redirected URL.

Exchange code for tokens:

curl -s -X POST "https://accounts.spotify.com/api/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=YOUR_CODE&redirect_uri=http://127.0.0.1:8888/callback&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

From response JSON, copy refresh_token.

refresh_token is typically long-lived, but can be invalidated if app access is revoked, app settings change, or credentials rotate.

3) Add credentials to .env

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REFRESH_TOKEN=your_refresh_token

4) Pass env vars to Docker compose service

In docker-compose.yml service environment: section:

- SPOTIFY_CLIENT_ID=${SPOTIFY_CLIENT_ID}
- SPOTIFY_CLIENT_SECRET=${SPOTIFY_CLIENT_SECRET}
- SPOTIFY_REFRESH_TOKEN=${SPOTIFY_REFRESH_TOKEN}

5) Restart service/container

docker compose down
docker compose up -d openclaw-gateway