把dots同款反检测浏览器接入Claude Code、Codex与Gemini CLI：MCP完整使用教程
【免费下载链接】dotsOpen-source dots for the web: an AI agent with its own browser, one that does not get blocked.项目地址: https://gitcode.com/gh_mirrors/dots140/dots
dots是一款开源 AI 智能体（web agent），它的核心是一台"不会被拦"的反检测浏览器：真实 Firefox 引擎、C++ 层指纹伪装、人机一致的键鼠事件。更关键的是，dots 可以把这台同款反检测浏览器以MCP 服务器的形式挂出来，让你手里的 Claude Code、Codex、Gemini CLI 直接"借"到它的手和眼。本文是一份面向新手的 dots MCP 完整教程：从一键安装，到把 dots 同款反检测浏览器接入三大 AI 编程助手，最后附上参数速查与排错指南。
一、dots 是什么？为什么"浏览器"才是关键 🧠
先说结论：当网页智能体（web agent）失败时，原因通常不在模型，而在浏览器。页面根本没加载、弹出人机验证挑战、登录过期、点击没有生效——这些事情都发生在"模型开始思考"之前。
"每一个 AI 智能体 = 一个模型 + 一个浏览器。模型用一个参数就能换，但网站看到的，是浏览器。" —— 项目口号，见 README.md
dots 把"浏览器"当成第一公民来构建：
- 真实 Firefox 引擎，C++ 层打补丁：指纹（fingerprint）在引擎内部决定，而不是画一层 JavaScript 上去——网页能直接检测 JS 层的伪装；
- 一个种子一个身份：屏幕分辨率、字体、GPU、时区、语言彼此自洽，
--seed让你在每次运行时拿到"同一个人"； - 页面上没有可被发现的痕迹：没有 WebDriver 标志、没有 DevTools 协议、没有自动化全局变量；
- 像真人一样操作：指针会移动到点击目标，按键逐个按下，页面收到的每一个事件都是"可信事件"；
- 有记忆的浏览器：
--profile-dir让登录态和 cookie 跨运行保留； - 出口即身份：
--proxy配置代理后，时区和语言自动跟随出口节点。
而模型层是开放的：任何 OpenRouter 上的模型都可以用，--model随时切换。
👉 完整功能说明见 README.md，项目元数据与依赖见 pyproject.toml。
二、dots 与 MCP 的关系：一句话讲清 🔌
很多读者会问：dots 到底是个什么程序？看源码会发现它出奇地"薄"：
- 入口：main.py 只调用一行
main()； - 实现：cli.py 把参数原样转发给
invisible-playwright-mcp包里的ui子命令； - 依赖：pyproject.toml 中唯一的依赖就是精确锁定的
invisible-playwright-mcp==0.70.2。
所以关系是这样的：
| 角色 | 说明 |
|---|---|
invisible-playwright-mcp | 真正的"大脑"：MCP 服务器 + 反检测浏览器 + 智能体循环 |
dots | 它的人类接口：跑起来是一个 Web 控制台（对话在左、浏览器在右），dots --help列出全部选项 |
| 你的 AI 助手 | Claude Code / Codex / Gemini CLI 作为MCP 客户端，接入同一台浏览器 |
一句话：
dots是你亲自对话用的界面；MCP 服务器是让 AI 助手对话用的接口。两者共用同一个浏览器、同一套反检测能力。
这也解释了 pyproject.toml 里那句注释："dots 就是 invisible-playwright-mcp 的界面，仅此而已"——你学 dots，等于把整个 MCP 生态的用法都学会了。
三、一键安装 dots 反检测浏览器（uvx 方式）⚡
dots 没有发布到 PyPI（PyPI 上同名的是另一个无关项目），所以官方推荐用 uv 的uvx从源码仓库直接拉起。
Linux / macOS 安装步骤
# 1. 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh source $HOME/.local/bin/env # 2. 启动 dots（填入你的 OpenRouter 密钥） uvx --from git+https://github.com/feder-cr/dots dots --openrouter-key sk-or-...Windows（PowerShell）安装步骤
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" $env:Path = "$env:USERPROFILE\.local\bin;$env:Path" uvx --from git+https://github.com/feder-cr/dots dots --openrouter-key sk-or-...启动后，打开http://127.0.0.1:8765，就能看到：左边是 AI 对话窗口，右边是活着的浏览器。
💡 三个小贴士：
- 密钥不想写在命令行？放在工作目录的
.env文件里即可——cli.py 的注释明确说明：dots 特意走invisible-playwright-mcp的命令组（command group）而不是直接调ui，就是为了让它读到.env、并正确继承旧的会话目录； - 想确认自己装的环境没被本地代码"污染"？项目自带一个测试：test_entry.py 会校验安装的包版本与锁定版本完全一致；
- 忘了带密钥会直接拒绝启动（报错提示
OpenRouter），见 test_entry.py 的行为定义，不用浪费时间排查。
四、接入 Claude Code：MCP 完整配置方法 📌
Claude Code 是 MCP 客户端，给它添加一个 stdio 服务器即可。dots 同款反检测浏览器由invisible_playwright_mcp包提供服务器入口：
方式 A：命令行添加（最快配置方法）
claude mcp add dots -- \ uvx --from git+https://github.com/feder-cr/invisible_playwright_mcp \ invisible-playwright-mcp --openrouter-key sk-or-...方式 B：写入配置文件
在~/.claude.json的mcpServers节点中追加：
{ "mcpServers": { "dots": { "command": "uvx", "args": ["--from", "git+https://github.com/feder-cr/invisible_playwright_mcp", "invisible-playwright-mcp"], "env": { "OPENROUTER_API_KEY": "sk-or-..." } } } }配置完成后，在 Claude Code 会话里输入/mcp，应能看到dots服务器连接成功，并列出浏览器操作相关的工具。此时 Claude 就"长出了手"：它可以直接打开网页、点击、输入、读取页面内容——而且用的是那台不会被拦的浏览器。
五、接入 Codex CLI：MCP 服务器配置方法 📌
Codex 支持在~/.codex/config.toml中声明 MCP 服务器：
[mcp_servers.dots] command = "uvx" args = ["--from", "git+https://github.com/feder-cr/invisible_playwright_mcp", "invisible-playwright-mcp"] [mcp_servers.dots.env] OPENROUTER_API_KEY = "sk-or-..."如果你的 Codex 版本支持
codex mcp add子命令，用法与 Claude Code 类似，直接传入上面的uvx命令即可。
添加后重启 Codex，它即可通过 MCP 协议调用反检测浏览器完成需要"上网"的子任务，例如抓取动态渲染页面、操作登录后的管理后台。
六、接入 Gemini CLI：settings.json 配置方法 📌
Gemini CLI 在~/.gemini/settings.json中配置 MCP：
{ "mcpServers": { "dots": { "command": "uvx", "args": ["--from", "git+https://github.com/feder-cr/invisible_playwright_mcp", "invisible-playwright-mcp"], "env": { "OPENROUTER_API_KEY": "sk-or-..." } } } }三个客户端的配置本质相同：一条uvx命令 + 一个模型密钥。区别只在于配置文件的格式与位置。
七、参数速查表：让 MCP 浏览器与 dots 保持同一身份 🔑
dots --help会列出全部选项。下面是最常用的几个，MCP 侧同理：
| 参数 | 作用 | 使用场景 |
|---|---|---|
--seed | 指纹种子：同一 seed = 同一个"人"，屏幕/字体/GPU/时区/语言完全一致 | 让 Claude Code 与 dots 控制台看起来是同一个人 |
--profile-dir | 浏览器档案目录，跨运行保留登录与 cookie | 一次登录，AI 助手长期复用登录态 |
--proxy | 出口代理，时区与语言自动跟随出口 | 让"从哪连接"与身份匹配 |
--model | 指定 OpenRouter 上的任意模型 | 按任务成本/能力切换大脑 |
--openrouter-key | 模型密钥，也可写入.env | 所有场景必需 |
--port | Web 控制台端口（默认 8765） | 多实例并存 |
--headed | 有头模式，可见浏览器窗口 | 调试时"看着它操作" |
保持一致身份的最佳实践：
- 先运行一次
dots --seed 42 --profile-dir ./my-profile，完成需要的人工登录； - 配置 MCP 服务器时传入相同的 seed 与 profile；
- 从此你的 AI 助手与 dots 控制台共享同一套指纹、同一套登录态——网站只会觉得"这就是同一个人"。
八、实战：让 AI 助手替你查机票 ✈️
项目给出的标准示范任务（见 README.md），非常适合拿来验证 MCP 是否接通：
打开某航空官网。查米兰 → 里斯本、经济舱、1 位成人，把下月 12 号到 16 号每一天都看一遍，读出每天最便宜的票价；某天没有舱位就直说，不许猜数字。
把它原样发给接入 dots MCP 的 Claude Code / Codex / Gemini CLI，你会看到它在浏览器里逐日切换日期、读取票价、汇总成表——全程没有任何挑战页拦截（前提是目标站没有针对你的出口 IP 做限制）。
给新手三条"提问姿势"建议：
- 说清验收标准："每天最便宜的价格 + 链接"，比"帮我看看机票"有效得多；
- 要求"查不到就直说"：能显著减少模型幻觉；
- 登录类任务先人工登一次：配合
--profile-dir保留会话，AI 只负责"登录后"的步骤。
九、常见问题排查清单（FAQ）🛠️
| 现象 | 原因 | 解决办法 |
|---|---|---|
启动即报错，提示OpenRouter | 没有模型密钥 | 传--openrouter-key，或把密钥写入工作目录.env（dots 走命令组加载，见 cli.py） |
| MCP 连上但操作被站点拦截 | 站点风控/挑战页 | 换--proxy出口、确认 seed 身份与出口匹配、必要时先人工过一次挑战 |
| 登录态丢了 | 每次用了不同的 profile | 固定--profile-dir，所有入口（dots / MCP / AI 助手）共用 |
| 不同运行"像换了个人" | 每次 seed 不同 | 固定--seed，指纹各维度才会自洽 |
| 端口 8765 被占用 | 已有实例在跑 | 换--port，或先停掉旧进程 |
| 想核对环境是否纯净 | 本地 editable 安装会干扰 | 跑一遍测试：pytest tests/test_entry.py（含版本锁定校验，见 test_entry.py） |
十、小结 🎯
- dots = 一台不会被拦的反检测浏览器 + AI 智能体，指纹在 C++ 引擎层决定，真人式事件，支持种子身份、档案记忆与代理出口；
- dots 本身是
invisible-playwright-mcp的界面（见 cli.py），dots --help就是完整参数手册； - 接入你的 AI 助手只需三步：装好 uv → 在客户端的 MCP 配置里加一条
uvx命令 → 填上 OpenRouter 密钥； - 想让 Claude Code、Codex、Gemini CLI 与 dots 控制台共用同一个身份，就固定
--seed+--profile-dir。
现在，你的 AI 助手已经"长出"了一双手，而那只手，是网站拦不下来的。
【免费下载链接】dotsOpen-source dots for the web: an AI agent with its own browser, one that does not get blocked.项目地址: https://gitcode.com/gh_mirrors/dots140/dots
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
