Skip to content

About

Local Anthropic and OpenAI compatible gateway backed by the official Antigravity CLI.

Resources

Readme
MIT license
Activity

Stars

20 stars

Watchers

0 watching

Forks

8 forks
Report repository
BranchesTags

Repository files navigation

Antigravity Gateway

中文 · English

中文

Antigravity Gateway 是一个本地 Anthropic/OpenAI 兼容网关。它复用官方 Antigravity CLI（agy）的登录状态，让 Claude Code、Codex CLI、Trae 及其他兼容客户端通过本地接口调用当前账号可用的模型。

默认使用原生 Cloud Code 直连，不经过 agy Agent 的包装提示词。客户端选择什么模型，网关就把该模型 ID 原样发送给上游；只有 Claude Code Auto Mode 的分类请求使用独立的快速模型。

非 Google 官方项目，仅用于学习、兼容性研究与个人测试。模型权限、额度、地区限制和服务条款均以上游为准。

当前版本：v1.2.0。详细更新记录见 CHANGELOG.md。

主要功能

  • 同时提供 Anthropic Messages、OpenAI Responses 和 Chat Completions 接口。
  • 支持 Claude Code、Codex CLI、Trae 和其他兼容客户端。
  • 支持前台运行，以及 macOS、Linux、Windows 后台保活和开机自启。
  • 支持自动导入本地 agy 账号，也可以输入 add 手动添加账号。
  • 多账号之间轮询；同一会话保持账号一致，限流、认证或额度异常时自动尝试其他账号。
  • 启动界面显示账号状态、历史用量、Token、缓存命中率和最近24小时图表。
  • 支持客户端工具调用、SSE、Claude Code Auto Mode 和结构化输出。
  • 支持图片生成、参考图编辑，以及图片、视频、音频、PDF 和普通文件理解。
  • 支持 OpenAI Images/Files 接口，并让远程客户端先上传文件再在对话中引用。

使用条件

条件 说明
Node.js 20 或更高版本；npm 随 Node.js 一起安装
Antigravity CLI 已安装 agy，并至少完成一次登录和正常对话
操作系统 macOS、Linux 或 Windows，ARM64/x64
网络 当前电脑能够正常访问 Antigravity/Google 上游服务

安装器会自动检查 Node.js 版本、操作系统、CPU 架构和临时目录，并由 npm 处理项目依赖。agy 及其登录账号是使用前提，不由本项目自动安装或注册。

没有 Node.js 时，可使用以下任一方式安装：

macOS（Homebrew）：

brew install node

macOS/Linux（nvm）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 24

Windows PowerShell：

winget install --exact --id OpenJS.NodeJS.LTS

也可以从 Node.js 官方网站 安装 LTS 版本。

安装

一条命令全局安装，不需要克隆仓库，也不需要进入项目目录：

npm install --global --foreground-scripts --allow-scripts=antigravity-gateway https://github.com/LeeFeee/antigravity-gateway/archive/refs/heads/main.tar.gz

验证版本：

antigravity-gateway --version

部分 npm 11 版本会提示 install scripts not yet covered by allowScripts。如果最后显示 changed 1 package 且命令可以运行，说明安装已经完成；该提示不是网关运行错误。

启动

前台模式：

antigravity-gateway

默认监听：

Anthropic: http://127.0.0.1:9897
OpenAI:    http://127.0.0.1:9897/v1
API Key:  antigravity-gateway（网关未设置专用 Key 时可使用任意非空内容）

关闭终端或按 Ctrl+C 会停止前台网关。

后台保活并设置自动启动：

antigravity-gateway service start

管理后台服务：

antigravity-gateway service status
antigravity-gateway service restart
antigravity-gateway service stop
antigravity-gateway service logs
antigravity-gateway service uninstall

重复执行 service start 会更新配置并重启现有服务，不会创建重复服务。后台模式没有交互输入框；需要添加账号时，先停止后台服务并以前台模式启动，添加完成后再执行 service start。

打开 Token 用量看板：

antigravity-gateway stats

网关启动后，无论使用前台模式还是后台保活模式，都可以另开一个终端执行这条命令。看板复用网关现有的 9897 端口，不会启动第二个后台服务；也可以直接访问 http://127.0.0.1:9897/dashboard。

如果 agy 不在默认位置：

antigravity-gateway --agy-path "/absolute/path/to/agy"

Windows：

antigravity-gateway --agy-path "C:\path\to\agy.exe"

账号池

网关启动时会检测当前官方 agy 登录账号：

  • 账号池中没有该账号：自动保存到账号池并立即参与请求。
  • 已存在同一账号：不重复添加，也不使用本地登录态反复覆盖已保存凭据。
  • 账号池非空后：请求以账号池凭据为主。

手动添加其他账号：启动前台网关，在 gateway> 后输入：

add

