Agent Chrome

agentchrome

让你的编码 Agent 使用你平时用的 Chrome。

安装 · 让你的 Agent 安装 · 功能介绍 · 工具 · 安全

Agent Chrome 是一款 Chrome 扩展程序和 MCP 服务，可让编码 Agent 使用你已登录的真实 Chrome 配置文件。它兼容 Claude Code、Codex、Gemini CLI、Antigravity、Grok、Muse、Cursor、opencode 以及任何其他 MCP 客户端。每个 Agent 都在自己的标签组中工作，蓝色边框和动态光标会显示它正在执行的操作。它可以截取屏幕截图、录制视频片段，还能同时连接多个 Chrome 配置文件。服务运行在 Cloudflare 上，也可以在你的本地计算机上运行。

_{Agent 工作时你看到的画面。此片段由扩展程序本身录制（MP4）。}

如果你觉得它有用，请给仓库点个星。这能帮助其他人发现它。

安装

你需要 Node.js 18 或更高版本，以及 Google Chrome。

1. 运行安装程序

curl -fsSL https://agentchrome.dev/install | sh

安装程序会一次性完成以下操作：

1. 创建你的账户，并将密钥保存到 ~/.config/agentchrome/config.json，权限设为 chmod 600。
2. 在它找到的每个 Agent 的用户级配置中添加名为 agentchrome 的 MCP 服务（见下表）。
3. 将 agentchrome 技能写入 ~/.agents/skills/agentchrome，并通过符号链接将其链接到每个 Agent 的技能文件夹。
4. 将扩展程序解压到 ~/.agentchrome/extension。
5. 显示配对码并将其复制到剪贴板。

若要将所有内容保留在本机，不使用任何云服务，请添加 --local。参见本地模式。

2. 在每个 Chrome 配置文件中加载一次扩展程序

安装程序会打开 chrome://extensions，并在 Finder 中为你显示文件夹。

1. 在 chrome://extensions 中开启开发者模式。
2. 点击加载已解压的扩展程序，然后选择 ~/.agentchrome/extension。运行 agentchrome extension --path 可显示完整路径。
3. 固定 Agent Chrome，点击它，粘贴配对码，然后按连接。

若要添加其他配置文件（工作、个人、客户的配置文件），请切换到该配置文件，加载同一文件夹，然后运行 agentchrome pair 获取新配对码。每个配置文件都会在 list_browsers 中显示为独立的浏览器。

3. 开始使用

向任意 Agent 提出请求：

使用 agentchrome 打开 news.ycombinator.com，截取屏幕截图，并录制一个滚动浏览首页的短片段。

或者让你的 Agent 为你安装

将以下内容粘贴到 Claude Code、Codex 或其他任意编码 Agent 中：

按照 https://github.com/ShadowWalker2014/agentchrome/blob/main/AGENT_INSTALL.md 为我安装 agentchrome

Agent 会运行安装程序，然后告诉你唯一需要亲自完成的步骤：在 Chrome 中加载扩展程序并粘贴配对码。

在 Claude.ai 或 ChatGPT 中使用

该服务是采用 OAuth 的标准远程 MCP 服务，因此聊天应用可以将其用作连接器。你不需要使用命令行工具。

Claude（claude.ai、Claude Desktop、Cowork）：打开 Customize > Connectors > Add custom connector，输入 https://agentchrome.dev/mcp，然后点击 Connect。

ChatGPT：在 Settings > Apps & Connectors > Advanced 下开启 Developer mode，然后使用相同的 URL 创建连接器，并选择 OAuth。

系统会打开登录页面。粘贴你的账户密钥，或者如果你还没有账户，点击 Create an account。然后在聊天中询问：“连接我的 Chrome。” 助手会调用 pairing_code，并指导你加载扩展程序和粘贴代码。

各 Agent 的配置位置

Agent	配置写入位置（用户级别）	格式
Claude Code	claude mcp add --scope user（~/.claude.json）	http，带有 Authorization 标头
Codex	~/.codex/config.toml	[mcp_servers.agentchrome]，包含 url 和 http_headers
Gemini CLI	~/.gemini/settings.json	httpUrl 和 headers
Antigravity	agy mcp add 和 ~/.gemini/antigravity/mcp_config.json	serverUrl 和 headers
Grok	grok mcp add --scope user（~/.grok/config.toml）	带有标头的 http
Muse	~/.config/muse/settings.json	type: "streamable-http"
Cursor	~/.cursor/mcp.json	url 和 headers
opencode	~/.config/opencode/opencode.json	type: "remote"
Windsurf	~/.codeium/windsurf/mcp_config.json	serverUrl 和 headers

