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

> Learn to configure a residential proxy for Bilibili access on servers using Agent Reach. Route Bilibili downloads via yt-dlp efficiently.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.

```bash
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:

```yaml
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:

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

```

The channel implementation in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) checks this environment variable as a fallback when the config key is absent:

```python
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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) around line 217. This ensures the proxy remains active for future sessions without requiring repeated CLI arguments.