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

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

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 within the check_all function. This routine iterates over every channel registered via get_all_channels() (defined in agent_reach/channels/__init__.py), invoking channel.check(config) for each instance.

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 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	File is world-readable (mode 644)	Run chmod 600 ~/.agent-reach/config.yaml

Practical Usage Examples

Generate a human-readable health report:

$ agent-reach doctor

Sample output:

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

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

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

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

Capture structured data for automation:

$ agent-reach doctor --json | jq .

{
  "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, iterating over registered classes from 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. 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.

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

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