kaiyuan/chatgpt-on-wechat
1
0
Fork 0
mirror of https://github.com/zhayujie/chatgpt-on-wechat.git synced 2026-06-02 00:57:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(browser): persistent login + CDP attach mode #2809

Browse Source 
Browser sessions now reuse a Chromium user profile across runs by default
(`~/.cow/browser_profile`), so users only log in to a site once.
Three launch modes are selectable via `tools.browser` in config.json:
  - persistent (default): Playwright Chromium with a persistent user_data_dir
  - cdp: attach to an externally launched real Chrome via `cdp_endpoint`
    (full fingerprints, ideal for sites with strict bot detection)
  - fresh: clean context every run, set `persistent: false`

Also:
  - Self-heal when the user closes the browser window mid-session: detect
    closed page/context/browser via close listeners and exception scanning,
    then transparently relaunch on the next request.
  - Graceful CDP shutdown: disconnect only, never kill the user's Chrome.
  - Friendly errors when the CDP endpoint is unreachable or the persistent
    profile is locked, so the LLM can guide the user instead of looping.
  - Fix tool config being silently overwritten by workspace config in
    AgentInitializer; per-tool user settings (e.g. browser.cdp_endpoint)
    are now merged instead of replaced.
  - Update zh / en / ja docs with the new login-persistence section,
    including the Chrome 137+ requirement to pair --remote-debugging-port
    with a dedicated --user-data-dir.
This commit is contained in:
zhayujie
2026-05-19 11:52:11 +08:00
parent a85c5f9d4e
commit a0dfdb79df
6 changed files with 592 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
docs/en/tools/browser.mdx
View File