网关会尝试打开浏览器，同时在终端显示完整授权链接。浏览器没有自动打开时，复制链接到浏览器完成授权。远程服务器无法访问 localhost 回调页时，把浏览器地址栏里的完整回调 URL 粘贴回 gateway>。

查看账号池：

acc

新会话会在可用账号之间轮询，同一会话尽量保持在同一账号。终端会为每次上游尝试打印实际账号：

[Antigravity Gateway] 路由账号=user@example.com source=managed-account model=gemini-3.8-flash-high attempt=1

账号文件保存在：

~/.antigravity-gateway/accounts/

账号池凭据以普通 JSON 保存，Token 刷新后会同步更新。请自行管理本机文件和账号使用风险。

前台终端命令

命令 作用
add 添加 Antigravity 账号
acc 查看账号池和账号状态
models 查看当前发现的模型
status 重新显示网关和统计状态
usage 查看实时详细用量
stats 在默认浏览器打开 Token 用量看板
reload 重新加载账号与额度信息
config 查看客户端连接配置
logs 查看日志说明或位置
clear 清理当前终端显示
version 查看网关版本
help 查看命令帮助
quit 保存状态并关闭网关

额度查询在后台异步进行。启动画面中的 1/1 额度可用 表示当时成功取得了一个有效额度快照，并不代表其他账号一定没有额度；等待几秒后输入 status 可重新显示当前结果。

接入 Claude Code

在 ~/.claude/settings.json 的 env 中配置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:9897",
    "ANTHROPIC_AUTH_TOKEN": "antigravity-gateway",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6-thinking",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-3.8-flash-low",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1048576"
  }
}

启动 Claude Code：

claude --model 'gemini-3.8-flash-high[1m]'

网关会生成包含当前真实模型的 Claude Code modelPicker 文件：

macOS/Linux：

claude --settings "$(antigravity-gateway --claude-config-path)"

Windows PowerShell：

claude --settings (antigravity-gateway --claude-config-path)

也可以执行下面的命令，把输出的 modelPicker 合并进自己的 ~/.claude/settings.json：

antigravity-gateway --claude-config

注意：

  • 使用本地网关时，不要同时启用 CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX 或 CLAUDE_CODE_USE_FOUNDRY。
  • Gemini 3.7/3.8 Flash 的上游目录当前返回 1,048,576 输入 Token；[1m] 或 CLAUDE_CODE_MAX_CONTEXT_TOKENS=1048576 用于告诉 Claude Code 使用真实窗口。
  • 正常请求使用客户端指定的模型。Auto Mode 分类请求单独使用快速模型，不改变主会话模型。

接入 Codex CLI

先取得动态模型目录路径：

antigravity-gateway --codex-catalog-path

在 ~/.codex/config.toml 中配置：

model = "gemini-3.8-flash-high"
model_provider = "antigravity"
model_catalog_json = "/ABSOLUTE/PATH/.antigravity-gateway/codex-models.json"

[model_providers.antigravity]
name = "Antigravity Gateway"
base_url = "http://127.0.0.1:9897/v1"
env_key = "ANTIGRAVITY_GATEWAY_API_KEY"
wire_api = "responses"
request_max_retries = 0
stream_max_retries = 0

Windows 路径建议使用 TOML 单引号：

model_catalog_json = 'C:\Users\YOUR_NAME\.antigravity-gateway\codex-models.json'

启动前设置 Key：

macOS/Linux：

export ANTIGRAVITY_GATEWAY_API_KEY=antigravity-gateway
codex

Windows PowerShell：

$env:ANTIGRAVITY_GATEWAY_API_KEY = "antigravity-gateway"
codex

接入 Trae 或其他客户端

根据客户端支持的协议填写：

API 格式 Base URL API Key 模型
Anthropic Messages http://127.0.0.1:9897 antigravity-gateway 从模型目录选择
OpenAI Responses/Chat http://127.0.0.1:9897/v1 antigravity-gateway 从模型目录选择

查询模型：

antigravity-gateway --models
curl http://127.0.0.1:9897/v1/models

模型取决于账号、套餐、地区和 Antigravity CLI 版本。模型目录只用于展示和诊断，不会阻止客户端把其他模型 ID 发给上游。

图片生成与多媒体理解

普通对话不依赖关键词判断。网关把文本和附件一并交给客户端指定的 Gemini 模型：模型认为附件只是资料时直接理解并回答；只有用户明确要求产出新图片或编辑参考图时，模型才会调用内置的原生生图工具。客户端自己的工具名、tool_choice 和工具执行流程不会被替换。

原生生图直接使用 agy 同款的 Antigravity 私有图片请求和账号池凭据，不会为每次请求启动本机 agy。新版本通过 add 授权的账号会同时保存后续刷新所需的 OAuth 客户端元数据；把完整账号 JSON 复制到服务器账号池后，即使服务器没有安装 agy，该账号也能刷新并参与对话和生图。旧版已保存但不含这些字段的账号仍按原有方式从本机 agy 安装中发现刷新配置。

