# What the Agent-Reach Doctor Command Checks and How to Read Its Output

> Understand the agent-reach doctor command. Learn what it checks for tool installation configuration and backend status and how to read its output for channel readiness.

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

---

**The `agent-reach doctor` command performs a comprehensive health check across all configured channels, verifying tool installation, configuration status, and backend availability, then outputs a tiered report showing which channels are ready to use.**

The `agent-reach doctor` command is the built-in diagnostic tool of the **Agent Reach** open-source framework. Located in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), this command helps users verify their environment setup before deploying agents. This guide explains exactly what the command validates and how to interpret both human-readable and machine-readable outputs.

## What the Agent-Reach Doctor Command Validates

The diagnostic process follows a three-step pipeline defined in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py).

### Channel Discovery via `get_all_channels()`

First, the CLI entry point `_cmd_doctor` calls `agent_reach.doctor.check_all`, which iterates over every channel returned by `agent_reach.channels.get_all_channels()`. This registry is maintained in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) within the `ALL_CHANNELS` list, ensuring every available channel is included in the health check.

### Per-Channel Validation with `check()`

For each `Channel` object, the function calls `ch.check(config)`. The base implementation in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) simply reports the list of possible backends and marks the first one as active. Concrete channel subclasses override this method to probe actual tools like `twitter-cli`, `opencli`, or `rdt-cli`, verifying binaries exist and configurations are valid.

### Error Handling and Status Mapping

Any exception raised during a channel check is caught and transformed into a status of `error`. The function returns a dictionary mapping channel names to status objects containing `status`, `name`, `message`, `tier`, `backends`, and `active_backend` fields.

## Interpreting the Text Report

The `format_report()` function in [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) constructs a Rich-formatted console output grouped by configuration tiers.

### Understanding the Legend and Symbols

The report begins with a visual legend explaining three states:

- **✅ (green)** – Channel is usable and fully configured
- **[!] (yellow)** – Tool is installed but requires additional configuration or login
- **[X] (red)** – Tool is not installed or unavailable

### Tier 0: Zero-Config Channels

Channels marked as tier 0 appear under the "装好即用" (ready-to-use) section. These should display green checkmarks if the underlying CLI tool is present in your PATH. For example:

```

✅ YouTube — ✅ YouTube 可用

```

This indicates the `youtube-cli` backend is detected and functional.

### Tier 1 and Tier 2: Optional Channels

Higher-tier channels requiring API keys, login cookies, or complex setup appear under "可选渠道" (optional channels). When installed but unconfigured, these show the yellow warning icon:

```

[!] Reddit — 需要登录 (rdt-cli 未配置)

```

### Backend Detection and Active Implementation

When a channel supports multiple backends (e.g., XiaoHongShu can use `opencli` or `xiaohongshu-mcp`), the report appends a note indicating which implementation is currently active:

```

（当前后端：opencli）

```

This is generated by the `_name_msg` helper in [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) and helps identify which specific tool is handling requests.

## Interpreting the JSON Output

When invoked with the `--json` flag, the command bypasses the Rich formatter and outputs raw JSON suitable for programmatic parsing.

The output structure is a dictionary keyed by channel name:

```json
{
  "youtube": {
    "status": "ok",
    "name": "YouTube 视频和字幕",
    "message": "✅ youtube 已安装",
    "tier": 0,
    "backends": ["youtube-cli"],
    "active_backend": "youtube-cli"
  }
}

```

Valid status values are `ok`, `warn`, `off`, and `error`. The `backends` array lists all candidate implementations, while `active_backend` indicates the currently selected one or `null` if none are configured.

## Running the Doctor Command: Practical Examples

### Basic Human-Readable Output

Execute the standard diagnostic to see the formatted console report:

```bash
agent-reach doctor

```

Typical output includes the tiered organization and summary statistics:

```

Agent Reach 状态
========================================
图例：✅ 可用  [!] 已装但需配置/登录  [X] 未安装

✅ 装好即用：
  ✅ YouTube — ✅ YouTube 可用
  ✅ GitHub — ✅ GitHub 可用

状态：9/12 个渠道可用

```

### Machine-Readable JSON Output

For integration with scripts or CI/CD pipelines, use the JSON flag:

```bash
agent-reach doctor --json > doctor.json

```

Inspect specific channels using `jq`:

```bash
jq '.reddit' doctor.json

```

### Integrating with Python Scripts

You can programmatically consume the health check in Python applications:

```python
import json
import subprocess

def run_doctor():
    out = subprocess.check_output(
        ["agent-reach", "doctor", "--json"], 
        text=True
    )
    return json.loads(out)

result = run_doctor()
for ch, info in result.items():
    if info["status"] != "ok":
        print(f"{info['name']} needs attention: {info['message']}")

```

This pattern allows automated agents to verify prerequisites before attempting operations on specific channels.

## Summary

- The `agent-reach doctor` command validates every channel registered in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) by executing per-channel `check()` methods defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py).
- Text output uses a three-tier system (0, 1, 2) with visual symbols (✅, [!], [X]) to indicate usability, configuration requirements, and missing installations.
- Each channel report includes the `active_backend` field showing which implementation is currently selected from available `backends`.
- JSON output via `--json` provides machine-readable status codes (`ok`, `warn`, `off`, `error`) for automation and scripting.
- The diagnostic catches all exceptions during checks and converts them to `error` status to prevent CLI crashes.

## Frequently Asked Questions

### What should I do if a channel shows the yellow warning icon?

The yellow `[!]` symbol indicates the tool is installed but lacks required configuration. Check the specific message—for example, "缺少 cookie" or "需要登录"—and provide the missing credentials or configuration files in the expected location for that channel's CLI tool.

### Can I check only specific channels instead of running a full diagnostic?

Currently, [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) iterates over all channels returned by `get_all_channels()` without a filtering mechanism. To check specific channels, you must run the full `agent-reach doctor` command and filter the JSON output using tools like `jq` or by parsing the dictionary in Python to examine only the keys you care about.

### What does the "active_backend" field indicate in the JSON output?

The `active_backend` field reveals which specific CLI tool or API implementation is currently handling requests for that channel. For instance, if a channel supports both `opencli` and a native MCP server, this field shows which one is actually configured and operational, while the `backends` array lists all available alternatives.

### How do I fix channels showing "error" status?

An `error` status means the channel's `check()` method raised an exception, usually due to missing binaries, permission issues, or corrupted configuration. Verify the underlying CLI tool is installed and accessible in your PATH, check file permissions for configuration directories, and consult the specific channel's documentation for setup requirements.