OpenClaw Skills YouTube 交互技能使用参考手册

概述

YouTube API Skill 是用于让 OpenClaw 通过 YouTube Data API v3 与 YouTube 平台交互的技能，该技能支持视频搜索、播放列表管理、频道信息访问、评论交互、订阅管理等功能，通过 Maton 平台的网关进行 OAuth 认证管理，无需手动处理复杂的 OAuth 流程。

该技能可以帮助用户在 OpenClaw 中直接访问和操作 YouTube 平台的功能，适合需要在 AI 助手中集成 YouTube 功能的场景，例如视频内容搜索、频道数据统计、播放列表管理等。

技能信息

• 名称：youtube-api-skill
• 描述：通过 YouTube Data API v3 与 YouTube 平台交互，支持视频搜索、播放列表管理、频道信息访问、评论交互和订阅管理，使用 Maton 平台的网关进行 OAuth 认证管理。
• 版本：1.0.3
• 作者：byungkyu
• 许可证：MIT License
• 依赖：
  • 需要网络访问权限
  • 需要有效的 Maton API Key（MATON_API_KEY）
• 触发词："YouTube 搜索"、"YouTube 视频管理"、"YouTube 频道信息"、"YouTube 播放列表"、"YouTube 评论"

👤 作者：byungkyu
🦞 官方地址：https://clawhub.ai/byungkyu/youtube-api-skill
👉 Skills 下载地址：youtube-api-skill-1.0.3.zip

配置要求

获取 Maton API Key

1. 访问maton.ai注册或登录账户
2. 进入maton.ai/settings页面
3. 复制你的 API Key

设置环境变量

将获取到的 API Key 设置为环境变量：

export MATON_API_KEY="你的API密钥"

连接管理

创建连接

创建 YouTube 连接以进行 OAuth 授权：