OpenAI 标准文生图：

curl http://127.0.0.1:9897/v1/images/generations \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"白色背景中央的黑色六边形","size":"1024x1024","response_format":"url"}'

参考图编辑，最多 3 张参考图：

curl http://127.0.0.1:9897/v1/images/edits \
  -F 'image=@reference.png' \
  -F 'prompt=只把主体颜色改为紫色，其他内容不变' \
  -F 'response_format=url'

远程服务器或不能直接传本地路径的客户端，可以先上传文件：

curl http://127.0.0.1:9897/v1/files \
  -F 'file=@recording.mp4;type=video/mp4' \
  -F 'purpose=assistants'

返回的 file_... 可放进 Anthropic source.file_id、Chat Completions 的 file_id/input_image/input_video，或 Responses 的 input_file/input_image/input_video。协议转换器也接受 Base64/Data URL、HTTP(S) URL 和网关本机绝对路径；生成图片的 URL 可以直接作为后续参考图再次使用。上传与生成文件保存在 ~/.antigravity-gateway/media/。

生图响应会同时提供普通文本回执、Markdown、可访问 URL、网关主机上的绝对路径，以及各协议中的 artifacts 结构化元数据；不识别扩展字段的客户端仍可从正文取得交付地址。文件内容接口同时支持 GET 和 HEAD。

如果 Agent 本身不会把本地视频转换成多媒体请求，可以使用随包附带的 skills/antigravity-video-understanding。该 Skill 的 Python 脚本会通过现有 Files API 上传本地视频，再以原生 input_video 调用 Chat Completions；本地或远程网关均使用同一流程：

python3 skills/antigravity-video-understanding/scripts/analyze_video.py \
  "/absolute/path/recording.mp4" \
  --prompt "分析这段视频并回答我的问题"

网关分别管理客户端身份、独立对话和账号黏性：同一对话及其工具调用优先使用同一账号；子 Agent 使用独立会话状态，但通过父会话继承账号黏性。软黏性映射会在本地保存固定 5 小时（可通过 ANTIGRAVITY_AFFINITY_TTL_SECONDS 调整），网关重启后仍会优先恢复当前窗口内的账号；窗口内的后续请求只检查本地可用状态，不重复读取或排序额度。窗口到期、账号额度耗尽、网络异常、凭据失效、访问受限或 Google 要求安全核验时会重新按 Gemini 周额度压力、5 小时重置时间和账号权重加权选择，避免单一高压力账号独占全部新流量。认证和账号风控会把账号标记为异常并停止继续尝试；重新授权导致凭据变化时自动恢复，也可以在看板中点击“重新检测”，以不生成内容、不消耗模型 Token 的轻量鉴权确认核验结果。网络瞬态故障仍由直连传输重试，失败后只进入短暂冷却。

首次选择账号或故障转移时，保留当前模型的可用性优先规则，然后仅参考 Gemini 模型组的周额度计算 Pressure = remainingFraction / 距周重置小时数，以 floor(log2(Pressure)) 分档。最高压力档、相邻档和其余可用档分别获得 4、2、1 倍权重；同档中 Gemini 5 小时额度最早重置的账号再获得 2 倍权重，最后叠加账号自身权重进行平滑加权轮询。无论请求使用 Gemini、Claude 还是 GPT，都不使用 Claude/GPT 周额度参与压力排序。已有可用的黏性账号及生图的优先账号直接续接，不重算压力或变更轮询权重；切号时重新读取快照，单次请求不重复尝试同一账号。

选号只读取内存中的真实上游额度快照，不等待联网查询，也不根据 Token 用量推算余额。有效的 Gemini 周压力档位优先，未知压力账号随后，已知周额度耗尽账号保留为最终兜底。快照过期、周重置已到或字段缺失时按未知处理，并异步补刷新；同档未知的 5 小时重置时间仍退回加权轮询。后台保留约 30 分钟一次的完整刷新；缺失/失效快照及实际额度失败只补查相关账号的额度汇总，普通补刷新每账号至少间隔 5 分钟，重复请求合并，最多同时刷新两个账号。新增账号、凭据变化及重新检测成功会触发该账号的完整刷新。额度汇总单独记录观测时间，套餐或模型目录查询成功不会把旧额度标记为最新。

支持客户端显式发送 x-client-id/x-agent-id、x-session-id/x-conversation-id、x-parent-session-id 和 x-routing-affinity-id；未提供时继续兼容现有 Claude、Codex、OpenAI 和 Anthropic 客户端字段。所有原始标识仅用于本地路由，提交上游的会话值是不可逆哈希，不会写入模型提示词。日志中的 request、client、session 和 affinity 短标识可用于区分并发链路。

用量和额度

