Troubleshooting OpenCLI Browser Extension Connection Issues: A Complete Guide

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.

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, 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 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:

   opencli --version

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

   npm install -g @jackwener/opencli

2. Check the daemon status

   Query the daemon without triggering auto-start:

   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:

   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:

   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.

Check OpenCLI status from 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:

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:

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: Contains opencli_status(), opencli_summary(), and _extension_installed_on_disk() for core probing logic.
• agent_reach/cli.py: Installer hook that calls opencli_status and prints the summary (around line 746).
• agent_reach/channels/_opencli_site.py: Base class for sites requiring OpenCLI (Facebook, Instagram, etc.).
• agent_reach/channels/twitter.py: Example implementation showing per-platform usage of _check_opencli.
• 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}