# How the Doctor Command Diagnoses Active Platform Backends in Agent Reach

> Discover how the Agent Reach doctor command diagnoses active platform backends. This command performs a health check to identify active, misconfigured, or missing integrations.

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

---

**The `doctor` command performs a comprehensive health check across all platform channels in Agent Reach, aggregating backend statuses to identify which integrations are active, misconfigured, or missing dependencies.**

The `doctor` command serves as the diagnostic engine for the Panniantong/Agent-Reach framework, providing users with actionable insights into their active platform backends. By executing systematic configuration audits across every supported channel—from Twitter to Reddit to YouTube—this utility eliminates guesswork when troubleshooting connectivity issues or credential problems.

## Entry Point and Command Registration

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the CLI registers the `doctor` sub-command at lines 92-96. When users execute `agent-reach doctor`, the handler `_cmd_doctor` (invoked at line 46) triggers the diagnostic sequence and manages output formatting.

## Collecting Channel Health Data

The core diagnostic logic resides in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), specifically within the `check_all` function (lines 12-35). This implementation iterates through all channel classes retrieved by `get_all_channels()` from [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py).

For each channel, the system invokes `ch.check(config)` and implements fault-tolerant error handling that captures exceptions individually. This design ensures that a single malfunctioning channel cannot abort the entire diagnostic report.

Each channel returns a structured dictionary containing:

- **`status`**: Operational state (`ok`, `warn`, `off`, or `error`)
- **`name`**: Human-readable platform identifier
- **`message`**: Detailed diagnostic text
- **`tier`**: Configuration complexity level (0 for zero-config, 1 for free-key/login, 2 for complex setup)
- **`backends`**: Array of available backend options
- **`active_backend`**: Currently selected backend implementation

## Report Formatting and Security Validation

The `format_report` function (lines 46-100 in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)) constructs a Rich-formatted text report that organizes channels by their configuration tier. The output includes emoji legends indicating availability and specifically highlights the active backend when multiple options exist (e.g., OpenCLI versus `rdt-cli` for Reddit).

Additionally, the diagnostic includes a security audit that checks if the user's [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) file is world-readable, warning about potential credential exposure.

## Running the Doctor Command

Execute a plain-text health check to see platform statuses and active backends:

```bash
agent-reach doctor

```

Typical output includes channel status indicators and backend identification:

```

Agent Reach 状态
========================================
图例：✅ 可用  [!]/[X] 未安装

✅ 装好即用：
  ✅ Twitter  （当前后端：twitter-cli）
  [!]/❌ Reddit   （当前后端：rdt-cli）

状态：[green]6/9[/green] 个渠道可用
还有 3 个可选渠道可以解锁（Facebook、Instagram、Bilibili），告诉你的 Agent「帮我装 XXX」即可

```

For machine-readable output suitable for automation pipelines, use the `--json` flag:

```bash
agent-reach doctor --json

```

The JSON output provides structured data for each channel:

```json
{
  "twitter": {
    "status": "ok",
    "name": "Twitter",
    "message": "已登录",
    "tier": 0,
    "backends": ["twitter-cli"],
    "active_backend": "twitter-cli"
  },
  "reddit": {
    "status": "warn",
    "name": "Reddit",
    "message": "需要登录",
    "tier": 1,
    "backends": ["opencli", "rdt-cli"],
    "active_backend": "rdt-cli"
  }
}

```

## Summary

- The `doctor` command aggregates health data from all platform channels via `check_all` in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)
- Diagnostic results include status codes, tier classifications, and active backend identification
- Fault-tolerant execution prevents individual channel failures from corrupting the report
- Rich text formatting provides visual grouping by configuration complexity
- JSON export mode supports the `--json` flag for programmatic consumption
- Security warnings alert users to world-readable configuration files

## Frequently Asked Questions

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

The command validates every platform channel registered in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py), testing API connectivity, credential validity, and dependency availability. It reports whether each backend is operational, requires configuration, or has encountered errors, including the specific `active_backend` currently in use for multi-backend channels.

### How does the doctor command handle failures in individual channels?

According to the source code in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (lines 12-35), the `check_all` function wraps each channel's `check(config)` call in exception handling. This ensures that a timeout or authentication error in one platform (like Twitter) does not prevent the diagnostic from completing for other channels (like Reddit or YouTube).

### What information does the JSON output include?

When invoked with `--json`, the command outputs a structured object where each key represents a platform channel containing: `status` (operational state), `name` (display name), `message` (diagnostic details), `tier` (complexity level), `backends` (available implementations), and `active_backend` (currently selected implementation).

### Where is the doctor command implemented in the codebase?

The command entry point resides in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 92-96), while the diagnostic logic lives in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py). The channel registry used for iteration is defined in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py), with individual channel checks implemented in their respective files (e.g., [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py)).