WebAI2API-Agent

简体中文 | English

Agent / Tool Calling 增强版

本仓库是基于 foxhui/WebAI2API 的 Agent-ready fork。它保留原版网页适配器、浏览器池和普通 OpenAI-compatible API，并增加一层面向 Codex、OpenClaw 等客户端的工具调用兼容层。原作者署名和 MIT 许可证保持不变。

普通聊天只需要消息和文本；Agent 还需要 tools、tool_choice、tool_calls、tool_call_id、工具结果和跨请求状态。本分支先把 Chat Completions 或 Responses 请求归一化为 Universal Agent IR，再按适配器和模型族选择 Synthetic 策略/解析器，最后输出标准 tool_calls 或 function_call。WebAI2API 不执行客户端工具，shell、文件、浏览器和 MCP 始终由 Agent 自己执行。

已实现的接口与能力

POST /v1/chat/completions：tools、tool_choice、parallel_tool_calls、assistant tool_calls、role: tool。
POST /v1/responses：function_call、function_call_output、call_id、previous_response_id 和受 TTL/数量限制的内存状态。
Universal Agent IR、JSON Schema/调用状态校验、唯一 call ID、多轮 tool result 回传和策略/解析器注册表。
OpenAI-like、Qwen Hermes、Qwen3-Coder、Gemini-like、Anthropic-like 和 Generic tagged JSON 策略；native pass-through 只作为能力扩展位，未默认宣称原生可用。
Agent 工具响应采用“完整收集网页输出 → 解析校验 → 输出稳定 SSE”的缓冲策略，不在参数尚未完整时执行工具。
Agent 默认关闭，普通 legacy 聊天仍走原路径；ChatGPT 网页 Agent 回合可使用临时会话、SSE 观察、DOM 恢复和空响应有界重试。

数据流

Agent → OpenAI Chat/Responses + tools → Universal Agent IR → 网页模型
← 标准 tool_calls/function_call ← 工具意图解析 ←
Agent 本地执行真实工具 → tool result/function_call_output → WebAI2API → 模型继续推理

与原版的差异

功能	原版	当前分支
普通聊天、浏览器池、队列和 WebUI	支持	保留 legacy 路径
`tools` / `tool_choice` 语义	非 Agent 主路径	归一化并严格校验
`tool_calls` / `function_call`	非 Agent 主路径	Chat 与 Responses 均可转换
工具结果多轮回传	非 Agent 主路径	Chat 使用 `role: tool`，Responses 使用 `previous_response_id`
模型专属策略和解析器	由适配器自行处理	通过策略/解析器注册表选择
工具执行	不由 WebAI2API 负责	仍由 Agent 客户端负责

支持边界（按证据分级）

层级	结论
已验证	`npm test` 46/46；legacy Chat、Chat Agent、Responses、SSE、队列和策略解析 fixture 通过
已验证	独立 Codex CLI 经生产 3000 Responses 闭环：真实失败测试、读取、修改、复测均完成，stdout 含 `CODEX_PRODUCTION_3000_OK`
已验证	隔离 OpenClaw profile/workspace 闭环：6 次真实 `exec`/`read`/`edit` 调用、失败修复后复测成功；这是 Canary 证据，不等同于每个生产账户均已验证
已验证网页路径	Codex 生产复测使用 ChatGPT `gpt-thinking`；此前 Canary 记录还使用过 `gpt-instant`
理论兼容	Qwen Hermes/Qwen3-Coder、Gemini-like、Anthropic-like 及其他 OpenAI-compatible Agent
未验证	Claude Code、真实 Qwen/Gemini/Claude 网页工具闭环、所有原版适配器的 Agent 兼容、并行工具执行

协议 fixture 通过不等于每个网页账户都已通过。请用 GET /v1/models 查看本机实际模型，并单独验证工具调用、工具结果和磁盘副作用。

启用 Agent 层

Agent 层默认关闭；在个人的 data/config.yaml 中按需开启：

agentCompatibility:
enabled: truenativePassThrough: falsetemporaryChat: trueforceInitialToolChoice: false# 对当前 Codex 网页工具链，可在确认网页账号已登录后使用：# forceInitialToolName: shell_commandforceSyntheticToolChoiceTurns: 0maxSyntheticToolRetries: 1retrySyntheticAutoFinal: falsemaxSyntheticInstructionChars: 12000

