How to Troubleshoot OpenCLI Browser Extension Setup Issues with Agent Reach

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

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

agent-reach doctor

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

2. Verify CLI Installation

opencli --version

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

3. Test Daemon Connectivity

curl http://127.0.0.1:19825/status

Expected response:

{"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:

ls ~/.opencli/extension/manifest.json

Load manually via Load unpacked in browser extensions page.

6. Restart Daemon Cleanly

pkill -f opencli        # terminate any stale daemon

opencli version         # starts fresh daemon with browser open

7. Re-verify

agent-reach doctor

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

Programmatic Diagnostics

You can reproduce the doctor's logic directly in 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:

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. 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
• 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, 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 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.

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