# How to Troubleshoot OpenCLI Browser Extension Setup Issues with Agent Reach

> Troubleshoot OpenCLI browser extension setup issues with Agent Reach. Resolve "OpenCLI not connected" errors by enabling the extension and ensuring your browser stays open.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-08-04

---

**The "OpenCLI not connected" error in Agent Reach almost always means the browser extension is installed but disabled, or the daemon cannot reach the browser—fix it by enabling the extension in `chrome://extensions/` and keeping the browser open while running any `opencli` command.**

Agent Reach uses **OpenCLI** to leverage existing Chrome or Edge sessions for platforms requiring logged-in browser access, including Reddit, Facebook, Instagram, and 小红书. When the OpenCLI browser extension fails to connect, Agent Reach falls back to less reliable methods or fails entirely. This guide walks through the diagnostic flow implemented in the source code—specifically [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) and [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)—to identify and resolve setup issues systematically.

## How Agent Reach Probes the OpenCLI Backend

Understanding the probing mechanism helps you interpret `agent-reach doctor` output accurately. The `opencli_status()` function in [`opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/opencli.py) aggregates multiple health signals:

| Step | Function | What It Checks |
|------|----------|---------------|
| CLI version | `probe_command("opencli", ["--version"], …)` | Confirms `opencli` is installed and executable |
| Daemon status | `_fetch_daemon_status()` | HTTP GET to `http://127.0.0.1:19825/status` for live daemon and `extensionConnected` flag |
| Extension on disk | `_extension_installed_on_disk()` | Scans Chrome/Edge profiles for extension ID `ildkmabpimmkaediidaifkhjpohdnifk` |
| Unpacked source | `_unpacked_extension_files_present()` | Checks for `~/.opencli/extension/manifest.json` |
| Result aggregate | `OpenCLIStatus` dataclass | Combines all signals; `ready` property is **only** true when daemon reports `extensionConnected=True` |

The doctor report uses `opencli_summary(st)` from [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) to convert these technical states into human-readable messages.

## Decoding Common Error Messages

Agent Reach surfaces specific hints via `OpenCLIStatus.hint`. Match your `agent-reach doctor` output to the root cause and fix below:

### "检测到扩展文件但当前未连接"

**Symptom:** Extension files exist but the browser reports no active connection.

**Root cause:** The OpenCLI extension is **disabled**, **not loaded**, or the browser is closed.

**Fix:**
1. Open Chrome/Edge and navigate to `chrome://extensions/` or `edge://extensions/`
2. Locate **OpenCLI** (ID: `ildkmabpimmkaediidaifkhjpohdnifk`)
3. Toggle **Enabled** on
4. Keep the browser window open
5. Run any `opencli` command to wake the daemon: `opencli --version`

### "检测到 unpacked 源文件但尚未确认浏览器已加载"

**Symptom:** Source code present at `~/.opencli/extension` but browser hasn't loaded it.

**Root cause:** Extension files downloaded but never loaded as unpacked extension.

**Fix:**
1. Go to `chrome://extensions/`
2. Enable **Developer mode** (toggle top-right)
3. Click **Load unpacked**
4. Select the `~/.opencli/extension` directory
5. Verify OpenCLI appears in your extensions list

### "未检测到已连接的浏览器扩展"

**Symptom:** No extension connection despite CLI appearing functional.

**Root cause:** Daemon not running, or browser started after daemon.

**Fix:**
1. Ensure browser is open
2. Run `opencli version` to auto-start the daemon
3. Verify: `curl http://127.0.0.1:19825/status` should return `{"ok": true, "extensionConnected": true}`

### "node 环境损坏"

**Symptom:** CLI binary fails execution.

**Root cause:** Corrupted or missing Node.js installation.

**Fix:**

```bash
npm install -g @jackwener/opencli

```

### "等待 Chrome 扩展安装"

**Symptom:** Daemon running but no extension files found.

**Root cause:** Extension never installed from Chrome Web Store or unpacked source.

**Fix:** Install from [Chrome Web Store](https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk) or load unpacked source as described above.

## Step-by-Step Troubleshooting Workflow

Follow this sequence to isolate OpenCLI browser extension setup issues with Agent Reach:

### 1. Run the Health Check

```bash
agent-reach doctor

```

Identify the OpenCLI line—it tells you exactly which condition applies.

### 2. Verify CLI Installation

```bash
opencli --version

```

- **Fails with "command not found":** `npm install -g @jackwener/opencli`
- **Fails with error:** Reinstall same command

### 3. Test Daemon Connectivity

```bash
curl http://127.0.0.1:19825/status

```

Expected response:

```json
{"ok": true, "extensionConnected": true}

```

If connection refused, the daemon is not running.

### 4. Confirm Browser Extension State

- Navigate to `chrome://extensions/` or `edge://extensions/`
- Search for **OpenCLI**
- Status must show **Enabled**

### 5. Handle Unpacked Extension Setup

If you see only source files:

```bash
ls ~/.opencli/extension/manifest.json

```

Load manually via **Load unpacked** in browser extensions page.

### 6. Restart Daemon Cleanly

```bash
pkill -f opencli        # terminate any stale daemon

opencli version         # starts fresh daemon with browser open

```

### 7. Re-verify

```bash
agent-reach doctor

```

Target status: **"OpenCLI 可用（浏览器登录态）"**

## Programmatic Diagnostics

You can reproduce the doctor's logic directly in Python:

```python
from agent_reach.backends.opencli import opencli_status, opencli_summary

st = opencli_status()
print(opencli_summary(st))

# Output: "OpenCLI 已安装，检测到扩展文件但当前未连接（无法确认已加载）"

print(st.hint)  # Actionable next step

```

Full doctor report programmatically:

```python
from agent_reach.doctor import check_all, format_report
from agent_reach.config import Config

cfg = Config()  # loads ~/.agent-reach/config.yaml

results = check_all(cfg)
print(format_report(results))

```

## Channel-Level Fallback Behavior

Each platform channel (e.g., `RedditChannel`, `TwitterChannel`) implements `_check_opencli()` per [`agent_reach/channels/reddit.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/reddit.py). The backend selection priority is:

1. **Verified OpenCLI** — `status == "ok"` AND `extension_connected=True`
2. **OpenCLI installed but not ready** — warn with `OpenCLIStatus.hint`
3. **Alternative CLI tools** — fallback to `twitter-cli`, `rdt-cli`, etc.

If OpenCLI is missing entirely, channels report "off" and suggest installation. This fallback chain means extension setup issues may silently degrade functionality rather than fail outright—making proactive diagnosis essential.

## Summary

- **Run `agent-reach doctor`** first—its output maps directly to specific failure modes in [`opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/opencli.py)
- **The `extensionConnected` flag** from daemon status (`:19825/status`) is the sole truth source for "ready" state
- **Enable the extension in browser** and **keep browser open** resolve most "detected but not connected" cases
- **Load unpacked** from `~/.opencli/extension` if you have source files but no store install
- **Reinstall via npm** only for corrupted Node environments, not connection issues

## Frequently Asked Questions

### How do I know if the OpenCLI daemon is running?

Run `curl http://127.0.0.1:19825/status`. A JSON response with `"ok": true` indicates the daemon is active; `"extensionConnected": true` confirms the browser extension is linked. Connection refused means the daemon has not started—trigger it with any `opencli` command while the browser is open.

### Can I use OpenCLI with browsers other than Chrome or Edge?

According to the source code in [`opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/opencli.py), the extension ID `ildkmabpimmkaediidaifkhjpohdnifk` and profile path scanning target Chromium-based browsers specifically. Firefox and Safari are not supported by the current implementation.

### Why does Agent Reach show OpenCLI as "installed" but not "available"?

The `OpenCLIStatus` dataclass distinguishes `installed` (binary present) from `ready` (daemon + extension connected). "Installed but not available" means your extension files exist on disk but the daemon cannot confirm an active browser connection—typically the extension is disabled or the browser is closed.

### What does the `ildkmabpimmkaediidaifkhjpohdnifk` ID represent?

This is the Chrome Web Store extension ID for OpenCLI. The `_extension_installed_on_disk()` function in [`opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/opencli.py) searches Chrome and Edge profile directories for this specific folder name to detect whether the extension has been installed, regardless of whether it is currently enabled.