 两分钟快速上手与技术原理解析：从 Snapshot 到 Chromium 的落地路径)
1. 为什么 AI Agent 需要真正操作浏览器
AI Agent 写代码、分析文本、调用 API 都很顺手，但任务一旦落到真实网页上——需要登录、需要点击、需要填表单——传统"搜索网页并总结"的能力就不够用了。搜索和操作是两件完全不同的事。搜索适合获取公开信息、阅读无需登录的文章、对公开页面做摘要；而真实工作场景经常包含登录 CRM、邮箱、招聘平台和企业后台，使用已有 Cookie、扩展程序和浏览器配置，点击筛选项、翻页、填写表单、上传文件，下载报表、截取结果、检查提交前页面，以及在验证码、支付和授权环节交还给用户确认。
这类任务很难仅靠 API 完成。一方面，许多 SaaS 平台没有开放完整 API；另一方面，即使存在 API，也可能拿不到浏览器中已经登录的个人上下文。ego (lite) 提供了一条不同的路径：让 Codex、Claude Code、Cursor 或自定义 Agent 连接到一款真实的 Chromium 浏览器，在保留登录状态和浏览器使用习惯的同时，通过独立 Space 完成网页任务。它的核心价值，就是让 Agent 不只"阅读互联网"，还能够在用户授权范围内操作真实网页。
ego (lite) 是一款基于 Chromium 的浏览器，同时面向人和 AI Agent 设计。它可以继承已有浏览器中的扩展程序、浏览记录、登录状态、Cookie 和个人资料，使 Agent 能够进入那些必须登录后才能使用的网站。从产品分工上看，可以把它拆成三层：任务层由 Codex、Claude Code、Cursor、自定义 Agent 负责理解用户目标、规划步骤、生成自动化流程；自动化层由 ego-browser Skill 提供浏览器操作 Helper、Snapshot、Space 和 CDP 能力；浏览器层由 ego (lite) 承载真实 Chromium 会话、登录状态、扩展和网页标签页。这与传统"Agent 启动一个全新的无头浏览器"不同，ego (lite) 更强调复用本机真实浏览器环境，并将 Agent 的任务放在独立 Space 中执行。
完整链路可以概括为：用户任务 → Codex / Claude Code / Cursor → ego-browser Skill → Chrome DevTools Protocol → ego (lite) 真实 Chromium 会话 → Space 中的目标网页。其中有两个关键机制值得展开。
Space 是 ego (lite) 为 Agent 划出的并行工作区。Agent 可以在自己的 Space 中打开网页、点击、填写、下载文件，而用户继续在自己的标签页中工作。它不是新启动一个完全独立的浏览器，不是云端浏览器会话，不是一套新的 Chrome 用户资料，也不是抢占用户鼠标和焦点的远程控制。它更接近"同一个浏览器进程中的独立 BrowserContext"：任务之间的页面、Cookie 和 Storage 可以隔离，但底层浏览器基础设施能够复用。官方文档给出的 6 并发对照测试显示，独立浏览器实例加资料副本约增加 15 GB 内存、84 个进程，启动约 2.5 秒；Space 模式约增加 0.9 GB 内存、6 个进程，启动约 0.6 秒。实际开销仍会受到网页复杂度、扩展和并发量影响。
Snapshot 则把网页变成 Agent 能理解的语义快照。网页完整 HTML 往往包含大量脚本、样式和隐藏节点，直接把整页 DOM 交给大模型，不但 Token 消耗高，还会让 Agent 难以找到真正可操作的元素。Snapshot 会基于网页的语义结构，为按钮、输入框、链接等元素生成临时引用，例如@1 [input] "搜索"、@2 [button] "提交"、@3 [link] "下一页"。Agent 可以执行await fillInput('@1', 'AI Agent 浏览器')和await click('@2', { label: '提交搜索' })。页面跳转、刷新、弹窗或局部重渲染后，旧的 @N 引用可能失效，因此可靠流程是：页面发生变化后重新获取 Snapshot。
2. TaoToken 前置准备与 API Key 获取
在跑通 ego (lite) 之前，你需要先准备好 Agent 侧的模型接入。无论你用的是 Codex、Claude Code 还是 Cursor，都需要一个稳定的模型 API 入口。TaoToken 提供了统一的 API 网关，兼容 OpenAI 和 Anthropic 的接口格式，你可以把它理解成一个"模型接入中转站"——不用分别去各家平台注册、充值、管理多个 Key，一个 Key 就能调用多种模型。
先访问官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册账号。注册完成后进入控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在左侧菜单找到"API Keys"页面，点击创建新的 Key。创建时建议给 Key 起一个能识别用途的名字，比如 "ego-browser-test"，方便后续管理。创建完成后立即复制保存，页面刷新后就看不到完整 Key 了。
拿到 Key 之后，你需要确认两件事：Base URL 和 Model ID。TaoToken 的 API 地址是 https://taotoken.net/api ，这个地址同时兼容 OpenAI 格式（/v1/chat/completions）和 Anthropic 格式（/v1/messages）。Model ID 则取决于你想用哪个模型，控制台的模型列表页面会列出当前可用的所有模型标识符。如果你不确定选哪个，可以先从通用的对话模型开始测试。
对于 Claude Code 用户，TaoToken 提供了专门的接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面详细说明了如何配置环境变量和 settings 文件。如果你用的是 Codex，需要修改~/.codex/auth.json和配置文件；如果用 Cursor，则在设置里填入 Base URL 和 API Key 即可。这里的关键是：Agent 本身负责理解任务和规划步骤，而模型 API 负责提供推理能力，两者配合才能让 ego-browser Skill 正常工作。
需要特别提醒的是，ego-browser Skill 的安装和模型 API 的配置是两条独立的线。Skill 负责浏览器操作能力，API Key 负责模型推理能力。你可以先配好 API Key 确保 Agent 能正常对话，再安装 Skill 让它获得浏览器操作能力。如果 Agent 连对话都不正常，那 Skill 装了也没用。所以建议的顺序是：先验证模型 API 能通，再装 Skill，最后跑浏览器任务。
另外，如果你打算长期用 Agent 做编码或浏览器自动化任务，可以关注一下 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它针对高频调用场景做了额度优化，比按量计费更适合日常开发使用。对于只是偶尔测试 ego (lite) 的场景，按量计费就足够了。
3. 可复制配置：安装 ego (lite) 与 ego-browser Skill
这一节给出完整的安装和配置片段，你可以直接复制执行。整个流程分为三步：安装 ego (lite) 应用、安装 ego-browser Skill、配置 Agent 权限。
3.1 安装 ego (lite) 应用
官方流程非常接近普通 Mac 应用安装：下载 DMG 文件，打开安装包，将 ego (lite) 拖入 Applications，启动应用并完成 Onboarding。Onboarding 阶段，ego (lite) 会询问是否迁移已有浏览器资料。迁移后，浏览记录、Cookie、登录状态、扩展程序和 Chrome 个人资料能够被继承。需要注意的是，迁移浏览器资料时系统可能要求输入密码，这是为了访问并迁移本机浏览器相关数据，并不是把密码直接交给 Agent。
首次启动时，ego (lite) 还会扫描机器上已经安装的 Agent，并将 ego-browser Skill 写入常见目录，例如~/.agents/skills和~/.claude/skills。如果自动安装没有生效，可以手动执行：
npx skills add github:CitroLabs/ego-lite/skills/ego-browser执行完成后，检查 Skill 是否写入成功：
ls ~/.agents/skills/ego-browser ls ~/.claude/skills/ego-browser如果目录存在且包含 SKILL.md 等文件，说明安装成功。
3.2 配置 Claude Code 接入 TaoToken
如果你用 Claude Code 作为 Agent，需要配置模型 API。创建或编辑~/.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-your-taotoken-key-here", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }把sk-your-taotoken-key-here替换成你在 TaoToken 控制台创建的真实 Key，ANTHROPIC_MODEL替换成你想用的模型 ID。保存后重启 Claude Code，输入/status确认 API 连接正常。
3.3 配置 Codex 接入 TaoToken
如果你用 Codex，需要编辑~/.codex/auth.json：
{ "OPENAI_API_KEY": "sk-your-taotoken-key-here", "OPENAI_BASE_URL": "https://taotoken.net/api/v1" }同时确认~/.codex/config.toml中的模型配置：
model = "gpt-4o" provider = "openai"这里的三件套是：Base URL 填https://taotoken.net/api/v1，Key 填 TaoToken 控制台创建的 Key，Model ID 填你选定的模型标识符。三者缺一不可，任何一个填错都会导致 401 或模型不存在错误。
3.4 配置 Cursor 接入 TaoToken
在 Cursor 设置中找到 "Models" 页面，关闭默认的 OpenAI/Anthropic 直连，添加自定义 API：
{ "openai.apiKey": "sk-your-taotoken-key-here", "openai.baseUrl": "https://taotoken.net/api/v1" }保存后 Cursor 会通过 TaoToken 网关调用模型。你可以在 Cursor 的 Chat 面板里发一条测试消息，确认能正常返回。
3.5 设置 Agent 运行权限
ego-browser 需要启动本机的 ego (lite) 应用。对于带有沙箱或权限控制的 Agent，需要允许它执行沙箱外应用。在 Codex 中，可以将当前任务权限设置为 Full access。Full access 不代表可以忽略风险边界，正确做法是：只在确实需要启动本机浏览器时开启，对支付、发布、删除、转账等操作明确要求暂停，给测试任务使用低风险账号或测试环境，任务完成后检查 Space 中访问过的网页。
4. 验证请求：跑通第一个浏览器任务
配置完成后，用下面这个最小示例验证整条链路是否通畅。以 Codex 为例，在 Agent 对话框中输入/ego-browser，然后从 Skill 选择器中选择 ego-browser。接着发送第一个任务：
使用 ego-browser 打开 OpenAI 和 Anthropic 的博客， 检查最近发布的文章，找出值得关注的新信息。 要求： 1. 分别列出最新文章标题、发布时间和核心内容； 2. 对共同趋势进行归纳； 3. 返回 Markdown 表格； 4. 只读取信息，不要登录、发布或修改任何内容。Agent 会创建一个 Space，在里面打开目标网站，读取页面、筛选文章并返回总结。任务运行时，点击 ego (lite) 右上角的 Space 按钮，可以进入 Space 管理面板。带有运行状态提示的空间表示 Agent 正在工作。
如果你更想直接控制浏览器操作，可以用 ego-browser 的 Node.js heredoc 模式。下面是一个经过简化的示例：
ego-browser nodejs <<'EOF' const task = await useOrCreateTaskSpace('collect latest ai articles') await openOrReuseTab( 'https://openai.com/news/', { wait: true, timeout: 20 } ) // 读取当前页面的语义快照 const snapshot = await snapshotText() cliLog(snapshot) // 根据最近一次 Snapshot 中的引用进行操作 // await click('@12', { label: '打开最新文章' }) // 输出最终结果 cliLog({ status: 'page opened', title: (await pageInfo()).title }) EOF典型循环是：useOrCreateTaskSpace()创建或复用任务空间，openOrReuseTab()打开目标页面，snapshotText()读取语义快照，click()、fillInput()、scroll()执行操作，页面变化后重新snapshotText()，最后cliLog()输出结果。
常用 Helper 包括：
await listTabs() await currentTab() await pageInfo() await snapshotText() await captureScreenshot('result.png') await click('@21', { label: '打开详情' }) await fillInput('@2', 'keyword') await pressKey('Enter') await scrollBy(900) await uploadFile('input[type="file"]', '/absolute/path/report.pdf') await waitForNetworkIdle()对于普通表单页面，应优先使用 Snapshot 中的 @N、loc= 或 CSS Selector；对于 Canvas、复杂可视化和无障碍树不完整的页面，则可能需要截图与坐标操作配合。
验证成功的标志是：Agent 返回了结构化的 Markdown 表格，Space 面板中能看到访问过的页面，且没有触发任何登录或修改操作。如果这一步跑通了，说明模型 API、Skill 安装、浏览器启动三条链路都正常。
5. 本篇常见错误排查
这一节对照真实报错，给出排查路径。大部分问题集中在 API 配置、Skill 安装和 Snapshot 引用三个环节。
5.1 401 Unauthorized 或 invalid api key
这是最常见的错误，说明模型 API 的 Key 配置有问题。检查顺序：确认~/.claude/settings.json或~/.codex/auth.json中的 Key 是否完整复制，没有多余空格；确认 Key 没有过期或被删除；确认 Base URL 填写正确——Claude Code 用https://taotoken.net/api，Codex 用https://taotoken.net/api/v1，两者路径不同。如果用的是 Cursor，检查设置里的 baseUrl 是否带了/v1。修改后重启 Agent 再试。
5.2 local proxy failed 或 connection refused
这个报错通常出现在 Agent 尝试启动 ego (lite) 应用时。原因是 Agent 的沙箱权限不允许执行本机应用。在 Codex 中，把当前任务权限设置为 Full access；在 Claude Code 中，确认没有开启过严的沙箱限制。另外检查 ego (lite) 是否已经正常启动，可以在 Applications 中手动打开一次，完成 Onboarding 后再让 Agent 调用。
5.3 reading choices 或 model not found
这个报错说明 Model ID 填错了。TaoToken 控制台的模型列表页面会列出当前可用的模型标识符，复制准确的 ID 填入配置。注意区分大小写和版本号，比如claude-sonnet-4-20250514和claude-sonnet-4可能是不同的模型。如果用的是 Codex，检查config.toml中的 model 字段是否和 auth.json 中的 provider 匹配。
5.4 OAuth 相关报错
如果你在 Claude Code 中看到 OAuth 报错，说明它还在尝试用 Anthropic 官方登录而不是 API Key。检查~/.claude/settings.json中是否正确设置了ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY，并且没有同时保留 OAuth 的 token 配置。必要时删除~/.claude/下的缓存文件，重新登录。
5.5 Agent 中找不到 /ego-browser
检查是否已经完成 ego (lite) Onboarding；~/.agents/skills或~/.claude/skills是否存在 Skill；Agent 是否需要重启才能重新扫描 Skill；是否可以使用独立安装命令npx skills add github:CitroLabs/ego-lite/skills/ego-browser。如果目录存在但 Agent 仍不识别，尝试重启 Agent 或重新执行安装命令。
5.6 Unknown ref 或元素引用失效
@N 只属于最近一次 Snapshot。页面跳转、刷新或重新渲染后，应重新执行：
const latest = await snapshotText() cliLog(latest)需要长期稳定引用时，优先使用 Snapshot 中的 loc= 或 CSS Selector。如果页面是 Canvas，Snapshot 找不到按钮，可以改用captureScreenshot()、坐标点击、js()读取页面运行时数据、原始 CDP 命令，或人工进入 Space 确认。
5.7 登录状态没有迁移成功
确认 Onboarding 时选择了正确的浏览器资料；系统密码授权是否完成；目标网站是否要求重新验证；Cookie 是否已经过期；网站是否限制新浏览器或新设备登录。如果迁移失败，可以在 ego (lite) 中手动登录一次目标网站，后续 Agent 就能复用这个登录状态。
6. 从只读任务到生产流程：接入方式与场景判断
跑通第一个任务后，你需要判断 ego (lite) 是否适配自己的场景。我的建议是从只读任务开始，第一阶段只做信息读取、列表筛选、报表下载、截图、结果汇总。等任务路径稳定后，再逐步增加表单填写和修改操作。
企业场景可以统一定义确认点：读取动作自动执行，草稿动作自动执行，提交动作等待确认，删除动作禁止执行，支付动作禁止执行，权限变更禁止执行。把"确认点"写进任务模板，比每次靠提示词约束更可靠。
为重要任务保留证据也很关键。输出结果时要求 Agent 同时提供访问过的页面、关键筛选条件、记录数量、详情链接、截图路径、下载文件路径、未完成或等待确认的动作。涉及 CRM、财务和内部管理系统时，优先使用测试账号、最小权限账号、Staging 环境、可恢复的数据副本、只读角色。
将高频流程沉淀为 Skill 是长期方向。一次性任务可以直接描述，重复任务应逐步沉淀为固定任务模板、稳定 Selector、站点经验、校验规则、输出结构、失败回退策略。这样才能从"偶尔能跑"升级为"可复用的生产流程"。
如果你需要验证模型对话能力，可以访问模型对话页面 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 快速测试；如果需要管理 API Key，进入 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ；如果打算长期用 Agent 做编码或浏览器自动化，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 更适合高频调用场景。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各客户端的详细配置说明。
ego (lite) 展示了一种值得关注的 Agent 产品形态：AI 不再只停留在聊天窗口中，而是通过真实浏览器进入用户已经登录的工作环境。它的关键不是简单的"自动点击"，而是复用真实 Chromium 会话、通过 Skill 连接主流 AI Agent、使用 Space 隔离任务工作区、用 Snapshot 降低网页理解成本、在验证码和不可逆操作前交还用户、保留页面和执行过程便于人工复核。对于开发者和技术团队，最合理的上手方式不是立刻追求全自动，而是先选择一个明确、只读、可验证的小任务，跑通"打开网页—读取 Snapshot—执行操作—返回结果—人工复核"的闭环。当这条闭环稳定之后，浏览器 Agent 才真正有机会从演示工具，成长为日常工作流的一部分。
