# How to Configure Xiaohongshu (Little Red Book) Authentication in Agent Reach: 3 Backend Methods

> Configure Xiaohongshu authentication in Agent Reach using three backend methods: OpenCLI, xiaohongshu-mcp, and xhs-cli. Learn automatic selection and manual overrides for seamless integration.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-13

---

**Agent Reach supports three authentication backends for Xiaohongshu—OpenCLI, xiaohongshu-mcp, and xhs-cli—automatically selecting the first available backend while allowing manual override via the `XIAOHONGSHU_BACKEND` environment variable.**

Agent Reach, the open-source automation framework maintained by Panniantong, provides flexible integration paths for Xiaohongshu (XHS) authentication. Configuring Xiaohongshu authentication in Agent Reach requires understanding the three available backends and how the system prioritizes them based on your environment and existing browser sessions.

## Backend Selection Logic

The channel implementation in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) contains the **backend detection algorithm** within the `XiaoHongShuChannel.check` method (lines 61-71). This logic probes for available backends in a specific order: OpenCLI first, then xiaohongshu-mcp, and finally the legacy xhs-cli. The first functional backend detected becomes the active authentication mechanism for the session.

You can override automatic selection by setting the `XIAOHONGSHU_BACKEND` environment variable or configuring the `xiaohongshu_backend` key in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) to force a specific implementation.

## Authentication Method 1: OpenCLI (Chrome Profile Reuse)

**OpenCLI** is the fastest backend for desktop environments, reusing your existing Chrome user profile that already contains a logged-in Xiaohongshu session. This method requires no additional login flows or QR codes.

1. Install the OpenCLI backend:

```bash
agent-reach install --channels=opencli

```

2. Ensure Chrome is logged into Xiaohongshu by visiting `xiaohongshu.com` and signing in once.

3. Verify the configuration using the diagnostic tool:

```bash
agent-reach doctor

```

A successful configuration displays **"OpenCLI 可用（复用浏览器登录态）"**, indicating the cookie is present and readable from your Chrome profile.

## Authentication Method 2: xiaohongshu-mcp (Docker Container)

The **xiaohongshu-mcp** backend provides a self-contained, headless browser environment running in Docker with a local HTTP service on `http://localhost:18060/mcp`. This method supports QR code authentication and is ideal for server environments without desktop browsers.

1. Pull and start the container:

```bash
docker run -d --name xiaohongshu-mcp -p 18060:18060 xpzouying/xiaohongshu-mcp

```

2. Register the service with mcporter:

```bash
mcporter config add xiaohongshu http://localhost:18060/mcp

```

3. Verify the service is running:

```bash
agent-reach doctor

```

Look for **"xiaohongshu-mcp 服务运行中"** in the output.

4. If the container reports *not authenticated*, trigger QR code generation:

```python
from agent_reach.core import get_login_qrcode

qr = get_login_qrcode()
print("Scan this QR code with your Xiaohongshu app:")
print(qr)

```

Scan the displayed QR code with the Xiaohongshu mobile app; the container automatically stores the resulting session cookies.

## Authentication Method 3: xhs-cli (Legacy)

The **xhs-cli** backend interfaces with the external `xiaohongshu-cli` command-line tool. This legacy method extracts cookies from your default browser or falls back to QR login via the external CLI.

1. Install the CLI tool using pipx or uv:

```bash
pipx install xiaohongshu-cli

# or

uv tool install xiaohongshu-cli

```

2. Execute the login command:

```bash
xhs login

```

3. Verify status with Agent Reach:

```bash
agent-reach doctor

```

The output displays **"xhs-cli 已安装但未登录"** until authentication succeeds, after which it confirms active credentials.

## Manual Cookie Import

For containers or advanced scenarios, Agent Reach provides manual cookie import functionality. The `import_cookies` implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (around line 1150) supports copying JSON cookie files directly into the xiaohongshu-mcp container:

```bash

# Export cookies from Chrome as JSON array to /tmp/xhs_cookies.json

# Then copy into the container

docker cp /tmp/xhs_cookies.json xiaohongshu-mcp:/app/data/cookies.json

```

The cookie extraction patterns for Xiaohongshu target the `".xiaohongshu.com"` domain, defined in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py).

## Summary

- **OpenCLI** offers the fastest setup for desktop users by reusing existing Chrome sessions, checked first by the `XiaoHongShuChannel.check` method.
- **xiaohongshu-mcp** provides containerized authentication with QR code support via `get_login_qrcode()` from [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py), ideal for headless servers.
- **xhs-cli** serves as the fallback legacy option requiring external CLI installation.
- Override backend selection using the `XIAOHONGSHU_BACKEND` environment variable or `xiaohongshu_backend` config key in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- Manual cookie import is available through [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) for Docker container management.

## Frequently Asked Questions

### Which Xiaohongshu backend should I use in Agent Reach?

**Use OpenCLI for desktop environments** where Chrome is already logged in, as it requires no additional authentication steps. **Use xiaohongshu-mcp for servers or isolated environments** where containerization is preferred and you can scan QR codes. Only use xhs-cli if you specifically need the external CLI tool's features or the other backends are unavailable.

### How do I force Agent Reach to use a specific backend?

Set the `XIAOHONGSHU_BACKEND` environment variable to `opencli`, `xiaohongshu-mcp`, or `xhs-cli` before running Agent Reach. Alternatively, modify the `xiaohongshu_backend` value in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) to permanently override the automatic selection logic in `XiaoHongShuChannel.check`.

### Where are Xiaohongshu cookies stored when using the mcp container?

Cookies are stored inside the Docker container at [`/app/data/cookies.json`](https://github.com/Panniantong/Agent-Reach/blob/main//app/data/cookies.json). The `get_login_qrcode` function from [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) handles authentication by generating a QR code that, when scanned, writes the session cookies to this location. You can manually inject cookies using `docker cp` as implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) around line 1150.

### Why does `agent-reach doctor` report no available backends?

This indicates that OpenCLI is not installed, the xiaohongshu-mcp Docker container is not running on port 18060, and xhs-cli is not installed in your PATH. Install at least one backend according to the methods above, verify Docker is running for the mcp option, or check that Chrome contains valid Xiaohongshu session data for the OpenCLI option.