# How to Debug "Offline" Channel Connection Issues in Agent Reach Doctor Output

> Fix 'offline' channel connection issues in Agent Reach Doctor output. Troubleshoot missing executables, failed probes, config errors, or API credential problems.

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

---

**Agent Reach marks channels as "offline" when the Doctor cannot verify a working backend, typically caused by missing executables, failed environment probes, invalid configuration overrides, or missing API credentials.**

Agent Reach utilizes a modular *channel* architecture where each platform (YouTube, Twitter, Reddit) inherits from `agent_reach.channels.base.Channel`. The **Doctor** utility—accessible via `python -m agent_reach.cli doctor`—orchestrates health checks across all channels and formats a human-readable report showing which platforms are ready for data collection.

## How the Doctor Validates Channel Health

The Doctor executes a three-stage pipeline defined in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) to generate its diagnostic report.

**1. Channel Collection**

`get_all_channels()` (defined in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py)) instantiates every available channel singleton registered in the system.

**2. Health Check Execution**

`check_all()` iterates over the channel list and invokes `ch.check(config)` for each instance. Any exception raised during a check is caught to prevent a single faulty channel from crashing the entire report. The method records the `active_backend` (the first backend that successfully responds) and returns a status of `"ok"`, `"warn"`, or `"off"`.

**3. Report Formatting**

`format_report()` converts the raw results into a Rich-markup string. Channels are grouped by *tier*:
- **Tier 0**: Zero-config channels requiring no API keys
- **Tier 1**: Free-key channels requiring simple authentication
- **Tier 2**: Complex setup channels requiring manual configuration

Each line displays a ✅/⚠️/❌ icon, the channel name, a status message, and the active backend in dim text.

## Root Causes of "Offline" Channel Status

When the Doctor shows a red ❌ icon, the channel's `check()` method failed to verify a usable backend. The specific cause is encoded in the status message and can be traced to one of five implementation points:

- **Missing Backend Binary**: `BaseChannel.check()` in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) uses `shutil.which()` to locate executables. If the probe fails to find the binary on `$PATH`, the method returns `"off"` and the message displays *"未安装"* (not installed).

- **Stale Shim or Broken Environment**: The `probe_command()` function in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) executes the candidate binary with a lightweight `--version` flag. A non-zero exit code causes the backend to be rejected, even if the file exists.

- **Invalid User Override**: The configuration key `<channel>_backend` (or environment variable `<CHANNEL>_BACKEND`) dictates backend priority via `Channel.ordered_backends()`. If this override points to a non-existent binary, the probe fails silently and the channel remains offline.

- **Missing Authentication**: Tier 1 and Tier 2 channels return `"warn"` with messages like *"未登录"* (not logged in) or *"请配置 API-Key"* when `check()` cannot locate required cookies, tokens, or API keys in [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml).

- **File Permission Errors**: Lines 109–124 of [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) perform a security check. If [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) is world-readable, the report emits a red warning independent of channel status.

## Step-by-Step Debugging Workflow

Follow this sequence to resolve "offline" statuses in the Doctor output.

**1. Execute the Doctor**

Run the diagnostic command to generate the current health report:

```bash
python -m agent_reach.cli doctor

```

**2. Identify the Error Message**

Locate the red ❌ icon and read the accompanying message:
- *"未安装"* indicates the backend binary is missing from `$PATH`.
- *"未登录"* signals missing authentication credentials for that platform.
- *"体检异常：<exception>"* reveals an unexpected Python error requiring manual traceback review.

**3. Validate Backend Binaries**

Test the executable directly in your shell. For example, to verify the YouTube backend:

```bash
which yt-dlp
yt-dlp --version

```

If these commands fail, reinstall the binary or activate the correct virtual environment.

**4. Inspect Configuration Overrides**

Run `agent_reach config show` or examine `~/.agent-reach/config.yaml`. Ensure that `<channel>_backend` keys point to valid executables.

**5. Provide Required Credentials**

For Tier 1/2 channels, add the necessary API keys, cookies, or tokens to [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml). Refer to the guides in `agent_reach/guides/` for the specific format required by each platform.

**6. Rerun the Doctor**

After correcting the environment or configuration, execute the Doctor again. The channel should now display a green ✅ icon.

## Programmatically Interacting with the Doctor

You can invoke the diagnostic logic directly from Python to build custom monitoring or automate remediation.

**Running Checks and Parsing Output**

```python
from agent_reach.doctor import check_all, format_report
from agent_reach.config import Config

cfg = Config()
results = check_all(cfg)          # Runs every channel's check()

report = format_report(results)   # Generates Rich-markup string

print(report)

```

*Source:* [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)

**Manually Probing a Backend**

```python
from agent_reach.probe import probe_command

# YouTube channel defines backends = ["yt-dlp", "youtube-dl"]

ok, output = probe_command("yt-dlp", ["--version"])
print("Backend works?", ok)       # True if exit code is 0

```

*Source:* [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py)

**Overriding Backend via Configuration**

```yaml

# ~/.agent-reach/config.yaml

youtube_backend: yt-dlp   # Forces YouTube channel to prefer yt-dlp

```

The `Channel.ordered_backends()` method in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) moves the specified backend to the front of the candidate list.

## Core Source Files

| File | Role |
|------|------|
| [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) | Orchestrates health checks via `check_all()` and `format_report()` |
| [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) | Defines `Channel` base class, `ordered_backends()`, and default `check()` logic |
| [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) | Executes `probe_command()` to verify backend executability |
| [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) | Provides `get_all_channels()` registry |
| [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) | Loads and validates [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) settings |

## Summary

- Agent Reach channels appear "offline" when `check()` cannot verify a working backend executable or valid credentials.
- The Doctor groups channels by setup complexity (Tier 0–2) and catches all exceptions to prevent report crashes.
- Debug by validating `$PATH` binaries, testing `--version` probes, and inspecting `<channel>_backend` overrides in [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml).
- Tier 1/2 channels require manual API key or cookie configuration; missing auth triggers "未登录" warnings.
- Use `probe_command()` from [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) to test backend viability programmatically.

## Frequently Asked Questions

### What does the "offline" status mean in Agent Reach Doctor?

The "offline" (❌) status indicates that `check()` in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) failed to locate a working backend binary or verify required authentication. This occurs when `shutil.which()` finds no executable or when `probe_command()` in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) returns a non-zero exit code during the version check.

### How do I override which backend Agent Reach uses for a specific channel?

Set the `<channel>_backend` key in `~/.agent-reach/config.yaml` or export the `<CHANNEL>_BACKEND` environment variable. The `ordered_backends()` method in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) respects this override and moves the specified binary to the front of the candidate list for that channel.

### Why does a channel show "未登录" (not logged in) despite having the backend installed?

This message appears for Tier 1 or Tier 2 channels when the `check()` method cannot locate required credentials such as API keys, cookies, or tokens. Installation of the binary is necessary but insufficient; you must also populate the appropriate fields in [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) as documented in `agent_reach/guides/`.

### Where does Agent Reach store its configuration and security settings?

Agent Reach stores user configuration in `~/.agent-reach/config.yaml`. The Doctor (lines 109–124 in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)) validates file permissions and warns if the configuration file is world-readable, as this could expose sensitive API keys to other users on the system.