# How XHS Backend Selection Differs Between Desktop and Server in Agent-Reach

> Discover how Agent-Reach handles XHS backend selection differently for desktop and server environments. Learn about the priority order and automatic session reuse.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-05

---

**Agent-Reach selects XHS (XiaoHongShu) backends in the priority order OpenCLI → xiaohongshu-mcp → xhs-cli, automatically detecting desktop environments with Chrome to reuse browser sessions while falling back to MCP services on headless servers.**

The Agent-Reach repository implements environment-aware probing that determines the optimal XHS backend selection strategy without requiring manual configuration. Whether you are running automation on a local workstation with a graphical browser or deploying to a headless CI/CD pipeline, the system evaluates available services through sequential health checks defined in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py).

## The Three-Tier Backend Priority

The XHS channel defines a strict hierarchy of three backends in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 2-9):

1. **OpenCLI** – Reuses locally-running Chrome sessions and existing login cookies
2. **xiaohongshu-mcp** – HTTP service wrapper for headless environments
3. **xhs-cli** – Legacy command-line interface serving as universal fallback

This ordering remains constant, but the **probe behavior** differs based on environment capabilities. The `ordered_backends(config)` helper in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) processes this list while respecting environment-specific configuration overrides.

## Environment-Specific Selection Logic

### Desktop Environments: OpenCLI Browser Reuse

On desktop systems with a graphical Chrome installation, Agent-Reach prioritizes **OpenCLI** through the `_check_opencli` probe. This backend calls `opencli_status` from [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) to verify whether the OpenCLI service reports *ready*.

When available, OpenCLI becomes the `active_backend` immediately because it can tap into existing browser login states without requiring separate authentication flows. The probe executes external commands via [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) to validate Chrome connectivity.

### Server Environments: MCP Service Priority

In headless server or CI environments where graphical Chrome is unavailable, the probe automatically skips OpenCLI and checks `_mcp_service_reachable` instead. This validates whether the local **xiaohongshu-mcp** HTTP service is running and responding to requests.

If the MCP service returns healthy, it becomes the active backend, accepting calls through the `mcporter` interface (e.g., `mcporter call 'xiaohongshu.search_feeds…'`). The probe utilities in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) handle the subprocess execution to verify service health.

### Universal Fallback: xhs-cli Legacy Support

When neither OpenCLI nor MCP services are detected, the system falls back to `_check_xhs_cli`. This legacy backend serves as the final safety net across all environments, ensuring basic functionality even when modern integration layers are unavailable.

## Implementation and Probing Mechanism

The `check()` method in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 60-68) implements the selection logic by iterating through `ordered_backends(config)`:

- **First "ok" status**: The first backend returning an "ok" status becomes the `active_backend`
- **First "warn" status**: If no backend reports "ok", the first "warn" status is returned to provide actionable guidance
- **"Off" status**: If all backends fail, the system reports "off" with installation instructions

This approach ensures users receive a single, specific recommendation rather than multiple conflicting options.

## Practical Configuration Examples

The following examples demonstrate how the same code behaves differently across environments:

```python
from agent_reach.channels.xiaohongshu import XiaoHongShuChannel

# Desktop usage – OpenCLI preferred when Chrome is available

channel = XiaoHongShuChannel()
status, msg = channel.check()
print(status)   # => "ok" (if OpenCLI is ready)

print(msg)      # => OpenCLI usage instructions with browser reuse

```

On a headless server without Chrome but with MCP running:

```python

# Server usage – Automatically falls back to xiaohongshu-mcp

channel = XiaoHongShuChannel()
status, msg = channel.check()
print(status)   # => "ok"

print(msg)      # => MCP service status and mcporter call examples

```

If both modern backends are unavailable, the system degrades gracefully:

```bash

# Terminal output when all backends are unavailable

xhs-cli  # Last-resort CLI commands available

```

## Summary

- Agent-Reach probes three XHS backends in fixed priority: **OpenCLI → xiaohongshu-mcp → xhs-cli**
- **Desktop environments** with Chrome automatically select OpenCLI to reuse existing browser login states
- **Server environments** bypass OpenCLI and prioritize the xiaohongshu-mcp HTTP service for headless operation
- The `check()` method in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) selects the first backend reporting "ok" status, falling back to "warn" messages if needed
- Legacy **xhs-cli** serves as the universal fallback across all deployment contexts

## Frequently Asked Questions

### What determines which XHS backend Agent-Reach selects first?

The selection depends on environment-specific probing results rather than manual configuration. The system checks `_check_opencli` first on desktops, automatically skipping to `_mcp_service_reachable` on headless servers, as implemented in the `check()` method within [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py).

### Why does OpenCLI fail on server environments?

OpenCLI requires a graphical Chrome browser instance to function, which is typically unavailable in headless CI/CD pipelines or cloud servers. The `opencli_status` function in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) detects this absence and returns a negative status, causing the probe to proceed to the MCP service check.

### How does the fallback to xhs-cli work?

If neither OpenCLI nor the MCP service returns an "ok" status during the iteration in `ordered_backends(config)`, the system evaluates `_check_xhs_cli` as the final option. This legacy backend verification ensures basic XHS functionality remains available even when modern integration layers are not installed or configured.

### Where is the backend ordering configured?

The backend priority list is hardcoded in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 2-9), while the generic reordering logic resides in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). The `ordered_backends()` helper processes configuration parameters to adjust priorities without modifying the core channel implementation.