Folo 开放API第三方集成实战：3步拿到密钥、发出第一个请求并看懂返回结果

Folo 开放API第三方集成实战：3步拿到密钥、发出第一个请求并看懂返回结果

【免费下载链接】follow🧡 Folo is the AI RSS Reader项目地址: https://gitcode.com/GitHub_Trending/fol/follow

Folo 是一个 AI RSS 阅读器，它把订阅源、精选列表和内容时间线都放在服务端统一管理，而它的开放 API（默认入口在 apps/cli/src/client.ts 里写明的api.folo.is）就是把这些能力开放出来：任何脚本、机器人或你自己的小应用，都能通过一组 REST 接口读写订阅、拉取时间线、批量标记已读。简单说，你不用再对着 App 点点点，一条命令或一个 fetch 就能把 Folo 变成你工作流里的数据源。

🎬 先说清楚：什么情况下你会用到 Folo API

想象两个场景。

一个是运营同学老周，她每天要盯十几个技术订阅源，希望"每天早上 8 点自动把昨日未读文章喂给 AI 总结，推到工作群"。手动点根本做不到定时，但如果未读数、文章列表都能用接口拿，这事就是一个定时脚本的事。

另一个是做 AI Agent 的人，想让 Agent 能替用户查"我订阅了什么""有哪些没读的"，甚至帮用户增删订阅。Folo 官方 CLI 本身就是一份现成的 API 调用范例，连 Agent 用的说明书都写好了，可以直接对照着接。

所以 Folo 开放 API 解决的核心问题是：把"人肉在 App 里操作"变成"程序按接口协议自动操作"。

🚀 三步上手：从拿到密钥到看懂第一个返回

第一步：拿到你的 API 密钥（session token）

Folo API 用的是 Bearer Token 认证，也就是你的 session token。最省事的方式是用官方 CLI 走一遍浏览器登录：

npx --yes folocli@latest login

这条命令会拉起浏览器完成 Folo 账号登录，通过本地一次性回调把 token 换回来并写进本地配置；整个过程约 3 分钟超时保护，实现细节可以看 apps/cli/src/browser-login.ts。

如果是在服务器上跑（没有浏览器），就手动指定 token，或者用环境变量：

npx --yes folocli@latest login --token <你的token> export FOLO_TOKEN=<你的token>

第二步：发出第一个真实请求

登录成功后，发个请求验证一下。直接调 session 检查接口就能看懂整个认证模式——Authorization头里放 Bearer token，再带上对应的 cookie：

const res = await fetch("https://api.folo.is/better-auth/get-session", { headers: { Authorization: `Bearer ${token}`, Cookie: `__Secure-better-auth.session_token=${token}`, }, }); const session = await res.json();

返回里能看到你的用户信息、角色、订阅配额（feedSubscriptionLimit 这些字段），这等于顺手完成了"权限自检"。

第三步：看懂返回结果，学会翻页

Folo 的接口返回是统一的 JSON 信封结构，成功是{ ok: true, data: {...} }，失败是{ ok: false, error: { code, message } }，这个约定在 apps/cli/skill.md 里写得很清楚，写自动化时照着解析就行。

时间线这类列表接口额外返回entries、nextCursor、hasNext三个字段：拿到nextCursor再传回--cursor就能翻下一页，循环到hasNext为false就到底了。

🔧 进阶玩法：三个最值钱的集成场景

场景一：定时机器人，每天自动消化未读

组合unread count+timeline --unread-only+entry mark-read三条命令，就是一个完整的"拉未读→处理→标记"闭环：

npx --yes folocli@latest timeline --unread-only --limit 20 npx --yes folocli@latest entry mark-all-read --view articles

老周那个"喂给 AI 总结"的机器人，骨架就是这两条命令加一层定时触发。

场景二：订阅迁移与备份

opml export --output backup.opml一条命令导出全部订阅，opml import导回来。换平台、备份、给新设备播种订阅源，都不用手点。

场景三：自己部署时如何接收外部回调

如果你要把 Folo 的自部署版接进自己的发布流程，可以研究一下 api/vercel_webhook.ts：它展示了 Folo 团队自己是怎么处理外部 webhook 的——HMAC-SHA1 校验请求体签名（x-vercel-signature头）、密钥缺失时返回 400、签名不匹配返回 403。自己写集成回调时照抄这套校验姿势，安全性就有了基本盘。

🧯 避坑清单：高频报错对照排查

另外两个容易踩的坑：一是 token 里可能含%等字符，复制时要保证完整（CLI 内部专门有normalizeToken做 decode）；二是生产、dev、local 三套环境的 API 地址和 Web 域名是配对映射的，自部署时别把地址混着配。

📬 文档、社区与贡献入口

想继续深挖，三个入口都放在仓库里：命令全集和输出约定看 apps/cli/skill.md，各条命令的参数实现看 apps/cli/src/commands/，参与开发则按 CONTRIBUTING.md 的指南提 issue 或 PR。跑通第一个请求之后，剩下的就是把 Folo 的数据流接进你自己的自动化里——这件事不难，值得动手试一次。

【免费下载链接】follow🧡 Folo is the AI RSS Reader项目地址: https://gitcode.com/GitHub_Trending/fol/follow