如何设置完整的代理浏览器：将爬虫浏览器技能安装到5个主要AI代理的完整指南

关键要点

• 一个技能，五个代理。 Claude Code、Cursor、VS Code + Copilot、Codex CLI 和 Gemini CLI 都从一小组常规目录中读取相同的 SKILL.md + YAML-frontmatter 格式。
• 一个基础 CLI。 通过一次性运行 npm install -g scrapeless-scraping-browser 和一个 Scrapeless API 密钥，便可以在各个代理中实现该技能。
• 一个令牌，任何代理。 只需使用 scrapeless-scraping-browser config set apiKey … 配置 API 密钥一次——任何调用 CLI 的代理都可以读取相同的存储密钥。
• 为网络构建的代理浏览器。 Scraping Browser 被设计用于动态页面、浏览器交互、验证码阻力、代理路由以及生产级自动化，适用于普通浏览器或静态抓取器无法满足的情境。Scraping Browser 原生解决 reCAPTCHA v2、Cloudflare Turnstile、Cloudflare 5s 挑战和 AWS 挑战——无需额外设置。
• 最佳用于真实代理用例。 当您的代理需要检查仪表板、导航多个步骤、填写表单、收集结构化数据或在布局变化的网站之间操作时，这尤其有用。

介绍：代理技能是新的安装目标

AI 代理正在从简单的文本生成转向真实的网页执行。在这一转变中，浏览器不再只是一个显示表面；它变成了一个操作层，代理可以在其中观察页面，推理状态，并跨站点采取行动。这就是为什么“代理浏览器”这一术语很重要：它描述了一个能够以一定自主性执行多步骤任务的浏览器环境，而不是等待人类点击每一步。

现代 AI 编码代理——Claude Code、Cursor、VS Code + GitHub Copilot、OpenAI Codex CLI 和 Gemini CLI——都支持代理技能：这些即插即用的包可以按需教会代理新的能力。生态系统已经趋向于单一的包装格式（SKILL.md 及其 YAML 前言），因此同一技能文件夹可以在上述每个代理中以最小的修改工作。

这也是 Scrapeless 自然切入的地方。scrapeless-Agent-browser 被定位为代理逻辑与可靠浏览器执行之间的桥梁，它让代理驱动 Scrapeless Scraping Browser——一个可定制的、反检测的云浏览器，专为网络自动化和 AI 代理而生——来打开页面、提取数据、填写表单、通过住宅代理路由流量，并处理验证码，所有这些都无需编写低级浏览器自动化代码。

本指南展示了如何将 Scrapeless Scraping Browser 技能安装到 5 个主要代理环境中，同时在它们之间保持相同的基础浏览器。

为什么代理浏览器很重要

传统的浏览器自动化常常在真实用户每天遇到的同样事务上中断：动态 JavaScript、反机器人检查、会话状态、地理敏感内容和快速变化的布局。代理浏览器通过为代理提供一个旨在交互、持久性和网页变化的浏览器，而不仅仅是页面渲染，来解决这个问题。对于构建生产工作流程的团队来说，这减少了在导航、重试和页面状态处理周围所需的胶水代码量。

对于许多公司来说，浏览器本身现在是数据的接口。代理浏览器可以读取仪表板、移动到认证门户、收集定价或可用性信号、验证账户状态，并完成耗费昂贵的端到端硬编码的网页任务。当这些工作流程需要可靠的基础设施、代理控制和大规模可靠执行时，Scrapeless 的浏览器层特别相关。

您可以用它做什么

安装后，代理获得了完整的 Scrapeless Scraping Browser 功能：

• 在 Scrapeless Scraping Browser 中打开任何 URL，并通过 snapshot -i 发现 DOM。
• 通过短 @e1、@e2 可访问性树引用或标准 CSS 选择器与元素交互。
• 填写表单、点击按钮、上传文件、截图、下载 PDF。
• 按国家、州或城市通过住宅代理路由流量。
• 配置每个会话的桌面指纹：平台（Windows、macOS、Linux）、时区、语言和屏幕尺寸。
• 记录会话以便后续在 Scrapeless 仪表板中查看，并打开实时视图进行实时检查。

