camofox-browser /tabs端点详解：创建、列表、统计、关闭全覆盖

camofox-browser /tabs端点详解：创建、列表、统计、关闭全覆盖

【免费下载链接】camofox-browserStealth headless browser for AI agents — bypass Cloudflare, bot detection, and anti-scraping. Drop-in Puppeteer/Playwright replacement.项目地址: https://gitcode.com/GitHub_Trending/ca/camofox-browser

camofox-browser是一个面向 AI Agent 的隐身无头浏览器服务，基于 Camoufox（C++ 级指纹伪造的 Firefox 分支），可绕过 Cloudflare 和各类反爬检测。它的/tabs端点是整个服务的核心入口，一个 URL 前缀就涵盖了标签页的创建、列表、统计、关闭四大操作，是 Agent 管理浏览任务的"总开关"。

一、为什么标签页是核心？

在 camofox-browser 中，每个用户拥有一个会话（session），会话内按sessionKey划分标签页组，每个标签页（tab）由唯一的tabId标识。所有浏览器操作——导航、截图、点击、提取数据——都挂在具体的tabId上。因此/tabs端点群就是 Agent 浏览生命周期的起点和终点：

• POST/tabs→ 创建标签页
• GET/tabs→ 列出所有打开的标签页
• GET/tabs/:tabId/stats→ 查询标签页运行统计
• DELETE/tabs/:tabId→ 关闭单个标签页
• DELETE/tabs/group/:listItemId→ 一键关闭整组标签页

路由实现集中在 server.js，完整接口契约可查看自动生成的 openapi.json 或交互式文档 docs/api.html。

二、创建标签页：POST /tabs

创建标签页是发起任何浏览任务的第一步（server.js#L2816）。

必填字段

可选字段

创建成功后返回：

{ "tabId": "…", "url": "about:blank" }

几个值得注意的机制：

1. 失败自动换代理重试：如果初始导航遇到代理错误或超时，服务会静默轮换代理并重试（server.js#L2884），Agent 通常无感知。
2. SSL 证书错误不重试：会直接返回502并标记recoverable: false。
3. 追踪限制：对已有会话追加trace会返回409，需要先DELETE /sessions/:userId重建会话。

💡 另有一个兼容旧版 OpenClaw 格式的别名端点POST/tabs/open（server.js#L5831），只要求userId+url两个字段，标记为已废弃，新接入建议使用POST /tabs。

三、列出标签页：GET /tabs

想看看某个用户当前开了哪些页面？带上userId查询参数即可（server.js#L5766）：

GET /tabs?userId=agent-001

返回结构非常直观：

{ "running": true, "tabs": [ { "tabId": "…", "targetId": "…", "url": "https://example.com", "title": "Example Domain", "listItemId": "default" } ] }

• running：服务是否处于运行状态；
• tabs：每个标签页的实时 URL、页面标题（通过 Playwright 实时读取）、所属分组。
• 若该userId尚无会话，返回{ "running": true, "tabs": [] }，不会报错，对 Agent 轮询非常友好。

四、标签页统计：GET /tabs/:tabId/stats

Agent 运行到一半时，需要知道"这个标签页干了多少活"。统计端点（server.js#L4845）一次返回：

GET /tabs/{tabId}/stats?userId=agent-001

这个端点特别适合做任务进度巡检：例如 Agent 批量抓取 20 个页面时，定期调用 stats 就能发现哪个标签页卡住（visitedUrls停止增长）、哪个已经产生下载。

五、关闭标签页：DELETE /tabs/:tabId

单标签页关闭（server.js#L5149）：

DELETE /tabs/{tabId}?userId=agent-001

服务端会完整清理资源：中断进行中的导航、清空下载记录、释放页面、移除锁，并同步更新指标。当整个标签页组为空时，该组也会自动删除。返回{"ok": true}；即使用户不存在该标签页也会返回ok，方便做幂等清理。

整组关闭：DELETE /tabs/group/{listItemId}?userId=…（server.js#L5211）一次性关掉某分组下的所有标签页，任务结束时推荐使用，比逐个删除更高效。

六、标签页数量限制与自动回收

camofox-browser 有两级数量上限（lib/config.js#L117-L118，可通过环境变量覆盖）：

• 每会话上限MAX_TABS_PER_SESSION，默认10
• 全局上限MAX_TABS_GLOBAL，默认50

达到上限时的行为很"聪明"：

1. 优先回收：自动关闭会话中最老、无活跃操作的标签页，为新标签页腾出空间；
2. 回收失败才拒绝：仅当无法回收时返回429（Maximum tabs per session reached）。

这意味着 Agent 可以放心连续开页，服务会帮你控制内存水位，而不是简单地把请求打回去。

七、常见错误码速查

八、动手试试

本地拉起服务只需三行命令：

git clone https://gitcode.com/GitHub_Trending/ca/camofox-browser cd camofox-browser && npm install && npm start # 服务运行在 http://localhost:9377

然后打开交互式 API 文档http://localhost:9377/docs（由 docs/openapi.json 自动生成），就能在线调试本文介绍的全部/tabs端点。

总结

/tabs端点用最小的接口面覆盖了标签页的完整生命周期：POST 创建（带自动代理重试）→ GET 列表（轮询友好）→ stats 统计（进度巡检）→ DELETE 关闭（支持整组清理），配合两级数量限制与最老标签页自动回收机制，让 AI Agent 既能连续开页、又不会撑爆内存。掌握这一个端点群，就掌握了 camofox-browser 的浏览任务管理骨架 🦊

【免费下载链接】camofox-browserStealth headless browser for AI agents — bypass Cloudflare, bot detection, and anti-scraping. Drop-in Puppeteer/Playwright replacement.项目地址: https://gitcode.com/GitHub_Trending/ca/camofox-browser