Antigravity-Manager HTTP API 参考指南8045 端口统一网关的鉴权、管理接口与 AI 协议兼容详解【免费下载链接】Antigravity-ManagerProfessional Antigravity Account Manager Switcher. One-click seamless account switching for Antigravity Tools. Built with Tauri v2 React (Rust).专业的 Antigravity 账号管理与切换工具。为 Antigravity 提供一键无缝账号切换功能。项目地址: https://gitcode.com/gh_mirrors/an/Antigravity-Manager本指南以 Antigravity-ManagerAntigravity Toolsv4.3.0 的 HTTP API 为对象完整梳理统一端口8045上的双重角色服务器面向 AI 客户端的 OpenAI / Anthropic / Google 协议兼容接口以及面向账号、配置与监控的管理后台接口。读完本文你将掌握两种接口的鉴权方式、全部管理端点的请求语义与参数示例并能结合仓库源码理解切换账号、热更新模型映射、Token 统计等能力的底层实现链路。1. 概览一个端口双重角色Antigravity Gateway即本项目内置的反代与管理服务器在同一进程、同一端口上同时扮演两个角色AI Proxy Interface兼容 OpenAI / Anthropic / Google 官方 SDK 的标准接口AI 客户端Claude Code、Cursor、Cherry Studio、Codex CLI 等可以直接把 Base URL 指向本服务。Management Admin API用于管理账号、配置系统、监控流量的 RESTful 接口供管理后台Tauri 前端或脚本化控制使用。版本注意自 v4.0.1 起所有服务包括 AI 反代与系统管理均已整合至统一端口8045原有的 19527 端口已废弃。这一点在源码中也有体现旧版独立的 HTTP API 模块 modules/http_api.rs 仍保留DEFAULT_PORT: u16 19527常量且注明当前未在主流程中启用而当前主流程的服务器由 proxy/server.rs 承载通过bind_tcp_listener(host, port)监听统一端口其中port默认即 8045。1.1 鉴权体系Authentication两种接口采用完全不同的鉴权路径接口类型路径前缀鉴权方式Header 示例说明AI Protocol/v1/*,/v1beta/*API KeyAuthorization: Bearer API_KEY用于 AI 客户端调用Admin API/api/*Admin Tokenx-admin-token: TOKEN用于管理后台或脚本控制提示默认情况下Admin Token与API Key是同一个值即您在.env或 Docker 环境变量中设置的API_KEY。从源码实现看管理接口的鉴权中间件admin_auth_middleware定义于 proxy/middleware/auth.rs为强制严格鉴权模式除/health、/healthz、/api/health等健康检查端点保持公开外其余/api/*请求一律要求凭证。凭证的解析兼容多种标准 HeaderAuthorization: Bearer token、x-api-key、x-goog-api-key并优先使用独立的admin_password若未设置则回退到api_key进行比对若admin_password已配置管理接口使用admin_password校验若未配置则回退使用api_key即文档所述的默认 Admin Token 与 API Key 相同若两者均为空中间件将直接拒绝请求并返回 401。同时ProxyAuthMode见 proxy/config.rs 中的枚举Off/Strict/AllExceptHealth/Auto控制 AI 代理接口的鉴权策略Off模式下请求直接放行但仍会尝试识别 User Token 以便记录用量AllExceptHealth模式仅豁免健康检查Strict模式则对 AI 接口也强制校验 API Key。2. 管理接口Management APIBase URLhttp://host:8045/api所有管理端点均挂在/api前缀之下源码中通过Router::new().nest(/api, admin_routes)注册见 proxy/server.rs。在应用管理鉴权层之前还叠加了monitor_middleware、auth_middleware、ip_filter_middleware、service_status_middleware与cors_layer等全局中间件请求体大小默认限制为 100MB可通过环境变量ABV_MAX_BODY_SIZE调整源码中std::env::var(ABV_MAX_BODY_SIZE)解析失败时回退100 * 1024 * 1024。2.1 账号管理Account Management方法路径说明参数示例GET/accounts获取账号列表-GET/accounts/current获取当前活跃账号-POST/accounts添加账号 (OAuth Refresh Token){refreshToken: ...}DELETE/accounts/:id删除账号-POST/accounts/switch切换活跃账号{accountId: acc_123, targetIde: agy}(targetIde 可选如传agy则仅写入凭据免重启 IDE)POST/accounts/refresh刷新所有账号配额-GET/accounts/:id/quota查询特定账号配额-POST/accounts/:id/toggle-proxy禁用/启用账号代理-POST/accounts/:id/bind-device绑定设备指纹{mode: generate}POST/accounts/bulk-delete批量删除账号{accountIds: [id1, id2]}POST/accounts/reorder账号排序{accountIds: [...]}切换账号的底层实现源码admin_switch_account见 proxy/server.rs 的 handler切换采用互斥保护若已有切换任务在执行新请求直接返回409 ConflictAnother switch operation is already in progress防止并发切换导致状态错乱请求结构体SwitchRequest包含account_id与可选的target_ide两个字段对应文档中的targetIde语义。仓库测试用例test_switch_request_deserialization_with_and_without_target_ide明确验证了传agy时target_ide被正确解析切换成功后服务会立即清理内存会话缓存token_manager.clear_all_sessions()并重新加载账号token_manager.load_accounts()确保新账号凭据立即对后续 AI 请求生效对应 Issue #1166 的修复。账号列表的返回结构GET /accounts返回{ accounts: [...], current_account_id }每个账号对象包含id、email、name、is_current、disabled、disabled_reason、disabled_at、proxy_disabled、protected_models、live_limited_models、quota含models、last_updated、subscription_tier、is_forbidden、quota_groups、device_bound、last_used以及 403 验证阻止状态validation_blocked等字段序列化逻辑见 proxy/server.rs 的to_account_response。2.2 系统配置System Config方法路径说明GET/config获取全量配置POST/config保存全量配置GET/proxy/status获取反代服务运行状态POST/proxy/start启动反代服务POST/proxy/stop停止反代服务POST/proxy/mapping更新模型映射规则GET/health系统健康检查模型映射的热更新原理POST /proxy/mapping对应admin_update_model_mapping它写入AxumServer.custom_mapping一个ArcRwLockHashMapString, String从而实现对模型映射规则的全量热更新无需重启服务update_mapping注释明确为模型映射 (Custom) 已全量热更新。类似地反代上游代理、代理池、安全配置、z.ai 配置、实验性配置等也都有对应的热更新方法update_proxy、update_proxy_pool、update_security、update_zai、update_experimental、update_debug_logging、update_user_agentPOST /config保存配置后这些状态会同步刷新。2.3 监控与统计Monitoring Stats流量日志GET/logs获取日志列表支持limit,offset,filter,errorsOnly参数GET/logs/count获取日志总数GET/logs/:id获取日志详情POST/logs/clear清空日志日志数据来自反代监控模块ProxyRequestLogGET /logs返回{ total, logs }结构limit缺省时默认取 50filter与errorsOnly会下推到数据库层做过滤统计对应proxy_db::get_logs_filtered与get_logs_count_filtered。Token 统计v4.0.1 NewGET/stats/token/summary获取 Token 消耗摘要今日/本周/总量GET/stats/token/hourly获取按小时统计数据GET/stats/token/daily获取按日统计数据GET/stats/token/by-account按账号统计消耗占比GET/stats/token/by-model按模型统计消耗占比POST/stats/token/clear重置统计数据在源码路由表中Token 统计接口还扩展了weekly、model-trend/hourly、model-trend/daily、account-trend/hourly、account-trend/daily等更细粒度的维度数据由token_stats模块modules/token_stats.rs提供可用于监控面板的趋势图与占比图。2.4 高级功能AdvancedPOST/proxy/cli/sync执行 CLIClaude/Codex配置文件同步POST/accounts/import/db从 v1 旧数据库导入账号POST/accounts/oauth/start发起 OAuth 授权流程 (Headless)POST/proxy/cloudflared/start启动 Cloudflare Tunnel围绕这些高级功能源码路由还提供了更完整的能力矩阵均可通过/api前缀访问CLI 同步族/proxy/cli/status、/proxy/cli/restore、/proxy/cli/configOpenCode 同步族/proxy/opencode/*status/sync/openai-sync/restore/clear/config/familiesDroid 同步族/proxy/droid/*status/sync/restore/config。对应实现见 cli_sync.rs、opencode_sync.rs、droid_sync.rs。OAuth 流程/accounts/oauth/prepare、/accounts/oauth/complete、/accounts/oauth/cancel、/accounts/oauth/submit-code、/accounts/oauth/clients等支撑 Headless 环境下的授权登录对应模块 modules/oauth.rs 与 modules/oauth_server.rs。设备指纹管理/accounts/:accountId/bind-device、/accounts/:accountId/device-profiles、/accounts/:accountId/device-versions、/accounts/device-preview、/accounts/restore-original及版本恢复/删除端点绑定结果返回machine_id、mac_machine_id、dev_device_id、sqm_id四元组。代理池管理/proxy/pool/config、/proxy/pool/bindings、/proxy/pool/bind、/proxy/pool/unbind、/proxy/pool/binding/:accountId以及/proxy/health-check/trigger手动触发健康检查。安全与 IP 监控/security/logs、/security/stats、/security/blacklist增删查、/security/whitelist、/security/config等配合 middleware/ip_filter.rs 实现请求级 IP 过滤。用户令牌User Token/user-tokens列表/创建、/user-tokens/summary、/user-tokens/:id/renew、/user-tokens/:id删除/更新用于多用户场景的令牌发放与用量追踪。系统管理/system/data-dir、/system/updates/*、/system/autostart/*、/system/http-api/settings、/system/antigravity/path、/system/cache/clear等。反代辅助/proxy/api-key/generate、/proxy/rate-limits清空限流状态、/proxy/preferred-account、/proxy/monitor/toggle、/proxy/stats。2.5 管理接口调用示例# 获取账号列表 curl -H x-admin-token: TOKEN http://127.0.0.1:8045/api/accounts # 获取当前活跃账号 curl -H x-admin-token: TOKEN http://127.0.0.1:8045/api/accounts/current # 切换账号targetIde 可选传 agy 时仅写入凭据、免重启 IDE curl -X POST http://127.0.0.1:8045/api/accounts/switch \ -H x-admin-token: TOKEN \ -H Content-Type: application/json \ -d {accountId: acc_123, targetIde: agy} # 刷新所有账号配额 curl -X POST http://127.0.0.1:8045/api/accounts/refresh \ -H x-admin-token: TOKEN # 查询指定账号配额 curl -H x-admin-token: TOKEN http://127.0.0.1:8045/api/accounts/acc_123/quota # 热更新模型映射规则 curl -X POST http://127.0.0.1:8045/api/proxy/mapping \ -H x-admin-token: TOKEN \ -H Content-Type: application/json \ -d {custom_mapping: {gpt-4o: claude-sonnet-4}} # 获取 Token 消耗摘要 curl -H x-admin-token: TOKEN http://127.0.0.1:8045/api/stats/token/summary # 健康检查无需鉴权 curl http://127.0.0.1:8045/api/health说明以上示例使用文档约定的x-admin-tokenHeader从 middleware/auth.rs 的实现看管理接口同样接受Authorization: Bearer token、x-api-key、x-goog-api-key等标准 Header 携带同一凭证实际接入时可按客户端习惯选用。3. AI 协议接口AI Protocol InterfaceBase URLhttp://host:8045本服务完全兼容主流 AI 厂商的官方协议规范可以直接将本服务地址填入支持 OpenAI / Claude 的客户端中。源码中 AI 路由与/api管理路由在同一个 Axum 应用中注册Router::new().nest(/api, admin_routes).merge(proxy_routes)并按照洋葱模型依次经过ip_filter - auth - monitor中间件再进入各协议处理器。3.1 OpenAI Compatible对话生成Chat CompletionsPOST/v1/chat/completions支持模型任何映射后的模型 ID如gpt-4o、gemini-1.5-pro兼容性完全兼容 OpenAI 官方 Response 格式包括流式 SSE处理器为handlers::openai::handle_chat_completions见 proxy/handlers/openai.rs底层通过 mappers/openai 系列完成请求/响应转换、流式转发与思维链恢复。图片生成Image GenerationPOST/v1/images/generations支持模型gemini-3-pro-image自动映射到 Imagen 3参数扩展支持size: 1920x1080、quality: hd等高级参数同族端点还包括/v1/images/edits图像编辑与/v1/audio/transcriptions音频转录分别由handlers::openai::handle_images_edits与handlers::audio::handle_audio_transcription处理。此外为兼容 Codex CLI 等客户端还注册了/v1/responsesPOST 与 WebSocket GET、/responses、/responses/compact、/v1/completions等端点/v1/models用于列出可用模型。3.2 Anthropic CompatibleClaude MessagesPOST/v1/messages用途支持 Claude CLIclaude、Cursor、Cherry Studio 等客户端特性完整支持 Tool Use工具调用和 Thinking思维链模式处理器为handlers::claude::handle_messages见 proxy/handlers/claude.rs配套端点还包括/v1/messages/count_tokensToken 计数与/v1/models/claude模型列表。Tool Use / Thinking 的映射细节位于 mappers/claude 目录request/response/streaming/thinking_utils 等。3.3 Gemini NativeGoogle AI StudioGET/POST/v1beta/models/*用途供使用 Google 官方 SDKPython/Node.js的应用调用路由注册于 proxy/server.rs/v1beta/models列表、/v1beta/models/:modelGET 取模型信息、POST 执行generateContent、/v1beta/models/:model/countTokens处理器见 proxy/handlers/gemini.rs 与 proxy/mappers/gemini 的封装层。3.4 其他协议辅助端点POST/v1/models/detect模型自动探测handlers::common::handle_detect_modelPOST/internal/warmup内部预热端点handlers::warmup::handle_warmup豁免鉴权POST/v1/thinking/end、GET/DELETE /v1/thinking/sessions/:session_id思维链会话的结束、统计与删除handlers/thinking.rsMCP 反代/mcp/web_search_prime/mcp、/mcp/web_reader/mcp、/mcp/zai-mcp-server/mcphandlers/mcp.rs支持将 z.ai 系列 MCP 服务通过本网关反代。3.5 AI 接口调用示例# OpenAI 兼容Chat Completions流式 curl http://127.0.0.1:8045/v1/chat/completions \ -H Authorization: Bearer API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: Hello}], stream: true } # Anthropic 兼容Claude Messages curl http://127.0.0.1:8045/v1/messages \ -H Authorization: Bearer API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4, max_tokens: 1024, messages: [{role: user, content: Hello}] } # 图片生成映射到 Imagen 3 curl http://127.0.0.1:8045/v1/images/generations \ -H Authorization: Bearer API_KEY \ -H Content-Type: application/json \ -d { model: gemini-3-pro-image, prompt: a mountain lake at sunset, size: 1920x1080, quality: hd } # Gemini NativegenerateContent curl http://127.0.0.1:8045/v1beta/models/gemini-1.5-pro:generateContent \ -H Authorization: Bearer API_KEY \ -H Content-Type: application/json \ -d {contents: [{parts: [{text: Hello}]}]}4. 从源码理解请求处理链路将文档中的接口清单与 proxy/server.rs 的路由注册对照可以总结出如下处理链路入口层所有请求先经过service_status_middleware服务状态与cors_layerCORS允许本地任意来源调用再按路径分发到/api管理路由或 AI 代理路由IP 过滤层ip_filter_middleware根据安全配置中的黑名单/白名单决定是否放行middleware/ip_filter.rs鉴权层auth_middlewareAI 接口遵循auth_mode或admin_auth_middleware管理接口强制严格校验执行凭证校验并通过UserTokenIdentity扩展注入用户身份监控层monitor_middleware记录请求/响应、采集 Token 用量在鉴权之后执行才能拿到用户身份业务层各协议处理器handlers完成协议转换经由上游客户端proxy/upstream/client.rs转发到真实厂商并将响应按原协议格式返回。其中账号切换、配额刷新等管理操作还会联动TokenManagerproxy/token_manager.rs与AccountServicemodules/account_service.rs切换后清空会话、重载账号缓存配额更新后通过全局待重载队列PENDING_RELOAD_ACCOUNTS通知TokenManager在下次取 Token 时刷新账号删除则进入PENDING_DELETE_ACCOUNTS队列清理内存缓存。5. 实践建议与注意事项端口确认统一端口为 8045若您在旧版本上配置过 19527请同步更新客户端 Base URL 与环境变量。凭证安全管理接口具备完整的状态控制能力删号、改配置、清日志建议在部署时设置独立的admin_password未设置时务必保管好API_KEY因为它同时是 Admin Token 与 AI 接口密钥。健康检查/health、/healthz、/api/health无需鉴权适合接入 Docker Compose 或系统监控的探针docker-compose.yml 中 healthcheck 可复用该端点。模型映射POST /api/proxy/mapping支持运行时热更新无需重启进程即可调整gpt-4o - claude-sonnet-4之类的映射关系更完整的映射逻辑可参考 docs/model-remapping-logic.md。并发切换保护账号切换接口在并发时会返回 409客户端脚本应做好重试或串行化。限流与安全反代内置 Rate Limitproxy/rate_limit.rs与 IP 安全策略管理接口可随时通过/api/proxy/rate-limits清空限流状态避免误伤。本参考与仓库当前实现保持一致如需在本地验证接口行为可通过 docker/Dockerfile 构建镜像后以 8045 端口运行或直接运行桌面版Tauri应用后访问http://127.0.0.1:8045。【免费下载链接】Antigravity-ManagerProfessional Antigravity Account Manager Switcher. One-click seamless account switching for Antigravity Tools. Built with Tauri v2 React (Rust).专业的 Antigravity 账号管理与切换工具。为 Antigravity 提供一键无缝账号切换功能。项目地址: https://gitcode.com/gh_mirrors/an/Antigravity-Manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考