lumingya/universal-web-api

Universal Web API – 将 AI 网页界面桥接到兼容 OpenAI/Anthropic 的本地 API

它是什么

• 一个本地运行的服务，控制 Chromium 浏览器，登录 AI 聊天网站（ChatGPT、Gemini、Claude 等），并将 Web 界面重新暴露为标准 OpenAI 兼容（/v1/chat/completions、/v1/models）和 Anthropic 兼容（/v1/messages）端点。
• 充当 调试/桥接 层：您自己的客户端可以调用熟悉的 OpenAI/Anthropic HTTP API，而服务将请求转发到真实的网页，解析 DOM 或网络流量，并返回 JSON 或服务器发送事件。

主要功能

• OpenAI 和 Anthropic 兼容性 – 支持聊天补全、模型列表、令牌计数、流式 SSE、工具调用、多模态输入，以及实验性的 /v1/responses。
• 多站点支持 – 预配置了 ChatGPT、DeepSeek、Gemini、Claude、Kimi、Qwen、Grok、Doubao、AI Studio、Arena AI，并提供通过 DOM 规则生成添加新站点的 UI。
• 路由灵活性 – 基于模型的自动路由、基于站点的显式 URL、标签页索引路由、URL 令牌路由和组路由。
• 标签页池管理 – 保持浏览器标签页池存活，每个标签页可分配给一个请求，并具有生命周期、健康和日志监控。
• 本地控制面板 – Web 仪表板（http://127.0.0.1:8199/）显示浏览器状态、请求历史、日志，并允许您实时编辑 sites.json 或预设。
• 安全选项 – 可选的 bearer 令牌 / API 密钥认证、CORS 控制、可选的安全令牌要求下的公共绑定，以及在暴露服务时关于防火墙 / TLS 的明确指导。
• 可扩展配置 – 环境变量（.env）、JSON 站点规则、代理支持、定时重启、配置文件清理等。

工作原理（高层流程）

1. 客户端 → FastAPI 端点（app/api）。
2. FastAPI 向 标签页池（app/core/tab_pool）请求一个空闲的浏览器标签页。
3. 标签页由 DrissionPage（一个 Chromium 驱动程序）驱动（app/core/workflow）。
4. 特定站点的 解析器（app/core/parsers）读取网络响应或 DOM 以提取 AI 模型的回复。
5. 服务将回复格式化为 JSON 或 SSE，并返回给客户端。

快速开始

# 1. 下载一个发布版本，解压到一个仅包含英文路径的文件夹。
# 2. Windows：双击 start.bat
#    macOS/Linux：python3 start.py   # 或 python main.py（无自动检查）
# 3. 脚本安装 Python 依赖，启动受控的 Chromium 配置文件，并在 http://127.0.0.1:8199/ 打开仪表板
# 4. 在受控浏览器中登录目标 AI 网站。
# 5. 将您自己的客户端指向 http://127.0.0.1:8199/v1，并从 GET /v1/models 中选择一个模型。

示例 API 调用（OpenAI 风格）

curl http://127.0.0.1:8199/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}],"stream":false}'

• 如果启用了认证，添加 -H "Authorization: Bearer <TOKEN>" 或 -H "X-API-Key: <TOKEN>"。
• 设置 "stream": true 以获取 SSE 输出。

配置要点

变量	默认值	用途
APP_HOST	127.0.0.1	绑定地址（仅在启用认证和防火墙时使用 0.0.0.0）。
APP_PORT	8199	API、仪表板和教程的端口。
AUTH_ENABLED / AUTH_TOKEN	false / 空	切换 bearer 令牌 / API 密钥保护。
CORS_ENABLED / CORS_ORIGINS	true / 空	控制跨域访问。
BROWSER_PATH	自动检测	Chrome/Edge/Brave 二进制文件的路径。
BROWSER_PROFILE_DIR	项目文件夹	用于隔离的独立 Chromium 配置文件。
SITES_CONFIG_FILE	config/sites.json	定义站点规则、预设和路由组的 JSON 文件。

典型用例

• 当您只能访问仅限网页的 AI 服务时，进行 OpenAI 兼容客户端的本地开发。
• 测试针对 Claude、Gemini 或其他基于网页的模型的工具调用集成，而无需官方 API 密钥。
• 通过检查底层 DOM 调试多模态交互（图像上传、文件粘贴）。

限制 / 注意事项

• 设计用于单机调试，而非多租户生产网关。
• 必须保持受控浏览器登录；任何登录挑战、验证码或账户锁定都会中断桥接。
• 公开暴露服务需要强认证、CORS 限制、防火墙规则，并且最好使用带 TLS 的反向代理。
• 该工具可能违反目标 AI 网站的服务条款；用户自行承担所有风险。

许可证

• AGPL-3.0（参见 LICENSE）。

支持

• 在 GitHub 上打开问题，或加入 QQ 群 1073037753 获取社区帮助。

---

以上所有细节均直接取自仓库的 README；未推断任何额外功能。