Surf CLI
为 AI Agent 打造的 Chrome 控制 CLI：零配置、不绑定特定 Agent、经实战检验，任何能执行 shell 命令的 Agent 都能借此驱动浏览器。
- Star 数
- ★ 640
- 最近更新
- 今天
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 77/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Claude Code
- 费用
- 免费，无需付费服务
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 使用 Claude Code 等 AI 编程 Agent 的开发者，需要在真实浏览器中执行端到端网页验证（登录、填表、点击），而不想配置 MCP 服务器
- 不适合
- 需要自动化 chrome:// 页面或 Chrome 应用商店的团队
- 需要完全隔离浏览器配置、Cookie 与登录态的团队
- 在 Windows 上部署远程 Tailscale 监听器的用户
- 源码审查
- 77/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
Surf（npm 包名 surf-cli）是一个让 AI Agent 通过命令行控制 Chrome 的工具，采用 Unix socket 加 Chrome 扩展加原生宿主（native host）的架构，并基于 Chrome DevTools Protocol 执行操作。它不依赖任何 MCP 服务器或中继进程，安装扩展并运行 surf install 后即可使用，与 Claude Code、GPT、Gemini、Cursor 或自定义脚本均兼容。CLI 提供 50 余条命令，覆盖导航、读取可访问性树、点击、填表、截图、iframe 切换、设备仿真、网络请求捕获、GIF/视频录制和性能审计。其亮点是可复用浏览器已登录会话直接查询 ChatGPT、Gemini、Perplexity、Grok、Kimi 等，无需 API 密钥。它还支持通过 Tailscale 进行远程控制，并使用 Ed25519 双向挑战-响应认证保护连接，整个项目以 MIT 协议开源。
Surf 通过 Chrome 原生消息机制连接 CLI 与浏览器扩展，在 /tmp/surf.sock（Windows 为 //./pipe/surf）上监听 JSON 请求。核心命令包括：surf go 导航、surf read 读取可访问性树和可见文本（支持 --depth、--compact、--max-bytes 压缩输出）、surf click/type/scroll/select 按元素引用（e5）、CSS 选择器或语义定位器（locate.role/locate.text/locate.label）操作页面、surf screenshot/snap 自动保存并缩放到 1200px 的截图。它会自动捕获所有网络请求，可用 surf network 过滤查询、network.body 提取响应体、network.export 导出 HAR。surf do 支持管道分隔的多步工作流（含 JSON 工作流文件、循环和步骤输出），playbook 体系支持可复用的站点操作与回退策略。surf chatgpt/gemini/perplexity/grok/kimi/aistudio 利用浏览器登录态直接调用各 AI 服务，surf oracle 提供持久化的 ChatGPT 咨询任务。此外还有 session.ensure 持久会话管理（支持多 Agent 并发）、frame.switch iframe 操作、emulate.device 设备仿真、record 动图录制和 perf-audit 性能审计。
- 使用 Claude Code 等 AI 编程 Agent 的开发者，需要在真实浏览器中执行端到端网页验证（登录、填表、点击），而不想配置 MCP 服务器
- 需要抓取和分析页面网络请求的工程师，用 surf network/network.export 无需手动设置拦截即可过滤和回放 API 调用
- 希望复用浏览器登录态调用 AI 服务、又不想申请 API 密钥的用户，用 surf chatgpt/gemini/grok 直接查询
- 运行多个并行 Agent 的团队，用 SURF_SESSION 和 session.ensure 为每个 Agent 分配独立标签页，避免互相干扰
- 需要在另一台 Tailnet 机器上远程驱动浏览器的研究者，用 surf remote authorize 加 --listen 配置经 Ed25519 认证的远程访问
- 需要生成网页交互演示的开发者，用 surf record 和 surf video 录制 GIF/WebM
如何安装或部署这个 Agent？
- 全局安装：npm install -g surf-cli
- 加载扩展：打开 chrome://extensions，启用开发者模式，点击“加载已解压的扩展程序”，粘贴 surf extension-path 输出的路径
- 安装原生宿主（从 chrome://extensions 复制扩展 ID）：surf install <extension-id>；可选 --browser brave|helium 等或 --browser all；WSL2 环境用 --target linux 针对 WSLg 内的 Linux 浏览器
- 重启 Chrome 并运行 surf tab.list 验证
排障：运行 surf doctor 检查 socket 路径、native messaging manifest 与扩展 ID 是否匹配。
如何使用这个 Agent？
基本流程：surf go "https://example.com" 导航 → surf read 读取页面（返回 e1/e2/e3 等稳定元素引用）→ surf click e5 或 surf type "text" --ref e12 交互 → surf snap 截图（自动保存至 /tmp 并缩放到 1200px）。多步操作可用 surf do 'go "url" | click e5 | screenshot' 一次执行。对 shell Agent，建议先 export SURF_SESSION="<唯一名>" 并运行 surf session.ensure "$SURF_SESSION" about:blank 以获得独立会话。运行 surf --help-full 查看全部 50+ 命令，surf --llm-context 获取面向 AI Agent 的紧凑参考。AI 查询需在 Chrome 中登录对应服务（如 chatgpt.com、gemini.google.com），然后如 surf chatgpt "summarize" --with-page。
这个 Agent 有哪些优点和局限？
- Agent 无关：纯 CLI 命令走 Unix socket，Claude Code、GPT、Cursor、shell 脚本均可直接调用，无需 MCP 配置或中继进程
- 经实战打磨：作者通过逆向工程生产级浏览器扩展并在 Discord 设置等对 Agent 不友好的页面上反复测试构建，CDP 失效时可优雅回退到 chrome.scripting API
- 为 Agent 优化：截图自动缩放到 1200px 节省 token，操作后自动截图减少往返，受限页面报错降级为警告而非失败
- 独有能力：复用浏览器登录态查询 ChatGPT/Gemini/Perplexity/Grok/Kimi 而无需 API 密钥，并内置自动网络请求捕获与 HAR 导出
- 多 Agent 并发：session.ensure 提供持久会话、每标签页 FIFO 调度与浏览器级互斥写操作，配合 Tailscale 远程模式与 Ed25519 双向认证
- 必须手动加载未打包的 Chrome 扩展并安装原生宿主，重启浏览器后才可用，首次部署比托管方案繁琐
- 受 Chrome 限制无法自动化 chrome:// 页面和 Chrome Web Store；新标签页首次 CDP 操作需 100-500ms 调试器附加延迟
- 基于浏览器 UI 的 AI 查询依赖对应网站的界面结构，官方提供了 surf grok --validate 等“可能随 UI 变更失效”的排障命令，暗示存在脆弱性
- Linux 支持标记为实验性且未在生产环境验证；远程监听器不支持 Windows 原生宿主，且不含额外 TLS/SSH 隧道，需依赖 Tailnet ACL 作纵深防御
- 会话共享同一 Chrome profile，Cookie、认证等状态互相可见，硬隔离需配置独立浏览器实例与 SURF_SOCKET
这个 Agent 与同类方案有什么区别？
README 自带的对比表将 Surf 与 Manus（仅 Manus 专用、需订阅、云端）、Claude Extension（仅 Claude 专用、需订阅）、DevTools MCP（需 MCP 配置）、dev-browser（Claude skill、需中继服务器）对比。Surf 的差异化在于：唯一同时具备 Agent 无关、零配置、CLI 接口、免费且支持通过浏览器 Cookie 调用 AI 的方案；Manus、Claude Extension 均绑定各自生态且收费，DevTools MCP 与 dev-browser 需要额外配置且部分限制在特定 Agent 生态。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Surf CLI 当前 | 77 · 存在缺口 | 命令行工具免费 | ★ 640 | 今天 | TypeScript | Claude Code |
| BrowserSkill | 49 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 9.4k | 今天 | TypeScript | Codex · Claude Code |
| Interceptor | 57 · 缺口较多 | 命令行工具免费 | ★ 564 | 1 天前 | TypeScript | Codex · Claude Code · Claude.ai |
| OpenTabs | 49 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 990 | 2 个月前 | TypeScript | Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示工具在设计上有安全意识：默认 socket 权限 600、远端采用 Ed25519 双向挑战-响应、每客户端凭据可撤销、群组共享 socket 为显式选择加入并附警告；但任何持有凭据或本机访问权的代理获得与受信用户等同的完整浏览器与主机文件权限，默认即共享整个 Chrome 配置文件的 Cookie 与登录态，最小权限只能算部分达成。常规代理驱动的浏览器操作没有用户确认机制，仅 playbook 显式写入需要 --write 且支持 --dry-run，扣分。数据流透明度较好：远端传输的分段、暂存、删除、256MiB 上限、remote: 直通路径均有文档。敏感数据方面凭据处理规范（0600、撤销命令），但网络捕获会自动记录所有请求，页面截图默认落盘 /tmp，未见脱敏说明。依赖安全有 npm audit --audit-level=critical 与每周 CodeQL，但未见 lockfile 或依赖策略文件。外部影响有充分文档（FIFO 调度、浏览器级写入互斥、副作用不回滚）。回滚明确欠缺：文档直陈'已完成的浏览器副作用不会回滚'，仅 cleanup 有 dry-run，扣分。来源归属：作者署名、MIT、仓库与 issue 链接齐全；发布者未验证按要求不加分也不扣分。
自洽性良好：命令命名统一（tab.list、session.ensure 等点分式），shell 测试验证旧命令名有迁移提示，README 与 package.、测试相互一致。依赖可用性：可选依赖要求明确说明（ImageMagick 的 magick/convert、ffmpeg 需在 PATH、CI 钉住 Chrome for Testing 版本、Node 版本在 CI 钉住）。失败消息是本仓库亮点：集成测试断言 socket 缺失时输出'Socket connect failed'、建议运行 surf doctor、提示 SURF_SOCKET；会话丢失时打印可复制的恢复命令（Recovery: surf session.reopen research），故满分。
受众与场景覆盖充分：面向 AI 代理与 shell 脚本，示例覆盖导航、表单、iframe、多代理并发会话、远程 Tailnet、录制与性能审计。能力边界描述较全（50+ 命令、受限页面警告而非失败、传输边界拒绝目录与多文件、远端不支持 Windows 原生宿主），但边界主要靠文档罗列，缺乏程序化能力协商说明，未给满分。触发精度高：标志语义、前置条件（--idle-after 必填、--selector 必填）、优先级规则（--remote 覆盖 SURF_REMOTE）均精确定义。环境适配出色：macOS/Linux/Windows、WSL2 双向路径、Nix/Homebrew 环境变量、Brave/Edge/Arc 等多浏览器均有说明。
信息架构优秀：README 从 Why、对比、安装、使用分组到远程运维层层递进，帮助系统分层（--help/--help-full/--help-topic/--find）。安装说明细致到 WSL2、包管理器路径变量、多浏览器与卸载，满分。命名稳定性有测试保障（read_page→page.read 等迁移提示被 shell 测试断言）。示例丰富且每条命令带示例（测试断言 help 含 Examples）。已知局限有相当披露（副作用不回滚、远端 POSIX 限制、会话共享配置文件风险），但缺乏集中章节，扣一分。LICENSE 文件完整 MIT，与 badge 与 package. 一致，满分。版本 2.18.0 在 package.，README 引用 CHANGELOG.md，但变更日志内容不在证据内，版本策略未说明。维护责任：单一作者、CI 完整（lint/test/typecheck/real-chrome E2E/audit），但无 CONTRIBUTING、安全政策或治理文件，维护路径依赖个人。
输出可用性强：JSON 输出选项、字节上限、compact/depth 裁剪、stderr 元数据（tab=42 window=7 queued=ms）、自动截图减少往返，均有测试佐证，满分。边际价值明确：代理无关的 CLI over Unix socket + 原生消息宿主方案确实与 MCP/dev-browser 方案差异化，浏览器 Cookie 免 API Key 查询是独特能力。成本收益：声称 token 节省（截图 1200px、--llm-context），方向合理但无量化数据，且多代理会话需要额外的隔离配置成本，扣一分。
主张可追溯性中等：协议、错误消息、调度语义均可被仓库内测试与 README 交叉印证；但'battle-tested'为断言，对比表中竞争对手的能力描述无法从仓库内验证。跨源一致性：README、package.（版本、MIT、仓库地址）、CI 工作流、shell/e2e 测试之间未发现矛盾，一致面较广但覆盖不到全部 50+ 命令。事实与推断区分：大多陈述具体可查，但营销语（'Smart Defaults saves tokens'）与规格陈述混排，未显式区分，未给满分。本审查为静态审查，未执行任何测试，置信度为 low。
- 任何获得 surf 凭据或本机 socket 访问权的代理拥有与受信用户等同的完整浏览器权限，包括已登录会话的 Cookie；多代理共用配置文件时状态互相可见，硬隔离需独立配置文件与原生宿主。
- 已执行的浏览器副作用不会回滚；写入类 playbook 操作前应使用 --dry-run 并在低风险环境验证。
- 网络捕获会自动记录所有请求（可能含敏感令牌），截图默认写入 /tmp；在高敏环境需评估落盘与日志留存风险。
- 发布者身份未经企业注册表验证，且维护依赖单一作者；生产采用前应评估其响应与更新路径。
- 本审查为静态源码审查，未执行任何测试；'battle-tested'等主张未经独立验证。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
Surf now tells you what happened after you act on a page. A click, typing or a key press prints what changed, such as a dialog that opened, new buttons you can use, or a navigation, so an agent often doesn't need another full read. When you do want to look around, read --summary gives a small overview of the page instead of the whole tree. This release also removes two ways surf used to get stuck or mislead you: a native alert() no longer hangs every command, and acting on an element the page already replaced now fails clearly instead of doing nothing. Highlights …在 GitHub 查看 ↗ -
发布说明摘录
Surf 2.21.1 keeps browser automation aligned with current Chrome and updates its supporting integrations. Puppeteer 25.12 now drives Chrome 154 in real-browser checks, avoiding browser-version mismatches. Pi Subagents and the MCP SDK pick up their latest compatibility and reliability fixes. This is a maintenance release with no CLI changes or migration required. Highlights - Run Surf's real-browser integration against Chrome 154 through Puppeteer 25.12. - Use the latest Pi Subagents reliability improvements. - Pick up current compatible fixes for MCP, Vite, and Node.js types. …在 GitHub 查看 ↗ -
发布说明摘录
Surf 2.21.0 makes everyday browser actions faster and makes page reading more reliable. Clicks, typing, scrolling, and js now return as soon as the action is done instead of waiting for a screenshot. After you switch into an iframe, reading the page reads that iframe, and js refuses to run in the wrong frame instead of quietly running in the main page. page.read can now list the whole page, including hidden elements, and no longer fails on very long pages. Highlights - Clicks, typing, scrolling, and js return faster because they no longer wait for the automatic screenshot. …在 GitHub 查看 ↗