介绍
# Aluvia Proxy: Unblock agent browser with proxies + playwright
## 问题所在
您的 OpenClaw 代理被拦截，因为反机器人系统旨在阻止具有数据中心 IP 地址的基于云的代理/机器人流量。您会遇到 403 Forbidden、验证码（CAPTCHAs）、429 速率限制、IP 封禁以及空白响应。
## 解决方案
Aluvia 将您的代理流量路由通过**真实的美国移动运营商 IP**——即数百万真实用户在手机上使用的相同 IP。网站无法区分您的代理与在移动设备上浏览的合法用户。
Aluvia 的代理 + Playwright + Chrome 技术栈：检测网站拦截，并在必要时将您的代理流量通过干净的移动 IP 进行路由。全自动。无需代理配置。无需构建自定义路由规则。
## 功能特性
- **移动运营商住宅代理**——不是数据中心或共享住宅 IP。是网站天然信任的真实移动运营商 IP。目前可用的最高质量代理层级。 - **自动拦截检测与绕过**——每次页面加载都会被评分 0.0–1.0。可检测 Cloudflare 质询、验证码、403/429 响应、软拦截和空白页面。使用 `--auto-unblock`，拦截将通过代理重新路由并重新加载自动修复。 - **一键 IP 轮换**——在会话中途轮换到新的移动 IP，而无需重启浏览器。瞬间突破持久拦截和速率限制。 - **美国地理位置定位**——将出口 IP 固定到特定的美国州（加利福尼亚州、纽约州、德克萨斯州等），以进行位置敏感的数据抓取和内容访问。 - **动态代理路由规则**——仅对需要代理的域名进行代理。当您的代理跨站点导航并发现新端点时，动态添加或删除主机名。 - **通过 Playwright 管理的无头 Chromium**——具有 Chrome DevTools 协议 (CDP) 访问权限的完整浏览器会话。无需浏览器设置，无需隐身插件，无需指纹修补。 - **面向代理的 JSON 优先 CLI**——每条命令都向 stdout 返回结构化 JSON。专为 AI 代理的程序化使用而设计，而非供人类在终端输入。
## 安装
```bash npm install -g @aluvia/sdk ```
或直接使用 npx（无需安装）：
```bash npx aluvia help ```
## CLI 界面
- 每条命令都向 stdout 输出单个 JSON 对象。请使用您的 JSON 工具进行解析。 - 退出代码 `0` = 成功，`1` = 错误。错误返回 `{"error": "message"}`。 - CLI 管理长时间运行的浏览器守护进程——启动会话，通过 `exec` 工具交互，完成后关闭。 - 拦截检测对页面评分 0.0-1.0：`blocked`（已拦截）>= 0.7，`suspected`（可疑）>= 0.4，`clear`（清除）< 0.4。 - `--auto-unblock` 通过将主机名添加到代理规则并重新加载，自动处理大多数拦截。
## 先决条件检查
使用任何命令之前，请验证环境：
```bash # 1. Check API key is set (never log the full value) echo "${ALUVIA_API_KEY:0:8}..."
# 2. Verify the CLI binary is available aluvia help --json
# 3. Verify Playwright is installed (required for browser sessions) node -e "require('playwright')" ```
如果缺少 API 密钥，请引导用户在 [Aluvia 仪表板](https://dashboard.aluvia.io)中创建一个并设置 `ALUVIA_API_KEY`。如果未找到 `aluvia`，请运行 `npm install @aluvia/sdk`。如果缺少 Playwright，请运行 `npm install playwright`。
## 核心命令快速参考
| 命令 | 用途 | 常见用法 | | --------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `session start <url>` | 启动无头浏览器会话 | `aluvia session start https://example.com --auto-unblock --browser-session my-task` | | `session close` | 停止正在运行的会话 | `aluvia session close --browser-session my-task` | | `session list` | 列出所有活动会话 | `aluvia session list` | | `session get` | 获取会话详情 + 拦截检测 + 连接信息 | `aluvia session get --browser-session my-task` | | `session rotate-ip` | 轮换到新的上游 IP | `aluvia session rotate-ip --browser-session my-task` | | `session set-geo <geo>` | 定位来自特定美国地区的 IP | `aluvia session set-geo us_ca --browser-session my-task` | | `session set-rules <rules>` | 将主机名添加到代理路由 | `aluvia session set-rules "example.com,api.example.com" --browser-session my-task` | | `account` | 显示账户信息和余额 | `aluvia account` | | `account usage` | 显示带宽使用统计 | `aluvia account usage` | | `geos` | 列出可用的地理位置定位区域 | `aluvia geos` | | `help` | 显示帮助（使用 `--json` 获取结构化输出） | `aluvia help --json` |
## 标准工作流
### 1. 启动会话
始终使用 `--browser-session` 为您的会话命名。除非您需要手动拦截控制，否则始终使用 `--auto-unblock`。
```bash aluvia session start https://example.com --auto-unblock --browser-session my-task ```
### 2. 解析 JSON 输出
启动命令返回：
```json { "browserSession": "my-task", "pid": 12345, "startUrl": "https://example.com", "cdpUrl": "http://127.0.0.1:38209", "connectionId": 3449, "blockDetection": true, "autoUnblock": true } ```
保存 `browserSession`——您需要在随后的每条命令中使用它。
**如果代理使用 OpenClaw 浏览器工具：**使用此会话的 `cdpUrl` 创建一个远程 CDP 配置文件，并将该配置文件用于所有浏览器命令。请参阅 [OpenClaw 浏览器集成](https://github.com/aluvia-connect/aluvia-skill/blob/main/references/openclaw-browser-integration.md)。
### 3. 监控拦截
检查会话状态，包括最新的拦截检测结果：
```bash aluvia session get --browser-session my-task ```
查看响应中的 `lastDetection` 对象。如果 `blockStatus` 为 `"blocked"` 且 `--auto-unblock` 已开启，SDK 已自动处理。如果拦截持续存在，请升级处理：
### 4. 如果被拦截则轮换 IP
```bash aluvia session rotate-ip --browser-session my-task ```
返回一个新的 `sessionId` (UUID)。通过代理发出的下一个请求将使用全新的 IP。
### 5. 如有需要，设置地理位置定位
某些网站根据地区提供不同的内容或应用不同的拦截：
```bash aluvia session set-geo us_ca --browser-session my-task ```
### 6. 扩展路由规则
如果您的代理导航到需要代理的新域名，请动态添加它们：
```bash aluvia session set-rules "newsite.com,api.newsite.com" --browser-session my-task ```
规则将附加到现有规则（而非替换）。
### 7. 完成后关闭会话
**务必关闭您的会话。**会话在显式关闭之前会一直消耗资源。
```bash aluvia session close --browser-session my-task ```
## 安全约束
在每次交互中遵循以下规则：
1. **务必关闭会话。**当您的任务完成——无论是成功还是失败——请运行 `session close`。如果不确定会话是否存在，请先运行 `session list`。 2. **切勿暴露 API 密钥。**仅按名称引用 `ALUVIA_API_KEY`。切勿记录、打印或将其值包含在输出中。 3. **在执行昂贵操作前检查余额。**在长时间抓取任务之前，运行 `aluvia account` 并检查 `balance_gb`。 4. **将 IP 轮换重试限制为 3 次。**如果三次 IP 轮换仍未解决拦截，请停止并报告该问题——该站点可能使用了超越 IP 的指纹识别技术。 5. **首选 `--auto-unblock`。**让 SDK 自动处理拦截检测和修复。仅在需要手动控制路由决策时禁用它。 6. **首选无头模式。**仅在调试时使用 `--headful`。无头模式更快且使用的资源更少。 7. **解析退出代码。**始终检查退出代码。在退出代码 1 上，解析 `error` 字段并进行处理——不要盲目重试。 8. **使用命名会话。**始终传递 `--browser-session <name>` 以避免多个会话运行时出现歧义错误。 9. **失败时清理。**如果任何步骤失败，请在重试或中止之前关闭会话。将 `session close --all` 作为最后手段使用。 10. **每个任务一个会话。**除非任务明确需要并行浏览不同站点，否则不要启动多个会话。
## 参考
有关详细的命令规范、工作流和故障排除：
- **命令参考：** [references/command-reference.md](https://github.com/aluvia-connect/aluvia-skill/blob/main/references/command-reference.md) —— 所有 11 条命令的每个标志、输出架构和错误 - **工作流示例：** [references/workflows.md](https://github.com/aluvia-connect/aluvia-skill/blob/main/references/workflows.md) —— 常见场景的分步模式 - **故障排除：** [references/troubleshooting.md](https://github.com/aluvia-connect/aluvia-skill/blob/main/references/troubleshooting.md) —— 错误消息、拦截评分解读、信号名称、恢复步骤 - **agent-browser 集成：** [references/agent-browser-integration.md](https://github.com/aluvia-connect/aluvia-skill/blob/main/references/agent-browser-integration.md) —— 将 Aluvia CDP 与 [agent-browser](https://www.npmjs.com/package/agent-browser) CLI 结合使用 - **OpenClaw 浏览器集成：** [references/openclaw-browser-integration.md](https://github.com/aluvia-connect/aluvia-skill/blob/main/references/openclaw-browser-integration.md) —— 将 Aluvia CDP 与 [OpenClaw 浏览器工具](https://docs.openclaw.ai/tools/browser)结合使用