How to Troubleshoot 'Off' or 'Error' Channel Status in the Agent Reach Doctor Report

Troubleshoot 'off' or 'error' statuses in the Agent Reach doctor report by installing missing binaries, adding required JavaScript runtimes, or exporting the authentication variables shown in the red error message, then rerunning python -m agent_reach.cli doctor to verify.

The python -m agent_reach.cli doctor command in the Agent Reach repository (Panniantong/Agent-Reach) scans every channel to verify that backend tools are installed and configured. When a channel appears with an off or error status, the report prints a specific message that points directly to the root cause. Understanding how agent_reach/doctor.py aggregates these results lets you fix the underlying issue quickly.

How the Doctor Command Collects Channel Statuses

In agent_reach/doctor.py, the doctor command loads every registered channel through get_all_channels() and invokes each channel's check() method.

# https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py

for ch in get_all_channels():
    status, message = ch.check(config)

BaseChannel Check Contract

Every channel inherits from the Channel base class in agent_reach/channels/base.py. The default implementation returns "ok", while concrete subclasses override check() to perform binary detection and credential verification.

# https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py

def check(self, config=None) -> Tuple[str, str]:
    return "ok", f"{'、'.join(self.backends) if self.backends else '内置'}"

Platform-Specific Health Checks

Channel subclasses implement custom logic. For example, the YouTube channel in agent_reach/channels/youtube.py verifies that yt-dlp exists on PATH.

# https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py

if not shutil.which("yt-dlp"):
    return "off", "yt-dlp 未安装。安装：pip install yt-dlp"

The Twitter/X channel in agent_reach/channels/twitter.py prefers the twitter CLI and falls back to bird, checking for authentication tokens if the binary is present but unconfigured.

Report Formatting for Failed Channels

The format_report() function in agent_reach/doctor.py renders off and error entries in red so they stand out immediately.

# https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py

elif r["status"] in ("off", "error"):
    lines.append(f"  [red][X][/red]  {name_msg}")

Common Causes of 'Off' and 'Error' Statuses

• YouTube — An 'off' status means yt-dlp is missing. An 'error' usually stems from a PermissionError or malformed JSON inside the yt-dlp configuration file.
• Twitter/X — The twitter.py snippet returns "warn" when shutil.which("twitter") fails; an 'error' occurs when the CLI subprocess crashes during probing.
• RSS — An 'off' status means the feedparser package is not installed, while an 'error' can arise from a broken virtual environment that triggers an ImportError.
• Weibo / WeChat — These platforms rely on an internal proxy (mcporter). A connection failure generally indicates a network timeout or SSL error.
• Other platforms — Any missing upstream runtime such as deno or node produces 'off', and any uncaught exception inside check() produces 'error'.

Step-by-Step Troubleshooting Guide

Run the Doctor Command

Start by generating the full health report:

python -m agent_reach.cli doctor

The report prints a red [X] next to any channel with an 'off' or 'error' status, followed by a diagnostic message.

Interpret the Diagnostic Message

Match the message text to the root cause:

• If the message contains 未安装, the required binary is absent.
• If the message contains 未配置, a credential or runtime variable is missing.
• If the message mentions 连接异常, investigate network or proxy connectivity.

Install Missing Binaries

For YouTube, install yt-dlp:

pip install yt-dlp

For Twitter/X, install the CLI via pipx or uv:

pipx install twitter-cli

# or

uv tool install twitter-cli

Add a JavaScript Runtime

YouTube requires a JS interpreter such as Node.js or Deno:

# Node.js

curl -fsSL https://deb.nodesource.com/setup_current.x | sudo -E bash -
sudo apt-get install -y nodejs

# Deno alternative

curl -fsSL https://deno.land/x/install/install.sh | sh

Configure Missing Credentials

For Twitter/X, export the required tokens:

export TWITTER_AUTH_TOKEN="your_token"
export TWITTER_CT0="your_ct0"

If you rely on the Bird CLI fallback, use these variables instead:

export AUTH_TOKEN="your_token"
export CT0="your_ct0"

