Folo 开放 API 实战指南3 分钟跑通第一个集成请求Folo 是一个 AI RSS 阅读器它的开放 API 把时间线、订阅、未读状态这些核心能力暴露给脚本、CI 和 Agent 使用——你只需要一个 token。下面从登录到真实 webhook 链路全程走一遍。 快速上手3 分钟跑通第一个 Folo API 请求这一节解决怎么拿到凭证怎么确认接口通了。先在本地用浏览器登录token 会自动写入~/.folo/config.json在 CI 或无浏览器环境里改用环境变量FOLO_TOKEN即可。认证方式是一行话请求头带Authorization: Bearer token服务端校验会话。npx --yes foloclilatest login # 打开浏览器完成登录 npx --yes foloclilatest whoami # 验证 token 有效 npx --yes foloclilatest timeline --limit 5默认 API 地址是api.folo.is自建环境用--api-url覆盖。所有命令默认输出稳定 JSON 包络方便程序解析{ ok: true, data: {}, error: null }出错时error带code和message比如UNAUTHORIZED。加--format table可以切成人眼友好的表格输出详见 Folo CLI 使用说明。Folo 开放 API 能力全景哪些接口分别干什么这一节解决除了读时间线接口还能做什么。按数据、事件、扩展三类列一下。分类能力对应入口数据读时间线按源/列表/分类过滤游标分页timeline 命令实现数据订阅/取消订阅发现源与趋势榜subscription 与 search 命令数据OPML 导入导出、标记已读/未读、未读计数unread 命令事件第三方平台部署回调生产发布后自动刷新缓存webhook 处理逻辑事件移动端/桌面端更新检查manifest、policy 路由OTA 服务运维手册扩展MCP 连接管理支持 streamable-http 与 sse 两种传输桌面端 MCP 设置面板扩展全仓共享的 HTTP 客户端follow-app/client-sdkCLI 的认证与会话处理 实战走通Folo webhook 回调怎么配置并验证这一节解决当第三方平台以 Vercel 为例要向你推送事件时怎么安全地接住它。这里有个容易忽略的点验签必须基于原始请求体。回调地址怎么填密钥怎么配在平台侧把 webhook URL 指向 Folo 的 Vercel 函数对应 api/vercel_webhook.ts选一个随机串作为共享密钥服务端把它放进环境变量WEBHOOK_SECRET。密钥只在验签时使用不参与任何返回。const body await getRawBody(request) const sign crypto.createHmac(sha1, secret) .update(body).digest(hex) if (sign ! request.headers[x-vercel-signature]) { return res.status(403).json({ code: invalid_signature }) }注意别把密钥拼错也别先解析 body 再验签——handler 里专门配了bodyParser: false就是防止原始字节被框架提前消费掉。回调链路怎么验证发一次真实事件Vercel 在生产环境部署成功后会推送deployment.succeeded。handler 只处理target production的载荷其余事件直接跳过并记录日志。验证成功的三个标志有效请求返回200 OK未配密钥返回400 invalid_secret签名对不上返回403 invalid_signature。踩坑手册最常见的 3 个报错怎么解这一节解决报错之后一分钟定位不来回猜。现象UNAUTHORIZED提示 token 无效或过期。原因会话过期或 token 里带 URL 编码字符没被还原。解法重跑loginCLI 遇到含%的 token 会自动做一次解码见 client.ts 的normalizeTokenCI 里检查FOLO_TOKEN是否完整注入。现象webhook 直接400 invalid_secret。原因服务端没设置WEBHOOK_SECRET或它和平台侧配置的密钥不一致。解法两边改到同一个值再触发一次推送别只改一边。现象403 invalid_signature但两边密钥明明一致。原因签名是对解析后的 body 算的平台是对原始字节算的两者不一致。解法关闭 body 解析始终对 raw bytes 计算 HMAC-SHA1。如果还是不通带上--verbose重跑一次控制台会打印每笔请求的 method、URL 和状态码排障快很多。资源入口跑通之后去哪看命令与参数的完整清单在 CLI skill 文档webhook 与缓存刷新逻辑在 api/vercel_webhook.tsOTA 发布与回滚的操作流程写在 apps/ota/README.md移动端和桌面端的接入方式分别在 apps/mobile/ 与 apps/desktop/ 下可以直接对照源码。遇到问题可以先去项目仓库提 issue也可以在 Discord 开发者群里问响应很快。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Folo 开放 API 实战指南：3 分钟跑通第一个集成请求
Folo 开放 API 实战指南3 分钟跑通第一个集成请求Folo 是一个 AI RSS 阅读器它的开放 API 把时间线、订阅、未读状态这些核心能力暴露给脚本、CI 和 Agent 使用——你只需要一个 token。下面从登录到真实 webhook 链路全程走一遍。 快速上手3 分钟跑通第一个 Folo API 请求这一节解决怎么拿到凭证怎么确认接口通了。先在本地用浏览器登录token 会自动写入~/.folo/config.json在 CI 或无浏览器环境里改用环境变量FOLO_TOKEN即可。认证方式是一行话请求头带Authorization: Bearer token服务端校验会话。npx --yes foloclilatest login # 打开浏览器完成登录 npx --yes foloclilatest whoami # 验证 token 有效 npx --yes foloclilatest timeline --limit 5默认 API 地址是api.folo.is自建环境用--api-url覆盖。所有命令默认输出稳定 JSON 包络方便程序解析{ ok: true, data: {}, error: null }出错时error带code和message比如UNAUTHORIZED。加--format table可以切成人眼友好的表格输出详见 Folo CLI 使用说明。Folo 开放 API 能力全景哪些接口分别干什么这一节解决除了读时间线接口还能做什么。按数据、事件、扩展三类列一下。分类能力对应入口数据读时间线按源/列表/分类过滤游标分页timeline 命令实现数据订阅/取消订阅发现源与趋势榜subscription 与 search 命令数据OPML 导入导出、标记已读/未读、未读计数unread 命令事件第三方平台部署回调生产发布后自动刷新缓存webhook 处理逻辑事件移动端/桌面端更新检查manifest、policy 路由OTA 服务运维手册扩展MCP 连接管理支持 streamable-http 与 sse 两种传输桌面端 MCP 设置面板扩展全仓共享的 HTTP 客户端follow-app/client-sdkCLI 的认证与会话处理 实战走通Folo webhook 回调怎么配置并验证这一节解决当第三方平台以 Vercel 为例要向你推送事件时怎么安全地接住它。这里有个容易忽略的点验签必须基于原始请求体。回调地址怎么填密钥怎么配在平台侧把 webhook URL 指向 Folo 的 Vercel 函数对应 api/vercel_webhook.ts选一个随机串作为共享密钥服务端把它放进环境变量WEBHOOK_SECRET。密钥只在验签时使用不参与任何返回。const body await getRawBody(request) const sign crypto.createHmac(sha1, secret) .update(body).digest(hex) if (sign ! request.headers[x-vercel-signature]) { return res.status(403).json({ code: invalid_signature }) }注意别把密钥拼错也别先解析 body 再验签——handler 里专门配了bodyParser: false就是防止原始字节被框架提前消费掉。回调链路怎么验证发一次真实事件Vercel 在生产环境部署成功后会推送deployment.succeeded。handler 只处理target production的载荷其余事件直接跳过并记录日志。验证成功的三个标志有效请求返回200 OK未配密钥返回400 invalid_secret签名对不上返回403 invalid_signature。踩坑手册最常见的 3 个报错怎么解这一节解决报错之后一分钟定位不来回猜。现象UNAUTHORIZED提示 token 无效或过期。原因会话过期或 token 里带 URL 编码字符没被还原。解法重跑loginCLI 遇到含%的 token 会自动做一次解码见 client.ts 的normalizeTokenCI 里检查FOLO_TOKEN是否完整注入。现象webhook 直接400 invalid_secret。原因服务端没设置WEBHOOK_SECRET或它和平台侧配置的密钥不一致。解法两边改到同一个值再触发一次推送别只改一边。现象403 invalid_signature但两边密钥明明一致。原因签名是对解析后的 body 算的平台是对原始字节算的两者不一致。解法关闭 body 解析始终对 raw bytes 计算 HMAC-SHA1。如果还是不通带上--verbose重跑一次控制台会打印每笔请求的 method、URL 和状态码排障快很多。资源入口跑通之后去哪看命令与参数的完整清单在 CLI skill 文档webhook 与缓存刷新逻辑在 api/vercel_webhook.tsOTA 发布与回滚的操作流程写在 apps/ota/README.md移动端和桌面端的接入方式分别在 apps/mobile/ 与 apps/desktop/ 下可以直接对照源码。遇到问题可以先去项目仓库提 issue也可以在 Discord 开发者群里问响应很快。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考