# Configure XiaoHongShu Server vs Desktop in Agent Reach: Complete Setup Guide

> Learn how to configure XiaoHongShu server vs desktop Agent Reach effortlessly. This guide explains automatic CLI selection for optimal performance in any environment.

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

---

**Agent Reach automatically selects OpenCLI for desktop environments and xiaohongshu-mcp for server environments, with fallback to the legacy xhs-cli, based on environment detection logic implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).**

The Panniantong/Agent-Reach repository provides intelligent XiaoHongShu (XHS) automation that adapts to your infrastructure. Whether you're running on a local workstation with a Chrome browser or a headless cloud VM, the platform automatically configures the appropriate backend by probing system environment variables and filesystem markers.

## How Agent Reach Detects Your Environment

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

The detection logic checks for these server signals:

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

If at least two of these clues appear, the CLI treats the host as a server environment and skips OpenCLI initialization in favor of containerized solutions.

## Desktop (Local) Configuration with OpenCLI

For workstations with visible displays, Agent Reach uses the **OpenCLI** backend to reuse your existing Chrome session.

### Installation and Setup

Run the installer with the XHS channel flag:

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

```

The installer invokes `_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). This requires Node.js and executes `npm install -g opencli`.

### Chrome Extension Configuration

After npm installation completes, the CLI outputs the `OPENCLI_EXTENSION_URL`. Complete the setup:

1. Open the URL in Chrome and click *Add to Chrome*
2. Verify the handshake:

```bash
opencli doctor

```

### Cookie Import (Optional)

Import existing XHS cookies using the configuration helper:

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

```

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

### Validation

Confirm the desktop setup:

```bash
agent-reach doctor

```

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

## Server (Headless) Configuration with xiaohongshu-mcp

For SSH sessions, Docker containers, or cloud VMs without displays, Agent Reach configures the **xiaohongshu-mcp** service running on port `18060`.

### MCP Service Installation

Force server mode during installation:

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

```

The installer skips OpenCLI and prints MCP setup guidance (see [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), lines 315-324).

Download and extract 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

```

### Docker Container Setup

Start the headless Chromium service:

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

```

The container downloads approximately 150 MB of headless browser dependencies on first start.

### Connect Agent Reach to MCP

Configure the `mcporter` client (installed automatically by `_install_mcporter()`):

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

```

### Authentication via QR Code

The first API request to the MCP service prints a QR code URL in the container logs. Scan this with the XHS mobile app to establish authenticated sessions. The service persists cookies automatically.

### Manual Cookie Injection (Optional)

If you have existing Cookie-Editor exports, inject them directly:

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

```

The helper detects the Docker container and copies the JSON to the path expected by the MCP service.

## Backend Selection Logic

The `XiaoHongShuChannel.check()` method in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 60-90) implements a priority-based probing system:

1. **OpenCLI** – Probed first on desktop environments; requires Chrome extension handshake
2. **xiaohongshu-mcp** – Probed second; checks for HTTP availability at `localhost:18060/mcp`
3. **xhs-cli** – Fallback legacy binary; maintained for compatibility but no longer updated (upstream support ended in 2026)

The channel reports **"ok"** for the first successful backend and suppresses lower-priority options.

## Summary

- **Automatic detection** relies on `_detect_environment()` analyzing SSH, Docker, and display variables to choose between desktop and server modes
- **Desktop setups** use OpenCLI with Chrome extension reuse, configured via `agent-reach install --env=local`
- **Server setups** require the xiaohongshu-mcp Docker container on port `18060`, configured via `agent-reach install --env=server`
- **Cookie management** works across both environments through `agent-reach configure xhs-cookies`, with automatic container detection for server deployments
- **Validation** uses `agent-reach doctor` to verify backend availability and authentication status

## Frequently Asked Questions

### How does Agent Reach choose between desktop and server mode?

Agent Reach calls `_detect_environment()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 555-595) to analyze environment variables and filesystem markers. If the system shows server indicators like `SSH_CONNECTION`, `/.dockerenv`, or missing `DISPLAY` variables, it automatically routes XiaoHongShu requests to the xiaohongshu-mcp backend instead of OpenCLI.

### Can I force server mode on a desktop machine?

Yes. Pass the `--env=server` flag explicitly to the installer: `agent-reach install --env=server --channels=xiaohongshu`. This bypasses automatic detection and configures the MCP backend even when a display is present, though you must still run the Docker container manually.

### What are the cookie format requirements for XiaoHongShu configuration?

The `_configure_xhs_cookies()` helper accepts two formats: raw HTTP cookie headers (semicolon-separated key-value pairs) or JSON arrays exported from Cookie-Editor containing `name`, `value`, `domain`, and `path` fields. The function stores these in Agent Reach's configuration and injects them into the appropriate backend (OpenCLI session or MCP container).

### Why does the xiaohongshu-mcp service require Docker?

The MCP service bundles a headless Chromium instance to execute XiaoHongShu web automation without a graphical display. Docker provides the necessary isolation for the browser environment and ensures consistent dependency management across different Linux distributions, eliminating the need for local Chrome installations on headless servers.