当用户说诸如“从 Hacker News 抓取前五个帖子”、“登录此网站并截图仪表板”或“用我的简历填写此职位申请并在最后提交前停止”时，代理会自动触发该技能。

为什么选择 Scrapeless

Scrapeless Scraping Browser 处理网页自动化中通常需要数周工程时间的部分：

• 反检测内置——Scrapeless的产品页面将其描述为*“可定制的、反检测的云浏览器，由自开发的Chromium提供支持。”*
• 住宅代理覆盖195多个国家，按会话选择。
• 自动解决 CAPTCHA，支持reCAPTCHA v2、Cloudflare Turnstile、Cloudflare 5秒挑战和AWS挑战（支持列表）；这四种以外的任何内容均由单独的Scrapeless CAPTCHA Solver产品覆盖。
• 会话录制和实时查看，用于实时检查和调试生产运行。
• 与Puppeteer和Playwright的协议兼容性，通过Scrapeless SDK实现。

相关产品：通用抓取API、代理解决方案以及用于模型上下文协议集成的Scrapeless MCP服务器。

技能格式

本指南中的每个代理读取技能的格式相同：

<skills-dir>/scrapeless-scraping-browser/
├── SKILL.md          # YAML前置信息 + 指令（必需）
├── skill.json        # 丰富的元数据（可选，但推荐）
├── SECURITY.md       # 安全注意事项（可选）
└── references/
    └── authentication.md

SKILL.md前置信息告诉代理技能的功能和何时触发：

---
name: scrapeless-scraping-browser
description: 基于Scrapeless的云浏览器自动化CLI，供AI代理使用。当用户需要使用云浏览器与网站交互时，包括导航页面、填写表单、点击按钮、截图、提取数据、测试web应用或使用住宅代理和反检测功能自动化任何浏览器任务时使用。触发条件包括请求“打开网站”、“填写表单”、“点击按钮”、“截图”、“从页面抓取数据”、“测试这个web应用”、“使用代理”、“绕过检测”或任何需要云浏览器自动化的任务。
allowed-tools: Bash(npx scrapeless-scraping-browser-skills scrapeless-scraping-browser:*), Bash(scrapeless-scraping-browser:*)
---

代理之间主要的不同之处在于技能文件夹放置的位置、代理如何在启动时发现它以及每个代理实际读取的可选前置信息字段（核心的name + description是通用的）。

先决条件

在将技能安装到任何代理之前，先设置基础CLI和凭证——只需一次。

1. 安装Node.js 18或更高版本

从nodejs.org下载，或通过版本管理工具（nvm、fnm、volta）安装。

2. 全局安装Scrapeless抓取浏览器CLI

npm install -g scrapeless-scraping-browser

验证：

scrapeless-scraping-browser version

3. 获取Scrapeless API密钥

1. 在app.scrapeless.com注册，以便您可以立即开始使用抓取浏览器。
2. 从仪表板生成API令牌。

4. 配置API密钥

选择以下方法之一。

选项A — 配置文件（推荐，持久，跨代理）：

scrapeless-scraping-browser config set apiKey your_api_token_here
scrapeless-scraping-browser config get apiKey   # 验证

这会将密钥存储在您主目录的~/.scrapeless/config.json中。

选项B — 环境变量：

# macOS / Linux
export SCRAPELESS_API_KEY=your_api_token_here

# Windows PowerShell
$env:SCRAPELESS_API_KEY="your_api_token_here"

将该行添加到~/.zshrc、~/.bashrc或您的Windows环境变量中，以便在会话之间持续使用。

注意：当同时设置配置文件和环境变量时，配置文件的优先级高于环境变量。仅从环境中读取SCRAPELESS_API_KEY——Scrapeless MCP服务器使用不同的变量（SCRAPELESS_KEY），与此技能无关。

5. 下载技能包

克隆技能包：

git clone https://github.com/scrapeless-ai/scrapeless-agent-browser.git
cd scrapeless-agent-browser/skills/scraping-browser-skill

以下步骤将此文件夹的内容复制到每个代理的技能目录中。

步骤1 — 安装到Claude Code（Anthropic）

技能目录

• 全局：~/.claude/skills/scrapeless-scraping-browser/
• 项目：<repo>/.claude/skills/scrapeless-scraping-browser/

