开始 / 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

> irm https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.ps1 | iex

Windows 版默认装到 %LOCALAPPDATA%\Programs\chrome-use，不需要管理员权限，并加入用户 PATH——原有条目原样保留， 包括 %USERPROFILE% 这类变量写法。下载后会强制校验 sha256：校验不过就什么都不装。 锁定版本或换位置：先设 $env:AGENT_BROWSER_VERSION = 'v1.5.139' 或 $env:AGENT_BROWSER_BIN_DIR = 'D:\tools'， 不想动 PATH 就设 $env:AGENT_BROWSER_NO_PATH = 1。

其它安装方式

需要固定版本、换安装目录，或在 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 和对应的 .sha256，确认 (Get-FileHash chrome-use-win32-x64.tar.gz -Algorithm SHA256).Hash 与 .sha256 一致，用 tar -xzf 解压，再把 chrome-use.exe 放进 PATH。运行前先对哈希：下载中断的包照样能解压出 .exe，启动时报访问违规（0xC0000005），不会提示下载不完整。连接真实 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 技能

手动安装或刷新：chrome-use skill install；只装当前项目：chrome-use skill install --project。 安装后重启 agent 或重新加载技能。全局目录覆盖 ~/.agents/skills、Claude Code、Codex、Cursor， 以及已有配置的 Pi、OpenCode、Windsurf、CodeBuddy、Trae；遵循 CLAUDE_CONFIG_DIR、XDG_CONFIG_HOME。 项目安装写入 .agents/skills、.claude/skills，以及已有的 .pi、.windsurf、.codebuddy、.trae 配置目录。

PowerShell 安装脚本也能从旧版 CLI 提取内置技能，绕过旧版 npx 依赖；按 UTF-8 读取内容，兼容 Windows PowerShell 5.1。 agent 未传入常见架构环境变量时会改查操作系统，CLI 的 JSON 错误详情也会保留。 自检超时或失败会明确报错。Windows 的 Chrome 检测不再启动浏览器，支持磁盘空间检测，使用 PowerShell 环境变量提示， 不再显示 macOS 的 ChooseBrowser 路径。可选云服务密钥无需配置；加密密钥在首次保存认证时自动生成。 Chrome Web Store 扩展仍需手动添加一次，安装完成不代表扩展已连通。

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

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

内置目录映射之外的 runner 仍可用 skills.sh 装 SKILL.md，这条可选路径需要 Node 及其自身依赖。加 -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 skills get core，再按任务读取 reference。若旧副本另带命令手册、没有引导加载 core，用 chrome-use skills update 刷新；只更新二进制不会替换该文件。

升级用 chrome-use upgrade：安装最新的 GitHub Release，再刷新找到的每一份 skill（Claude Code 插件、git checkout、安装脚本写入的目录）。chrome-use upgrade --check 或 --json 只报告当前和最新版本，不做改动；退出码 2 表示检查失败。其他命令每天最多在后台检查一次新版本；只要有新版，每次运行都会往 stderr 打一行提示，设 CHROME_USE_NO_UPDATE_CHECK=1 或 USE_NO_UPDATE_CHECK=1 可关闭。

跑通第一条命令

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

# 截一张页面图
$ 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。