打造 Agent 友好的 SaaS 模板：API Key 与 CLI 鉴权为什么要一开始就做好

今天再谈一个现代 SaaS 模板，已经不能只盯着浏览器页面、支付和后台管理。越来越多团队希望同一套产品既能服务人类用户，也能服务脚本、内部自动化，以及 OpenClaw、Codex、Claude Code 这类 agent 工作流。

这会直接改变“生产就绪”这四个字的含义。

为什么 Agent 友好很重要

如果一个 starter 只支持浏览器 session，那么所有脚本和本地工具最后都会走向一些别扭方案：

• 复用浏览器 cookie
• 事后再补一套平行鉴权层
• 直接硬编码长期密钥而没有管理入口
• 产品上线后再仓促补 CLI 能力

Agent 友好的 SaaS 模板应该从一开始就把机器访问当成一等公民，而不是补丁。

一套够用而不过度的机器鉴权基线

对这个 starter 来说，合理的最小组合是：

• 给人类用户的 Web session
• 给脚本和集成的 API Key
• 给本地 CLI 的浏览器批准 device login
• 给 CLI 会话的 refresh token rotation
• 给用户查看和撤销已授权设备的设置页入口

这套组合不复杂，但已经覆盖了大多数真实开发工作流。

为什么不能直接复用浏览器 session

浏览器 session 很适合做一件事：给交互式 Web 用户登录。

但它并不适合：

• 无头脚本
• 本地 CLI 工具
• 后台任务
• Agent 驱动工作流

把机器认证单独抽出来，安全边界会更清晰，后续做审计、撤销和轮换也更自然。

这个模板现在重点强调什么

目前这个 starter 会把下面这些能力作为一级卖点来表达：

• 按用户创建和管理 API Key
• 版本化的 /api/v1/* 机器接口
• 通过 saas-cli 发起的 CLI device auth
• 在独立的 Developer Access 工作区中查看已授权 CLI 会话
• 覆盖 API Key 和 device auth 的冒烟测试

这会让模板对“既有用户界面、又需要可编程访问”的产品更有价值。

结论

Agent 友好的 SaaS 模板，并不意味着你非要把产品包装成一个“AI 平台”。

真正重要的是承认一个现实：

现代 SaaS 产品，天然同时服务人类和机器。

如果 starter 从第一天就把这件事处理好，后面的很多设计都会更轻松。