启动界面显示：

  • 账号池可用状态和已取得的额度快照。
  • 历史请求数、上游调用数、输入/输出 Token、缓存 Token 与命中率。
  • 最近24小时每小时用量图。

输入 usage 查看实时明细，输入 status 刷新展示。用量每5分钟保存一次，24小时图表每小时更新，历史总量展示每24小时更新。额度快照约每30分钟刷新；上游实时返回始终是最终依据。

网关以前台或后台模式运行时，都可以另开终端执行下面的命令查看完整图形看板：

antigravity-gateway stats

看板提供历史与所选时段 Token、请求和上游调用、输入/输出/思考/缓存、失败率、账号额度、小时热力图、模型趋势和模型消耗占比；支持最近1天、3天、7天、30天及按账号筛选，浏览器会记住上次选择的统计周期。账号列表只来自当前账号池；额度与 agy /usage 保持一致，默认按账号完整展示 Gemini 模型组、Claude/GPT 模型组共享的每周额度和 5 小时额度，也可切换为只看 Gemini 模型组的额度概览，浏览器同样会记住上次选择。异常账号提供一次性轻量鉴权的“重新检测”按钮；“删除账号”会移除账号凭据、健康状态、额度快照与会话黏性，并防止已主动删除的本地 agy 身份在重启时被自动导回。若账号池因此变空，网关不会绕过账号池退回该本地登录态；重新使用需通过 add 明确加入账号。具体模型的调用次数与 Token 只按真实请求的模型 ID 统计，不再把模型目录中的单项余额误写成账号总额度。点击“生成图片”会在浏览器本地生成账号脱敏的高清 PNG，桌面端直接下载，移动端提供长按保存预览；该过程不依赖第三方服务，也不会增加网关后端截图负担。网页每分钟读取一次本地聚合数据，关闭页面后不会继续轮询，也不保存提示词或模型回复。账号与模型的小时细分从 v0.8.0 起累计。

~/.antigravity-gateway/state/account-pool.json
~/.antigravity-gateway/state/quota.json
~/.antigravity-gateway/usage/usage-state.json

account-pool.json 只保存账号 ID、不可逆会话路由标识、被主动删除身份的不可逆哈希、时间和账号健康状态，不保存提示词、模型回复或账号 Token；用量统计也只保存数字。

更新与卸载

更新：

npm install --global --foreground-scripts --allow-scripts=antigravity-gateway https://github.com/LeeFeee/antigravity-gateway/archive/refs/heads/main.tar.gz

更新后必须重启正在运行的网关。前台模式按 Ctrl+C 后重新运行；后台模式执行：

antigravity-gateway service start

卸载：

antigravity-gateway service uninstall
npm uninstall --global antigravity-gateway

常见问题

401 本地 agy 登录态刷新失败

先在官方 agy 中重新登录并完成一次正常对话，然后重启网关。输入 acc 检查账号池状态；若看板仍标记异常，可点击该账号的“重新检测”确认新凭据或安全核验已经生效。

429 Resource has been exhausted

通常表示当前账号或模型额度受限。网关会尝试其他可用账号；如果所有账号都受限，请等待额度恢复或切换模型。

EADDRINUSE 127.0.0.1:9897

已有网关占用端口。关闭旧进程，或使用其他端口：

antigravity-gateway --port 9898

客户端 Base URL 也必须改成新端口。

Claude Code 请求没有出现在网关日志

检查 ANTHROPIC_BASE_URL，并移除 Bedrock、Vertex、Foundry 等会覆盖本地 Base URL 的 provider 开关。系统代理环境下可设置：

export NO_PROXY=127.0.0.1,localhost

鉴权与休眠恢复诊断日志

网关会把账号隔离、手动重新检测、Token 刷新阶段、上游鉴权探测结果，以及疑似休眠或挂起造成的运行时间断层写入 ~/.antigravity-gateway/logs/auth-diagnostics.jsonl。每行都是带 ISO 时间的独立 JSON，便于按事件还原链路；文件达到约 5 MB 后保留一份 .1 轮转副本。日志只记录账号掩码、状态、耗时、HTTP 状态和脱敏错误，不记录 access token、refresh token、client secret、提示词或模型回答。

tail -f ~/.antigravity-gateway/logs/auth-diagnostics.jsonl

启动时只发现少量模型

模型探测可能暂时失败或账号目录尚未刷新。输入 models、reload，或使用 antigravity-gateway --models 再次查询。客户端明确指定的模型仍会原样发给上游。

常用配置

