ValueError: Invalid YouTube channel URL: @exampleChannel

问题场景

用户在 CrewAI 项目中导入 crewai_tools 的 YoutubeChannelSearchTool，并按照 CrewAI v1.15.21 文档，用 youtube_channel_handle="@handle" 这类频道句柄初始化工具。工具初始化阶段即抛出 ValueError，无法进入实际的频道内容加载流程。

讨论中还确认了第二种失败路径：用户尝试改用完整 YouTube 频道 URL 作为输入，同样失败，因为 YoutubeChannelSearchTool.add() 会给不以 @ 开头的值补上 @，把完整 URL 变成畸形值。

报错原文

ValueError: Invalid YouTube channel URL: @exampleChannel

ValueError: Invalid YouTube channel URL: @handle

原因分析

根因在于 YoutubeChannelSearchTool 与底层 YoutubeChannelLoader 对输入格式的预期不一致。

YoutubeChannelLoader.load() 只接受包含 youtube.com/... 的 source，其校验模式包括：

[
    "youtube.com/channel/",
    "youtube.com/c/",
    "youtube.com/@",
    "youtube.com/user/",
]

而 YoutubeChannelSearchTool 会把文档中约定的 @handle 直接交给 RAG adapter，并未先转换成完整 URL，因此在进入 pytube 之前就被 loader 拒绝。

另一方面，YoutubeChannelSearchTool.add() 会对任何不以 @ 开头的输入补 @ 前缀，所以传完整 URL 也不是可行绕过方式，反而会得到 @https://... 并被 loader 再次拒绝。

Issue 正文认为该问题与旧 Issue #5429 相关；评论进一步指出，现有测试之所以没覆盖到，是因为测试 mock 了 RAG adapter，绕过了 loader 的真实校验路径，因此无法暴露这一格式不匹配。

环境排查

• 确认 crewai 版本：Issue 中为 1.15.21。
• 确认 crewai-tools 版本：Issue 中为 1.15.21。
• 确认操作系统：Issue 中为 Windows 11。
• 确认 Python 版本：Issue 元数据为 3.12，复现步骤写的是 Python 3.13。
• 确认虚拟环境：Issue 中为 Conda。
• 确认 YoutubeChannelLoader 的校验是否仍要求 youtube.com/...，以及 add() 是否仍对非 @ 开头输入补前缀。
• 确认你安装的 crewai-tools 是否已包含针对 @handle 到完整 URL 的规范化逻辑，以及是否已合入修复 PR #7420。
• 确认 pytube 相关句柄兼容性是否正常，Issue 讨论提到修复 PR 也涉及 pytube 句柄兼容问题。

解决步骤

1. 先在当前环境中复现最小用例，确认输入为 youtube_channel_handle="@handle" 时抛出 ValueError: Invalid YouTube channel URL: @handle。
2. 检查 crewai_tools/rag/loaders/youtube_channel_loader.py 中的 URL 校验模式，确认它是否只接受包含 youtube.com/... 的 source。
3. 检查 YoutubeChannelSearchTool.add() 的实现，确认它是否会对不以 @ 开头的输入补 @；这会解释为什么完整 URL 也不是 workaround。
4. 不要用完整 URL 直接替换 @handle 作为临时绕过，因为 add() 会将其变成 @https://... 并继续被 loader 拒绝。
5. 若你希望自行修复，可优先尝试 Issue 讨论中的规范化思路：在 YoutubeChannelLoader 做 URL 模式检查前，把开头的 @handle 转成 https://www.youtube.com/@handle；同时修改 add()，对已经以 http(s):// 开头的 URL 不再补 @ 前缀。该方案属于讨论中提出的候选修复，尚未在本文确认已合入稳定发行版。
6. 关注 PR #7420 的处理状态。Issue 评论称该 PR 包含句柄/URL 规范化、pytube 句柄兼容、现代 YouTube 频道布局与 continuation 分页，并带有覆盖加载路径的回归测试。
7. 如需自行验证修复，可参考 Issue 评论中提到的回归测试方式：mock pytube，避免真实网络请求，覆盖 @handle 与完整 URL 两条路径。

验证方法

用 YoutubeChannelSearchTool(youtube_channel_handle="@handle") 初始化不再抛出 ValueError，且工具能继续进入频道内容加载流程；同时确认传入以 http(s):// 开头的完整频道 URL 时，add() 不会生成 @https://... 这种畸形值。若在本地应用了候选修复，建议运行针对搜索工具与 tests/rag/ 的回归测试，并确保测试中 pytube 为 mock 状态、不依赖真实网络。

参考来源

crewAIInc/crewAI #7404

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。