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

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 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 (lines 10-66) to verify these prerequisites using shutil.which("gh") and shutil.which("node").

Fix:

# 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) attempts installation via pipx first, then falls back to uv. If neither is present, the installation fails.

Fix:

# 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) checks for a running Docker container before proceeding.

Fix:

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) checks the file mode, while config.py (lines 18-20) defines the config directory path.

Fix:

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). Exceptions are captured in the message field.

Debug steps:

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

   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:

   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:

# 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) returns False when required keys defined in FEATURE_REQUIREMENTS (lines 22-28) are absent.

Fix:

# 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). However, the CLI does not automatically export environment variables; agents must set them.

Fix:

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) tallies SSH sessions, containers, display servers, and cloud VM indicators to determine the environment type.

Fix:

Override auto-detection explicitly:

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:

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:

   agent-reach doctor --json | jq .

2. Inspect the specific check implementation for the failing channel (e.g., agent_reach/channels/twitter.py).

3. Verify upstream binary availability:

   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:

   agent-reach configure --from-browser chrome

6. Confirm resolution:

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

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