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

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.

The Three-Tier Backend Priority

The XHS channel defines a strict hierarchy of three backends in 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 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 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 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 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 (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:

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:

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

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

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 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 (lines 2-9), while the generic reordering logic resides in agent_reach/channels/base.py. The ordered_backends() helper processes configuration parameters to adjust priorities without modifying the core channel implementation.

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