# How to Debug Channel Detection Issues Using `agent-reach doctor --json`

> Debug channel detection issues in Agent Reach with `agent-reach doctor --json`. Get machine-readable diagnostics for error messages, API keys, and backend misconfigurations.

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

---

**Run `agent-reach doctor --json` to expose machine-readable diagnostics that reveal exact error messages, missing API keys, and backend misconfigurations for every channel in the Agent Reach framework.**

Agent Reach is an open-source automation framework that relies on multiple channel integrations to interact with various platforms. When channels fail to initialize or report detection errors, the `--json` flag on the `doctor` command provides structured diagnostic data that bypasses the human-readable summary to reveal precise failure details.

## Understanding the `doctor --json` Output Structure

### Core Aggregation Logic

The diagnostic aggregation lives in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) within the `check_all` function. This function iterates through every registered channel, invoking each channel's `BaseChannel.check` method to perform self-tests and collect health metrics.

### JSON Schema and Status Codes

When you append `--json`, the CLI handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (specifically within the `_cmd_doctor` implementation) bypasses the Rich formatter and dumps the raw result dictionary via `json.dumps`. Each channel entry in the JSON payload contains:

- **`status`**: `"ok"` (functional), `"warn"` (installed but needs config), `"off"` (not installed), or `"error"` (exception during check)
- **`name`**: Human-readable channel description
- **`message`**: Diagnostic details (e.g., "未登录", "缺少 API-Key", or exception text)
- **`tier`**: Complexity level where **0** = zero-config, **1** = requires login/key, **2** = optional complex setup
- **`backends`**: List of available backend names the channel can utilize
- **`active_backend`**: Currently selected backend (shown only when multiple backends exist)

When detection fails, `status` becomes `"error"` and `message` contains the raw exception text (e.g., "体检异常：twitter-cli not installed").

## Why JSON Output Beats the Rich Report

The human-readable Rich report condenses inactive channels and hides raw exception traces. The JSON output provides three critical advantages for debugging:

- **Exact error strings** for log searching and error tracking systems
- **Programmatic accessibility** via `jq` or Python scripts to automate health checks
- **Stable field names** guaranteed by the `check_all` contract, regardless of UI theming changes

## Step-by-Step Debugging Workflow

Follow this sequence to isolate and resolve channel detection failures:

1. **Generate the diagnostic dump**

   ```bash
   agent-reach doctor --json > doctor.json
   ```

2. **Identify problematic channels**

   Filter for any entry where `status` is not `"ok"`:

   ```bash
   jq 'to_entries[] | select(.value.status!="ok")' doctor.json
   ```

3. **Read the diagnostic message**

   The `"message"` field specifies what is missing, such as a binary, cookie, or API key.

4. **Check backend selection** (for multi-backend channels)

   ```bash
   jq '.["reddit"].active_backend' doctor.json
   ```

   If `active_backend` is `null` but `backends` lists alternatives, install or configure the preferred backend.

5. **Cross-reference the channel implementation**

   Each channel's validation logic lives in `agent_reach/channels/<platform>.py` (e.g., [`twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/twitter.py), [`reddit.py`](https://github.com/Panniantong/Agent-Reach/blob/main/reddit.py)). Examine the `check` method to understand the specific validation logic that generated the message.

6. **Apply the appropriate fix**

   - **Missing binary**: Run `agent-reach install --channels=<name>`
   - **Missing cookie**: Execute `agent-reach configure --from-browser <browser>` or set manually via `agent-reach configure <platform>-cookies`
   - **Missing API key**: Add via `agent-reach configure <platform>-key <value>`

7. **Validate the resolution**

   ```bash
   agent-reach doctor --json | jq .
   ```

   Confirm the channel now reports `"status": "ok"`.

## Practical Code Examples for Filtering Output

Extract only channels that failed with errors:

```bash
agent-reach doctor --json | \
jq 'to_entries[] | select(.value.status=="error") | {channel:.key, message:.value.message}'

```

Example output:

```json
{
  "channel": "twitter",
  "message": "体检异常：twitter-cli not installed"
}

```

Verify specific channel backend availability:

```bash
jq '.["twitter"] | {backends, active_backend, status}' doctor.json

```

## Key Source Files for Deep Debugging

| File | Role |
|------|------|
| [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) | Contains the `check_all` aggregation logic and `format_report` for Rich display |
| [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | Handles `--json` flag parsing and the `_cmd_doctor` JSON dumping implementation |
| [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) | Defines the `BaseChannel` abstract class requiring implementations of `can_handle`, `read`, `search`, and `check` |
| `agent_reach/channels/<platform>.py` | Platform-specific implementations (e.g., [`xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaohongshu.py), [`twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/twitter.py)) containing the `check` logic that generates diagnostic messages |
| [`tests/test_doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_doctor.py) | Test suite exercising the doctor command, including JSON output verification |

## Summary

- The `agent-reach doctor --json` command outputs structured diagnostics aggregated by the `check_all` function in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)
- **Status codes** indicate health levels: `"ok"`, `"warn"`, `"off"`, or `"error"`
- Use `jq` to filter for non-OK statuses and isolate specific failure messages programmatically
- Each channel's validation logic resides in its `check` method within `agent_reach/channels/<platform>.py`
- Resolve issues using `agent-reach configure` for credentials or `agent-reach install` for missing binaries, then re-run the doctor to confirm `"status": "ok"`

## Frequently Asked Questions

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

The `tier` field categorizes channel setup complexity according to the `BaseChannel` contract. **Tier 0** indicates zero-configuration channels that function immediately without credentials. **Tier 1** requires authentication elements such as login sessions or API keys. **Tier 2** denotes optional complex setup requiring specific browser configurations, external toolchains, or advanced environment preparation.

### Why is a channel showing "error" status instead of "off"?

An `"error"` status signifies that the channel's `check` method in `agent_reach/channels/<platform>.py` raised an unhandled exception during validation, while `"off"` simply indicates the channel binary or dependency is not installed. Inspect the `message` field for the specific exception text, which typically reveals missing Python packages, network timeouts, or authentication failures that occurred during the self-test.

### How do I programmatically check if all channels are healthy?

Pipe the JSON output to a validation utility that verifies every entry's `status` field equals `"ok"`. For example, run `agent-reach doctor --json | jq -e 'all(.[]; .status == "ok")'` which returns exit code 0 only if all channels report healthy status, making it ideal for CI/CD pipelines or monitoring scripts that require automated health verification.

### Where does the doctor command get the list of channels to check?

The `check_all` function in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) discovers available channels by iterating through registered channel classes that inherit from `BaseChannel` defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). This ensures every implemented platform receives a diagnostic self-test without hardcoding specific channel names in the doctor logic.