1. 项目概述一个为AI助手赋能的媒体栈统一控制台如果你和我一样家里跑着一整套自托管的媒体服务器那你肯定对“*arr”系列软件Sonarr, Radarr, Prowlarr等和Plex、Tautulli这些工具不陌生。这套组合拳确实强大但管理起来也够呛十几个服务每个都有自己的Web界面和API想查个下载状态、看看库统计或者同步个观看记录得在好几个标签页之间来回切换。更别提那些自动化任务比如用Recyclarr同步质量配置、用Kometa更新Plex海报墙虽然设好了定时任务但真想看看它干了啥、或者临时手动触发一下又得去翻日志或者敲命令行。ClawARR Suite就是为了解决这个痛点而生的。它本质上不是一个独立的新软件而是一个为OpenClaw这个AI助手平台开发的“技能包”。你可以把它理解为一套超级齐全的、针对媒体服务器的“命令行工具集”只不过这个命令行是自然语言。通过它你可以直接对你的AI助手说“帮我看看现在正在下载什么”、“生成一份上个月的观影报告”、“把Plex里标记为已看的电影同步到Trakt.tv”然后助手就能调用背后对应的脚本去执行并把结果用你能看懂的话反馈回来。这个技能包包含了24个Bash脚本总计超过8500行代码封装了180多个子命令覆盖了从内容发现、下载管理、字幕搜索、库清洗到数据分析、外部同步的几乎全链路操作。它的核心价值在于“统一”和“深度集成”——用一个统一的对话入口打通了所有分散的服务让你能用最自然的方式管理整个媒体生态。2. 核心设计思路为何选择Bash脚本与AI代理的结合看到8500多行的Bash脚本可能有人会问为什么不用Python、Go这些更“现代”的语言为什么要把控制权交给一个AI代理这背后其实是一套非常务实的设计哲学。2.1 技术栈选型Bash的独特优势首先Bash是这个场景下的“最优解”而非“将就”。媒体服务器管理脚本的核心任务是什么是调用各种服务的REST API处理返回的JSON数据然后进行逻辑判断和输出。这正是curl和jq这两个工具的主场而它们几乎就是为Bash环境而生的。极致的轻量与零依赖目标环境是用户的NAS如群晖、Linux服务器或Docker主机。这些环境100%预装了Bash、curl和jq。用Bash意味着用户无需安装任何额外的运行时如Python解释器、Node.js环境及其庞大的依赖包实现了真正的开箱即用降低了部署门槛和潜在的环境冲突。与系统原生集成很多自动化操作需要与系统层交互比如通过SSH在Docker主机上执行命令管理Recyclarr、Kometa、读取环境变量、处理进程。Bash在这方面具有天然优势脚本可以无缝嵌入现有的运维体系。可预测性与稳定性Bash语法虽然古老但也意味着极其稳定。一个写好的Bash脚本其行为在十年内不同的Linux发行版上基本一致。这对于追求“一次设置永久运行”的家庭服务器来说至关重要。当然编写大型Bash脚本有其挑战比如错误处理、代码组织。ClawARR Suite通过模块化设计每个功能一个脚本、严格的输入验证、以及大量的注释和文档来应对这些挑战确保了可维护性。2.2 AI代理作为交互层从命令行到自然语言传统的脚本需要你记住命令和参数。而ClawARR Suite通过OpenClaw技能的形式引入了一个智能的“翻译层”。降低使用门槛你不需要记住./library.sh --service sonarr --action missing --days 30这样的命令。你只需要对助手说“我这个月有哪些想看的剧还没下载” AI代理会理解你的意图将其映射到正确的脚本和参数上并执行。处理复杂工作流有些操作涉及多个步骤。例如“把我在Trakt上标记为‘想看’的电影都加到Radarr里监视”。这涉及到先调用Trakt API获取列表再解析列表最后循环调用Radarr API添加电影。这个工作流被封装在trakt.sh脚本的sync-watchlist子命令中。用户只需说一句话AI代理就会触发这个复杂工作流。动态信息查询与决策支持AI代理可以结合上下文。比如你问“《沙丘2》下载好了吗” 助手可以先调用downloads.sh检查SABnzbd队列如果不在队列中再调用library.sh查询Radarr中这部电影的状态最后给你一个综合的回答“《沙丘2》已在Radarr中监控目前正在搜索发布尚未进入下载队列。”这种设计将底层脚本的强大能力与顶层的自然语言交互结合起来既保留了脚本的灵活和高效又提供了前所未有的易用性。2.3 架构解读松耦合与高内聚整个套件的架构清晰体现了“Unix哲学”每个工具只做好一件事并通过清晰的接口组合起来。按服务/功能分治24个脚本各司其职。analytics.sh只处理Plex/Tautulli的分析数据downloads.sh只与SABnzbd交互recyclarr.sh只负责同步质量配置。这种分治使得每个脚本逻辑单纯易于调试和维护。统一的配置与认证层所有脚本都通过环境变量如SONARR_KEY,PLEX_TOKEN读取配置。setup.sh脚本的核心工作就是帮助用户自动发现服务并生成这份统一的配置。这意味着认证信息只需管理一份。数据格式标准化所有脚本的输出都经过jq精心格式化力求清晰、可读并且为JSON格式便于AI代理解析和重组最终以更友好的方式呈现给用户。参考文档作为知识库8份参考文档references/并非摆设。它们详细记录了每个服务的API端点、常见问题解决方案、第三方服务如Trakt的API申请指南。这不仅是给用户看的更是给AI代理的“知识库”帮助它更好地理解每个功能背后的原理和边界条件。3. 环境部署与初始配置实战理论说得再多不如动手搭一遍。下面我将以最常见的Docker Compose环境为例带你一步步配置ClawARR Suite。假设你的媒体服务都运行在一台IP为192.168.1.100的服务器上。3.1 前置条件检查在安装技能包之前确保你的环境已经就绪已部署并运行的媒体服务栈你需要至少安装了Sonarr、Radarr、Plex和SABnzbd并且知道如何获取它们的API密钥。通常可以在各服务的设置 - 通用中找到。安装并配置好OpenClaw AI助手这是技能运行的基础平台。请确保你的OpenClaw实例已能正常响应。技能运行主机的环境这台主机可以是你的日常电脑macOS/Linux也可以是你的媒体服务器本身。它需要能通过网络访问到所有媒体服务并且安装有bash,curl,jq,bc,sed。在macOS和主流Linux发行版上这些通常都是预装的。3.2 技能安装的三种方式由于项目提到ClawHubOpenClaw的技能商店上的版本因安全扫描误报而被标记我们优先考虑从GitHub直接安装这是最可靠的方式。方式一通过GitHub克隆推荐在你的OpenClaw技能目录下执行# 假设你的OpenClaw技能目录在默认位置 git clone https://github.com/omiron33/clawarr-suite.git ~/.openclaw/skills/clawarr-suite执行后技能包的所有文件就会被放置到正确的位置。方式二手动放置如果你无法使用git可以直接从GitHub仓库下载ZIP包并解压然后将整个clawarr-suite文件夹复制到~/.openclaw/skills/目录下。注意技能目录的名称必须保持为clawarr-suite因为OpenClaw会通过目录名来识别和加载技能。3.3 核心配置使用setup.sh进行自动发现配置是最大的门槛而setup.sh脚本正是为此而生。它尝试自动发现你局域网内的服务并获取配置。进入技能目录cd ~/.openclaw/skills/clawarr-suite运行自动设置脚本# 将 192.168.1.100 替换为你媒体服务器的真实IP ./scripts/setup.sh 192.168.1.100这个脚本会做以下几件大事端口扫描对你指定的IP地址的常用端口如7878, 8989, 32400等进行扫描识别运行了哪些服务。API密钥提取尝试对于某些已知其配置文件路径的服务尤其是Docker部署的脚本会尝试通过模拟的HTTP请求或直接读取容器内的配置文件如果主机有相应权限来获取API密钥。请注意这种方式可能因权限和路径问题失败。生成配置报告脚本运行结束后会在终端输出一个总结报告列出它发现了哪些服务、是否成功获取了API密钥并为每个服务生成一条export环境变量命令。手动查漏补缺自动发现不可能100%成功尤其是API密钥。你需要仔细查看脚本的输出。对于标记为“未找到密钥”的服务你需要手动登录该服务的Web界面获取API密钥。Sonarr/Radarr设置 - 通用 - 安全 - API密钥。Plex需要获取Plex Token这相对复杂通常可以通过访问https://plex.tv/devices.xml并在认证后从页面源码中查找或使用第三方工具获取。SABnzbd设置 - 通用 - 安全 - API密钥。Tautulli设置 - 通用 - API密钥。创建持久化配置将所需的环境变量写入你的shell配置文件如~/.bashrc,~/.zshrc或OpenClaw的特定环境配置文件中确保每次启动时都能加载。# 编辑配置文件 nano ~/.bashrc # 在文件末尾添加以下内容根据你的实际情况修改 export CLAWARR_HOST192.168.1.100 export SONARR_KEY你的Sonarr_API密钥 export RADARR_KEY你的Radarr_API密钥 export PLEX_TOKEN你的Plex_Token export SABNZBD_KEY你的SABnzbd_API密钥 # ... 其他服务的密钥保存后执行source ~/.bashrc使配置立即生效。3.4 验证安装与配置配置完成后可以通过运行一个简单的脚本来测试连通性。# 测试Sonarr连接 ./scripts/library.sh --service sonarr --action health如果配置正确这个命令会返回Sonarr的健康状态信息。如果报错如连接拒绝、认证失败请根据错误信息检查CLAWARR_HOST和SONARR_KEY是否正确以及防火墙是否放行了对应端口。4. 核心功能模块深度解析与实操ClawARR Suite的功能模块覆盖了媒体管理的全生命周期。我们挑几个最常用、也最能体现其价值的模块来深入看看。4.1 库管理与内容分析library.sh, analytics.sh这是你与媒体库交互最频繁的部分。library.sh主要负责与Sonarr、Radarr、Lidarr、Readarr这些内容管理器的库交互而analytics.sh则专注于从Plex和Tautulli中挖掘观看数据。典型使用场景与命令映射你的自然语言问题AI代理可能调用的底层命令功能解释“我这个月添加了多少部电影”library.sh --service radarr --action added --days 30查询Radarr过去30天内添加的电影条目。“我的剧集库里有哪些是4K分辨率的”library.sh --service sonarr --action list --quality 4K过滤并列出Sonarr中所有质量属性为4K的剧集。“显示当前在Plex上播放的内容。”analytics.sh --service plex --action activity调用Plex API获取当前活动流。“谁是我家Plex上最活跃的用户”analytics.sh --service tautulli --action top-users --period month查询Tautulli获取本月播放时长最多的用户。实操示例生成库健康报告假设你想快速了解整个媒体库的概况可以组合使用这些脚本。虽然AI代理会帮你封装但了解底层命令有助于调试。# 1. 检查缺失的电影在Radarr中监控但未下载的 ./scripts/library.sh --service radarr --action missing # 2. 检查磁盘使用情况 ./scripts/library.sh --service radarr --action disk-usage # 3. 获取最近一周的观看统计 ./scripts/analytics.sh --service tautulli --action history --days 7这些命令的输出都是结构化的JSONAI代理可以将其整合成一段清晰的文字报告“你的电影库有5部缺失影片总计占用磁盘1.2TB过去一周共有42次播放记录。”4.2 下载队列与状态管理downloads.sh管理下载队列是日常运维的一部分。downloads.sh脚本封装了与SABnzbd或计划支持的其它下载器的所有交互。核心操作查看队列./scripts/downloads.sh --action queue。这是最常用的命令可以查看正在下载、排队、暂停的项目以及每个项目的进度、大小、预计完成时间。速度控制./scripts/downloads.sh --action pause和--action resume。在晚上网络高峰期你可以让AI助手暂停下载白天再恢复。历史记录./scripts/downloads.sh --action history --slots 20。查看最近20个已完成或失败的下载任务对于排查“为什么那部电影一直没下完”很有用。一个实用技巧脚本输出的队列信息里包含每个任务的唯一IDnzo_id。你可以利用这个ID进行精确操作比如删除一个卡住的任务./scripts/downloads.sh --action delete --id nzo_id。4.3 自动化质量与库维护recyclarr.sh, maintainerr.sh这是让媒体库保持“整洁”和“高质量”的自动化利器。Recyclarr自动同步TRaSH质量指南TRaSH Guides 是一个社区维护的、针对不同发布组的优质规则集。手动在Radarr/Sonarr里配置这些规则非常繁琐。Recyclarr能自动将这些指南同步到你的*arr实例中。ClawARR Suite中的recyclarr.sh脚本并不直接包含Recyclarr程序而是通过SSH连接到运行着Docker版Recyclarr的服务器来触发同步或查看差异。# 预览Radarr质量配置将会发生的变化干跑模式 ./scripts/recyclarr.sh --service radarr --action preview # 实际执行同步 ./scripts/recyclarr.sh --service radarr --action sync重要提示使用此功能前你必须在媒体服务器上正确安装并配置好Docker版的Recyclarr并在ClawARR Suite的环境变量中设置RECYCLARR_SSH指向该服务器。Maintainerr智能库清理Maintainerr可以根据你设定的规则如“上映超过5年且评分低于6.0的电影”、“剧集完结超过3年且无人观看”自动将内容移出库或删除文件。maintainerr.sh脚本同样通过SSH与Docker容器交互# 列出所有已配置的清理规则 ./scripts/maintainerr.sh --action list-rules # 手动触发一次规则扫描不实际执行删除 ./scripts/maintainerr.sh --action run --dry-run这个功能能有效防止你的媒体库被低质量或无人问津的内容无限膨胀是存储空间管理的好帮手。4.4 外部媒体追踪与同步trakt.sh, letterboxd.sh将你的观影数据从封闭的Plex同步到开放的社交平台是很多影迷的需求。Trakt.tv 深度集成trakt.sh脚本的功能非常全面授权你需要先在Trakt.tv官网创建API应用获取CLIENT_ID和CLIENT_SECRET并配置到环境变量中。脚本会引导你完成OAuth授权流程。同步Scrobbling进度同步近乎实时地将Plex的播放进度同步到Trakt。历史同步批量将Plex观看历史导入Trakt或反向操作。收藏/观看列表同步将Trakt的列表同步到Radarr/Sonarr进行自动下载依赖Traktarr或将你的媒体库导出为Trakt列表依赖Retraktarr。发现从Trakt的推荐、流行榜单中获取内容并一键添加到你的*arr库中。Letterboxd CSV导出对于喜欢在Letterboxd上记录和评价电影的用户letterboxd.sh脚本可以将你的Plex/Tautulli观看历史导出为Letterboxd官方支持的CSV格式方便你进行批量导入省去一部部手动标记的麻烦。5. 高级功能与自定义扩展除了开箱即用的功能ClawARR Suite还提供了一些高级玩法和扩展点。5.1 生成自定义仪表盘dashboard.sh这是项目中一个非常酷的功能。dashboard.sh脚本可以调用其他多个脚本收集库统计、下载状态、当前活动、系统资源等信息然后生成一个静态的HTML仪表盘文件。你可以把这个文件放在Web服务器上或者直接用浏览器打开就能得到一个可视化的媒体服务器状态总览。# 生成一个仪表盘 ./scripts/dashboard.sh --output ~/media-dashboard.html生成的HTML是自包含的使用了内联的CSS和JavaScript图表库如Chart.js无需网络依赖。你可以进一步修改references/dashboard-templates.md中的模板来定制仪表盘的外观和显示内容。5.2 通过SSH管理Docker化伴侣服务如前所述对于Recyclarr、Kometa、Unpackerr这些通常以Docker容器运行、没有直接HTTP API的服务套件通过SSH进行管理。这要求技能运行主机能够通过SSH密钥推荐或密码连接到媒体服务器。在环境变量中正确设置XXX_SSH如RECYCLARR_SSHmynas其中mynas是你的~/.ssh/config中定义的主机别名或者直接是用户名主机地址。确保SSH用户有权限执行docker命令通常需要加入docker用户组。这种设计非常灵活意味着你的AI助手和技能包可以运行在你的笔记本电脑上而媒体服务器在另一个房间的NAS里只要网络和SSH通畅就能实现远程管理。5.3 编写你自己的脚本与集成ClawARR Suite的脚本结构清晰可以作为你编写自定义集成任务的绝佳参考。每个脚本都遵循类似的模式解析命令行参数。加载环境变量和配置。根据参数调用对应的函数。函数内部使用curl调用API用jq处理JSON。格式化输出。例如如果你想添加对Jellyfin的支持完全可以参照analytics.sh写一个jellyfin.sh调用Jellyfin的API实现类似功能然后将其放入scripts/目录。只要你的脚本提供了清晰的帮助信息--helpOpenClaw的AI代理就有可能通过阅读脚本内容来学习如何使用它。6. 故障排除与经验分享即使准备得再充分在实际部署和运行中也可能遇到问题。这里分享一些常见坑点和解决思路。6.1 安装与配置常见问题问题1setup.sh自动发现失败找不到服务。原因服务运行在非标准端口或者主机防火墙/ Docker网络隔离导致端口扫描失败。解决不要完全依赖自动发现。手动确认每个服务的IP和端口然后直接编辑环境变量。setup.sh的主要价值在于生成配置模板而非100%的配置。问题2API密钥测试通过但某些操作如删除、修改返回403错误。原因某些服务如Plex的API令牌可能有细粒度的权限控制。你使用的令牌可能只有“读取”权限没有“写入”或“管理”权限。解决检查该服务中API令牌或账户的权限设置确保其具备执行相应操作所需的权限。问题3SSH连接到Docker主机执行命令失败提示“Permission denied”或“docker: command not found”。原因SSH用户权限不足。解决确保使用密钥认证并检查~/.ssh/config配置。登录到媒体服务器将用于SSH的用户加入docker组sudo usermod -aG docker 你的用户名然后退出重新登录。尝试在SSH命令中使用完整的docker路径例如在脚本或环境变量中设置DOCKER_CMDsudo docker需配置sudo免密码。6.2 脚本执行中的典型错误错误jq命令解析JSON失败报错“Cannot index string with string”。原因API返回的响应可能不是预期的JSON格式可能是HTML错误页面也可能是空的。排查在脚本命令前加上set -x或在命令中直接使用curl -v来查看原始的HTTP请求和响应。手动用curl测试API端点curl -s -H X-Api-Key: YOUR_KEY http://host:port/api/v3/health看看返回什么。检查服务日志确认API服务本身是否正常运行。错误脚本执行缓慢或超时。原因某些操作如查询全部历史记录、同步大量数据到Trakt可能耗时很长。脚本默认的超时时间可能不够。解决找到脚本中对应的curl命令增加超时参数例如curl --max-time 300300秒。建议在编写或修改脚本时对长时间运行的任务添加进度提示。6.3 性能与安全考量API调用频率避免在短时间内对同一个服务发起大量API请求这可能导致服务暂时屏蔽你的IP或增加服务器负载。脚本中已经考虑了一些延迟但在编写复杂工作流时仍需注意。敏感信息存储所有API密钥、令牌都以环境变量形式存储。务必确保你的shell历史记录文件如~/.bash_history和包含环境变量的配置文件如~/.bashrc的权限设置得当避免被未授权用户读取。可以考虑使用专门的密钥管理工具或至少对这些文件设置严格的访问权限chmod 600。网络隔离理想情况下你的媒体服务器应该位于家庭内部网络不直接暴露在公网。ClawARR Suite的所有通信都基于HTTP如果需要在公网访问务必通过VPN等安全通道并确保使用HTTPS如果服务支持。6.4 我的使用心得经过一段时间的深度使用我发现将日常运维“对话化”带来的最大改变是降低了管理的心智负担。以前需要记住“去哪个页面点哪个按钮”现在变成了“问一个问题”。例如周末想找部电影看我会直接问助手“推荐一部我库里还没看过的、评分7.5以上的科幻片。” 助手会调用脚本查询Radarr库过滤条件再结合Tautulli看看我最近的偏好给出一个建议。另一个深刻体会是脚本的健壮性比花哨的功能更重要。ClawARR Suite的脚本在错误处理上做得比较到位当某个服务暂时不可用时它会给出明确的错误信息而不是让整个流程静默失败。这在自动化场景中至关重要。最后不要试图一次性配置所有功能。先从核心的library.sh和analytics.sh开始确保Sonarr、Radarr、Plex的基础查询工作正常。然后再逐步添加下载管理、字幕搜索、外部同步等高级功能。每成功集成一个服务你对整个系统的掌控力就提升一个档次。这个技能包就像给你的媒体服务器插上了一对翅膀而真正有趣的是学会如何驾驭它去探索更高效、更个性化的媒体管理方式。