# How the Agent-Reach `doctor` Command Verifies and Reports Channel Availability

> Discover how the Agent-Reach doctor command verifies and reports channel availability with its tiered, color-coded status updates. Understand channel readiness instantly.

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

---

**The `doctor` command iterates through all registered channels, executes each channel's `check()` method to determine availability status, and compiles a tiered, color-coded report showing which channels are ready, need configuration, or are offline.**

The `doctor` command serves as the health-checking subsystem for the Panniantong/Agent-Reach repository, providing users with immediate visibility into which communication channels are operational. By systematically verifying and reporting channel availability, this diagnostic tool ensures that agents can successfully interact with external platforms like Twitter, Bilibili, and WeChat.

## Channel Health Discovery and Verification

The core verification logic resides in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), where the `check_all()` function orchestrates the health-checking process across all registered channels.

### The `check_all` Function Implementation

At lines 12-35 of [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), the `check_all` function collects per-channel status information:

```python
def check_all(config: Config) -> Dict[str, dict]:
    """Check all channels and return status dict."""
    results = {}
    for ch in get_all_channels():
        try:
            status, message = ch.check(config)          # ← each channel implements its own check()

            active = getattr(ch, "active_backend", None) # ← which backend (if any) is currently active

        except Exception as e:                           # ← a busted channel never crashes the doctor

            status, message, active = "error", f"体检异常：{e}", None
        results[ch.name] = {
            "status": status,
            "name": ch.description,
            "message": message,
            "tier": ch.tier,
            "backends": ch.backends,
            "active_backend": active,
        }
    return results

```

### Individual Channel Check Methods

Each channel implements its own availability logic through the `check(config)` method defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). This method returns a tuple `(status, message)` where status is one of four string values:

- `"ok"` – The channel is fully functional and ready for use
- `"warn"` – The channel is installed but requires additional configuration or login
- `"off"` – The channel is not installed on the system
- `"error"` – The check encountered an exception during execution

Channel discovery begins with `get_all_channels()` in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py), which returns singleton instances of all available channel objects.

### Error Handling and Robustness

The verification process employs defensive programming to ensure that a single malfunctioning channel cannot crash the entire diagnostic report. When a channel's `check()` method raises an exception, the `doctor` command catches the error and assigns a status of `"error"` with the exception message, allowing the remaining channels to complete their verification.

## Rendering the Channel Availability Report

After collecting health data, the `format_report()` function (lines 47-99 in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)) transforms the raw status dictionary into a human-readable, Rich-formatted string.

### Tier-Based Organization

Channels are classified by their `tier` attribute (values 0-2), indicating the level of user configuration required:

- **Tier 0**: Ready-to-use channels requiring no setup
- **Tier 1**: Optional channels that are installed but may need login
- **Tier 2**: Advanced channels requiring complex configuration

### Status Icons and Visual Indicators

The report uses intuitive visual markers to convey availability at a glance:

- **✅ Green checkmark**: Channel is available and operational
- **[!] Yellow warning**: Channel is installed but requires configuration or login
- **[X] Red X**: Channel is not installed or encountered an error

For channels supporting multiple backends (such as different API implementations), the report displays the `active_backend` attribute in a dimmed note, showing which specific backend is currently selected.

### Security Validation

Beyond channel availability, the `doctor` command includes a security check (lines 100-127) that verifies [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) file permissions on Unix systems. If the configuration file has overly permissive access rights, the report appends a warning to alert users of potential security risks.

## CLI Integration and Execution

The command-line interface wires the health-checking functionality through [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). When users execute:

```bash
python -m agent_reach.cli doctor

```

The CLI performs the following sequence:

1. Parses the `doctor` sub-command
2. Loads the user configuration via `Config.load()`
3. Invokes `check_all(config)` to gather per-channel health data
4. Passes results to `format_report()` to generate Rich-styled output
5. Prints the formatted report to the terminal

Typical output displays the channel name alongside its status icon, active backend (if applicable), and a summary line indicating the ratio of healthy channels (`ok_count/total`).

## Summary

- The `doctor` command verifies channel availability by calling individual `check()` methods on each registered channel in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)
- Status classification uses four distinct states: `"ok"`, `"warn"`, `"off"`, and `"error"` to represent different availability levels
- Robust error handling ensures that exceptions in one channel do not abort the entire health-checking process
- The report organizes channels by tier (0-2) and uses visual icons (✅, !, X) for immediate status recognition
- Security checks validate [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) permissions to prevent configuration file exposure
- The CLI entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) orchestrates configuration loading, health checking, and report rendering

## Frequently Asked Questions

### What does the `doctor` command check in Agent-Reach?

The `doctor` command checks the availability and health status of all registered communication channels in the Agent-Reach framework. It verifies whether each channel (such as Twitter, WeChat, or Bilibili) is properly installed, configured, and able to connect to its respective platform, returning a comprehensive report of which channels are ready for use.

### How does the `doctor` command handle channels that fail their health check?

If a channel raises an exception during its `check()` method, the `doctor` command catches the error in `check_all()` and records the status as `"error"` with the exception message. This defensive approach ensures that one malfunctioning channel cannot crash the entire diagnostic process, allowing users to see the status of all other channels regardless of individual failures.

### What do the different status icons in the `doctor` report mean?

The report uses three primary visual indicators: a green ✅ indicates the channel is fully operational, a yellow [!] signals the channel is installed but requires additional configuration or login credentials, and a red [X] means the channel is either not installed or encountered an error during verification. These icons correspond to the internal status values `"ok"`, `"warn"`, and `"off"`/`"error"` respectively.

### Where is the `doctor` command implementation located in the repository?

The core implementation resides in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), specifically the `check_all()` function (lines 12-35) for health verification and `format_report()` (lines 47-99) for output formatting. The CLI integration is handled in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), while individual channel check methods are implemented in their respective files under `agent_reach/channels/`.