# How to Use the Doctor Command for Debugging Platform Issues in Agent Reach

> Debug platform issues with the Agent Reach doctor command. Get a color-coded report or JSON output identifying integration status and missing dependencies easily.

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

---

**The `doctor` command runs a comprehensive health check across all supported platforms by invoking each channel's `check` method and returning a color-coded report or JSON output that identifies which integrations are ready, misconfigured, or missing dependencies.**

Agent Reach is an open-source multi-platform automation framework that requires proper configuration for each social media channel. The **doctor command for debugging platform issues** provides a systematic way to diagnose connectivity, authentication, and dependency problems across Twitter, Reddit, Bilibili, XiaoHongShu, and other supported backends.

## How the Doctor Command Works Internally

### Command Entry Point in agent_reach/cli.py

The diagnostic process begins in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), where the CLI parser routes the `doctor` sub-command to the `_cmd_doctor` function. This entry point initializes the user configuration via `Config()` and orchestrates the health check workflow.

```python
def _cmd_doctor(args=None):
    from agent_reach.config import Config
    from agent_reach.doctor import check_all, format_report
    config = Config()
    results = check_all(config)
    # Outputs either Rich-formatted text or JSON

```

The function supports two output modes: a human-readable report rendered with the Rich library, or machine-readable JSON when `--json` is specified.

### Health Check Execution in agent_reach/doctor.py

The core logic resides in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) within the `check_all` function. This routine iterates over every channel registered via `get_all_channels()` (defined in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py)), invoking `channel.check(config)` for each instance.

```python
for ch in get_all_channels():
    status, message = ch.check(config)
    results[ch.name] = {
        "status": status,
        "name": ch.description,
        "message": message,
        "tier": ch.tier,
        "backends": ch.backends,
    }

```

Each channel returns a tuple containing a **status** (`ok`, `warn`, `off`, or `error`) and a descriptive **message** explaining the current state or missing requirements.

### Report Generation and Output Modes

Results are processed through `format_report`, which aggregates channel states and renders a legend (✅ available, [!] requires configuration, [X] not installed) alongside per-tier groupings. The report includes a security warning if `~/.agent-reach/config.yaml` has overly permissive file permissions.

When the `--json` flag is provided, the command bypasses Rich formatting and executes `json.dumps(results)` for programmatic consumption in CI pipelines or automation scripts.

## Running the Doctor Command: Step-by-Step Workflow

Follow this systematic approach to diagnose and resolve platform integration issues:

1. **Run a baseline health check** with `agent-reach doctor` to generate a color-coded overview of all channels.

2. **Capture machine-readable output** using `agent-reach doctor --json` for scripts that programmatically determine which platforms are available.

3. **Identify channels with `warn` or `off` status** in the report. The accompanying message specifies the missing configuration (e.g., "未配置 Twitter cookies" or "需要代理").

4. **Apply the suggested fix**, such as running `agent-reach configure twitter-cookies …` or installing the required CLI tool like `twitter-cli`.

5. **Verify file permissions** if the report warns about [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) being world-readable. Execute `chmod 600 ~/.agent-reach/config.yaml` to prevent credential leakage.

## Interpreting the Diagnostic Report

### Understanding Status Symbols and Configuration Tiers

The report organizes channels into **tiers** based on setup complexity:

- **Tier 0**: Zero-configuration channels that work out-of-the-box (e.g., Reddit, provided the binary is installed).
- **Tier 1**: Channels requiring a free API key or login cookies (e.g., Twitter, XiaoHongShu).
- **Tier 2**: Optional integrations with complex setup requirements (e.g., Bilibili behind a proxy, Exa search).

Status indicators include:
- **✅ `ok`**: Channel is fully operational and authenticated.
- **[!] `warn`**: Installed but requires additional configuration (e.g., proxy settings or cookie refresh).
- **[X] `off` or `error`**: Missing dependencies or not installed.

### Common Platform Issues and Solutions

| Symptom | Root Cause | Resolution |
|---------|------------|------------|
| `[!] Bilibili — 需要代理` | `bilibili_proxy` not set in config | Run `agent-reach configure proxy http://user:pass@ip:port` |
| `[X] twitter-cli not installed` | `shutil.which("twitter")` returned `None` | Execute `pipx install twitter-cli` or `uv tool install twitter-cli` |
| `[!] XHS cookies missing` | Cookie extraction failed or expired | Run `agent-reach configure xhs-cookies "<header>"` or use `--from-browser` |
| Permission warning on [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) | File is world-readable (mode 644) | Run `chmod 600 ~/.agent-reach/config.yaml` |

## Practical Usage Examples

Generate a human-readable health report:

```bash
$ agent-reach doctor

```

Sample output:

```text
Agent Reach 状态
========================================
图例：✅ 可用  [!] 已装但需配置/登录  [X] 未安装

✅ 装好即用：
  ✅ Twitter — 已登录
  [!]  Bilibili — 需要代理（未配置）

可选渠道（已安装）：
  ✅ Reddit — 已安装

状态：3/5 个渠道可用
还有 2 个可选渠道可以解锁（XHS、YouTube），告诉你的 Agent「帮我装 XXX」即可

```

Capture structured data for automation:

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

```

```json
{
  "twitter": {
    "status": "ok",
    "name": "Twitter",
    "message": "已登录",
    "tier": 0,
    "backends": []
  },
  "bilibili": {
    "status": "warn",
    "name": "Bilibili",
    "message": "需要代理（未配置）",
    "tier": 0,
    "backends": []
  }
}

```

## Summary

- The `doctor` command aggregates health status from all channels via `check_all` in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), iterating over registered classes from [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py).
- Status values include `ok`, `warn`, `off`, and `error`, with configuration tiers 0-2 indicating setup complexity from zero-config to optional advanced integrations.
- Human-readable reports use Rich formatting with color-coded symbols, while `--json` enables machine-readable output for CI integration.
- Each diagnostic message includes specific remediation steps, such as running `agent-reach configure <platform>-cookies` or adjusting file permissions on `~/.agent-reach/config.yaml`.

## Frequently Asked Questions

### What does the "tier" field indicate in the doctor report?

The **tier** field categorizes channels by setup difficulty according to the source code in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py). Tier 0 requires no configuration (e.g., Reddit), Tier 1 needs free API keys or login cookies (e.g., Twitter), and Tier 2 involves optional complex setup like proxy configuration for Bilibili or additional dependency installation.

### How do I fix a "warn" status for a specific platform?

A `warn` status indicates the channel is installed but lacks required configuration. Follow the specific **message** returned by the channel's `check` method—for example, if Twitter shows a warning, run `agent-reach configure twitter-cookies` with your authentication headers. For Bilibili warnings, configure the proxy setting in [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml).

### Can I use the doctor command in automated CI pipelines?

Yes. Append the `--json` flag to `agent-reach doctor` to output raw JSON instead of styled text. This allows shell scripts or CI jobs to parse the results programmatically using tools like `jq` to determine which platforms are available before executing platform-specific tasks.

### Where does the doctor command check for configuration files?

The command loads settings via `Config()` from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), which reads `~/.agent-reach/config.yaml` by default. The doctor utility specifically checks this file's permissions during execution and warns if it is world-readable, recommending `chmod 600` to secure credentials stored in the configuration.