密钥永不出本地:API Anything 安全设计、已知限制与未来路线图
密钥永不出本地:API Anything 安全设计、已知限制与未来路线图
API Anything 是一个把任意网站变成可调用 API 的本地工具:它从网站自己的前端学习请求,让 AI Agent 通过 HTTP 直接拿到 JSON,而无需驱动整个浏览器。它最打动人的安全设计是——你的登录凭证(Cookie、token)始终留在本机 ~/.api-anything,规格文件里只存引用、从不存值。本文带你读懂它的完整安全设计,诚实列出已知限制,并梳理它明确不做与未来打算做的事。
一、为什么"密钥不出本地"是基石 🛡️
Agent 要访问 LinkedIn、X、Instagram 这类需要登录的站点,绕不开凭证。市面上不少"把网站变 API"的方案,会把抓到的 Cookie、token 直接硬编码进生成的代码或规格文件里——一旦这份文件被分享、提交到仓库,密钥就泄露了。
API Anything 反其道而行:所有凭证都待在本地目录,规格文件(spec)里只有像 cookie:ct0 这样的引用,真正的值永远不落地到可分享的文件中。 这就是"密钥永不出本地"这句话的由来。
二、核心安全设计拆解
1. 规格只存引用,不存值
学习一个操作时,引擎会把请求里的 Cookie 和认证头替换成对本地会话存储的引用,而不是原值。这样一份 spec 可以安全导出、分享、交给他人,而不会夹带你的登录信息。
- 学习逻辑:src/learn.ts
- 本地会话与存储:src/store.ts、src/session.ts
2. 保存前强制"秘密扫描"(fail-closed)
这是安全设计里最硬核的一环。每次 add(学习)或 heal(修复)保存前,以及 export 导出前,都会跑一遍秘密扫描 scanSecrets():
- 它拿你真实的 Cookie 和会话值(而不是泛泛的正则)去逐个规格字段比对;
- 不仅看原文,还会把文本解码三层(URL 编码、JSON 转义、base64)再找,甚至按"该值自身的 base64 编码"在任意字节偏移处反查,防止值被藏在编码后面;
- 一旦命中"活的"密钥,直接拒绝保存这份 spec,而不是打个警告让你忽略。
换句话说:宁可不存,也不带密钥出门。
3. 登录只"借"你已登录的浏览器会话 🌐
需要账号的站点,一条命令即可完成登录:
api-anything login linkedin.com
它默认从你日常浏览器里导入该站点的 Cookie——你早就在那里登录好了,所以不用重输密码、不用重做 2FA/验证码。它有三个贴心细节:
- 只读取该站点的 Cookie,不扫别的站;
- 多个浏览器配置都登录着时绝不猜,而是列出候选让你选;
- 导入的是和你浏览器同一个会话,站点把你登出时两边一起失效——所以官方提醒别在这个会话上跑重度自动化。
4. 写操作默认禁止,且"学习时绝不真正执行"
发帖、发消息、下单这类写操作有独立的安全规则:
- 学习写操作时,引擎会在浏览器里拦截并中止该请求,因此学习本身永远不会真正执行动作;
- 调用写操作必须显式加
--allow-writes; - 写请求只发一次,仅在服务器确定没执行(如直接返回 4xx)时才重试,超时/5xx 一律报告不重试;
- 内置示例里没有任何写操作,相关流程只针对本地测试桩验证过。
规则细节见 skills/api-anything/SKILL.md 的 "Write safety" 小节。
5. 本地文件权限 + 敏感产物自动清理
- 凭证目录
~/.api-anything使用 0700(目录)/ 0600(文件) 权限,防止其他用户读取; - 抓包产物
captures会保存完整响应和当次 Cookie 值,因此只保留最新 20 份、超过 24 小时即删; - 跨源重定向时,认证头(authorization、cookie 及所有引用填充的头)会被丢弃,不把凭证带到别的域名。
三、诚实的已知限制 ⚠️
API Anything 自称是 v0.1 的开发者早期版本,官方把边界写得很清楚(见 docs/REFERENCE.md 的 "Status and known limits"):
- 本地工具,不是托管 API:用你的机器、你的网络、你的会话,不提供云端服务;
- 只认识被教过的操作:只覆盖 9 个站点的 22 个只读操作,不是整站能力;
- 修复会失败:没有验证码破解、没有 TLS 指纹伪装;若某站对真实 Chrome 也弹人机验证,需要手动清除;
- 无分页建模;一个操作只从一个请求里提取一份数据;跨请求派生的参数(如先查 id 再取值)无法自动替换;
- 速率限制只在单进程内生效:多次独立 CLI 运行之间不做互限速;
- Chrome 配置被单进程锁定:MCP 服务空闲 3 秒后释放,其他进程最多等 15 秒;
- 规格是"可执行的请求/交互说明":请从可信来源安装,
readOnly声明并非针对恶意规格的沙箱,网站文本是数据、不是给 Agent 的指令。
此外,docs/PERFORMANCE-AUDIT.md 也坦承:凭证识别存在已记录的边界——未被识别、被拆分、深度编码或调用方自带的凭证,新加的"重叠引用"守卫并不能让它们绝对安全。
四、明确不做的事 vs 未来路线图 🗺️
DESIGN 文档列出了 v1 的 non-goals(刻意不做),这也是理解路线图的关键:
| 刻意不做(v1 non-goals) | 原因 / 权衡 |
|---|---|
| TLS 指纹伪装(impersonation) | 受保护站点会直接跳到 tier 2/3(更慢但可靠) |
| 验证码破解 | 交给真人清除,保持本地、诚实降级 |
| 签名重实现 | 站点自有请求由浏览器触发即可覆盖 |
| 托管注册中心 / 市场 | 定位为本地 MIT 工具,靠 sites/ 社区共享 |
| Windows 应用绑定 Cookie 解密 | 登录在该平台回退到 --window 手动登录 |
而 docs/research/prior-art.md 则梳理了从同类项目中值得补齐的机制,可视为下一步方向:
- 派生参数(provenance):把一个请求的值追溯回"它来自哪个更早的响应",从而支持 id 链式查询;
- 主动发现(discovery):不只为有人写 trigger 的操作学习,而是把捕获到的候选请求提升成操作;
- 更稳的反爬覆盖:识别更多厂商的人机挑战页并正确路由(升级 tier 而非误判为 drift);
- 受保护站点的更优传输层:在"纯 fetch"和"开浏览器"之间补一个更快的人为伪装档。
五、小结
API Anything 用一套"引用代替值 + 保存前强制扫描 + 本地权限与清理 + 写操作默认禁止"的组合拳,把密钥永不出本地从口号落成了工程约束;同时它用 v0.1 的坦诚标注了本地工具、无验证码破解、无托管 API 等真实边界。对新手而言,最实用的安全守则就三条:
- 凭证只放
~/.api-anything,规格文件随便分享; - 写操作永远显式
--allow-writes,并先确认回执; - 从可信来源安装 spec,把它当"可执行指令"而非普通文档。

