1. 为什么浏览器智能需要 MCP 这层“翻译官”
浏览器智能这个词听起来很玄，落到工程里其实就一句话：让大模型能真正操作页面，而不是只会在聊天框里输出文字。我最早做前端自动化时用的是 Puppeteer，写一堆page.click('#submit')这样的硬编码选择器，页面一改版脚本就全废。后来想接大模型，又发现每个 AI 客户端（Claude Desktop、Cursor、Cline）的接入方式都不一样，光适配就够喝一壶。
MCP（Model Context Protocol）解决的正是这个“适配地狱”。你可以把它理解成 AI 客户端和工具之间的 USB-C 接口：客户端只管按协议发工具调用请求，工具侧只管按协议返回结果，中间谁也不用关心对方内部怎么实现。Page Agent 就是把这套协议用在浏览器控制上的一个典型实践——它把“打开标签页、填表单、抓数据”这些浏览器操作封装成 MCP 工具，AI 客户端通过自然语言就能驱动。
这套架构适合谁？三类人值得看：一是做 AI 原生应用的前端，想让 Agent 接管页面交互；二是做自动化测试或数据采集的工程师，受够了选择器维护；三是想在自己项目里接多模型能力、又不想为每个模型写一套适配的开发者。本文会从架构分层讲到可复制的配置，重点演示用 TaoToken 统一 Key 接入多模型时，怎么从local proxy failed一路排到成功调用。核心检索词就三个：MCP 协议、Page Agent、浏览器智能架构。
先说清楚 Page Agent 的分层设计，不然后面配置容易懵。它整体是四层解耦：AI 客户端层负责收自然语言指令；MCP 服务层处理 stdio 通信，同时起 HTTP + WebSocket 服务；扩展枢纽层（Hub Tab）是浏览器扩展里的一个独立标签页，做协议隔离；执行层（MultiPage Agent）真正调浏览器 API 干活。四层之间只靠标准协议通信，改一层不影响其他层。
为什么 Hub Tab 要单独存在，而不是让扩展后台脚本直接通信？因为浏览器会回收后台脚本，长任务跑到一半可能就断了。Hub Tab 是个真实标签页，生命周期稳定，还能顺便做个可视化状态面板。这个设计细节很关键，很多自己搭类似方案的人卡在“任务执行到一半没反应”，八成就是后台脚本被回收了。
MCP 服务层这边，Page Agent 用的是纯 ESM、无构建步骤的设计，源码直接跑。它的目录结构大致是src/index.js做 CLI 入口和 MCP 协议解析，hub-bridge.js做 HTTP 服务和 WebSocket 桥接，launcher.html做扩展检测引导页。无构建的好处是调试时改完源码直接node跑，不用等 webpack。对工具类库来说，这个取舍很值。
理解了分层，你就能明白为什么配置里既有LLM_BASE_URL又有PORT：前者是给执行层解析自然语言用的模型通道，后者是 MCP 服务层和 Hub Tab 之间的通信端口。两者解耦，换模型不用动端口，换端口不用动模型。这也是后面用 TaoToken 统一 Key 能一把接多个模型的基础。
2. TaoToken 统一 Key 的前置准备与 endpoint 选择
在动手配 Page Agent 之前，得先把模型通道这块理顺。Page Agent 的执行层需要调用一个兼容 OpenAI 格式的 LLM 来把自然语言任务解析成分步操作，所以你需要一个能提供 OpenAI 兼容接口的通道。TaoToken 在这里的价值就是统一 Key：一个 Key 走通多个模型，不用为通义、Claude、GPT 各维护一套密钥和 base_url。
先明确几个地址，后面配置会反复用到。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基础地址是 https://taotoken.net/api ，注意这个 API 地址后面不加任何查询参数，配置里就写这个干净的 base。模型对话页面在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，想先手动验证模型通不通可以去这里试。API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
前置条件清单先过一遍：Node.js 版本要 >= 20，因为 Page Agent 的 MCP 包是纯 ESM，低版本对 ESM 支持不完善容易报模块加载错误；Chrome 浏览器装好 Page Agent 扩展，并且给它“所有网站的访问权限”，否则执行层调不动页面；一个 TaoToken 的 API Key，去上面那个 api-keys 页面生成。
关于 endpoint 的选择，有个坑要提前说。Page Agent 的LLM_BASE_URL需要的是“兼容 OpenAI 格式”的地址，也就是最终请求会打到{base_url}/chat/completions。TaoToken 的 API 基础地址是https://taotoken.net/api，所以配置里LLM_BASE_URL就填这个，不要自己再拼/v1或者/chat/completions，拼错了就是 404。我见过有人填成https://taotoken.net/api/v1，结果请求变成/api/v1/chat/completions，直接 404，排查半天。
模型 ID 这块，TaoToken 支持多个模型，你在模型对话页面能看到当前可用的模型列表。Page Agent 的LLM_MODEL_NAME填你选定的模型 ID 就行。建议先用一个你熟悉的模型跑通链路，比如通义系列或者 Claude 系列，跑通后再换其他模型验证统一 Key 的便利性。换模型时只改LLM_MODEL_NAME一个字段，base_url 和 key 都不动，这就是统一 Key 的意义。
还有一点，TaoToken 的 Key 是敏感信息，别硬编码进提交到 git 的配置文件里。本地调试可以用环境变量，或者放在不纳入版本管理的本地配置文件里。Page Agent 的 MCP 配置支持env字段注入环境变量，这个后面配置片段里会体现。如果你在团队里协作，建议把 Key 放到团队的密钥管理里，配置文件里只留占位符。
最后确认一下网络环境：Page Agent 的 MCP 服务层会在本地起 HTTP + WebSocket 服务，默认端口 38401，Launcher 页面和 Hub Tab 都跑在 localhost。这个本地服务只监听本机，不涉及对外暴露，所以不用担心端口安全问题。但如果 38401 被占用了，得通过PORT环境变量改，这个后面排障章节会细说。
3. 可复制的 MCP 配置片段与 auth.json 写法
这一节是全文最该收藏的部分，直接给可复制的配置。Page Agent 接入不同 AI 客户端，配置位置不一样，但核心字段就三个：LLM_BASE_URL、LLM_API_KEY、LLM_MODEL_NAME。下面按客户端分别给。
先看 Claude Desktop 的配置。文件路径在 macOS 上是~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上是%APPDATA%\Claude\claude_desktop_config.json。内容如下：
{ "mcpServers": { "page-agent": { "command": "npx", "args": ["-y", "@page-agent/mcp"], "env": { "LLM_BASE_URL": "https://taotoken.net/api", "LLM_API_KEY": "sk-你的TaoToken密钥", "LLM_MODEL_NAME": "qwen3.5-plus", "PORT": "38401" } } } }这里LLM_BASE_URL填的是https://taotoken.net/api，不带尾斜杠，不带/v1。LLM_API_KEY换成你在 TaoToken api-keys 页面生成的 Key。LLM_MODEL_NAME先填一个你确认可用的模型 ID。PORT不写也行，默认就是 38401，写出来是为了后面排障时方便改。
再看 Cursor 的配置。Cursor 的 MCP 配置在设置里的 MCP 面板，或者直接编辑~/.cursor/mcp.json。结构和 Claude Desktop 基本一致：
{ "mcpServers": { "page-agent": { "command": "npx", "args": ["-y", "@page-agent/mcp"], "env": { "LLM_BASE_URL": "https://taotoken.net/api", "LLM_API_KEY": "sk-你的TaoToken密钥", "LLM_MODEL_NAME": "claude-sonnet-4", "PORT": "38401" } } } }Cline 的配置在 VS Code 的设置里，路径是~/.vscode/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json，字段名一样，只是外层 key 可能叫mcpServers。如果你用的是 Codex 这类走auth.json的客户端，写法不太一样。Codex 的auth.json通常放在~/.codex/auth.json，里面记录的是 provider 的认证信息：
{ "providers": { "taotoken": { "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "model": "qwen3.5-plus" } } }注意auth.json里的字段名是base_url而不是LLM_BASE_URL，这是 Codex 自己的 schema，别混用。三件套还是那三样：Base URL、Key、Model ID，只是字段名随客户端变。这也是为什么我一直强调统一 Key 的价值——不管客户端字段怎么变，你手里的 Key 和 base_url 是同一套，换客户端只是改字段名，不用重新申请密钥。
如果你用 CC Switch 这类工具管理多个 MCP 客户端配置，它的配置文件通常是 TOML 格式，写法如下：
[[servers]] name = "page-agent" command = "npx" args = ["-y", "@page-agent/mcp"] [servers.env] LLM_BASE_URL = "https://taotoken.net/api" LLM_API_KEY = "sk-你的TaoToken密钥" LLM_MODEL_NAME = "qwen3.5-plus" PORT = "38401"TOML 里字符串用双引号，数组用方括号，别写成 JSON 的花括号。CC Switch 的好处是可以在多个客户端配置间切换，但底层还是这套字段。
配置改完记得重启对应的 AI 客户端，MCP 配置是启动时加载的，不重启不生效。重启后客户端会去拉起npx @page-agent/mcp，第一次跑会下载包，网络慢的话多等一会。如果客户端界面里能看到 page-agent 这个 MCP server 并且状态是 connected，说明配置这步过了。接下来就是验证请求。
4. 从 local proxy failed 到成功调用的验证过程
配置写完不代表能跑通，这一步专门演示验证动作，包括那个经典的local proxy failed报错怎么排。先讲正常流程，再讲报错。
正常验证分两步。第一步，确认 MCP server 起来了。在终端手动跑一次：
LLM_BASE_URL="https://taotoken.net/api" \ LLM_API_KEY="sk-你的TaoToken密钥" \ LLM_MODEL_NAME="qwen3.5-plus" \ PORT=38401 \ npx -y @page-agent/mcp如果配置没问题，终端会输出类似启动 Launcher 页面、HTTP 服务监听 38401 的日志。这时候打开 Chrome，Page Agent 扩展应该能检测到本地服务。第二步，在 AI 客户端里发一条自然语言指令，比如“调用 execute_task，打开 https://github.com 搜索 page-agent”。客户端会通过 MCP 协议把任务发给 MCP server，server 再通过 WebSocket 转给 Hub Tab，Hub Tab 调执行层操作浏览器。
成功的话，你会在 Hub Tab 里看到任务执行日志，浏览器自动打开标签页、输入搜索词。AI 客户端那边会收到执行结果。整个过程你不用写一行浏览器操作代码。
现在说local proxy failed。这个报错通常出现在 MCP server 启动阶段或者第一次调用模型时，意思是本地代理层没能把请求转发出去。原因一般有三类。
第一类是LLM_BASE_URL填错。如果你填了https://taotoken.net/api/v1或者带了尾斜杠，请求路径就错了，代理层转发失败。改成干净的https://taotoken.net/api再试。验证方法是在终端直接 curl 一下：
curl -X POST https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -H "Content-Type: application/json" \ -d '{"model":"qwen3.5-plus","messages":[{"role":"user","content":"ping"}]}'如果这个 curl 返回正常 JSON，说明 base_url 和 key 没问题，问题在 Page Agent 配置侧；如果 curl 也报错，那就是 key 或模型 ID 的问题。
第二类是 Key 无效或没权限。401 报错会明确告诉你 unauthorized。去 TaoToken 的 api-keys 页面确认 Key 还在、没被删、额度够。有时候 Key 复制时带了空格或者换行，也会导致认证失败，重新复制一遍。
第三类是端口冲突。38401 被别的进程占了，MCP server 起不来，代理层自然失败。查端口占用：
lsof -i :38401有输出就说明被占了，改PORT环境变量换个端口，比如 38402，然后客户端配置里的PORT也要同步改。改完重启客户端。
还有一种情况是reading choices报错，这个通常出现在模型返回格式不符合预期时。Page Agent 期望的是标准 OpenAI 格式的响应，如果模型返回结构不对，解析choices字段就会失败。这时候先确认LLM_MODEL_NAME填的模型确实兼容 OpenAI 格式，TaoToken 上的模型基本都是兼容的，但如果你填了个不存在的模型 ID，返回可能是错误结构，也会触发这个报错。去模型对话页面确认模型 ID 拼写。
OAuth 相关的报错一般和 MCP 客户端自身的认证有关，不是 Page Agent 的问题。如果你在 Claude Desktop 里看到 OAuth 报错，检查客户端的登录状态，重新登录一次。
排障顺序建议：先 curl 验证 base_url + key + model 三件套，再查端口，再看客户端日志。MCP server 的日志会打在客户端启动它的那个终端里，如果客户端是 GUI 启动的，日志可能在客户端的开发者工具里。Page Agent 还提供了 MCP Inspector 工具，可以监控协议交互：
npx @modelcontextprotocol/inspector node packages/mcp/src/index.js这个能让你看到 MCP 协议层收发的原始消息，定位是客户端没发出去还是 server 没返回。
5. 本篇常见错误对照与修复清单
把上面散落的报错集中成一张对照表，方便你按图索骥。每个报错都对应真实场景，不是编的。
| 报错信息 | 常见原因 | 修复动作 |
|---|---|---|
| local proxy failed | base_url 带/v1或尾斜杠 | 改成https://taotoken.net/api |
| 401 unauthorized | Key 无效、带空格、额度不足 | 重新复制 Key，查 api-keys 页面 |
| reading choices 失败 | 模型 ID 拼错或返回结构异常 | 核对模型 ID，去模型对话页验证 |
| 端口占用无日志 | 38401 被占 | lsof -i :38401后改 PORT |
| 扩展无响应 | 扩展权限不足 | 给 Page Agent“所有网站访问权限” |
| 任务执行中断 | 后台脚本被回收 | 确认走的是 Hub Tab 而非后台脚本 |
| OAuth 报错 | 客户端登录态失效 | 重新登录 AI 客户端 |
| 模块加载错误 | Node 版本 < 20 | 升级 Node 到 20 以上 |
重点说几个容易反复踩的。local proxy failed我试过最隐蔽的一种情况是环境变量没生效——你在终端 export 了，但客户端是从 GUI 启动的，读不到你 shell 里的环境变量。解决办法是把环境变量写进客户端的 MCP 配置env字段里，而不是依赖 shell。这也是为什么前面配置片段里我把LLM_BASE_URL这些都写在env里。
扩展权限这个也值得展开。Chrome 扩展默认可能只有“点击时”权限，Page Agent 要操作任意页面，必须给“所有网站”权限。在chrome://extensions里找到 Page Agent，点详情，把“网站访问权限”改成“在所有网站上”。改完刷新页面，Hub Tab 才能正常接管。
任务执行中断的问题，根源在浏览器对后台脚本的生命周期管理。如果你的方案是让扩展后台脚本直接和 MCP server 通信，长任务跑到一半后台脚本被回收，连接就断了。Page Agent 用 Hub Tab 规避了这个问题，但前提是 Hub Tab 得保持打开。如果你手动关了 Hub Tab，任务自然就断了。所以调试时别关那个标签页。
Node 版本这个，报错信息可能是Cannot use import statement outside a module或者ERR_REQUIRE_ESM，本质都是 ESM 支持问题。Node 20 以上对 ESM 支持完善，升级就行。用 nvm 的话nvm install 20 && nvm use 20。
还有一类不报错但没反应的情况：MCP server 起来了，客户端也 connected，但发指令没动静。这时候先看 Hub Tab 有没有打开，再看 Launcher 页面有没有提示扩展未检测到。Launcher 页面是 MCP server 启动时自动打开的引导页，它会检测扩展安装状态和 WS 连接状态。如果 Launcher 显示 WS 未连接，说明 MCP server 的 WebSocket 服务没起来，回去查端口和启动日志。
修复清单按优先级排：先保证 curl 三件套通，再保证 MCP server 能手动启动，再保证客户端 connected，最后保证 Hub Tab 打开且扩展有权限。这四步都过了，基本就能跑通。
6. 把统一 Key 接进你的前端 Agent 工作流
链路跑通之后，真正有价值的是把它接进日常开发流。Page Agent 提供三个核心 MCP 工具：execute_task执行自然语言任务、get_status查连接和忙碌状态、stop_task中断当前任务。这三个覆盖了“执行-监控-中断”全流程，你在 AI 客户端里直接调用就行。
实际用的时候，我建议把常用任务写成模板。比如数据采集场景，固定指令“打开某页面，抓取表格数据，返回 JSON”，每次只改 URL。因为执行层是把自然语言交给 LLM 解析成分步操作的，指令越结构化，解析越稳定。别写太模糊的指令，比如“帮我看看这个页面”，LLM 解析出来的操作可能不是你要的。
多模型切换是统一 Key 最爽的地方。你可以在 TaoToken 的模型对话页面先对比几个模型对同一任务指令的解析效果，选一个稳定的填进LLM_MODEL_NAME。比如复杂页面操作选推理强的模型，简单表单填写选快的模型。切换时只改一个字段，base_url 和 key 不动。如果你在做长期编码或 Agent 项目，可以考虑 Coding Plan 这类方案，把模型通道和额度统一管理，地址在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。
对于 Claude Code 这类偏编码的场景，接入逻辑和 Page Agent 类似，也是三件套配置。Claude Code 的配置入口和文档在 https://taotoken.net/claude-code?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite ，里面有针对 Anthropic 协议的接入说明。如果你用的是 ClaudeCodeAnthropic 相关的客户端，注意它的 base_url 和 OpenAI 兼容格式可能不同，按文档里的 endpoint 填。
控制台入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，可以看用量和额度。API Keys 管理还是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。遇到接入问题先翻文档，大部分报错文档里都有对应说明。
最后给个实用技巧：把 MCP 配置里的 Key 用环境变量引用，而不是明文写死。虽然 Page Agent 的配置支持直接写 Key，但如果你把配置文件提交到 git，Key 就泄露了。可以在客户端配置里写"LLM_API_KEY": "${TAOTOKEN_KEY}"，然后在系统环境变量里设TAOTOKEN_KEY。不同客户端对环境变量引用的支持不一样，Claude Desktop 支持${VAR}语法，Cursor 也支持。这样配置文件可以安全地进版本库，Key 留在本地。
浏览器智能这条链路，核心不是某个具体工具，而是 MCP 这层标准化协议带来的解耦。你把模型通道用统一 Key 管起来，把浏览器操作封装成 MCP 工具，剩下的就是组合任务。前端从“用户交互层”变成“AI 交互层”，这个转变的工程基础，就是今天这套配置和排障流程。
