# How to Set Up XiaoHongshu on Desktop vs Server for Agent-Reach

> Learn how to set up XiaoHongshu on desktop vs server for Agent-Reach. Discover automatic environment detection for OpenCLI and xiaohongshu-mcp.

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

---

**Agent-Reach automatically selects the optimal XiaoHongshu backend—OpenCLI for desktop environments that reuse your Chrome session, or xiaohongshu-mcp for headless servers running a Dockerized Chromium instance—based on environment detection heuristics in `_detect_environment()`.**

Agent-Reach provides adaptive XiaoHongshu (XHS) integration that automatically configures the appropriate backend for your environment, whether you are running on a local workstation or a headless server. The framework intelligently probes system signals to determine which driver to activate, switching between three possible implementations defined in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py). This guide covers the complete configuration process for both scenarios using the actual implementation in the Panniantong/Agent-Reach repository.

## How Agent-Reach Detects Desktop vs Server Environments

The detection logic resides in `_detect_environment()` inside [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 555-595). This function examines environment variables, filesystem markers, and `systemd-detect-virt` to classify the host as **"local"** or **"server"**.

Typical server signals include:

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

If at least two of these clues appear, the CLI treats the host as a server.

The channel selection happens in `XiaoHongShuChannel.check()` in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 60-90), which probes three backends in order: OpenCLI, xiaohongshu-mcp, then xhs-cli, picking the first that reports "ok".

## Desktop Setup: Using OpenCLI for Local Workstations

For desktop or local workstations with a visible display, Agent-Reach uses the **OpenCLI** backend to reuse your existing Chrome session. This requires no additional virtualization or containerization.

### Installation Steps

Run the installer with the XHS channel:

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

```

This triggers `_install_xhs_deps()` → `_install_opencli_deps()` (see [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 302-332).

Ensure Node.js is present, then the script runs `npm install -g opencli`. After installation, the CLI prints the Chrome extension URL (`OPENCLI_EXTENSION_URL`). Open that URL in Chrome, click *Add to Chrome*, then verify the handshake:

```bash
opencli doctor

```

Import cookies if you need access to private notes or authenticated content:

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

```

The helper `_configure_xhs_cookies()` (see [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 552-618) parses the header or a Cookie-Editor JSON export and stores it for the OpenCLI backend.

Validate the configuration:

```bash
agent-reach doctor

```

You should see a line like **"OpenCLI 可用（复用浏览器登录态）"** under the XiaoHongshu section.

## Server Setup: Deploying xiaohongshu-mcp for Headless Environments

For servers, SSH sessions, Docker containers, or cloud VMs without a display, Agent-Reach uses the **xiaohongshu-mcp** service. This backend starts a self-contained headless Chromium instance that the agent communicates with over HTTP.

### Installation Steps

Run the installer with the server flag:

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

```

Since `--env=server` forces the server path, `_install_xhs_deps()` skips OpenCLI and prints a guide for the MCP service (see [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 315-324).

Download the MCP 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

```

Start the Docker container:

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

```

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

Connect Agent-Reach to the service using `mcporter` (installed automatically by `_install_mcporter()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)):

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

```

Authenticate via QR code—the first request to the MCP service prints a QR code URL in its logs. Scan it with the XHS app to store authenticated cookies.

Optionally inject cookies manually if you have a Cookie-Editor export:

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

```

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

Validate the setup:

```bash
agent-reach doctor

```

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

## Fallback: Legacy xhs-cli

If neither OpenCLI nor xiaohongshu-mcp is available, the system falls back to the legacy `xhs` CLI. The `_check_xhs_cli()` method in [`xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaohongshu.py) checks for this binary. While functional on both desktop and server, it requires manual `xhs login` configuration and lacks the zero-config benefits of OpenCLI or the headless capabilities of MCP. Note that upstream maintenance stopped in 2026.

## Summary

- **Environment Detection**: The `_detect_environment()` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) automatically classifies hosts as "local" or "server" based on SSH variables, Docker markers, and display availability.
- **Desktop Workflow**: Uses OpenCLI to reuse existing Chrome sessions via `npm install -g opencli` and a browser extension, configured through `_install_opencli_deps()`.
- **Server Workflow**: Deploys the xiaohongshu-mcp Docker container on port 18060, managed via `mcporter` to provide headless Chromium automation.
- **Cookie Management**: Both backends support cookie injection via `agent-reach configure xhs-cookies`, with automatic Docker container detection for server deployments.
- **Validation**: Use `agent-reach doctor` to verify backend status, checking for "OpenCLI 可用" (desktop) or "xiaohongshu-mcp 服务运行中" (server).

## Frequently Asked Questions

### How does Agent-Reach determine whether to use OpenCLI or xiaohongshu-mcp?

The framework probes three backends in sequence within `XiaoHongShuChannel.check()` in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 60-90). It first attempts OpenCLI, which requires a visible display and the Chrome extension. If that fails, it checks for the xiaohongshu-mcp HTTP service on `localhost:18060`. The environment classification is performed by `_detect_environment()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), which looks for server indicators like `SSH_CONNECTION`, `/.dockerenv`, or missing `DISPLAY` variables.

### Can I manually force a specific backend instead of auto-detection?

Yes. Pass the `--env=local` flag to force the OpenCLI desktop path, or `--env=server` to skip OpenCLI and configure for MCP. These flags directly influence the `_install_xhs_deps()` logic in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), bypassing the automatic environment detection heuristics.

### What if the xiaohongshu-mcp Docker container fails to start on my server?

Ensure Docker is installed and port 18060 is not already in use. The container downloads a ~150 MiB headless Chromium on first start, so verify you have sufficient disk space and internet connectivity. If issues persist, you can inject cookies manually using `agent-reach configure xhs-cookies` with a Cookie-Editor JSON export, which the helper will copy into the container if it detects a running Docker instance.

### Is the legacy xhs-cli backend still maintained for Agent-Reach?

No. According to the source code comments in [`xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaohongshu.py), the upstream `xhs` CLI stopped updating in 2026, and it is retained only as a fallback. The `xhs-cli` backend is checked last in `XiaoHongShuChannel.check()` and should only be used if OpenCLI and xiaohongshu-mcp are unavailable. New deployments should use OpenCLI for desktops or xiaohongshu-mcp for servers.