安装程序会将其编辑的每个 JSON 或 TOML 文件备份为 <file>.bak-agentchrome。该技能会链接到 ~/.claude/skills、~/.codex/skills、~/.gemini/skills、~/.gemini/antigravity/global_skills、~/.cursor/skills 和 ~/.config/opencode/skills。

Gemini CLI 注意： Gemini 会关闭你尚未信任的文件夹中的所有 MCP 服务，因此 gemini mcp list 会在这些文件夹中显示“Disabled”。在 Gemini 中使用 /permissions 信任该文件夹后，服务便会启用。

选择 Agent，或改用 OAuth 而非密钥

agentchrome install claude codex grok   # only these agents
agentchrome install --oauth             # no secret in config files; each agent signs in through the browser

使用 OAuth 时，支持 MCP 登录的 Agent（Claude Code、Codex、Gemini CLI 等）会在首次使用时打开登录页面。粘贴一次账户密钥（agentchrome key 会显示该密钥），之后 Agent 将获得有效期较短的令牌，这些令牌会在 90 天内续期。

手动添加

claude mcp add --scope user --transport http agentchrome https://agentchrome.dev/mcp \
  --header "Authorization: Bearer $(agentchrome key)"

codex mcp add agentchrome --url https://agentchrome.dev/mcp --bearer-token-env-var AGENT_CHROME_MCP_KEY

任何支持 Streamable HTTP 的 MCP 客户端都可以使用。使用 https://<server>/mcp 并提供 bearer 密钥，或者将其指向该 URL，让 OAuth 发现机制完成其余步骤。

功能介绍

你可以看到 Agent 正在做什么。 页面周围会出现蓝色边框，标签会显示当前正在操作的 Agent，并带有“停止”按钮；Agent 自己的光标会滑动到每个目标位置。光标悬停在链接上时会变成手形，悬停在文本上时会变成文本光标，并带有 Agent 的徽标和名称。不会移动你自己的鼠标。	录制画面看起来就像有人在使用页面。 record 不会显示边框、标签和名称标记，而是绘制普通光标（MP4）。传入 cursor: "agent" 可保留指示标记，传入 "hidden" 则隐藏光标。
每个 Agent 都有自己的标签组，组名取自其任务（例如“修复结账漏洞”）。弹出窗口会列出当前活跃的 Agent，并允许你暂停某个 Agent 或停止所有 Agent。	设置只需一分钟。加载扩展程序，粘贴安装程序提供的代码，即可连接配置文件。

它还可以处理真实网站中通常会导致浏览器 Agent 出错的情况：

• 拖放支持原生 HTML5 拖放事件（Trello 风格看板、文件投放区域），也支持基于指针的滑块和可排序列表。
• 文件上传不会打开原生文件选择器。Agent 可以传入电脑上的真实文件路径或文件内容。如果点击操作试图打开选择器，系统会阻止它，并提示 Agent 填写文件。
• alert、confirm、prompt 和“离开网站？”对话框会报告给 Agent，而不会让它卡住。Agent 发起的导航会离开未保存的页面，并说明这一点。
• 通过链接打开的新标签页会加入 Agent 的标签组，下载内容也会在触发下载的点击操作结果中报告。
• **会说明页面失败的原因：**HTTP 错误（例如 404）、DNS 故障、标签页崩溃、扩展程序无法访问的 chrome:// 页面，以及需要权限的 file:// 页面。
• 如果你在 Chrome 显示“已开始调试此浏览器”的提示栏上按下“取消”，所有 Agent 都会停止，并获知原因。

命令行界面

命令	功能
agentchrome setup [--server URL] [--key KEY] [--local]	创建账户或登录，在 Agent 中安装，关联技能，解压扩展程序，并打印配对码
agentchrome pair	打印新的单次使用配对码，有效期为 15 分钟
agentchrome status	显示账户、已配对浏览器及其在线状态，以及已配置的 Agent
agentchrome install [ids] [--oauth] / uninstall [ids]	添加或移除 MCP 服务和技能
agentchrome revoke <browser-id>	移除已配对的 Chrome 配置文件；连接会立即断开
agentchrome rotate-key	更换账户密钥并重写所有 Agent 配置
agentchrome key	打印账户密钥
agentchrome serve [--install]	运行本地服务；--install 会通过 launchd 设置登录时启动
agentchrome extension [--path]	解压扩展程序并显示加载方法

