Tencent SkillHub · AI

revol-suno-headless-skill

Suno AI 音乐创作助手（无头 Linux 服务器专用版）— 自动登录、创建歌曲、下载音频。通过 Xvfb 虚拟显示在无 GUI 的 Linux 云服务器上运行。当用户要求生成音乐、写歌、创作歌曲、用 Suno 生成 AI 音乐时使用。

skill openclawclawhub Free

0 Downloads

0 Stars

0 Installs

0 Score

High Signal

⬇ 0 downloads ★ 0 stars Unverified but indexed

Install for OpenClaw

Known item issue.

This item's current download entry is known to bounce back to a listing or homepage instead of returning a package file.

Quick setup

Open the source page and confirm the package flow manually.
Review SKILL.md if you can obtain the files.
Treat this source as manual setup until the download is verified.

Requirements

Target platform: OpenClaw
Install method: Manual import
Extraction: Extract archive
Prerequisites: OpenClaw
Primary doc: SKILL.md

Package facts

Download mode: Manual review
Package format: ZIP package
Source platform: Tencent SkillHub
What's included: output_manager.py, suno_create_song.py, requirements.txt, patch_hcaptcha.py, suno_login.py, check_env.sh

Validation

Open the source listing and confirm there is a real package or setup artifact available.
Review SKILL.md before asking your agent to continue.
Treat this source as manual setup until the upstream download flow is fixed.

Install with your agent

Agent handoff

Use the source page and any available docs to guide the install because the item currently does not return a direct package file.

Open the source page via Open source listing.
If you can obtain the package, extract it into a folder your agent can access.
Paste one of the prompts below and point your agent at the source page and extracted files.

New install

I tried to install a skill package from Yavira, but the item currently does not return a direct package file. Inspect the source page and any extracted docs, then tell me what you can confirm and any manual steps still required.

Upgrade existing

I tried to upgrade a skill package from Yavira, but the item currently does not return a direct package file. Compare the source page and any extracted docs with my current installation, then summarize what changed and what manual follow-up I still need.

Open Send to Agent page Open JSON manifest Open Markdown brief

Trust & source

Release facts

Source: Tencent SkillHub
Verification: Indexed source record
Version: 1.0.6

Provenance

Publisher: RevolGMPHL
Source page: View original listing
Canonical URL: Open canonical page

Documentation

ClawHub primary doc Primary doc: SKILL.md 23 sections Open source page

🎵 Suno AI 音乐创作助手（Headless Linux 专用版）

专为无图形界面的 Linux 云服务器设计，通过 Xvfb 虚拟显示在没有显示器的环境下运行 Chrome GUI 模式，绕过 Google 反自动化检测。两大核心能力：账号登录（通过 Google OAuth）和歌曲创作（自定义歌词+风格+下载）。

零、前置检查

每次操作前必须先执行环境检查： bash {baseDir}/suno-headless/check_env.sh 返回码：0 = 正常已登录 → 可直接创建歌曲；1 = 缺少依赖 → 安装依赖；2 = 未登录 → 登录流程。

1.1 系统依赖

# Xvfb 虚拟显示（核心依赖，无 GUI 环境必装） sudo apt update && sudo apt install -y xvfb # Google Chrome 浏览器 wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add - echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list sudo apt update && sudo apt install -y google-chrome-stable # 中文字体支持（歌词含中文时需要） sudo apt install -y fonts-noto-cjk

1.2 Python 依赖

cd {baseDir}/suno-headless pip3 install -r requirements.txt playwright install

二、登录流程

⚠️ 重要：不要在 skill 代码中硬编码账号密码！必须先询问用户的凭据。提供两种登录方式：方式 A: Cookie 导入（🌟 推荐！完美绕过 Google 安全验证）方式 B: 邮箱密码直接登录（可能触发 Google 安全验证）

2.1 方式 A: Cookie 导入（推荐）

这是云服务器上最稳定的登录方式，完全绕过 Google 的安全验证。操作步骤：当需要登录时，向用户说明： 🍪 推荐使用 Cookie 导入方式登录（绕过 Google 安全验证）：步骤 1: 在你的本地电脑（有浏览器的）上运行： pip install playwright && playwright install python3 export_cookies.py 这会打开浏览器，你手动登录 Suno，登录成功后自动导出 Cookie 文件。步骤 2: 把导出的 Cookie 文件上传到服务器固定路径： scp <本地导出的Cookie文件> user@your-server:/root/suno_cookie/suno_cookies.json 步骤 3: 上传完成后告诉我，我来导入。用户上传文件后，执行导入。脚本会自动检测 /root/suno_cookie/suno_cookies.json 是否存在，存在则自动导入，无需额外指定参数： cd {baseDir}/suno-headless python3 suno_login.py 也可以显式指定 Cookie 文件路径： python3 suno_login.py --import-cookies /path/to/cookies.json

2.2 方式 B: 邮箱密码登录

