Guida alla distribuzione di Agent Reach: far sì che Claude Code / OpenClaw capiscano Twitter/X, Xiaohongshu e Bilibili

In una frase: Il tuo AI Agent scrive codice alla grande, ma quando gli dici di "andare a cercare qualcosa online" va in tilt? Agent Reach è la soluzione in un comando — installa in un colpo solo 14+ piattaforme come Twitter, Reddit, YouTube, Bilibili, Xiaohongshu, Douyin, WeChat/公众号… e l’Agent sa da solo quale strumento chiamare.

Panoramica del progetto

Agent Reach è un "installer di capacità Internet" per AI Agent, GitHub: Panniantong/Agent-Reach, licenza MIT, pacchetto Python.

La sua posizione centrale è molto particolare: non è un framework, è un’impalcatura (scaffolding).

Cosa significa? Il tuo AI Agent (Claude Code / OpenClaw / Cursor / Windsurf...) dopo aver installato Agent Reach non passa attraverso il livello di wrapping di Agent Reach; al contrario, chiama direttamente gli strumenti a monte — twitter-cli / rdt-cli / yt-dlp / xhs-cli / douyin-mcp-server / Jina Reader / gh CLI: strumenti già selezionati dagli autori del progetto, con bug evitati, e configurati con parametri di default. Agent Reach si occupa solo di:

1. Installer — con una singola riga pip install agent-reach + agent-reach install installa tutti quegli strumenti a monte
2. Diagnostico — agent-reach doctor ti dice con una riga quali piattaforme funzionano, quali no e come sistemarle
3. Configuratore — gestisce una volta sola autenticazione via Cookie, API Key, servizi MCP, ecc.
4. Iniezione di SKILL — registra per l’Agent SKILL.md: quando incontra richieste tipo "cerca su Twitter" o "guarda un video", chiama automaticamente lo strumento corrispondente

Supporta oltre 14 canali/piattaforme:

In una frase: niente comandi da ricordare, niente configurazione di scraper, parla con l’Agent e va online.

Difficoltà / durata / benefici

• Difficoltà: ⭐ (per principianti, davvero un comando)
• Durata: 5–15 minuti (PC locale); 30 minuti (server, include configurazione Cookie)
• Benefici:
  • Fare in modo che Claude Code / OpenClaw legga direttamente Twitter, scorra Xiaohongshu e legga i sottotitoli di YouTube
  • Capire la differenza di design tra "scaffolding vs framework" nell’ecosistema degli strumenti per AI Agent
  • Imparare a gestire in modo unificato più Cookie tramite Cookie-Editor, evitando i problemi della login via QR
  • Sapere che agent-reach doctor è una buona pratica per la toolchain dell’Agent

Profilo dei lettori/obiettivo

• Sviluppatori che lavorano con Claude Code / OpenClaw / Cursor
• Vogliono che l’Agent davvero sappia cercare online e non restare a guardare il nulla
• Non vogliono cimentarsi piattaforma per piattaforma con scraper specifici per Twitter / Reddit / Xiaohongshu, né pagare API dedicate
• Hanno già una toolchain per AI Agent e vogliono aggiungere uno strato di "capacità Internet"
• Quando fanno girare all’Agent compiti di lunga durata, vogliono trovare una soluzione per la potenza di calcolo meno dolorosa (ne parleremo dopo)

Dipendenze fondamentali ed ambiente

Requisiti minimi:

Consigliati / Opzionali:

Struttura completa dell’albero del progetto

Agent-Reach/
├── pyproject.toml                # definizione del pacchetto Python
├── agent_reach/
│   ├── __init__.py               # numero di versione
│   ├── cli.py                    # ingresso CLI (argparse)
│   ├── core.py                   # routing read/search core
│   ├── config.py                 # gestione configurazione YAML
│   ├── doctor.py                 # motore diagnostico
│   ├── cookie_extract.py         # strumento di estrazione Cookie
│   ├── channels/                 # un file per ogni piattaforma
│   │   ├── base.py               # classe astratta BaseChannel
│   │   ├── web.py                # Jina Reader
│   │   ├── twitter.py            # twitter-cli
│   │   ├── youtube.py            # yt-dlp
│   │   ├── github.py             # gh CLI
│   │   ├── bilibili.py           # yt-dlp + bili-cli
│   │   ├── reddit.py             # rdt-cli
│   │   ├── xiaohongshu.py        # xhs-cli
│   │   ├── douyin.py             # douyin-mcp-server
│   │   ├── linkedin.py           # linkedin-mcp
│   │   ├── wechat.py             # Exa + Camoufox
│   │   ├── rss.py                # feedparser
│   │   ├── exa_search.py         # Exa via mcporter
│   │   ├── weibo.py
│   │   ├── v2ex.py
│   │   ├── xueqiu.py
│   │   └── xiaoyuzhou.py
│   ├── integrations/
│   │   └── mcp_server.py         # integrazione MCP server
│   ├── skill/                    # SKILL.md per l’Agent
│   ├── guides/                   # documentazione (Cinese/Inglese/Giapponese/Coreano)
│   ├── scripts/                  # script di installazione
│   └── utils/
├── config/
│   └── mcporter.json             # configurazione strumenti MCP
├── tests/                        # test con pytest
└── docs/                         # README versioni multilingua