工具

工具名称与 Claude in Chrome 相同，因此为其编写的提示词和技能可以直接使用。

工具	功能
tabs_context	列出此会话的标签组和标签页；如果没有标签页，则创建一个包含标签页的标签组。all: true 会列出所有标签页
tabs_create / tabs_close / tabs_select	在会话标签组中打开、关闭或切换标签页；adopt 会将用户的标签页加入该组
tab_groups	列出、创建、重命名、更改颜色、折叠、移动或取消分组 Chrome 标签组
navigate	加载 URL 并等待；还支持 back、forward 和 reload
computer	screenshot、left_click、right_click、middle_click、double_click、triple_click、hover / mouse_move、left_click_drag（HTML5 和指针拖动；start_ref 或 start_coordinate）、type、key（如 cmd+a 这样的组合键）、scroll、scroll_to、wait、zoom。接受坐标或元素引用，以及 modifiers
screenshot	捕获视口；或使用 fullPage: true 捕获整页长图。它会先滚动页面以加载延迟加载的图片，并拼接在面板内滚动的应用页面，例如 Gmail、Notion 和仪表板。支持 JPEG 或 PNG；save: true 会返回下载链接
read_page	返回包含 ref_N 句柄的无障碍树；支持 filter: "interactive"、ref_id（读取子树）和 viewportOnly
find	根据自然语言描述查找元素，并返回带坐标的引用
form_input	通过引用设置输入框、选择框、复选框、单选按钮和可编辑内容字段
get_page_text	返回文章或主要内容的可读文本
javascript_tool	在页面中运行 JavaScript 并返回最后一个表达式；支持 await，且可在严格 CSP 下运行
read_console_messages / read_network_requests	返回控制台日志和错误，以及包含状态和计时信息的请求；可包含响应正文
file_upload / upload_image	使用本地文件路径、base64 数据、URL 或截图填充文件输入框或拖放区域，无需使用原生文件选择器；如果点击操作尝试打开了选择器，则省略 ref 以填充该选择器
record	录制标签页的 MP4 或 WebM 视频片段并返回链接。cursor：natural（默认，无指示标记）、agent 或 hidden；showClicks 会添加点击波纹效果。action: "scroll" 会在一次调用中生成整页平滑滚动视频
gif_creator	录制动画 GIF 并以内嵌方式返回
wait_for	等待文本出现或消失、CSS 选择器匹配，或 URL 匹配
handle_dialog	接受或关闭 alert、confirm 和 prompt 对话框
resize_window	调整浏览器窗口大小
history_search	仅当你在弹出窗口中启用后，才会搜索浏览历史
list_browsers / select_browser	列出已配对的 Chrome 配置文件并选择一个；每个工具也都接受 browser: "<name or id>"

功能对比

	Claude in Chrome	Codex Chrome extension	agentchrome
适用于任何 MCP Agent	仅限 Claude	仅限 Codex	是
每个 Agent 会话对应一个标签组	是	是	是，且 Agent 可以重命名并更改标签组颜色
同时使用多个 Chrome 配置文件	一次只能连接一个浏览器	一个配置文件	是，可同时使用所有配置文件
截图	是	是	是，包括缩放和长整页截图（滚动面板内也可）
视频录制	GIF	否	MP4 或 WebM，也支持 GIF 和一次调用即可录制的滚动视频
控制台、网络、JavaScript	是	是	是
按网站提示权限	是	是	是，默认关闭；还支持屏蔽列表
可见的“Agent 正在工作”指示器	是	是	脉冲边框、状态标签和停止按钮
动画 Agent 光标	否	是	是，带有 Agent 的徽标；悬停在链接上时显示手形光标
不带指示器的干净录制	否	否	是
通过脚本以无头模式运行（codex exec、claude -p）	否	否	是，因为它是远程 MCP 服务
可自托管	否	否	是：Cloudflare 或本地

本地模式