环境变量 默认值 作用
ANTIGRAVITY_GATEWAY_HOST 127.0.0.1 网关监听地址
ANTIGRAVITY_GATEWAY_PORT 9897 网关监听端口
ANTIGRAVITY_GATEWAY_API_KEY 空 自定义网关 Key；非本机监听时必须设置
ANTIGRAVITY_CLI_PATH 自动查找 agy 指定 agy 路径
ANTIGRAVITY_LOCAL_AUTH_FILE 自动读取本地登录态 指定本地 agy 凭据文件
ANTIGRAVITY_GATEWAY_CONFIG_DIR ~/.antigravity-gateway 账号、额度、用量和客户端配置目录
ANTIGRAVITY_DEFAULT_MODEL gemini-3.8-flash-high 请求未提供模型时使用
ANTIGRAVITY_FAST_MODEL 自动选择 Claude Code Auto Mode 分类请求使用
ANTIGRAVITY_MODEL_ALIASES {} 用户主动设置的精确模型映射
ANTIGRAVITY_DIRECT_MODEL_DISCOVERY_TIMEOUT_MS 8000 模型目录探测超时，单位毫秒
ANTIGRAVITY_GATEWAY_TIMEOUT_MS 300000 单次请求总超时，单位毫秒
ANTIGRAVITY_GATEWAY_MAX_CONCURRENCY 12（agy 模式为 4） 最大并发请求数
ANTIGRAVITY_GATEWAY_MAX_QUEUE 32 最大排队请求数
ANTIGRAVITY_AFFINITY_TTL_SECONDS 18000 账号软黏性的固定窗口，单位秒；窗口内成功请求不会续期
ANTIGRAVITY_GATEWAY_CORS_ORIGIN 空 允许访问本地网关的浏览器 Origin
ANTIGRAVITY_GATEWAY_DASHBOARD_ALLOW 空 额外允许访问看板的 IP、CIDR 或 *，逗号分隔；默认仅本机
ANTIGRAVITY_GATEWAY_DEBUG 空 设置为 1 输出更多诊断信息
ANTIGRAVITY_IMAGE_MODEL gemini-3.1-flash-image 原生图片请求使用的 Antigravity 图片模型
ANTIGRAVITY_GATEWAY_MEDIA_LIMIT 100663296 单个多媒体文件内存/解析上限，单位字节
ANTIGRAVITY_GATEWAY_TOTAL_MEDIA_LIMIT 201326592 单次对话解析的多媒体总上限，单位字节

非必要情况下不建议手动设置 access token、refresh token、project ID 或上游地址。普通用户使用本地 agy 登录态和账号池即可。

跨设备查看看板时，需要同时把监听地址改为非回环地址并设置 API Key。例如只允许局域网 192.168.1.0/24：

export ANTIGRAVITY_GATEWAY_HOST=0.0.0.0
export ANTIGRAVITY_GATEWAY_API_KEY=请设置自己的密钥
export ANTIGRAVITY_GATEWAY_DASHBOARD_ALLOW=192.168.1.0/24
antigravity-gateway

看板本身不校验 API Key，白名单来源可以看到账号邮箱、额度和用量；不建议在公网环境中使用 *。来源按真实 TCP 对端地址判断，不信任 X-Forwarded-For。使用后台模式时重新执行 antigravity-gateway service start，即可保存配置并重启服务。

接口

GET  /
GET  /v1/models
POST /v1/files
GET  /v1/files/:id
GET  /v1/files/:id/content
DELETE /v1/files/:id
POST /v1/images/generations
POST /v1/images/edits
POST /v1/messages
POST /v1/messages/count_tokens
POST /v1/responses
POST /v1/chat/completions

工作原理

客户端请求先进入本地兼容接口，网关完成 Anthropic/OpenAI 与 Cloud Code 之间的格式转换，再使用本地账号池凭据请求上游，最后把结果转换回客户端协议。普通客户端工具仍由 Claude Code、Codex 等客户端执行；只有网关私有的原生生图工具由网关拦截，并直接调用 Antigravity 图片接口。

已知限制

  • 直连使用的是非公开 Cloud Code 内部接口，上游升级后可能需要同步适配。
  • 可用模型和额度取决于账号；本项目不会绕过上游限制。
  • 工具调用、Auto Mode 和结构化输出请求可能需要先完整校验，再向客户端返回。
  • 私有生图和多媒体协议并非公开稳定接口，上游格式或权限发生变化时可能需要同步适配。
  • 本地账号文件是普通 JSON，由使用者自行保管。

License

MIT，见 LICENSE。

English

Antigravity Gateway is a local Anthropic/OpenAI-compatible gateway. It reuses the official Antigravity CLI (agy) login state so Claude Code, Codex CLI, Trae, and other compatible clients can access models available to the current account through local HTTP endpoints.

The default direct transport calls Cloud Code without the agy Agent wrapper prompt. Normal requests preserve the exact model ID selected by the client. Only detected Claude Code Auto Mode classifier requests use a separate fast model.

Unofficial and intended for learning, compatibility research, and personal testing. Upstream plans, quotas, regional restrictions, and terms still apply.

Current version: v1.2.0. See CHANGELOG.md for release notes.

