# Troubleshooting OpenCLI Browser Extension Connection Issues: A Complete Guide

> Resolve OpenCLI browser extension connection issues with this complete guide. Learn to troubleshoot Node.js CLI, background daemon, and service worker status for seamless operation. Analyze probes and fix failures quickly.

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

---

**OpenCLI connection failures stem from three distinct points of failure: the Node.js CLI binary (`@jackwener/opencli`), the background daemon process, or the Chrome extension's service worker status, all of which can be diagnosed via the `opencli_status()` probe in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py).**

Agent-Reach relies on the **OpenCLI** backend to allow AI agents to reuse your existing Chrome session for authenticated web actions. When **troubleshooting OpenCLI browser extension connection issues**, you are essentially debugging a chain of three dependent components. The backend probes each element without side effects and returns an `OpenCLIStatus` dataclass that pinpoints the exact failure point.

## Understanding the OpenCLI Architecture

OpenCLI consists of three distinct layers that must all be healthy for the channel to function. According to the source code in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py), the system is designed to fail gracefully by identifying which specific layer is broken.

- **`opencli` command** (Node.js package `@jackwener/opencli`): Provides the CLI entry point. If the binary is missing or the Node environment is corrupted, the CLI cannot run. Typical failure: *"opencli 未安装"* or *"OpenCLI 无法执行（node 环境损坏）"*.

- **OpenCLI daemon**: A local process that mediates between the CLI and the Chrome extension. If this daemon is not running, the CLI cannot reach the browser. Typical failure: *"daemon: not running"*.

- **Chrome extension** (`ildkmabpimmkaediidaifkhjpohdnifk`): Holds the actual Chrome profile credentials. The extension may be installed but asleep (service worker stopped) or not installed at all. Typical failures: *"Extension: disconnected"* or *"Extension: 未安装"*.

## Diagnostic Symptoms and Root Causes

The `opencli_status()` function in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) maps specific symptoms to their root causes using non-destructive probes. Here is how the code interprets common failure states:

- **"OpenCLI 未安装"**: The `probe_command()` function detects a missing executable when `opencli` is not found in `PATH`, setting `installed=False` in the status object.

- **"OpenCLI 无法执行（node 环境损坏）"**: The binary exists but crashes on `opencli --version` with a non-zero exit code. The `probe_command` sets `broken=True` and suggests reinstalling via `npm install -g @jackwener/opencli`.

- **"Extension: disconnected"**: The daemon reports `extension_connected=False`. If `_extension_installed_on_disk()` finds the extension folder in Chrome's profile directory, the summary reports *"可用（扩展睡眠中…）"* indicating the service worker is sleeping.

- **"Extension: 未安装"**: The `_extension_installed_on_disk()` function walks known profile roots (`~/Library/...`, `~/.config/...`, Windows `%LOCALAPPDATA%...`) and returns `False` when the extension ID `ildkmabpimmkaediidaifkhjpohdnifk` is absent.

- **"daemon 未运行"**: The `daemon_probe` parses `Daemon: not running`, setting `daemon_running=False`. The summary notes that the daemon auto-starts on the first real command.

## Step-by-Step Resolution Guide

Follow these steps in order to resolve **OpenCLI browser extension connection issues**:

1. **Verify the `opencli` binary**

   Run the version check to ensure the Node.js package is installed and functional:

   ```bash
   opencli --version
   ```

   If you see "command not found" or a Node.js error, reinstall the package:

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

2. **Check the daemon status**

   Query the daemon without triggering auto-start:

   ```bash
   opencli daemon status
   ```

   If it reports "not running", the daemon will start automatically when you execute any OpenCLI command (e.g., `opencli doctor`).

3. **Confirm the Chrome extension is present**

   Verify the extension exists on disk by checking your Chrome profile directories:

   - **macOS/Linux**: `~/.config/google-chrome/*/Extensions/ildkmabpimmkaediidaifkhjpohdnifk`
   - **Windows**: `%LOCALAPPDATA%\Google\Chrome\User Data\*\Extensions\ildkmabpimmkaediidaifkhjpohdnifk`

   If the folder is missing, install the extension from the Chrome Web Store: `https://chrome.google.com/webstore/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk`.

4. **Wake a sleeping extension**

   If the extension is installed but disconnected, the service worker is likely asleep. Run any OpenCLI command to wake it:

   ```bash
   opencli doctor
   ```

   After this call, `opencli_status` will report *"可用（扩展睡眠中，调用时自动唤醒）"*.

