前言¶
直接对接 YouTube Data API v3 的开发，通常要自己申请 OAuth 客户端、管理 token 刷新、按任务挑 scope，还要处理配额和权限范围的细节。另一个极端是用爬虫抓搜索结果页，验证码和 IP 限制是绕不开的问题。这个 Skill 走的是托管 OAuth 的路子：认证交给 Maton 网关，Skill 本身只负责组织对 YouTube 的调用。下面介绍这个 Skill 的定位、安装和调用方式。
这是什么¶
@byungkyu/youtube-api-skill，发布者 byungkyu，来源 clawhub，版本 1.0.6，上游仓库为 https://clawhub.ai/byungkyu/youtube-api-skill 。它通过 Maton 的托管 OAuth 集成 YouTube Data API v3，把视频搜索、播放列表管理、频道数据访问和评论互动包装成可直接调用的 Skill。SkillHub 页面（https://www.skillhub.cn/skills/clawhub_byungkyu/youtube-api-skill ）标注的元数据是：分类 dev-programming，标签 requires_api_key=true，评分 100000，下载 77434，安装 5073（以抓取时的页面为准）。
它解决的问题在于：把”连上 YouTube 账号并拿到授权”这件事从业务代码里剥离出去。调用都以用户自己连接的身份发起，能访问到的范围就是该连接授权允许的范围，由服务商在每个请求上强制执行。
核心功能¶
官方 SKILL.md 说明的能力包括：
1、视频搜索（video search）；
2、播放列表管理（playlists）；
3、频道数据访问（channel data）；
4、评论与订阅互动（comments and subscriptions）。
调用方式有两种：安装 Maton CLI 时走 CLI 加 OAuth 登录；装不了 CLI 的环境可以用 Maton API key 直接发 HTTP 请求。所有调用都以用户连接的身份认证，权限边界就是该连接的授权范围。
另外，这个 Skill 的文档还描述了 Maton 平台的三个构件：连接（connection）、托管函数（hosted function）和触发器（trigger）。函数用来把已批准的 YouTube 操作变成可自动运行的代码，触发器按计划或事件调用函数。需要注意，YouTube 本身不是事件源，触发器不能直接读 YouTube 数据；YouTube 相关的触发示例是平台通用文档，不额外增加 YouTube 能力。
安装与启用¶
安装 CLI¶
Skill 的调用经 maton CLI 完成，先装 CLI。官方提供两种安装方式，版本固定在 Skill 审核时的发布版本：
npm install -g @maton/cli@0.4.0
或：
brew install maton-ai/cli/maton
brew pin maton
Homebrew 无法从 tap 中选择版本，brew pin maton 会把当前安装的版本固定住，直到你决定升级。升级应当先看 release notes 再移动 pin，而不是直接跑未固定版本的安装命令。
安装 Skill¶
openclaw skills install @byungkyu/youtube-api-skill
这是 clawhub 页面给出的安装命令。页面同时标注了备选入口 npx skills install @byungkyu/youtube-api-skill。
登录与创建连接¶
maton login
执行后会打印登录链接，在浏览器打开并复制验证码，然后运行 maton login --code <CODE> 完成登录。登录成功后会在 config.toml（如 $HOME/.config/maton/config.toml）创建 profile，并把 access token 和 refresh token 存进系统凭据库（macOS 的 Keychain、Windows 的 Credential Manager、Linux 的 Secret Service），到期自动续期。
验证登录状态：
maton whoami --json
返回 authenticated: true 才算完成；如果 auth_type 是 api_key，建议改用 maton login 登录，避免长期持有持久凭据。
接下来创建 YouTube 连接。这一步需要用户明确批准授权，不要在未经确认的情况下自行创建：
maton connection create youtube
命令返回一个授权 URL，在浏览器打开完成授权。如果 YouTube 弹出 scope 选择，只勾选当前任务需要的 scope。
如果存在多个 YouTube 连接，调用时用 --connection {connection_id} 指定目标：
maton youtube video list --region US --limit 10 --connection {connection_id}
典型用法¶
先确认连接状态：
maton connection list youtube --status ACTIVE
返回 ACTIVE 的连接列表，拿到 connection_id 后发起第一次调用：
maton youtube video list --region US --limit 10
按区域（US）列出视频，限制 10 条。这是官方 Quick Start 的第一条调用命令，也是本 Skill 最常用的读操作。
如果要把一次 YouTube 读取变成定时运行的自动化任务，可以写一个经 Maton SDK 调用的托管函数。YouTube 凭据不离开网关：
import json
from maton_ai import Maton
maton = Maton()
def handler(event):
result = maton.youtube.video.list(limit=10)
return {"result": result}
部署函数时固定用 --network-policy DENY_ALL，禁止出站网络：
maton function create --name youtube-check --file main.py --network-policy DENY_ALL
函数以部署它的 Maton 账号身份运行，凭据通过运行时注入的 MATON_API_KEY 传递，不写进代码也不通过 function env 设置。通过 YouTube 连接读到的数据属于用户自己的业务数据，所以读 YouTube 的函数必须由用户编写并批准，且只读它所写的那个连接。需要访问外网的场景属于 api-gateway 技能，要单独走评审。
适用场景与注意¶
适合的场景：需要以编程方式搜索 YouTube 视频、读取频道数据、管理播放列表、处理评论互动，且希望认证托管、不在业务代码里碰 OAuth 流程的开发者。
注意事项：
1、默认使用读和列表类调用；每个写操作或新连接都要先和用户确认，不要自行发起。
2、创建连接前必须确认用户有意授权 YouTube 访问，maton connection create youtube 需要用户批准。
3、删除连接不可逆：会撤销已存储的授权，指向该 connection_id 的自动化会立即失效。删除前先 list connections 核对 id，--yes 会跳过交互确认，除非用户已明确确认特定连接，否则不要加。
4、Skill 标签为 requires_api_key=true；在无法安装 CLI 的环境，需要配置 Maton API key 走原始 HTTP 调用。
5、版本固定在审核时的发布版（CLI 0.4.0），升级要先看 release notes 再移动版本 pin。
结尾¶
这个 Skill 的价值在于把 YouTube Data API v3 的接入成本压到最小：认证交给托管 OAuth，业务侧只需要 maton 命令或一段托管函数。安装、登录、建连接、发调用的完整链路都在官方 SKILL.md 里给出了可复现的命令。
官方地址：https://clawhub.ai/byungkyu/youtube-api-skill ，SkillHub 页面：https://www.skillhub.cn/skills/clawhub_byungkyu/youtube-api-skill 。
