Folo API 完整接入指南从认证到首次调用只需 3 步Folo 是一款开源 AI RSS 阅读器把你的订阅整理进同一条时间线。借助 Folo API你可以在自己的脚本、第三方工具或 AI 助手里读取时间线、管理订阅、获取文章正文而不用重建一套内容管道。集成后你拿到的就是与官方客户端相同的数据和能力。 Folo API 认证方式与凭证获取Folo API 使用会话令牌认证与 Web 端、桌面端共用同一套登录体系不需要单独申请 API Key。认证方式每次请求把令牌放在两处请求头Authorization: Bearer token请求头Cookie: better-auth.session_tokentoken部分接口依赖建议一起带上基础地址为https://api.folo.is。开发、本地环境的地址对照见环境配置。如何获取 Token浏览器登录终端执行npx --yes foloclilatest login。CLI 会在本机启动回调服务你在浏览器里登录后令牌自动写入本地配置。手动令牌从桌面端获取会话令牌或一次性令牌执行npx --yes foloclilatest login --token token或设置环境变量FOLO_TOKEN。前置条件已安装 Node.jsCLI 通过 npx 运行最新版无需全局安装已有 Folo 账号并在任一官方客户端处于登录态用于换取一次性令牌 三步完成第一次 Folo API 调用第一步登录并验证。npx --yes foloclilatest login npx --yes foloclilatest whoamiwhoami会请求/better-auth/get-session返回里同时有user和session就说明令牌有效。第二步发起业务调用。CLI 就是 API 的现成示例直接调用的话用 fetch 带上令牌即可const res await fetch(https://api.folo.is/better-auth/get-session, { headers: { Authorization: Bearer ${token} }, });第三步读懂响应。响应统一是 JSON 信封ok、data、error。成功时ok为true业务字段在data失败时ok为falseerror里是code和message例如UNAUTHORIZED配Token is invalid or expired.。列表接口额外带entries、nextCursor、hasNext三个分页字段把nextCursor回传给下一次请求循环到hasNext为false即可拉完。 Folo API 能力一览分类用途认证登录、会话校验、一次性令牌换取时间线拉取时间线按已读、分类、单源筛选分页订阅管理增删改 feed 与 list调整分类和可见性文章操作读详情、可读性正文标记已读/未读搜索发现关键词发现、热门源、RSSHub 生成收藏把文章加入收藏列表与移除导入导出OPML 备份与还原各命令的参数明细在CLI 能力说明里都有请求与响应的完整结构可以参考客户端代码和命令实现。典型集成场景场景一让 AI 助手读你的信息流。桌面端内置的 Agent 入口就是让助手按 skill.md 的约定操作 Folo。你要接入自己的 bot只需两件事配好令牌把 apps/cli/skill.md 里的工作流说明交给助手。浏览器登录流程中的本地回调加一次性令牌交换逻辑也可以原样搬到你的服务端。场景二Webhook 事件通知。Folo 用带签名的 webhook 接收平台事件webhook 处理器是参考实现服务端用WEBHOOK_SECRET对原始请求体做 HMAC-SHA1与x-vercel-signature头比对不一致直接拒绝通过后按type字段分发。你要往自己系统推事件时照这个「密钥加签名」的模式做即可。场景三跨端迁移订阅库。用 OPML 把订阅导出成文件在新设备或新脚本里导入也可以只挑选部分条目导入适合换环境时保留整套订阅。⚠️ Folo API 避坑与故障排查表现象常见原因处理办法UNAUTHORIZED令牌过期或写错重新执行login脚本里检查FOLO_TOKEN来源400 invalid_secretwebhook服务端没配WEBHOOK_SECRET补上密钥环境变量403 invalid_signaturewebhook两端密钥不一致或请求体被改动用原始字节体验签确认密钥一致HTTP_5xx服务临时故障重试加--verbose查看请求详情INVALID_ARGUMENT参数名或取值不对执行command --help核对429请求过于频繁降低频率分页拉取合并成批量一个隐蔽坑令牌可能是 URL 编码过的CLI 内部会先解码再用。你从 OAuth 回调链接里取令牌时记得先做一次 URL 解码。️ Folo API 资源地图能力与工作流说明apps/cli/skill.md认证与客户端逻辑apps/cli/src/client.ts全部命令实现apps/cli/src/commands/webhook 验签参考实现api/vercel_webhook.ts环境地址配置packages/internal/shared/src/env.common.ts贡献指南CONTRIBUTING.md下一步可以先跑whoami确认令牌可用再把时间线读取或 OPML 导出接进你的脚本。若要构建常驻服务照着 webhook 的实现给自己的事件入口加上同样的验签逻辑。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考