API参考大全:Antigravity Phone Connect 全部HTTP端点清单与curl请求示例
API参考大全:Antigravity Phone Connect 全部HTTP端点清单与curl请求示例
本文是 Antigravity Phone Connect 的完整 API参考:它把桌面端 Antigravity AI 会话实时镜像到手机,并提供远程发消息、停止生成、切换模型等能力。下面列出项目全部 HTTP 端点(如 /health、/snapshot、/send),逐一说明用途、请求参数,并附上可直接复制的 curl 请求示例,方便你用终端或脚本调用该服务。
💡 核心源码位于 server.js,所有路由都在这一个文件里;官方端点速查表见 CODE_DOCUMENTATION.md 的 "API Endpoints" 章节。
启动服务并确定 Base URL
所有端点都挂在同一个 Express 服务器上,默认端口 3000(可用环境变量 PORT 修改,定义见 server.js)。启动方式:
- Windows:双击 start_ag_phone_connect.bat
- macOS / Linux:执行 start_ag_phone_connect.sh
启动成功后终端会打印形如 http://192.168.1.5:3000 的地址(局域网 IP)。后文统一用 BASE_URL 指代它:
BASE_URL="http://192.168.1.5:3000"
认证规则很简单:同一局域网(LAN)内发起的请求自动免登录;只有走 ngrok / Cloudflare / Pinggy 隧道从外部访问时才需要密码登录。本地调试 curl 基本不用操心认证。
认证与会话管理:/login 与 /logout
| 端点 | 方法 | 请求体 | 说明 |
|---|---|---|---|
/login |
POST |
{"password": "..."} |
校验 .env 中的 APP_PASSWORD,成功后签发 30 天有效期的签名 httpOnly Cookie(ag_auth_token) |
/logout |
POST |
无 | 清除会话 Cookie |
curl 示例(外部访问场景,用 -c 保存 Cookie,后续请求用 -b 带上):
# 登录并保存会话 Cookie
curl -X POST "$BASE_URL/login" \
-H 'Content-Type: application/json' \
-d '{"password":"你的APP_PASSWORD"}' \
-c cookies.txt
# 之后调用任意端点时携带 Cookie
curl "$BASE_URL/snapshot" -b cookies.txt
# 退出登录
curl -X POST "$BASE_URL/logout" -b cookies.txt
状态检查端点:快速判断服务是否就绪
查看服务健康:/health(GET)
最常用的"服务活着吗"检查接口,返回 CDP 连接状态、运行时长与是否启用 HTTPS:
curl "$BASE_URL/health"
# {"status":"ok","cdpConnected":true,"uptime":123.45,"timestamp":"...","https":false}
⚠️ 若
cdpConnected为false,说明还没连上 Antigravity,请确认它已用调试模式启动:antigravity . --remote-debugging-port=9000
查看 HTTPS 证书状态:/ssl-status(GET)
curl "$BASE_URL/ssl-status"
# {"enabled":false,"certsExist":false,"message":"No certificates found"}
查看聊天窗口状态:/chat-status(GET)
判断桌面端是否有打开的会话、是否已有消息、输入框是否就绪:
curl "$BASE_URL/chat-status"
# {"hasChat":true,"hasMessages":true,"editorFound":true}
排查 CDP 连接:/cdp-targets(GET)
依次探测 9000~9003 四个调试端口上可发现的 CDP 目标,是排查"连不上 Antigravity"问题的第一站:
curl "$BASE_URL/cdp-targets"
实时镜像数据端点:/snapshot 与 /app-state
获取实时聊天快照:/snapshot(GET)
核心端点。服务端每秒轮询一次桌面会话,内容变化时更新缓存;调用时直接返回最新一份快照,包含清理后的 html、全量 css、滚动位置 scrollInfo 与统计信息 stats。首次启动尚未抓到内容时返回 503:
curl "$BASE_URL/snapshot" | head -c 300
# {"html":"<div id=\"conversation\">...","css":"...","scrollInfo":{"scrollPercent":0.02,...},"stats":{...}}
手机端页面就是靠它渲染镜像界面的,想验证"镜像是否正常",看这个端点最直接。
获取当前模式与模型:/app-state(GET)
返回桌面端当前的思考模式(Fast / Planning)和 AI 模型名:
curl "$BASE_URL/app-state"
# {"mode":"Planning","model":"Gemini 3 Flash"}
获取历史会话列表:/chat-history(GET)
自动点击桌面端历史按钮并抓取会话标题列表:
curl "$BASE_URL/chat-history"
# {"chats":[{"title":"...","index":0}, ...]}
远程控制端点:发消息、停止、新建会话
发送消息:/send(POST)
把一段文本注入桌面 Antigravity 输入框并自动提交。参数 message 必填(缺失返回 400)。该接口采用"乐观返回"——只要注入尝试完成即返回 success: true,客户端随后刷新快照确认:
curl -X POST "$BASE_URL/send" \
-H 'Content-Type: application/json' \
-d '{"message":"帮我总结当前改动"}'
# {"success":true,"method":"click_submit","details":{...}}
停止 AI 生成:/stop(POST)
点击桌面端取消按钮,中断当前生成:
curl -X POST "$BASE_URL/stop"
# {"success":true}
一键新建会话:/new-chat(POST)
等价于点击桌面右上角的 + 按钮:
curl -X POST "$BASE_URL/new-chat"
# {"success":true,"method":"data-tooltip-id"}
切换历史会话:/select-chat(POST)
参数 title 必填(来自 /chat-history 返回的标题,缺失返回 400):
curl -X POST "$BASE_URL/select-chat" \
-H 'Content-Type: application/json' \
-d '{"title":"修复登录bug"}'
关闭历史面板:/close-history(POST)
向桌面端派发一次 Escape 键事件,收起历史抽屉:
curl -X POST "$BASE_URL/close-history"
精确控制端点:点击、滚动、模式与模型切换
远程点击元素:/remote-click(POST)
三个可选参数配合定位目标:selector(CSS 选择器)、index(第几个匹配项)、textContent(按文字过滤)。内置"叶子节点过滤",保证点中的是最内层精确按钮:
curl -X POST "$BASE_URL/remote-click" \
-H 'Content-Type: application/json' \
-d '{"selector":"button","index":0,"textContent":"Run"}'
远程滚动同步:/remote-scroll(POST)
把手机滚动位置同步到桌面,scrollPercent(0~1,推荐)或 scrollTop 二选一:
curl -X POST "$BASE_URL/remote-scroll" \
-H 'Content-Type: application/json' \
-d '{"scrollPercent":0.5}'
切换思考模式:/set-mode(POST)
mode 只接受 Fast 或 Planning:
curl -X POST "$BASE_URL/set-mode" \
-H 'Content-Type: application/json' \
-d '{"mode":"Planning"}'
# {"success":true}
切换 AI 模型:/set-model(POST)
model 传下拉列表中的名称,如 Claude Sonnet 4.5,脚本会自动打开选择器并完成点击:
curl -X POST "$BASE_URL/set-model" \
-H 'Content-Type: application/json' \
-d '{"model":"Claude Sonnet 4.5"}'
# {"success":true}
SSL 与调试端点
生成 SSL 证书:/generate-ssl(POST)
等价于执行 generate_ssl.js,在 certs/ 目录生成自签名证书,需重启服务后生效:
curl -X POST "$BASE_URL/generate-ssl"
# {"success":true,"message":"SSL certificates generated! Restart the server to enable HTTPS."}
调试 UI 结构:/debug-ui(GET)与 /ui-inspect(GET)
/debug-ui 返回序列化的 UI 树文本;/ui-inspect 返回页面所有可见按钮、图标的坐标、aria-label、svg 类等详细元数据(实现见 ui_inspector.js),开发或适配新版 Antigravity 界面时非常有用:
curl "$BASE_URL/ui-inspect"
# {"summary":{...},"frames":[...],"contexts":[...],"usefulButtons":[...],"bestContextData":{...}}
全部 HTTP 端点清单(速查表)
| # | 方法 | 端点 | 关键参数 | 作用 |
|---|---|---|---|---|
| 1 | POST |
/login |
password |
密码登录,签发会话 Cookie |
| 2 | POST |
/logout |
— | 退出登录 |
| 3 | GET |
/health |
— | 服务状态与 CDP 连接检查 |
| 4 | GET |
/snapshot |
— | 最新聊天快照(html/css/滚动) |
| 5 | GET |
/ssl-status |
— | HTTPS 与证书状态 |
| 6 | POST |
/generate-ssl |
— | 生成自签名证书 |
| 7 | GET |
/app-state |
— | 当前模式与模型 |
| 8 | GET |
/chat-status |
— | 会话/消息/输入框状态 |
| 9 | GET |
/chat-history |
— | 历史会话标题列表 |
| 10 | POST |
/send |
message |
向 AI 发送消息 |
| 11 | POST |
/stop |
— | 停止当前生成 |
| 12 | POST |
/new-chat |
— | 新建会话 |
| 13 | POST |
/select-chat |
title |
切换到指定历史会话 |
| 14 | POST |
/close-history |
— | 关闭历史面板 |
| 15 | POST |
/remote-click |
selector、index、textContent |
远程精确点击 |
| 16 | POST |
/remote-scroll |
scrollPercent / scrollTop |
远程滚动同步 |
| 17 | POST |
/set-mode |
mode |
切换 Fast / Planning |
| 18 | POST |
/set-model |
model |
切换 AI 模型 |
| 19 | GET |
/debug-ui |
— | 序列化 UI 树(调试) |
| 20 | GET |
/ui-inspect |
— | 按钮/图标元数据(开发) |
| 21 | GET |
/cdp-targets |
— | 探测 9000~9003 调试端口 |
另外,服务器在同一端口上还运行 WebSocket 服务(ws:// 或 HTTPS 下的 wss://),快照更新时向所有已认证客户端推送 snapshot_update 通知——这是手机页面能秒级刷新的关键。
常见 HTTP 状态码与排查
| 状态码 | 含义 | 处理建议 |
|---|---|---|
401 |
Unauthorized | 外部访问未登录:先调 /login,或用带 ?key=密码 的 Magic Link |
400 |
Bad Request | 缺少必填参数(message 或 title) |
503 |
Service Unavailable | CDP 未连接或快照尚未生成:确认 Antigravity 以 --remote-debugging-port=9000 启动且已有打开的会话 |
相关文件索引
- 路由与端点实现:server.js
- 官方端点表与数据流说明:CODE_DOCUMENTATION.md
- 快速上手与隧道配置:README.md
- 隧道与进程管理:launcher.py
- 安全模型与 HTTPS 说明:SECURITY.md



