# How the Agent Reach Doctor Command Verifies Channel Availability

> Discover how the agent reach doctor command verifies channel availability. Learn about its process of checking tools and credentials for a comprehensive health report.

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

---

**The `agent-reach doctor` command verifies channel availability by iterating over all registered channel classes, invoking each channel's `check()` method to probe for required external tools and credentials, and aggregating the results into a human-readable health report.**

The `doctor` sub-command serves as the health-checking engine for Agent Reach, an open-source platform that unifies social media integrations. When you run `agent-reach doctor`, the system validates that every supported channel—from Twitter to YouTube—is correctly installed and configured. This article examines the source code to explain exactly how the doctor command verifies channel availability.

## Channel Discovery Through the Registry

The verification process begins by loading the complete registry of available channels. In [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py), the framework maintains a global list named `ALL_CHANNELS` that contains every platform class. The function `get_all_channels()` exposes this registry to the doctor command.

When `check_all()` is invoked in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), it retrieves the list of channel objects by calling `get_all_channels()`. This design ensures that the doctor command automatically detects new channels as soon as they are added to the `ALL_CHANNELS` registry, without requiring manual updates to the health-check logic.

## The Self-Diagnosis Pattern: Channel Check Methods

Each channel class inherits from `agent_reach.channels.base.Channel`, which defines the interface for health verification. The base class provides a default `check()` implementation that simply returns an `"ok"` status, suitable for built-in channels that require no external dependencies.

Concrete channel implementations override this method to perform platform-specific validation. The `check()` method receives the current configuration object and returns a tuple containing the status (`"ok"`, `"warn"`, `"off"`, or `"error"`) and a descriptive message.

### Twitter Channel Verification Example

In [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py), the `TwitterChannel.check()` method implements a multi-layered verification strategy. First, it uses `shutil.which` to locate the `twitter-cli` binary. If the binary is missing, it returns `("warn", "Twitter CLI 未安装...")`.

If the binary exists, the method executes `twitter status` and parses the output. A successful execution with valid authentication yields `("ok", "...")`. If the binary is present but the user is not authenticated, it returns a distinct warning message indicating the authentication failure.

### Other Platform-Specific Checks

Other channels follow the same pattern but probe for their respective external tools:

- **YouTube**: Verifies the presence of `yt-dlp`
- **Weibo**: Checks for `mcporter`
- **Bilibili**: Validates `bili-cli` installation

Each channel interprets exit codes and output to determine whether the external tool is properly installed and configured.

## Aggregating Health Status in check_all()

The central orchestration logic resides in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py). The `check_all()` function iterates over the channel list returned by `get_all_channels()` and invokes `ch.check(config)` for each instance.

For every channel, it collects:

- The dynamic status and message from the `check()` method
- Static metadata including `name`, `description`, `tier`, and `back-ends`

These results are stored in a dictionary keyed by the channel's `name` attribute, enabling downstream components to access both the health status and platform metadata.

## Rendering the Health Report

After collecting statuses from all channels, [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) calls `format_report()` to transform the raw results into a human-readable display. This function uses the Rich library to generate styled output grouped by tier, with colored symbols indicating status.

The report displays categories such as "装好即用" (ready to use) and "可选渠道" (optional channels), followed by a summary line like "状态：✅ 3/5 个渠道可用" (Status: 3/5 channels available).

## CLI Integration and Command Execution

The `doctor` command is registered in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) as a sub-parser. When invoked, the `_cmd_doctor()` function instantiates a `Config()` object and passes it to `check_all()`. After receiving the results dictionary, it prints the formatted report to the terminal.

This architecture separates the CLI interface from the core verification logic, allowing the health checks to be triggered programmatically or through other interfaces.

## Code Examples

Run the health check from your terminal:

```bash
python -m agent_reach.cli doctor

```

Typical output shows tiered availability:

```

Agent Reach 状态
========================================

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

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

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

```

Use the doctor functionality programmatically in your own scripts:

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

- **Registry-based discovery**: The doctor command loads all channels from `ALL_CHANNELS` in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py), ensuring automatic detection of new platforms.
- **Self-diagnostic pattern**: Each channel implements a `check()` method that probes for required binaries and credentials, returning standardized status codes.
- **Concrete implementations**: Channels like Twitter verify specific CLI tools (`twitter-cli`) and authentication states, while others check for `yt-dlp`, `mcporter`, or `bili-cli`.
- **Centralized aggregation**: The `check_all()` function in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) coordinates the verification workflow and compiles metadata.
- **Rich formatting**: The `format_report()` function generates color-coded, tier-grouped output showing exactly which channels are available and what is missing.

## Frequently Asked Questions

### How do I run the doctor command to check channel availability?

Execute `python -m agent_reach.cli doctor` from your terminal. The command automatically scans all registered channels in `ALL_CHANNELS` and displays a formatted report showing which platforms are ready to use and which require installation or configuration.

### Can I use the doctor functionality programmatically without the CLI?

Yes. Import `check_all` and `format_report` from `agent_reach.doctor`, instantiate a `Config` object from `agent_reach.config`, and call `check_all(cfg)` to receive a dictionary of results. Pass this dictionary to `format_report()` to generate the same text output shown in the CLI, or inspect the results dictionary directly for automated health monitoring.

### What statuses can the doctor command return for each channel?

The `check()` method returns one of four statuses: `"ok"` (fully operational), `"warn"` (installed but misconfigured or unauthenticated), `"off"` (not installed), or `"error"` (unexpected failure). These statuses determine the color coding and messaging in the final report generated by `format_report()`.

### How does adding a new channel affect the doctor command?

When you add a new channel class to `agent_reach/channels/` and register it in `ALL_CHANNELS` within [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py), the doctor command automatically includes it in health checks. You only need to implement the `check()` method in your channel class to define how the system verifies that platform's availability via [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py).