Manus实战：AI Agent 控制浏览器实现原理与实战——用 TaoToken 统一 Key 打通 CDP/Puppeteer 配置-开发者社区

1. 从 Manus 类 Agent 说起：浏览器操控到底难在哪

Manus 这类 AI Agent 最让人上头的能力，就是它能自己打开浏览器、点按钮、填表单、翻页抓数据，像一个真人一样把网页任务跑完。但真到自己动手搭一套，你会发现核心难点根本不在“让模型说话”，而在“让模型的手能准确落到浏览器上”。浏览器操控这条链路，本质是把自然语言指令翻译成 CDP（Chrome DevTools Protocol）能听懂的动作，再通过 Puppeteer 这类驱动层执行出去。

我先把这条链路拆开讲清楚，你才知道后面配置为什么要那样写。一个完整的 Manus 类 Agent 控制浏览器，通常分四层：最上面是用户指令层，比如“帮我在某网站搜索关键词并提取前十条结果”；第二层是 AI 解析层，用大模型把自然语言转成结构化 JSON 动作序列；第三层是驱动层，Puppeteer 或 Playwright 把动作翻译成 CDP 命令；最底层是浏览器执行层，Chrome 通过调试端口接收命令并返回结果。四层里最容易出问题的，恰恰是第二层和第三层之间的衔接，以及模型 API 通道的稳定性。

为什么很多人搭到一半就卡住？我总结下来有三个高频坑。第一，模型 API 通道不统一，Agent 里同时要调意图解析、元素定位、结果总结好几个模型，每个都单独配 Key，管理起来一团乱，还容易触发限流。第二，CDP 连接参数写错，--remote-debugging-port没开或者端口被占，Puppeteer 连不上浏览器，报connect ECONNREFUSED。第三，元素定位策略太单一，只靠 CSS 选择器，遇到动态渲染的页面就抓瞎。

这篇要解决的就是这三件事。我会用 TaoToken 作为统一的模型 API 通道，把意图解析、元素定位、结果总结这几个环节的 Key 收敛成一个，然后给出可复制的config.toml和settings.json骨架，再带你走完启动、连通性、页面操控三步验证。适合谁看？正在做本地浏览器自动化调试的开发者、想给 Agent 加浏览器能力的后端同学，以及被多 Key 管理折磨过的朋友。下面直接进配置。

2. TaoToken 前置准备：统一 Key 与 API 通道

在动手写浏览器操控代码之前，得先把模型通道这块理顺。Manus 类 Agent 控制浏览器的过程中，模型调用非常密集：解析用户意图要调一次，生成动作序列要调一次，遇到复杂页面做视觉辅助定位可能还要调一次，最后总结结果再调一次。如果每个环节都单独配一个厂商的 Key，你的配置文件会变成一锅粥，调试时根本分不清是哪个 Key 出的问题。

TaoToken 在这里扮演的角色就是统一入口。它提供兼容主流接口规范的 API 通道，你只需要一个 Key，就能在 Agent 的不同环节调用不同模型。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基础地址是 https://taotoken.net/api 。注意这两个地址的用途不一样，官网用来注册和管理 Key，API 地址才是代码里要填的 Base URL。

具体操作上，你需要先拿到一个可用的 API Key。进入控制台创建 Key 的入口在这里：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。创建好之后，Key 的查看和管理在 API Keys 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。这两个页面建议都收藏一下，后面调试时经常要回来核对。

这里有个关键点要提醒：TaoToken 的 Base URL 填https://taotoken.net/api，不要带任何多余路径。很多同学第一次配的时候习惯性在后面加/v1，结果请求 404。正确的做法是让 SDK 自己拼接版本路径，你只填到/api这一层。模型 ID 方面，意图解析这种任务用轻量模型就够，视觉辅助定位和结果总结可以用能力更强的模型，具体在模型对话页面能看到当前可用的模型列表：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。

如果你后面要长期跑编码类或 Agent 类任务，可以考虑 Coding Plan，它更适合高频调用场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。不过对于本篇的浏览器操控调试，按量调用就够了，先把链路跑通再说。

