{
  "schemaVersion": "1.0",
  "item": {
    "slug": "clawspotify",
    "name": "ClawSpotify",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/ejatapibeda/clawspotify",
    "canonicalUrl": "https://clawhub.ai/ejatapibeda/clawspotify",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/clawspotify",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=clawspotify",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      ".gitattributes",
      "clawspotify.sh",
      "README.md",
      "SKILL.md",
      "scripts/spotify.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/clawspotify"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/clawspotify",
    "agentPageUrl": "https://openagent3.xyz/skills/clawspotify/agent",
    "manifestUrl": "https://openagent3.xyz/skills/clawspotify/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/clawspotify/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "ClawSpotify 🎵",
        "body": "Control your Spotify playback directly from your OpenClaw agent or terminal. Works with both Free and Premium Spotify accounts."
      },
      {
        "title": "Via ClawHub (recommended)",
        "body": "clawhub install clawspotify"
      },
      {
        "title": "Manual from GitHub",
        "body": "# Clone main skill\ngit clone https://github.com/ejatapibeda/ClawSpotify.git ~/.openclaw/workspace/skills/ClawSpotify\n\n# Create virtual environment\npython3 -m venv ~/.venv-clawspotify\n\n# Install SpotAPI (modified version with session support)\ngit clone https://github.com/ejatapibeda/SpotAPI.git ~/.openclaw/workspace/skills/SpotAPI\n~/.venv-clawspotify/bin/pip install -e ~/.openclaw/workspace/skills/SpotAPI\n\n# Create wrapper script\ncat > ~/.local/bin/clawspotify << 'EOF'\n#!/bin/bash\nVENV=\"/home/$(whoami)/.venv-clawspotify\"\nSCRIPT_DIR=\"/home/$(whoami)/.openclaw/workspace/skills/ClawSpotify\"\nexec \"$VENV/bin/python\" \"$SCRIPT_DIR/scripts/spotify.py\" \"$@\"\nEOF\nchmod +x ~/.local/bin/clawspotify\n\n# Ensure ~/.local/bin is in PATH\nexport PATH=\"$HOME/.local/bin:$PATH\""
      },
      {
        "title": "Dependencies",
        "body": "Python 3.10+\nSpotAPI (custom version from ejatapibeda/SpotAPI)\nActive Spotify account (Free or Premium)\nSpotify app open on at least one device (PC/phone/web) for playback commands to work"
      },
      {
        "title": "🔐 First-Time Setup (Authentication)",
        "body": "clawspotify authenticates using two session cookies from your browser (sp_dc and sp_key). You only need to do this once per account."
      },
      {
        "title": "Step-by-step",
        "body": "Open https://open.spotify.com in your browser and log in\nPress F12 to open DevTools\nGo to Application tab → Cookies → https://open.spotify.com\nFind and copy the value of sp_dc\nFind and copy the value of sp_key\nRun:\n\nclawspotify setup --sp-dc \"AQC...\" --sp-key \"07c9...\"\n\nSession is saved to ~/.config/spotapi/session.json and reused automatically.\n\nMulti-account support\n\nclawspotify setup --sp-dc \"...\" --sp-key \"...\" --id \"work\"\nclawspotify status --id \"work\"\n\nNote: Cookies expire periodically. If commands fail with a 401 error, re-run setup with fresh cookies."
      },
      {
        "title": "Now playing status",
        "body": "clawspotify status            # default account\nclawspotify status --id work  # specific account"
      },
      {
        "title": "Search music (without playing)",
        "body": "clawspotify search \"Bohemian Rhapsody\"        # search tracks, show top 5\nclawspotify search-playlist \"Workout\"         # search playlists, show top 5"
      },
      {
        "title": "Search and play",
        "body": "clawspotify play \"Bohemian Rhapsody\"          # play first result\nclawspotify play \"Bohemian Rhapsody\" --index 2  # pick result #2 (0-indexed)\nclawspotify play-playlist \"Lofi Girl\"         # play first playlist result"
      },
      {
        "title": "Playback controls",
        "body": "clawspotify pause\nclawspotify resume\nclawspotify skip                     # next track\nclawspotify prev                     # previous track\nclawspotify restart                  # restart from beginning"
      },
      {
        "title": "Queue",
        "body": "clawspotify queue \"Stairway to Heaven\"\nclawspotify queue \"spotify:track:3z8h0TU...\"  # add by URI"
      },
      {
        "title": "Volume",
        "body": "clawspotify volume 50     # set to 50%\nclawspotify volume 0      # mute\nclawspotify volume 100    # max"
      },
      {
        "title": "Shuffle / Repeat",
        "body": "clawspotify shuffle on\nclawspotify shuffle off\nclawspotify repeat on\nclawspotify repeat off"
      },
      {
        "title": "💡 Usage Tips",
        "body": "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.\nFirst run may be slow (10-30 seconds) due to WebSocket handshake and device registration. Subsequent commands are faster.\nSession identifier: Default is \"default\". Use --id flag to manage multiple Spotify accounts.\nSearch is fuzzy: Use artist name + title for best results.\nOutput: Commands print status messages (e.g., Searching for \"...\", Playing: URI)."
      },
      {
        "title": "\"No active Spotify device found\"",
        "body": "Open Spotify on any device (PC, phone, or web) and start playing something first.\nEnsure you're logged in with the same account as the cookies."
      },
      {
        "title": "\"spotapi is not installed\" or import errors",
        "body": "Verify virtual environment: ls ~/.venv-clawspotify/bin/python\nReinstall SpotAPI: ~/.venv-clawspotify/bin/pip install -e ~/.openclaw/workspace/skills/SpotAPI"
      },
      {
        "title": "401 Unauthorized / Session expired",
        "body": "Cookies (sp_dc, sp_key) expire. Re-run clawspotify setup with fresh cookies from browser."
      },
      {
        "title": "Commands time out or hang",
        "body": "The skill uses WebSockets for real-time state. If Spotify's API is slow, commands may take longer. Use longer timeout or background execution.\nRestart OpenClaw gateway to reload skill if it becomes unresponsive."
      },
      {
        "title": "Wrapper not found (command not found: clawspotify)",
        "body": "Ensure ~/.local/bin is in your PATH: echo $PATH\nOr run directly: ~/.venv-clawspotify/bin/python ~/.openclaw/workspace/skills/ClawSpotify/scripts/spotify.py <command>"
      },
      {
        "title": "📂 File Locations",
        "body": "ComponentPathSkill folder~/.openclaw/workspace/skills/ClawSpotifyWrapper script~/.local/bin/clawspotifyVirtualenv~/.venv-clawspotifySpotAPI (editable)~/.openclaw/workspace/skills/SpotAPISession credentials~/.config/spotapi/session.jsonMain script~/skills/ClawSpotify/scripts/spotify.py"
      },
      {
        "title": "🔧 Agent Implementation Notes",
        "body": "When using this skill via OpenClaw agent:\n\nPlayback commands (play, pause, skip, etc.) are asynchronous. The command returns once Spotify accepts the request. Actual playback may take a few seconds to start.\nLong-running operations: Use background execution or extended timeout (15-30 seconds) for play, search, and status to avoid premature termination.\nStatus query may occasionally timeout due to WebSocket latency. Play commands are more reliable.\nAlways check Spotify app/device for actual playback state. The CLI reports what Spotify acknowledges.\nIf the skill becomes unresponsive, restart the OpenClaw gateway to clear WebSocket connections."
      },
      {
        "title": "🌐 Platform Note",
        "body": "Linux/macOS: Works natively with bash.\nWindows: Requires WSL, Git Bash, or Cygwin to run the clawspotify bash script. Alternatively, run Python directly:\npython ~/.openclaw/workspace/skills/ClawSpotify/scripts/spotify.py play \"song name\"\n\nVersion: 1.0.1 (skill) | SpotAPI: 1.2.7 (custom)\nHomepage: https://github.com/ejatapibeda/ClawSpotify\nAuthor: Deli (OpenClaw agent) + ejatapibeda (original author)"
      }
    ],
    "body": "ClawSpotify 🎵\n\nControl your Spotify playback directly from your OpenClaw agent or terminal. Works with both Free and Premium Spotify accounts.\n\n📦 Installation\nVia ClawHub (recommended)\nclawhub install clawspotify\n\nManual from GitHub\n# Clone main skill\ngit clone https://github.com/ejatapibeda/ClawSpotify.git ~/.openclaw/workspace/skills/ClawSpotify\n\n# Create virtual environment\npython3 -m venv ~/.venv-clawspotify\n\n# Install SpotAPI (modified version with session support)\ngit clone https://github.com/ejatapibeda/SpotAPI.git ~/.openclaw/workspace/skills/SpotAPI\n~/.venv-clawspotify/bin/pip install -e ~/.openclaw/workspace/skills/SpotAPI\n\n# Create wrapper script\ncat > ~/.local/bin/clawspotify << 'EOF'\n#!/bin/bash\nVENV=\"/home/$(whoami)/.venv-clawspotify\"\nSCRIPT_DIR=\"/home/$(whoami)/.openclaw/workspace/skills/ClawSpotify\"\nexec \"$VENV/bin/python\" \"$SCRIPT_DIR/scripts/spotify.py\" \"$@\"\nEOF\nchmod +x ~/.local/bin/clawspotify\n\n# Ensure ~/.local/bin is in PATH\nexport PATH=\"$HOME/.local/bin:$PATH\"\n\nDependencies\nPython 3.10+\nSpotAPI (custom version from ejatapibeda/SpotAPI)\nActive Spotify account (Free or Premium)\nSpotify app open on at least one device (PC/phone/web) for playback commands to work\n🔐 First-Time Setup (Authentication)\n\nclawspotify authenticates using two session cookies from your browser (sp_dc and sp_key). You only need to do this once per account.\n\nStep-by-step\nOpen https://open.spotify.com in your browser and log in\nPress F12 to open DevTools\nGo to Application tab → Cookies → https://open.spotify.com\nFind and copy the value of sp_dc\nFind and copy the value of sp_key\nRun:\nclawspotify setup --sp-dc \"AQC...\" --sp-key \"07c9...\"\n\n\nSession is saved to ~/.config/spotapi/session.json and reused automatically.\n\nMulti-account support\nclawspotify setup --sp-dc \"...\" --sp-key \"...\" --id \"work\"\nclawspotify status --id \"work\"\n\n\nNote: Cookies expire periodically. If commands fail with a 401 error, re-run setup with fresh cookies.\n\n🎮 Commands\nNow playing status\nclawspotify status            # default account\nclawspotify status --id work  # specific account\n\nSearch music (without playing)\nclawspotify search \"Bohemian Rhapsody\"        # search tracks, show top 5\nclawspotify search-playlist \"Workout\"         # search playlists, show top 5\n\nSearch and play\nclawspotify play \"Bohemian Rhapsody\"          # play first result\nclawspotify play \"Bohemian Rhapsody\" --index 2  # pick result #2 (0-indexed)\nclawspotify play-playlist \"Lofi Girl\"         # play first playlist result\n\nPlayback controls\nclawspotify pause\nclawspotify resume\nclawspotify skip                     # next track\nclawspotify prev                     # previous track\nclawspotify restart                  # restart from beginning\n\nQueue\nclawspotify queue \"Stairway to Heaven\"\nclawspotify queue \"spotify:track:3z8h0TU...\"  # add by URI\n\nVolume\nclawspotify volume 50     # set to 50%\nclawspotify volume 0      # mute\nclawspotify volume 100    # max\n\nShuffle / Repeat\nclawspotify shuffle on\nclawspotify shuffle off\nclawspotify repeat on\nclawspotify repeat off\n\n💡 Usage Tips\nSpotify 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.\nFirst run may be slow (10-30 seconds) due to WebSocket handshake and device registration. Subsequent commands are faster.\nSession identifier: Default is \"default\". Use --id flag to manage multiple Spotify accounts.\nSearch is fuzzy: Use artist name + title for best results.\nOutput: Commands print status messages (e.g., Searching for \"...\", Playing: URI).\n⚠️ Troubleshooting\n\"No active Spotify device found\"\nOpen Spotify on any device (PC, phone, or web) and start playing something first.\nEnsure you're logged in with the same account as the cookies.\n\"spotapi is not installed\" or import errors\nVerify virtual environment: ls ~/.venv-clawspotify/bin/python\nReinstall SpotAPI: ~/.venv-clawspotify/bin/pip install -e ~/.openclaw/workspace/skills/SpotAPI\n401 Unauthorized / Session expired\nCookies (sp_dc, sp_key) expire. Re-run clawspotify setup with fresh cookies from browser.\nCommands time out or hang\nThe skill uses WebSockets for real-time state. If Spotify's API is slow, commands may take longer. Use longer timeout or background execution.\nRestart OpenClaw gateway to reload skill if it becomes unresponsive.\nWrapper not found (command not found: clawspotify)\nEnsure ~/.local/bin is in your PATH: echo $PATH\nOr run directly: ~/.venv-clawspotify/bin/python ~/.openclaw/workspace/skills/ClawSpotify/scripts/spotify.py <command>\n📂 File Locations\nComponent\tPath\nSkill folder\t~/.openclaw/workspace/skills/ClawSpotify\nWrapper script\t~/.local/bin/clawspotify\nVirtualenv\t~/.venv-clawspotify\nSpotAPI (editable)\t~/.openclaw/workspace/skills/SpotAPI\nSession credentials\t~/.config/spotapi/session.json\nMain script\t~/skills/ClawSpotify/scripts/spotify.py\n🔧 Agent Implementation Notes\n\nWhen using this skill via OpenClaw agent:\n\nPlayback commands (play, pause, skip, etc.) are asynchronous. The command returns once Spotify accepts the request. Actual playback may take a few seconds to start.\nLong-running operations: Use background execution or extended timeout (15-30 seconds) for play, search, and status to avoid premature termination.\nStatus query may occasionally timeout due to WebSocket latency. Play commands are more reliable.\nAlways check Spotify app/device for actual playback state. The CLI reports what Spotify acknowledges.\nIf the skill becomes unresponsive, restart the OpenClaw gateway to clear WebSocket connections.\n🌐 Platform Note\nLinux/macOS: Works natively with bash.\nWindows: Requires WSL, Git Bash, or Cygwin to run the clawspotify bash script. Alternatively, run Python directly:\npython ~/.openclaw/workspace/skills/ClawSpotify/scripts/spotify.py play \"song name\"\n\n\nVersion: 1.0.1 (skill) | SpotAPI: 1.2.7 (custom) Homepage: https://github.com/ejatapibeda/ClawSpotify Author: Deli (OpenClaw agent) + ejatapibeda (original author)"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/ejatapibeda/clawspotify",
    "publisherUrl": "https://clawhub.ai/ejatapibeda/clawspotify",
    "owner": "ejatapibeda",
    "version": "1.0.3",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/clawspotify",
    "downloadUrl": "https://openagent3.xyz/downloads/clawspotify",
    "agentUrl": "https://openagent3.xyz/skills/clawspotify/agent",
    "manifestUrl": "https://openagent3.xyz/skills/clawspotify/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/clawspotify/agent.md"
  }
}