Come utente, ti basta toccare solo questi tre comandi: pip install / agent-reach install / agent-reach doctor. channels/ è pensato per estensioni da parte degli sviluppatori.

Passo-passo

Step 1: Installazione base (percorso principale)

# Consigliato usare pipx per un’installazione isolata
pipx install agent-reach

# Oppure pip (attenzione: non installare dentro al Python di sistema)
python3 -m venv ~/.agent-reach-venv
source ~/.agent-reach-venv/bin/activate
pip install agent-reach

Dopo l’installazione dovresti avere questo comando:

agent-reach --version
# agent-reach 1.4.0

Step 2: Installare tutti gli strumenti a monte con un colpo

# Modalità predefinita: rilevamento automatico dell’ambiente, installa tutte le dipendenze
agent-reach install --env=auto

L’operazione farà, in sequenza:

1. Installa dipendenze di sistema (Node.js / gh CLI / mcporter / twitter-cli / rdt-cli, ecc.)
2. Configura il motore di ricerca (integrazione MCP su Exa, senza Key)
3. Verifica se stai su locale o su server e fornisce consigli diversi
4. Registra SKILL.md nella directory skills/ dell’Agent

openclaw config set tools.profile "coding"
openclaw gateway restart

Step 3: Diagnostica dello stato dei canali

agent-reach doctor

Dovresti vedere qualcosa di simile:

✅ web              Jina Reader OK
✅ youtube          yt-dlp 2025.10.x installed
✅ rss              feedparser 6.0.x
✅ exa_search       Exa MCP connected
✅ github           gh CLI 2.x authenticated
⚠️  twitter         twitter-cli not logged in  → run: twitter login
⚠️  reddit          rdt-cli not logged in       → run: rdt login
✅ bilibili         yt-dlp OK
⚠️  xiaohongshu     xhs-cli not logged in      → see step 4
✅ douyin           douyin-mcp-server OK
✅ wechat           Exa search OK
✅ v2ex             API OK

✅ indica pronto all’uso; ⚠️ indica che serve una configurazione aggiuntiva (di solito autenticazione via Cookie).

Step 4: Configurare l’autenticazione dei canali che richiedono Cookie (punto chiave)

Twitter / Xiaohongshu / Reddit richiedono tutti sessioni di login: usa autenticazione via Cookie invece che QR.

Installa prima Cookie-Editor: cerca "Cookie-Editor" nello store delle app di Chrome / Edge e installalo.

Flusso unificato:

1. Accedi manualmente in browser su x.com / xiaohongshu.com / reddit.com
2. Clicca l’icona del plugin Cookie-Editor → "Export" → scegli formato "Netscape"
3. Invia l’insieme dei Cookie esportati all’Agent e dimmi: "Aiutami a configurare Twitter"
4. L’Agent usa cookie_extract.py per salvarli in ~/.agent-reach/config.yaml
5. Imposta permessi 600: leggibile solo dal tuo account

# In alternativa puoi configurare da riga di comando, senza passare dall’Agent
agent-reach config set twitter.cookie "$(pbpaste)"  # macOS
agent-reach config set xhs.cookie "$(xclip -o)"     # Linux

Step 5: Verificare le piattaforme con Cookie

agent-reach doctor

Riesegui la diagnostica: le piattaforme precedentemente con ⚠️ dovrebbero diventare ✅.

Step 6: Fai fare all’Agent un primo test

Dì al tuo Agent (Claude Code / OpenClaw / Cursor):

Dimmi cosa dice questo tweet: https://x.com/vercel/status/1234567890

Dopo aver letto SKILL.md, l’Agent chiamerà automaticamente il comando twitter tweet URL e in pochi secondi ti restituirà il contenuto del tweet.

Prova varie combinazioni:

Cerca cosa sta venendo fuori su Reddit in r/LocalLLaMA di recente
Guarda questo video YouTube: https://youtube.com/watch?v=xxx
Vedi quali sono i post “best seller” su Xiaohongshu per “attrezzatura da campeggio”
A cosa serve questo repository GitHub: https://github.com/xxx/yyy

