---
title: "پلاگین opencode-browser-agent"
description: "پلاگین OpenCode برای agent-browser: اتوماسیون policy-first با sessionهای persistent، اتصال CDP، devtools و installerهای چندپلتفورم."
author: "Mohammad-Pouya Ghourchiani"
canonical: "https://ghourchiani.ir/fa/projects/opencode-browser-agent"
image: "https://ghourchiani.ir/og/mark-square.png"
updated: "2026-10-26"
lang: "fa"
generated: "2026-11-02"
---
# پلاگین opencode-browser-agent

> **خلاصه:** پلاگین OpenCode برای agent-browser — اتوماسیون مرورگر policy-first با sessionهای persistent، اتصال CDP، devtools و نصب‌کننده‌های چندپلتفورم.

opencode-browser-agent یک پلاگین OpenCode برای agent-browser است: اتوماسیون مرورگر برای ایجنت‌های AI با sessionهای persistent، ابزار توسعه‌دهنده، نصب‌کننده‌های چندپلتفورم (Windows / دسکتاپ Linux / VPS headless) و یک skill بازنویسی‌شده و policy-first.

## پاسخ مستقیم

به Chrome درحال اجرایت از طریق `--auto-connect` متصل می‌شود (لاگین‌ها و تب‌هایت سرجایشان می‌مانند)، کشتن یا بستن مرورگر را ممنوع می‌کند، و اسکریپت‌های نصب/به‌روزرسانی یک‌دستوری برای Windows PowerShell و Linux/macOS دارد. یک backend اختیاری Obscura یک موتور CDP محلی سبک ارائه می‌دهد؛ Chrome پیش‌فرض می‌ماند.

## چرا وجود دارد

- **از مرورگر واقعی‌ات استفاده می‌کند، نه یک مرورگر دورریختنی.** Chrome درحال اجرا را بازاستفاده کن — لاگین‌ها دست‌نخورده، پروفایل جدید نمی‌سازد.
- **policy-first.** یک skill بازنویسی‌شده نحوهٔ هدایت مرورگر توسط ایجنت را محدود می‌کند (`pkill` ممنوع، تب‌های نامرتبط را ندزدد، پیش‌فرض حریم خصوصی) به‌جای اینکه مدل خودش تصمیم بگیرد.
- **نصب یک‌دستوری همه‌جا.** Windows PowerShell، دسکتاپ Linux و VPS headless، با مسیر به‌روزرسانی یک‌دستوری هم‌تراز.
- **موتور Obscura اختیاری.** فقط opt-in، هرگز خودکار؛ به docs مراجعه کن.

## نصب

**پیش‌نیازها:** OpenCode ≥ 2.0.0، agent-browser CLI (`npm i -g agent-browser`)، Chromium (`agent-browser install`؛ روی Linux با `--with-deps`).

**از npm (ساده‌ترین):**

```json
{ "plugins": ["opencode-browser-agent"] }
```

**از build محلی (Windows PowerShell):**

```powershell
powershell -ExecutionPolicy Bypass -File .\install.ps1        # نصب اولیه
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Update  # به‌روزرسانی
```

**از build محلی (Linux / macOS):**

```bash
bash install.sh            # نصب اولیه
bash install.sh --update   # به‌روزرسانی
```

**Linux VPS (headless):**

```bash
npm i -g agent-browser
agent-browser install --with-deps
agent-browser doctor
bash install.sh
```

سپس OpenCode را دوباره راه‌اندازی کن — پلاگین‌ها در startup بارگذاری می‌شوند.

## اتصال به Chrome (CDP)

Chrome فقط وقتی با `--remote-debugging-port=9222` راه‌اندازی شده باشد CDP را نمایش می‌دهد؛ آن پورت متعلق به یک پروسهٔ مرورگر است (پس پروفایل را هم مشخص می‌کند).

```bash
agent-browser --auto-connect open <url>            # بازاستفاده از Chrome درحال اجرا
agent-browser --auto-connect false --cdp 9222 open <url>  # اتصال با پورت
```

نکات شناخته‌شده:

- اگر `~/.agent-browser/config.json` مقدار `"autoConnect": true` داشته باشد، هر فراخوانی `--cdp` با خطای "Cannot use --auto-connect and --cdp together" می‌افتد — با `--auto-connect false` جفتش کن.
- Chrome جدید ممکن است به `GET /json/version` با 404/empty پاسخ دهد در حالی که CDP کار می‌کند — هرگز با `/json*` تشخیص نده.
- یک `DevToolsActivePort` قدیمی باعث hang و سپس `os error 10060` می‌شود — بررسی کن پورت واقعاً listen است.
- `chrome://inspect` «Target discovery settings» پورت debugging روی Chrome محلی باز **نمی‌کند**.

تشخیص read-only: `ss -ltnp | grep 9222` (Linux) / `Get-NetTCPConnection -LocalPort 9222` (Windows).

## عیب‌یابی

- **خطای "Browser not launched":** اول `agent-browser doctor`؛ روی Linux/container headless با `agent-browser install --with-deps` و `agent-browser open --args "--no-sandbox" <url>`.
- **console/cookies خالی:** همیشه `--json` بزن (`agent-browser console --json`).
- **cookie banner شناسایی نشد:** `agent-browser snapshot -i` سپس کلیک روی `@ref` متناظر.
- **session از دست رفت:** `agent-browser close` را اجرا نکن (cookieها پاک می‌شوند)؛ به URLهای جدید برو یا `--auto-connect` استفاده کن.
- **element پیدا نشد:** پس از ناوبری دوباره `snapshot -i` بزن برای `@ref`های تازه.

## محدودیت‌ها

- اتصال CDP نیازمند Chrome راه‌اندازی‌شده با `--remote-debugging-port` است؛ `--auto-connect` فقط تأیید می‌کند *یک* Chrome پاسخ داده، نه اینکه کدام پروفایل/حساب. پیش از اقدام وابسته به حساب، هویت (پورت، PID، تب‌ها، حساب قابل‌مشاهده) را بررسی کن.
- VPS headless Chrome GUI ندارد؛ `--auto-connect` آنجا بی‌فایده است — مرورگر تازه راه‌اندازی کن.
- ورود بدون دسکتاپ: export cookieها / بازیابی `auth.json` / استفاده از `--session-name`.
- مشتق‌شده از `opencode-agent-browser` (MIT، Nicola Crotti)؛ به NOTICE مراجعه کن.

## لینک‌ها

- بستهٔ npm: https://www.npmjs.com/package/opencode-browser-agent
- مخزن: https://github.com/BTF-Kabir-2020/opencode-browser-agent
- مستندات Obscura: https://github.com/BTF-Kabir-2020/opencode-browser-agent/blob/main/docs/obscura.md