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

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, 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.

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

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

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:

agent-reach doctor --json > doctor.json

Inspect specific channels using jq:

jq '.reddit' doctor.json

Integrating with Python Scripts

You can programmatically consume the health check in Python applications:

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 by executing per-channel check() methods defined in 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 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.

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