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

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

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:

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:

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

2. Register the service with mcporter:

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

3. Verify the service is running:

agent-reach doctor

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

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

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:

pipx install xiaohongshu-cli

# or

uv tool install xiaohongshu-cli

2. Execute the login command:

xhs login

3. Verify status with Agent Reach:

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 (around line 1150) supports copying JSON cookie files directly into the xiaohongshu-mcp container:

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

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, 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.
• Manual cookie import is available through 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 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. The get_login_qrcode function from 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 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.

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