{ "schemaVersion": "1.0", "item": { "slug": "suno-headless-skill", "name": "revol-suno-headless-skill", "source": "tencent", "type": "skill", "category": "AI 智能", "sourceUrl": "https://clawhub.ai/RevolGMPHL/suno-headless-skill", "canonicalUrl": "https://clawhub.ai/RevolGMPHL/suno-headless-skill", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/suno-headless-skill", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=suno-headless-skill", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "output_manager.py", "suno_create_song.py", "requirements.txt", "patch_hcaptcha.py", "suno_login.py", "check_env.sh" ], "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. 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. 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/suno-headless-skill" }, "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/suno-headless-skill", "agentPageUrl": "https://openagent3.xyz/skills/suno-headless-skill/agent", "manifestUrl": "https://openagent3.xyz/skills/suno-headless-skill/agent.json", "briefUrl": "https://openagent3.xyz/skills/suno-headless-skill/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. 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. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "🎵 Suno AI 音乐创作助手（Headless Linux 专用版）", "body": "专为 无图形界面的 Linux 云服务器 设计，通过 Xvfb 虚拟显示 在没有显示器的环境下运行 Chrome GUI 模式，绕过 Google 反自动化检测。\n\n两大核心能力：账号登录（通过 Google OAuth）和 歌曲创作（自定义歌词+风格+下载）。" }, { "title": "零、前置检查", "body": "每次操作前必须先执行环境检查：\n\nbash {baseDir}/suno-headless/check_env.sh\n\n返回码：0 = 正常已登录 → 可直接创建歌曲；1 = 缺少依赖 → 安装依赖；2 = 未登录 → 登录流程。" }, { "title": "1.1 系统依赖", "body": "# Xvfb 虚拟显示（核心依赖，无 GUI 环境必装）\nsudo apt update && sudo apt install -y xvfb\n\n# Google Chrome 浏览器\nwget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -\necho \"deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main\" | sudo tee /etc/apt/sources.list.d/google-chrome.list\nsudo apt update && sudo apt install -y google-chrome-stable\n\n# 中文字体支持（歌词含中文时需要）\nsudo apt install -y fonts-noto-cjk" }, { "title": "1.2 Python 依赖", "body": "cd {baseDir}/suno-headless\npip3 install -r requirements.txt\nplaywright install" }, { "title": "二、登录流程", "body": "⚠️ 重要：不要在 skill 代码中硬编码账号密码！必须先询问用户的凭据。\n\n提供两种登录方式：\n\n方式 A: Cookie 导入（🌟 推荐！完美绕过 Google 安全验证）\n方式 B: 邮箱密码直接登录（可能触发 Google 安全验证）" }, { "title": "2.1 方式 A: Cookie 导入（推荐）", "body": "这是云服务器上最稳定的登录方式，完全绕过 Google 的安全验证。\n\n操作步骤：\n\n当需要登录时，向用户说明：\n\n🍪 推荐使用 Cookie 导入方式登录（绕过 Google 安全验证）：\n步骤 1: 在你的本地电脑（有浏览器的）上运行：\npip install playwright && playwright install\npython3 export_cookies.py\n\n这会打开浏览器，你手动登录 Suno，登录成功后自动导出 Cookie 文件。\n步骤 2: 把导出的 Cookie 文件上传到服务器固定路径：\nscp <本地导出的Cookie文件> user@your-server:/root/suno_cookie/suno_cookies.json\n\n步骤 3: 上传完成后告诉我，我来导入。\n\n用户上传文件后，执行导入。脚本会自动检测 /root/suno_cookie/suno_cookies.json 是否存在，存在则自动导入，无需额外指定参数：\n\ncd {baseDir}/suno-headless\npython3 suno_login.py\n\n也可以显式指定 Cookie 文件路径：\n\npython3 suno_login.py --import-cookies /path/to/cookies.json" }, { "title": "2.2 方式 B: 邮箱密码登录", "body": "⚠️ 注意：云服务器上可能触发 Google 安全验证，推荐优先使用方式 A。\n\n当需要登录时，必须先向用户询问：\n\n需要登录 Suno.com（通过 Google 账号）。请提供：\n\nGmail 邮箱地址\nGmail 密码\n\n⚠️ 你的凭据仅用于本次登录，不会被存储或传输到任何第三方。\n\n用户提供邮箱和密码后：\n\ncd {baseDir}/suno-headless\npython3 suno_login.py --email \"<用户邮箱>\" --password \"<用户密码>\"\n\nHeadless Linux 模式说明：\n\n脚本会自动检测无 GUI 环境（无 $DISPLAY 变量）\n自动启动 Xvfb 虚拟显示，在内存中模拟一个假显示器\nChrome 以 GUI 模式运行（headless=False），但屏幕上不显示任何东西\n这样可以绕过 Google 对 headless 浏览器的检测拦截" }, { "title": "2.3 检查登录状态", "body": "cd {baseDir}/suno-headless\npython3 suno_login.py --check-only\n\n退出码 0 = 已登录，2 = 未登录。" }, { "title": "2.4 强制重新登录", "body": "# 方式 A: 重新导入 Cookie\ncd {baseDir}/suno-headless\npython3 suno_login.py --import-cookies \"<新的Cookie文件>\"\n\n# 方式 B: 邮箱密码重新登录\ncd {baseDir}/suno-headless\npython3 suno_login.py --email \"<邮箱>\" --password \"<密码>\" --force-login" }, { "title": "3.1 前置条件", "body": "已完成登录（suno_login.py --check-only 返回 0）\n需要 Gemini API Key（用于自动解决 hCaptcha 验证码）" }, { "title": "3.2 获取 Gemini API Key", "body": "如果用户没有 Gemini API Key，引导用户获取：\n\n创建歌曲时 Suno 会弹出验证码，需要 Gemini API Key 来自动解决。\n\n访问 https://aistudio.google.com/app/apikey\n点击 \"Create API key\"\n复制生成的 Key\n\n获取后保存到环境文件：\n\nmkdir -p ~/.suno\necho \"GEMINI_API_KEY=<用户的key>\" > ~/.suno/.env\n\n或通过环境变量：\n\nexport GEMINI_API_KEY=\"<用户的key>\"" }, { "title": "3.3 hCaptcha 兼容补丁", "body": "首次使用前需运行一次（Suno 使用自定义 hCaptcha 域名，需打补丁）：\n\ncd {baseDir}/suno-headless\npython3 patch_hcaptcha.py" }, { "title": "3.4 创建歌曲命令", "body": "cd {baseDir}/suno-headless\npython3 suno_create_song.py \\\n --lyrics \"<歌词内容>\" \\\n --style \"<音乐风格标签>\" \\\n --title \"<歌曲标题>\" \\\n --output-dir \"<下载目录>\"\n\n也可以从文件读取歌词：\n\ncd {baseDir}/suno-headless\npython3 suno_create_song.py \\\n --lyrics-file \"<歌词文件路径>\" \\\n --style \"<音乐风格标签>\" \\\n --title \"<歌曲标题>\"\n\nHeadless 模式说明：\n\nsuno_create_song.py 会自动检测无 GUI 环境\n自动启动 Xvfb 虚拟显示，Chrome 以 GUI 模式在虚拟显示中运行\n脚本结束后自动关闭虚拟显示，无需手动操作" }, { "title": "3.5 参数说明", "body": "参数说明必填默认值--lyrics歌词内容（与 --lyrics-file 二选一）✅---lyrics-file歌词文件路径（与 --lyrics 二选一）✅---style音乐风格标签（英文，逗号分隔）❌rock, electric guitar, energetic, male vocals--title歌曲标题❌My Song--output-dirMP3 下载目录❌{baseDir}/output_mp3--gemini-keyGemini API Key（也可通过环境变量或 ~/.suno/.env）❌自动读取--verbose / -v详细输出模式（实时打印所有中间步骤）❌关闭（默认只输出最终摘要）\n\n📋 输出行为说明：默认情况下，所有脚本（suno_create_song.py、suno_login.py、export_cookies.py）只在完成时输出一条简洁的摘要，中间步骤的详细日志写入 {baseDir}/suno-headless/logs/ 目录。如需实时查看所有中间步骤，请添加 --verbose 或 -v 参数。" }, { "title": "3.6 音乐风格标签参考", "body": "常用风格标签（英文，可自由组合）：\n\n流派: rock, pop, jazz, blues, electronic, hip-hop, R&B, classical, folk, metal, country, reggae, latin, indie\n乐器: electric guitar, acoustic guitar, piano, synthesizer, drums, bass, violin, saxophone, trumpet\n情绪: energetic, emotional, melancholic, upbeat, dark, dreamy, aggressive, peaceful, romantic\n人声: male vocals, female vocals, choir, rap, whisper, powerful vocals, falsetto\n语言: chinese, japanese, korean, english, spanish\n其他: fast tempo, slow tempo, instrumental, lo-fi, cinematic, epic\n\n示例：\n\n摇滚: rock, electric guitar, energetic, male vocals, chinese\n抒情: pop, piano, emotional, female vocals, slow tempo, chinese\n电子: electronic, synthesizer, upbeat, fast tempo, dance\n说唱: hip-hop, rap, bass, drums, energetic, chinese" }, { "title": "示例：在 Linux 云服务器上创建中文摇滚歌曲", "body": "# 1. 检查环境（会自动检测 Xvfb、Chrome 等）\nbash {baseDir}/suno-headless/check_env.sh\n\n# 2. 如果未登录，使用 Cookie 导入方式登录（推荐）\n# 步骤 1: 在本地电脑运行 export_cookies.py 导出 Cookie\n# 步骤 2: scp user@server:/root/suno_cookie/suno_cookies.json\n# 步骤 3: 服务器上运行登录脚本（自动检测默认路径并导入）\ncd {baseDir}/suno-headless\npython3 suno_login.py\n\n# 或者使用邮箱密码方式（可能触发 Google 安全验证）\n# python3 suno_login.py --email \"user@gmail.com\" --password \"password123\"\n\n# 3. 确保 hCaptcha 补丁已应用\npython3 patch_hcaptcha.py\n\n# 4. 创建歌曲（自动使用 Xvfb 虚拟显示）\npython3 suno_create_song.py \\\n --lyrics \"窗外的麻雀 在电线杆上多嘴\n你说这一句 很有夏天的感觉\n手中的铅笔 在纸上来来回回\n我用几行字形容你是我的谁\" \\\n --style \"rock, electric guitar, energetic, male vocals, chinese\" \\\n --title \"七里香摇滚版\"" }, { "title": "五、与原版 suno skill 的区别", "body": "特性suno（原版）suno-headless（本版）目标环境macOS / 有 GUI 的 Linux无 GUI 的 Linux 云服务器显示方式弹出真实 Chrome 窗口Xvfb 虚拟显示（内存模拟）额外依赖无xvfb + PyVirtualDisplay登录 Xvfb✅ 已支持✅ 已支持创建歌曲 Xvfb❌ 不支持✅ 已支持环境检查基础检查增加 Xvfb/Chrome/字体检查" }, { "title": "Xvfb 虚拟显示方案", "body": "┌─────────────────────────────────────────┐\n│ Linux 云服务器（无显示器） │\n│ │\n│ ┌─────────────┐ ┌────────────────┐ │\n│ │ Xvfb │ │ Chrome │ │\n│ │ (虚拟显示器) │◄───│ (GUI 模式) │ │\n│ │ :99 1280x800│ │ headless=False │ │\n│ └─────────────┘ └────────────────┘ │\n│ ▲ │ │\n│ │ 自动操作 Suno.com │\n│ PyVirtualDisplay │ │\n│ 自动管理生命周期 ▼ │\n│ ┌────────────────┐ │\n│ │ 歌曲生成+下载 │ │\n│ └────────────────┘ │\n└─────────────────────────────────────────┘\n\n为什么不用 headless=True？ Google OAuth 会检测到 headless 浏览器并拒绝登录\nXvfb 方案：在内存中创建虚拟 X11 显示，Chrome 以为自己有真实 GUI，Google 无法检测到自动化\n自动检测：脚本检查 $DISPLAY 环境变量，无 GUI 时自动启用 Xvfb\n资源占用：Xvfb 仅占用极少内存，脚本结束后自动释放" }, { "title": "登录方案", "body": "使用 Playwright + 真实 Chrome 浏览器 (channel='chrome')\npersistent context 保持浏览器状态（cookies、localStorage）\nheadless=False + Xvfb 虚拟显示绕过 Google 反自动化\n首次登录后 persistent context 自动保持会话" }, { "title": "歌曲创建方案", "body": "浏览器自动化操作 suno.com/create 页面\nhcaptcha-challenger + Gemini API 自动解决 hCaptcha 验证码\n通过拦截浏览器网络响应捕获新生成的 clip ID\n通过 Suno 内部 API (studio-api.prod.suno.com) 轮询歌曲生成状态\n生成完成后自动下载 MP3 文件" }, { "title": "文件结构", "body": "suno-headless/\n├── suno_login.py # 登录工具（Google OAuth / Cookie 导入 + Xvfb）\n├── suno_create_song.py # 歌曲创建+下载工具（Xvfb 支持）\n├── export_cookies.py # Cookie 导出工具（在本地电脑上运行）\n├── output_manager.py # 输出管理器（控制日志和摘要）\n├── patch_hcaptcha.py # hCaptcha 域名兼容补丁\n├── check_env.sh # 环境检查脚本（含 Xvfb/Chrome 检查）\n├── requirements.txt # Python 依赖（含 PyVirtualDisplay）\n└── SKILL.md # 本文档" }, { "title": "七、注意事项", "body": "不要硬编码账号密码 — 每次都需要询问用户（推荐优先使用 Cookie 导入方式）\n必须安装 Xvfb — sudo apt install -y xvfb，否则无法在无 GUI 环境运行\n必须安装真实 Chrome — Playwright 自带的 Chromium 可能被 Google 检测\nSuno 免费账号每天有积分限制，每首歌消耗约 100 积分\n歌曲生成通常需要 1-3 分钟\n每次创建会生成 2 首不同版本的歌曲\n如果遇到 Google 登录被拒（rejected），等待 10-30 分钟后重试\nGemini API 免费额度：每分钟 15 次请求，每天 1500 次\nhCaptcha 可能需要多次尝试，成功率取决于 Gemini 模型的图片识别能力" }, { "title": "八、故障排查", "body": "# 检查环境（含 Xvfb 状态）\nbash {baseDir}/suno-headless/check_env.sh\n\n# 手动测试 Xvfb 是否正常\nXvfb :99 -screen 0 1280x800x24 &\nDISPLAY=:99 google-chrome --no-sandbox --version\nkill %1\n\n# 查看登录截图\nls -la /tmp/suno_debug_*.png\n\n# 检查 persistent context\nls -la ~/.suno/chrome_gui_profile/\n\n# 查看 cookies\npython3 -c \"import json; d=json.load(open('$HOME/.suno/cookies.json')); print(f'{len(d)} cookies')\"\n\n# 查看 Gemini API Key\ncat ~/.suno/.env\n\n# 查看下载的歌曲\nls -la {baseDir}/output_mp3/" } ], "body": "🎵 Suno AI 音乐创作助手（Headless Linux 专用版）\n\n专为 无图形界面的 Linux 云服务器 设计，通过 Xvfb 虚拟显示 在没有显示器的环境下运行 Chrome GUI 模式，绕过 Google 反自动化检测。\n\n两大核心能力：账号登录（通过 Google OAuth）和 歌曲创作（自定义歌词+风格+下载）。\n\n零、前置检查\n\n每次操作前必须先执行环境检查：\n\nbash {baseDir}/suno-headless/check_env.sh\n\n\n返回码：0 = 正常已登录 → 可直接创建歌曲；1 = 缺少依赖 → 安装依赖；2 = 未登录 → 登录流程。\n\n一、安装依赖（仅首次）\n1.1 系统依赖\n# Xvfb 虚拟显示（核心依赖，无 GUI 环境必装）\nsudo apt update && sudo apt install -y xvfb\n\n# Google Chrome 浏览器\nwget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -\necho \"deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main\" | sudo tee /etc/apt/sources.list.d/google-chrome.list\nsudo apt update && sudo apt install -y google-chrome-stable\n\n# 中文字体支持（歌词含中文时需要）\nsudo apt install -y fonts-noto-cjk\n\n1.2 Python 依赖\ncd {baseDir}/suno-headless\npip3 install -r requirements.txt\nplaywright install\n\n二、登录流程\n\n⚠️ 重要：不要在 skill 代码中硬编码账号密码！必须先询问用户的凭据。\n\n提供两种登录方式：\n\n方式 A: Cookie 导入（🌟 推荐！完美绕过 Google 安全验证）\n方式 B: 邮箱密码直接登录（可能触发 Google 安全验证）\n2.1 方式 A: Cookie 导入（推荐）\n\n这是云服务器上最稳定的登录方式，完全绕过 Google 的安全验证。\n\n操作步骤：\n\n当需要登录时，向用户说明：\n\n🍪 推荐使用 Cookie 导入方式登录（绕过 Google 安全验证）：\n\n步骤 1: 在你的本地电脑（有浏览器的）上运行：\n\npip install playwright && playwright install\npython3 export_cookies.py\n\n\n这会打开浏览器，你手动登录 Suno，登录成功后自动导出 Cookie 文件。\n\n步骤 2: 把导出的 Cookie 文件上传到服务器固定路径：\n\nscp <本地导出的Cookie文件> user@your-server:/root/suno_cookie/suno_cookies.json\n\n\n步骤 3: 上传完成后告诉我，我来导入。\n\n用户上传文件后，执行导入。脚本会自动检测 /root/suno_cookie/suno_cookies.json 是否存在，存在则自动导入，无需额外指定参数：\n\ncd {baseDir}/suno-headless\npython3 suno_login.py\n\n\n也可以显式指定 Cookie 文件路径：\n\npython3 suno_login.py --import-cookies /path/to/cookies.json\n\n2.2 方式 B: 邮箱密码登录\n\n⚠️ 注意：云服务器上可能触发 Google 安全验证，推荐优先使用方式 A。\n\n当需要登录时，必须先向用户询问：\n\n需要登录 Suno.com（通过 Google 账号）。请提供：\n\nGmail 邮箱地址\nGmail 密码\n\n⚠️ 你的凭据仅用于本次登录，不会被存储或传输到任何第三方。\n\n用户提供邮箱和密码后：\n\ncd {baseDir}/suno-headless\npython3 suno_login.py --email \"<用户邮箱>\" --password \"<用户密码>\"\n\n\nHeadless Linux 模式说明：\n\n脚本会自动检测无 GUI 环境（无 $DISPLAY 变量）\n自动启动 Xvfb 虚拟显示，在内存中模拟一个假显示器\nChrome 以 GUI 模式运行（headless=False），但屏幕上不显示任何东西\n这样可以绕过 Google 对 headless 浏览器的检测拦截\n2.3 检查登录状态\ncd {baseDir}/suno-headless\npython3 suno_login.py --check-only\n\n\n退出码 0 = 已登录，2 = 未登录。\n\n2.4 强制重新登录\n# 方式 A: 重新导入 Cookie\ncd {baseDir}/suno-headless\npython3 suno_login.py --import-cookies \"<新的Cookie文件>\"\n\n# 方式 B: 邮箱密码重新登录\ncd {baseDir}/suno-headless\npython3 suno_login.py --email \"<邮箱>\" --password \"<密码>\" --force-login\n\n三、创建歌曲\n3.1 前置条件\n已完成登录（suno_login.py --check-only 返回 0）\n需要 Gemini API Key（用于自动解决 hCaptcha 验证码）\n3.2 获取 Gemini API Key\n\n如果用户没有 Gemini API Key，引导用户获取：\n\n创建歌曲时 Suno 会弹出验证码，需要 Gemini API Key 来自动解决。\n\n访问 https://aistudio.google.com/app/apikey\n点击 \"Create API key\"\n复制生成的 Key\n\n获取后保存到环境文件：\n\nmkdir -p ~/.suno\necho \"GEMINI_API_KEY=<用户的key>\" > ~/.suno/.env\n\n\n或通过环境变量：\n\nexport GEMINI_API_KEY=\"<用户的key>\"\n\n3.3 hCaptcha 兼容补丁\n\n首次使用前需运行一次（Suno 使用自定义 hCaptcha 域名，需打补丁）：\n\ncd {baseDir}/suno-headless\npython3 patch_hcaptcha.py\n\n3.4 创建歌曲命令\ncd {baseDir}/suno-headless\npython3 suno_create_song.py \\\n --lyrics \"<歌词内容>\" \\\n --style \"<音乐风格标签>\" \\\n --title \"<歌曲标题>\" \\\n --output-dir \"<下载目录>\"\n\n\n也可以从文件读取歌词：\n\ncd {baseDir}/suno-headless\npython3 suno_create_song.py \\\n --lyrics-file \"<歌词文件路径>\" \\\n --style \"<音乐风格标签>\" \\\n --title \"<歌曲标题>\"\n\n\nHeadless 模式说明：\n\nsuno_create_song.py 会自动检测无 GUI 环境\n自动启动 Xvfb 虚拟显示，Chrome 以 GUI 模式在虚拟显示中运行\n脚本结束后自动关闭虚拟显示，无需手动操作\n3.5 参数说明\n参数\t说明\t必填\t默认值\n--lyrics\t歌词内容（与 --lyrics-file 二选一）\t✅\t-\n--lyrics-file\t歌词文件路径（与 --lyrics 二选一）\t✅\t-\n--style\t音乐风格标签（英文，逗号分隔）\t❌\trock, electric guitar, energetic, male vocals\n--title\t歌曲标题\t❌\tMy Song\n--output-dir\tMP3 下载目录\t❌\t{baseDir}/output_mp3\n--gemini-key\tGemini API Key（也可通过环境变量或 ~/.suno/.env）\t❌\t自动读取\n--verbose / -v\t详细输出模式（实时打印所有中间步骤）\t❌\t关闭（默认只输出最终摘要）\n\n📋 输出行为说明：默认情况下，所有脚本（suno_create_song.py、suno_login.py、export_cookies.py）只在完成时输出一条简洁的摘要，中间步骤的详细日志写入 {baseDir}/suno-headless/logs/ 目录。如需实时查看所有中间步骤，请添加 --verbose 或 -v 参数。\n\n3.6 音乐风格标签参考\n\n常用风格标签（英文，可自由组合）：\n\n流派: rock, pop, jazz, blues, electronic, hip-hop, R&B, classical, folk, metal, country, reggae, latin, indie\n乐器: electric guitar, acoustic guitar, piano, synthesizer, drums, bass, violin, saxophone, trumpet\n情绪: energetic, emotional, melancholic, upbeat, dark, dreamy, aggressive, peaceful, romantic\n人声: male vocals, female vocals, choir, rap, whisper, powerful vocals, falsetto\n语言: chinese, japanese, korean, english, spanish\n其他: fast tempo, slow tempo, instrumental, lo-fi, cinematic, epic\n\n示例：\n\n摇滚: rock, electric guitar, energetic, male vocals, chinese\n抒情: pop, piano, emotional, female vocals, slow tempo, chinese\n电子: electronic, synthesizer, upbeat, fast tempo, dance\n说唱: hip-hop, rap, bass, drums, energetic, chinese\n四、完整使用示例\n示例：在 Linux 云服务器上创建中文摇滚歌曲\n# 1. 检查环境（会自动检测 Xvfb、Chrome 等）\nbash {baseDir}/suno-headless/check_env.sh\n\n# 2. 如果未登录，使用 Cookie 导入方式登录（推荐）\n# 步骤 1: 在本地电脑运行 export_cookies.py 导出 Cookie\n# 步骤 2: scp user@server:/root/suno_cookie/suno_cookies.json\n# 步骤 3: 服务器上运行登录脚本（自动检测默认路径并导入）\ncd {baseDir}/suno-headless\npython3 suno_login.py\n\n# 或者使用邮箱密码方式（可能触发 Google 安全验证）\n# python3 suno_login.py --email \"user@gmail.com\" --password \"password123\"\n\n# 3. 确保 hCaptcha 补丁已应用\npython3 patch_hcaptcha.py\n\n# 4. 创建歌曲（自动使用 Xvfb 虚拟显示）\npython3 suno_create_song.py \\\n --lyrics \"窗外的麻雀 在电线杆上多嘴\n你说这一句 很有夏天的感觉\n手中的铅笔 在纸上来来回回\n我用几行字形容你是我的谁\" \\\n --style \"rock, electric guitar, energetic, male vocals, chinese\" \\\n --title \"七里香摇滚版\"\n\n五、与原版 suno skill 的区别\n特性\tsuno（原版）\tsuno-headless（本版）\n目标环境\tmacOS / 有 GUI 的 Linux\t无 GUI 的 Linux 云服务器\n显示方式\t弹出真实 Chrome 窗口\tXvfb 虚拟显示（内存模拟）\n额外依赖\t无\txvfb + PyVirtualDisplay\n登录 Xvfb\t✅ 已支持\t✅ 已支持\n创建歌曲 Xvfb\t❌ 不支持\t✅ 已支持\n环境检查\t基础检查\t增加 Xvfb/Chrome/字体检查\n六、技术原理\nXvfb 虚拟显示方案\n┌─────────────────────────────────────────┐\n│ Linux 云服务器（无显示器） │\n│ │\n│ ┌─────────────┐ ┌────────────────┐ │\n│ │ Xvfb │ │ Chrome │ │\n│ │ (虚拟显示器) │◄───│ (GUI 模式) │ │\n│ │ :99 1280x800│ │ headless=False │ │\n│ └─────────────┘ └────────────────┘ │\n│ ▲ │ │\n│ │ 自动操作 Suno.com │\n│ PyVirtualDisplay │ │\n│ 自动管理生命周期 ▼ │\n│ ┌────────────────┐ │\n│ │ 歌曲生成+下载 │ │\n│ └────────────────┘ │\n└─────────────────────────────────────────┘\n\n为什么不用 headless=True？ Google OAuth 会检测到 headless 浏览器并拒绝登录\nXvfb 方案：在内存中创建虚拟 X11 显示，Chrome 以为自己有真实 GUI，Google 无法检测到自动化\n自动检测：脚本检查 $DISPLAY 环境变量，无 GUI 时自动启用 Xvfb\n资源占用：Xvfb 仅占用极少内存，脚本结束后自动释放\n登录方案\n使用 Playwright + 真实 Chrome 浏览器 (channel='chrome')\npersistent context 保持浏览器状态（cookies、localStorage）\nheadless=False + Xvfb 虚拟显示绕过 Google 反自动化\n首次登录后 persistent context 自动保持会话\n歌曲创建方案\n浏览器自动化操作 suno.com/create 页面\nhcaptcha-challenger + Gemini API 自动解决 hCaptcha 验证码\n通过拦截浏览器网络响应捕获新生成的 clip ID\n通过 Suno 内部 API (studio-api.prod.suno.com) 轮询歌曲生成状态\n生成完成后自动下载 MP3 文件\n文件结构\nsuno-headless/\n├── suno_login.py # 登录工具（Google OAuth / Cookie 导入 + Xvfb）\n├── suno_create_song.py # 歌曲创建+下载工具（Xvfb 支持）\n├── export_cookies.py # Cookie 导出工具（在本地电脑上运行）\n├── output_manager.py # 输出管理器（控制日志和摘要）\n├── patch_hcaptcha.py # hCaptcha 域名兼容补丁\n├── check_env.sh # 环境检查脚本（含 Xvfb/Chrome 检查）\n├── requirements.txt # Python 依赖（含 PyVirtualDisplay）\n└── SKILL.md # 本文档\n\n七、注意事项\n不要硬编码账号密码 — 每次都需要询问用户（推荐优先使用 Cookie 导入方式）\n必须安装 Xvfb — sudo apt install -y xvfb，否则无法在无 GUI 环境运行\n必须安装真实 Chrome — Playwright 自带的 Chromium 可能被 Google 检测\nSuno 免费账号每天有积分限制，每首歌消耗约 100 积分\n歌曲生成通常需要 1-3 分钟\n每次创建会生成 2 首不同版本的歌曲\n如果遇到 Google 登录被拒（rejected），等待 10-30 分钟后重试\nGemini API 免费额度：每分钟 15 次请求，每天 1500 次\nhCaptcha 可能需要多次尝试，成功率取决于 Gemini 模型的图片识别能力\n八、故障排查\n# 检查环境（含 Xvfb 状态）\nbash {baseDir}/suno-headless/check_env.sh\n\n# 手动测试 Xvfb 是否正常\nXvfb :99 -screen 0 1280x800x24 &\nDISPLAY=:99 google-chrome --no-sandbox --version\nkill %1\n\n# 查看登录截图\nls -la /tmp/suno_debug_*.png\n\n# 检查 persistent context\nls -la ~/.suno/chrome_gui_profile/\n\n# 查看 cookies\npython3 -c \"import json; d=json.load(open('$HOME/.suno/cookies.json')); print(f'{len(d)} cookies')\"\n\n# 查看 Gemini API Key\ncat ~/.suno/.env\n\n# 查看下载的歌曲\nls -la {baseDir}/output_mp3/" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/RevolGMPHL/suno-headless-skill", "publisherUrl": "https://clawhub.ai/RevolGMPHL/suno-headless-skill", "owner": "RevolGMPHL", "version": "1.0.6", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/suno-headless-skill", "downloadUrl": "https://openagent3.xyz/downloads/suno-headless-skill", "agentUrl": "https://openagent3.xyz/skills/suno-headless-skill/agent", "manifestUrl": "https://openagent3.xyz/skills/suno-headless-skill/agent.json", "briefUrl": "https://openagent3.xyz/skills/suno-headless-skill/agent.md" } }