# How to Set Up XiaoHongShu (Xiaohongshu) on Server vs Desktop Environments with Agent Reach

> Learn how to set up XiaoHongShu on server or desktop with Agent Reach. Discover automatic backend selection for optimal performance on any environment.

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

---

**Agent Reach automatically selects the optimal XiaoHongShu backend—OpenCLI for desktop environments with Chrome, xiaohongshu-mcp for headless servers, or xhs-cli as a fallback—based on environment detection logic in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).**

The Panniantong/Agent-Reach repository provides adaptive XiaoHongShu (Xiaohongshu) integration that automatically configures the appropriate backend for your specific environment. Whether you are running on a local workstation with a GUI or deploying to a headless cloud server, Agent Reach handles the complexity through intelligent environment detection. This guide explains how to set up XiaoHongShu (Xiaohongshu) on server vs desktop environments with Agent Reach using the three available backends.

## How Agent Reach Detects Your Environment

The environment detection logic resides in the `_detect_environment()` helper function within [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 555-595). This function examines system indicators to classify the host as either "server" or "local".

Agent Reach treats the host as a server when at least two of the following conditions are present:

- Presence of `SSH_CONNECTION` or `SSH_CLIENT` environment variables
- Container markers like `/.dockerenv` or `/run/.containerenv`
- Absence of `DISPLAY` or `WAYLAND_DISPLAY` variables
- Cloud-VM identifiers in `/sys/...`

When these signals indicate a desktop environment, the system prioritizes the OpenCLI backend; otherwise, it configures the xiaohongshu-mcp service.

## Desktop Setup with OpenCLI

For desktop environments with a visible display, Agent Reach uses the **OpenCLI** backend to reuse your existing Chrome session. No Docker containers or separate browser instances are required.

### 1. Install the XiaoHongShu Channel

Run the installer with the local environment flag:

```bash
agent-reach install --env=local --channels=xiaohongshu

```

The installer executes `_install_xhs_deps()` which calls `_install_opencli_deps()` (lines 302-332 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) to set up the Node.js dependency and global npm package.

### 2. Install the Chrome Extension

After npm installation completes, the CLI displays the `OPENCLI_EXTENSION_URL`. Open this URL in Chrome, click *Add to Chrome*, then verify the extension handshake:

```bash
opencli doctor

```

### 3. Import Cookies (Optional)

If you need to import existing XHS cookies for private notes or authenticated access, use:

```bash
agent-reach configure xhs-cookies '<cookie header>'

```

The `_configure_xhs_cookies()` function (lines 552-618 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) parses Cookie-Editor JSON exports or header strings and stores them for the OpenCLI backend.

### 4. Validate the Installation

Run the diagnostic command:

```bash
agent-reach doctor

```

Look for the status line indicating **"OpenCLI 可用（复用浏览器登录态）"** under the XiaoHongShu section.

## Server Setup with xiaohongshu-mcp

For server or headless environments, Agent Reach deploys the **xiaohongshu-mcp** service in a Docker container. This backend runs a self-contained headless Chromium instance that the agent controls over HTTP.

### 1. Install with Server Flag

Force the server configuration path:

```bash
agent-reach install --env=server --channels=xiaohongshu

```

The `_install_xhs_deps()` function skips OpenCLI and provides MCP setup guidance (lines 315-324).

### 2. Download and Run the MCP Service

Create the tools directory and download the binary:

```bash
mkdir -p ~/.agent-reach/tools/
cd ~/.agent-reach/tools/
curl -L -o xiaohongshu-mcp.tar.gz https://github.com/xpzouying/xiaohongshu-mcp/releases/latest/download/xiaohongshu-mcp-linux-amd64.tar.gz
tar xzf xiaohongshu-mcp.tar.gz
chmod +x xiaohongshu-mcp

```

Alternatively, run the Docker container directly:

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

```

The service downloads a ~150 MiB headless Chromium image on first start.

### 3. Configure Agent Reach to Connect

Register the MCP endpoint with the `mcporter` tool (installed automatically by `_install_mcporter()`):

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

```

### 4. Authenticate via QR Code

The first request to the MCP service prints a QR code URL in its logs. Scan this code with the XiaoHongShu mobile app to establish an authenticated session. The service stores the resulting cookies automatically.

### 5. Inject Cookies Manually (Optional)

For existing Cookie-Editor exports or manual cookie strings:

```bash
agent-reach configure xhs-cookies '[{"name":"xhsid","value":"...","domain":".xiaohongshu.com"}]'

```

The helper detects Docker and copies the JSON into the running container at the path expected by the MCP service.

### 6. Validate Server Setup

Confirm the service is running:

```bash
agent-reach doctor

```

The output should display **"xiaohongshu-mcp 服务运行中"** with a note that `mcporter` can call `xiaohongshu.search_feeds(...)`.

## Fallback to Legacy xhs-cli

If neither OpenCLI nor MCP is available, `XiaoHongShuChannel.check()` in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 60-90) probes for the legacy `xhs` binary via `_check_xhs_cli()`. While functional on both desktop and server, this backend is no longer maintained (upstream updates ceased in 2026) and lacks the zero-config convenience of OpenCLI or the headless capabilities of MCP.

## Summary

- **Desktop environments**: Use OpenCLI to reuse Chrome sessions; install with `--env=local` and add the Chrome extension.
- **Server environments**: Use xiaohongshu-mcp in Docker; install with `--env=server` and configure `mcporter` to connect to `localhost:18060`.
- **Environment detection**: Automatic via `_detect_environment()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) using SSH vars, container markers, and display checks.
- **Cookie management**: Use `agent-reach configure xhs-cookies` for both backends; the CLI handles path translation for Docker containers.
- **Validation**: Always run `agent-reach doctor` to verify backend status and connectivity.

## Frequently Asked Questions

### How does Agent Reach decide which XiaoHongShu backend to use?

The `XiaoHongShuChannel.check()` method in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) probes three candidates in order: OpenCLI, xiaohongshu-mcp, and xhs-cli. It selects the first reporting "ok" status, with priority given to OpenCLI on desktops and MCP on servers based on `_detect_environment()` results.

### Can I run the XiaoHongShu integration on a cloud VM without a GUI?

Yes. Deploy the xiaohongshu-mcp backend using Docker on your headless server. The service runs on port 18060 and provides a headless Chromium instance that Agent Reach controls via HTTP, eliminating the need for a display or Chrome installation.

### What should I do if OpenCLI fails to connect on my desktop?

Run `opencli doctor` to verify the Chrome extension handshake. Ensure you installed the extension from the URL printed during `agent-reach install`. If issues persist, import cookies using `agent-reach configure xhs-cookies` or switch to the xiaohongshu-mcp backend by running the installer with `--env=server`.

### Is the legacy xhs-cli backend still supported?

The xhs-cli backend remains as a fallback but is no longer maintained. The upstream project stopped updating in 2026. For production use, prefer OpenCLI for desktops or xiaohongshu-mcp for servers.