把 Key 拿到手之后，先别急着写 Agent 代码。我建议你先用最简方式验证一下通道是否通，比如用 curl 发一个最小请求。这一步能帮你排除掉 90% 的配置问题，省得后面在浏览器代码里排查半天，最后发现是 Key 填错了。验证命令我放在下一节，和配置文件一起给。

3. 可复制配置：config.toml 与 settings.json 骨架

这一节是整篇的核心，配置写对了，后面基本就是顺水推舟。我会给出两个文件：config.toml用来管 Agent 的运行时参数和模型通道，settings.json用来管浏览器启动参数和 Puppeteer 连接选项。两个文件配合使用，路径按你项目根目录来放。

先看config.toml。这个文件负责把 TaoToken 作为统一 Key 通道接进来，同时定义不同环节用哪个模型：

# config.toml - Agent 运行时配置 [api] # TaoToken 统一 API 通道，注意只填到 /api base_url = "https://taotoken.net/api" # 从控制台创建的 Key，建议用环境变量注入，这里写占位 api_key = "${TAOTOKEN_API_KEY}" timeout_seconds = 60 max_retries = 3 [models] # 意图解析：轻量模型即可，响应快 intent_parser = "gpt-4o-mini" # 动作序列生成：需要较强推理 action_planner = "gpt-4o" # 视觉辅助定位：多模态模型 visual_locator = "gpt-4o" # 结果总结：中等能力 summarizer = "gpt-4o-mini" [browser] # Chrome 调试端口，Puppeteer 通过它连 CDP debug_port = 9222 headless = false viewport_width = 1280 viewport_height = 800 # 单动作超时 action_timeout_ms = 30000 # 动作间稳定等待 settle_wait_ms = 500 [agent] max_actions_per_task = 20 max_retries_per_action = 3 screenshot_on_error = true

这里有几个参数值得展开说。base_url必须是https://taotoken.net/api，这是 TaoToken 的 API 入口，不要画蛇添足加/v1。api_key我用的是环境变量占位，实际运行时通过export TAOTOKEN_API_KEY=你的Key注入，这样配置文件可以安全提交到仓库。debug_port默认 9222，这是 Chrome 远程调试的标准端口，Puppeteer 连接时要用同一个值。

再看settings.json，这个文件管浏览器和 Puppeteer 的连接细节：

{ "browser": { "executablePath": "/usr/bin/chromium", "args": [ "--remote-debugging-port=9222", "--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage", "--window-size=1280,800" ], "headless": false }, "puppeteer": { "connectOptions": { "browserURL": "http://127.0.0.1:9222", "defaultViewport": { "width": 1280, "height": 800 }, "protocolTimeout": 60000 }, "launchOptions": { "ignoreHTTPSErrors": true, "slowMo": 50 } }, "agent": { "apiBaseUrl": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "modelId": "gpt-4o" } }

注意settings.json里我特意把apiBaseUrl、apiKeyEnv、modelId三件套都写全了。这是接入任何模型通道的标准三件套：Base URL 指向 TaoToken 的 API 地址，Key 通过环境变量注入，Model ID 指定具体模型。很多同学配 Cline MCP 或者 Codex 的auth.json时只填了 Key 忘了 Base URL，结果请求打到默认地址上，报 401 或者连接超时。三件套缺一不可。

executablePath要根据你的系统改。Linux 上常见的是/usr/bin/chromium或/usr/bin/google-chrome，macOS 上一般是/Applications/Google Chrome.app/Contents/MacOS/Google Chrome。如果你用 Puppeteer 自带的 Chromium，这一行可以删掉，让它自己找。

--no-sandbox和--disable-setuid-sandbox在容器环境里基本是必须的，否则 Chrome 起不来。--disable-dev-shm-usage解决的是 Docker 里共享内存不足导致页面崩溃的问题，本地调试也建议留着。

配置文件写好后，先别急着跑 Agent。用下面这条命令验证 TaoToken 通道是否通：

export TAOTOKEN_API_KEY="你的Key" curl -s https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "回复 OK"}], "max_tokens": 10 }'

如果返回里能看到choices字段和正常内容，说明通道没问题。如果报 401，检查 Key 是否复制完整；如果报连接错误，检查网络和 Base URL 是否写成了https://taotoken.net/api。这一步过了，再往下走浏览器部分。