import urllib.request, os, json
data = json.dumps({'app': 'youtube'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

获取连接

获取当前的 YouTube 连接信息：

import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=youtube&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

获取指定连接

获取特定 ID 的连接信息：

import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

删除连接

删除指定的 YouTube 连接：

import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

指定连接

如果你有多个 YouTube 连接，可以通过Maton-Connection头指定使用哪个连接：

import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/youtube/youtube/v3/channels?part=snippet&mine=true')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))

API 参考

搜索

搜索视频、频道或播放列表

GET /youtube/youtube/v3/search

查询参数：

• part - 必填：snippet
• q - 搜索关键词
• type - 按类型过滤：video、channel、playlist
• maxResults - 每页结果数（1-50，默认 5）
• order - 排序方式：date、rating、relevance、title、viewCount
• publishedAfter - 按发布日期过滤（RFC 3339 格式）
• publishedBefore - 按发布日期过滤（RFC 3339 格式）
• channelId - 按频道过滤
• videoDuration - 视频时长：short（<4 分钟）、medium（4-20 分钟）、long（>20 分钟）
• pageToken - 分页令牌

示例：

curl -s -X GET "https://gateway.maton.ai/youtube/youtube/v3/search?part=snippet&q=machine+learning&type=video&maxResults=10&order=viewCount" -H "Authorization: Bearer $MATON_API_KEY"

视频

获取视频详情

GET /youtube/youtube/v3/videos?part=snippet,statistics,contentDetails&id={videoId}

可用的 part：

• snippet - 标题、描述、缩略图、频道信息
• statistics - 观看次数、点赞数、评论数
• contentDetails - 时长、维度、清晰度
• status - 上传状态、隐私状态
• player - 嵌入播放器 HTML

示例：

curl -s -X GET "https://gateway.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ" -H "Authorization: Bearer $MATON_API_KEY"

获取我上传的视频

GET /youtube/youtube/v3/search?part=snippet&forMine=true&type=video&maxResults=25

评分视频（点赞 / 点踩）

POST /youtube/youtube/v3/videos/rate?id={videoId}&rating=like

评分值：like、dislike、none

获取热门视频

GET /youtube/youtube/v3/videos?part=snippet,statistics&chart=mostPopular®ionCode=US&maxResults=10

获取视频分类

GET /youtube/youtube/v3/videoCategories?part=snippet®ionCode=US

频道

获取频道详情

GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&id={channelId}

获取我的频道

GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&mine=true

通过用户名获取频道

GET /youtube/youtube/v3/channels?part=snippet,statistics&forUsername={username}

播放列表

列出我的播放列表

GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&mine=true&maxResults=25

获取播放列表

GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&id={playlistId}

创建播放列表

POST /youtube/youtube/v3/playlists?part=snippet,status
Content-Type: application/json
{
  "snippet": {
    "title": "我的新播放列表",
    "description": "视频合集",
    "defaultLanguage": "en"
  },
  "status": {
    "privacyStatus": "private"
  }
}

隐私状态值：public、private、unlisted

更新播放列表

PUT /youtube/youtube/v3/playlists?part=snippet,status
{
  "id": "PLxyz123",
  "snippet": {
    "title": "更新后的播放列表标题",
    "description": "更新后的描述"
  },
  "status": {
    "privacyStatus": "public"
  }
}

删除播放列表

DELETE /youtube/youtube/v3/playlists?id={playlistId}

播放列表项

列出播放列表项

GET /youtube/youtube/v3/playlistItems?part=snippet,contentDetails&playlistId={playlistId}&maxResults=50

添加视频到播放列表

POST /youtube/youtube/v3/playlistItems?part=snippet
Content-Type: application/json
{
  "snippet": {
    "playlistId": "PLxyz123",
    "resourceId": {
      "kind": "youtube#video",
      "videoId": "abc123xyz"
    },
    "position": 0
  }
}

从播放列表移除

DELETE /youtube/youtube/v3/playlistItems?id={playlistItemId}

订阅

列出我的订阅

GET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&maxResults=50

检查是否订阅频道

GET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&forChannelId={channelId}

订阅频道

POST /youtube/youtube/v3/subscriptions?part=snippet
Content-Type: application/json
{
  "snippet": {
    "resourceId": {
      "kind": "youtube#channel",
      "channelId": "UCxyz123"
    }
  }
}

取消订阅

DELETE /youtube/youtube/v3/subscriptions?id={subscriptionId}

评论

列出视频评论

GET /youtube/youtube/v3/commentThreads?part=snippet,replies&videoId={videoId}&maxResults=100

给视频添加评论

POST /youtube/youtube/v3/commentThreads?part=snippet
Content-Type: application/json
{
  "snippet": {
    "videoId": "abc123xyz",
    "topLevelComment": {
      "snippet": {
        "textOriginal": "很棒的视频！"
      }
    }
  }
}

回复评论

POST /youtube/youtube/v3/comments?part=snippet
Content-Type: application/json
{
  "snippet": {
    "parentId": "comment123",
    "textOriginal": "感谢你的评论！"
  }
}

删除评论

DELETE /youtube/youtube/v3/comments?id={commentId}

代码示例

JavaScript

const headers = {
  'Authorization': `Bearer ${process.env.MATON_API_KEY}`
};


// 搜索视频
const results = await fetch(
  'https://gateway.maton.ai/youtube/youtube/v3/search?part=snippet&q=tutorial&type=video&maxResults=10',
  { headers }
).then(r => r.json());


// 获取视频详情
const video = await fetch(
  'https://gateway.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ',
  { headers }
).then(r => r.json());


// 创建播放列表
await fetch(
  'https://gateway.maton.ai/youtube/youtube/v3/playlists?part=snippet,status',
  {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      snippet: { title: '我的播放列表', description: '我喜欢的视频' },
      status: { privacyStatus: 'private' }
    })
  }
);

Python

import os
import requests


headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}


## 搜索视频
results = requests.get(
  'https://gateway.maton.ai/youtube/youtube/v3/search',
  headers=headers,
  params={'part': 'snippet', 'q': 'tutorial', 'type': 'video', 'maxResults': 10}
).json()


## 获取视频详情
video = requests.get(
  'https://gateway.maton.ai/youtube/youtube/v3/videos',
  headers=headers,
  params={'part': 'snippet,statistics', 'id': 'dQw4w9WgXcQ'}
).json()


## 创建播放列表
response = requests.post(
  'https://gateway.maton.ai/youtube/youtube/v3/playlists?part=snippet,status',
  headers=headers,
  json={
    'snippet': {'title': '我的播放列表', 'description': '我喜欢的视频'},
    'status': {'privacyStatus': 'private'}
  }
)

常见问题

错误代码

提示

• 视频 ID 是 11 个字符（例如：dQw4w9WgXcQ）
• 频道 ID 以UC开头（例如：UCxyz123）
• 播放列表 ID 以PL（用户创建）或UU（上传视频）开头

许可证信息

该技能采用 MIT License，完整的许可条款如下：

The MIT License (MIT)
Copyright (c) 2026 Maton


Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:


The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.


THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

元数据信息

该技能的元数据信息如下：

{
  "ownerId": "kn75240wq8bnv2qm2xgry748jd80b9r0",
  "slug": "youtube-api-skill",
  "version": "1.0.3",
  "publishedAt": 1770756366839
}