核心用法
spotify-claw 是一款面向 macOS 的 Spotify Premium 深度控制工具，通过命令行实现完整的播放控制、音乐分析与智能发现功能。用户需先在 Spotify Developer Dashboard 创建应用并配置 Keychain 凭证，之后即可通过 python3 ~/.openclaw/scripts/spotify.py [cmd] 执行所有操作。
播放控制：支持基础操作（播放/暂停/切歌/音量）、智能搜索播放（按曲名或 URI）、播放列表直接播放，以及独特的自动唤醒功能——当 Spotify 未运行时自动启动应用并等待初始化完成后播放。
音乐分析：提供多维度听歌画像，包括 short（4周）/medium（6个月）/long（全部时间）三个时间维度的 Top 曲目/艺人统计、完整曲风分布分析、最近播放、全部 liked 歌曲检索及按艺人筛选功能。
智能发现与歌单构建：绕过 Spotify 对新开发者账号封锁的 Recommendations API，采用 related_artists + artist_top_tracks 组合策略实现音乐发现。支持从特定艺人深度拓展（可设置跳转深度与每艺人曲目数）、一键生成并填充播放列表、相关艺人查询等。
显著优点
1. 绕过 API 限制：针对 Spotify 对新开发者应用封锁 recommendations/audio_features API 的现状，创新性地使用关系图谱算法实现同等功能
2. 自动应用生命周期管理：唯一支持 Spotify 未运行时自动启动并智能等待就绪的终端工具
3. 深度整合 macOS：凭证存储于系统 Keychain，安全性优于环境变量或明文配置文件
4. 高效歌单工作流：单命令完成创建+填充，支持分析结果直接转化为播放列表
5. 双语自然语言触发：支持英语与俄语指令识别
潜在局限
- 平台限制：macOS only（依赖 Keychain 与 AppleScript 自动启动）
- 订阅门槛：需 Spotify Premium 订阅
- 初始配置复杂度：需注册开发者账号、配置 Redirect URI、Keychain 凭证管理
- 发现算法局限：相比原生 Recommendations API，基于 related_artists 的发现路径可能遗漏跨风格推荐
- 无实时音频分析：因 API 限制无法获取音频特征（能量值、舞曲性等）
适合人群
- 重度 Spotify 用户且偏好终端/自动化工作流
- 需要定期生成基于听歌习惯的智能播放列表者
- 因 API 限制无法使用其他推荐功能的新开发者账号持有者
- 俄语母语用户
常规风险
- OAuth 凭证泄露风险：Keychain 虽安全，但首次配置时的明文 CLIENT_ID/SECRET 在剪贴板历史中可能存在短暂暴露窗口
- Rate limiting：高频调用可能导致 Spotify API 限流
- 自动化播放干扰：自动唤醒功能可能在不合时宜场景启动 Spotify
- 第三方依赖：依赖 spotipy 库的维护状态与安全性