什么是 Suno Headless 音乐创作工具？

Suno Headless 技能是为需要在服务器环境中直接生成高质量 AI 音乐的开发者和创作者提供的强大解决方案。与经常被 Google 和 Suno 机器人检测拦截的标准自动化工具不同，该技能利用 Xvfb（X 虚拟帧缓冲）在内存中运行完整的 Google Chrome 实例。这使其能够在无头系统上模拟真实的用户界面，在 Openclaw Skills 与 Suno 的创意引擎之间提供无缝衔接。

通过将此技能集成到工作流中，您可以自动化音乐制作的整个生命周期——从通过 Google OAuth 或 Cookie 注入进行身份验证，到歌词提交和 MP3 交付。它专为 Ubuntu 等 Linux 发行版优化，确保基于云的 AI 代理无需物理显示器或桌面环境即可执行音频任务。

下载入口:https://github.com/openclaw/skills/tree/main/skills/revolgmphl/suno-headless-skill

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Suno Headless 音乐创作工具 应用场景

• 在远程 VPS 或云实例上部署自动化音乐生成机器人。
• 将专业的 AI 音频制作集成到服务器端开发人员工作流中。
• 绕过 Google OAuth 和 Suno 登录过程中的无头浏览器限制。
• 从文本文件或外部数据库批量处理歌曲创作。

1. 该技能执行环境检查，确保 Linux 系统上安装了 Xvfb、Google Chrome 和所需的字体。
2. 它通过安全 Cookie 导入或 Gmail 凭据启动会话，在虚拟化 GUI 模式下运行 Chrome 以避免检测。
3. 应用特定的 hCaptcha 补丁，并利用 Gemini API 在歌曲创作过程中自动解决视觉挑战。
4. 通过 Playwright 驱动的自动化层将歌词和音乐风格参数提交到 Suno 界面。
5. 系统通过内部 API 监控制作状态，并自动将完成的 MP3 文件下载到指定的输出目录。

Suno Headless 音乐创作工具 配置指南

首先，在您的 Linux 服务器上安装必要的系统依赖：

sudo apt update && sudo apt install -y xvfb google-chrome-stable fonts-noto-cjk

接下来，安装 Python 环境和浏览器二进制文件：

cd suno-headless
pip3 install -r requirements.txt
playwright install

最后，配置您的 Gemini API 密钥用于 hCaptcha 求解并验证安装：

echo "GEMINI_API_KEY=your_key_here" > ~/.suno/.env
bash suno-headless/check_env.sh

Suno Headless 音乐创作工具 数据架构与分类体系

该技能使用以下结构组织其配置和输出：

name: suno-headless
description: Suno AI 音乐创作助手（无头 Linux 服务器专用版）— 自动登录、创建歌曲、下载音频。通过 Xvfb 虚拟显示在无 GUI 的 Linux 云服务器上运行。当用户要求生成音乐、写歌、创作歌曲、用 Suno 生成 AI 音乐时使用。
metadata: {"openclaw": {"emoji": "??", "requires": {"bins": ["google-chrome", "Xvfb"]}}}

?? 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 账号）。请提供：

1. Gmail 邮箱地址
2. 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 前置条件

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

3.2 获取 Gemini API Key

如果用户没有 Gemini API Key，引导用户获取：

创建歌曲时 Suno 会弹出验证码，需要 Gemini API Key 来自动解决。

1. 访问 https://aistudio.google.com/app/apikey
2. 点击 "Create API key"
3. 复制生成的 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 r
  --lyrics "<歌词内容>" r
  --style "<音乐风格标签>" r
  --title "<歌曲标题>" r
  --output-dir "<下载目录>"

也可以从文件读取歌词：

cd {baseDir}/suno-headless
python3 suno_create_song.py r
  --lyrics-file "<歌词文件路径>" r
  --style "<音乐风格标签>" r
  --title "<歌曲标题>"

Headless 模式说明：

• suno_create_song.py 会自动检测无 GUI 环境
• 自动启动 Xvfb 虚拟显示，Chrome 以 GUI 模式在虚拟显示中运行
• 脚本结束后自动关闭虚拟显示，无需手动操作

3.5 参数说明

?? 输出行为说明：默认情况下，所有脚本（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  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 r
  --lyrics "窗外的麻雀 在电线杆上多嘴
你说这一句 很有夏天的感觉
手中的铅笔 在纸上来来回回
我用几行字形容你是我的谁" r
  --style "rock, electric guitar, energetic, male vocals, chinese" r
  --title "七里香摇滚版"

五、与原版 suno skill 的区别

六、技术原理

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               # 本文档

七、注意事项

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