# How to Configure a Bilibili Proxy for Mainland China Access Using Agent Reach

> Easily configure a Bilibili proxy with Agent Reach. Learn to set up a proxy via command line, environment variables, or programmatically for seamless access.

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

---

**You can configure a Bilibili proxy in Agent Reach by running `agent-reach configure proxy <url>`, exporting `HTTP_PROXY`/`HTTPS_PROXY` environment variables, or programmatically setting the `proxy` key via the `Config` class.**

Agent Reach is an open-source agent framework that includes native support for routing Bilibili traffic through proxy servers. This configuration is essential for users accessing mainland China networks or bypassing regional restrictions. The implementation stores proxy settings in `~/.agent-reach/config.yaml` and relies on standard environment variables to transparently route HTTP requests.

## CLI Configuration Method

The fastest way to configure a Bilibili proxy is through the built-in CLI command. This approach writes the proxy URL to both the canonical `proxy` key and the legacy `bilibili_proxy` key for backward compatibility.

### Set Proxy via Command Line

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

```

This command executes in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 291-297), where it calls:

- `config.set("proxy", args.proxy)` — the current canonical key
- `config.set("bilibili_proxy", args.proxy)` — legacy alias maintained for compatibility

The dual-key approach ensures older configurations continue functioning while new code migrates to the standardized `proxy` key.

### Export Environment Variables

After saving the proxy, you must export standard environment variables so subprocesses and the underlying `urllib.request` client can detect them:

```bash
export HTTP_PROXY="http://user:pass@proxy.example:8080"
export HTTPS_PROXY="http://user:pass@proxy.example:8080"

```

Agent Reach's HTTP client stack automatically respects these variables. No additional code changes are required for the Bilibili channel to route through the proxy.

## Programmatic Configuration Method

For applications embedding Agent Reach or automation scripts, configure the proxy directly through the Python API.

### Using the Config Class

```python
from agent_reach.config import Config

cfg = Config()  # Loads existing config or creates ~/.agent-reach/config.yaml

proxy_url = "http://user:pass@10.0.0.1:3128"

cfg.set("proxy", proxy_url)          # Canonical key used by current code

cfg.set("bilibili_proxy", proxy_url) # Legacy key maintained for compatibility

```

The `Config.set` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 69-78) performs atomic writes with proper file locking, ensuring safe concurrent access across multiple Agent Reach processes.

## How the Bilibili Channel Uses the Proxy

The Bilibili channel implementation demonstrates why environment variable export is critical. In [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) (lines 24-33), the `_search_api_ok` helper uses standard library `urllib.request.urlopen`:

```python

# Simplified from agent_reach/channels/bilibili.py

import urllib.request

def _search_api_ok(self):
    req = urllib.request.Request("https://api.bilibili.com/x/web-interface/search/type")
    # urllib.request respects HTTP_PROXY/HTTPS_PROXY automatically

    with urllib.request.urlopen(req, timeout=5) as response:
        return response.status == 200

```

Because `urllib.request` checks environment variables before establishing connections, the proxy configuration propagates without explicit code handling. This design keeps the channel implementation clean while supporting complex network topologies.

### Verify Proxy Functionality

Test that the Bilibili channel can reach the API through your proxy:

```python
from agent_reach.channels.bilibili import BilibiliChannel

channel = BilibiliChannel()
status, message = channel.check()
print(f"Status: {status}")   # "ok", "warn", or "error"

print(f"Details: {message}")

```

If the proxy is unreachable, the channel gracefully degrades to alternative backends such as `bili-cli` or `OpenCLI` where available.

## Complete Configuration Example

Here's a reproducible setup for mainland China Bilibili access:

```bash

# 1. Configure proxy in Agent Reach

agent-reach configure proxy http://proxy.internal.company.com:8080

# 2. Export for current shell and subprocesses

export HTTP_PROXY="http://proxy.internal.company.com:8080"
export HTTPS_PROXY="http://proxy.internal.company.com:8080"

# 3. Persist to shell profile (optional)

echo 'export HTTP_PROXY="http://proxy.internal.company.com:8080"' >> ~/.bashrc
echo 'export HTTPS_PROXY="http://proxy.internal.company.com:8080"' >> ~/.bashrc

```

For authenticated corporate proxies:

```bash
agent-reach configure proxy http://username:password@proxy.company.cn:8080
export HTTP_PROXY="http://username:password@proxy.company.cn:8080"
export HTTPS_PROXY="http://username:password@proxy.company.cn:8080"

```

## Key Source Files Reference

Understanding the implementation helps diagnose configuration issues:

| File | Purpose | Relevant Lines |
|------|---------|--------------|
| [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | Parses `configure proxy` command, writes dual keys | Lines 291-297 |
| [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) | Atomic configuration persistence via `Config.set` | Lines 69-78 |
| [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) | HTTP client that respects proxy environment variables | Lines 24-33 |

## Summary

- **Use `agent-reach configure proxy <url>`** for quick CLI-based setup, which writes both `proxy` and `bilibili_proxy` keys
- **Export `HTTP_PROXY` and `HTTPS_PROXY`** — the Bilibili channel's `urllib.request` client requires these environment variables
- **Programmatic setup** uses `Config().set("proxy", url)` from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) for embedded applications
- **Verification** is available via `BilibiliChannel().check()` which returns status and diagnostic messages
- **Graceful fallback** occurs when proxies fail, with automatic switching to `bili-cli` or `OpenCLI` backends

## Frequently Asked Questions

### What's the difference between the `proxy` and `bilibili_proxy` configuration keys?

The `proxy` key is the current canonical setting used throughout Agent Reach, while `bilibili_proxy` is a legacy alias maintained for backward compatibility. The CLI `configure proxy` command writes both keys simultaneously, as seen in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 291-297. You should use `proxy` in new code, but either key will work for Bilibili channel access when properly combined with environment variables.

### Why do I need to export HTTP_PROXY after running `agent-reach configure proxy`?

Agent Reach stores the proxy URL in its configuration file, but the underlying `urllib.request` library used by the Bilibili channel only reads from standard environment variables `HTTP_PROXY` and `HTTPS_PROXY`. The CLI reminds you to export these after configuration. Without this step, the stored proxy URL won't actually route network traffic.

### Does Agent Reach support SOCKS proxies for Bilibili access?

The source code analysis shows `urllib.request` as the HTTP client, which natively supports HTTP and HTTPS proxies through environment variables. For SOCKS proxy support, you would need to ensure your environment has `pysocks` installed and configure `ALL_PROXY` or use a wrapper that converts SOCKS to HTTP proxy locally, as `urllib.request` does not natively implement SOCKS protocol handlers.

### How can I verify my Bilibili proxy configuration is working?

Run `BilibiliChannel().check()` which exercises the `_search_api_ok` helper in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) (lines 24-33). This method attempts a real API call to `api.bilibili.com`. If the proxy is misconfigured, you'll receive an "error" or "warn" status with diagnostic details. The channel will also automatically attempt fallback to `bili-cli` or `OpenCLI` if the proxied connection fails.