Deepseek-V4
Minimax-M2.7
Kimi-k2.6Spotify
Hermes 可以使用 Spotify 官方 Web API 配合 PKCE OAuth 直接控制 Spotify——包括播放、隊列、搜索、播放列表、已保存的曲目/專輯以及收聽歷史。令牌存儲在 ~/.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
只有在完成第 1 步後，7 個 Spotify 工具才會出現在 agent 的工具集中——它們默認處於關閉狀態，這樣不需要它們的用戶就不會在每次 API 調用中攜帶額外的工具 schema。
如果未設置 HERMES_SPOTIFY_CLIENT_ID，Hermes 會引導你內聯完成應用註冊：
- 在瀏覽器中打開
https://developer.spotify.com/dashboard - 打印出需要粘貼到 Spotify “Create app”表單中的確切值
- 提示你輸入獲得的 Client ID
- 將其保存到
~/.hermes/.env，以便後續運行跳過此步驟 - 直接進入 OAuth 同意流程
批准後，令牌將寫入 ~/.hermes/auth.json 下的 providers.spotify 中。當前推理提供程序不會更改——Spotify 認證獨立於你的 LLM 提供程序。
創建 Spotify 應用（嚮導所需內容）
當儀表板打開時，點擊 Create app 並填寫：
| 字段 | 值 |
|---|---|
| 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 |
同意條款並點擊 Save。在下一頁點擊 Settings → 複製 Client ID 並將其粘貼到 Hermes 提示符中。這是 Hermes 需要的唯一值——PKCE 不使用 client secret。
通過 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
顯示是否存在令牌以及訪問令牌何時過期。刷新是自動的：當任何 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。
功能矩陣：Free 與 Premium
只讀工具適用於 Free 賬戶。任何改變播放狀態或隊列的操作都需要 Premium。
| 適用於 Free | 需要 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 任務（例如定時“通過電子郵件發送我最近播放的曲目”）在 Free 賬戶上正常工作。
- Cron agent 繼承您激活的工具集。 必須在
hermes tools中啟用 Spotify，cron 會話才能看到 Spotify 工具。 - Cron 任務以
skip_memory=True運行，因此它們不會寫入您的記憶存儲。
完整 cron 參考：Cron Jobs。
退出登錄
hermes auth logout spotify
從 ~/.hermes/auth.json 中移除令牌。若要同時清除應用配置，請從 ~/.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 — 你使用的是免費賬戶，但嘗試執行會改變播放狀態的操作。請參閱上方的功能矩陣。
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 為你註冊的 URI。
429 Too Many Requests — 觸發了 Spotify 的速率限制。Hermes 會返回一個友好的錯誤提示；請等待一分鐘後再重試。如果問題持續存在，你可能在腳本中運行了緊密循環 — Spotify 的配額大約每 30 秒重置一次。
401 Unauthorized 持續出現 — 你的刷新令牌已被撤銷（通常是因為你從賬戶中移除了該應用，或者該應用已被刪除）。請再次運行 hermes auth spotify。
嚮導未打開瀏覽器 — 如果你通過 SSH 連接或在沒有顯示界面的容器中運行，Hermes 會檢測到這種情況並跳過自動打開瀏覽器的步驟。請複製它打印出的儀表板 URL 並手動打開。
高級：自定義 scopes
默認情況下，Hermes 會請求所有內置工具所需的 scopes。如果你希望限制訪問權限，可以進行覆蓋：
hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"
Scope 參考：Spotify Web API scopes。如果你請求的 scopes 少於某個工具所需，該工具的調用將因 403 錯誤而失敗。
高級：自定義 client 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 | access token、refresh token、過期時間、scope、重定向 URI |
~/.hermes/.env | HERMES_SPOTIFY_CLIENT_ID，可選的 HERMES_SPOTIFY_REDIRECT_URI |
| Spotify 應用 | 由你在 developer.spotify.com/dashboard 擁有；包含 Client ID 和重定向 URI 允許列表 |