名称： next-browser
描述： 使用 Nextbrowser 云 API 为 Openclaw 启动云浏览器，以运行自动化浏览器任务。主要用途是创建带有配置文件（持久化登录状态/cookies）的浏览器会话，供 Openclaw 控制以管理社交媒体和其他在线账户。次要用途是运行任务子代理，在住宅代理、浏览器隐身和验证码解决能力支持下，实现快速的自动化浏览器操作。文档位于 docs.nextbrowser.com。

Nextbrowser

Nextbrowser 通过 API 提供云浏览器和自动化浏览器操作服务。

文档：
- 云 API: https://docs.nextbrowser.com/getting-started

配置

API 密钥 从 Openclaw 配置文件的 skills.entries.next-browser.apiKey 路径读取。

如果未配置，请告知用户：

要使用 Nextbrowser，您需要一个 API 密钥。请在 https://app.nextbrowser.com/user-settings 获取（新注册用户可获得 2000 免费点数）。然后按以下方式配置：
openclaw config set skills.entries.next-browser.apiKey "YOUR_API_KEY"

重要提示： Nextbrowser API 密钥可能有多种格式和前缀。
请勿自行验证密钥格式——直接使用用户提供的任何密钥即可。如果密钥无效，API 将返回身份验证错误，届时再请用户核实其密钥。

基础 URL: https://app.nextbrowser.com/api/v1

所有请求都需要包含请求头: Authorization: x-api-key <apiKey>

1. 凭证管理器

凭证管理器用于安全地存储和跨浏览器运行及自动化任务复用认证数据。

# 列出凭证
curl "https://app.nextbrowser.com/api/v1/users/credentials" -H "Authorization: x-api-key $API_KEY"

2. 配置文件

配置文件可在不同浏览器会话间持久化 cookies 和登录状态。创建一个配置文件，在浏览器中登录您的账户，之后即可重复使用。

# 列出配置文件
curl "https://app.nextbrowser.com/api/v1/browser/profiles" -H "Authorization: x-api-key $API_KEY"

# 创建浏览器配置文件
curl -X POST "https://app.nextbrowser.com/api/v1/browser/profiles" \
  -H "Authorization: x-api-key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "<profile-name>", "browser_settings": {"os_type": "<os-type>", "browser_type": "chrome"},
   "proxy_settings":{"protocol":"<http|https|socks5>","country":"<iso-2-country-code>","mode":"built-in"},
   "credentials": ["<credential-id>"]}'

# 删除配置文件
curl -X DELETE "https://app.nextbrowser.com/api/v1/browser/profiles/<profile-id>" \
  -H "Authorization: x-api-key $API_KEY"

3. 地理位置

地理位置端点提供了用于代理和浏览器配置的可用地理位置元数据。在创建配置文件或在特定网络条件下运行任务之前，可使用这些端点动态发现支持的国家、地区、城市和 ISP。

# 列出国家
curl "https://app.nextbrowser.com/api/v1/location/countries?\
limit=<limit>&\
offset=<offset>&\
name=<name>&\
code=<iso2-code>&\
connection_type=<connection-type>" \
  -H "Authorization: x-api-key $API_KEY"

# 列出地区
curl "https://app.nextbrowser.com/api/v1/location/regions?\
country__code=<iso2-country>&\
limit=<limit>&\
offset=<offset>&\
name=<name>&\
code=<region-code>&\
city__code=<city-code>&\
connection_type=<connection-type>" \
  -H "Authorization: x-api-key $API_KEY"

# 列出城市
curl "https://app.nextbrowser.com/api/v1/location/cities?\
country__code=<iso2-country>&\
limit=<limit>&\
offset=<offset>&\
name=<name>&\
code=<city-code>&\
region__code=<region-code>&\
connection_type=<connection-type>" \
  -H "Authorization: x-api-key $API_KEY"

# 列出 ISP
curl "https://app.nextbrowser.com/api/v1/location/isps?\
country__code=<iso2-country>&\
limit=<limit>&\
offset=<offset>&\
name=<name>&\
code=<isp-code>&\
region__code=<region-code>&\
city__code=<city-code>&\
connection_type=<connection-type>" \
  -H "Authorization: x-api-key $API_KEY"

4. 任务（子代理）

运行自动化浏览器任务——就像一个为您处理浏览器交互的子代理。给它一个提示，它就会完成任务。

始终使用 fast 模式——专为浏览器任务优化，比其他模式快 3-5 倍。
始终将 skip_plan_approval 设为 true——专为自动化任务优化，跳过审批步骤以提高性能。

curl -X POST "https://app.nextbrowser.com/api/v1/chat/tasks" \
  -H "Authorization: x-api-key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_description": "'"\
访问 Reddit.com 账户，检查账户是否已登录（如未登录，使用存储的凭证）。\
在 AI Agents 主题下找到 10 个相关帖子，为其中 8 个点赞，并发布 3 条听起来既愤世嫉俗又有趣的评论，\
就像一位愤世嫉俗且有趣的 Reddit 用户会发的那样。确保评论已发布，如果不确定某条评论是否合适，请请求批准。\
最终，您应该至少浏览了 10 个相关帖子，完成了 8 次点赞，并发布了 3 条评论。"\
"'",
    "mode": "fast",
    "profile_id": "<profile-id>",
    "skip_plan_approval": true
  }'

端点：轮询任务完成状态

curl "https://app.nextbrowser.com/api/v1/chat/tasks/<task-id>" \
  -H "Authorization: x-api-key $API_KEY"

curl "https://app.nextbrowser.com/api/v1/chat/tasks/<task-id>?from_step=3" \
  -H "Authorization: x-api-key $API_KEY"

• 查询参数（可选）：
• from_step: 整数 >= 1。要返回的第一个步骤索引。如果缺失或无效，默认为 1。使用此参数可仅轮询新步骤。

响应示例

{
  "success": true,
  "payload": {
    "status": "finished",
    "output": "任务完成。已浏览 10 个相关帖子，完成 8 次点赞，并发布了 3 条评论。",
    "isSuccess": true,
    "steps": [
      {
        "created_at": "2025-01-01T10:00:00Z",
        "finished_at": "2025-01-01T10:00:05Z",
        "description": "打开了 Reddit 搜索页面",
        "status": "completed",
        "step_number": 1
      }
      // ... 更多从 from_step 开始的步骤
    ],
    "total_steps": 5
  },
  "errors": {},
  "description": "任务获取成功"
}

字段语义

• status: 高级任务状态: "processing" | "finished" | "failed"。
• output: 最终任务输出（如果可用）。
• isSuccess: 如果任务成功完成则为 true，否则为 false。
• steps: 从 from_step（或默认从 1）开始的任务步骤列表。
• step_number: 步骤在任务中的顺序号，在此数组中始终从 1 开始。
• total_steps: 任务的总步骤数，与 from_step 无关。

任务选项

完整 API 参考

所有端点（包括会话、文件、技能和技能市场）请参阅 references/api.md。