安装（全局，macOS / Linux）

mkdir -p ~/.claude/skills/scrapeless-scraping-browser
cp -r ./* ~/.claude/skills/scrapeless-scraping-browser/

安装（全局，Windows PowerShell）

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\scrapeless-scraping-browser"
Copy-Item -Recurse -Force .\* "$HOME\.claude\skills\scrapeless-scraping-browser\"

激活： Claude Code 会实时识别已有 ~/.claude/skills/ 中的技能变更（无需重启）。如果启动会话时顶级 ~/.claude/skills/ 目录不存在，则首次安装时需执行此操作——在这种情况下，请重启任何正在运行的 claude 会话一次。

验证： 在 Claude Code 中询问 “有哪些技能可用？” — Anthropic 的技能故障排除文档明确指出这个提示作为清单检查 (源)。或者运行类似 “打开 example.com 并截图首页” 的触发提示，Claude 将调用 SKILL.md 中记录的技能命令。

第 2 步 — 安装到 Cursor

最低版本： Cursor 2.4 或更新版本（代理技能在 2.4 版本中发布，2026 年 1 月）。

技能目录

• 全局（规范）： ~/.agents/skills/scrapeless-scraping-browser/
• 全局（也可接受）： ~/.cursor/skills/、~/.claude/skills/、~/.codex/skills/
• 项目（规范）： <repo>/.agents/skills/scrapeless-scraping-browser/
• 项目（也可接受）： <repo>/.cursor/skills/、<repo>/.claude/skills/、<repo>/.codex/skills/

安装（全局，规范路径）

mkdir -p ~/.agents/skills/scrapeless-scraping-browser
cp -r ./* ~/.agents/skills/scrapeless-scraping-browser/

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.agents\skills\scrapeless-scraping-browser"
Copy-Item -Recurse -Force .\* "$HOME\.agents\skills\scrapeless-scraping-browser\"

激活： “当 Cursor 启动时，它会自动发现技能目录中的技能，并将其提供给代理。” （Cursor 文档）

验证： 打开 Cursor 设置（Cmd/Ctrl+Shift+J）→ 规则 — scrapeless-scraping-browser 出现在 代理决定 下。或者在代理聊天中输入 / 查看斜杠命令选择器中的技能。或者提示 “将 news.ycombinator.com 中的前 5 个故事提取为 JSON” — 代理应自动链式调用技能的命令（new-session → open → get html → eval）.

第 3 步 — 安装到 VS Code + GitHub Copilot

GitHub Copilot 于 2025 年 12 月添加了代理技能支持（变更日志）。VS Code 中的 Copilot 自动发现来自三个位置系列的技能：

• 全局（个人）： ~/.copilot/skills/、~/.claude/skills/、或 ~/.agents/skills/
• 项目（Copilot 原生）： <repo>/.github/skills/scrapeless-scraping-browser/
• 项目（跨代理）： <repo>/.claude/skills/... 或 <repo>/.agents/skills/...

前言说明： Copilot 仅需要 name 和 description；allowed-tools 和 license 是可选的。GitHub 的 Copilot 技能文档 逐字说明： “在您的 SKILL.md 前言中，您可以使用 allowed-tools 字段列出 Copilot 可以使用而无需每次确认的工具。” 在授予预先批准之前请先查看技能源代码。

安装（全局，macOS / Linux）

mkdir -p ~/.copilot/skills/scrapeless-scraping-browser
cp -r ./* ~/.copilot/skills/scrapeless-scraping-browser/

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.copilot\skills\scrapeless-scraping-browser"
Copy-Item -Recurse -Force .\* "$HOME\.copilot\skills\scrapeless-scraping-browser\"

安装（项目级，推荐团队使用）

cd <your-repo>
mkdir -p .github/skills/scrapeless-scraping-browser
cp -r /path/to/skill/* .github/skills/scrapeless-scraping-browser/
git add .github/skills/scrapeless-scraping-browser
git commit -m "添加 scrapeless-scraping-browser 技能"

激活： 根据 GitHub 的 2025 年 12 月 18 日变更日志，Copilot 会在受支持的目录中自动识别技能，而无需额外配置。技能内容仅在与任务相关时逐步加载。

验证： 打开 Copilot 聊天并输入 /skills — 根据 VS Code 的 Copilot 技能文档，此操作“可以快速打开 配置技能 菜单”，其中应出现 scrapeless-scraping-browser。或者提示 “从此 URL 抓取产品价格” / “截图 example.com”，观察 Copilot 调用技能。

第 4 步 — 安装到 OpenAI Codex CLI

最低版本： 任何文档化代理技能的 Codex CLI 构建 — 为了安全起见，请更新到最新的 codex CLI （Codex 技能文档）。

技能目录

• 全局：$HOME/.agents/skills/scrapeless-scraping-browser/ — 文档化的用户范围。
• 项目：$CWD/.agents/skills/，任何父目录的 .agents/skills/，或 $REPO_ROOT/.agents/skills/。Codex 从 CWD 向上到仓库根目录进行查找。
• ~/.codex/skills/ 不会被自动发现 — 如果希望 Codex 从那里读取，请在 ~/.codex/config.toml 中的 [[skills.config]] 下以绝对路径明确注册，例如 path = "/home/<you>/.codex/skills/scrapeless-scraping-browser/SKILL.md"（Codex 文档在 [[skills.config]] 示例中显示绝对路径 — 在 TOML 中的波浪线展开未被记录）。

安装（全局）

mkdir -p ~/.agents/skills/scrapeless-scraping-browser
cp -r ./* ~/.agents/skills/scrapeless-scraping-browser/

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.agents\skills\scrapeless-scraping-browser"
Copy-Item -Recurse -Force .\* "$HOME\.agents\skills\scrapeless-scraping-browser\"

激活： “Codex 自动检测技能变化。如果更新未出现，请重启 Codex。” （Codex 技能文档）

验证： 在 Codex 提示符下，运行 /skills 列出可用技能。直接通过在消息中输入 $scrapeless-scraping-browser 调用技能，或用 “在 example.com/signup 填写注册表单并在最终提交前停止” 测试自动触发。

第5步 — 安装到 Gemini CLI（Google）

技能目录

• 全局：~/.gemini/skills/scrapeless-scraping-browser/ — ~/.agents/skills/ 是一个正式文档化的别名，当两个目录都存在时，其优先于 ~/.gemini/skills/。
• 项目：<repo>/.gemini/skills/scrapeless-scraping-browser/ — 或使用别名 <repo>/.agents/skills/。

安装

mkdir -p ~/.gemini/skills/scrapeless-scraping-browser
cp -r ./* ~/.gemini/skills/scrapeless-scraping-browser/

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.gemini\skills\scrapeless-scraping-browser"
Copy-Item -Recurse -Force .\* "$HOME\.gemini\skills\scrapeless-scraping-browser\"

激活： 在会话中运行 /skills reload 刷新来自所有层级发掘的技能列表（Gemini CLI 技能文档）。

验证： 在 Gemini CLI 会话内运行 /skills list — scrapeless-scraping-browser 应出现在发现的列表中。然后测试 “通过东京的住宅代理打开 booking.com，并拉取 6 月 15-18 日的前 5 家酒店”；模型在运行技能命令前将请求激活。

第6步 — 一个技能，所有代理（符号链接技巧）

如果您使用多个代理并且不想将技能复制到 N 个目录中，请安装一次并为其余的创建符号链接。

macOS / Linux

# 作为真相源安装一次：
mkdir -p ~/.agents/skills/scrapeless-scraping-browser
cp -r ./* ~/.agents/skills/scrapeless-scraping-browser/

# 为每个其他代理创建符号链接：
ln -s ~/.agents/skills/scrapeless-scraping-browser ~/.claude/skills/scrapeless-scraping-browser
ln -s ~/.agents/skills/scrapeless-scraping-browser ~/.cursor/skills/scrapeless-scraping-browser
ln -s ~/.agents/skills/scrapeless-scraping-browser ~/.copilot/skills/scrapeless-scraping-browser
ln -s ~/.agents/skills/scrapeless-scraping-browser ~/.gemini/skills/scrapeless-scraping-browser

现在更新源时，每个代理会同时更新。

Windows PowerShell — 在启用开发者模式的 Windows 10/11 上（在 Windows 11 25H2+ 上的 设置 → 系统 → 高级 → 开发者；在早期版本直接访问 开发者 页面），符号链接在没有提升的情况下工作。否则以管理员身份运行 PowerShell。请参见 微软的开发者模式文档。

$src = "$HOME\.agents\skills\scrapeless-scraping-browser"
"claude","cursor","copilot","gemini" | ForEach-Object {
  $dest = "$HOME\.$_\skills\scrapeless-scraping-browser"
  New-Item -ItemType Directory -Force -Path (Split-Path $dest)
  New-Item -ItemType SymbolicLink -Path $dest -Target $src
}

第7步 — 项目级别与全局：选择哪个

第 8 步 — 故障排除常见问题

复制后技能未出现。 每个代理的刷新路径不同：Claude Code — 文档 说在会话开始后创建的顶级 ~/.claude/skills/ 目录需要重启 claude；现有目录中的更改会实时更新。Codex — 文档 说 “Codex 会自动检测技能变化。如果更新未出现，请重启 Codex。” Gemini CLI — 在会话中运行 /skills reload。Cursor 和 VS Code / Copilot — 他们的文档描述了启动时的自动发现；如果缺少某个技能，请重启编辑器。

代理表示 SCRAPELESS_API_KEY 是必需的。 密钥不在代理进程的环境中。首选配置文件方法（scrapeless-scraping-browser config set apiKey ...） — 这种方法与进程无关，并且适用于所有代理。

触发器未自动触发。 打开安装位置中的 SKILL.md 并检查前言 description — 代理使用它作为路由信号。将用户措辞添加到 skill.json 的 triggers 列表中，以扩展匹配。

结论

智能代理浏览器正成为网络重型自动化的实际默认选项，Scrapeless 通过提供一个代理可以真正依赖的云浏览器层来适应这一趋势。如果您的工作流程依赖于导航、交互、动态内容或基于浏览器的数据访问，Scrapeless Scraping Browser 技能是一个强大的基础。主要优势很简单：您只需安装一次浏览器技能，然后在多个主要代理中重复使用，而不必每次都重建执行层。scrapeless-agent-browser 存储库 将浏览器执行打包成可重用的代理层，而不是将浏览器视为一次性脚本依赖关系。

请关注我们即将推出的博客指南中的更多实践用例。现在，加入官方 Scrapeless 社区，获取最新更新并申请访问您的 免费计划！
Discord
Telegram

常见问题

Q1: 我是否需要为每个代理配置单独的 API 密钥？
不需要。只需通过 scrapeless-scraping-browser config set apiKey ... 配置一次 Scrapeless API 密钥，每个运行 CLI 的代理会自动获取。

Q2: 我可以在项目级别使用该技能并将其提交到我的仓库吗？
可以。该指南中的每个代理都支持项目级别的技能目录（例如 <repo>/.claude/skills/、<repo>/.github/skills/、<repo>/.agents/skills/）。提交该技能后，所有克隆该仓库的团队成员都可以使用。

Q3: 如果我已经安装了技能，我还需要安装 scrapeless-scraping-browser npm 包吗？
需要 — 该技能是代理的指令层；npm 包是它驱动的 CLI。CLI 必须对代理可访问，既可以全局安装（npm install -g scrapeless-scraping-browser），也可以通过 npx scrapeless-scraping-browser … 调用。

Q4: 该技能如何处理 CAPTCHA？
Scraping Browser 开箱即用地自动解决四种 CAPTCHA 类型 — reCaptcha v2、Cloudflare Turnstile、Cloudflare 5 秒挑战以及 AWS 挑战（官方支持列表）。文档中指出 “后续操作需要您自己实现” — 浏览器解决，您的代码（或代理）决定接下来发生什么。对于这四种类型以外的任何东西，Scrapeless CAPTCHA Solver 是一款单独的产品。

Q5: 可以将该技能与 Puppeteer 或 Playwright 代码一起使用吗？
可以。Scrapeless Scraping Browser 在协议上与 Puppeteer 和 Playwright 兼容，详见 Scrapeless Scraping Browser 文档，因此代理可以将以技能驱动的会话与现有自动化脚本相结合。