@@ -1,25 +1,172 @@
---
title: browser - Browser
description: Access and interact with web pages
description: Control a browser to access and interact with web pages
---
Use a browser to access and interact with web pages, supports JavaScript-rendered dynamic pages.
Control a Chromium browser for web navigation, element interaction and content extraction. Supports JavaScript-rendered pages and uses a compact DOM snapshot so the Agent can efficiently understand page structure.
## Dependencies
## Installation
| Dependency | Install Command |
| --- | --- |
| `browser-use` ≥ 0.1.40 | `pip install browser-use` |
| `markdownify` | `pip install markdownify` |
| `playwright` + chromium | `pip install playwright && playwright install chromium` |
<Tabs>
<Tab title="CLI install (recommended)">
```bash
cow install-browser
```
This command will:
- Install the `playwright` Python package (with auto-fallback for older systems)
- Install system dependencies on Linux
- Download the Chromium browser (Linux servers automatically use the headless build)
- Detect China-mainland networks and use mirror acceleration
</Tab>
<Tab title="Manual install">
```bash
pip install playwright
playwright install chromium
```
On Linux servers, install system dependencies as well:
```bash
sudo playwright install-deps chromium
```
On older systems (e.g. Ubuntu 18.04, glibc < 2.28), install a compatible version:
```bash
pip install playwright==1.28.0
python -m playwright install chromium
```
To accelerate the Chromium download from China:
```bash
export PLAYWRIGHT_DOWNLOAD_HOST=https://registry.npmmirror.com/-/binary/playwright
python -m playwright install chromium
```
</Tab>
</Tabs>
<Note>
1. Supported on Ubuntu 20.04+, Debian 10+, macOS and Windows. Older systems such as Ubuntu 18.04 will fall back to a compatible version automatically.
2. The browser tool has heavy dependencies (~300MB) and is optional. For lightweight web content retrieval, use the `web_fetch` tool.
</Note>
## Workflow
A typical browser workflow for the Agent:
1. **`navigate`** — Open the target URL
2. **`snapshot`** — Get a compact DOM with auto-numbered interactive elements (`ref`)
3. **`click` / `fill` / `select`** — Operate elements by `ref`
4. **`snapshot`** — Snapshot again to verify the result
## Supported Actions
| Action | Description | Key parameters |
| --- | --- | --- |
| `navigate` | Open URL | `url` |
| `snapshot` | Get structured page text (primary way) | `selector` (optional) |
| `click` | Click an element | `ref` or `selector` |
| `fill` | Fill text into an input | `ref` or `selector`, `text` |
| `select` | Select a dropdown option | `ref` or `selector`, `value` |
| `scroll` | Scroll the page | `direction` (up/down/left/right) |
| `screenshot` | Save a screenshot to the workspace | `full_page` |
| `wait` | Wait for an element or timeout | `selector`, `timeout` |
| `press` | Press a key (Enter, Tab, etc.) | `key` |
| `back` / `forward` | Browser back / forward | - |
| `get_text` | Get an element's text content | `selector` |
| `evaluate` | Run JavaScript | `script` |
## Use Cases
- Access specific URLs to get page content
- Interact with web page elements (click, type, etc.)
- Verify deployed web pages
- Scrape dynamic content requiring JS rendering
- Access a URL to retrieve dynamic page content
- Fill in forms and log in
- Operate web elements (click buttons, select options, etc.)
- Verify the result of a deployed web page
- Scrape content that requires JS rendering
## Run Mode
The browser picks a mode based on the runtime environment:
| Environment | Mode |
| --- | --- |
| macOS / Windows | Headed (browser window visible) |
| Linux desktop (with DISPLAY) | Headed |
| Linux server (no DISPLAY) | Headless |
You can override it in `config.json`:
```json
{
"tools": {
"browser": {
"headless": true
}
}
}
```
## Persistent Login
**Log in to a target site once and the Agent can keep using it.** Two ways are supported:
### Option 1: Persistent mode (default)
Works out of the box. Login state is saved under `~/.cow/browser_profile`. No configuration needed.
To disable persistence and start with a clean environment every time:
```json
{
"tools": {
"browser": {
"persistent": false
}
}
}
```
### Option 2: CDP mode (attach to real Chrome)
Have the Agent connect to a separately launched real Chrome (instead of the Chromium bundled with Playwright) for full browser fingerprints. Useful for sites with strict bot detection.
Launch Chrome with a debugging port and a dedicated user data directory:
<Tabs>
<Tab title="macOS">
```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.cow/chrome-cdp"
```
</Tab>
<Tab title="Linux">
```bash
google-chrome \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.cow/chrome-cdp"
```
</Tab>
<Tab title="Windows">
```powershell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
--remote-debugging-port=9222 `
--user-data-dir="$env:USERPROFILE\.cow\chrome-cdp"
```
</Tab>
</Tabs>
Then point the Agent at the endpoint in `config.json`:
```json
{
"tools": {
"browser": {
"cdp_endpoint": "http://localhost:9222"
}
}
}
```
<Note>
The browser tool has heavy dependencies. If not needed, skip installation. For lightweight web content retrieval, use the `web-fetch` skill instead.
Chrome 137+ requires `--remote-debugging-port` to be paired with a dedicated `--user-data-dir`. As a result, the CDP-launched Chrome **cannot directly reuse the login state of your daily Chrome**; you'll need to log in once inside this dedicated profile.
</Note>

171
docs/ja/tools/browser.mdx
View File

@@ -1,25 +1,172 @@
---
title: browser - ブラウザ
description: Webページへのアクセスと操作
description: ブラウザを操作してWebページにアクセス・操作する
---
ブラウザを使用してWebページにアクセス・操作します。JavaScriptでレンダリングされる動的ページにも対応しています。
Chromiumブラウザを操作してWebページのナビゲーション、要素操作、コンテンツ取得を行います。JavaScriptでレンダリングされる動的ページに対応し、簡略化したDOMスナップショットによりAgentが効率的にページ構造を理解できます。
## 依存関係
## インストール
| 依存関係 | インストールコマンド |
| --- | --- |
| `browser-use` ≥ 0.1.40 | `pip install browser-use` |
| `markdownify` | `pip install markdownify` |
| `playwright` + chromium | `pip install playwright && playwright install chromium` |
<Tabs>
<Tab title="CLIインストール（推奨）">
```bash
cow install-browser
```
このコマンドは以下を自動で実行します：
- `playwright` Pythonパッケージのインストール（古いシステムでは互換バージョンに自動フォールバック）
- Linuxにおけるシステム依存のインストール
- Chromiumブラウザのダウンロード（Linuxサーバーでは自動的にヘッドレス軽量版を使用）
- 中国本土ネットワークの自動検知とミラー高速化
</Tab>
<Tab title="手動インストール">
```bash
pip install playwright
playwright install chromium
```
Linuxサーバーではシステム依存も必要：
```bash
sudo playwright install-deps chromium
```
古いシステム（例: Ubuntu 18.04、glibc < 2.28）では互換バージョンをインストール：
```bash
pip install playwright==1.28.0
python -m playwright install chromium
```
中国からChromiumのダウンロードを高速化したい場合：
```bash
export PLAYWRIGHT_DOWNLOAD_HOST=https://registry.npmmirror.com/-/binary/playwright
python -m playwright install chromium
```
</Tab>
</Tabs>
<Note>
1. Ubuntu 20.04+、Debian 10+、macOS、Windowsをサポート。Ubuntu 18.04などの古いシステムでは互換バージョンに自動フォールバックします。
2. ブラウザToolは依存関係が大きい（約300MB）ため、不要な場合はインストールを省略できます。軽量なWebコンテンツ取得には `web_fetch` Toolをご利用ください。
</Note>
## ワークフロー
Agentがブラウザを使う典型的な流れ：
1. **`navigate`** — 対象URLを開く
2. **`snapshot`** — 簡略化したDOMを取得し、操作可能な要素には自動で番号（`ref`）が付く
3. **`click` / `fill` / `select`** — `ref`で要素を操作する
4. **`snapshot`** — 再度スナップショットを取得して結果を確認
## サポートされる操作
| 操作 | 説明 | 主なパラメータ |
| --- | --- | --- |
| `navigate` | URLを開く | `url` |
| `snapshot` | 構造化されたページテキストを取得（主な利用方法） | `selector`（任意） |
| `click` | 要素をクリック | `ref` または `selector` |
| `fill` | 入力欄にテキストを入力 | `ref` または `selector`、`text` |
| `select` | プルダウンから選択 | `ref` または `selector`、`value` |
| `scroll` | ページをスクロール | `direction`（up/down/left/right） |
| `screenshot` | スクリーンショットをワークスペースに保存 | `full_page` |
| `wait` | 要素または時間を待機 | `selector`、`timeout` |
| `press` | キー入力（Enter、Tabなど） | `key` |
| `back` / `forward` | ブラウザの戻る／進む | - |
| `get_text` | 要素のテキストを取得 | `selector` |
| `evaluate` | JavaScriptを実行 | `script` |
## ユースケース
- 特定のURLにアクセスしてページ内容を取得
- Webページの要素を操作（クリック、入力など）
- デプロイされたWebページの検証
- 指定URLにアクセスして動的コンテンツを取得
- フォーム入力やログイン操作
- Web要素の操作（ボタンクリック、項目選択など）
- デプロイ後のWebページ動作確認
- JSレンダリングが必要な動的コンテンツのスクレイピング
## 動作モード
実行環境に応じてブラウザのモードが自動選択されます：
| 環境 | モード |
| --- | --- |
| macOS / Windows | ヘッドモード（ブラウザウィンドウを表示） |
| Linuxデスクトップ（DISPLAYあり） | ヘッドモード |
| Linuxサーバー（DISPLAYなし） | ヘッドレスモード |
`config.json`で手動上書き可能：
```json
{
"tools": {
"browser": {
"headless": true
}
}
}
```
## ログイン状態の永続化
**対象サイトに一度ログインすれば、Agentは以降そのまま利用できます。** 2つの方法があります：
### 方法1: Persistentモード（デフォルト）
設定不要、すぐに利用可能。ログイン情報は `~/.cow/browser_profile` に保存されます。
毎回クリーンな環境で起動したい場合は、永続化を無効化：
```json
{
"tools": {
"browser": {
"persistent": false
}
}
}
```
### 方法2: CDPモード（既存のChromeに接続）
Playwright付属のChromiumではなく、別途起動した本物のChromeにAgentを接続させることで、完全なブラウザフィンガープリントが得られます。Bot検知が厳しいサイトに有効です。
Chromeをデバッグポートと専用のユーザーデータディレクトリ付きで起動します：
<Tabs>
<Tab title="macOS">
```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.cow/chrome-cdp"
```
</Tab>
<Tab title="Linux">
```bash
google-chrome \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.cow/chrome-cdp"
```
</Tab>
<Tab title="Windows">
```powershell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
--remote-debugging-port=9222 `
--user-data-dir="$env:USERPROFILE\.cow\chrome-cdp"
```
</Tab>
</Tabs>
`config.json` で接続先を指定：
```json
{
"tools": {
"browser": {
"cdp_endpoint": "http://localhost:9222"
}
}
}
```
<Note>
ブラウザToolは依存関係が大きいため、不要な場合はインストールを省略できます。軽量なWebコンテンツ取得には、代わりに `web-fetch` Skillをご利用ください。
Chrome 137以降では `--remote-debugging-port` を専用の `--user-data-dir` と組み合わせる必要があるため、CDPで起動するChromeは**普段使いのChromeのログイン状態をそのまま流用できません**。専用プロファイル内で一度ログインし直す必要があります。
</Note>

