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

> Debug channel issues with Agent Reach Doctor JSON output. Generate a machine-readable report, filter for errors and warnings, and quickly pinpoint channel misconfigurations. Improve your agent reach diagnostics today.

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

---

**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)](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)](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)](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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

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

```python
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)](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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python
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.
- **"体检异常：<exception>"**: Review the traceback in the JSON and correlate with lines 23-27 in [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

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

```python
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)](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)](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)](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)](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)](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)](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`.