4. 三步验证：启动、连通性、页面操控

配置就绪后，按三步走验证，每步都有明确的成功标志，出问题也能快速定位到是哪一层。

第一步，启动带调试端口的 Chrome。不要直接双击打开浏览器，那样不会开调试端口。用命令行启动：

# Linux / macOS /usr/bin/chromium \ --remote-debugging-port=9222 \ --user-data-dir=/tmp/chrome-agent-profile \ --no-first-run \ --no-default-browser-check

Windows 上换成对应的 Chrome 路径，参数一样。--user-data-dir指定一个独立配置目录，避免和你日常用的浏览器冲突。启动后，访问http://127.0.0.1:9222/json/version，如果返回一段 JSON，里面有Browser和webSocketDebuggerUrl字段，说明调试端口开成功了。这一步的成功标志就是能看到这个 JSON。

第二步，验证 Puppeteer 能否连上 CDP。写一个最小脚本：

// verify-connect.js const puppeteer = require('puppeteer-core'); (async () => { const browser = await puppeteer.connect({ browserURL: 'http://127.0.0.1:9222', defaultViewport: { width: 1280, height: 800 }, }); const pages = await browser.pages(); console.log('已连接，当前标签页数量:', pages.length); const page = pages[0] || await browser.newPage(); await page.goto('https://example.com', { waitUntil: 'domcontentloaded' }); const title = await page.title(); console.log('页面标题:', title); await browser.disconnect(); })();

跑之前先npm install puppeteer-core。如果输出“已连接”和页面标题，说明 Puppeteer 到 CDP 这条链路通了。这里注意用puppeteer-core而不是puppeteer，因为我们已经手动启动了 Chrome，不需要它再下载一个浏览器。browser.disconnect()只断开连接，不关闭浏览器，方便你反复调试。

第三步，把模型通道接进来，跑一个完整的“自然语言转动作”小例子。下面这段代码用 TaoToken 解析指令，然后执行：

// agent-demo.js const puppeteer = require('puppeteer-core'); const fetch = require('node-fetch'); const API_BASE = 'https://taotoken.net/api'; const API_KEY = process.env.TAOTOKEN_API_KEY; async function planActions(instruction, pageContext) { const prompt = `你是浏览器自动化助手。根据指令和页面上下文生成动作序列。 页面URL: ${pageContext.url} 页面标题: ${pageContext.title} 可交互元素: ${JSON.stringify(pageContext.elements.slice(0, 20))} 用户指令: ${instruction} 可用动作: navigate / click / type / scroll / extract 返回JSON数组，每项含 type 和参数，仅返回JSON。`; const res = await fetch(`${API_BASE}/chat/completions`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: prompt }], temperature: 0, }), }); const data = await res.json(); const text = data.choices[0].message.content.trim(); return JSON.parse(text.replace(/```json|```/g, '')); } async function run() { const browser = await puppeteer.connect({ browserURL: 'http://127.0.0.1:9222', }); const page = (await browser.pages())[0] || await browser.newPage(); await page.goto('https://example.com', { waitUntil: 'domcontentloaded' }); const context = { url: page.url(), title: await page.title(), elements: await page.evaluate(() => Array.from(document.querySelectorAll('a, button, input')).map(el => ({ tag: el.tagName, text: (el.innerText || el.value || '').slice(0, 30), id: el.id, })) ), }; const actions = await planActions('提取页面主标题文字', context); console.log('模型生成的动作:', actions); for (const action of actions) { if (action.type === 'extract') { const result = await page.evaluate(sel => { const el = document.querySelector(sel); return el ? el.innerText : null; }, action.selector); console.log('提取结果:', result); } } await browser.disconnect(); } run().catch(console.error);

跑之前npm install node-fetch，并确保TAOTOKEN_API_KEY已导出。如果能看到模型生成的动作序列和提取结果，说明整条链路——从自然语言到 TaoToken 解析，再到 Puppeteer 执行 CDP 命令——全部打通了。这三步验证下来，你的 Manus 类 Agent 浏览器操控骨架就立起来了。

5. 常见报错排查：401、连接失败与 choices 读取

