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

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.

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

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

The installer invokes _install_xhs_deps() → _install_opencli_deps() (see 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:

opencli doctor

Cookie Import (Optional)

Import existing XHS cookies using the configuration helper:

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

The _configure_xhs_cookies() function in 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:

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:

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

The installer skips OpenCLI and prints MCP setup guidance (see agent_reach/cli.py, lines 315-324).

Download and extract the MCP binary:

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:

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

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:

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

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