67
docs/tools/browser.mdx
View File

@@ -45,7 +45,8 @@ description: 控制浏览器访问和操作网页
</Tabs>
<Note>
支持 Ubuntu 20.04+、Debian 10+、macOS、Windows。Ubuntu 18.04 等旧系统会自动降级安装兼容版本。
1. 支持 Ubuntu 20.04+、Debian 10+、macOS、Windows。Ubuntu 18.04 等旧系统会自动降级安装兼容版本。
2. 浏览器工具依赖较重（约300MB），为可选安装。轻量的网页内容获取可使用 `web_fetch` 工具。
</Note>
## 工作流程
@@ -104,6 +105,68 @@ Agent 使用浏览器的典型流程：
}
```
## 登录态持久化
**只需登录一次目标网站，Agent 后续可直接使用**。提供两种方式：
### 方式一：Persistent 模式（默认）
开箱即用，登录信息保存在 `~/.cow/browser_profile`。无需任何配置。
如需关闭持久化模式，每次都用纯净环境：
```json
{
"tools": {
"browser": {
"persistent": false
}
}
}
```
### 方式二：CDP 模式（接管真实 Chrome）
让 Agent 连接独立启动的真实 Chrome（而非 Playwright 自带的 Chromium），获得完整浏览器指纹，适合反爬严格的网站。
启动 Chrome 时加上调试端口和独立用户目录：
<Tabs>
<Tab title="macOS">
```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.cow/chrome-cdp"
```
</Tab>
<Tab title="Linux">
```bash
google-chrome \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.cow/chrome-cdp"
```
</Tab>
<Tab title="Windows">
```powershell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
--remote-debugging-port=9222 `
--user-data-dir="$env:USERPROFILE\.cow\chrome-cdp"
```
</Tab>
</Tabs>
在 `config.json` 中配置端点：
```json
{
"tools": {
"browser": {
"cdp_endpoint": "http://localhost:9222"
}
}
}
```
<Note>
浏览器工具依赖较重（~300MB），如不需要可不安装。轻量的网页内容获取可使用 `web_fetch` 工具。
Chrome 137+ 限制 `--remote-debugging-port` 必须搭配独立 `--user-data-dir`，因此 CDP 启动的 Chrome **无法直接复用你日常 Chrome 的登录态**，需要在独立目录中重新登录一次。
</Note>