OpenClaw 的 Trakt.tv 集成

集成 Trakt.tv，用于追踪观看历史并提供个性化的剧集/电影推荐。

📚 Trakt API 文档： https://trakt.docs.apiary.io/

首次使用前需完成初始化设置

在使用本功能前，请运行交互式初始化脚本：

自动化设置（推荐）

python3 scripts/setup.py

该脚本将引导您完成以下步骤：

1. 安装依赖项
2. 创建 Trakt 应用程序
3. 配置认证凭据
4. 通过 PIN 方式完成身份验证
5. 测试集成是否正常工作

手动设置

若自动化设置失败，请参考下方“设置”章节中的手动操作步骤。

OpenClaw 的交互式设置流程

当用户提出“安装 Trakt”或“设置 Trakt 集成”等请求时，OpenClaw 应执行以下操作：

1. 查阅 INSTALL.md 获取详细的交互式流程说明
2. 或直接运行 python3 scripts/setup.py，并根据终端提示引导用户完成配置

功能特性

• 追踪观看历史（由 Trakt 自动从流媒体服务同步）
• 基于用户观看习惯生成个性化推荐
• 访问用户的观看列表（watchlist）与收藏集（collections）
• 搜索剧集和电影
• 查看当前热门内容（trending）

前置条件

1. Python 依赖项：

   # 使用 pip 安装（如需，可添加 --break-system-packages 参数）
   pip3 install requests
   
   # 或推荐使用虚拟环境
   python3 -m venv ~/.openclaw-venv
   source ~/.openclaw-venv/bin/activate
   pip install requests
   

   如系统支持，也可通过 Homebrew 安装：

   brew install python-requests
   

2. Trakt.tv 账户（需订阅 Pro 版本，自动追踪观看记录所必需）

3. Trakt API 应用程序 —— 请前往 https://trakt.tv/oauth/applications 创建

4. 配置文件： ~/.openclaw/trakt_config.json（详见下方设置说明）

设置

1. 创建 Trakt 应用程序

1. 访问 https://trakt.tv/oauth/applications
2. 点击“New Application”
3. 填写表单：
   • 名称（Name）： “OpenClaw Assistant”
   • 描述（Description）： “Personal AI assistant integration”
   • 重定向 URI（Redirect URI）： urn:ietf:wg:oauth:2.0:oob（用于 PIN 认证）
   • 权限（Permissions）：勾选所有适用选项
4. 保存后，请记录下您的 Client ID 和 Client Secret

2. 创建配置文件

创建配置文件 ~/.openclaw/trakt_config.json，填入您的凭据信息：

{
  "client_id": "YOUR_CLIENT_ID_HERE",
  "client_secret": "YOUR_CLIENT_SECRET_HERE",
  "access_token": "",
  "refresh_token": ""
}

请将 YOUR_CLIENT_ID_HERE 和 YOUR_CLIENT_SECRET_HERE 替换为步骤 1 中获取的实际值。

注意： access_token 与 refresh_token 字段请保持为空，将在完成身份验证后由系统自动填充。

3. 身份验证

运行认证脚本：

python3 scripts/trakt_client.py auth

脚本将输出一个 PIN 认证链接。请访问该链接，授权应用后，再执行：

python3 scripts/trakt_client.py auth 

认证成功后，令牌将被保存至 ~/.openclaw/trakt_config.json。

使用方法

获取推荐内容

当用户请求剧集或电影推荐时：

python3 scripts/trakt_client.py recommend

该命令将基于用户的观看历史与评分数据返回个性化推荐结果。

查看观看历史

python3 scripts/trakt_client.py history

返回用户最近的观看记录。

查看观看列表（Watchlist）

python3 scripts/trakt_client.py watchlist

显示用户已保存、计划稍后观看的内容。

搜索内容

python3 scripts/trakt_client.py search "Breaking Bad"

按名称搜索特定剧集或电影。

查看热门内容

python3 scripts/trakt_client.py trending

获取当前热门的剧集与电影列表。

推荐工作流

当用户询问“我该看什么？”或类似问题时：

1. 获取个性化推荐：

   python3 scripts/trakt_client.py recommend
   

2. 解析返回结果，并以自然语言方式呈现：

   • 剧集/电影标题、年份、评分
   • 简要描述或所属类型（genre）
   • 推荐理由（如 API 返回中包含）

3. 可选：检查观看列表，避免向用户推荐其已计划观看的内容

4. 结合近期观看历史，避免重复推荐刚看过的内容

API 参考文档

详细 Trakt API 接口说明请参阅 references/api.md。

常见使用场景

“今晚该看什么？”

• 获取推荐内容；若用户指定了情绪（mood）或类型（genre），则进行相应过滤
• 若用户希望观看流行内容，可改查 trending 列表

“把 [剧集名] 加入我的观看列表”

• 先搜索目标剧集
• 调用 Trakt API 将其加入用户的 watchlist（需额外实现对应接口）

“我最近都在看些什么？”

• 获取观看历史记录
• 汇总近期观看的剧集/电影

“[剧集名] 现在热门吗？”

• 获取 trending 列表
• 在列表中搜索指定剧集

限制条件

• 需订阅 Trakt Pro 才能实现从流媒体平台自动同步观看记录
• 推荐质量随观看历史积累而逐步提升
• API 请求频率限制：每 5 分钟最多 1000 次（需认证）
• 完整 API 文档：https://trakt.docs.apiary.io/

故障排查

“认证失败”

• 确认 ~/.openclaw/trakt_config.json 中的 CLIENT_ID 与 CLIENT_SECRET 设置正确
• 确保 PIN 码准确复制（区分大小写）
• 检查 Trakt 应用程序是否已授予必要权限

“未返回任何推荐结果”

• 用户可能尚未积累足够观看历史
• 可尝试回退至 trending 内容作为替代方案
• 确认用户已在 Trakt 上对部分内容进行过评分

“API 请求失败”

• 检查 access_token 是否已过期
• 确认网络连接正常
• 查看 Trakt API 服务状态：https://status.trakt.tv