Persist the YouTube Runtime Configuration

According to agent_reach/utils/paths.py, the built-in installer appends --js-runtimes node to the yt-dlp config:

agent-reach install

Verify the Fix

Rerun the Doctor command to confirm the channel status switches to ok:

python -m agent_reach.cli doctor

Persist Environment Variables

Add the export statements to ~/.bashrc or to a .env file loaded by your shell so the settings survive across sessions.

Practical CLI Examples

Fixing YouTube 'Off' Status (Missing yt-dlp)

When the doctor report prints a red [X] next to YouTube, the message typically reads yt-dlp 未安装.

$ python -m agent_reach.cli doctor | grep YouTube
  [red][X][/red]  YouTube 视频和字幕 — yt-dlp 未安装。安装：pip install yt-dlp

Install the binary, add a JS runtime if necessary, and verify:

pip install yt-dlp

curl -fsSL https://deb.nodesource.com/setup_current.x | sudo -E bash -
sudo apt-get install -y nodejs

python -m agent_reach.cli doctor

Resolving Twitter/X Authentication Warnings

A yellow [!] indicates the binary exists but lacks credentials. The Twitter channel in agent_reach/channels/twitter.py checks for these tokens after confirming the CLI is present.

$ python -m agent_reach.cli doctor | grep Twitter
  [yellow][!][/yellow]  Twitter/X 推文 — twitter-cli 已安装但未认证。设置方式：

Export the variables and validate:

export TWITTER_AUTH_TOKEN="YOUR_TOKEN"
export TWITTER_CT0="YOUR_CT0"

twitter -v status

python -m agent_reach.cli doctor

Installing a Missing JavaScript Runtime for YouTube

If yt-dlp is installed but Node or Deno is missing, the report shows a warning that YouTube requires a JS runtime.

$ python -m agent_reach.cli doctor | grep YouTube
  [yellow][!][/yellow]  YouTube 视频和字幕 — yt-dlp 已安装但缺少 JS runtime（YouTube 必须）。

Install Node.js, then update the configuration:

curl -fsSL https://deb.nodesource.com/setup_current.x | sudo -E bash -
sudo apt-get install -y nodejs

agent-reach install

python -m agent_reach.cli doctor

Summary

• agent_reach/doctor.py calls check() on every channel via get_all_channels(), and 'off' or 'error' results are rendered in red by format_report().
• An 'off' status means a required binary or package is missing, while an 'error' status signals an unexpected exception during the health probe.
• YouTube issues are usually resolved by installing yt-dlp and a JS runtime (node or deno), then running agent-reach install to persist the config.
• Twitter/X issues are fixed by installing twitter-cli and exporting TWITTER_AUTH_TOKEN and TWITTER_CT0.
• Always rerun python -m agent_reach.cli doctor after each change to confirm the channel returns ok.

Frequently Asked Questions

What does the 'off' status mean in the Agent Reach doctor report?

The 'off' status means the required binary or Python package for that channel was not found on the system. For example, the YouTube channel in agent_reach/channels/youtube.py returns 'off' when shutil.which("yt-dlp") fails, indicating you need to install the missing tool.

How is 'error' different from 'warn' in the doctor report?

The 'error' status appears when the check() method raises an unexpected exception that is not handled by the channel's own logic, such as a subprocess crash or a permissions failure. The 'warn' status is returned intentionally by the channel when a binary exists but a configuration step—like a missing credential or JS runtime—is incomplete.

Why does the YouTube channel require a JavaScript runtime?

According to the source logic in agent_reach/channels/youtube.py, yt-dlp needs a JS interpreter to evaluate player scripts on modern YouTube pages. The doctor checks for deno or node; if neither is present, the channel reports an installation warning or error depending on how far the probe gets.

Where should I store persistent environment variables for Agent Reach channels?

Add the necessary export statements to your shell profile, such as ~/.bashrc or ~/.zshrc, or place them in a .env file that your execution environment loads before running python -m agent_reach.cli doctor. This prevents authentication warnings from recurring across terminal sessions.

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