How to Configure a Residential Proxy for Bilibili Access in Agent Reach

Agent Reach routes Bilibili video downloads through yt-dlp and accepts residential proxy credentials via CLI flags, YAML configuration, or environment variables.

Agent Reach is an open-source automation tool that processes video content from platforms including Bilibili. When deploying on servers that face geographic restrictions or IP-based rate limiting, routing traffic through a residential proxy ensures consistent access to Bilibili's content delivery network.

How Proxy Configuration Works

Under the hood, Agent Reach leverages yt-dlp to fetch Bilibili videos. The proxy configuration flows through three core components:

• agent_reach/cli.py – Handles the --proxy flag during installation and stores the value under the bilibili_proxy config key (approximately lines 210–230).
• agent_reach/channels/bilibili.py – Reads the proxy setting from configuration or environment variables at lines 42–51 and passes it to the download engine.
• Configuration system – Centralizes settings in ~/.config/agent_reach/config.yaml with fallback support for environment variables.

When a proxy is active, the Bilibili channel appends "视频读取：yt-dlp（代理已配置）" to its health check status, confirming the configuration is active.

Configuration Methods

Method 1: CLI Flag During Installation

The fastest way to set a residential proxy is passing it directly during the installation phase. The CLI parses the --proxy argument and persists it to your configuration via a config.set call around line 217.

python -m agent_reach.cli install --proxy http://user:pass@proxy-host:port

This command stores the proxy URL under the bilibili_proxy key, making it available for all subsequent Bilibili operations.

Method 2: YAML Configuration File

For persistent, version-controlled deployments, edit the Agent Reach configuration file directly. The default location is ~/.config/agent_reach/config.yaml.

Add the following line:

bilibili_proxy: http://user:pass@proxy-host:port

The Config helper class reads this value at runtime and injects it into the Bilibili channel's yt-dlp invocation. No CLI flags are required when using this method.

Method 3: Environment Variable

For containerized environments or CI/CD pipelines where file modifications are impractical, set the BILIBILI_PROXY environment variable:

export BILIBILI_PROXY=http://user:pass@proxy-host:port
python -m agent_reach.cli doctor

The channel implementation in agent_reach/channels/bilibili.py checks this environment variable as a fallback when the config key is absent:

proxy = (config.get("bilibili_proxy") if config else None) or os.environ.get("BILIBILI_PROXY")

Verifying Proxy Activation

To confirm your residential proxy is active, run the health check command:

python -m agent_reach.cli doctor

If the proxy is correctly configured, the output will display 视频读取：yt-dlp（代理已配置）. Without a proxy, it shows 视频读取：yt-dlp. This status is generated by the logic in agent_reach/channels/bilibili.py lines 42–51, which evaluates both the configuration file and environment variables before reporting the proxy state.

Summary

• Agent Reach uses yt-dlp as the underlying engine for Bilibili video retrieval.
• Three configuration methods are supported: CLI --proxy flag, YAML config file (bilibili_proxy key), and BILIBILI_PROXY environment variable.
• The proxy URL should follow the format http://user:pass@host:port.
• Verify configuration using agent_reach.cli doctor and look for the "代理已配置" status indicator.

Frequently Asked Questions

What authentication format does Agent Reach expect for proxy URLs?

Agent Reach passes the proxy string directly to yt-dlp, which expects standard URL authentication encoding. Use the format http://username:password@proxy-host:port. Ensure special characters in passwords are URL-encoded to prevent parsing errors.

Can I rotate between multiple residential proxies?

The source implementation stores a single proxy string in the bilibili_proxy config key. For rotation, you would need to update this value between runs either by modifying the config file or by rotating the BILIBILI_PROXY environment variable before each Agent Reach invocation.

Why does the health check show the proxy status in Chinese characters?

The status message 视频读取：yt-dlp（代理已配置） is hardcoded in agent_reach/channels/bilibili.py to match Bilibili's Chinese origin. This indicates the yt-dlp backend has successfully loaded your proxy credentials and will route traffic through the specified residential IP.

Where does Agent Reach store the configuration when using the --proxy CLI flag?

When you run python -m agent_reach.cli install --proxy, the value is persisted to ~/.config/agent_reach/config.yaml under the bilibili_proxy key by the CLI handler in agent_reach/cli.py around line 217. This ensures the proxy remains active for future sessions without requiring repeated CLI arguments.

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