ClawSpotify 🎵

直接通过 OpenClaw agent 或终端控制你的 Spotify 播放。支持 免费版与高级版 Spotify 账户。

📦 安装

通过 ClawHub（推荐）

clawhub install clawspotify

手动从 GitHub 安装

# 克隆主技能仓库
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（sp_dc 和 sp_key）进行身份验证。每个账户仅需执行此操作 一次。

分步操作

1. 在浏览器中打开 https://open.spotify.com 并 登录
2. 按 F12 打开开发者工具（DevTools）
3. 切换至 Application 标签页 → Cookies → https://open.spotify.com
4. 找到并复制 sp_dc 的值
5. 找到并复制 sp_key 的值
6. 运行以下命令：

clawspotify setup --sp-dc "AQC..." --sp-key "07c9..."

会话信息将保存至 ~/.config/spotapi/session.json，后续自动复用。

多账户支持

clawspotify setup --sp-dc "..." --sp-key "..." --id "work"
clawspotify status --id "work"

注意：Cookie 会定期过期。若命令返回 401 错误，请使用浏览器中最新获取的 Cookie 重新运行 setup 命令。

🎮 命令

当前播放状态

clawspotify status            # 默认账户
clawspotify status --id work  # 指定账户

搜索音乐（不播放）

clawspotify search "Bohemian Rhapsody"        # 搜索音轨，显示前 5 条结果
clawspotify search-playlist "Workout"         # 搜索歌单，显示前 5 条结果

搜索并播放

clawspotify play "Bohemian Rhapsody"          # 播放首个匹配结果
clawspotify play "Bohemian Rhapsody" --index 2  # 播放第 2 条结果（索引从 0 开始）
clawspotify play-playlist "Lofi Girl"         # 播放首个匹配歌单

播放控制

clawspotify pause
clawspotify resume
clawspotify skip                     # 下一曲
clawspotify prev                     # 上一曲
clawspotify restart                  # 从开头重播

队列

clawspotify queue "Stairway to Heaven"
clawspotify queue "spotify:track:3z8h0TU..."  # 通过 URI 添加

音量

clawspotify volume 50     # 设置为 50%
clawspotify volume 0      # 静音
clawspotify volume 100    # 最大音量

随机播放 / 循环播放

clawspotify shuffle on
clawspotify shuffle off
clawspotify repeat on
clawspotify repeat off

💡 使用提示

• Spotify 必须处于开启状态：至少在一个设备（PC / 手机 / 网页版）上运行 Spotify 应用，播放控制命令才能生效。该技能会将播放转移至一个“虚拟设备”，但仍需存在活跃会话。
• 首次运行可能较慢：由于 WebSocket 握手及设备注册过程，首次运行耗时约 10–30 秒；后续命令响应更快。
• 会话标识符：默认为 "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 Unauthorized / 会话已过期

• Cookie（sp_dc、sp_key）已过期，请从浏览器中重新获取最新 Cookie，并再次运行 clawspotify setup。

命令超时或卡住

• 该技能依赖 WebSocket 实现实时状态同步。若 Spotify API 响应缓慢，命令执行时间可能延长。可适当增加超时时间，或改用后台执行方式。
• 若技能无响应，可重启 OpenClaw gateway 以重新加载技能。

找不到包装脚本（command not found: clawspotify）

• 确认 ~/.local/bin 已加入你的 PATH：echo $PATH
• 或直接运行 Python 脚本：~/.venv-clawspotify/bin/python ~/.openclaw/workspace/skills/ClawSpotify/scripts/spotify.py

📂 文件路径

🔧 Agent 集成说明

当通过 OpenClaw agent 使用本技能时：

1. 播放控制命令（如 play、pause、skip 等）为异步执行。命令返回仅代表 Spotify 已接收请求，实际播放启动可能延迟数秒。
2. 长时操作：对 play、search 和 status 等命令，建议启用后台执行或延长超时时间（15–30 秒），避免被提前终止。
3. 状态查询 可能因 WebSocket 延迟而超时。相比之下，播放类命令更可靠。
4. 请始终以 Spotify 应用/设备上的实际播放状态为准。 CLI 输出反映的是 Spotify 接口所确认的状态。
5. 若技能失去响应，可重启 OpenClaw gateway 以清除 WebSocket 连接。

🌐 平台说明

• Linux/macOS：原生支持 bash。
• Windows：需使用 WSL、Git Bash 或 Cygwin 运行 clawspotify bash 脚本。也可直接调用 Python：

  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 agent）+ ejatapibeda（原始作者）