# Fallback Order for Xiaohongshu Backends in Agent Reach: Priority and Configuration

> Understand the fallback order for Xiaohongshu backends in Agent Reach: OpenCLI, xiaohongshu-mcp, and xhs-cli. Learn how Agent Reach automatically selects available options.

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

---

**Agent Reach probes Xiaohongshu backends in the fixed sequence OpenCLI → xiaohongshu-mcp → xhs-cli, automatically falling back to the next available option when the preferred backend is unreachable.**

Agent Reach abstracts social media platforms as *channels* that support multiple backend implementations. For the **Xiaohongshu** (小红书) channel, the fallback order for Xiaohongshu backends in Agent Reach is defined in the source code to ensure resilient automation across different runtime environments.

## How the Fallback Order Is Defined

The fallback mechanism relies on a declared list of backends and a base class method that determines probing priority.

### Backend Declaration in xiaohongshu.py

In [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py), the `XiaoHongShuChannel` class declares its supported backends as a class attribute:

```python
class XiaoHongShuChannel(Channel):
    …
    backends = ["OpenCLI", "xiaohongshu-mcp", "xhs-cli (xiaohongshu-cli)"]

```

This ordered list establishes the default fallback hierarchy.

### The ordered_backends() Method

The `Channel` base class in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) implements `ordered_backends()`, which returns the probing sequence. By default, it returns the backends list exactly as declared, but it can also prioritize a user-specified override.

## The Three-Tier Fallback Sequence

When Agent Reach initializes a Xiaohongshu connection, it probes backends in this order:

1. **OpenCLI** – The preferred desktop environment backend that reuses existing Chrome sessions.
2. **xiaohongshu-mcp** – A headless-browser service designed for server-side automation.
3. **xhs-cli (xiaohongshu-cli)** – The legacy upstream CLI tool retained as a final fallback.

If [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) determines that a backend is unavailable (e.g., Chrome is not running for OpenCLI), Agent Reach automatically proceeds to the next backend in the sequence.

## Configuring Backend Priority

Users can override the default fallback order by providing a configuration dictionary. When the key `xiaohongshu_backend` is present, `ordered_backends()` moves that specific backend to the front of the queue.

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

# Default probing order

xhs = XiaoHongShuChannel()
print(xhs.ordered_backends())

# → ['OpenCLI', 'xiaohongshu-mcp', 'xhs-cli (xiaohongshu-cli)']

# Force the MCP backend to be tried first

config = {"xiaohongshu_backend": "xiaohongshu-mcp"}
print(xhs.ordered_backends(config))

# → ['xiaohongshu-mcp', 'OpenCLI', 'xhs-cli (xiaohongshu-cli)']

```

This configuration pattern allows environment-specific optimization without modifying the core channel definition.

## Summary

- **OpenCLI** takes precedence as the default backend for desktop environments.
- The fallback order is defined in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) and processed by `ordered_backends()` in the base channel class.
- Agent Reach automatically skips unavailable backends and proceeds to the next option in the sequence.
- Users can override the priority via the `xiaohongshu_backend` configuration key.
- The contract is verified by [`tests/test_channel_contracts.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channel_contracts.py), ensuring `ordered_backends()` always returns a valid permutation of the declared backends.

## Frequently Asked Questions

### What happens if all Xiaohongshu backends are unavailable?

If none of the three backends respond to the probe check, Agent Reach raises a `BackendUnavailableError` after exhausting the sequence. The error message indicates which backends were attempted and why each failed (e.g., missing Chrome binary, network timeout, or authentication failure).

### Can I disable specific backends from the fallback order?

Currently, the `backends` list in `XiaoHongShuChannel` is static. To exclude a backend, you must subclass the channel or provide a configuration that forces a specific working backend to the front. The `ordered_backends()` method guarantees the requested backend is tried first, effectively bypassing others if it succeeds.

### Where does the backend probing logic reside?

The lightweight availability checks are implemented in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py), which is invoked by the channel's `check()` method. This module performs environment detection (e.g., verifying Chrome processes for OpenCLI or HTTP health checks for xiaohongshu-mcp) without fully initializing the backend.

### Is the fallback order the same across all Agent Reach versions?

As of the current implementation in the Panniantong/Agent-Reach repository, the fallback order for Xiaohongshu backends is hardcoded in the class definition. Future versions may expose this ordering through configuration files, but the current release requires code modification to change the base sequence.