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

> Troubleshoot off or error channel status in the Agent Reach doctor report by installing binaries, adding JavaScript runtimes, or exporting auth variables. Rerun the doctor command for verification.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), the doctor command loads every registered channel through `get_all_channels()` and invokes each channel's `check()` method.

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). The default implementation returns `"ok"`, while concrete subclasses override `check()` to perform binary detection and credential verification.

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) verifies that `yt-dlp` exists on `PATH`.

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) renders off and error entries in red so they stand out immediately.

```python

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

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

```bash
pip install yt-dlp

```

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

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

```bash

# 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:

```bash
export TWITTER_AUTH_TOKEN="your_token"
export TWITTER_CT0="your_ct0"

```

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

```bash
export AUTH_TOKEN="your_token"
export CT0="your_ct0"

```

### Persist the YouTube Runtime Configuration

According to [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py), the built-in installer appends `--js-runtimes node` to the `yt-dlp` config:

```bash
agent-reach install

```

### Verify the Fix

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

```bash
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 未安装`.

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

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) checks for these tokens after confirming the CLI is present.

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

```

Export the variables and validate:

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

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

```

Install Node.js, then update the configuration:

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