Spotify
Hermes 可以直接控制 Spotify——播放、队列、搜索、播放列表、已保存的曲目/专辑和收听历史——通过 Spotify 官方 Web API 使用 PKCE OAuth。Token 存储在 ~/.hermes/auth.json 中，在 401 时自动刷新；每台机器只需登录一次。
与 Hermes 的内置 OAuth 集成（Google、GitHub Copilot、Codex）不同，Spotify 要求每个用户注册自己的轻量开发者应用。Spotify 不允许第三方提供公共 OAuth 应用供任何人使用。这大约需要两分钟，hermes auth spotify 会引导你完成。
前提条件
- 一个 Spotify 账户。免费账户适用于搜索、播放列表、资料库和活动工具。Premium 账户用于播放控制（播放、暂停、跳过、定位、音量、加入队列、转移）。
- 已安装并运行 Hermes Agent。
- 对于播放工具：一个活跃的 Spotify Connect 设备——Spotify 应用必须在至少一台设备（手机、桌面端、网页播放器、音箱）上打开，这样 Web API 才有东西可以控制。如果没有活跃设备，你会收到带有"no active device"消息的
403 Forbidden；在任意设备上打开 Spotify 后重试。
设置
一步完成：hermes tools
最快的方式。运行：
hermes tools
滚动到 🎵 Spotify，按空格键开启，然后按 s 保存。Hermes 会直接进入 OAuth 流程——如果你还没有 Spotify 应用，它会内联引导你创建一个。完成后，工具集在一次操作中完成启用和认证。
如果你更喜欢分步操作（或稍后重新认证），请使用下面的两步流程。
两步流程
1. 启用工具集
hermes tools
开启 🎵 Spotify，保存，当内联向导打开时，关闭它（Ctrl+C）。工具集保持开启；只有认证步骤被延迟。
2. 运行登录向导
hermes auth spotify
7 个 Spotify 工具只有在步骤 1 之后才会出现在 Agent 的工具集中——它们默认关闭，这样不需要它们的用户就不会在每次 API 调用时携带额外的工具模式。
如果没有设置 HERMES_SPOTIFY_CLIENT_ID，Hermes 会内联引导你完成应用注册：
- 在浏览器中打开
https://developer.spotify.com/dashboard - 打印要粘贴到 Spotify"创建应用"表单中的确切值
- 提示你输入获得的 Client ID
- 将其保存到
~/.hermes/.env，以便未来运行跳过此步骤 - 直接继续进入 OAuth 授权流程
批准后，token 会写入 ~/.hermes/auth.json 的 providers.spotify 下。活跃的推理提供商不会改变——Spotify 认证独立于你的 LLM 提供商。
创建 Spotify 应用（向导的要求）
当仪表板打开时，点击创建应用并填写：
| 字段 | 值 |
|---|---|
| App name | 任意（如 hermes-agent） |
| App description | 任意（如 personal Hermes integration） |
| Website | 留空 |
| Redirect URI | http://127.0.0.1:43827/spotify/callback |
| Which API/SDKs? | 勾选 Web API |
同意条款并点击保存。在下一页点击设置 → 复制 Client ID 并粘贴到 Hermes 提示中。这是 Hermes 唯一需要的值——PKCE 不使用客户端密钥。
通过 SSH / 无头环境运行
如果设置了 SSH_CLIENT 或 SSH_TTY，Hermes 在向导和 OAuth 步骤期间会跳过自动打开浏览器。复制 Hermes 打印的仪表板 URL 和授权 URL，在本地机器的浏览器中打开，然后正常操作——本地 HTTP 监听器仍在远程主机的端口 43827 上运行。如果你需要通过 SSH 隧道访问它，转发该端口：ssh -L 43827:127.0.0.1:43827 remote。
验证
hermes auth status spotify
显示 token 是否存在以及访问令牌何时过期。刷新是自动的：当任何 Spotify API 调用返回 401 时，客户端会交换刷新令牌并重试一次。刷新令牌在 Hermes 重启后持久存在，因此只有在你从 Spotify 账户设置中撤销应用或运行 hermes auth logout spotify 时才需要重新认证。
使用方式
登录后，Agent 可以访问 7 个 Spotify 工具。你自然地与 Agent 对话——它会选择正确的工具和操作。为获得最佳行为，Agent 会加载一个伴随技能，教授规范使用模式（单次搜索后播放、何时不要预检 get_state 等）。
> play some miles davis
> what am I listening to
> add this track to my Late Night Jazz playlist
> skip to the next song
> make a new playlist called "Focus 2026" and add the last three songs I played
> which of my saved albums are by Radiohead
> search for acoustic covers of Blackbird
> transfer playback to my kitchen speaker
工具参考
所有修改播放的操作都接受可选的 device_id 来指定目标设备。如果省略，Spotify 使用当前活跃设备。
spotify_playback
控制和检查播放，以及获取最近播放历史。
| 操作 | 目的 | 需要 Premium？ |
|---|---|---|
get_state | 完整播放状态（曲目、设备、进度、随机/重复） | 否 |
get_currently_playing | 仅当前曲目（204 时返回空——见下文） | 否 |
play | 开始/恢复播放。可选：context_uri、uris、offset、position_ms | 是 |
pause | 暂停播放 | 是 |
next / previous | 跳过曲目 | 是 |
seek | 跳转到 position_ms | 是 |
set_repeat | state = track / context / off | 是 |
set_shuffle | state = true / false | 是 |
set_volume | volume_percent = 0-100 | 是 |
recently_played | 最近播放的曲目。可选 limit、before、after（Unix 毫秒） | 否 |
spotify_devices
| 操作 | 目的 |
|---|---|
list | 账户可见的每个 Spotify Connect 设备 |
transfer | 将播放移动到 device_id。可选 play: true 在转移时开始播放 |
spotify_queue
| 操作 | 目的 | 需要 Premium？ |
|---|---|---|
get | 当前队列中的曲目 | 否 |
add | 将 uri 追加到队列 | 是 |
spotify_search
搜索目录。query 为必填项。可选：types（track / album / artist / playlist / show / episode 的数组）、limit、offset、market。
spotify_playlists
| 操作 | 目的 | 必填参数 |
|---|---|---|
list | 用户的播放列表 | — |
get | 一个播放列表 + 曲目 | playlist_id |
create | 新播放列表 | name（+ 可选 description、public、collaborative） |
add_items | 添加曲目 | playlist_id、uris（可选 position） |
remove_items | 移除曲目 | playlist_id、uris（+ 可选 snapshot_id） |
update_details | 重命名/编辑 | playlist_id + name、description、public、collaborative 中的任意 |
spotify_albums
| 操作 | 目的 | 必填参数 |
|---|---|---|
get | 专辑元数据 | album_id |
tracks | 专辑曲目列表 | album_id |
spotify_library
统一访问已保存的曲目和已保存的专辑。用 kind 参数选择集合。
| 操作 | 目的 |
|---|---|
list | 分页资料库列表 |
save | 将 ids / uris 添加到资料库 |
remove | 从资料库移除 ids / uris |
必填：kind = tracks 或 albums，以及 action。
功能矩阵：免费版 vs Premium
只读工具适用于免费账户。任何修改播放或队列的操作都需要 Premium。
| 免费版可用 | 需要 Premium |
|---|---|
spotify_search（全部） | spotify_playback — play、pause、next、previous、seek、set_repeat、set_shuffle、set_volume |
spotify_playback — get_state、get_currently_playing、recently_played | spotify_queue — add |
spotify_devices — list | spotify_devices — transfer |
spotify_queue — get | |
spotify_playlists（全部） | |
spotify_albums（全部） | |
spotify_library（全部） |
调度：Spotify + cron
由于 Spotify 工具是普通的 Hermes 工具，在 Hermes 会话中运行的 cron 任务可以按任意计划触发播放。不需要任何新代码。
早晨唤醒播放列表
hermes cron add \
--name "morning-commute" \
"0 7 * * 1-5" \
"Transfer playback to my kitchen speaker and start my 'Morning Commute' playlist. Volume to 40. Shuffle on."
每个工作日早上 7 点发生的事：
- Cron 启动一个无头 Hermes 会话。
- Agent 读取提示词，调用
spotify_devices list按名称查找"kitchen speaker"，然后spotify_devices transfer→spotify_playback set_volume→spotify_playback set_shuffle→spotify_search+spotify_playback play。 - 音乐在目标音箱上开始播放。总消耗：一个会话，几次工具调用，无需人工输入。
夜间舒缓
hermes cron add \
--name "wind-down" \
"30 22 * * *" \
"Pause Spotify. Then set volume to 20 so it's quiet when I start it again tomorrow."
注意事项
- cron 触发时必须存在活跃设备。 如果没有 Spotify 客户端运行（手机/桌面/Connect 音箱），播放操作返回
403 no active device。对于早晨播放列表，技巧是以始终开启的设备（Sonos、Echo、智能音箱）为目标，而非手机。 - 任何修改播放的操作都需要 Premium — 播放、暂停、跳过、音量、转移。只读 cron 任务（定时"给我发最近播放的曲目邮件"）在免费版上也能正常工作。
- cron Agent 继承你的活跃工具集。 Spotify 必须在
hermes tools中启用，cron 会话才能看到 Spotify 工具。 - Cron 任务以
skip_memory=True运行，因此不会写入你的记忆存储。
完整 cron 参考：定时任务。
退出登录
hermes auth logout spotify
从 ~/.hermes/auth.json 中移除 token。要同时清除应用配置，从 ~/.hermes/.env 中删除 HERMES_SPOTIFY_CLIENT_ID（以及 HERMES_SPOTIFY_REDIRECT_URI 如果已设置），或再次运行向导。
要在 Spotify 端撤销应用，访问已连接到你账户的应用并点击 REMOVE ACCESS。
故障排查
403 Forbidden — Player command failed: No active device found — 你需要在至少一台设备上运行 Spotify。在手机、桌面端或网页播放器上打开 Spotify 应用，播放一秒钟以注册它，然后重试。spotify_devices list 显示当前可见的设备。
403 Forbidden — Premium required — 你在免费账户上尝试使用需要 Premium 的播放操作。查看上方的功能矩阵。
get_currently_playing 返回 204 No Content — 当前所有设备上都没有在播放任何内容。这是 Spotify 的正常响应，不是错误；Hermes 将其呈现为解释性的空结果（is_playing: false）。
INVALID_CLIENT: Invalid redirect URI — Spotify 应用设置中的重定向 URI 与 Hermes 使用的不匹配。默认是 http://127.0.0.1:43827/spotify/callback。要么将其添加到应用的允许重定向 URI 中，要么在 ~/.hermes/.env 中将 HERMES_SPOTIFY_REDIRECT_URI 设置为你注册的值。
429 Too Many Requests — Spotify 的速率限制。Hermes 返回友好错误；等一分钟后重试。如果持续出现，你可能在脚本中运行了紧密循环——Spotify 的配额大约每 30 秒重置一次。
401 Unauthorized 持续出现 — 你的刷新令牌已被撤销（通常是因为你从账户中移除了应用，或应用被删除）。再次运行 hermes auth spotify。
向导没有打开浏览器 — 如果你通过 SSH 或在没有显示器的容器中，Hermes 会检测到并跳过自动打开。复制它打印的仪表板 URL 并手动打开。
高级：自定义权限范围
默认情况下，Hermes 请求每个已发布工具所需的权限范围。如需限制访问，可覆盖：
hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"
权限范围参考：Spotify Web API scopes。如果你请求的范围少于工具所需，该工具的调用将以 403 失败。
高级：自定义客户端 ID / 重定向 URI
hermes auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback
或在 ~/.hermes/.env 中永久设置：
HERMES_SPOTIFY_CLIENT_ID=<your_id>
HERMES_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback
重定向 URI 必须在 Spotify 应用设置中加入允许列表。默认值适用于大多数人——只有在端口 43827 被占用时才需要更改。
文件位置
| 文件 | 内容 |
|---|---|
~/.hermes/auth.json → providers.spotify | 访问令牌、刷新令牌、过期时间、权限范围、重定向 URI |
~/.hermes/.env | HERMES_SPOTIFY_CLIENT_ID、可选 HERMES_SPOTIFY_REDIRECT_URI |
| Spotify 应用 | 由你在 developer.spotify.com/dashboard 持有；包含 Client ID 和重定向 URI 允许列表 |