调试过程中有几类报错几乎人人都会遇到，我把它们和对应的排查路径列清楚，你对着改就行。

第一类是 401 未授权。典型报错长这样：{"error":{"message":"Invalid API key","type":"invalid_request_error"}}。原因通常是三个：Key 没导出到环境变量、Key 复制时带了空格、或者 Base URL 写错导致请求打到了别的地址。排查顺序是先echo $TAOTOKEN_API_KEY确认环境变量有值，再用第 3 节的 curl 命令单独测通道。如果 curl 通但代码里报 401，那就是代码里读取环境变量的方式有问题，检查process.env.TAOTOKEN_API_KEY拼写。

第二类是连接失败，报错类似Error: connect ECONNREFUSED 127.0.0.1:9222或者Failed to fetch browser webSocket URL。这说明 Puppeteer 连不上 Chrome 的调试端口。先确认 Chrome 是不是用--remote-debugging-port=9222启动的，再访问http://127.0.0.1:9222/json/version看有没有响应。如果端口被占用，换个端口，同时改config.toml和settings.json里的值保持一致。还有一种情况是 Chrome 启动时没加--user-data-dir，导致它复用了已有实例，调试端口没生效，加上独立目录就好。

第三类是读取choices报错，比如TypeError: Cannot read properties of undefined (reading 'choices')。这通常意味着 API 返回的结构和你预期的不一样。先console.log(data)把完整响应打出来看。常见原因是模型 ID 写错了，返回了错误对象而不是正常响应；或者请求体里messages格式不对。还有一种可能是响应被截断，max_tokens设太小导致choices为空。把max_tokens调大，并确认model字段用的是模型对话页面里列出的可用模型。

第四类是 OAuth 或认证相关的报错，如果你在配 Cline MCP 或 Codex 的auth.json，报错可能是OAuth token expired或authentication failed。这类问题的根源往往是只配了 Key 没配 Base URL，或者auth.json里的字段名不对。记住三件套：Base URL 填https://taotoken.net/api，Key 填你创建的那串，Model ID 填具体模型名。三个字段名要和工具要求的一致，Cline 里通常是baseUrl、apiKey、model，Codex 的auth.json里字段名可能不同，以官方文档为准。

第五类是local proxy failed或代理相关报错。这类报错通常和网络环境有关，检查你的请求是否走了不必要的中间层。TaoToken 的 API 地址是直连的，不需要额外代理配置。如果你在代码里设了HTTP_PROXY之类的环境变量，先 unset 掉再试。

排查的核心思路是分层定位：先确认模型通道通不通（curl 测），再确认浏览器调试端口通不通（访问 9222），最后确认代码里的连接参数和配置文件一致。三层都过了，基本不会有玄学报错。

6. 把通道固定下来，让 Agent 跑得更稳

浏览器操控这条链路跑通之后，真正影响长期体验的其实是通道稳定性。我自己的做法是把 TaoToken 的 Key 和 Base URL 固定成项目级的环境变量，所有 Agent 环节都从这里读，不再散落在各个文件里。这样换模型、调参数只需要改一处，调试时也不会因为某个环节用了旧 Key 而报 401。

另外一个小技巧是给动作执行加一层重试和截图。config.toml里的max_retries_per_action和screenshot_on_error就是干这个的。页面动态渲染时，元素可能晚几百毫秒才出现，重试一次往往就成功了；失败时截个图，回头排查能直观看到当时页面长什么样。这两个参数配合使用，Agent 的鲁棒性会明显提升。

如果你后面要把这套东西用到更复杂的场景，比如多标签页协作或者长时间运行的自动化任务，建议把模型调用和浏览器操作解耦成两个独立模块，中间用队列通信。这样模型通道抖动不会直接卡死浏览器，浏览器崩溃也不会丢任务。模型对话页面可以帮你快速验证不同模型在意图解析上的表现：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。接入文档里有更完整的参数说明：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

最后说个实际经验：调试浏览器 Agent 时，把headless设成false，让浏览器窗口可见。你能亲眼看到 Agent 点了哪里、填了什么，比看日志快十倍。等流程稳定了再切回无头模式跑批量任务。这个习惯帮我省下了大量排查时间。