ClawSpotify 🎵
Control your Spotify playback directly from your OpenClaw agent or terminal. Works with both Free and Premium Spotify accounts.
📦 Installation
Via ClawHub (recommended)
CODEBLOCK0
Manual from GitHub
CODEBLOCK1
Dependencies
- - Python 3.10+
- SpotAPI (custom version from ejatapibeda/SpotAPI)
- Active Spotify account (Free or Premium)
- Spotify app open on at least one device (PC/phone/web) for playback commands to work
🔐 First-Time Setup (Authentication)
INLINECODE0 authenticates using two session cookies from your browser (sp_dc and sp_key). You only need to do this once per account.
Step-by-step
- 1. Open https://open.spotify.com in your browser and log in
- Press F12 to open DevTools
- Go to Application tab → Cookies → INLINECODE3
- Find and copy the value of
sp_dc - Find and copy the value of
sp_key - Run:
CODEBLOCK2
Session is saved to ~/.config/spotapi/session.json and reused automatically.
Multi-account support
CODEBLOCK3
Note: Cookies expire periodically. If commands fail with a 401 error, re-run setup with fresh cookies.
🎮 Commands
Now playing status
CODEBLOCK4
Search music (without playing)
CODEBLOCK5
Search and play
CODEBLOCK6
Playback controls
CODEBLOCK7
Queue
CODEBLOCK8
Volume
CODEBLOCK9
Shuffle / Repeat
clawspotify shuffle on
clawspotify shuffle off
clawspotify repeat on
clawspotify repeat off
💡 Usage Tips
- - Spotify must be open on at least one device for playback commands to work. The skill transfers playback to a phantom device but needs an active session.
- First run may be slow (10-30 seconds) due to WebSocket handshake and device registration. Subsequent commands are faster.
- Session identifier: Default is
"default". Use --id flag to manage multiple Spotify accounts. - Search is fuzzy: Use artist name + title for best results.
- Output: Commands print status messages (e.g.,
Searching for "...", Playing: URI).
⚠️ Troubleshooting
"No active Spotify device found"
- - Open Spotify on any device (PC, phone, or web) and start playing something first.
- Ensure you're logged in with the same account as the cookies.
"spotapi is not installed" or import errors
- - Verify virtual environment: INLINECODE10
- Reinstall SpotAPI: INLINECODE11
401 Unauthorized / Session expired
- - Cookies (
sp_dc, sp_key) expire. Re-run clawspotify setup with fresh cookies from browser.
Commands time out or hang
- - The skill uses WebSockets for real-time state. If Spotify's API is slow, commands may take longer. Use longer timeout or background execution.
- Restart OpenClaw gateway to reload skill if it becomes unresponsive.
Wrapper not found (command not found: clawspotify)
- - Ensure
~/.local/bin is in your PATH: INLINECODE18 - Or run directly: INLINECODE19
📂 File Locations
| Component | Path |
|---|
| Skill folder | INLINECODE20 |
| Wrapper script |
~/.local/bin/clawspotify |
| Virtualenv |
~/.venv-clawspotify |
| SpotAPI (editable) |
~/.openclaw/workspace/skills/SpotAPI |
| Session credentials |
~/.config/spotapi/session.json |
| Main script |
~/skills/ClawSpotify/scripts/spotify.py |
🔧 Agent Implementation Notes
When using this skill via OpenClaw agent:
- 1. Playback commands (
play, pause, skip, etc.) are asynchronous. The command returns once Spotify accepts the request. Actual playback may take a few seconds to start. - Long-running operations: Use background execution or extended timeout (15-30 seconds) for
play, search, and status to avoid premature termination. - Status query may occasionally timeout due to WebSocket latency. Play commands are more reliable.
- Always check Spotify app/device for actual playback state. The CLI reports what Spotify acknowledges.
- If the skill becomes unresponsive, restart the OpenClaw gateway to clear WebSocket connections.
🌐 Platform Note
- - Linux/macOS: Works natively with bash.
- Windows: Requires WSL, Git Bash, or Cygwin to run the
clawspotify bash script. Alternatively, run Python directly:
python ~/.openclaw/workspace/skills/ClawSpotify/scripts/spotify.py play "song name"
Version: 1.0.1 (skill) | SpotAPI: 1.2.7 (custom)
Homepage: https://github.com/ejatapibeda/ClawSpotify
Author: Deli (OpenClaw agent) + ejatapibeda (original author)
技能名称: clawspotify
详细描述:
ClawSpotify 🎵
直接从你的 OpenClaw 代理或终端控制 Spotify 播放。支持 免费版和高级版 Spotify 账户。
📦 安装
通过 ClawHub（推荐）
bash
clawhub install clawspotify
从 GitHub 手动安装
bash
克隆主技能
git clone https://github.com/ejatapibeda/ClawSpotify.git ~/.openclaw/workspace/skills/ClawSpotify
创建虚拟环境
python3 -m venv ~/.venv-clawspotify
安装 SpotAPI（支持会话的修改版）
git clone https://github.com/ejatapibeda/SpotAPI.git ~/.openclaw/workspace/skills/SpotAPI
~/.venv-clawspotify/bin/pip install -e ~/.openclaw/workspace/skills/SpotAPI
创建包装脚本
cat > ~/.local/bin/clawspotify << EOF
#!/bin/bash
VENV=/home/$(whoami)/.venv-clawspotify
SCRIPT_DIR=/home/$(whoami)/.openclaw/workspace/skills/ClawSpotify
exec $VENV/bin/python $SCRIPT_DIR/scripts/spotify.py $@
EOF
chmod +x ~/.local/bin/clawspotify
确保 ~/.local/bin 在 PATH 中
export PATH=$HOME/.local/bin:$PATH
依赖项
- - Python 3.10+
- SpotAPI（来自 ejatapibeda/SpotAPI 的自定义版本）
- 有效的 Spotify 账户（免费版或高级版）
- 至少在一个设备（PC/手机/网页）上打开 Spotify 应用，播放命令才能生效
🔐 首次设置（身份验证）
clawspotify 使用浏览器中的两个会话 Cookie（spdc 和 spkey）进行身份验证。每个账户只需执行一次。
分步指南
- 1. 在浏览器中打开 https://open.spotify.com 并登录
- 按 F12 打开开发者工具
- 转到 Application 选项卡 → Cookies → https://open.spotify.com
- 找到并复制 spdc 的值
- 找到并复制 sp_key 的值
- 运行：
bash
clawspotify setup --sp-dc AQC... --sp-key 07c9...
会话将保存到 ~/.config/spotapi/session.json 并自动重用。
多账户支持
bash
clawspotify setup --sp-dc ... --sp-key ... --id work
clawspotify status --id work
注意： Cookie 会定期过期。如果命令失败并显示 401 错误，请使用新的 Cookie 重新运行设置。
🎮 命令
当前播放状态
bash
clawspotify status # 默认账户
clawspotify status --id work # 指定账户
搜索音乐（不播放）
bash
clawspotify search Bohemian Rhapsody # 搜索曲目，显示前 5 个
clawspotify search-playlist Workout # 搜索播放列表，显示前 5 个
搜索并播放
bash
clawspotify play Bohemian Rhapsody # 播放第一个结果
clawspotify play Bohemian Rhapsody --index 2 # 选择第 2 个结果（从 0 开始）
clawspotify play-playlist Lofi Girl # 播放第一个播放列表结果
播放控制
bash
clawspotify pause
clawspotify resume
clawspotify skip # 下一曲
clawspotify prev # 上一曲
clawspotify restart # 从头开始播放
队列
bash
clawspotify queue Stairway to Heaven
clawspotify queue spotify:track:3z8h0TU... # 通过 URI 添加
音量
bash
clawspotify volume 50 # 设置为 50%
clawspotify volume 0 # 静音
clawspotify volume 100 # 最大
随机播放 / 重复播放
bash
clawspotify shuffle on
clawspotify shuffle off
clawspotify repeat on
clawspotify repeat off
💡 使用技巧
- - Spotify 必须打开 至少在一个设备上，播放命令才能生效。该技能会将播放转移到虚拟设备，但需要活跃的会话。
- 首次运行可能较慢（10-30 秒），因为需要进行 WebSocket 握手和设备注册。后续命令会更快。
- 会话标识符： 默认为 default。使用 --id 标志管理多个 Spotify 账户。
- 搜索是模糊的： 使用艺术家名称 + 标题可获得最佳结果。
- 输出： 命令会打印状态消息（例如，Searching for ..., Playing: URI）。
⚠️ 故障排除
未找到活跃的 Spotify 设备
- - 在任何设备（PC、手机或网页）上打开 Spotify，并先播放一些内容。
- 确保你登录的账户与 Cookie 对应的账户相同。
spotapi 未安装 或导入错误
- - 验证虚拟环境：ls ~/.venv-clawspotify/bin/python
- 重新安装 SpotAPI：~/.venv-clawspotify/bin/pip install -e ~/.openclaw/workspace/skills/SpotAPI
401 未授权 / 会话过期
- - Cookie（spdc、spkey）已过期。使用浏览器中的新 Cookie 重新运行 clawspotify setup。
命令超时或无响应
- - 该技能使用 WebSocket 进行实时状态同步。如果 Spotify 的 API 响应慢，命令可能需要更长时间。使用更长的超时时间或后台执行。
- 如果技能无响应，重启 OpenClaw 网关以重新加载技能。
包装脚本未找到（command not found: clawspotify）
- - 确保 ~/.local/bin 在你的 PATH 中：echo $PATH
- 或直接运行：~/.venv-clawspotify/bin/python ~/.openclaw/workspace/skills/ClawSpotify/scripts/spotify.py
📂 文件位置
| 组件 | 路径 |
|---|
| 技能文件夹 | ~/.openclaw/workspace/skills/ClawSpotify |
| 包装脚本 |
~/.local/bin/clawspotify |
| 虚拟环境 | ~/.venv-clawspotify |
| SpotAPI（可编辑） | ~/.openclaw/workspace/skills/SpotAPI |
| 会话凭据 | ~/.config/spotapi/session.json |
| 主脚本 | ~/skills/ClawSpotify/scripts/spotify.py |
🔧 代理实现说明
通过 OpenClaw 代理使用此技能时：
- 1. 播放命令（play、pause、skip 等）是异步的。命令在 Spotify 接受请求后返回。实际播放可能需要几秒钟才能开始。
- 长时间运行的操作： 对 play、search 和 status 使用后台执行或延长超时时间（15-30 秒），以避免过早终止。
- 状态查询 可能偶尔因 WebSocket 延迟而超时。播放命令更可靠。
- 始终检查 Spotify 应用/设备以获取实际播放状态。CLI 报告的是 Spotify 确认的内容。
- 如果技能无响应，重启 OpenClaw 网关以清除 WebSocket 连接。
🌐 平台说明
- - Linux/macOS： 原生支持 bash。
- Windows： 需要 WSL、Git Bash 或 Cygwin 来运行 clawspotify bash 脚本。或者直接运行 Python：
bash
python ~/.openclaw/workspace/skills/ClawSpotify/scripts/spotify.py play song name
版本： 1.0.1（技能）| SpotAPI：1.2.7（自定义）
主页： https://github.com/ejatapibeda/ClawSpotify
作者： Deli（OpenClaw 代理）+ ejatapibeda（原作者）
