Configuring Residential Proxy for Bilibili When Deployed on a Server

To route Agent-Reach traffic through a residential proxy on a headless server, run agent-reach configure proxy <url> once to persist the setting, then export HTTP_PROXY and HTTPS_PROXY environment variables before each command to ensure the search‑API fallback uses the proxy.

Agent-Reach treats upstream tools as black boxes and does not inject its own networking layer, which means configuring a residential proxy for Bilibili when deployed on a server requires understanding how the tool handles proxy storage versus runtime environment variables. This guide explains the exact mechanism implemented in the Panniantong/Agent-Reach repository, including the specific source files responsible for proxy persistence and the Bilibili channel's dual-backend architecture.

How Agent-Reach Stores Proxy Configuration

The Config class in agent_reach/config.py handles persistent storage by writing values to ~/.agent-reach/config.yaml. When you invoke the configure command, the CLI calls set("proxy", …) and set("bilibili_proxy", …) to synchronize both the modern and legacy keys (lines 40‑46).

agent-reach configure proxy http://user:pass@123.45.67.89:8080

This command writes the following to your config file:

proxy: http://user:pass@123.45.67.89:8080
bilibili_proxy: http://user:pass@123.45.67.89:8080

The CLI handling logic in agent_reach/cli.py (lines 40‑48) parses the --proxy argument and ensures the legacy bilibili_proxy key mirrors the primary proxy value for backward compatibility.

Bilibili Channel Architecture and Proxy Behavior

The BilibiliChannel implementation in agent_reach/channels/bilibili.py operates two distinct modes that affect proxy requirements (lines 36‑40 and 73‑80).

bili-cli Backend (Preferred)

When the bili-cli tool is available, Agent-Reach delegates all network operations to it. According to the source code comments—including the note "Note: B站走 bili-cli，国内网络无需代理。"—this backend does not need a proxy for China-domestic traffic (search, hot lists, video details), as it connects directly to Bilibili servers.

Search-API Fallback

If bili-cli is not installed, the channel falls back to a direct urllib.request call to Bilibili’s public API. This request inherits the process-wide HTTP_PROXY and HTTPS_PROXY environment variables; the CLI does not inject the config file proxy directly into the HTTP request.

Step-by-Step Server Configuration

Follow these steps to ensure your residential proxy is active on a headless server deployment.

1. Persist the Proxy URL

Store the proxy once so Agent-Reach can reference it:

agent-reach configure proxy http://user:pass@host:port

2. Export Environment Variables

Before running any Bilibili command, export the variables so the search-API fallback (and any urllib/curl calls) routes through the proxy:

export HTTP_PROXY="http://user:pass@123.45.67.89:8080"
export HTTPS_PROXY="http://user:pass@123.45.67.89:8080"

agent-reach read https://www.bilibili.com/video/BV1xxxxxx

3. Verify Backend Status

Check which backend is active and whether your environment is correctly configured:

agent-reach doctor

Look for these lines:

• bili-cli available: bilibili ok bili-cli 可用（搜索/热门/排行/视频详情/音频，无需登录） — Proxy is unnecessary.
• Search-API only: bilibili warn B站搜索 API 可达（仅搜索，curl 直连） — You must have HTTP_PROXY exported for the proxy to take effect.

Automated Proxy Wrapper Script

To avoid manually exporting variables, create a wrapper script that reads the saved config and sets the environment automatically:

#!/usr/bin/env bash

# ~/.agent-reach/bin/agent-reach-proxy

CONF=$(agent-reach configure show proxy 2>/dev/null | grep '^proxy:' | awk '{print $2}')
if [[ -n $CONF ]]; then
    export HTTP_PROXY=$CONF
    export HTTPS_PROXY=$CONF
fi
exec agent-reach "$@"

Mark it executable and use it instead of the base command:

chmod +x ~/.agent-reach/bin/agent-reach-proxy
~/.agent-reach/bin/agent-reach-proxy read https://www.bilibili.com/video/BV1xxxxxx

Summary

• Storage: Use agent-reach configure proxy to write the URL to ~/.agent-reach/config.yaml under both proxy and bilibili_proxy keys (handled in agent_reach/config.py and agent_reach/cli.py).
• bili-cli: When this backend is available, traffic goes direct and ignores proxy settings.
• Fallback: The search-API uses urllib.request, which respects HTTP_PROXY and HTTPS_PROXY environment variables.
• Server requirement: You must export these variables before invocation or use a wrapper script to ensure the residential proxy is active.

Frequently Asked Questions

Does the bili-cli backend require a residential proxy?

No. According to the source code in agent_reach/channels/bilibili.py (lines 36‑40), the bili-cli backend connects directly to Bilibili servers for search, trending, and video details, and is explicitly documented as not requiring a proxy for domestic Chinese traffic.

Why must I export HTTP_PROXY if the config file already stores the proxy?

Agent-Reach treats upstream tools as black boxes and does not modify their internal networking. The search-API fallback uses Python’s urllib.request, which only respects process-wide environment variables (HTTP_PROXY/HTTPS_PROXY). The config file stores the value for CLI reference, but the actual network call inherits proxy settings from the shell environment.

How do I verify my proxy is actually being used?

Run agent-reach doctor to check the Bilibili channel status. If it shows bili-cli is available, the proxy is not being used. If it shows the search-API fallback is active, ensure HTTP_PROXY is exported and check your proxy provider’s connection logs for requests to api.bilibili.com.

Can I use a SOCKS5 proxy instead of HTTP/HTTPS?

The fallback uses urllib.request, which supports HTTP_PROXY and HTTPS_PROXY for HTTP/HTTPS proxies. For SOCKS5, you would need to ensure the underlying tools (like curl or bili-cli) support it, or use a tool like proxychains to wrap the Agent-Reach process, as the environment variable standard for urllib does not natively support SOCKS5 without additional libraries.

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