企业官网建设流程全解析

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 folocli@latest login # 打开浏览器完成登录 npx --yes folocli@latest whoami # 验证 token 有效 npx --yes folocli@latest 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 能力全景：哪些接口，分别干什么

这一节解决：除了读时间线，接口还能做什么。按数据、事件、扩展三类列一下。

🪝 实战走通：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 个报错怎么解

这一节解决：报错之后一分钟定位，不来回猜。

1. 现象：UNAUTHORIZED，提示 token 无效或过期。原因：会话过期，或 token 里带 URL 编码字符没被还原。解法：重跑login；CLI 遇到含%的 token 会自动做一次解码（见 client.ts 的normalizeToken）；CI 里检查FOLO_TOKEN是否完整注入。

2. 现象：webhook 直接400 invalid_secret。原因：服务端没设置WEBHOOK_SECRET，或它和平台侧配置的密钥不一致。解法：两边改到同一个值再触发一次推送，别只改一边。

3. 现象：403 invalid_signature，但两边密钥明明一致。原因：签名是对解析后的 body 算的，平台是对原始字节算的，两者不一致。解法：关闭 body 解析，始终对 raw bytes 计算 HMAC-SHA1。

如果还是不通，带上--verbose重跑一次，控制台会打印每笔请求的 method、URL 和状态码，排障快很多。

资源入口：跑通之后去哪看

命令与参数的完整清单在 CLI skill 文档，webhook 与缓存刷新逻辑在 api/vercel_webhook.ts，OTA 发布与回滚的操作流程写在 apps/ota/README.md，移动端和桌面端的接入方式分别在 apps/mobile/ 与 apps/desktop/ 下可以直接对照源码。遇到问题可以先去项目仓库提 issue，也可以在 Discord 开发者群里问，响应很快。