开始 / Getting Started

安装

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

扩展图标打开本机 agent 侧栏。macOS、Linux 和 Windows 支持 Codex、Claude Code、OpenCode 和 Pi，提供当前页面标签、CLI 模型下拉、按 agent 区分的权限开关和会话删除。旧 Windows 主机需升级 CLI，完整侧栏功能不需要管理员权限。操作与隐私说明见 本机 agent 侧栏。

一行装好 CLI

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

一行装好 · macOS / Linux 
$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh
一行装好 · Windows（PowerShell） 
> 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。

安装检查核验磁盘文件，不会替换正在运行的 native host。升级时 Chrome 已打开的，等 agent 会话空闲后在 chrome://extensions 重新加载扩展。重连会话 daemon 不会替换 host。status 的 health.nativeHostVersion 来自实际 host 握手，无法取得时为 null；无法核实或与 CLI 版本不一致时给出警告，hostLauncherHealthy 只表示磁盘启动器正常。

ℹ️ 一个二进制
没有单独的「stealth 可执行文件」；反检测是运行时行为，连你的真实 Chrome 就零补丁，--launch 开新浏览器才上全套补丁。详见 连接真实 Chrome。

其它安装方式

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

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

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

使用 Nix 安装

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

nix 
# 不安装，直接运行
$ 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 演进。

⚠️ 装了多份会互相遮盖
如果 which -a chrome-use 显示不止一个安装，旧的 npm / pnpm 拷贝可能盖住了 install.sh 装的新版本 （npm registry 落后于 GitHub Releases）。删掉旧拷贝——npm rm -g chrome-use 或 pnpm rm -g chrome-use——让新构建生效。

装扩展、连你的真实 Chrome

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

在 macOS/Linux 上，chrome-use extension install 还会为正在运行、以 --user-data-dir=<path> 单独启动的 Chromium 系浏览器注册本地 host，扫描到的自定义目录必须已经存在。如果浏览器尚未运行或无法被扫描到，可执行 chrome-use extension install --user-data-dir "/path/Chrome Data"；也接受 --user-data-dir=<path>，可重复指定多个目录。显式指定的目录不存在时会报错。命令会列出写入的清单，并回读校验 host 名称和启动器路径。这只确认注册完成；之后请在该 Chrome 里重新打开侧栏，或等扩展自动重连。Windows 使用 HKCU 注册表注册，不支持此选项。 自动扫描仅限当前用户的进程；发现目录写入或校验失败时警告并跳过，可用 --user-data-dir 重试，默认或显式目录失败仍报错。成功写入的自定义数据目录记录在 ~/.chrome-use/custom-host-dirs.json，供状态查询和浏览器停止后的卸载清理使用；记录失败会警告卸载可能残留清单。

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

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

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

ℹ️ Windows 也走这条扩展路径
chrome-use extension install 在 Windows 上同样可用：它把 native-messaging host 注册进 HKCU 注册表， 再从应用商店手动装一次扩展即可（Windows 没有 macOS 那套静默强制安装）。之后 chrome-use open 一样驱动你已登录的 Chrome。
⚠ macOS：那个「策略描述文件」会让 Chrome 进入受管理状态

extension install 在 macOS 上会提供一条「静默装进所有 profile」的路径：批准一个 ExtensionInstallForcelist 策略描述文件。它确实一劳永逸，但代价是 Chrome 会变成 「由贵单位管理」：

  • 「使用安全 DNS (DoH)」被停用并锁死——依赖自定义 DoH 的站点（如 linux.do）会解析失败（#187）。
  • 扩展显示「由管理员安装」：没有手动更新/删除按钮，更新交给 Chrome 自动从商店拉取（#186）。

不想要就跳过它——从商店装扩展的效果完全一样，只是每个 profile 要点一次「加入 Chrome」： 

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

已经批准过、想退出受管理状态（自定义 DoH 会立刻恢复）： 

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

