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

> Learn how to set up XiaoHongShu on server versus desktop using Agent Reach. Discover automatic environment detection for seamless integration and optimal performance.

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

---

**Agent Reach automatically selects between OpenCLI for desktop environments and xiaohongshu-mcp for server environments, probing three backend candidates in order and falling back to the legacy xhs-cli if needed.**

Agent Reach provides adaptive XiaoHongShu (Xiaohongshu or XHS) integration that configures the appropriate backend for your specific environment. Whether you are developing on a local workstation with a GUI or deploying to a headless cloud server, the framework handles authentication and session management through environment-specific adapters implemented in the `Panniantong/Agent-Reach` repository.

## How Agent Reach Detects Server vs Desktop Environments

Agent Reach determines your host type through the `_detect_environment()` helper in [`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 virtualization indicators to return either **"server"** or **"local"**.

The probe checks for server signals including:

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

If at least two of these signals appear, the CLI treats the host as a server. This detection drives the selection logic in `XiaoHongShuChannel.check()` within [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 60–90), which probes three backend candidates sequentially and selects the first reporting **"ok"**.

## Desktop Setup: OpenCLI Backend

For **local workstations** with a visible display, Agent Reach uses the OpenCLI backend to reuse your existing Chrome browser session.

### Installation

Run the installer with the XHS channel specified:

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

```

This command 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). The process requires Node.js and automatically runs `npm install -g opencli`.

### Chrome Extension Configuration

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

1. Opening the URL in Chrome and clicking *Add to Chrome*
2. Running the verification command:

```bash
opencli doctor

```

This confirms the Chrome-extension handshake is functioning.

### Cookie Import (Optional)

To import existing XHS credentials for private notes or authenticated actions:

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

```

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

### Validation

Verify the desktop configuration:

```bash
agent-reach doctor

```

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

## Server Setup: xiaohongshu-mcp Backend

For **headless servers**, SSH sessions, or Docker containers, Agent Reach uses the xiaohongshu-mcp service running a headless Chromium instance.

### Installation

Force the server installation path:

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

```

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

### MCP Service Deployment

Download and run 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 container (the binary handles this internally, or run Docker directly):

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

```

The service downloads a ~150 MiB headless Chromium on first startup and exposes an HTTP endpoint at `http://localhost:18060/mcp`.

### Connect Agent Reach to the Service

Configure the MCP endpoint using `mcporter` (installed automatically by the installer, see `_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

```

### Authentication

The first request to the MCP service prints a QR code URL in its logs. Scan this code with the XHS mobile app to authenticate. The service stores authenticated cookies automatically for subsequent requests.

### Manual Cookie Injection (Optional)

If you have an existing Cookie-Editor export, inject it directly:

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

```

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

### Validation

Run the health check:

```bash
agent-reach doctor

```

The output should display “xiaohongshu-mcp 服务运行中” with a note that `mcporter` can invoke `xiaohongshu.search_feeds(...)`.

## Fallback: xhs-cli Backend

If neither OpenCLI nor MCP is available, the installer checks for the legacy `xhs` binary via `_check_xhs_cli()` in [`xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaohongshu.py). While this backend works on both desktop and server, it lacks the zero-config convenience of OpenCLI and the containerized isolation of MCP. Upstream maintenance ceased in 2026, so this remains strictly a backup option.

## Summary

- **Automatic detection** via `_detect_environment()` examines SSH variables, Docker markers, and display availability to choose the appropriate backend.
- **Desktop environments** use OpenCLI to reuse existing Chrome sessions with minimal configuration.
- **Server environments** run the xiaohongshu-mcp Docker service on port 18060 for headless operation.
- **Cookie management** works across both environments through `agent-reach configure xhs-cookies`.
- **Validation**统一通过 `agent-reach doctor` 检查，显示特定后端状态。

## Frequently Asked Questions

### How does Agent Reach determine if I'm on a server versus a desktop?

The framework runs `_detect_environment()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 555–595), which checks for server indicators like `SSH_CONNECTION`, `/.dockerenv`, and missing `DISPLAY` variables. If two or more signals are present, it classifies the host as a server and prioritizes the xiaohongshu-mcp backend over OpenCLI.

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

Yes. Use the `--env` flag explicitly: `agent-reach install --env=local --channels=xiaohongshu` forces the OpenCLI path, while `--env=server` forces the MCP container setup. This overrides the automatic probing logic in `XiaoHongShuChannel.check()`.

### What if the Chrome extension fails to connect on desktop?

Run `opencli doctor` to diagnose the handshake. Ensure you have installed the extension from the URL printed during `agent-reach install`, and verify that Chrome is running with the same user profile that installed the extension. Check [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) for the `opencli_status` implementation if debugging programmatically.

### How do I persist cookies on the server after the initial QR login?

The xiaohongshu-mcp service automatically persists authenticated sessions within its Docker container. If you need to migrate or backup cookies, use `agent-reach configure xhs-cookies` with a JSON export from Cookie-Editor; the helper detects the containerized environment and copies the credentials to the correct path inside the running MCP container.