Agent 示例

先通过 GET /v1/models 选择实际模型。以下 key、模型名和路径都是占位符：

curl http://127.0.0.1:3000/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"<model-from-v1-models>","messages":[{"role":"user","content":"读取项目版本"}],"tools":[{"type":"function","function":{"name":"read_file","description":"Read a UTF-8 file","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}}],"tool_choice":"auto"}'

若返回 message.tool_calls，客户端执行工具后用相同的 tool_call_id 追加 role: "tool" 消息。Responses 客户端则提交 function_call_output 并携带上一次的 previous_response_id。兼容层不会替客户端执行任何工具。

Codex 的核心配置值是 wire_api = "responses"、base_url = "http://127.0.0.1:3000/v1" 和从环境变量读取 API key；OpenClaw 使用其版本对应的 OpenAI-compatible provider 配置，填写同一个 base URL、环境变量 key 和 /v1/models 中的模型 ID。不同客户端配置键名会变化，不能把此说明当成固定配置文件。

安装与启动

git clone https://github.com/passionsugar/WebAI2API.git
cd WebAI2API
corepack enable
pnpm install
npm run init
npm run genkey
npm start -- -xvfb -vnc

如果 pnpm 11 的供应链策略提示 ERR_PNPM_IGNORED_BUILDS，先批准项目需要的本地构建脚本，再重跑安装：pnpm approve-builds better-sqlite3 sharp、pnpm install。

首次启动会从 config.example.yaml 创建 data/config.yaml；把 npm run genkey 输出的 key 写入 server.auth，再配置浏览器实例和登录状态。Dockerfile 会从当前源码构建；现有 docker-compose.yaml 仍引用原版 foxhui/webai-2api:latest，不会自动包含本分支 Agent 代码。

已知限制

Synthetic tool calling 是提示与解析兼容，不等于网页模型原生 function calling；网页 DOM/SSE/风控变化可能导致失效。
Agent SSE 是缓冲式转换；Responses 状态保存在进程内存，重启或过期后旧 response_id 不再可用。
WebAI2API 不执行 shell、文件、浏览器或 MCP 工具；客户端必须自行负责授权、沙箱和错误结果回传。
parallel_tool_calls 受状态机和请求约束；本分支没有把并行执行器列为已验证能力。
Claude Code、真实 Qwen/Gemini/Claude 工具闭环和其他 Agent 客户端尚未逐一验收。

详细协议/架构说明见 AGENT_COMPATIBILITY_TUTORIAL.md，验收边界见 AGENT_ACCEPTANCE_20260816.md。

📝 项目简介

WebAI2API 是一个基于 Camoufox (Playwright) 的网页版 AI 服务转通用 API 的工具。通过模拟人类操作与 LMArena、Gemini 等网站交互, 提供兼容 OpenAI 格式 的接口服务, 同时支持 多窗口并发 与 多账号管理(浏览器实例数据隔离)。

✨ 主要特性

🤖 拟人交互: 模拟人类打字与鼠标轨迹, 通过特征伪装规避自动化检测
🔄 接口兼容: 提供标准 OpenAI 格式接口, 支持流式响应与心跳保活
🚀 并发隔离: 支持多窗口并发执行, 可配置独立代理,实现多账号浏览器实例级数据隔离
🛡️ 稳定防护: 内置任务队列、负载均衡、故障转移、错误重试等基础功能
🎨 网页管理: 提供可视化管理界面, 支持实时日志查看、VNC 连接、适配器管理等

📋 支持列表

网站名称	文本生成	图片生成	视频生成
LMArena	✅	✅	🚫
Gemini Enterprise Business	✅	✅	✅
Nano Banana Free	🚫	✅	🚫
zAI	✅	✅	🚫
Google Gemini	✅	✅💧	✅💧
ZenMux	✅	❌	🚫
ChatGPT	✅	✅	🚫
DeepSeek	✅	🚫	🚫
Sora	🚫	🚫	✅💧
Google Flow	🚫	✅	❌
豆包	✅	✅	❌
待续...	-	-	-

Note

获取完整模型列表: 通过 GET /v1/models 接口查看当前配置下所有可用模型及其详细信息。

✅目前支持；❌目前不支持，但未来可能会支持；🚫网站不支持, 未来是否在支持看网站具体情况；💧结果带水印且无法去除；

