How to Debug Channel Issues Using the Agent Reach Doctor JSON Output

Use agent-reach doctor --json to generate a machine-readable diagnostic report, then filter for status: "error" or "warn" entries to identify misconfigured channels and their specific failure messages.

The Agent Reach framework provides a built-in diagnostics system that validates every registered channel's health. When you append the --json flag to the doctor command, the tool outputs a structured payload that maps channel names to their configuration status, dependency checks, and active back-ends. This JSON format eliminates locale-dependent terminal markup and enables automated parsing in CI pipelines or agent runtimes.

Understanding the Doctor JSON Structure

The diagnostic report is generated by check_all() in [agent_reach/doctor.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py#L12) and printed via the CLI handler in [agent_reach/cli.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L47). Each channel implements a check(config) method defined in the abstract base class at [agent_reach/channels/base.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py#L28).

The JSON object contains top-level keys for each channel (e.g., "twitter", "reddit"), with values containing these fields:

• status: "ok" (healthy), "warn" (installed but needs configuration), "off" (missing dependencies), or "error" (exception raised during check).
• name: Human-readable description (e.g., "Twitter 时间线").
• message: Diagnostic explanation (e.g., "未检测到 twitter-cli").
• tier: Configuration complexity level (0 = zero-config, 1 = free key/login required, 2 = extra setup needed).
• backends: Ordered list of candidate back-ends for the channel.
• active_backend: The back-end actually selected after probing (may be null).

If a channel raises an exception during the check, the doctor routine catches it at line 23 in doctor.py and records status: "error" with the exception text in message, ensuring one broken channel cannot collapse the entire report.

Step-by-Step Debugging Workflow

Generate the JSON Report

Run the diagnostics command and redirect the output to a file for inspection:

agent-reach doctor --json > doctor.json

The resulting file contains a single JSON object where each key represents a channel identifier.

Parse and Filter Problematic Channels

Load the JSON and isolate channels reporting errors or warnings:

import json
import pathlib

data = json.load(open("doctor.json"))
problems = {
    k: v for k, v in data.items() 
    if v["status"] in ("error", "warn")
}

for name, info in problems.items():
    print(f"{name}: {info['status']} – {info['message']}")
    if info["active_backend"]:
        print(f"  Active backend: {info['active_backend']}")

This script outputs a concise list of channels requiring attention, including the specific failure reason in the message field.

Inspect Channel Source Code

Drill into the offending channel's implementation in agent_reach/channels/. For example, the Twitter channel resides in [agent_reach/channels/twitter.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py), where its check method (line 41) calls shutil.which("twitter") and may probe the back-end using probe_command from agent_reach/probe.py.

Examine the check method to understand how it constructs the message and determines the active_backend.

Replicate Probes Manually

Many channels use the probe_command helper to verify back-end functionality. Replicate this check directly in a Python REPL to isolate environment issues:

from agent_reach.probe import probe_command

# Verify twitter-cli can authenticate

ok, out = probe_command(["twitter", "status"], timeout=10)
print("OK?", ok)
print(out)

Adjust the command list to match the channel's backends list as shown in the JSON output.

Resolve and Verify

Interpret the message field to determine the fix:

• "未检测到 twitter-cli": Install the missing binary via pipx install twitter-cli or system package manager.
• "体检异常：": Review the traceback in the JSON and correlate with lines 23-27 in doctor.py to identify the failure point.
• Missing credentials: Provide required tokens via agent-reach configure <channel>-cookies ....

After corrective action, rerun agent-reach doctor --json to confirm the channel now reports "status": "ok".

Programmatic Usage for Automation

The JSON format enables CI pipelines to gate deployments based on channel health. Use this one-liner to exit non-zero if any channel requires attention:

python - <<'PY'
import json, sys
data = json.load(open("doctor.json"))
bad = [k for k, v in data.items() if v['status'] != "ok"]
if bad:
    print("Unhealthy channels:", ", ".join(bad))
    sys.exit(1)
PY

Alternatively, embed the check directly in Python applications:

from agent_reach.config import Config
from agent_reach.doctor import check_all

cfg = Config()  # loads ~/.agent-reach/config.yaml

report = check_all(cfg)

problem_channels = {
    k: v for k, v in report.items() 
    if v["status"] in ("error", "warn")
}
print("Channels needing attention:", list(problem_channels.keys()))

Why the JSON Format Matters for Automation

Structured data eliminates parsing errors from colored terminal output or translated strings. Machine-readable status codes allow build scripts to fail fast when critical channels report "error". Programmatic access via check_all() lets embedding agents dynamically select usable back-ends at runtime based on the tier and active_backend fields.

Summary

• The agent-reach doctor --json command produces a structured health report for every channel.
• Each channel entry includes status, message, and active_backend fields generated by the check() method in [agent_reach/doctor.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py).
• Filter the JSON for status values of "error" or "warn" to identify misconfigurations.
• Replicate channel checks manually using probe_command from [agent_reach/probe.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) to isolate environment issues.
• The JSON output is generated by check_all() in [agent_reach/doctor.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) and printed by the CLI in [agent_reach/cli.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

Frequently Asked Questions

What does the "tier" field indicate in the doctor JSON output?

The tier field indicates the configuration complexity required to activate the channel. Tier 0 means zero-config (works immediately), tier 1 requires a free API key or login credentials, and tier 2 demands additional setup such as custom headers or proxy configuration. This helps prioritize which channels to configure first when onboarding new environments.

How does Agent Reach handle exceptions during channel checks?

According to the source code in [agent_reach/doctor.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py#L23), the check_all() function wraps each channel's check() call in a try-except block. If a channel raises an exception, the doctor records status: "error" and captures the exception text in the message field instead of crashing the entire diagnostic report. This ensures you receive a complete health overview even when individual channels are broken.

Can I use the doctor JSON output in CI/CD pipelines?

Yes. The JSON output is specifically designed for automation. You can pipe agent-reach doctor --json into a Python script or use jq to verify that no channels report "error" or "warn" statuses before proceeding with deployment. The structured format eliminates locale-dependent parsing issues common with colored terminal output.

Where is the active_backend field set during the check process?

The active_backend field is populated by each channel's check method, which must set self.active_backend according to the abstract base class defined in [agent_reach/channels/base.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py#L28). The method returns a (status, message) tuple, and the doctor aggregates these into the final JSON output under the active_backend key. If no suitable back-end is found, this value will be null.

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