# How to Troubleshoot Common Agent-Reach Issues: A Complete Diagnostic Guide

> Troubleshoot common Agent-Reach issues with our diagnostic guide. Learn to identify root causes, verify dependencies, and fix connectivity or auth errors using agent-reach doctor.

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

---

**Run `agent-reach doctor --json` to identify the root cause of failures, then verify system dependencies, config file permissions (mode 600), and upstream CLI availability to resolve most connectivity and authentication errors.**

Agent-Reach is a lightweight installer and diagnostic **doctor** that provides AI agents with transparent access to Internet platforms without wrapping upstream tools. When integrations fail, the issue typically stems from missing system binaries, misconfigured credentials in `~/.agent-reach/config.yaml`, or incorrect file permissions. This guide walks through the most common failure modes and their fixes using the actual source implementation from the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository.

## Installation Failures

### Missing System Dependencies (gh CLI and Node.js)

*Symptoms*: The `agent-reach install` command aborts with errors like "gh CLI not found" or "Node.js not found".

Agent-Reach requires **GitHub CLI** (`gh`) and **Node.js** to be present on `$PATH` before installing optional channels. The installer calls `_install_system_deps` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 10-66) to verify these prerequisites using `shutil.which("gh")` and `shutil.which("node")`.

**Fix:**

```bash

# Debian/Ubuntu

sudo apt-get install gh nodejs npm

# macOS

brew install gh node

```

If you prefer to audit dependencies without installing them, use **safe mode** (`--safe`), which invokes `_install_system_deps_safe` (lines 44-71) to display missing components without making changes.

### Optional Channel Installers Fail

*Symptoms*: Running `agent-reach install --channels=twitter` ends with "[!] twitter-cli install failed".

Optional channels require a Python tool manager. The `_install_twitter_deps` function (lines 71-100 of [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py)) attempts installation via `pipx` first, then falls back to `uv`. If neither is present, the installation fails.

**Fix:**

```bash

# Install pipx

pip install pipx

# Or install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

# Then re-run

agent-reach install --channels=twitter

```

### Docker-Dependent Channels Not Running

*Symptoms*: Configuring Xiaohongshu cookies prints "xhs-mcp container is not running".

The `_configure_xhs_cookies` function (lines 64-73 of [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py)) checks for a running Docker container before proceeding.

**Fix:**

```bash
docker run -d --name xiaohongshu-mcp -p 18060:18060 xpzouying/xiaohongshu-mcp

```

Then re-run the `configure` command.

## Doctor and Health-Check Errors

### Config File Permission Warnings

*Symptoms*: `agent-reach doctor` displays a red warning about the config file being readable by other users ("config.yaml 权限过宽").

Agent-Reach enforces secure permissions on `~/.agent-reach/config.yaml`. The `doctor.format_report` method (lines 9-23 of [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py)) checks the file mode, while [`config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/config.py) (lines 18-20) defines the config directory path.

**Fix:**

```bash
chmod 600 ~/.agent-reach/config.yaml

```

### Channel Reports "error" Instead of "ok"

*Symptoms*: The doctor report shows a red `[X]` for a channel, and JSON output contains `"status": "error"`.

Each channel's `check(config)` method runs inside a `try/except` block within `doctor.check_all` (lines 18-28 of [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py)). Exceptions are captured in the `message` field.

**Debug steps:**

1. Run the doctor in JSON mode to see the raw error:

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

2. Inspect the `results[<name>]["message"]` field for the specific exception.

3. Test the upstream tool directly with stored credentials. For Twitter:

   ```bash
   TWITTER_AUTH_TOKEN=$(agent-reach config get twitter_auth_token) \
   TWITTER_CT0=$(agent-reach config get twitter_ct0) \
   twitter status
   ```

If the upstream CLI reports "authentication failed", re-extract cookies using `agent-reach configure --from-browser chrome` or update them manually via `agent-reach configure twitter-cookies`.

### No Active Backend Reported

*Symptoms*: The doctor shows no active backend for channels that support multiple implementations.

The active backend is stored in `ch.active_backend`. If detection fails, the value is `None`.

**Fix:**

Re-install the backend and verify it is on `$PATH`:

```bash

# Re-install OpenCLI backend

agent-reach install --backends=opencli

# Verify

which opencli

```

## Configuration Problems

### Missing Keys for Optional Features

*Symptoms*: `agent-reach doctor` reports a yellow "[!]" for tier-1 channels like Exa search or Groq Whisper.

The `Config.is_configured` method (lines 90-94 of [`config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/config.py)) returns `False` when required keys defined in `FEATURE_REQUIREMENTS` (lines 22-28) are absent.