🚀 快速部署

本项目支持 源码直接运行 和 Docker 容器化部署 两种方式。

📋 环境要求

Node.js: v20.0.0+ (ABI 115+)
操作系统: Windows / Linux / macOS
核心依赖: Camoufox (安装过程中自动获取)

🛠️ 方式一:手动部署

安装与配置

# 1. 安装 NPM 依赖
pnpm install
# 2. 安装浏览器等预编译依赖# ⚠️ 该脚本需连接 GitHub 下载资源。若网络受限，请使用代理
npm run init # 使用代理# 直接使用 -proxy 可交互式输入代理配置
npm run init -- -proxy=http://username:passwd@host:port
# 3. Linux 依赖安装# 其他发行版请前往文档中心查找或者自行搜索
apt install -y xvfb x11vnc libgtk-3-0 libx11-xcb1 libasound2

启动服务

# 标准启动
npm start
# Linux 系统 - 虚拟显示启动
npm start -- -xvfb -vnc
# 登录模式 (会临时强行禁用无头模式和自动化)
npm start -- -login (-xvfb -vnc)

🐳 方式二:Docker 部署

Warning

安全提醒:

Docker 镜像默认开启虚拟显示器 (Xvfb) 和 VNC 服务
可通过 WebUI 的虚拟显示器板块连接
WebUI 传输过程未加密, 公网环境请使用 SSH 隧道或 HTTPS

Docker CLI 启动

docker run -d --name webai-2api \
-p 3000:3000 \
-v "$(pwd)/data:/app/data" \
--shm-size=2gb \
foxhui/webai-2api:latest

Docker Compose 启动

docker-compose up -d

⚡ 快速开始

1. 调整配置文件

程序初次运行会从config.example.yaml复制配置文件到data/config.yaml

配置文件的生效需要重启程序！

server:
# 监听端口port: 3000# 鉴权 API Token (可使用 npm run genkey 生成)# 该配置会对 API 接口和 WebUI 生效auth: sk-change-me-to-your-secure-key

Tip

完整配置说明: 请参考 config.example.yaml 文件中的详细注释,或访问 WebAI2API 文档中心查看完整配置指南。

2. 访问 Web 管理界面

服务启动后, 打开浏览器访问:

http://localhost:3000

Tip

远程访问: 将 localhost 替换为服务器 IP 地址即可远程访问。 API Token: 配置文件中的auth所配置的鉴权密钥。 安全建议: 公网环境建议使用 Nginx/Caddy 配置 HTTPS 或通过 SSH 隧道访问。

3. 初始化账号登录

Important

首次使用必须完成以下初始化步骤:

连接虚拟显示器:
- Linux/Docker: 在 WebUI 的"虚拟显示器"板块连接
- Windows: 直接在弹出的浏览器窗口中操作
完成账号登录:
- 手动登录所需的 AI 网站账号 (账号要求可进入 WebUI 的适配器管理中查看)
- 在输入框发送任意消息, 触发并完成人机验证 (如需要)
- 同意服务条款或者新手指引 (如需要)
- 确保不再有初次使用相关内容的阻拦

SSH 隧道连接示例(公网服务器推荐):

# 在本地终端运行,将服务器的 WebUI 映射到本地
ssh -L 3000:127.0.0.1:3000 root@服务器IP
# 然后在本地访问# WebUI: http://localhost:3000

📖 使用方法

运行模式说明

Note

关于有头/无头模式:

有头模式(默认): 显示浏览器窗口, 便于调试和人工干预
无头模式: 后台运行, 节省资源但无法查看浏览器界面, 且可能会被网站检测

建议: 为降低风控, 强烈建议长期保持非无头模式运行(或使用虚拟显示器 Xvfb)。

🔌 API 接口

Tip

详细文档: 请访问 WebAI2API 文档中心获取更全面的配置指南与接口说明。

1. OpenAI 兼容接口

Warning

并发限制与流式保活建议

本项目通过模拟真实浏览器操作实现, 处理过程根据实际情况时间可能有所变化, 当积压的任务超过设置的数量时会直接拒绝非流式模式的请求。

💡 强烈建议开启流式模式: 服务器将发送保活心跳包, 可无限排队避免超时。

文本对话

端点: POST /v1/chat/completions

请求示例:

