# How the Agent-Reach Doctor Command Checks Channel Availability

> Learn how the agent-reach doctor command checks channel availability by running self-diagnostics and presenting results in a human-readable report.

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

---

**The `agent-reach doctor` command checks channel availability by delegating self-diagnostic tests to every registered channel class, aggregating their `(status, message)` results, and rendering them into a human-readable Rich-formatted report.**

The `doctor` sub-command is the health-checking engine of the open-source **Agent Reach** project. Its purpose is to verify that every supported **channel**—a platform integration—is correctly installed and configured by probing external tools. According to the Panniantong/Agent-Reach source code, the entire workflow is orchestrated in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) while individual channel classes in `agent_reach/channels/` supply the platform-specific logic.

## Channel Discovery Through the Global Registry

Before any test runs, the system must know which platforms exist. [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) maintains a global list called `ALL_CHANNELS` that holds every channel class. It exposes the helper `get_all_channels()`, which returns this list so the doctor engine knows exactly which integrations to examine.

## The `check_all()` Orchestration Loop

The central coordinator lives in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py). Its `check_all()` function iterates over the collection returned by `get_all_channels()` and, for each channel object, invokes `ch.check(config)`. This call returns a `(status, message)` pair that is stored alongside static metadata—`name`, `description`, `tier`, and `back-ends`—inside a dictionary keyed by the channel’s `name` attribute.

## Channel-Specific Availability Checks

Every concrete channel inherits from `agent_reach.channels.base.Channel`. The base class supplies a default `check()` implementation that simply reports `"ok"`, which is sufficient for built-in channels that require no external tooling. Real-world channels override this method to probe their dependencies and interpret the results.

### Default Check in the Base `Channel` Class

Inside [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), the abstract `Channel` class defines the interface. When a subclass does not override `check()`, the inherited behavior returns an `"ok"` status. This ensures that pure built-in integrations automatically pass the health screen without extra configuration.

### Example: `TwitterChannel.check()` Probes `twitter-cli`

A representative override appears in [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py). The `TwitterChannel.check()` method uses `shutil.which` to locate the `twitter-cli` binary. If the binary is found, it executes `twitter status` and parses the output; a successful response yields `("ok", …)`. If the binary is absent, it returns `("warn", "Twitter CLI 未安装…")`. When the binary is present but the user is not authenticated, it emits a distinct warning message rather than an error.

### Probes for YouTube, Weibo, and Bilibili

Other channels follow the same pattern. They each look for a specific external binary or library and map the outcome to a status string:

- **YouTube** probes for `yt-dlp`
- **Weibo** probes for `mcporter`
- **Bilibili** probes for `bili-cli`

Depending on whether the tool is missing, misconfigured, present but unauthenticated, or fully ready, the overridden `check()` method returns **`ok`**, **`warn`**, **`off`**, or **`error`**.

## Report Formatting and CLI Output

Once `check_all()` finishes, [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) passes the result dictionary to `format_report()`. This function converts the raw statuses into a Rich-styled terminal report grouped by tier, prefixes colored symbols, and prints a summary line such as:

```text
状态：✅ 3/5 个渠道可用

```

A typical truncated report looks like this:

```text
Agent Reach 状态
========================================

✅ 装好即用：
  ✅ YouTube — 内置
  ✅ GitHub — 内置

可选渠道（已安装）：
  ✅ Twitter — twitter-cli 完整可用（搜索、读推文、时间线、长文/Article、用户查询、Thread）
  ✅ Bilibili — bili-cli 已安装

状态：[green]4/5[/green] 个渠道可用
还有 1 个可选渠道可以解锁（Weibo），告诉你的 Agent「帮我装 Weibo」即可

```

## Programmatic and CLI Usage

The `doctor` command is registered in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) under the sub-parser `"doctor"`. When invoked, `_cmd_doctor()` instantiates `Config()` and calls `check_all()` followed by `format_report()`.

Run the check from your terminal:

```bash
python -m agent_reach.cli doctor

```

You can also trigger the same logic from another Python script:

```python
from agent_reach.doctor import check_all, format_report
from agent_reach.config import Config

cfg = Config()
results = check_all(cfg)            # dict of channel statuses

print(format_report(results))       # pretty text report

```

## Summary

- [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) registers every platform class in `ALL_CHANNELS` and exposes `get_all_channels()`.
- [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) implements `check_all()` to iterate over channels and `format_report()` to render a Rich-styled status report.
- Each channel inherits from `agent_reach.channels.base.Channel` and overrides `check()` to probe its specific external dependencies.
- The CLI entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) wires the `doctor` sub-command directly to `check_all(Config())`.

## Frequently Asked Questions

### What does the `agent-reach doctor` command actually test?

It validates whether each supported platform channel is locally ready for use by checking that required external binaries or libraries are installed and authenticated. It does not test live network connectivity to the platforms themselves; instead, it relies on each channel’s `check()` method to inspect local tooling state.

### How does a channel report that it is unavailable?

A channel’s `check()` method returns a `(status, message)` tuple. The status string can be **`ok`**, **`warn`**, **`off`**, or **`error`**, depending on whether the external tool is missing, misconfigured, disabled, or fully operational.

### Can I run channel health checks programmatically without the CLI?

Yes. Import `check_all` and `format_report` from `agent_reach.doctor`, instantiate a `Config`, and call `check_all(cfg)` to receive a dictionary of results. You can then pass that dictionary to `format_report()` for pretty printing or inspect the raw statuses directly in your own automation.

### Which file should I modify to customize a channel's availability check?

You should override the `check()` method in your concrete channel file—for example, [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) for Twitter. All custom channels must inherit from the `Channel` base class defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) so that `check_all()` can discover and invoke them uniformly.