# How to Use the Doctor Command to Diagnose Agent Reach Platform Issues

> Learn to use the doctor command to diagnose Agent Reach platform issues. Get a clear health check for your Twitter, Reddit, YouTube, and other integrations with human-readable or JSON reports.

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

---

**The `doctor` command runs a comprehensive health check across all Agent Reach channels, returning either a human-readable report with status indicators or machine-readable JSON to verify your Twitter, Reddit, YouTube, and other platform integrations are properly configured.**

The **Agent Reach** platform (available at `Panniantong/Agent-Reach`) provides a built-in diagnostic tool to verify your multi-channel setup. When you need to troubleshoot connectivity issues, missing credentials, or misconfigured proxies, the `doctor` command examines every supported channel and reports exactly which components are ready to use, require configuration, or are broken.

## How the Doctor Command Works

The diagnostic workflow follows a three-stage architecture: CLI parsing, channel health checking, and result aggregation.

### CLI Entry Point

When you execute `agent-reach doctor` from the terminal, the argument parser defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 92-96) creates a `Namespace` with `command == "doctor"` and dispatches to the `_cmd_doctor(args)` function.

```python
if args.command == "doctor":
    _cmd_doctor(args)   # cli.py line 46-48

```

The dispatcher instantiates the global `Config` object and passes it to the core health checker.

### Health Check Execution

The `_cmd_doctor` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) orchestrates the diagnostic process by calling `check_all(config)` from [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (lines 12-35):

```python
config = Config()
results = check_all(config)           # agent_reach/doctor.py line 12-35

if args.json:
    print(json.dumps(results, ensure_ascii=False, indent=2))
else:
    print(format_report(results))     # agent_reach/doctor.py line 47-128

```

The `check_all` function iterates over all registered channels via `get_all_channels()` from [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) and invokes each channel's `check(config)` method. This method is defined in the abstract `BaseChannel` class in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) and returns a `(status, message)` tuple. Any exceptions raised during channel checks are caught and converted to an `"error"` status, ensuring one misbehaving channel does not abort the entire diagnostic report.

## Understanding the Output

The doctor aggregates results into a dictionary keyed by channel name, providing detailed metadata about each platform's health status.

### Status Levels

Each channel returns one of four diagnostic states:

- **`"ok"`** – Channel is fully configured and ready to use
- **`"warn"`** – Channel is installed but requires additional configuration (login, API keys, or cookies)
- **`"off"`** – Channel is not installed or available
- **`"error"`** – Channel check failed due to an unexpected exception

### Report Structure

Every channel entry in the results dictionary contains:

- `status` – The health state of the channel
- `name` – Human-readable channel description
- `message` – Diagnostic text (e.g., "已登录", "缺少 cookie")
- `tier` – Installation complexity classification (0 = zero-config, 1 = needs free key/login, 2 = optional complex setup)
- `backends` – Available backend implementations for the channel
- `active_backend` – Currently selected backend when multiple options exist

The `format_report` function in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (lines 47-128) transforms this data into a rich-text report grouped by tier, using emoji indicators (✅ for available, ⚠️ for configuration needed, ❌ for errors) and warning about insecure [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) permissions on Unix systems.

## Running the Doctor Command

You can execute the diagnostic tool via command line for both interactive debugging and automated validation.

### Basic Health Check

Run the following command to generate a human-readable status report:

```bash
agent-reach doctor

```

This produces output similar to:

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

✅ 装好即用：
  ✅ Twitter — 已登录
  ✅ YouTube — 已配置

可选渠道（已安装）：
  ✅ Reddit — 已登录

状态：5/7 个渠道可用

```

### JSON Output for Automation

For CI pipelines or scripting, use the `--json` flag to receive machine-readable output:

```bash
agent-reach doctor --json

```

This outputs a structured JSON object:

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

```

## Programmatic Integration

The doctor functionality is fully exposed via Python API for custom tooling and automated testing workflows.

### Python API Usage

Import the core functions directly from `agent_reach.doctor` to run diagnostics programmatically:

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

cfg = Config()
results = check_all(cfg)          # dict with per-channel status

print(format_report(results))     # same rich text as CLI

```

### CI/CD Pipeline Integration

Integrate the doctor into your continuous integration pipeline to validate deployment health:

```yaml
steps:
  - name: Run Agent Reach doctor
    run: |
      python -m agent_reach.cli doctor --json > doctor_report.json
  - name: Fail if any channel is broken
    run: |
      python -c '
import json, sys
data = json.load(open("doctor_report.json"))
if any(v["status"] != "ok" for v in data.values()):
    sys.exit("Doctor found problems")
      '

```

## Summary

- The **`doctor`** command in Agent Reach provides comprehensive health diagnostics for all supported channels including Twitter, Reddit, and YouTube.
- **Entry point** is located in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), which dispatches to `check_all(config)` defined in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py).
- Each channel implements a `check()` method contract from [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) that returns status and diagnostic messages.
- Results include **tier classifications** (0-2) indicating setup complexity and **backend availability** for multi-implementation channels.
- Use **`--json`** for machine-readable output suitable for CI/CD automation and programmatic validation.
- The tool catches all exceptions during channel checks to ensure complete diagnostic coverage even when individual channels fail.

## Frequently Asked Questions

### What file contains the main doctor implementation logic?

The core health-checking logic resides in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), which contains the `check_all()` function (lines 12-35) for executing channel checks and `format_report()` (lines 47-128) for human-readable output formatting.

### How does the doctor command handle misconfigured channels?

The doctor command wraps each channel's `check()` call in exception handling. If a channel raises an error, the doctor catches it and reports the status as `"error"` with the exception message, allowing the diagnostic report to complete for all remaining channels rather than aborting prematurely.

### Can I add custom channels to the doctor check?

Yes. The doctor automatically discovers all channels registered via `get_all_channels()` in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py). To include a new platform, implement the `check(config)` method in your channel class following the `BaseChannel` contract defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), and the doctor will include it without requiring modifications to the core diagnostic logic.

### What is the difference between tier 0, tier 1, and tier 2 channels?

**Tier 0** channels require zero configuration and work immediately when credentials are present. **Tier 1** channels need additional setup such as free API keys or login cookies. **Tier 2** channels involve optional complex configuration or enterprise-level setup that most users do not require for basic functionality.