⚠️ 注意：云服务器上可能触发 Google 安全验证，推荐优先使用方式 A。当需要登录时，必须先向用户询问：需要登录 Suno.com（通过 Google 账号）。请提供： Gmail 邮箱地址 Gmail 密码 ⚠️ 你的凭据仅用于本次登录，不会被存储或传输到任何第三方。用户提供邮箱和密码后： cd {baseDir}/suno-headless python3 suno_login.py --email "<用户邮箱>" --password "<用户密码>" Headless Linux 模式说明：脚本会自动检测无 GUI 环境（无 $DISPLAY 变量）自动启动 Xvfb 虚拟显示，在内存中模拟一个假显示器 Chrome 以 GUI 模式运行（headless=False），但屏幕上不显示任何东西这样可以绕过 Google 对 headless 浏览器的检测拦截

2.3 检查登录状态

cd {baseDir}/suno-headless python3 suno_login.py --check-only 退出码 0 = 已登录，2 = 未登录。

2.4 强制重新登录

# 方式 A: 重新导入 Cookie cd {baseDir}/suno-headless python3 suno_login.py --import-cookies "<新的Cookie文件>" # 方式 B: 邮箱密码重新登录 cd {baseDir}/suno-headless python3 suno_login.py --email "<邮箱>" --password "<密码>" --force-login

3.1 前置条件

已完成登录（suno_login.py --check-only 返回 0）需要 Gemini API Key（用于自动解决 hCaptcha 验证码）

3.2 获取 Gemini API Key

如果用户没有 Gemini API Key，引导用户获取：创建歌曲时 Suno 会弹出验证码，需要 Gemini API Key 来自动解决。访问 https://aistudio.google.com/app/apikey 点击 "Create API key" 复制生成的 Key 获取后保存到环境文件： mkdir -p ~/.suno echo "GEMINI_API_KEY=<用户的key>" > ~/.suno/.env 或通过环境变量： export GEMINI_API_KEY="<用户的key>"

3.3 hCaptcha 兼容补丁

首次使用前需运行一次（Suno 使用自定义 hCaptcha 域名，需打补丁）： cd {baseDir}/suno-headless python3 patch_hcaptcha.py

3.4 创建歌曲命令

cd {baseDir}/suno-headless python3 suno_create_song.py \ --lyrics "<歌词内容>" \ --style "<音乐风格标签>" \ --title "<歌曲标题>" \ --output-dir "<下载目录>" 也可以从文件读取歌词： cd {baseDir}/suno-headless python3 suno_create_song.py \ --lyrics-file "<歌词文件路径>" \ --style "<音乐风格标签>" \ --title "<歌曲标题>" Headless 模式说明： suno_create_song.py 会自动检测无 GUI 环境自动启动 Xvfb 虚拟显示，Chrome 以 GUI 模式在虚拟显示中运行脚本结束后自动关闭虚拟显示，无需手动操作

3.5 参数说明

参数说明必填默认值--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详细输出模式（实时打印所有中间步骤）❌关闭（默认只输出最终摘要） 📋 输出行为说明：默认情况下，所有脚本（suno_create_song.py、suno_login.py、export_cookies.py）只在完成时输出一条简洁的摘要，中间步骤的详细日志写入 {baseDir}/suno-headless/logs/ 目录。如需实时查看所有中间步骤，请添加 --verbose 或 -v 参数。

3.6 音乐风格标签参考

常用风格标签（英文，可自由组合）：流派: rock, pop, jazz, blues, electronic, hip-hop, R&B, classical, folk, metal, country, reggae, latin, indie 乐器: electric guitar, acoustic guitar, piano, synthesizer, drums, bass, violin, saxophone, trumpet 情绪: energetic, emotional, melancholic, upbeat, dark, dreamy, aggressive, peaceful, romantic 人声: male vocals, female vocals, choir, rap, whisper, powerful vocals, falsetto 语言: chinese, japanese, korean, english, spanish 其他: fast tempo, slow tempo, instrumental, lo-fi, cinematic, epic 示例：摇滚: rock, electric guitar, energetic, male vocals, chinese 抒情: pop, piano, emotional, female vocals, slow tempo, chinese 电子: electronic, synthesizer, upbeat, fast tempo, dance 说唱: hip-hop, rap, bass, drums, energetic, chinese

示例：在 Linux 云服务器上创建中文摇滚歌曲

# 1. 检查环境（会自动检测 Xvfb、Chrome 等） bash {baseDir}/suno-headless/check_env.sh # 2. 如果未登录，使用 Cookie 导入方式登录（推荐） # 步骤 1: 在本地电脑运行 export_cookies.py 导出 Cookie # 步骤 2: scp <Cookie文件> user@server:/root/suno_cookie/suno_cookies.json # 步骤 3: 服务器上运行登录脚本（自动检测默认路径并导入） cd {baseDir}/suno-headless python3 suno_login.py # 或者使用邮箱密码方式（可能触发 Google 安全验证） # python3 suno_login.py --email "user@gmail.com" --password "password123" # 3. 确保 hCaptcha 补丁已应用 python3 patch_hcaptcha.py # 4. 创建歌曲（自动使用 Xvfb 虚拟显示） python3 suno_create_song.py \ --lyrics "窗外的麻雀在电线杆上多嘴你说这一句很有夏天的感觉手中的铅笔在纸上来来回回我用几行字形容你是我的谁" \ --style "rock, electric guitar, energetic, male vocals, chinese" \ --title "七里香摇滚版"

