# How Bili-Backend Routing Works in Agent Reach: bili-cli → OpenCLI → Search API

> Understand Bili-backend routing in Agent Reach: bili-cli, OpenCLI, and Search API fallback system. Discover how Agent Reach optimizes Bilibili requests.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-06-23

---

**Agent Reach routes Bilibili requests through a three-tier fallback system—prioritizing the local `bili-cli` tool, falling back to the OpenCLI browser extension, and finally resorting to the public Bili search API when neither local tool is available.**

The Bili-backend routing in Agent Reach abstracts platform complexity behind the `BilibiliChannel` class in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py). By automatically probing three distinct backends in order of capability, the system ensures AI agents can access Bilibili content without manual configuration, selecting the first healthy option that returns an `"ok"` or `"warn"` status.

## The Three-Tier Backend Architecture

The `BilibiliChannel` declares three backends in its `backends` list, ranked by functionality:

### bili-cli (Preferred)

The **bili-cli** backend leverages the standalone `bilibili-cli` command-line tool. When available, this backend provides the full feature set—including video downloads and metadata extraction—without requiring browser authentication.

### OpenCLI (Browser Bridge)

The **OpenCLI** backend acts as a Chrome-extension bridge capable of fetching subtitles and video data via the logged-in browser session. This option activates when `bili-cli` is missing but the user has the OpenCLI daemon running and extension installed.

### B站搜索 API (Fallback)

The **B站搜索 API** backend provides a lightweight HTTP search endpoint that only supports keyword search. It serves as the final fallback when no local tools are present on the system.

## Routing Logic Implementation

The routing mechanism centers on `BilibiliChannel.check()` (lines 46-76 in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py)), which implements a probe-and-select pattern.

### Backend Ordering with User Overrides

`Channel.ordered_backends()` (defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), lines 45-60) generates the candidate list. By default, the order follows `BilibiliChannel.backends`: `["bili-cli", "OpenCLI", "B站搜索 API"]`.

Users can override this ordering by setting an environment variable or config key named `<channel>_backend` (e.g., `BILIBILI_BACKEND`). When configured, the specified backend moves to the front of the probe sequence.

### The Probe Sequence

The `check()` method iterates over the ordered backends, dispatching to dedicated verification methods for each:

1. **`_check_bili_cli`** (lines 84-91): Invokes `probe_command("bili", ["--version"], ...)` from [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) to verify the binary exists and executes successfully.

2. **`_check_opencli`**: Calls `opencli_status()` (defined in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py), lines 80-100), which returns a status object indicating whether the daemon is running and the extension is connected.

3. **`_check_search_api`**: Executes `_search_api_ok()` (lines 24-31), performing an HTTP GET to the public Bili search endpoint and validating that the JSON response contains `code == 0`.

### Status Resolution and Selection

The probe sequence follows strict selection rules:

- **First viable wins**: The first backend returning `"ok"` or `"warn"` becomes `self.active_backend`.
- **Error tracking**: Backends reporting `"error"` (e.g., a broken `bili` command) collect messages as *broken notes* (lines 62-71) and append them to the final status message.
- **Complete failure**: If all candidates fail, the channel reports `"off"` and provides installation hints (lines 73-80).

## Practical Usage Examples

### Checking Channel Status from CLI

Verify which backend is active and diagnose connectivity issues:

```bash
$ python -m agent_reach.cli check bilibili

# Probes bili-cli first; if missing falls back to OpenCLI; finally tries the API

```

### Overriding the Backend Selection

Force a specific backend regardless of availability:

```bash

# Prioritize OpenCLI over local tools

$ export BILIBILI_BACKEND=OpenCLI
$ python -m agent_reach.cli check bilibili

# Ordered backends become ["OpenCLI", "bili-cli", "B站搜索 API"]

```

### Accessing Content Programmatically

Once the channel has selected an active backend, content reads automatically route through it:

```python
from agent_reach.core import read

# Assuming active_backend = "OpenCLI" after health check

content = read("https://www.bilibili.com/video/BV1xxxxxx")

# Under the hood: invokes opencli bilibili video <url> -f yaml

```

## Summary

- **Three-tier hierarchy**: Agent Reach prefers `bili-cli`, falls back to `OpenCLI`, and finally uses the public search API.
- **Dynamic probing**: The `check()` method in [`bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/bilibili.py) (lines 46-76) probes each backend via specialized methods: `_check_bili_cli`, `_check_opencli`, and `_check_search_api`.
- **User control**: Set `BILIBILI_BACKEND` to force a specific backend, overriding the default priority order defined in `ordered_backends()` ([`base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/base.py) lines 45-60).
- **Graceful degradation**: The system collects error messages from broken backends and only reports `"off"` when absolutely no option is available.

## Frequently Asked Questions

### How does Agent Reach choose which Bili backend to use?

Agent Reach probes backends in the order defined by `ordered_backends()` in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), which defaults to `["bili-cli", "OpenCLI", "B站搜索 API"]`. The first backend returning `"ok"` or `"warn"` from its respective check function becomes the active backend.

### Can I force Agent Reach to use a specific backend?

Yes. Set the environment variable `BILIBILI_BACKEND` (or the corresponding config key) to the preferred backend name. This moves that backend to the front of the probe list, making Agent Reach try it first.

### What happens if all Bili backends fail the health check?

If `bili-cli` is broken, OpenCLI is unreachable, and the search API returns an error code, the `BilibiliChannel` reports status `"off"` and includes diagnostic messages from any backends that returned `"error"` status (collected at lines 62-71 in [`bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/bilibili.py)).

### Why does Agent Reach prefer bili-cli over OpenCLI?

The `bili-cli` tool provides the most complete feature set without requiring a browser session. OpenCLI requires a running Chrome extension and authenticated browser, while the search API is limited to keyword searches only. The ranking ensures the richest data source is used when available.