Features

  • Anthropic Messages, OpenAI Responses, and Chat Completions endpoints.
  • Claude Code, Codex CLI, Trae, and other compatible clients.
  • Foreground mode and cross-platform background keepalive/autostart.
  • Automatic local agy account import plus interactive add authorization.
  • Sticky-session account rotation and failover on authentication, quota, or rate-limit failures.
  • Request, token, cache, account, quota, and 24-hour usage displays.
  • Client-side tools, SSE, Claude Code Auto Mode, and structured output support.
  • Native image generation/reference editing and multimodal understanding for images, video, audio, PDFs, and files.
  • OpenAI-compatible Images and Files endpoints for local and remote clients.

Requirements

  • Node.js 20 or newer with npm.
  • Official Antigravity CLI (agy) installed, signed in, and verified with one successful conversation.
  • macOS, Linux, or Windows on ARM64/x64.
  • Network access to Antigravity/Google upstream services.

Install Node.js if needed:

# macOS with Homebrew
brew install node

# macOS/Linux with nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 24

Windows PowerShell:

winget install --exact --id OpenJS.NodeJS.LTS

Install and run

Install globally from any directory:

npm install --global --foreground-scripts --allow-scripts=antigravity-gateway https://github.com/LeeFeee/antigravity-gateway/archive/refs/heads/main.tar.gz

Foreground mode:

antigravity-gateway

Background keepalive and autostart:

antigravity-gateway service start

Open the local Token dashboard while either foreground or background mode is running:

antigravity-gateway stats

Once the gateway is running in either foreground or background mode, run this command from another terminal. The dashboard reuses the gateway process and port 9897; it does not start another persistent web service. The direct URL is http://127.0.0.1:9897/dashboard.

Service management:

antigravity-gateway service status
antigravity-gateway service restart
antigravity-gateway service stop
antigravity-gateway service logs
antigravity-gateway service uninstall

Default client endpoints:

Anthropic: http://127.0.0.1:9897
OpenAI:    http://127.0.0.1:9897/v1
API Key:  antigravity-gateway (any non-empty value when no custom gateway key is set)

If npm 11 prints install scripts not yet covered by allowScripts, but installation ends with changed 1 package and the command works, the installation succeeded.

Accounts and terminal commands

At startup, a usable official local agy identity is added to the pool only when it is new. Existing matching identities are not duplicated or overwritten. Once the pool is non-empty, requests use its stored credentials.

Run the gateway in foreground mode and type add to authorize another account. The complete OAuth URL is always printed. On a remote host, paste the final localhost callback URL back at gateway>.

Command Purpose
add Add an Antigravity account
acc Show pool and account state
models Show discovered models
status Refresh gateway and dashboard status
usage Show live detailed usage
stats Open the local Token dashboard
reload Reload accounts and quota snapshots
config Show client configuration
logs Show log information
clear Clear the terminal
version Show gateway version
help Show command help
quit Save state and stop the gateway

Each upstream attempt prints the selected account, model, and attempt number. Account files are stored under ~/.antigravity-gateway/accounts/ as ordinary JSON.

Claude Code

Add these values to the env object in ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:9897",
    "ANTHROPIC_AUTH_TOKEN": "antigravity-gateway",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6-thinking",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-3.8-flash-low",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1048576"
  }
}

Start with a Gemini 1M context declaration:

claude --model 'gemini-3.8-flash-high[1m]'

Load the generated model picker:

# macOS/Linux
claude --settings "$(antigravity-gateway --claude-config-path)"
# Windows PowerShell
claude --settings (antigravity-gateway --claude-config-path)

Do not enable Bedrock, Vertex, or Foundry provider switches while using the local ANTHROPIC_BASE_URL.

Codex CLI

Print the generated catalog path:

antigravity-gateway --codex-catalog-path

Add to ~/.codex/config.toml:

model = "gemini-3.8-flash-high"
model_provider = "antigravity"
model_catalog_json = "/ABSOLUTE/PATH/.antigravity-gateway/codex-models.json"

[model_providers.antigravity]
name = "Antigravity Gateway"
base_url = "http://127.0.0.1:9897/v1"
env_key = "ANTIGRAVITY_GATEWAY_API_KEY"
wire_api = "responses"
request_max_retries = 0
stream_max_retries = 0

Windows path:

model_catalog_json = 'C:\Users\YOUR_NAME\.antigravity-gateway\codex-models.json'

Start Codex:

export ANTIGRAVITY_GATEWAY_API_KEY=antigravity-gateway
codex

Trae and other clients

API format Base URL API Key
Anthropic Messages http://127.0.0.1:9897 antigravity-gateway
OpenAI Responses/Chat http://127.0.0.1:9897/v1 antigravity-gateway

List available models:

antigravity-gateway --models
curl http://127.0.0.1:9897/v1/models

Images and multimodal input