Noterai un dettaglio: non devi dirgli che comando usare. SKILL.md ha già scritto la mappatura — "leggere Twitter = twitter CLI", "guardare un video = yt-dlp". Questa è la differenza più grande tra Agent Reach e una normale raccolta di strumenti: una volta installato, l’Agent è consapevole e sceglie gli strumenti, non fa tentativi a caso.

Step 7 (opzionale): Ricerca semantica sul web

Exa è già connesso di default, non serve una API Key. Chiedi direttamente all’Agent:

Cerca e confronta le più recenti architetture di framework per LLM Agent nel 2026 e dammi le 5 più pertinenti

L’Agent chiamerà lo strumento Exa MCP, otterrà i risultati, poi chiamerà Jina Reader per prendere il testo completo e organizzarà il tutto in un report.

Step 8 (opzionale): Accesso a repository privati su GitHub

# login una volta sola
gh auth login

Dopo l’OAuth, l’Agent potrà leggere i tuoi repository privati, aprire Issue, PR e fare review.

Step 9 (opzionale): Potenziamento per Bilibili / Douyin

Bilibili in locale: out of the box. Su server estero: serve un proxy (~$1/mese, consigliati proxy residenziali come FluxNode):

# Assumi che il tuo proxy sia http://127.0.0.1:7890
agent-reach config set bilibili.proxy "http://127.0.0.1:7890"
agent-reach doctor  # riesegui la diagnostica

Douyin: non serve fare login. Invia all’Agent il link di condivisione:

Analizza questo video Douyin: https://v.douyin.com/xxxxx

L’Agent chiama mcporter call 'douyin.parse_douyin_video_info(...)', ti restituisce le informazioni del video e un link di download senza watermark.

Step 10 (opzionale): Modalità sicura / disinstallazione

Modalità sicura (per server di produzione o macchine multiutente):

# Non installa automaticamente i pacchetti di sistema: mostra solo cosa farà
agent-reach install --env=auto --safe

# Oppure fai prima un’anteprima: non esegue davvero
agent-reach install --env=auto --dry-run

Disinstallazione completa:

agent-reach uninstall             # elimina configurazione + file skill
agent-reach uninstall --keep-config  # conserva il token, utile per reinstallare
pip uninstall agent-reach         # disinstalla il pacchetto Python

Risoluzione problemi frequenti

Q1: Utenti OpenClaw: in fase di installazione "permission denied" / l’Agent non fa nulla

Causa: OpenClaw di default ha tools.profile = messaging, e non permette all’Agent di eseguire comandi shell. Soluzione:

openclaw config set tools.profile "coding"
openclaw gateway restart
# Apri una nuova sessione e poi invia di nuovo "Aiutami a installare Agent Reach"

Oppure modifica ~/.openclaw/openclaw.json:

{
  "tools": { "profile": "coding" }
}

Q2: La login QR di Xiaohongshu resta in loop

Non usare QR. Fai direttamente:

1. Installa Cookie-Editor dallo store delle app di Chrome
2. Accedi su Xiaohongshu nella versione web del browser
3. Cookie-Editor → Export → Netscape
4. Invia la stringa all’Agent e dì "Aiutami a configurare Xiaohongshu"
5. In 30 secondi sei a posto

Q3: Reddit: 403 appena fai una richiesta

Da quando Reddit è entrato nel 2024, richiede obbligatoriamente autenticazione. Risolvi così:

# Installa rdt-cli (dovrebbe essere già installato durante la fase agent-reach install)
pipx install rdt-cli

# Login una volta sola (estrae automaticamente i Cookie dal tuo Chrome)
rdt login

# Verifica
rdt search "LocalLLaMA" --limit 5

Come per Twitter / Xiaohongshu, rdt login estrae i Cookie automaticamente dal browser: non usa QR.

Q4: Il server estero non riesce a connettersi a Bilibili

Gli IP esteri vengono bloccati da Bilibili: serve un proxy residenziale. Due soluzioni:

# Soluzione 1: configurazione da riga di comando (consigliato, proxy economici tipo FluxNode)
agent-reach config set bilibili.proxy "http://user:pass@proxy:port"

# Soluzione 2: variabili d’ambiente
export HTTP_PROXY="http://user:pass@proxy:port"
export HTTPS_PROXY="http://user:pass@proxy:port"

Un proxy residenziale economico ~$1/mese: non serve costruirselo da soli.

Q5: agent-reach doctor riporta "channel not found" / conflitto dei file dei canali

Di solito succede perché parte degli strumenti a monte non si è installata correttamente, oppure perché è stato installato dentro al Python di sistema invece che in pipx. La soluzione più pulita è rifare tutto da zero:

