> **No token or crypto affiliation:** Agent Reach has no official token, coin, investment product, fee-claim program, wallet connection, or Solana/Pump.fun project. Any crypto project using the Agent Reach name, GitHub URL, or author identity is not affiliated with this repository. Do not connect a wallet or claim fees based on messages, posts, or links that say otherwise.
---
## ❤️ Sponsors
> [Want to appear here?](mailto:pnt01@foxmail.com)
Click to collapse
BrowserAct extracts any data you need from complex websites such as Amazon, LinkedIn, X, and Google Maps. Simply describe your extraction request in natural language, and its Agent will explore and test page flows in a real browser, generate a reliable reusable data-collection Bot, and return structured results. There is no need to build a scraper or write code. Built-in stealth browsing, CAPTCHA handling, and high-quality residential proxies help make complex web data extraction more reliable. New users receive 1,000 credits upon registration. Try it free now.
Deploy OpenClaw on Tencent Cloud Lighthouse in seconds, connect Agent Reach through chat, and add internet access to your OpenClaw setup.
CoreClaw | Web scraping platform and ready-made data collection tools. CoreClaw provides 100+ ready-made data collection tools for Amazon, TikTok, Google Maps, Instagram, Facebook, YouTube, and more. No code required, with JSON/CSV exports and billing only for successful results. Free $3 trial!
AstraFlow ModelVerse provides one-click access to 200+ models, including leading open-source models such as Kimi K3, DeepSeek V4/V3, Qwen 3, GLM5.2, and happyhorse. No training required—ready to use out of the box.
---
## Why Agent Reach?
AI Agents can already access the internet — but "can go online" is barely the start.
The most valuable information lives across social and niche platforms: Twitter discussions, Reddit feedback, YouTube tutorials, XiaoHongShu reviews, Bilibili videos, GitHub activity… **These are where information density is highest**, but each platform has its own barriers:
| Pain Point | Reality |
|------------|---------|
| Twitter API | Pay-per-use, moderate usage ~$215/month |
| Reddit | Server IPs get 403'd |
| XiaoHongShu | Login required to browse |
| Bilibili | Blocks overseas/server IPs |
To connect your Agent to these platforms, you'd have to find tools, install dependencies, and debug configs — one by one.
**Agent Reach turns this into one command:**
```
Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
```
Copy that to your Agent. A few minutes later, it can read tweets, search Reddit, and watch Bilibili.
**Already installed? Update in one command:**
```
Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
```
### ✅ Before you start, you might want to know
| | |
|---|---|
| 💰 **Completely free** | All tools are open source, all APIs are free. The only possible cost is a server proxy ($1/month) — local computers don't need one |
| 🔒 **Privacy safe** | Cookies stay local. Never uploaded. Fully open source — audit anytime |
| 🔄 **Kept up to date** | Every platform routes through a primary + fallback backend list. When an access path dies, we switch to the next — you won't notice (June 2026: Bilibili 412-blocked yt-dlp → switched to bili-cli, zero action on your side) |
| 🤖 **Works with any Agent** | Claude Code, OpenClaw, Cursor, Windsurf… any Agent that can run commands |
| 🩺 **Built-in diagnostics** | `agent-reach doctor` — one command shows what works, what doesn't, and how to fix it |
---
## Supported Platforms
| Platform | Capabilities | Setup | Notes |
|----------|-------------|:-----:|-------|
| 🌐 **Web** | Read | Zero config | Any URL → clean Markdown ([Jina Reader](https://github.com/jina-ai/reader) ⭐9.8K) |
| 🐦 **Twitter/X** | Read · Search | Cookie | Cookie unlocks search, timeline, tweet reading, articles ([twitter-cli](https://github.com/public-clis/twitter-cli)) |
| 📕 **XiaoHongShu** | Read · Search · Comments | OpenCLI / MCP | OpenCLI uses only an existing user-controlled Chrome session; MCP/legacy tools use a manual Cookie-Editor export |
| 📘 **Facebook** | Search · Profiles · Feed · Groups list | OpenCLI | Desktop only: [OpenCLI](https://github.com/jackwener/opencli) reuses your logged-in Chrome session |
| 📷 **Instagram** | User search · Profiles · Recent posts · Explore | OpenCLI | Desktop only: [OpenCLI](https://github.com/jackwener/opencli) reuses your logged-in Chrome session |
| 💼 **LinkedIn** | Jina Reader (public pages) | Full profiles, companies, job search | Tell your Agent "help me set up LinkedIn" |
| 💻 **V2EX** | Hot topics · Node topics · Topic detail + replies · User profile | Zero config | Public JSON API, no auth required. Great for tech community content |
| 📈 **Xueqiu (雪球)** | Stock quotes · Search · Hot posts · Hot stocks | Browser cookie | Tell your Agent "help me set up Xueqiu" |
| 🎙️ **Xiaoyuzhou Podcast** | Transcription | Free API key | Podcast audio → full text transcript via Groq Whisper (free) |
| 🔍 **Web Search** | Search | Auto-configured | Auto-configured during install, free, no API key ([Exa](https://exa.ai) via [mcporter](https://github.com/nicepkg/mcporter)) |
| 📦 **GitHub** | Read · Search | Zero config | [gh CLI](https://cli.github.com) powered. Public repos work immediately. `gh auth login` unlocks Fork, Issue, PR |
| 📺 **YouTube** | Read · **Search** | Zero config | Subtitles + search across 1800+ video sites ([yt-dlp](https://github.com/yt-dlp/yt-dlp) ⭐148K) |
| 📺 **Bilibili** | Read · **Search** | Zero config | Search + video detail via [bili-cli](https://github.com/public-clis/bilibili-cli) (no login needed); subtitles via [OpenCLI](https://github.com/jackwener/opencli). yt-dlp is 412-blocked by Bilibili and no longer used here |
| 📡 **RSS** | Read | Zero config | Any RSS/Atom feed ([feedparser](https://github.com/kurtmckee/feedparser) ⭐2.3K) |
| 📖 **Reddit** | Search · Read | OpenCLI / Cookie | No zero-config path (anonymous endpoints blocked). Desktop: [OpenCLI](https://github.com/jackwener/opencli) via browser session; or [rdt-cli](https://github.com/public-clis/rdt-cli) + cookie |
> **Setup levels:** Zero config = install and go · Auto-configured = handled during install · mcporter = needs MCP service · Cookie = export from browser · Proxy = $1/month
---
## Quick Start
> ⚠️ **OpenClaw users: enable `exec` permission first**
>
> Agent Reach relies on the Agent running shell commands (`pip install`, `mcporter`, `twitter`, etc.). If your OpenClaw uses the default `messaging` tool profile, the Agent won't be able to run them. **Enable `exec` before installing:**
>
> ```bash
> openclaw config set tools.profile "coding"
> ```
> Or set `"tools": { "profile": "coding" }` in `~/.openclaw/openclaw.json`. After changing it, restart the Gateway (`openclaw gateway restart`) and start a new conversation. Other platforms (Claude Code, Cursor, Windsurf, etc.) are not affected.
Copy this to your AI Agent (Claude Code, OpenClaw, Cursor, etc.):
```
Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
```
The Agent installs the Python package, checks your environment, and tells you what's ready. System-level changes require an explicit `--system` flag.
> 🔄 **Already installed?** Update in one command:
> ```
> Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
> ```
> 🛡️ **Safe by default:** `agent-reach install` checks the machine without installing system packages or writing configuration:
> ```
> Safely check and install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
> ```
> Use `agent-reach install --system` only after explicitly approving system changes.
Manual install
```bash
pip install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto
```
Install as a Skill (Claude Code / OpenClaw / any agent with Skills support)
```bash
npx skills add Panniantong/Agent-Reach@agent-reach
```
After the Skill is installed, the Agent will auto-detect whether `agent-reach` CLI is available and install it if needed.
> If you explicitly install external tools with `agent-reach install --system`, the skill is registered automatically. The default read-only check leaves existing files unchanged.
>
> Prefer an English-only skill file? Set an English locale or export `AGENT_REACH_LANG=en`
> before running `agent-reach install --env=auto --system` or `agent-reach skill --install`.
> The installed file is always written as `SKILL.md`, so switching languages means rerunning
> the install command with the new locale and replacing the previously installed skill file.
---
## Works Out of the Box
No configuration needed — just tell your Agent:
- "Read this link" → `curl https://r.jina.ai/URL` for any web page
- "What's this GitHub repo about?" → `gh repo view owner/repo`
- "What does this video cover?" → `yt-dlp --dump-json URL` for subtitles
- "Read this tweet" → set `TWITTER_AUTH_TOKEN` / `TWITTER_CT0`, then run `twitter tweet URL`
- "Subscribe to this RSS" → `feedparser` to parse feeds
- "Search GitHub for LLM frameworks" → `gh search repos "LLM framework"`
**No commands to remember.** The Agent reads SKILL.md and knows what to call.
---
## Unlock on Demand
Don't use it? Don't configure it. Every step is optional.
### 🍪 Cookies — Free, 2 minutes
Tell your Agent "help me configure Twitter cookies" — it'll guide you through a
manual Cookie-Editor export. Agent Reach saves the values for `doctor` to check
whether credentials are present; `doctor` does not run `twitter status`.
Direct `twitter` commands still require `TWITTER_AUTH_TOKEN` and `TWITTER_CT0`
in their process environment.
For XiaoHongShu, Agent Reach never logs the user in or reads browser cookies.
OpenCLI may use only an existing Chrome session explicitly controlled by the
user. If none exists, do not automate login; use a manual Cookie-Editor export
with xiaohongshu-mcp or a legacy tool. `agent-reach configure xhs-cookies`
does not inject cookies into OpenCLI or Chrome.
### 🌐 Proxy — $1/month, restricted networks only
Most users need no proxy. If your network blocks Reddit/Twitter (e.g. mainland China) get one ([Webshare](https://webshare.io) recommended, $1/month) and send the address to your Agent — it saves it and exports HTTP(S)_PROXY when calling those tools.
> Reddit needs a logged-in session either way — OpenCLI rides your browser session, or rdt-cli after `rdt login`. Bilibili works via bili-cli without a proxy.
---
## Status at a Glance
```
$ agent-reach doctor
👁️ Agent Reach Status
========================================
✅ Ready to use:
✅ GitHub repos and code — public repos readable and searchable
✅ YouTube video subtitles — yt-dlp
✅ Bilibili search & video detail — bili-cli (subtitles via OpenCLI)
✅ RSS/Atom feeds — feedparser
✅ Web pages (any URL) — Jina Reader API
🔍 Search (free Exa key to unlock):
⬜ Web semantic search — sign up at exa.ai for free key
🔧 Configurable:
⚠️ Twitter/X — doctor checks only that explicit credentials exist; direct CLI still needs its environment variables
⬜ Reddit posts and comments — needs login: rdt-cli after `rdt login`, or OpenCLI browser session
⬜ XiaoHongShu notes — OpenCLI needs an existing user-controlled session; otherwise use Cookie-Editor with MCP/legacy tools
⬜ Facebook / Instagram — desktop: OpenCLI browser session
Status: 6/9 channels available
```
---
## Design Philosophy
**Agent Reach is a capability layer, not yet another tool.**
It sits one level above any specific implementation — it handles **selection, installation, health checks, and routing**, not the reading itself. Reading is done by your Agent calling upstream tools directly; there is no wrapper layer.
Every time you spin up a new Agent, you spend time finding tools, installing deps, and debugging configs — what reads Twitter? How do you log into Reddit? What replaces a discontinued XiaoHongShu CLI? Every time, you re-do the same work. Agent Reach does one simple thing: **the most reliable access path for each platform, chosen, installed, and health-checked for you. Access paths come and go (in March 2026 a batch of single-platform CLIs went unmaintained — we re-routed), so you don't have to care.**
### 🔌 Every platform = an ordered backend list (primary + fallbacks)
Switching access paths means reordering the list, not rewriting code. `agent-reach doctor` tells you **which backend each platform is currently using**.
```
channels/
├── web.py → Jina Reader
├── twitter.py → twitter-cli ▸ OpenCLI ▸ bird
├── youtube.py → yt-dlp
├── github.py → gh CLI
├── bilibili.py → bili-cli ▸ OpenCLI ▸ search API (yt-dlp retired, 412-blocked)
├── reddit.py → OpenCLI ▸ rdt-cli (no zero-config path, login required)
├── facebook.py → OpenCLI (desktop browser session)
├── instagram.py → OpenCLI (desktop browser session)
├── xiaohongshu.py → OpenCLI ▸ xiaohongshu-mcp ▸ xhs-cli
├── linkedin.py → linkedin-mcp ▸ Jina Reader
├── rss.py → feedparser
├── exa_search.py → Exa via mcporter
└── __init__.py → Channel registry (for doctor checks)
```
Each channel file **actually probes** its candidate backends in order (not just checking that a command exists) — the first fully working one becomes the active backend, and broken ones come with a fix prescription. The actual reading and searching is done by the Agent calling the upstream tools directly.
### Current Tool Choices
| Scenario | Primary | Fallback | Why |
|----------|---------|----------|-----|
| Read web pages | [Jina Reader](https://github.com/jina-ai/reader) | — | Free, no API key needed |
| Read tweets | [twitter-cli](https://github.com/public-clis/twitter-cli) | [OpenCLI](https://github.com/jackwener/opencli) | Reliable search in real-world tests; OpenCLI falls back on your browser session |
| Reddit | [OpenCLI](https://github.com/jackwener/opencli) (desktop) | [rdt-cli](https://github.com/public-clis/rdt-cli) | Anonymous endpoints blocked, official API gated — logged-in sessions are the only route left |
| Facebook | [OpenCLI](https://github.com/jackwener/opencli) (desktop) | — | Graph/Groups API access is heavily restricted; browser sessions are the practical route |
| Instagram | [OpenCLI](https://github.com/jackwener/opencli) (desktop) | Official Graph API (Business/Creator + review) | Instaloader-style paths are unstable; OpenCLI reuses the real browser session |
| YouTube subtitles + search | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | — | 154K stars, still the best for YouTube (no longer used for Bilibili) |
| Bilibili | [bili-cli](https://github.com/public-clis/bilibili-cli) | OpenCLI ▸ search API | yt-dlp is 412-blocked by Bilibili (verified June 2026); bili-cli searches and reads without login |
| Search the web | [Exa](https://exa.ai) via [mcporter](https://github.com/nicobailon/mcporter) | — | AI semantic search, MCP integration, no API key |
| GitHub | [gh CLI](https://cli.github.com) | — | Official tool, full API after auth |
| Read RSS | [feedparser](https://github.com/kurtmckee/feedparser) | — | Python ecosystem standard |
| XiaoHongShu | [OpenCLI](https://github.com/jackwener/opencli) (desktop) | [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) (server) ▸ xhs-cli | OpenCLI uses only an existing user-controlled session; other backends use a manual Cookie-Editor export |
| LinkedIn | [mcp-server-linkedin](https://github.com/stickerdaniel/linkedin-mcp-server) | Jina Reader | MCP server, browser automation |
| Xiaoyuzhou Podcast | `transcribe.sh` | — | `bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh ` |
> 📌 These are the *current* choices, re-verified regularly on real machines. When a path dies we switch to the next — `agent-reach doctor` always tells you which one is active.
---
## Credits
[twitter-cli](https://github.com/public-clis/twitter-cli) · [rdt-cli](https://github.com/public-clis/rdt-cli) · [xhs-cli](https://github.com/jackwener/xiaohongshu-cli) · [bili-cli](https://github.com/public-clis/bilibili-cli) · [yt-dlp](https://github.com/yt-dlp/yt-dlp) · [Jina Reader](https://github.com/jina-ai/reader) · [Exa](https://exa.ai) · [mcporter](https://github.com/nicobailon/mcporter) · [feedparser](https://github.com/kurtmckee/feedparser) · [mcp-server-linkedin](https://github.com/stickerdaniel/linkedin-mcp-server)
## Contact
- 📧 **Email:** pnt01@foxmail.com
- 🐦 **Twitter/X:** [@Neo_Reidlab](https://x.com/Neo_Reidlab)
For collaboration or questions, add me on WeChat — I'll invite you to the community group:
> For bug reports and feature requests, please use [GitHub Issues](https://github.com/Panniantong/Agent-Reach/issues) — easier to track.
## License
[MIT](../LICENSE)
## Friends
[Agent Skills Hub](https://agentskillshub.top/) — Find Claude skills & MCP servers without guessing what's safe. Every one of 133,000+ entries is security-graded, quality-scored, and refreshed every 8 hours.
[AtomGit mirror](https://atomgit.com/qq_51337814/Agent-Reach) — Synchronized AtomGit mirror for Agent Reach.
## Star History
---
### README Ja (`docs/README_ja.md`)
---
## Agent Reach가 필요한 이유
AI 에이전트는 이미 인터넷에 접근할 수 있습니다 — 하지만 "인터넷에 접속할 수 있다"는 것은 시작에 불과합니다.
가장 가치 있는 정보는 소셜 미디어와 특화된 플랫폼에 분포되어 있습니다: Twitter 토론, Reddit 피드백, YouTube 튜토리얼, XiaoHongShu 리뷰, Bilibili 비디오, GitHub 활동... **여기가 정보 밀도가 가장 높은 곳**이지만, 각 플랫폼은 고유한 진입장벽이 있습니다:
| 문제점 | 현실 |
|------------|---------|
| Twitter API | 유료 사용, 중간 정도 사용량 ~월 $215 |
| Reddit | 서버 IP가 403 오류 발생 |
| XiaoHongShu | 둘러보기 위해 로그인 필요 |
| Bilibili | 해외/서버 IP 차단 |
에이전트를 이 플랫폼에 연결하려면 도구를 찾고, 의존성을 설치하고, 설정을 디버깅해야 합니다 — 하나씩 직접.
**Agent Reach는 이를 하나의 명령으로 바꿉니다:**
```
Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
```
이 명령을 에이전트에 복사해서 붙여넣으세요. 몇 분 뒤에는 트윗을 읽고, Reddit을 검색하고, Bilibili를 볼 수 있게 됩니다.
**이미 설치하셨나요? 한 번에 업데이트하세요:**
```
Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
```
### ✅ 시작하기 전에 알면 좋은 것들
| | |
|---|---|
| 💰 **완전 무료** | 모든 도구는 오픈 소스, 모든 API는 무료입니다. 유일한 비용은 서버 프록시(월 $1)일 수 있습니다 — 로컬 컴퓨터에서는 불필요 |
| 🔒 **프라이버시 안전** | Cookie는 로컬에 유지됩니다. 업로드되지 않습니다. 완전 오픈 소스 — 언제든지 감사 가능 |
| 🔄 **최신 상태 유지** | 업스트림 도구(yt-dlp, twitter-cli, rdt-cli, Jina Reader 등)를 추적하고 정기적으로 업데이트 |
| 🤖 **모든 에이전트와 호환** | Claude Code, OpenClaw, Cursor, Windsurf... 명령을 실행할 수 있는 모든 에이전트 |
| 🩺 **내장 진단 도구** | `agent-reach doctor` — 하나의 명령으로 작동 항목, 작동하지 않는 항목, 수정 방법 표시 |
---
## 지원 플랫폼
| 플랫폼 | 기능 | 설정 | 참고 |
|----------|-------------|:-----:|-------|
| 🌐 **Web** | 읽기 | 없음 | 모든 URL → 깨끗한 Markdown ([Jina Reader](https://github.com/jina-ai/reader) ⭐9.8K) |
| 🐦 **Twitter/X** | 읽기 · 검색 | Cookie | Cookie로 검색, 타임라인, 트윗 읽기, 아티클 읽기 가능 ([twitter-cli](https://github.com/public-clis/twitter-cli)) |
| 📕 **XiaoHongShu** | 읽기 · 검색 · 댓글 | OpenCLI / Cookie | OpenCLI는 사용자가 관리하는 기존 Chrome 세션만 사용하며, MCP/기존 도구는 Cookie-Editor 사용 |
| 💼 **LinkedIn** | Jina Reader (공개 페이지) | Cookie | 전체 프로필, 회사, 채용 공고 검색 가능. 에이전트에 "LinkedIn 설정 도와줘"라고 말하세요 |
| 💬 **WeChat Articles** | 검색 + 읽기 | 없음 | Exa를 통한 WeChat 공식 계정 게시글 검색 + 읽기 (설정 없음) + 선택적 [Camoufox](https://github.com/daijro/camoufox) |
| 💻 **V2EX** | 인기 주제 · 노드 주제 · 주제 상세 + 답글 · 사용자 프로필 | 없음 | 공개 JSON API, 인증 없음. 기술 커뮤니티 콘텐츠에 적합 |
| 📈 **Xueqiu (雪球)** | 주식 시세 · 검색 · 인기 글 · 인기 종목 | 브라우저 Cookie | 에이전트에 "Xueqiu 설정 도와줘"라고 말하세요 |
| 🎙️ **Xiaoyuzhou Podcast** | 음성 변환 | 무료 API key | Groq Whisper를 통한 팟캐스트 오디오 → 전체 텍스트 변환 (무료) |
| 🔍 **Web Search** | 검색 | 자동 설정 | 설치 시 자동 설정, 무료, API key 불필요 ([Exa](https://exa.ai) via [mcporter](https://github.com/nicepkg/mcporter)) |
| 📦 **GitHub** | 읽기 · 검색 | 없음 | [gh CLI](https://cli.github.com) 기반. 공개 저장소는 즉시 사용 가능. `gh auth login`으로 Fork, Issue, PR 기능 활성화 |
| 📺 **YouTube** | 읽기 · **검색** | 없음 | 자막 + 1800+ 비디오 사이트 검색 ([yt-dlp](https://github.com/yt-dlp/yt-dlp) ⭐148K) |
| 📺 **Bilibili** | 읽기 · **검색** | 설정 없음 | [bili-cli](https://github.com/public-clis/bilibili-cli)로 검색·비디오 정보(로그인 불필요), 자막은 OpenCLI. yt-dlp는 Bilibili의 412 차단으로 사용하지 않음 |
| 📡 **RSS** | 읽기 | 없음 | 모든 RSS/Atom 피드 ([feedparser](https://github.com/kurtmckee/feedparser) ⭐2.3K) |
| 📖 **Reddit** | 검색 · 읽기 | Cookie | 2024년부터 인증 필요 — 설치 후 `rdt login` 실행 ([rdt-cli](https://github.com/public-clis/rdt-cli)) |
> **설정 단계:** 없음 = 설치 후 바로 사용 · 자동 = 설치 시 처리 · mcporter = MCP 서비스 필요 · Cookie = 브라우저에서 내보내기 · 프록시 = 월 $1
---
## 빠른 시작
이 명령을 AI 에이전트(Claude Code, OpenClaw, Cursor 등)에 입력하세요:
```
Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
```
에이전트가 자동으로 설치하고, 환경을 감지하고, 준비된 항목을 알려줍니다.
> 🔄 **이미 설치하셨나요?** 한 번에 업데이트:
> ```
> Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
> ```
수동 설치
```bash
pip install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto # 읽기 전용 확인 (기본값)
agent-reach install --env=auto --system # 시스템 변경을 명시적으로 승인한 경우에만
```
Skill로 설치 (Claude Code / OpenClaw / Skill을 지원하는 모든 에이전트)
```bash
npx skills add Panniantong/Agent-Reach@agent-reach
```
Skill이 설치된 후, 에이전트는 `agent-reach` CLI 사용 가능 여부를 자동 감지하고 필요한 경우 설치합니다.
> `agent-reach install --system`을 명시적으로 승인한 경우에만 Skill이 자동 등록됩니다. 기본 `agent-reach install`은 읽기 전용입니다.
---
## 별도 설정 없이 바로 사용
별도의 설정이 필요 없습니다. 에이전트에게 요청하기만 하면 됩니다:
- "이 링크 읽어줘" → 모든 웹 페이지에 대해 `curl https://r.jina.ai/URL`
- "이 GitHub 저장소는 무엇인가요?" → `gh repo view owner/repo`
- "이 비디오는 무엇을 다루나요?" → 자막을 위해 `yt-dlp --dump-json URL`
- "이 트윗 읽어줘" → `TWITTER_AUTH_TOKEN` / `TWITTER_CT0` 설정 후 `twitter tweet URL`
- "이 RSS 구독해줘" → 피드 파싱을 위해 `feedparser`
- "GitHub에서 LLM 프레임워크 검색" → `gh search repos "LLM framework"`
**기억할 명령이 없습니다.** 에이전트가 SKILL.md를 읽고 무엇을 호출할지 알고 있습니다.
---
## 필요할 때 설정
사용하지 않나요? 설정하지 마세요. 모든 단계는 선택 사항입니다.
### 🍪 Cookies — 무료, 2분
에이전트에 "Twitter 쿠키 설정 도와줘"라고 말하세요. Cookie-Editor 수동
내보내기 절차를 안내합니다. 저장한 값은 `agent-reach doctor`가 명시적
자격 증명의 존재 여부를 확인할 때만 사용하며, doctor는 `twitter status`를
실행하지 않습니다. 직접 실행하는 `twitter` 프로세스에는
`TWITTER_AUTH_TOKEN`과 `TWITTER_CT0`를 명시적으로 전달해야 합니다.
### 🌐 Proxy — 월 $1, 서버 전용
대부분의 사용자는 프록시가 필요 없습니다. 네트워크에서 Reddit/Twitter가 차단된 경우에만 프록시를 설정하세요. Bilibili는 bili-cli를 사용합니다.
> Reddit은 이제 프록시 없이 rdt-cli를 통해 무료로 작동합니다. 로컬 컴퓨터는 Bilibili에도 프록시가 필요 없습니다.
---
## 한눈에 보는 상태
```
$ agent-reach doctor
👁️ Agent Reach 상태
========================================
✅ 사용 가능:
✅ GitHub 저장소 및 코드 — 공개 저장소 읽기 및 검색 가능
✅ YouTube 비디오 자막 — yt-dlp
✅ Bilibili 검색 및 비디오 정보 — bili-cli (자막은 OpenCLI)
✅ RSS/Atom 피드 — feedparser
✅ 웹 페이지 (모든 URL) — Jina Reader API
🔍 검색 (무료 Exa key로 잠금 해제):
⬜ 웹 시맨틱 검색 — exa.ai에서 무료 key 발급
🔧 설정 가능:
⚠️ Twitter/X — doctor는 명시적 자격 증명의 존재만 확인하며, 업스트림 CLI에는 환경 변수가 필요
✅ Reddit 글 및 댓글 — rdt-cli를 통한 검색 및 읽기 (무료, 프록시 없음)
⬜ XiaoHongShu 노트 — OpenCLI는 기존 세션만 사용하며, 그 외에는 Cookie-Editor로 MCP/기존 도구 설정
상태: 6/9 채널 사용 가능
```
---
## 설계 철학
**Agent Reach는 스캐폴딩(scaffolding) 도구이지, 프레임워크가 아닙니다.**
새 에이전트를 실행할 때마다 도구를 찾고, 의존성을 설치하고, 설정을 디버깅하는 데 시간을 보내게 됩니다 — Twitter는 무엇으로 읽나요? Reddit 차단을 어떻게 우회하나요? YouTube 자막은 어떻게 추출하나요? 매번 동일한 작업을 반복해야 합니다.
Agent Reach는 한 가지 간단한 작업을 수행합니다: **도구 선택 및 설정 결정을 대신 해줍니다.**
설치 후, 에이전트는 업스트림 도구(twitter-cli, rdt-cli, xhs-cli, yt-dlp, mcporter, gh CLI 등)를 직접 호출합니다 — 중간에 래퍼 계층이 없습니다.
### 🔌 모든 채널은 플러그인 가능
각 플랫폼은 업스트림 도구에 매핑됩니다. **마음에 안 드나요? 교체하세요.**
```
channels/
├── web.py → Jina Reader ← Firecrawl, Crawl4AI로 교체...
├── twitter.py → twitter-cli ← 공식 API로 교체...
├── youtube.py → yt-dlp ← YouTube API, Whisper로 교체...
├── github.py → gh CLI → REST API, PyGithub로 교체...
├── bilibili.py → bili-cli ▸ OpenCLI ▸ 검색 API (yt-dlp는 412 차단으로 폐기)
├── reddit.py → OpenCLI ▸ rdt-cli (로그인 상태 필요)
├── xiaohongshu.py → OpenCLI ▸ xiaohongshu-mcp ▸ xhs-cli
├── linkedin.py → linkedin-mcp ← LinkedIn API로 교체...
├── rss.py → feedparser ← atoma로 교체...
├── exa_search.py → mcporter MCP ← Tavily, SerpAPI로 교체...
└── __init__.py → 채널 레지스트리 (doctor 검사용)
```
각 채널 파일은 업스트림 도구가 설치되어 작동하는지만 확인합니다(`agent-reach doctor`용 `check()` 메서드). 실제 읽기 및 검색은 업스트림 도구를 직접 호출하여 수행합니다.
### 현재 도구 선택
| 시나리오 | 도구 | 이유 |
|----------|------|-----|
| 웹 페이지 읽기 | [Jina Reader](https://github.com/jina-ai/reader) | 9.8K stars, 무료, API key 불필요 |
| 트윗 읽기 | [twitter-cli](https://github.com/public-clis/twitter-cli) | 2.1K stars, cookie 인증, 검색/읽기/타임라인/글 |
| Reddit | [rdt-cli](https://github.com/public-clis/rdt-cli) | 304 stars, cookie 인증, 검색 + 전체 글 + 댓글 |
| YouTube 자막 + 검색 | [yt-dlp](https://github.com/yt-dlp/yt-dlp) | YouTube 및 지원 비디오 사이트용(Bilibili에는 사용하지 않음) |
| Bilibili | [bili-cli](https://github.com/public-clis/bilibili-cli) ▸ OpenCLI ▸ 검색 API | yt-dlp는 412 차단으로 폐기. bili-cli는 로그인 없이 검색·읽기 가능 |
| 웹 검색 | [Exa](https://exa.ai) via [mcporter](https://github.com/nicobailon/mcporter) | AI 시맨틱 검색, MCP 통합, API key 불필요 |
| GitHub | [gh CLI](https://cli.github.com) | 공식 도구, 인증 후 전체 API |
| RSS 읽기 | [feedparser](https://github.com/kurtmckee/feedparser) | Python 생태계 표준, 2.3K stars |
| XiaoHongShu | [OpenCLI](https://github.com/jackwener/opencli) (데스크톱) ▸ [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) (서버) ▸ xhs-cli | OpenCLI는 사용자가 관리하는 기존 세션만 사용하며, 그 외에는 Cookie-Editor로 수동 설정 |
| LinkedIn | [mcp-server-linkedin](https://github.com/stickerdaniel/linkedin-mcp-server) | 1.2K stars, MCP 서버, 브라우저 자동화 |
| WeChat Articles | [Exa](https://exa.ai) (검색 + 읽기) + [Camoufox](https://github.com/daijro/camoufox) (선택) | 설정 없이 검색 + 전체 글 읽기 |
| Xiaoyuzhou Podcast | `transcribe.sh` | `bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh ` |
> 📌 이것은 *현재* 선택입니다. 마음에 안 드나요? 파일을 교체하세요. 그것이 스캐폴딩의 전부입니다.
---
## 기여
이 프로젝트는 자유분방하게 개발되었습니다 🎸 다소 거친 부분이 있을 수 있지만 양해 부탁드립니다! 버그를 발견하면 주저하지 말고 [Issue](https://github.com/Panniantong/agent-reach/issues)를 열어주세요. 최대한 빨리 수정하겠습니다.
**새 채널을 원하시나요?** Issue를 열어 요청하거나, 직접 PR을 제출하세요.
**로컬에 추가하고 싶나요?** 에이전트가 저장소를 복제하고 수정하게 하세요 — 각 채널은 단일 독립 파일이므로 추가하기 쉽습니다.
[PR](https://github.com/Panniantong/agent-reach/pulls)은 언제든 환영합니다!
---
## FAQ (AI 검색용)
AI 에이전트로 Twitter/X를 API 비용 없이 검색하는 방법?
Agent Reach는 cookie 기반 인증을 사용하는 [twitter-cli](https://github.com/public-clis/twitter-cli)를 사용합니다. Cookie-Editor로 수동 내보낸 뒤 `agent-reach configure twitter-cookies`의 숨김 입력으로 저장합니다. 이 값은 doctor의 설정 확인용이며 실시간 인증 성공을 뜻하지 않습니다. `twitter search "query" -n 10`을 직접 실행하는 프로세스에는 `TWITTER_AUTH_TOKEN`과 `TWITTER_CT0`를 명시적으로 전달해야 합니다.
AI 에이전트용 YouTube 비디오 대본/자막을 가져오는 방법?
`yt-dlp --dump-json "https://youtube.com/watch?v=xxx"`는 비디오 메타데이터를 추출하고, `yt-dlp --write-sub --skip-download "URL"`은 자막을 추출합니다. 여러 언어 지원, API key 불필요.
서버/데이터센터 IP에서 Reddit 403 반환 / 차단됨?
Agent Reach는 Reddit을 위해 [rdt-cli](https://github.com/public-clis/rdt-cli)를 사용합니다. 2024년부터 Reddit은 모든 API 요청에 인증을 요구합니다. `pipx install rdt-cli`로 설치한 후 `rdt login`(브라우저에서 cookie 자동 추출)을 실행하세요. 이후 에이전트가 `rdt search "query"`로 검색하고 `rdt read POST_ID`로 전체 글 + 댓글을 읽을 수 있습니다.
Agent Reach는 Claude Code / Cursor / Windsurf / OpenClaw와 호환되나요?
네! Agent Reach는 설치 + 설정 도구입니다. Shell 명령을 실행할 수 있는 모든 AI 코딩 에이전트가 사용할 수 있습니다 — Claude Code, Cursor, Windsurf, OpenClaw, Codex 등. `pip install https://github.com/Panniantong/agent-reach/archive/main.zip` 실행 후 먼저 `agent-reach install`로 읽기 전용 검사를 하고, 시스템 변경을 명시적으로 승인한 경우에만 `agent-reach install --system`을 실행합니다. PyPI의 동명 패키지는 다른 프로젝트입니다.
Agent Reach는 무료인가요? API 비용이 있나요?
100% 무료 오픈 소스입니다. 모든 백엔드(twitter-cli, rdt-cli, OpenCLI, bili-cli, yt-dlp, Jina Reader, Exa)는 유료 API key가 필요 없는 무료 도구입니다. 네트워크에서 특정 사이트가 차단된 경우에만 선택적으로 프록시 비용이 발생할 수 있습니다.
웹 스크래핑용 Twitter API의 무료 대안?
Agent Reach는 cookie 인증을 통해 Twitter에 접근하는 twitter-cli를 사용합니다 — 브라우저 세션과 동일. API 요금 없음, 속도 제한 등급 없음, 개발자 계정 불필요. 검색, 트윗 읽기, 프로필 읽기, 타임라인 지원.
XiaoHongShu / 小红书 콘텐츠를 프로그래밍 방식으로 읽는 방법?
Agent Reach는 XiaoHongShu 로그인을 대신 수행하거나 브라우저 cookie를 읽지 않습니다. OpenCLI는 사용자가 이미 보유하고 명시적으로 관리하는 Chrome 세션만 사용합니다. 기존 세션이 없다면 자동 로그인하지 말고 Cookie-Editor로 수동 내보내 xiaohongshu-mcp 또는 기존 도구를 설정하세요. `agent-reach configure xhs-cookies`는 OpenCLI/Chrome에 cookie를 주입하지 않습니다.
---
## 크레딧
[twitter-cli](https://github.com/public-clis/twitter-cli) · [rdt-cli](https://github.com/public-clis/rdt-cli) · [xhs-cli](https://github.com/jackwener/xiaohongshu-cli) · [bili-cli](https://github.com/public-clis/bilibili-cli) · [yt-dlp](https://github.com/yt-dlp/yt-dlp) · [Jina Reader](https://github.com/jina-ai/reader) · [Exa](https://exa.ai) · [mcporter](https://github.com/nicobailon/mcporter) · [feedparser](https://github.com/kurtmckee/feedparser) · [mcp-server-linkedin](https://github.com/stickerdaniel/linkedin-mcp-server)
## 연락처
- 📧 **이메일:** pnt01@foxmail.com
- 🐦 **Twitter/X:** [@Neo_Reidlab](https://x.com/Neo_Reidlab)
협력이나 질문은 WeChat에 추가해주세요 — 커뮤니티 그룹에 초대해 드리겠습니다:
> 버그 보고 및 기능 요청은 [GitHub Issues](https://github.com/Panniantong/Agent-Reach/issues)를 이용해주세요 — 추적이 더 수월합니다.
## 라이선스
[MIT](../LICENSE)
## 관련 프로젝트
[OpenClaw on Tencent Cloud](https://www.tencentcloud.com/act/pro/intl-openclaw?referral_code=G76Y819A&lang=en&pg=) — Tencent Cloud에서 원클릭 OpenClaw: 채팅으로 Agent Reach를 연결하고 인터넷 기능을 활성화하세요.
## Star History
---
### Cookie Export (`docs/cookie-export.md`)
# Cookie Export Guide — For Server Users
Your Agent is on a server and can't access your browser directly.
Here's how to export cookies from your local computer — **fastest method first**.
## Method 1: Cookie-Editor Extension (Recommended — 30 seconds per site)
1. Install **Cookie-Editor** for Chrome: https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm
(Also available for Firefox, Edge)
2. Go to the website (e.g. https://x.com) and make sure you're logged in
3. Click the Cookie-Editor icon in your toolbar
4. Click **Export** → **Header String**
5. Paste the result to your Agent
That's it! Your Agent will run:
```bash
agent-reach configure twitter-cookies
agent-reach configure xhs-cookies
```
Both commands use a hidden prompt. For non-interactive automation, send the
same exported value through stdin and add `--stdin`; never place cookies in
the process arguments.
Twitter values saved by Agent Reach are used by `agent-reach doctor` only to
check whether explicit credentials are present. Doctor does not run
`twitter status`. Direct `twitter` commands still require
`TWITTER_AUTH_TOKEN` and `TWITTER_CT0` in their process environment.
This XiaoHongShu export is for xiaohongshu-mcp or a legacy tool.
`agent-reach configure xhs-cookies` does not inject cookies into OpenCLI or
Chrome. OpenCLI may use only an existing Chrome session explicitly controlled
by the user. Agent Reach never logs the user in or reads XiaoHongShu browser
cookies.
### Sites to export:
| Site | URL to visit | What to tell Agent |
|------|-------------|-------------------|
| Twitter/X | https://x.com | "Here are my Twitter cookies: [paste]" |
| XiaoHongShu | https://www.xiaohongshu.com | "Here are my XHS cookies: [paste]" |
| Bilibili | https://www.bilibili.com | "Here are my Bilibili cookies: [paste]" |
## Method 2: Manual (No extension needed)
1. Open the site in Chrome, make sure you're logged in
2. Press **F12** (or right-click → Inspect)
3. Click the **Network** tab
4. Refresh the page (F5)
5. Click any request in the list
6. In the right panel, scroll to **Request Headers**
7. Find the line starting with `Cookie:`
8. Copy the entire value after `Cookie: `
9. Paste to your Agent
---
### Dependency Locking (`docs/dependency-locking.md`)
# Dependency Locking Guide
Agent Reach uses `constraints.txt` as a reproducible dependency baseline.
## Why
- Keep local/CI dependency graph stable
- Reduce "works on my machine" drift
- Make regression results easier to compare
## Install with constraints
```bash
pip install -c constraints.txt -e '.[dev]'
```
## Update workflow
1. Update `pyproject.toml` dependency ranges as needed.
2. Validate against latest compatible versions locally.
3. Update pinned versions in `constraints.txt`.
4. Run validation:
```bash
pytest -q
ruff check agent_reach tests
mypy agent_reach
```
5. Open PR with dependency and validation notes.
---
### Install (`docs/install.md`)
# Agent Reach — Installation Guide
## For Humans
Copy this to your AI Agent:
```
帮我安装 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
```
> 🛡️ **Safe by default:** `agent-reach install` only checks the machine and lists missing dependencies:
> ```
> 帮我安全检查并安装 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
> ```
> Only use `--system` after the user explicitly approves system-level installs and configuration writes.
---
## For AI Agents
### Goal
Install Agent Reach and all upstream tools so your user's agent has full internet access. After installation, you'll use the upstream tools directly (OpenCLI, twitter-cli, bili-cli, rdt-cli, yt-dlp, mcporter, gh CLI, etc.) — Agent Reach is the selector, installer, health checker and router, never a wrapper.
### ⚠️ Boundaries
When fixing issues, stay within these limits:
- **DO NOT** run commands with `sudo` unless the user explicitly approved
- **DO NOT** modify system files outside `~/.agent-reach/`
- **DO NOT** install packages not listed in this guide
- **DO NOT** disable firewalls, security settings, or system protections
- **DO NOT** clone repos, create files, or run commands inside the agent workspace / working directory
- If something requires elevated permissions, **tell the user** what's needed and let them decide
### 📁 Directory Rules
All Agent Reach files go in dedicated directories — **never in the agent workspace**:
| Purpose | Directory | Example |
|---------|-----------|---------|
| Config & tokens | `~/.agent-reach/` | `~/.agent-reach/config.json` |
| Upstream tool repos | `~/.agent-reach/tools/` | `~/.agent-reach/tools/xiaoyuzhou/` |
| Temporary files | `/tmp/` | `/tmp/yt-dlp-output/` |
| Skills | `~/.openclaw/skills/agent-reach/` | SKILL.md |
**Why?** If you clone repos or create files in the workspace, it pollutes the user's project directory and can break their agent over time. Keep the workspace clean.
### Step 1: Install the basics
```bash
# 推荐：pipx（最省心）
pipx install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto # Read-only check (default)
# After the user explicitly approves system changes:
agent-reach install --env=auto --system
# 如果你的 Python 来自 Homebrew / 遇到 PEP 668（externally-managed-environment）
# 用虚拟环境安装：
python3 -m venv ~/.agent-reach-venv
source ~/.agent-reach-venv/bin/activate
pip install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto # Read-only check (default)
# After the user explicitly approves system changes:
agent-reach install --env=auto --system
```
> 💡 **Windows / Microsoft Store Python alias?**
> 如果 `python3 --version` 打开 Microsoft Store，或 `where python3` 指向
> `...\AppData\Local\Microsoft\WindowsApps\python3.exe`，说明 `python3` 是 Windows
> 的 Store alias，不是可用的 Python 安装。请改用 Python Launcher `py -3`，或实际安装目录里的 `python.exe`。
>
> PowerShell 示例：
> ```powershell
> py -3 -m venv $env:USERPROFILE\.agent-reach-venv
> $env:USERPROFILE\.agent-reach-venv\Scripts\Activate.ps1
> python -m pip install https://github.com/Panniantong/agent-reach/archive/main.zip
> agent-reach install --env=auto
> ```
The default command checks core infrastructure (gh CLI, Node.js, mcporter, Exa search, yt-dlp config) without changing the host. With explicit `--system` approval it installs/configures the missing pieces and activates these zero-config channels:
- Web (Jina Reader), YouTube, GitHub, RSS, Exa Search, V2EX, Bilibili (basic)
> 💡 **macOS / Homebrew Python 提示 `externally-managed-environment`？**
> 这是 PEP 668 保护，不是 Agent Reach 本身的问题。优先用 `pipx install ...`，或先创建 `venv` 再安装。
**Install modes:**
```bash
agent-reach install --env=auto # Check only; safe default
agent-reach install --env=auto --safe # Same check-only behavior (compatibility)
agent-reach install --env=auto --system # Explicitly allow external/system installs
agent-reach install --env=auto --dry-run # Preview what --system would do
```
### Step 2: Ask the user which optional channels they want
After installing the basics, **ask the user** which additional channels they need. Present this list:
> 基础渠道装好了！你现在可以让我搜网页、看 YouTube、读 GitHub 等。
>
> 还有这些可选渠道，你需要哪些？
>
> - 🌟 **OpenCLI**（桌面推荐）— 一次安装即可提供 Reddit/Facebook/Instagram/B站字幕/Twitter 备选，并作为小红书桌面后端；小红书只使用用户已有且明确控制的 Chrome 会话
> - 🐦 **Twitter/X** — 搜推文、看时间线（需要登录 Cookie）
> - 📈 **雪球** — 股票行情、热门帖子（需要登录 Cookie）
> - 🎙️ **小宇宙播客** — 音频转文字（需要免费 Groq Key）
> - 📕 **小红书** — 搜索、阅读、评论（OpenCLI 用已有会话；MCP/存量工具用 Cookie-Editor）
> - 📖 **Reddit** — 搜索和阅读帖子（必须登录态：桌面 OpenCLI 或 rdt-cli + Cookie）
> - 📘 **Facebook** — 搜索、主页、Feed、群组列表（桌面走 OpenCLI，复用 Chrome 登录态）
> - 📷 **Instagram** — 用户搜索、Profile、用户最近帖子、Explore（桌面走 OpenCLI，复用 Chrome 登录态）
> - 📺 **B站完整版** — 热门、排行、搜索、视频详情（bili-cli，无需登录）
> - 💼 **LinkedIn** — Profile、职位搜索
> - 🎯 **Boss直聘** — 搜索岗位 + JD 全文（本地专用 Chrome；用户手动登录）
>
> 告诉我你要哪些，比如"帮我装小红书和 Twitter"、"帮我装 Facebook 和 Instagram"。或者说"全部装"。
Based on the user's choice, run:
```bash
agent-reach install --env=auto --system --channels=opencli,xiaohongshu # Desktop user chose XHS
agent-reach install --env=auto --system --channels=facebook,instagram # Desktop Meta channels
agent-reach install --env=local --system --channels=boss # Desktop Boss直聘
agent-reach install --env=auto --system --channels=all # User approved everything
```
Supported channel names: `opencli`, `twitter`, `xiaoyuzhou`, `xueqiu`, `xiaohongshu`, `reddit`, `facebook`, `instagram`, `bilibili`, `linkedin`, `boss`, `all`
### Step 3: Fix what's broken
Run `agent-reach doctor` and check the output.
Try to get as many channels to ✅ as possible. If something failed during install or shows as ❌/⚠️ in doctor, diagnose the problem and try to fix it — but stay within the boundaries above. If a fix requires elevated permissions or system changes, ask the user first.
Only ask the user when you genuinely need their input (credentials, permissions, etc.).
### Step 3: Configure things that need user input
Some channels need credentials only the user can provide. Based on the doctor output, ask for what's missing:
> 🔒 **Security tip:** For platforms that need cookies or browser sessions (Twitter, XiaoHongShu, Reddit, Facebook, Instagram, Boss直聘), we recommend using a **dedicated/secondary account** rather than your main account. Cookie/browser-session auth carries two risks:
> 1. **Account ban** — platforms may detect non-browser API calls and restrict or ban the account
> 2. **Credential exposure** — cookies grant full account access; using a secondary account limits the blast radius if credentials are ever compromised
> 🍪 **Cookie / 登录态：**
>
> 传统 CLI 需要 Cookie 的平台（Twitter、雪球等），**优先使用 Cookie-Editor 导入**，这是最简单最可靠的方式：
> 1. 用户在自己的浏览器上登录对应平台
> 2. 安装 [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) Chrome 插件
> 3. 点击插件 → Export → Header String
> 4. 把导出的字符串发给 Agent
>
> Twitter 只接受用户通过 Cookie-Editor 明确导出的内容。Agent Reach 不替用户执行小红书登录，也不读取小红书浏览器 Cookie；小红书 OpenCLI 只使用用户已有且明确控制的 Chrome 会话。没有现成会话时，改用 Cookie-Editor 导出后配置 xiaohongshu-mcp / 存量工具。雪球、Bilibili 可按平台显式导入，例如 `agent-reach configure --from-browser chrome --platform xueqiu`；命令不会扫描或保存其他平台。
**Twitter search & posting:**
> "To unlock Twitter search, I need your Twitter cookies. Install the Cookie-Editor Chrome extension, go to x.com/twitter.com, click the extension → Export → Header String, and paste it to me."
```bash
agent-reach configure twitter-cookies
```
这会把 `twitter_auth_token` 和 `twitter_ct0` 保存给 Agent Reach 自己的
`doctor` 配置检查。`doctor` 不会实时执行上游 `twitter status`，也不会修改
当前 Shell。直接运行 `twitter search/read/...` 前，必须在该进程环境中显式设置：
```bash
export TWITTER_AUTH_TOKEN="..."
export TWITTER_CT0="..."
twitter search "query" -n 10
```
> **代理说明（中国大陆等需要翻墙的网络环境）：**
>
> twitter-cli 和 rdt-cli 使用 Python，在需要代理的网络环境下可通过环境变量配置代理。
>
> **你（Agent）需要做的：**
> 1. 确认用户配了代理：`agent-reach configure proxy`（隐藏输入）
> 2. 设置环境变量：`export HTTP_PROXY="..." HTTPS_PROXY="..."`
> 3. Agent Reach 会自动处理剩下的，不需要用户做额外操作
>
> 如果用户报告 "fetch failed"，参考 [troubleshooting.md](troubleshooting.md)
**Reddit (login is mandatory — no zero-config path):**
> Reddit 的匿名接口已被封、官方 API 需人工审批。桌面用户首选 OpenCLI（浏览器里登录过 reddit.com 即可用）；服务器/存量用户用 rdt-cli：
```bash
# PyPI 落后，从 GitHub 装（与代码内 _RDT_GIT_SOURCE 同一钉定版本）
pipx install 'git+https://github.com/public-clis/rdt-cli.git@5e4fb3720d5c174e976cd425ccc3b879d52cac66'
rdt login # 自动提取浏览器 Cookie；服务器无浏览器时按 doctor 提示手动写 Cookie
```
> 中国大陆访问 Reddit 需要代理；服务器 IP 被风控时可配住宅代理（如 https://webshare.io，约 $1/月）：
> ```bash
> agent-reach configure proxy
> ```
**XiaoHongShu / 小红书（多后端，按环境选）:**
> **认证边界：** Agent Reach 不替用户执行小红书登录，也不读取浏览器
> Cookie。OpenCLI 只使用用户已经存在且明确控制的 Chrome 会话；
> `agent-reach configure xhs-cookies` 不会把 Cookie 注入 OpenCLI 或 Chrome。
> 如果没有现成会话，不要自动登录；改用 Cookie-Editor 手工导出后配置
> xiaohongshu-mcp 或存量工具：
>
> ```bash
> agent-reach configure xhs-cookies
> ```
>
> 该显式命令会保存/导入用户提供的 xiaohongshu.com 同域 Cookie 集；请先确认
> Cookie 名称和范围。非 xiaohongshu.com 域 Cookie 会被忽略。
>
> **桌面电脑（推荐 OpenCLI）：**
```bash
agent-reach install --system --channels opencli
```
> 装完后引导用户做唯一一步手动操作（Chrome 安全限制，无法代劳）：
> 1. 打开 https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk
> 2. 点「添加至 Chrome」
> 3. 运行 `opencli doctor` 验证（显示 Extension: connected 即成功）
>
> AUTH_REQUIRED 且用户没有现成会话时，不要替用户自动登录；改走下面的
> xiaohongshu-mcp / 存量工具 Cookie-Editor 路线。
>
> **服务器 / 无桌面环境（xiaohongshu-mcp）：**
> 1. 从 https://github.com/xpzouying/xiaohongshu-mcp/releases 下载对应平台 binary 到 `~/.agent-reach/tools/`
> 2. 启动服务（首次运行会自动下载约 150MB 无头浏览器，耐心等完成）
> 3. 按上面的 Cookie-Editor 流程手工导入 Cookie
> 4. 接入：`mcporter config add xiaohongshu http://localhost:18060/mcp --scope home`
> 5. 调用时务必带 `--timeout 120000`
>
> **存量用户（xhs-cli）：** 已装好的 xhs-cli 继续作为备选后端工作
> （上游 2026-03 起停更，不推荐新装）；认证仍使用上面的 Cookie-Editor
> 手工导出流程。
**Facebook / Instagram（桌面 OpenCLI）:**
> 这两个平台走 OpenCLI：复用用户自己的 Chrome 登录态，不保存账号密码，不走 Meta Graph API 审批流。服务器/无桌面环境不推荐支持。
```bash
agent-reach install --system --channels facebook,instagram
```
> 装完后：
> 1. 确认 Chrome 已安装 OpenCLI 扩展并通过 `opencli doctor`
> 2. 在 Chrome 里登录 facebook.com / instagram.com
> 3. Agent 直接调用：
> ```bash
> opencli facebook search "query" -f yaml
> opencli facebook profile zuck -f yaml
> opencli facebook groups -f yaml
> opencli instagram search "query" -f yaml # 用户搜索
> opencli instagram profile nasa -f yaml
> opencli instagram user nasa -f yaml # 指定用户最近帖子
> ```
>
> Facebook Groups 当前只承诺读取用户登录后可见的群组列表/最近动态，不承诺任意群帖子和评论 API。Instagram 的 search 是用户搜索，不是全站帖子关键词搜索；若提示 429/登录错误，先让用户在 Chrome 里重新登录并降低频率。
**雪球 / Xueqiu (股票行情 + 热门帖子):**
> "雪球需要登录后的 Cookie。请先在 Chrome 里登录 xueqiu.com，然后运行："
```bash
agent-reach configure --from-browser chrome --platform xueqiu
```
> 只会读取并保存雪球需要的最小 Cookie；不会顺带读取其他平台。
**小宇宙播客 / Xiaoyuzhou Podcast (Groq Whisper):**
> "小宇宙播客转文字已默认安装，只需要一个免费的 Groq API Key。"
脚本已随 Agent Reach 自动安装，用户只需提供 Key：
```bash
agent-reach configure groq-key
```
> **获取 Groq API Key（免费、无需信用卡、30 秒搞定）：**
> 1. 打开 https://console.groq.com
> 2. 用 Google/GitHub 账号登录（或注册）
> 3. 左侧菜单 → API Keys → Create API Key
> 4. 复制 Key（以 `gsk_` 开头），发给 Agent 即可
>
> **使用方式：**
> 用户发一个小宇宙链接给 Agent，Agent 自动调用：
> ```bash
> bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh https://www.xiaoyuzhoufm.com/episode/xxxxx
> ```
>
> 自动下载音频 → 转码切片 → Groq Whisper 转录 → 输出完整中文文字稿。
>
> **免费额度和限制：**
> - 每小时约 2 小时音频（7200 秒），超出后等 15 分钟自动恢复
> - 日常听几期播客完全够用
> - 转录质量高（Whisper large-v3），但不区分说话人
> - 2 小时以上的播客建议分批处理
**LinkedIn (可选 — mcp-server-linkedin):**
> "LinkedIn 基本内容可通过 Jina Reader 读取。完整功能（Profile 详情、人才与职位搜索）需要 mcp-server-linkedin。"
> **配置方式（推荐 stdio）：**
> 先按官方说明安装 `uv`（会同时提供 `uvx`）：
> https://docs.astral.sh/uv/getting-started/installation/
>
> ```bash
> mcporter config add linkedin --command uvx --arg mcp-server-linkedin@latest --env UV_HTTP_TIMEOUT=300 --scope home
> ```
>
> `uvx` 会按需获取并启动最新版服务，无需另装 Python 包或常驻 HTTP 服务。
>
> **首次登录（需要浏览器界面）：**
> ```bash
> uvx mcp-server-linkedin@latest --login
> ```
> 浏览器弹出后手动登录 LinkedIn；登录态会保存到 `~/.linkedin-mcp/profile/`。无桌面的服务器需在 VNC 等可见桌面中运行同一条登录命令。
>
> 详见 https://github.com/stickerdaniel/linkedin-mcp-server
**Boss直聘（桌面专用 — boss-agent-cli + CDP）:**
当用户说“帮我配 Boss直聘”时，Agent 完成可自动完成的部分，只把网站登录留给用户：
1. 先说明将安装一个上游 CLI、启动独立 Chrome 配置目录，并请求系统安装授权。
2. 用户同意后运行：
```bash
agent-reach install --env=local --system --channels=boss
```
3. 按操作系统启动只绑定本机回环地址的专用 Chrome：
```bash
# macOS
open -na "Google Chrome" --args --remote-debugging-address=127.0.0.1 \
--remote-debugging-port=9222 --user-data-dir="$HOME/.boss-chrome-profile" \
"https://www.zhipin.com/web/geek/job"
# Linux
google-chrome --remote-debugging-address=127.0.0.1 \
--remote-debugging-port=9222 --user-data-dir="$HOME/.boss-chrome-profile" \
"https://www.zhipin.com/web/geek/job"
```
Windows PowerShell：
```powershell
Start-Process chrome.exe -ArgumentList '--remote-debugging-address=127.0.0.1','--remote-debugging-port=9222',"--user-data-dir=$env:USERPROFILE\.boss-chrome-profile",'https://www.zhipin.com/web/geek/job'
```
4. 暂停，让**用户肉眼确认**窗口内的登录状态（右上角有头像）；未登录则让**用户手动
登录**、扫码或处理滑块。Agent 不索取账号密码、不代替登录，也不要用 `boss status`
代替这一步——它只校验本地 `session.enc`，不代表这个 Chrome 已登录。
5. 用户确认登录完成后运行：
```bash
boss --cdp-url http://localhost:9222 login --cdp
agent-reach doctor # 看 boss 行 message 里的浏览器 wt2 cookie 探测结果
```
> 安全边界：任何能访问调试端口 9222 的本机进程都能完全控制这个 Chrome。
> 必须使用 `--remote-debugging-address=127.0.0.1`，不得暴露到局域网或公网；使用
> 独立 profile 并长期复用，不要每次删除或新建，也不要默认切换到日常主 Chrome；
> 不使用时关闭专用 Chrome。Boss 不支持服务器/无桌面环境。搜索命令必须带
> `--browser-source existing-browser --cdp-url http://localhost:9222`。
>
> 依赖：boss-agent-cli 后继拆分 PR #403–#407 已合并入上游 master，安装器锁定上游
> 固定提交
> `4c991b77086a203173bf08a4cb64a23af6514fe6`，不跟随会移动的 branch。该提交包含
> `browser_source="existing-browser"`（严格 CDP）、`JobItem.lid` 和 `job_card_browser()`。上游发布正式版后，
> Agent Reach 应改用版本约束。
### Step 4: Final check
Run `agent-reach doctor` one final time and report the results to your user.
### Step 5: Set up daily monitoring (OpenClaw only)
If you are running inside **OpenClaw**, ask your user:
> "Agent Reach 安装好了。要不要我设一个每天自动检查的任务？它会帮你盯着这些渠道是否正常、有没有新版本。有问题才会通知你，没问题不打扰。"
If the user agrees, create a **cron job** (daily, `sessionTarget: "isolated"`, `delivery: "announce"`) with this task:
```
运行 agent-reach watch 命令。
如果输出包含"全部正常"，不需要通知用户，静默结束。
如果输出包含问题（❌ ⚠️）或新版本（🆕），把完整报告发给用户，并建议修复方案。
如果有新版本可用，问用户是否要升级（把这句话发给用户的 Agent 即可完整更新：帮我更新 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md）。
```
If the user wants a different agent to handle it, let them choose.
---
## Quick Reference
| Command | What it does |
|---------|-------------|
| `agent-reach install --env=auto` | Read-only dependency and channel check (default) |
| `agent-reach install --env=auto --system` | Explicitly install/configure core external tools |
| `agent-reach install --env=auto --system --channels=twitter,xiaohongshu` | Install approved optional channels |
| `agent-reach install --env=local --system --channels=boss` | Install the desktop Boss直聘 strict-CDP backend |
| `agent-reach install --env=auto --system --channels=all` | Install everything after explicit approval |
| `agent-reach install --env=auto --safe` | Compatibility alias for the safe default |
| `agent-reach install --env=auto --dry-run` | Preview what would be done |
| `agent-reach doctor` | Show channel status |
| `agent-reach watch` | Quick health + update check (for scheduled tasks) |
| `agent-reach check-update` | Check for new versions |
| `agent-reach configure twitter-cookies` | 通过隐藏输入保存 Twitter Cookie；直接调用仍需显式环境变量 |
| `agent-reach configure proxy` | 通过隐藏输入保存代理地址；不是自动解锁开关 |
| `agent-reach configure groq-key` | 通过隐藏输入配置小宇宙转录 Key |
After installation, use upstream tools directly. See SKILL.md for the full command reference:
| Platform | Upstream Tool | Example |
|----------|--------------|---------|
| Twitter/X | `twitter`（备选 `opencli`） | 设置 `TWITTER_AUTH_TOKEN` / `TWITTER_CT0` 后运行 `twitter search "query" -n 10` |
| YouTube | `yt-dlp` | `yt-dlp --dump-json URL` |
| Bilibili | `bili`（字幕走 `opencli`） | `bili search "query" --type video` / `opencli bilibili subtitle BVxxx` |
| Reddit | `opencli`（备选 `rdt`） | `opencli reddit search "query" -f yaml` / `rdt read POST_ID` |
| Facebook | `opencli` | `opencli facebook search "query" -f yaml` |
| Instagram | `opencli` | `opencli instagram user nasa -f yaml` |
| GitHub | `gh` | `gh search repos "query"` |
| Web | `curl` + Jina | `curl -s "https://r.jina.ai/URL"` |
| Exa Search | `mcporter` | `mcporter call exa.web_search_exa query="..." numResults=5` |
| 小红书 | `opencli`（服务器 `mcporter`） | `opencli xiaohongshu search "query" -f yaml` |
| 小宇宙播客 | `transcribe.sh` | `bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh ` |
| LinkedIn | `mcporter` | `mcporter call linkedin.get_person_profile linkedin_username="..."` |
| Boss直聘 | `boss` / Python public API | `agent-reach doctor`（浏览器 wt2 探测；`boss status` 只反映本地 session.enc）；搜索和 JD 见 `references/career.md` |
| RSS | `feedparser` | `python3 -c "import feedparser; ..."` |
> 多后端平台以 `agent-reach doctor --json` 的 `active_backend` 为准。
---
### Troubleshooting (`docs/troubleshooting.md`)
# 常见问题排查
## 雪球 / Xueqiu: API 返回 400
**症状：** `agent-reach doctor` 显示雪球 ⚠️，报 `HTTP Error 400`
**原因：** 雪球 API 需要登录 Cookie，无法通过匿名访问获取。
**解决方案：** 在 Chrome 里登录 xueqiu.com，然后运行：
```bash
agent-reach configure --from-browser chrome --platform xueqiu
```
再次运行 `agent-reach doctor` 确认恢复 ✅。Cookie 过期后重新运行即可。
---
## Boss直聘: `boss status` 说已登录，但搜索报 `AUTH_EXPIRED`
**症状：** `boss status` / `status --live` 返回 `logged_in: true`（甚至带用户名），
但 `boss ... search` 立刻报 `{"code": "AUTH_EXPIRED", "message": "用户未登录"}`。
专用 Chrome 可能同时停在带 `_security_check` 的 URL 上，看起来像反爬滑块。
**原因：** Boss 有两个登录态存储，认证的是不同通道：
| 存储 | 谁在用 |
|---|---|
| `~/.boss-agent/auth/session.enc` | `boss status` / `status --live`；httpx 通道的低危操作（`detail` / `cities` / `job_card_httpx`）。CDP 搜索也会读它（读不到直接报「未登录」），但复用真 Chrome context 时它的 cookie 从未真正生效 |
| `~/.boss-chrome-profile` 内的浏览器 cookie | `existing-browser` 严格 CDP 模式下 search / greet 等高危操作实际携带的凭据 |
`boss status` 只校验本地 session.enc。本地存着几天前的旧凭据、而专用 Chrome
profile 本身没登录时，它依然报 `logged_in: true`——这不是登录态有效的证明。
同时 `_security_check` 页面是反爬挑战，**已登录也会出现**，不能用它判断登录态；
两者叠加很容易把「浏览器未登录」误判成「卡在滑块」。
> 两个存储都不要删。session.enc 缺失会让 CDP 搜索在连上浏览器之前就失败；
> 需要刷新它时跑 `login --cdp`，不要手工删文件。
**判定顺序：**
1. `AUTH_EXPIRED` 是 ground truth——出现即浏览器未登录，不管 `boss status` 说什么；
2. `agent-reach doctor` 的 boss 行会直接探测浏览器内有无 `wt2` cookie，以它为准；
3. `boss status` 仅作参考；页面 URL 完全不作为判据。
**解决方案：** 在专用 Chrome 窗口里肉眼确认并手动登录 zhipin.com，然后同步登录态：
```bash
boss --cdp-url http://localhost:9222 login --cdp
agent-reach doctor # boss 行 message 应显示「浏览器内有登录 cookie（wt2）」
```
> 拉起专用 Chrome 后的第一步永远是让用户肉眼确认登录状态，不要用 `boss status` 代替。
---
## Twitter/X: twitter-cli 连接失败
**症状：** `twitter search` 或其他命令返回错误
**原因：** twitter-cli 需要 `TWITTER_AUTH_TOKEN` 和 `TWITTER_CT0`
环境变量才能访问 Twitter API。`agent-reach configure twitter-cookies`
保存的值只供 doctor 检查配置是否齐全；doctor 不执行上游认证，也不会设置当前
Shell。如果你的网络环境需要代理才能访问 x.com，还需要配置代理。
**解决方案：**
### 方案 1：设置环境变量代理
```bash
export TWITTER_AUTH_TOKEN="..."
export TWITTER_CT0="..."
export HTTP_PROXY="http://user:pass@host:port"
export HTTPS_PROXY="http://user:pass@host:port"
twitter search "test" -n 1
```
### 方案 2：使用全局代理工具
让代理工具接管所有网络流量，这样 twitter-cli 的请求也会走代理：
```bash
# macOS — ClashX / Surge 开启"增强模式"
# Linux — proxychains 或 tun2socks
proxychains twitter search "test" -n 1
```
### 方案 3：不用 twitter-cli，用 Exa 搜索替代
twitter-cli 不可用时，可以直接用 Exa 搜索 Twitter 内容：
```bash
mcporter call exa.web_search_exa query="site:x.com 搜索词" numResults=5
```
### 方案 4：检查认证
```bash
twitter check
```
> 如果返回 "Missing credentials"，需要在运行该命令的进程环境中设置
> `TWITTER_AUTH_TOKEN` 和 `TWITTER_CT0`。
>
> **Fallback：** 如果你已经安装了 bird CLI（`npm install @steipete/bird`），它也能正常工作。Agent Reach 会自动检测已安装的工具。
---
### Update (`docs/update.md`)
# Agent Reach — Update Guide
## For Humans
Copy this to your AI Agent:
```
帮我更新 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
```
Or in English:
```
Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md
```
---
## For AI Agents
### ⚠️ Workspace Rules
**Never create files, clone repos, or run commands in the agent workspace.** Use `/tmp/` for temporary work and `~/.agent-reach/` for persistent data.
### Goal
Update Agent Reach to the latest version, refresh upstream tools, migrate from retired backends, and verify everything works. The user should not need to do anything manually (except things only a human can do, like clicking a browser-extension install button).
### Step 1: Check current version
```bash
agent-reach check-update
```
If it says "已是最新版本", skip to Step 4 (verify). Otherwise continue.
### Step 2: Update Agent Reach package
```bash
pip install --upgrade https://github.com/Panniantong/agent-reach/archive/main.zip
```
> If pip complains about `externally-managed-environment` (PEP 668), the user
> originally installed via pipx or a venv — use the matching command:
> `pipx install --force https://github.com/Panniantong/agent-reach/archive/main.zip`
> or activate `~/.agent-reach-venv` first.
### Step 3: Refresh upstream tools
Run these to keep installed tools current. **Only upgrade what is already
installed — do not install new tools the user never asked for** (the one
exception: OpenCLI on desktop, see below).
```bash
# Python-based CLIs the user already has (upgrade keeps signatures fresh)
which twitter >/dev/null 2>&1 && { pipx upgrade twitter-cli 2>/dev/null || uv tool upgrade twitter-cli 2>/dev/null; }
which bili >/dev/null 2>&1 && { pipx upgrade bilibili-cli 2>/dev/null || uv tool upgrade bilibili-cli 2>/dev/null; }
which xhs >/dev/null 2>&1 && { pipx upgrade xiaohongshu-cli 2>/dev/null || uv tool upgrade xiaohongshu-cli 2>/dev/null; }
which yt-dlp >/dev/null 2>&1 && { pipx install --force 'yt-dlp[default]' 2>/dev/null || uv tool install --force 'yt-dlp[default]' 2>/dev/null || python -m pip install -U 'yt-dlp[default]' 2>/dev/null; }
# rdt-cli is pinned to a git source (PyPI lags upstream) — same pin as the code's _RDT_GIT_SOURCE
which rdt >/dev/null 2>&1 && pipx install --force 'git+https://github.com/public-clis/rdt-cli.git@5e4fb3720d5c174e976cd425ccc3b879d52cac66' 2>/dev/null
# npm-based
which mcporter >/dev/null 2>&1 && npm update -g mcporter 2>/dev/null
which opencli >/dev/null 2>&1 && npm update -g @jackwener/opencli 2>/dev/null
```
**Desktop users without OpenCLI**: since v1.5.0 OpenCLI is the preferred
backend for 小红书/Reddit (and adds B站 subtitles). Offer it once. For
小红书, OpenCLI may use only an existing Chrome session explicitly controlled
by the user. The update must never log the user in or read browser cookies:
> "这次更新引入了 OpenCLI 后端。要装吗？装完只需你在 Chrome 商店点一次
> 『添加扩展』。小红书 OpenCLI 只使用你已有的 Chrome 会话；如果没有现成
> 会话，我不会自动登录，会改用 Cookie-Editor 配置 MCP / 存量工具。"
If yes: `agent-reach install --system --channels opencli` and guide them through the
extension click. If no, everything keeps working on existing backends.
### Step 4: Coexistence (DO NOT uninstall old tools)
**Never uninstall tools the user already has.** Retired backends (e.g. yt-dlp
no longer serves Bilibili; xhs-cli is no longer installed by default) keep
working as fallbacks where they still function. Agent Reach routes around
them automatically — removal is the user's call, not yours.
### Step 5: Verify
```bash
agent-reach version
agent-reach doctor
```
Running `agent-reach doctor` (text mode) also makes sure an Agent Reach skill
exists in detected agent skill directories. If the user already has a skill
there, doctor preserves it instead of overwriting local customizations. Use
`agent-reach skill --install` when you explicitly want to refresh the bundled
skill files.
Check the doctor output:
- Every channel shows ✅ / [!] with a clear message, and multi-backend
channels (小红书/Reddit/B站/Twitter) report `当前后端：…`
- If a previously-working channel now shows [X]/error, the message contains
the exact fix (e.g. a venv-reinstall prescription) — run it, then re-check
- `--json` gives the same data machine-readably (`active_backend` per channel)
### Step 6: Report to user
Tell the user:
1. What version they're on now (`agent-reach version`)
2. How many channels are available, and which backend each multi-backend
platform is using (from doctor)
3. Anything that needs their action (e.g. a Chrome extension click, or a
manual Cookie-Editor export when XiaoHongShu uses MCP / a legacy tool)
4. What changed in this update (release notes shown by `check-update`)
Done.
---
--- METRICS ---
- Files Extracted: 9
- Estimated Token Budget: ~23121 tokens
- Canonical Reference: https://codewiki.google/github.com/Panniantong/Agent-Reach