Normal conversation has no keyword router. The selected Gemini model receives both the text and attachments, understands them as context by default, and invokes a private native image tool only when the requested deliverable is a new or edited image. Existing client tools and tool_choice semantics are preserved.

The image path mirrors agy's private Antigravity image request and uses the managed account pool directly; it does not launch agy for each image. Accounts newly authorized with add retain the OAuth client metadata needed for token refresh if the complete account JSON is later moved to a server without agy.

# Text to image
curl http://127.0.0.1:9897/v1/images/generations \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"a black hexagon on white","size":"1024x1024","response_format":"url"}'

# Reference-image edit (up to three images)
curl http://127.0.0.1:9897/v1/images/edits \
  -F 'image=@reference.png' \
  -F 'prompt=change only the subject to purple' \
  -F 'response_format=url'

# Upload media for a remote client
curl http://127.0.0.1:9897/v1/files \
  -F 'file=@recording.mp4;type=video/mp4' \
  -F 'purpose=assistants'

Use the returned file_... in Anthropic, Chat Completions, or Responses media blocks. Base64/Data URLs, HTTP(S) URLs, gateway-local absolute paths, and previously generated gateway URLs are also accepted. Files are kept under ~/.antigravity-gateway/media/. The gateway separates client identity, conversation state, parent-child relationships, request tracing, and account affinity. Explicit x-client-id/x-agent-id, x-session-id/x-conversation-id, x-parent-session-id, and x-routing-affinity-id headers are supported alongside existing Claude, Codex, OpenAI, Anthropic, and Responses identifiers. Child agents keep independent upstream sessions while inheriting parent account affinity; raw identifiers stay local and only irreversible hashes are used as upstream session metadata. Soft affinity is persisted locally for a fixed five-hour window, configurable through ANTIGRAVITY_AFFINITY_TTL_SECONDS, and successful requests do not extend that window. Healthy continuations use an O(1) local affinity lookup without recalculating quota ranks; expiry or failure triggers weighted selection using Gemini weekly pressure, Gemini five-hour reset time, and configured account weights without starving lower-ranked healthy accounts. Account-level authentication, access-denial, and Google verification challenges mark that account unhealthy and stop further routing or quota probes until its credentials change or the user runs the dashboard's token-free authentication recheck; transient network failures retain transport retries and only cause a short cooldown.

For new bindings and failover, retain current-model availability priority, then calculate Gemini-only weekly pressure bands as floor(log2(remainingFraction / hoursUntilWeeklyReset)), with a one-minute minimum denominator. The highest, adjacent, and remaining usable bands receive 4x, 2x, and 1x weights; the earliest Gemini five-hour reset within each band receives a further 2x boost before applying the configured account weight through smooth weighted rotation. Claude/GPT weekly quota does not affect pressure regardless of the requested model. Healthy sticky continuations and preferred image accounts skip recalculation and do not spend rotation weights. Failover rereads snapshots and tries each account at most once per request.

Scheduling reads fresh in-memory quota summaries without waiting for network queries or estimating quota from Token counts. Unknown/expired weekly data follows known positive pressure, and exhausted snapshots remain advisory fallbacks. Full background refreshes remain approximately half-hourly. Missing/expired data and live quota failures trigger asynchronous per-account summary refreshes, coalesced and throttled to once per five minutes with two accounts refreshed concurrently; account additions, changed credentials and successful authentication rechecks trigger full account refreshes. Summary freshness is tracked independently, so successful plan/catalog queries cannot renew stale quota data.

Generated-image responses include a readable text receipt, Markdown, an accessible URL, the absolute path on the gateway host, and structured artifacts metadata for each protocol. Clients that ignore extension fields can still obtain the delivery address from the assistant text. File content supports both GET and HEAD.

For agents that cannot construct video inputs themselves, the bundled skills/antigravity-video-understanding package uploads a local video through the existing Files API and submits it as native input_video through Chat Completions:

python3 skills/antigravity-video-understanding/scripts/analyze_video.py \
  "/absolute/path/recording.mp4" \
  --prompt "Analyze this video and answer my question."

Usage, update, and troubleshooting

The browser dashboard shows lifetime and selected-period Tokens, requests, upstream calls, input/output/thinking/cache usage, failures, per-account quota, hourly heatmaps, model trends, and model consumption share. It supports 1/3/7/30-day windows and account filtering, and remembers the last selected time window in the browser. Accounts come exclusively from the active account pool. Quota cards mirror agy /usage: by default each account shows the shared weekly and five-hour limits for both the Gemini and Claude/GPT groups, with a compact overview that shows only the Gemini group; the browser also remembers the last selected quota view. Unhealthy accounts expose a one-shot authentication recheck, while Delete Account removes the credential, health record, quota snapshot, and affinity bindings and prevents an explicitly removed local agy identity from being auto-imported or used as an implicit fallback again; use add to explicitly restore it. Per-model request and Token charts use the exact model IDs actually called instead of treating a model-catalog balance as the account's total quota. The Generate Image action creates an account-masked, high-resolution PNG entirely in the browser: desktop browsers download it directly, while mobile browsers show a long-press save preview. No third-party screenshot service or extra gateway-side rendering process is used. The page reads local aggregate data once per minute only while open; it never stores prompts or model responses. Hourly account/model breakdowns begin with v0.8.0. Type usage for terminal details or run antigravity-gateway stats while either foreground or background mode is active. Usage is persisted every five minutes; quota snapshots refresh asynchronously.

