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

> Fix Twitter authentication failures in Agent Reach by troubleshooting auth_token and ct0 cookies. Resolve not_authenticated errors and get X/Twitter working again.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.

```bash
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:

```bash
export AUTH_TOKEN="your_auth_token"
export CT0="your_ct0"

```

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

```bash
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:

```bash
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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`.