5. **Run the Agent-Reach health check**

   Use the built-in doctor command to verify the full chain:

   ```bash
   python -m agent_reach.cli doctor
   ```

   Look for the confirmation line: `✅ OpenCLI 可用（浏览器登录态，v1.8.3）`.

6. **Final validation**

   Ensure Chrome is actually running, as the extension cannot wake if the browser is closed. Re-run `opencli doctor` after installing the extension to verify connectivity.

## Automated Diagnostics via Python API

For programmatic **troubleshooting OpenCLI browser extension connection issues**, use the Python API defined in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py).

**Check OpenCLI status from Python:**

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

st = opencli_status()
print(opencli_summary(st))  # Human-readable one-liner

print(st)                   # Full OpenCLIStatus dataclass for debugging

```

**Integrate checks into a channel class:**

```python
from agent_reach.backends import opencli_status

class TwitterChannel(BaseChannel):
    # ...

    def _check_opencli(self):
        st = opencli_status()
        if st.ready:
            return "ok", f"OpenCLI 可用（复用浏览器登录态）"
        return None  # Fallback to API key path

```

**Reinstall via the Agent-Reach CLI:**

```bash
agent-reach install --channels opencli  # Triggers _install_opencli_deps()

```

## Key Source Files for Debugging

When **troubleshooting OpenCLI browser extension connection issues**, consult these specific files in the Panniantong/Agent-Reach repository:

- **[`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py)**: Contains `opencli_status()`, `opencli_summary()`, and `_extension_installed_on_disk()` for core probing logic.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: Installer hook that calls `opencli_status` and prints the summary (around line 746).
- **[`agent_reach/channels/_opencli_site.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/_opencli_site.py)**: Base class for sites requiring OpenCLI (Facebook, Instagram, etc.).
- **[`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py)**: Example implementation showing per-platform usage of `_check_opencli`.
- **[`tests/test_opencli_backend.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_opencli_backend.py)**: Test suite validating all status branches and hint messages.

## Summary

- **OpenCLI browser extension connection issues** originate from three potential failure points: the Node.js CLI binary, the background daemon, or the Chrome extension's service worker.
- Use `opencli --version` and `opencli daemon status` to verify the CLI and daemon layers.
- Check disk paths for extension ID `ildkmabpimmkaediidaifkhjpohdnifk` to confirm installation, and run `opencli doctor` to wake sleeping service workers.
- The `opencli_status()` function in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) provides non-destructive probing that distinguishes between missing binaries, broken Node environments, stopped daemons, and sleeping extensions.
- Run `python -m agent_reach.cli doctor` for a comprehensive health check that validates the entire chain.

## Frequently Asked Questions

### Why does the extension show as "disconnected" even though it is installed?

The Chrome extension's service worker may be sleeping due to inactivity. According to the implementation in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py), when `_extension_installed_on_disk()` finds the extension files but `extension_connected` is `False`, the status reports *"可用（扩展睡眠中…）"*. Running any `opencli` command (such as `opencli doctor`) will wake the service worker and establish the connection.

### How do I completely reinstall OpenCLI if the Node environment is corrupted?

First, uninstall the existing package with `npm uninstall -g @jackwener/opencli`, then reinstall globally using `npm install -g @jackwener/opencli`. You can also trigger the Agent-Reach installer specifically for OpenCLI dependencies using `agent-reach install --channels opencli`, which executes the `_install_opencli_deps()` routine defined in the CLI module.

### Where does the code look for the Chrome extension on disk?

The `_extension_installed_on_disk()` function searches standard Chrome profile directories across operating systems. On macOS and Linux, it checks `~/.config/google-chrome/*/Extensions/ildkmabpimmkaediidaifkhjpohdnifk`. On Windows, it checks `%LOCALAPPDATA%\Google\Chrome\User Data\*\Extensions\ildkmabpimmkaediidaifkhjpohdnifk`. If this directory is missing, the summary reports *"Extension: 未安装"* and provides the Chrome Web Store link.

### Will the daemon start automatically, or do I need to run it manually?

The daemon auto-starts when you execute any OpenCLI command that requires browser interaction. The `daemon_probe` logic in `opencli_status()` specifically uses the `status` subcommand (which does not auto-start) to check health, but notes that the daemon will launch on the first real command. You do not need to manually start it unless you are running in a restricted environment.