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

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

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

This command executes in 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:

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

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 (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 (lines 24-33), the _search_api_ok helper uses standard library urllib.request.urlopen:

# 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:

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:

# 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:

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	Parses configure proxy command, writes dual keys	Lines 291-297
agent_reach/config.py	Atomic configuration persistence via Config.set	Lines 69-78
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 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 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 (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.

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