应用解锁期间，Agilelogin 会在这台电脑上运行一个小的 HTTP API。脚本从两个文件读出端口和会话 token，请求 API 启动一个 Profile，再通过 Chrome DevTools Protocol（CDP）接上它拉起的浏览器；本文讲这条路径，以及这个 API 不做的事。
适用范围： launcher 0.1.0，API 版本 v1。完整的 API 参考在首发后发布；在那之前，只使用本文给出的调用。
服务在哪里？
- API 只监听
127.0.0.1，端口由操作系统在每次服务启动时随机分配。没有远程访问，也没有任何设置能把它绑到别的地址。 - 服务启动时会往应用数据目录写两个文件，脚本每次连接前都要重新读：
api_port：纯文本的端口号。api_token：64 个十六进制字符的会话 token，每次启动都重新生成。Windows 上依赖%APPDATA%的默认用户权限；macOS 上该文件只有你的用户可读。
- 数据目录：Windows 为
%APPDATA%\com.agilelogin.app\，macOS 为~/Library/Application Support/com.agilelogin.app/。 - 锁定应用（手动锁定，或 15 分钟无操作自动锁定）会停掉服务并删除这两个文件。此时脚本看到的是连接被拒绝，不是
401。解锁后服务重新启动，端口和 token 都是新的，所以不要缓存它们。 - 除
GET /api/v1/status外，所有路由都需要请求头Authorization: Bearer <api_token 文件内容>。缺少或错误的 token 返回401，响应体形如{ "error": { "kind": "unauthorized", "message": "…" } }。 - 所有路径以
/api/v1开头。请求和响应字段一律 camelCase。
最小流程
- 从数据目录读出
api_port和api_token。 - 带 Bearer 头调用
POST /api/v1/profiles/{id}/start。200响应里有cdpReady和cdpEndpoint，形如ws://127.0.0.1:<port>/devtools/browser/<guid>。 - 接上：
puppeteer.connect({ browserWSEndpoint: cdpEndpoint })或playwright.chromium.connectOverCDP(cdpEndpoint)。 GET /api/v1/profiles/{id}/status返回status（idle、running或error）和当前的cdpEndpoint；浏览器没在运行时为null。POST /api/v1/profiles/{id}/stop关闭浏览器。
这条流程依赖的几件事：
cdpEndpoint是内核自己报出来的地址，端口每次启动都不同。从响应里读，不要自己拼。start可能返回200但cdpReady: false、cdpEndpoint: null：浏览器起来了，CDP 在大约十秒内没就绪。连接前先检查cdpReady。GET /api/v1/profiles/{id}返回的 Profile 对象不含cdpEndpoint，要从status拿。- 这个 API 没有事件推送，也没有 WebSocket。状态变化靠轮询
status。你用到的唯一一条 WebSocket 是内核的 CDP，不属于这个 API。 - 对已在运行的 Profile 再次
start返回422，消息为Profile is already running。 - 启用启动安全锁时，如果同一个 Profile 正在另一台登录了同一账号的设备上打开，
start可能返回409，消息以机器可解析的前缀PROFILE_IN_USE_ELSEWHERE:开头。启动安全锁是协商性的：它协调守规矩的客户端，不是访问控制；拿不到租约的客户端（比如断网时）照样能启动。 GET /api/v1/status不需要 token，返回应用版本和apiVersion，可以当健康检查用。
API 还覆盖什么
本版本已稳定、完整请求形状在首发后的参考里给出的部分：
- Profile： 列出、创建、读取、修改、删除，批量删除，按状态计数，启动、停止、查状态。
- 代理： 列出、创建、批量创建、修改、删除，以及对单个代理做连通性和出口 IP 检测。
- Cookie（挂在 Profile 下）： 读概要、清空、导入（Netscape、JSON 或 EditThisCookie）、导出、复制到另一个 Profile。
- 分组： 列出、创建、删除。
- 扩展： 列出和删除已导入的扩展，从本机路径导入（crx、zip 或解包目录），读取或设置某个 Profile 加载哪些扩展。
- 账号： 读账号状态，注册，登录和登出，列出和踢除设备会话，发忘记密码邮件，重发验证邮件，设置密码。登录响应不含 access 或 refresh token。Google 或 GitHub 社交登录不走 API：它需要有人在键盘前点授权，只在应用窗口里有入口。
本版本已存在、但首发后形状可能变化、因此这里只列名不给用法的部分：内核状态，批量导入导出（异步，有操作可轮询或取消），把 Profile 迁到另一个内核版本，重置某个 Profile 的登录状态，克隆机检查，应用自用的 license 端点，以及做镜像前的制备。
错误
- 响应体为
{ "error": { "kind": "<snake_case>", "message": "<English sentence>" } }，状态码按类别：400、403、404、409、422、500、502。 - 请求在到达路由前就被框架拒绝时（比如 JSON 解析失败），返回的是纯文本
422，不是上面的形状。 - 消息一律英文，不本地化。错误体的字段首发后可能变。
一个 token 能做什么
读到 api_token 的本地进程，就能以这台电脑的身份做这个 API 能做的一切：导入导出 cookie、启停浏览器、替这台电脑登录或登出账号。边界是这个文件只有当前操作系统用户可读。没有按脚本的权限划分，也没有只读 token。登录响应不透传 access 或 refresh token，所以进程能替这台电脑操作，但不能把凭据带走。
不提供的
- 没有远程访问：服务只监听
127.0.0.1，没有任何东西能改这一点。 - 没有云端 API：这个 API 只存在于装了应用的那台电脑上。账号服务不向第三方开放接口。
- 这个 API 没有事件推送，也没有 WebSocket。
关于 API 的问题请发到 support@agilelogin.com。