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

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 (lines 92-96) creates a Namespace with command == "doctor" and dispatches to the _cmd_doctor(args) function.

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 orchestrates the diagnostic process by calling check_all(config) from agent_reach/doctor.py (lines 12-35):

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 and invokes each channel's check(config) method. This method is defined in the abstract BaseChannel class in 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 (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 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:

agent-reach doctor

This produces output similar to:

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:

agent-reach doctor --json

This outputs a structured JSON object:

{
  "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:

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:

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, which dispatches to check_all(config) defined in agent_reach/doctor.py.
• Each channel implements a check() method contract from 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, 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. 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}