agentrhq/webcmd · 上手攻略
- 仓库：agentrhq/webcmd
- 链接：https://github.com/agentrhq/webcmd
- 分类：AI · 浏览器自动化
- 作者：Jay
- 更新：2026-09-10
是什么
Webcmd 是一个面向 AI 编程 agent 的自学习浏览器基础设施。它的核心思路很直接：让 agent 在真实浏览器中完成任务，同时把网站的结构知识（sitemap、action space、pitfalls）留在本地，下次同类任务不再重复探测，直接从记忆启动。据 README 描述，理论上可将浏览器 agent 的 token 消耗降低 90%。
它不是另一个"browser-use"克隆，而是专门为 agent 上下文设计的工具——记忆层只记录有用的结构信息，不记录页面像素；Live 浏览器永远是真值，记忆永远服从实时页面。
解决什么问题
浏览器自动化 agent 常见两个痛点：
- 每次都从头探索：同样的网站，agent 每次运行都要重新发现页面结构，浪费 token和时间。
- 认证状态难管理：跨任务、跨 agent 的登录状态隔离没有标准方案。
Webcmd 用 Profile（Cookie 隔离容器）+ Session（独立浏览器窗口）+ 自学习记忆层解决这两件事。
快速安装
环境要求：Node.js 20.6+
# 全局安装
npm install -g @agentrhq/webcmd
# 验证安装
webcmd --version
# 安装后诊断（必须绿灯才能跑浏览器）
webcmd doctor
安装 agent skill（以 Codex/Claude/OpenCode 等 harness 为例）：
webcmd skills add
# 选择对应 provider（agents / codex / claude）和作用域
# 安装路径示例：~/.agents/skills/webcmd-browser/SKILL.md
安装完成后，先读 skill 文件再创建或编辑浏览器自动化逻辑：
cat ~/.agents/skills/webcmd-browser/SKILL.md
# 或项目级：./.agents/skills/webcmd-browser/SKILL.md
核心用法
Profile 与 Session 管理
# 创建 Session（Profile 隔离 Cookie，Session 隔离窗口）
webcmd --profile work session create "Work Project" -f json
# 返回：{ id: "work-project-k7" }
# 查看当前 Session 的 Tab
webcmd --profile work --session work-project-k7 browser tabs
# 在 Session 中运行 Playwright 脚本
webcmd --profile work --session work-project-k7 browser run --file explore.js
# 单行脚本（stdin）
printf 'return await page.title();' \
| webcmd --profile work --session work-project-k7 browser run --stdin
# 关闭 Session
webcmd --profile work session close work-project-k7
重要原则：并行 agent 应各自创建独立 Session；Session ID 在其 Profile 生命周期内不可变且只属于该 Profile。
给 Agent 的任务描述示例
推荐用自然语言描述目标，由 agent 自己决定浏览器操作步骤：
Use Webcmd to research the latest discussions about browser automation
across Hacker News and Reddit, then return a concise comparison with
source links.
Use Webcmd with my logged-in work profile to summarize unread LinkedIn
messages from the last seven days and return sender, subject, received
time, and conversation URL.
Use Webcmd to check Grainger part prices and SAP Ariba purchase-order
status, then return a combined summary.
关闭冲突工具（建议向用户说明后执行）
Webcmd 官方建议在 browser 任务为主的 agent 中禁用以下内置工具，由 Webcmd 替代：
| 工具类型 | 示例 | 操作 |
|---|---|---|
| Web Fetch | Claude Code WebFetch / OpenCode webfetch | 建议禁用 |
| 浏览器导航工具 | Hermes browser_* / OpenClaw browser | 建议禁用 |
| Web Search | websearch 等 | 保持开启 |
各 harness 的禁用方法见 Webcmd agent 文档（Cursor / OpenCode / Claude Code / Codex CLI / Hermes / Pi / OpenClaw 等）。
典型适用场景
适合： - 研究型任务：抓取 Hacker News / Reddit / PubMed 等网站的结构化信息（带认证状态） - 社媒监控：读取 LinkedIn 消息、X 推文书签、TikTok 内容（需登录 Profile） - 电商/物流：查 Grainger 零件价格/库存、订单状态 - AI 工具数据提取：从 ChatGPT / Claude / Gemini / NotebookLM 导出对话和笔记 - 需要登录态的网页数据采集：浏览器 Profile 保留完整 Cookie 和 session
不适合： - 纯静态页面抓取（用普通 fetch 更快更省） - 需要 JS 执行但无视觉验证的任务 - 高并发大规模爬取（Session 并行受浏览器资源限制）
坑与注意
-
webcmd doctor必须绿：安装后不先跑 doctor 直接用，大概率遇到浏览器权限或 Playwright 依赖问题。诊断不通过不要继续。 -
Session ID 只在同一 Profile 内有效：跨 Profile 传 Session ID 会导致"找不到 Session"错误。
-
并行 agent 要用独立 Session：两个 agent 共用一个 Session 会抢标签页，建议
session create隔离。 -
认证操作的审批边界：Webcmd 可以完成发帖、购买、申请等写操作，需要在用户描述中明确授权范围，agent 本身不会主动执行外部写操作。
-
Cloud 版不稳定：Webcmd Cloud（云端浏览器托管）仍在活跃开发中，非稳定状态，生产使用建议走本地。
-
MCP-based agent 暂不支持：README 明确说明 MCP-only harness（无法运行本地可执行文件的）暂不可用。
-
⚠️ benchmark 数据标注：BU Bench V1 评估中 Webcmd 自述"最高精度、最低单任务成本、最少 agent 轮次"，但评估用的是 Pi controller + Codex gpt-5.4 judge，与官方 BU Bench 原版 runner（Gemini 2.5 Flash）不同，横向可比性待独立验证。
与同类对比
| 维度 | Webcmd | browser-use | Playwright MCP |
|---|---|---|---|
| 学习记忆层 | ✅ 自学习 sitemap/记忆 | ❌ 无 | ❌ 无 |
| 认证 Profile | ✅ Profile/Session 隔离 | ❌ 无内置 | ⚠️ 需手动管理 context |
| Token 节省 | ✅ 声称 90%（⚠️待验） | ❌ 无节省 | ❌ 无 |
| MCP 支持 | ⚠️ 规划中 | ✅ | ✅ |
| Agent 生态 | Codex/Claude/OpenCode 等 | Python agent | 通用 MCP |
| Benchmark 精度 | 声称最高（⚠️条件不同） | 参考 | 参考 |
一句话推荐结论
Webcmd 是目前最适合有记忆需求的浏览器 agent 的开源方案——如果你的 Coding Agent 经常重复访问同一网站，且需要保留登录态，它值得优先集成。