Authentication diagnostics are written as timestamped JSON Lines to ~/.antigravity-gateway/logs/auth-diagnostics.jsonl, with one rotated .1 copy at approximately 5 MB. Events cover account quarantine and recovery, manual rechecks, token-refresh stages, upstream authentication probes, and runtime gaps consistent with sleep or suspension. Credentials, prompts, and model responses are never written to this file.

Update:

npm install --global --foreground-scripts --allow-scripts=antigravity-gateway https://github.com/LeeFeee/antigravity-gateway/archive/refs/heads/main.tar.gz

Restart the foreground process after updating, or run antigravity-gateway service start again for background mode.

Common failures:

  • 401: sign in through official agy again, complete one successful conversation, restart the gateway, and check acc.
  • 429: the account/model is rate-limited or out of quota; wait, switch models, or add another account.
  • EADDRINUSE: stop the old process or use antigravity-gateway --port 9898, then update the client URL.
  • No gateway request log: verify ANTHROPIC_BASE_URL and remove Bedrock/Vertex/Foundry provider switches.

Common configuration

Variable Default Purpose
ANTIGRAVITY_GATEWAY_HOST 127.0.0.1 Listen address
ANTIGRAVITY_GATEWAY_PORT 9897 Listen port
ANTIGRAVITY_GATEWAY_API_KEY empty Custom gateway key; required for non-loopback binding
ANTIGRAVITY_CLI_PATH auto-detected Custom agy path
ANTIGRAVITY_LOCAL_AUTH_FILE auto-detected Custom local agy credential file
ANTIGRAVITY_GATEWAY_CONFIG_DIR ~/.antigravity-gateway Accounts, quota, usage, and generated client configuration
ANTIGRAVITY_DEFAULT_MODEL gemini-3.8-flash-high Used only when a request omits model
ANTIGRAVITY_FAST_MODEL auto-selected Auto Mode classifier model
ANTIGRAVITY_MODEL_ALIASES {} Explicit exact model aliases
ANTIGRAVITY_GATEWAY_TIMEOUT_MS 300000 Request timeout in milliseconds
ANTIGRAVITY_GATEWAY_MAX_CONCURRENCY 12 (4 in agy mode) Maximum concurrent requests
ANTIGRAVITY_GATEWAY_MAX_QUEUE 32 Maximum queued requests
ANTIGRAVITY_AFFINITY_TTL_SECONDS 18000 Fixed account-affinity window in seconds; successful requests do not renew it
ANTIGRAVITY_GATEWAY_DASHBOARD_ALLOW empty Extra IPs, CIDRs, or * allowed to open the dashboard; comma-separated and local-only by default
ANTIGRAVITY_IMAGE_MODEL gemini-3.1-flash-image Native Antigravity image model
ANTIGRAVITY_GATEWAY_MEDIA_LIMIT 100663296 Maximum bytes per media item
ANTIGRAVITY_GATEWAY_TOTAL_MEDIA_LIMIT 201326592 Maximum resolved media bytes per request

For remote dashboard access, bind the gateway to a non-loopback address, configure an API key, and allow only the required LAN address or CIDR. The dashboard itself does not validate the API key, so allowed sources can see account emails, quotas, and usage; avoid * on public networks. Matching uses the TCP peer address and does not trust X-Forwarded-For. Re-run antigravity-gateway service start to persist changed environment settings in background mode.

How it works

Clients call the local Anthropic/OpenAI endpoints. The gateway converts requests to the Cloud Code protocol, selects a pool account, sends the upstream request, and converts the result back. Normal tools remain client-executed. Only the private native image tool is intercepted and sent directly to the Antigravity image endpoint.

Limitations

  • Direct transport uses an undocumented Cloud Code internal API and may require updates after upstream changes.
  • Available models and quotas depend on the account and upstream service.
  • Tool, Auto Mode, and structured-output requests may be buffered for validation.
  • Private image and multimodal protocols are undocumented upstream interfaces and may require compatibility updates.
  • Account credentials are ordinary local JSON files and remain the user's responsibility.

License

MIT. See LICENSE.

About

Local Anthropic and OpenAI compatible gateway backed by the official Antigravity CLI.

Resources

Readme
MIT license
Activity

Stars

20 stars

Watchers

0 watching

Forks

8 forks
Report repository

Releases

Packages

Contributors

Languages