**Fix:**

```bash

# For Exa (installs mcporter, no key needed)

agent-reach install --channels=exasearch

# For Groq Whisper

agent-reach configure groq-key <your-groq-key>

```

### Proxy Settings Not Respected

*Symptoms*: Calls to Reddit or Twitter time out behind a corporate firewall.

Proxy configuration is stored under both `proxy` and legacy `bilibili_proxy` keys via `_cmd_configure` (lines 40-47 of [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py)). However, the CLI does not automatically export environment variables; agents must set them.

**Fix:**

```bash
agent-reach configure proxy http://user:pass@proxy.example.com:8080

# Export before running upstream tools

export HTTP_PROXY=$(agent-reach config get proxy)
export HTTPS_PROXY=$HTTP_PROXY

```

## Environment and Skill Issues

### Local vs. Server Mis-Detection

*Symptoms*: The installer skips OpenCLI on a desktop machine, assuming a server environment.

The `_detect_environment` function (lines 55-94 of [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py)) tallies SSH sessions, containers, display servers, and cloud VM indicators to determine the environment type.

**Fix:**

Override auto-detection explicitly:

```bash
agent-reach install --env=local

# or

agent-reach install --env=server

```

### Skill Installation Failures

*Symptoms*: `agent-reach skill --install` prints "Could not install skill".

The `_install_skill` function builds target paths from a prioritized list of skill directories (lines 12-18) and handles permission errors (lines 29-40).

**Fix:**

Ensure the skill directory exists and has write permissions:

```bash
mkdir -p ~/.agents/skills
agent-reach skill --install -v

```

## Step-by-Step Debugging Workflow

Use this sequence to systematically resolve issues:

1. **Identify failing channels:**

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

2. **Inspect the specific check implementation** for the failing channel (e.g., [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py)).

3. **Verify upstream binary availability:**

   ```bash
   which twitter   # or youtube-dlp, rdt, etc.

   ```

4. **Test with stored credentials** to isolate Agent-Reach from upstream issues.

5. **Refresh stale cookies** if authentication fails:

   ```bash
   agent-reach configure --from-browser chrome
   ```

6. **Confirm resolution:**

   ```bash
   agent-reach doctor
   ```

## Summary

- **System dependencies**: Ensure `gh` and `node` are on `$PATH` before running `agent-reach install`.
- **File permissions**: Set `~/.agent-reach/config.yaml` to mode `600` to avoid security warnings.
- **Tool managers**: Install `pipx` or `uv` before adding optional channels like Twitter.
- **JSON diagnostics**: Use `agent-reach doctor --json` to view raw exception messages from channel checks.
- **Proxy configuration**: Store the proxy with `configure proxy`, but manually export `HTTP_PROXY` and `HTTPS_PROXY` before calling upstream CLIs.
- **Environment override**: Use `--env=local` or `--env=server` if auto-detection fails.

## Frequently Asked Questions

### Why does `agent-reach doctor` report "config.yaml 权限过宽"?

This warning appears when the configuration file at `~/.agent-reach/config.yaml` has permissions broader than owner-only read/write. The `doctor.format_report` method checks file modes and flags any setting more permissive than `600`. Run `chmod 600 ~/.agent-reach/config.yaml` to resolve this security warning.

### How do I fix "twitter-cli install failed" errors?

This error occurs when the installer cannot find a Python tool manager to install the Twitter CLI. The `_install_twitter_deps` function requires either `pipx` or `uv` to be installed on your system. Install one of these tools, ensure they are on your `$PATH`, then re-run the install command with `--channels=twitter`.

### Why is my proxy configuration being ignored?

Agent-Reach stores proxy settings in the config file via `_cmd_configure`, but it does not automatically export `HTTP_PROXY` or `HTTPS_PROXY` environment variables for upstream tools. You must manually export these variables using `export HTTP_PROXY=$(agent-reach config get proxy)` before invoking any channel commands that require network access.

### How can I override automatic environment detection?

The `_detect_environment` function in [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py) uses heuristics like SSH sessions and display availability to guess if you are on a local desktop or remote server. If this detection is incorrect (e.g., skipping OpenCLI installation on a desktop), explicitly pass `--env=local` or `--env=server` to the `agent-reach install` command to force the correct behavior.