YouTube Comment Moderator
Classify, reply to, and delete YouTube comments automatically using Gemini Flash + YouTube Data API v3.
Setup (Agent-Driven)
When a user wants to set up YouTube moderation, walk them through this conversationally. Do not tell them to run shell commands.
1. Collect Channel Info
Ask: "What's your YouTube channel URL or channel ID?"
Resolve it:
source .env
python3 scripts/fetch_comments.py --channel-id <ID> --max-videos 1 --max-comments 0
This validates the channel exists. If they give a URL like
youtube.com/@handle, extract the handle and look up the channel ID via the API.
2. Check Environment Keys
Four keys are needed. Check which are missing:
CODEBLOCK1
For any missing keys, tell the user what to do (not how to run scripts):
- - YOUTUBEAPIKEY: "Go to Google Cloud Console → Credentials, create an API key, and add
YOUTUBE_API_KEY=... to your .env file." - GEMINIAPIKEY: "Go to Google AI Studio, create a key, and add
GEMINI_API_KEY=... to your .env file." - YTMODCLIENTID + YTMODCLIENTSECRET: These require OAuth setup. Walk them through
references/oauth-setup.md conversationally, or summarize: "In Google Cloud Console, enable YouTube Data API, create an OAuth consent screen (External, Testing mode), add yourself as test user, create a Web Application OAuth client with redirect URI http://127.0.0.1:8976/callback, then add the Client ID and Client Secret to your .env."
After they confirm keys are added, restart the gateway so env vars reload.
3. OAuth Authorization
Generate the auth URL and send it to the user:
CODEBLOCK2
Tell them: "Open this link, sign in with the Google account that owns your YouTube channel, and click Allow."
If user has a local browser (desktop): The script automatically catches the callback on http://127.0.0.1:8976/callback and saves the token. Tell them: "After clicking Allow, the browser should show a success page. You're done — I'll verify the token was saved."
If user is headless/remote (VPS, Telegram): Tell them: "After clicking Allow, your browser will redirect to a URL starting with http://127.0.0.1:8976/callback?code=.... That page won't load — that's expected. Copy ONLY the code parameter value from the URL (the part between code= and the next &), and paste just that code here. Do NOT paste the full URL — it contains sensitive auth data."
When they provide the code:
CODEBLOCK3
⚠️ Security note: The OAuth code is single-use and expires in minutes, but avoid logging or echoing the full callback URL. If the user accidentally pastes a full URL in chat, exchange it immediately, then advise them the code is already consumed and useless.
4. Configure
Ask them conversationally:
- - "What moderation mode? Auto (replies and deletes automatically), Approval (drafts everything for your review), or Monitor (classify and report only)?"
- "How do you typically talk to your audience? Casual? Professional? Funny?" (this sets voice_style)
- "Any common questions you get? I can pre-load answers so replies are accurate." (optional FAQ)
Then create the config:
CODEBLOCK4
5. Test
Run a dry run and show them the results:
CODEBLOCK5
Summarize: "Found X videos, Y new comments. Here's what I'd do: Z spam deleted, W questions answered, etc." Show a few examples.
6. Go Live
Once they approve:
CODEBLOCK6
Optionally set up a cron job to run every 15-30 minutes for ongoing moderation.
Scripts Reference
| Script | Purpose |
|---|
| INLINECODE13 | Setup wizard (interactive or --auth-url / --exchange-code / --create-config) |
| INLINECODE17 |
Main pipeline: fetch → classify → act. Also:
--stats,
--queue,
--approve,
--all-videos |
|
fetch_comments.py | Standalone comment fetcher (API key only) |
|
classify_comments.py | Standalone classifier (JSON in → JSON out) |
|
db.py | SQLite persistence layer |
Moderation Modes
- - monitor — classify + report only (no OAuth needed)
- approval — drafts replies and queues deletions for review (
--queue to see, --approve to execute) - auto — auto-replies to questions, auto-deletes spam/hate
Classification Categories
| Category | Auto Action | Description |
|---|
| spam | delete | Promotional links, scam offers, bot text, self-promo |
| question |
reply | Genuine question about video/creator/topic |
| praise | thank | Positive feedback, compliments |
| hate | delete | Hateful, abusive, harassing content |
| neutral | skip | Generic reactions, timestamps |
| constructive | flag | Thoughtful criticism, suggestions |
Architecture
- - State: SQLite (
data/youtube-comment-moderator/moderator.db) - Classification: Gemini 2.0 Flash (~$0.001/comment)
- Read: YouTube Data API v3 (API key)
- Write: YouTube Data API v3 (OAuth)
- Deduplication: comment_id primary key, already-processed comments skipped
Environment Variables
Required:
- -
YOUTUBE_API_KEY — YouTube Data API v3 key (free, 10K units/day) - INLINECODE29 — Gemini Flash for classification
For write operations (reply/delete):
- -
YT_MOD_CLIENT_ID — Google OAuth client ID - INLINECODE31 — Google OAuth client secret
Optional overrides:
- -
YT_MOD_DB — SQLite DB path (default: data/youtube-comment-moderator/moderator.db) - INLINECODE34 — OAuth token path (default:
skills/youtube-comment-moderator/oauth.json) - INLINECODE36 — Config path (default:
skills/youtube-comment-moderator/config.json)
OAuth Setup Details
See references/oauth-setup.md for the full step-by-step Google Cloud setup guide with screenshots-level detail and troubleshooting.
YouTube 评论审核工具
使用 Gemini Flash + YouTube Data API v3 自动分类、回复和删除 YouTube 评论。
设置流程（由代理引导）
当用户想要设置 YouTube 审核功能时，以对话方式引导他们完成以下步骤。不要让他们运行 shell 命令。
1. 收集频道信息
询问：你的 YouTube 频道 URL 或频道 ID 是什么？
解析频道信息：
bash
source .env
python3 scripts/fetch_comments.py --channel-id --max-videos 1 --max-comments 0
此操作验证频道是否存在。如果用户提供类似 youtube.com/@handle 的 URL，则提取 handle 并通过 API 查找频道 ID。
2. 检查环境密钥
需要四个密钥。检查哪些缺失：
bash
echo YOUTUBEAPIKEY=${YOUTUBEAPIKEY:+SET}
echo GEMINIAPIKEY=${GEMINIAPIKEY:+SET}
echo YTMODCLIENTID=${YTMODCLIENTID:+SET}
echo YTMODCLIENTSECRET=${YTMODCLIENTSECRET:+SET}
对于任何缺失的密钥，告知用户该做什么（而不是如何运行脚本）：
- - YOUTUBEAPIKEY：前往 Google Cloud Console → 凭据，创建一个 API 密钥，并将 YOUTUBEAPIKEY=... 添加到你的 .env 文件中。
- GEMINIAPIKEY：前往 Google AI Studio，创建一个密钥，并将 GEMINIAPIKEY=... 添加到你的 .env 文件中。
- YTMODCLIENTID + YTMODCLIENTSECRET：这些需要 OAuth 设置。以对话方式引导用户参考 references/oauth-setup.md，或总结如下：在 Google Cloud Console 中，启用 YouTube Data API，创建 OAuth 同意屏幕（外部，测试模式），将自己添加为测试用户，创建一个重定向 URI 为 http://127.0.0.1:8976/callback 的 Web 应用 OAuth 客户端，然后将客户端 ID 和客户端密钥添加到你的 .env 文件中。
用户确认密钥已添加后，重启网关以重新加载环境变量。
3. OAuth 授权
生成授权 URL 并发送给用户：
bash
source .env && python3 scripts/setup.py --auth-url
告知用户：打开此链接，使用拥有你 YouTube 频道的 Google 账号登录，然后点击允许。
如果用户有本地浏览器（桌面端）： 脚本会自动在 http://127.0.0.1:8976/callback 捕获回调并保存令牌。告知用户：点击允许后，浏览器应显示成功页面。操作完成——我将验证令牌已保存。
如果用户是无头/远程环境（VPS、Telegram）： 告知用户：点击允许后，你的浏览器将重定向到以 http://127.0.0.1:8976/callback?code=... 开头的 URL。该页面无法加载——这是正常现象。仅从 URL 中复制 code 参数的值（code= 和下一个 & 之间的部分），然后将该代码粘贴到这里。不要粘贴完整的 URL——它包含敏感的授权数据。
当用户提供代码时：
bash
source .env && python3 scripts/setup.py --exchange-code http://127.0.0.1:8976/callback?code=
⚠️ 安全提示： OAuth 代码为一次性使用，几分钟后过期，但应避免记录或回显完整的回调 URL。如果用户意外在聊天中粘贴了完整 URL，立即进行交换，然后告知用户该代码已被使用且已失效。
4. 配置
以对话方式询问用户：
- - 选择哪种审核模式？自动（自动回复和删除）、审批（将所有操作草稿化供你审核）或监控（仅分类和报告）？
- 你通常如何与观众交流？随意？专业？幽默？（这用于设置 voice_style）
- 你经常收到哪些常见问题？我可以预加载答案，确保回复准确。（可选 FAQ）
然后创建配置：
bash
python3 scripts/setup.py --create-config \
--channel-id \
--channel-name \
--mode \
--voice
5. 测试
运行试运行并向用户展示结果：
bash
source .env && python3 scripts/moderate.py --all-videos --dry-run
总结：找到 X 个视频，Y 条新评论。以下是我将执行的操作：删除 Z 条垃圾评论，回答 W 个问题等。展示几个示例。
6. 上线
用户批准后：
bash
source .env && python3 scripts/moderate.py --all-videos
可选择设置 cron 任务，每 15-30 分钟运行一次，实现持续审核。
脚本参考
| 脚本 | 用途 |
|---|
| setup.py | 设置向导（交互式或 --auth-url / --exchange-code / --create-config） |
| moderate.py |
主流程：获取 → 分类 → 执行。还支持：--stats、--queue、--approve、--all-videos |
| fetch_comments.py | 独立评论获取器（仅需 API 密钥） |
| classify_comments.py | 独立分类器（JSON 输入 → JSON 输出） |
| db.py | SQLite 持久化层 |
审核模式
- - 监控 — 仅分类和报告（无需 OAuth）
- 审批 — 草拟回复并将删除操作加入队列供审核（使用 --queue 查看，--approve 执行）
- 自动 — 自动回复问题，自动删除垃圾/仇恨内容
分类类别
| 类别 | 自动操作 | 描述 |
|---|
| 垃圾 | 删除 | 推广链接、诈骗信息、机器人文本、自我推广 |
| 问题 |
回复 | 关于视频/创作者/主题的真实问题 |
| 赞美 | 感谢 | 正面反馈、赞美 |
| 仇恨 | 删除 | 仇恨、辱骂、骚扰内容 |
| 中立 | 跳过 | 通用反应、时间戳 |
| 建设性 | 标记 | 有见地的批评、建议 |
架构
- - 状态： SQLite（data/youtube-comment-moderator/moderator.db）
- 分类： Gemini 2.0 Flash（约 $0.001/条评论）
- 读取： YouTube Data API v3（API 密钥）
- 写入： YouTube Data API v3（OAuth）
- 去重： comment_id 主键，跳过已处理的评论
环境变量
必需：
- - YOUTUBEAPIKEY — YouTube Data API v3 密钥（免费，每天 10K 单位）
- GEMINIAPIKEY — 用于分类的 Gemini Flash
用于写入操作（回复/删除）：
- - YTMODCLIENTID — Google OAuth 客户端 ID
- YTMODCLIENTSECRET — Google OAuth 客户端密钥
可选覆盖：
- - YTMODDB — SQLite 数据库路径（默认：data/youtube-comment-moderator/moderator.db）
- YTMODOAUTH — OAuth 令牌路径（默认：skills/youtube-comment-moderator/oauth.json）
- YTMODCONFIG — 配置路径（默认：skills/youtube-comment-moderator/config.json）
OAuth 设置详情
请参阅 references/oauth-setup.md 获取完整的 Google Cloud 设置分步指南，包含截图级别的详细信息和故障排除。