五、与原版 suno skill 的区别

特性suno（原版）suno-headless（本版）目标环境macOS / 有 GUI 的 Linux无 GUI 的 Linux 云服务器显示方式弹出真实 Chrome 窗口Xvfb 虚拟显示（内存模拟）额外依赖无xvfb + PyVirtualDisplay登录 Xvfb✅ 已支持✅ 已支持创建歌曲 Xvfb❌ 不支持✅ 已支持环境检查基础检查增加 Xvfb/Chrome/字体检查

Xvfb 虚拟显示方案

┌─────────────────────────────────────────┐ │ Linux 云服务器（无显示器） │ │ │ │ ┌─────────────┐ ┌────────────────┐ │ │ │ Xvfb │ │ Chrome │ │ │ │ (虚拟显示器) │◄───│ (GUI 模式) │ │ │ │ :99 1280x800│ │ headless=False │ │ │ └─────────────┘ └────────────────┘ │ │ ▲ │ │ │ │ 自动操作 Suno.com │ │ PyVirtualDisplay │ │ │ 自动管理生命周期 ▼ │ │ ┌────────────────┐ │ │ │ 歌曲生成+下载 │ │ │ └────────────────┘ │ └─────────────────────────────────────────┘ 为什么不用 headless=True？ Google OAuth 会检测到 headless 浏览器并拒绝登录 Xvfb 方案：在内存中创建虚拟 X11 显示，Chrome 以为自己有真实 GUI，Google 无法检测到自动化自动检测：脚本检查 $DISPLAY 环境变量，无 GUI 时自动启用 Xvfb 资源占用：Xvfb 仅占用极少内存，脚本结束后自动释放

登录方案

使用 Playwright + 真实 Chrome 浏览器 (channel='chrome') persistent context 保持浏览器状态（cookies、localStorage） headless=False + Xvfb 虚拟显示绕过 Google 反自动化首次登录后 persistent context 自动保持会话

歌曲创建方案

浏览器自动化操作 suno.com/create 页面 hcaptcha-challenger + Gemini API 自动解决 hCaptcha 验证码通过拦截浏览器网络响应捕获新生成的 clip ID 通过 Suno 内部 API (studio-api.prod.suno.com) 轮询歌曲生成状态生成完成后自动下载 MP3 文件

文件结构

suno-headless/ ├── suno_login.py # 登录工具（Google OAuth / Cookie 导入 + Xvfb） ├── suno_create_song.py # 歌曲创建+下载工具（Xvfb 支持） ├── export_cookies.py # Cookie 导出工具（在本地电脑上运行） ├── output_manager.py # 输出管理器（控制日志和摘要） ├── patch_hcaptcha.py # hCaptcha 域名兼容补丁 ├── check_env.sh # 环境检查脚本（含 Xvfb/Chrome 检查） ├── requirements.txt # Python 依赖（含 PyVirtualDisplay） └── SKILL.md # 本文档

七、注意事项

不要硬编码账号密码 — 每次都需要询问用户（推荐优先使用 Cookie 导入方式）必须安装 Xvfb — sudo apt install -y xvfb，否则无法在无 GUI 环境运行必须安装真实 Chrome — Playwright 自带的 Chromium 可能被 Google 检测 Suno 免费账号每天有积分限制，每首歌消耗约 100 积分歌曲生成通常需要 1-3 分钟每次创建会生成 2 首不同版本的歌曲如果遇到 Google 登录被拒（rejected），等待 10-30 分钟后重试 Gemini API 免费额度：每分钟 15 次请求，每天 1500 次 hCaptcha 可能需要多次尝试，成功率取决于 Gemini 模型的图片识别能力

八、故障排查

# 检查环境（含 Xvfb 状态） bash {baseDir}/suno-headless/check_env.sh # 手动测试 Xvfb 是否正常 Xvfb :99 -screen 0 1280x800x24 & DISPLAY=:99 google-chrome --no-sandbox --version kill %1 # 查看登录截图 ls -la /tmp/suno_debug_*.png # 检查 persistent context ls -la ~/.suno/chrome_gui_profile/ # 查看 cookies python3 -c "import json; d=json.load(open('$HOME/.suno/cookies.json')); print(f'{len(d)} cookies')" # 查看 Gemini API Key cat ~/.suno/.env # 查看下载的歌曲 ls -la {baseDir}/output_mp3/

Category context

Agent frameworks, memory systems, reasoning layers, and model-native orchestration.

Source: Tencent SkillHub

Largest current source with strong distribution and engagement signals.

Package contents

Included in package

5 Scripts1 Files

check_env.sh Scripts
output_manager.py Scripts
patch_hcaptcha.py Scripts
suno_create_song.py Scripts
suno_login.py Scripts
requirements.txt Files