curl -fsSL https://agentchrome.dev/install | sh -s -- --local
agentchrome serve --install    # starts the local server now and at every login (macOS)

服务仅监听 127.0.0.1:47823，并拒绝来自网页的请求。在扩展弹出窗口中，打开 Server，并在连接前将其设置为 http://127.0.0.1:47823。截图和录制文件会保存到 ~/.agentchrome/artifacts。

在 Cloudflare 上自托管

git clone https://github.com/ShadowWalker2014/agentchrome && cd agentchrome
pnpm install
npx wrangler login
sh scripts/deploy-cloudflare.sh my-agentchrome

该脚本会创建一个 D1 数据库、一个 KV 命名空间和一个 R2 存储桶，运行迁移，部署包含 Durable Object 的 Worker，设置会话密钥，并打印你自己的安装命令（curl -fsSL https://my-agentchrome.<you>.workers.dev/install | sh）。创建自己的账户后，将 SIGNUP_MODE 设置为 "closed"，这样其他人就无法注册。

个人使用时，在 Workers 免费套餐上即可轻松运行。Durable Objects 会在调用间隔期间休眠，因此空闲的扩展连接不会产生费用。

安全

• **密钥：**账户密钥（acm_sk_…）和设备令牌（acm_dt_…）都是 256 位随机值。服务仅存储它们的 SHA-256 哈希。本地配置文件的权限设置为 chmod 600。
• **配对：**浏览器只能通过一次性 10 位代码加入你的账户，该代码 15 分钟后过期，并且只能由已持有账户密钥的人创建。每个 Chrome 配置文件都有自己的设备令牌，你可以单独撤销。
• **OAuth 2.1：**使用 @cloudflare/workers-oauth-provider，支持 PKCE（S256）、动态客户端注册、刷新令牌轮换和 RFC 9728 发现机制。
• **隔离：**每个账户都有自己的 Durable Object。MCP 会话 ID 通过 HMAC 签名并绑定到账户，因此一个账户无法使用另一个账户的会话。
• **录制文件：**你选择保存的截图和视频会存储在 R2 中，通过无法猜测的 144 位链接访问，并在 7 天后删除。
• **浏览器内控制：**网页上或弹出窗口中的停止按钮可以同时暂停所有 Agent。你也可以设置每次访问新网站前都询问、屏蔽网站，以及关闭历史记录访问（默认关闭）。
• **速率限制：**注册、配对和登录页面均按 IP 地址进行速率限制。
• **不可信网页：**技能说明和服务指令会告知 Agent，绝不要遵循网页中的指令。

请通过私密 GitHub 安全公告报告漏洞。

工作原理

Claude Code ─┐                    ┌──────────────────────────────┐        ┌─ Chrome "Work" profile
Codex ───────┤  MCP over HTTPS    │ Cloudflare Worker            │  WSS   │   (extension, paired)
Gemini ──────┼──────────────────► │  /mcp  OAuth 2.1 or API key  │ ◄────► ├─ Chrome "Personal" profile
Grok, Muse … ┘                    │  Durable Object per account  │        └─ …
                                  └──────────────────────────────┘

扩展会与服务保持一个 WebSocket 连接。服务运行在 Cloudflare Workers 上，每个账户对应一个 Durable Object。每个 MCP 会话在每个已配对的配置文件中都有自己的标签组。操作网页的工具会使用 Chrome 调试器协议处理输入、截图、控制台和网络日志。一个小型内容脚本提供元素引用、无障碍树、叠加层和 Agent 光标。

开发

pnpm install
pnpm --filter @agentchrome/server exec wrangler d1 migrations apply agent-chrome-mcp --local
pnpm dev:server                         # Worker on http://127.0.0.1:8787
node scripts/build-all.mjs              # extension, CLI and public assets
pnpm test:e2e                           # end-to-end tests: real Chromium, the extension and the MCP SDK client
node --test tests/e2e/edge.test.mjs     # drag and drop, file pickers, dialogs, new tabs, downloads, errors
ACM_SERVER=https://… pnpm test:e2e      # the same suite against a deployed server
sh tests/e2e/local.sh                   # the same suite against local mode

架构和贡献者规则请参阅 AGENTS.md。

Star 历史

如果 agentchrome 为你节省了时间，请给它点个 Star。Star 有助于其他开发者发现这个项目。

许可证

MIT