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

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

   agent-reach doctor --json > doctor.json

2. Identify problematic channels

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

   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)

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

   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:

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

Example output:

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

Verify specific channel backend availability:

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

Key Source Files for Deep Debugging

File	Role
agent_reach/doctor.py	Contains the check_all aggregation logic and format_report for Rich display
agent_reach/cli.py	Handles --json flag parsing and the _cmd_doctor JSON dumping implementation
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, twitter.py) containing the check logic that generates diagnostic messages
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
• 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 discovers available channels by iterating through registered channel classes that inherit from BaseChannel defined in agent_reach/channels/base.py. This ensures every implemented platform receives a diagnostic self-test without hardcoding specific channel names in the doctor logic.

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