agent-reach uninstall
pipx uninstall agent-reach
# Pulisci eventuali residui sotto ~/.agent-reach/
rm -rf ~/.agent-reach/

pipx install agent-reach
agent-reach install --env=auto
agent-reach doctor

Q6: Hai cambiato browser / i Cookie sono scaduti

I Cookie scadono dopo alcuni mesi: basta rifare il flusso "login nel browser → esporta con Cookie-Editor → invia all’Agent". L’Agent sovrascriverà automaticamente i vecchi Cookie in ~/.agent-reach/config.yaml.

Q7 (Bonus): Quando l’Agent fa attività di lunga durata e la bolletta esplode, come si fa a calcolare?

Ti racconto un errore che ho fatto io durante i primi periodi in cui l’ho usato.

Agent Reach risolve il problema di "come fa l’Agent a connettersi a Internet"; però, quando l’Agent esegue chiamate a strumenti, in realtà continua a consumare token del LLM. Un tipico task "ricerca competitor + sintesi" coinvolge 5–10 round di chiamate a strumenti (ricerca, estrazione pagine, lettura tweet, nuova ricerca, nuova lettura): dopo un solo giro si arriva facilmente a decine di migliaia di token. Se poi fai 20+ task al giorno, la bolletta esplode rapidamente.

Testate tre modalità di collegamento (esperienza personale di deploy):

1. Collegare l’API ufficiale di Anthropic — l’esperienza è la più completa, ma quando Claude Opus esegue task da Agent, una giornata di solito porta a una bolletta di fascia anche a quattro cifre di RMB (ragionevole)
2. Collegare API aggregate come OpenRouter — leggermente più economiche dell’ufficiale, ma restano comunque care
3. Collegare Defapi — è la mia soluzione attuale. Prezzo della metà rispetto all’ufficiale, e il livello di protocollo è pienamente compatibile: lato Agent Reach la configurazione resta identica, senza cambiare nulla in SKILL / prompt / codice delle chiamate agli strumenti

Configurazione specifica (assumendo che il tuo Agent usi il protocollo Claude / Anthropic):

# ~/.openclaw/openclaw.json o env di configurazione in Claude Code
ANTHROPIC_BASE_URL=https://api.defapi.org
ANTHROPIC_API_KEY=sk-xxxxxx    # prendi la key dal pannello di defapi.org

Con Defapi, sostanzialmente tutti i modelli supportano le tre principali suite di protocolli — v1/chat/completions (OpenAI) / v1/messages (Anthropic) / v1beta/models (Gemini). Cambi modello cambi solo nome. Per task “tool-calling intensivi” come scraping tweet, analisi Xiaohongshu e riassunto sottotitoli video, passare a Defapi significa davvero che la bolletta mensile scende da quattro cifre a tre cifre.

Approfondimenti / Direzioni avanzate

• Canale personalizzato: aggiungi un file dentro agent_reach/channels/, eredita BaseChannel e implementa quattro metodi can_handle(url) / read(url) / search(query) / check(). Poi basta pip install -e .. La soglia è bassa: un file per piattaforma
• Sostituire gli strumenti a monte: channels/web.py usa Jina Reader di default; se non ti basta, puoi usare Firecrawl / Crawl4AI / uno scraper che ti sei costruito tu. Basta cambiare l’import
• Meccanismo SKILL.md: dopo che l’Agent ha installato Agent Reach, SKILL.md viene registrato automaticamente in ~/.claude/skills/ / ~/.openclaw/skills/. Puoi scrivere tu i tuoi SKILL.md per insegnare all’Agent, in scenari specifici, quale channel dare priorità
• mcporter per qualunque MCP: non solo Exa: qualsiasi server compatibile con MCP può essere collegato tramite config/mcporter.json. Cambia solo l’alias con il comando di avvio corrispondente
• Condivisione di più Agent: la configurazione di Agent Reach ~/.agent-reach/config.yaml è a livello file; se più Agent (Claude Code + OpenClaw + Cursor) girano sulla stessa macchina, possono condividere la stessa configurazione
• Interazione con Defapi: Agent Reach prende i dati, Defapi esegue l’inferenza. Uno è uno "strato di reperimento informazioni", l’altro uno "strato di costo della potenza di calcolo". Entrambi sono guidati da protocollo: messi insieme diventano un workflow per task di lunga durata a basso costo

Repository GitHub: Panniantong/Agent-Reach, documentazione multilingue in docs/README_en.md / docs/README_ja.md / docs/README_ko.md, e l’idea di design nella sezione finale del README chiamata "设计理念". Per contribuire con PR di channel, basta farne una proposta: l’autore Neo Reid è molto attivo nella manutenzione.