How to Add XiaoHongShu Support to Agent Reach via xhs-cli

Adding XiaoHongShu support to Agent Reach requires installing the external xhs-cli binary, authenticating with xhs login, and optionally supplying cookies directly through the agent-reach configure xhs-cookies command.

Agent Reach, from the Panniantong/Agent-Reach repository, treats XiaoHongShu (小红书) as a unified channel that delegates platform operations to the xhs-cli command-line tool. Integrating this channel follows three distinct phases that unlock read, search, comment, post, like, collect, follow, and user-lookup capabilities.

Install the xhs-cli Binary

Agent Reach relies on the external xiaohongshu-cli package, which provides the xhs executable. In agent_reach/cli.py, the _install_xhs_deps() function checks whether the xhs binary exists. If it is missing, the framework offers an automatic installation via pipx with a uv fallback (source).

You can trigger this installation through the CLI:

# Install xhs-cli using Agent Reach's internal installer

agent-reach install xhs

Behind the scenes, this executes the same dependency resolution logic found in _install_xhs_deps(), ensuring the xhs command is available on your system path before proceeding. The user-facing instructions in docs/install.md also document the standard pipx install xiaohongshu-cli pathway for manual installation (source).

Authenticate the Tool with xhs login

Once the binary is installed, you must authenticate with XiaoHongShu. The XiaoHongShuChannel class defined in agent_reach/channels/xiaohongshu.py expects a valid local session before it forwards any operations (source).

Run the following command to extract the required cookies from your browser automatically:

xhs login

This tool gathers authentication tokens from your default browser or accepts a manual cookie import, storing them locally so that subsequent xhs commands run as an authenticated user. Agent Reach checks this state through the channel's check() routine, which confirms the binary is present and that xhs status returns ok: true.

(Optional) Pass Cookies Directly to Agent Reach

If you prefer to manage cookie data inside Agent Reach rather than relying solely on xhs-cli's local storage, you can export cookies from your browser—using an extension such as Cookie-Editor as either JSON or a header string—and feed them into the framework.

Use the configure command to store these cookies for the channel:

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

This step is optional; the XiaoHongShuChannel will use internally stored cookies when invoking xhs-cli if they are provided.

Verify the Integration

After installation and authentication, confirm that the channel is fully operational:

agent-reach doctor

A successful setup reports ok for XiaoHongShu. Internally, the XiaoHongShuChannel.check() method verifies two conditions: the xhs binary exists on the system path, and a call to xhs status returns a healthy response. If either check fails, the doctor output flags the specific failure so you can re-run xhs login or reinstall the binary.

How XiaoHongShuChannel Handles Operations

The XiaoHongShuChannel class in agent_reach/channels/xiaohongshu.py serves as the bridge between Agent Reach's unified API and the external xhs binary. It declares the channel name, description, and required backend (xhs-cli), and implements three core methods:

• can_handle(url) – Determines whether a given URL belongs to XiaoHongShu.
• check() – Validates that xhs-cli is installed and authenticated.
• Read/search methods – Forward calls to the xhs binary to execute read, search, comment, post, like, collect, follow, and user-lookup operations.

Because Agent Reach delegates all platform-specific logic to xhs-cli, the channel remains lightweight and maintenance is isolated to the external tool.

Summary

• Install xhs-cli: Agent Reach's _install_xhs_deps() in agent_reach/cli.py manages installation via pipx or uv.
• Authenticate: Run xhs login to extract and store browser cookies locally.
• Optional cookie injection: Use agent-reach configure xhs-cookies to pass JSON cookies directly into the framework.
• Verify: Run agent-reach doctor to confirm the XiaoHongShuChannel.check() logic passes.
• Operations: The channel forwards read, search, and social actions to the xhs binary through agent_reach/channels/xiaohongshu.py.

Frequently Asked Questions

What is xhs-cli and why does Agent Reach require it?

xhs-cli is the external command-line tool provided by the xiaohongshu-cli package. Agent Reach treats XiaoHongShu as a backend-driven channel, so it delegates all platform-specific operations—such as reading posts and searching content—to this binary rather than reimplementing the protocol internally.

Can I add XiaoHongShu support without installing xhs-cli separately?

No. The XiaoHongShuChannel explicitly requires the xhs executable. As implemented in Panniantong/Agent-Reach, the check() method in agent_reach/channels/xiaohongshu.py fails if the binary is missing, and the _install_xhs_deps() helper in agent_reach/cli.py exists specifically to provide it.

How does Agent Reach store XiaoHongShu cookies?

By default, xhs-cli stores cookies locally after you run xhs login. Alternatively, you can pass cookie data directly into Agent Reach using agent-reach configure xhs-cookies, which stores the JSON or header string inside the framework's configuration layer for use during xhs invocations.

Which XiaoHongShu actions does Agent Reach support once integrated?

According to the source, the unified channel supports read, search, comment, post, like, collect, follow, and user-lookup capabilities. These are exposed through Agent Reach's common interface and executed by forwarding commands to the xhs binary.

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