curl http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{ "model": "gemini-3-pro", "messages": [ {"role": "user", "content": "你好,请介绍一下你自己"} ], "stream": true }'

多模态请求(文生图/图生图)

支持的图片格式:

格式: PNG, JPEG, GIF, WebP
数量: 最大 10 张(具体限制因网站而异)
数据格式: 必须使用 Base64 Data URL 格式
自动转换: 服务器会自动将所有图片转换为 JPG 格式以保证兼容性

参数说明

参数	类型	必填	说明
`model`	string	✅	模型名称, 可通过 `/v1/models` 获取可用列表
`stream`	boolean	推荐	是否开启流式响应, 包含心跳保活机制

Note

关于流式保活 (Heartbeat)

为防止长连接超时, 系统提供两种保活模式 (可在配置中切换):

Comment 模式 (默认/推荐): 发送 :keepalive 注释, 符合 SSE 标准,兼容性最好
Content 模式: 发送空内容的 data 包, 仅用于必须收到 JSON 数据才重置超时的特殊客户端

2. 获取模型列表

端点: GET /v1/models

请求示例:

curl http://localhost:3000/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"

3. 获取 Cookies

功能说明: 利用本项目的自动续登功能获取最新 Cookie 供其他工具使用。

端点: GET /v1/cookies

参数:

name (可选): 浏览器实例名称,默认为 default
domain (可选): 过滤指定域名的 Cookie

请求示例:

# 获取指定实例和域名的 Cookie
curl "http://localhost:3000/v1/cookies?name=browser_default&domain=lmarena.ai" \
-H "Authorization: Bearer YOUR_API_KEY"

📊 设备配置参考

资源	最低配置	推荐配置 (单实例)	推荐配置 (多实例)
CPU	1 核	2 核及以上	2 核及以上
内存	1 GB	2 GB 及以上	4 GB 及以上
磁盘	2 GB 可用空间	5 GB 及以上	7 GB 及以上

实测环境表现 (均为单浏览器实例):

Oracle 免费机 (1C1G, Debian 12): 资源紧张, 比较卡顿, 仅供尝鲜或轻度使用
阿里云轻量云 (2C2G, Debian 11): 运行流畅但实例也会卡顿, 项目开发测试所用机型

📄 许可证和免责声明

本项目采用 MIT License 开源。

Caution

免责声明

本项目仅供学习交流使用。如果因使用该项目造成的任何后果 (包括但不限于账号被禁用),作者和项目均不承担任何责任。请遵守相关网站和服务的使用条款 (ToS),并做好相关数据的备份工作。

📋 更新日志

查看完整的版本历史和更新内容, 请访问 CHANGELOG.md。

🕰️ 历史版本说明

本项目已从 Puppeteer 迁移至 Camoufox, 以应对日益复杂的反机器人检测机制。基于 Puppeteer 的旧版本代码已归档至 puppeteer-edition 分支, 仅作留存, 不再提供更新与维护。

感谢 LMArena、Gemini 等网站提供 AI 服务! 🎉

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
patches		patches
scripts		scripts
src		src
tests		tests
webui		webui
.gitignore		.gitignore
AGENT_ACCEPTANCE_20260816.md		AGENT_ACCEPTANCE_20260816.md
AGENT_COMPATIBILITY_TUTORIAL.md		AGENT_COMPATIBILITY_TUTORIAL.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
config.example.yaml		config.example.yaml
docker-compose.yaml		docker-compose.yaml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
supervisor.js		supervisor.js

Latest commit

History

Folders and files

Repository files navigation

WebAI2API-Agent

Agent / Tool Calling 增强版

已实现的接口与能力

数据流

与原版的差异

支持边界（按证据分级）

启用 Agent 层

Agent 示例

安装与启动

已知限制

📑 目录

📝 项目简介

✨ 主要特性

📋 支持列表

🚀 快速部署

📋 环境要求

🛠️ 方式一:手动部署

🐳 方式二:Docker 部署

⚡ 快速开始

1. 调整配置文件

2. 访问 Web 管理界面

3. 初始化账号登录

📖 使用方法

运行模式说明

🔌 API 接口

1. OpenAI 兼容接口

文本对话

多模态请求(文生图/图生图)

参数说明

2. 获取模型列表

3. 获取 Cookies

📊 设备配置参考

📄 许可证和免责声明

📋 更新日志

🕰️ 历史版本说明

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages