How to Troubleshoot Twitter Authentication Failures (auth_token/ct0) in Agent Reach

Agent Reach authenticates to X/Twitter via the twitter-cli backend using only two browser cookies—auth_token and ct0—and surfaces a "not_authenticated" warning when these values are missing, expired, or invalid.

Agent Reach is an open-source automation framework that retrieves tweets through the twitter-cli backend. When you encounter authentication failures, the root cause is almost always missing or invalid cookie values. This guide walks through the exact failure detection logic in agent_reach/channels/twitter.py and provides step-by-step remediation based on the official Panniantong/Agent-Reach source code.

How Authentication Works in Agent Reach

The twitter-cli Backend

Agent Reach delegates Twitter/X API calls to the external twitter-cli tool. Unlike OAuth flows, this backend requires only two cookies copied from an authenticated browser session: auth_token and ct0. These cookies identify your session to X.com without requiring API keys.

The Authentication Check Logic

In agent_reach/channels/twitter.py, the TwitterChannel.check() method probes the backend by running twitter status. If the output contains the string "not_authenticated", the method returns a warning status with instructions to set the environment variables.

if "not_authenticated" in output:
    return "warn", (
        "twitter-cli 已安装但未认证。设置方式：\n"
        "  export TWITTER_AUTH_TOKEN=\"xxx\"\n"
        "  export TWITTER_CT0=\"yyy\"\n"
        "或确保已在浏览器中登录 x.com"
    )

This probe runs through the probe_command wrapper in agent_reach/probe.py, which returns a ProbeResult with statuses ok, warn, or error.

Common Failure Patterns

Authentication failures manifest in specific ways. Here are the root causes:

• Missing credentials: The AUTH_TOKEN and CT0 environment variables are unset or empty.
• Expired cookies: The auth_token cookie has expired or the session was logged out remotely.
• Account mismatch: The cookies belong to a different X account than intended.
• Network blockage: The twitter-cli cannot reach x.com due to firewalls or regional blocks.

Step-by-Step Troubleshooting Guide

1. Verify Backend Installation

Confirm that twitter-cli is installed and accessible in your PATH before checking credentials.

which twitter
agent-reach doctor --json

The doctor command should list the twitter channel as ok if the binary is present, or warn if the authentication cookies are missing.

2. Export Cookie Environment Variables

Extract auth_token and ct0 from your browser's cookies for x.com using the Cookie-Editor extension or DevTools. Export them as environment variables:

export AUTH_TOKEN="your_auth_token"
export CT0="your_ct0"

Alternatively, use the built-in configurator to parse a JSON cookie string:

agent-reach configure twitter-cookies "PASTE_COOKIE_JSON"

The configurator automatically extracts auth_token and ct0 from the JSON and sets the variables for you.

3. Validate Credentials

Test the authentication by running:

twitter status

You should see ok: true. If you still see not_authenticated, verify you copied the cookies from an active, logged-in session on x.com and that they have not expired.

4. Configure Proxy Settings (if needed)

If you are behind a firewall or in a region that blocks x.com, configure proxy variables that twitter-cli respects:

export HTTP_PROXY="http://user:pass@host:port"
export HTTPS_PROXY="http://user:pass@host:port"
twitter search "test" -n 1

5. Enable Fallback Backends

If twitter-cli remains unusable, Agent Reach automatically falls back to the bird CLI (if installed) or an Exa-based web search. This logic resides in TwitterChannel._check_bird() and the main check() method in agent_reach/channels/twitter.py (lines 10-15 and 43-48).

Quick Diagnostic Checklist

Run these commands in order to isolate the issue:

1. Verify backend: agent-reach doctor --json should show "twitter" as ok.
2. Check env vars: echo $AUTH_TOKEN $CT0 should output non-empty strings.
3. Probe status: twitter status should return ok: true.
4. Test query: twitter search "openai" -n 1 should return JSON results.
5. Proxy test: If steps 3-4 fail, set HTTP_PROXY and HTTPS_PROXY, then retry.

Summary

• Agent Reach uses twitter-cli which requires only auth_token and ct0 cookies.
• Authentication failures are detected in TwitterChannel.check() when twitter status returns "not_authenticated".
• Remediation involves setting AUTH_TOKEN and CT0 environment variables or using agent-reach configure twitter-cookies.
• Network restrictions require HTTP_PROXY and HTTPS_PROXY configuration.
• Fallback to bird CLI or Exa search occurs automatically if the primary backend fails.

Frequently Asked Questions

What are auth_token and ct0 cookies?

auth_token is the session token proving you are logged into X/Twitter, while ct0 is a Cross-Site Request Forgery (CSRF) token required for API actions. Together, they allow twitter-cli to perform searches and fetch timelines without OAuth credentials.

Why does Agent Reach show "not_authenticated" even after setting env vars?

Ensure the variable names match exactly what twitter-cli expects (AUTH_TOKEN and CT0). Also verify the cookies are fresh and copied from an active browser session on x.com. Expired or revoked sessions will return this error until you refresh the cookies.

Can I use Twitter without twitter-cli?

Yes. If twitter-cli is unavailable or authentication fails, Agent Reach automatically falls back to the bird CLI backend or an Exa-based web search provider. This fallback logic is defined in agent_reach/channels/twitter.py in the _check_bird() method.

How do I extract cookies from my browser?

Install the Cookie-Editor browser extension, navigate to x.com, and export the cookies as JSON. Look for the auth_token and ct0 values, then either set them as environment variables or pass the entire JSON string to agent-reach configure twitter-cookies.

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