# Configuring Residential Proxy for Bilibili When Deployed on a Server

> Learn how to configure a residential proxy for Bilibili on your server using Agent-Reach. Ensure successful API fallback by setting environment variables for traffic routing.

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

---

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

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

```

This command writes the following to your config file:

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

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

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

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

```bash
#!/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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.