注意：移除策略后 Chrome 会一并卸载它装的扩展——之后在每个 profile 里从商店重新「加入 Chrome」即可， 还是同一个扩展、照样自动更新，而且这次归你自己管。chrome-use extension status 会实时告诉你当前处于哪种状态。

✅ 不想碰你的真实 Chrome？
用 chrome-use --launch open <url> 开一个全新的、隔离的空 profile 浏览器（上全套反检测补丁）， 无需扩展，CI 会自动走这条路。需要真实 cookies / 登录态时改用 --profile auto。

profile 里要开着窗口

chrome-use 只把标签页放进已经开着窗口的 profile，从不自己开窗口（那会把 Chrome 弹到你面前）。没有窗口时它会停下并报 profile not open（错误码 profile_not_open）：先在那个 profile 里打开一个窗口，再重跑。 判断不了有没有窗口时报 profile window unavailable（profile_window_unavailable）。 判断不了就什么都不创建，这两个错误都不会自动重试。第一个标签页清理相关的错误码见故障排查。

拉 agent 技能

安装脚本已包含技能安装与校验
install.sh 和 install.ps1 安装 CLI 内置的发现入口，不需要 Node、npx、Git 或额外下载。 任一目录写入失败都会报错，不再无条件显示全部就绪。可用 AGENT_BROWSER_NO_SKILL=1 跳过。

手动安装或刷新：chrome-use skills install；只装当前项目：chrome-use skills 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 全家桶里的其他工具：

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

内置目录映射之外的 runner 仍可用 skills.sh 装 SKILL.md，这条可选路径需要 Node 及其自身依赖。加 -g 装到全局（所有项目可见）；去掉 -g 只装当前项目：

bash 
$ npx skills add leeguooooo/chrome-use -g

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

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 预授权的 bash 权限； 专门化指南（electron / slack / agentcore …）由二进制经 chrome-use skills get <name> 提供， 永远和已装版本一致。装好后建议先读一遍 核心循环。

ℹ️ 技能装不上时自愈
plugin 和 skills add 都只带 markdown，不附带 ~28MB 的二进制。如果技能环境里没有 chrome-use， 重新跑一次上面的 install.sh 一行命令即可补齐二进制（技能本身也会教 agent 自愈）。

安装到运行器的发现入口会先加载一次 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 收尾。

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

✅ 反检测自检
要在敏感流程前确认 stealth 状态，用 chrome-use stealth status（加 --json 拿结构化结果）—— 它跑 webdriver / chrome / plugins / UA 的实时探针并列出已应用的 override，比去驱动外部检测器更可靠。
⚠️ 弹了「Allow remote debugging?」别硬重试
每次重试都会再弹一次。要么你的 chrome-use 太旧（重跑 install.sh 升级），要么扩展 / 本地桥没起来 （装商店扩展后这个框就再也不出现）。更多排障见 排障。

本机 agent 侧栏支持输入 / 选择技能、图片附件、会话工具与模型参数，以及独立后台 session 的定时提示。完整流程见 本机 agent 侧栏。

源码仓库：贡献者 hook

Git pre-push hook 默认不会同步到 ClawHub，普通推送不需要 pnpm 或 ClawHub。维护者可用 CHROME_USE_CLAWHUB_SYNC=1 git push 为单次推送启用同步。只有值 1 才会启用；SKIP_CLAWHUB_SYNC=1 始终优先跳过。同步失败只发出警告，不阻止推送。手动执行 pnpm run clawhub:sync 的行为不变。这些变量仅控制源码仓库的 hook，不影响已安装的 CLI。

在 Linux 上安装了 Docker 且本地已有 node:24-bookworm 镜像时，可运行 sh scripts/test-pre-push-sandbox.sh 测试 hook。脚本不会拉取镜像或安装依赖，先检查隔离条件，再使用模拟发布器验证临时本地 Git 推送。容器以非特权用户运行，无网络或宿主目录挂载，使用只读根文件系统、临时存储和资源限制。