开始 / Getting Started

装 chrome-use 就三件事：一行命令装好 CLI、装上 Chrome 扩展并注册本地桥、把 agent 技能拉进项目。 走 GitHub Release 的预编译二进制——无 npm、无 token，发布方和使用方都不用登录任何账号。 装完用 chrome-use doctor 一键自检。

一行装好 CLI

从最新的 GitHub Release 下载对应平台的预编译二进制，装好 chrome-use（以及 abs 短别名）。这是主要分发渠道，不经过 npm，也不需要任何 token。

$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh

其它安装方式

需要固定版本、换安装目录，或在 Windows 上手动放置时：

# 固定某个版本
$ AGENT_BROWSER_VERSION=v1.5.70 curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh

# 装到自定义目录
$ AGENT_BROWSER_BIN_DIR=$HOME/bin curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh

• Windows：从 Releases 页面 下载 chrome-use-win32-x64.tar.gz，把 chrome-use.exe 放进 PATH。连接真实 Chrome 的扩展路径 Windows 同样支持，见下一节。
• npm（遗留）：npm install -g chrome-use 仍在发布，但 GitHub Releases 是现在的主渠道。

使用 Nix 安装

可以直接运行仓库 flake，也可以导入 Home Manager 或 NixOS 模块进行声明式安装：

# 不安装，直接运行
$ nix run github:leeguooooo/chrome-use -- --help

# flake 输入
inputs.chrome-use.url = "github:leeguooooo/chrome-use";

# Home Manager：安装并在激活时注册原生消息 host
imports = [ inputs.chrome-use.homeManagerModules.default ];
programs.chrome-use.enable = true;

# NixOS：系统级安装，并可选强制安装浏览器扩展
imports = [ inputs.chrome-use.nixosModules.default ];
programs.chrome-use = {
  enable = true;
  forceInstallExtension = true;
};

NixOS 模块会写入 Chrome 和 Chromium 的托管扩展策略。原生消息 host 按用户注册；系统切换后运行一次 chrome-use extension connect，或同时使用上面的 Home Manager 模块。

可选的版本 tag 见 版本沿革——从 agent-browser fork（早期 v0.x-fork.N tag）到今天 chrome-use 的 v1.5.x tag 演进。

装扩展、连你的真实 Chrome

要驱动你已经登录好的真实 Chrome（复用现成会话、不弹确认框），装浏览器扩展并注册一次本地桥。这是推荐路径。

1. 从 Chrome 应用商店安装 chrome-use 扩展，一键 Add to Chrome。 商店版重启后依然稳定，适合无人值守。认准商店名 chrome-use、扩展 ID knfcmbamhjmaonkfnjhldjedeobeafmk（仓库内部代号 ab-connect），确认没装错。
2. 注册原生消息（native-messaging）主机——一次性：

# 注册本地桥（一次性）
$ chrome-use extension install

# 之后 open 就直接驱动你已登录的 Chrome
$ chrome-use open https://x.com/home

此后 chrome-use open 通过 原生消息驱动你真实、已登录的 Chrome——无调试端口、无 token， 也永远不弹「Allow remote debugging?」确认框。扩展会自动更新、重启后依然连着，之后每次调用都不用再点确认。想深入了解连接原理见 连接真实 Chrome。

$ chrome-use extension install --no-profile      # 不写策略描述文件
$ chrome-use extension install --all-profiles    # 在每个缺失的 profile 里打开商店页

$ profiles remove -identifier com.leeguoo.chrome-use.connect

拉 agent 技能

Claude Code 推荐走 plugin marketplace：全局生效（所有项目）、自动更新，还能顺带发现 *-use 全家桶里的其他工具：

> /plugin marketplace add leeguooooo/plugins
> /plugin install chrome-use@leeguooooo-plugins

其他 agent runner（Cursor、Codex、CodeBuddy、Trae、Windsurf、Cline、自研脚本）用 skills.sh 装 SKILL.md。加 -g 装到全局（所有项目可见）；去掉 -g 只装当前项目：

$ npx skills add leeguooooo/chrome-use -g

Codex 用户注意：Codex 自带浏览器插件，遇到浏览器任务会优先选它。实测在装了很多技能的机器上， Codex 会把每条技能描述截到几个字符甚至截空，所以技能描述赢不了路由，在提示词里点名 chrome-use 也不够。有效的办法是在项目的 AGENTS.md 里写一行：

Use the `chrome-use` CLI from the shell for every browser task; start with `chrome-use skills get core`.
Do not use the built-in Chrome plugin for browser work here.

两种装法都让 AI agent 拿到正确的用法模式和对 chrome-use、abs 预授权的 bash 权限； 专门化指南（electron / slack / agentcore …）由二进制经 chrome-use skills get <name> 提供， 永远和已装版本一致。装好后建议先读一遍 核心循环。

跑通第一条命令

浏览器在多条命令之间保持运行，所以下面这些命令感觉像一次会话。完事用 chrome-use close（或 close --all）收尾。

# 截一张页面图
$ chrome-use open https://example.com
$ chrome-use screenshot home.png
$ chrome-use close

想看 open → snapshot -i → fill → click 的完整走查（搜索、点结果、再截图），读 核心循环； 每条命令和参数见 命令参考。

诊断安装问题

命令意外失败时（Unknown command、Failed to connect、守护进程卡死、upgrade 后版本不一致、找不到 Chrome 等）， 先跑 doctor，别的都放后面。

# 完整诊断：环境、Chrome、守护进程、配置、providers、网络、启动自测
$ chrome-use doctor
$ chrome-use doctor --offline --quick   # 快速、纯本地
$ chrome-use doctor --fix               # 执行破坏性修复（重装 Chrome、清旧状态…）
$ chrome-use doctor --json              # 结构化输出，供程序消费

doctor 每次运行都会自动清理陈旧的 socket / pid / 版本 sidecar 文件；破坏性操作只有加 --fix 才执行。 退出码：全部通过（含 warning）为 0，有任何 fail 为 1。