Agent Reach 全平台接入指南：零配置起步、多渠道后端与 doctor 体检的 Agent 互联网能力架构

本文基于 Agent Reach 的韩文版 README（docs/README_ko.md）展开，系统讲解该项目如何以“scaffolding（脚手架）”定位，让 AI 编码 Agent 以一条命令接入 Web、Twitter/X、Reddit、YouTube、Bilibili、XiaoHongShu、GitHub 等 14 类平台：覆盖安装/更新的三条路径、各平台配置档位与上游工具选型、Cookie 凭据的安全边界，并结合 agent_reach/channels/ 源码解析多后端候选、check() 体检与 agent-reach doctor 报告的底层实现。

为什么“能上网”不等于“能读到有价值的信息”

README 开宗明义：AI Agent 已经可以访问互联网，但信息密度最高的内容分散在社交平台与垂直站点，而每个平台都有独特的进入壁垒：

问题点	现实情况
Twitter API	付费使用，中等用量约 $215/月
Reddit	服务器 IP 直接 403
XiaoHongShu（小红书）	浏览需要登录
Bilibili	海外/服务器 IP 被拦截

传统做法是每个平台单独找工具、装依赖、调配置。Agent Reach 的核心价值在于把这些工具选型与配置决策一次性做完：安装后 Agent 直接调用上游工具（twitter-cli、rdt-cli、bili-cli、yt-dlp、mcporter、gh CLI 等），中间没有 wrapper 层。README 强调的三个前置事实值得记住：

• 完全免费：所有工具开源、所有 API 免费，唯一可能的成本是受限网络下的代理（约 $1/月），本地电脑不需要；
• 隐私安全：Cookie 只保存在本地，不上传，全开源可审计；
• 内置诊断：agent-reach doctor 一条命令告诉你哪些可用、哪些不可用、怎么修。

快速开始：三种安装路径

1. 让 Agent 自己装（推荐）

把下面这行复制给任意能执行 Shell 命令的 Agent（Claude Code、Cursor、Windsurf、OpenClaw 等）：

Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md

docs/install.md 是一份“写给 Agent 看的安装手册”，Agent 会按其步骤自动安装、检测环境并汇报已就绪的渠道。已安装过则用更新指令：

Update Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md

2. 手动安装

pip install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto           # 只读检查（默认值，不修改系统）
agent-reach install --env=auto --system  # 仅在你明确批准系统级变更时执行

从 agent_reach/cli.py 的参数定义看，install 子命令的完整能力面包括：

• --env：local / server / auto（默认 auto 自动探测）；
• --system 与 --safe 互斥：默认（或 --safe）只做检查与缺件清单，--system 才允许安装系统依赖、全局工具、写配置与注册 Skill；
• --dry-run：预览 --system 将要做的事而不实际执行；
• --channels：按逗号分隔追加可选渠道，如 opencli,twitter,xiaohongshu,reddit,facebook,instagram,bilibili,xueqiu,xiaoyuzhou,linkedin,all。

--channels 的可选值与文档中“问用户要哪些渠道”的清单一一对应，体现了“所有可选渠道默认不装、按需解锁”的原则。

3. 以 Skill 形式安装

npx skills add Panniantong/Agent-Reach@agent-reach

Skill 安装后，Agent 会自动检测 agent-reach CLI 是否可用，必要时再触发安装。README 特别注明：只有显式批准过 --system 的场景才会自动注册 Skill，默认的 agent-reach install 是只读的。Skill 文件本体见 agent_reach/skill/SKILL.md。

支持平台一览：功能、配置档位与上游工具

README 的支持平台总表（原文完整继承）：

平台	功能	配置	说明
Web	读取	无	任意 URL → 干净 Markdown（Jina Reader）
Twitter/X	读 · 搜索	Cookie	凭 Cookie 搜索、读时间线/推文/长文（twitter-cli）
XiaoHongShu	读 · 搜索 · 评论	OpenCLI / Cookie	OpenCLI 只复用用户自管的 Chrome 会话；MCP/存量工具走 Cookie-Editor
LinkedIn	读（Jina Reader 公开页）	Cookie	完整 Profile、公司、职位搜索；对 Agent 说“帮我配 LinkedIn”
WeChat Articles（公众号）	搜索 + 读	无	Exa 搜索公众号文章并读取，可选 Camoufox
V2EX	热门 · 节点主题 · 主题详情+回复 · 用户主页	无	公开 JSON API，无需认证
Xueqiu（雪球）	行情 · 搜索 · 热帖 · 热门股票	浏览器 Cookie	对 Agent 说“帮我配 Xueqiu”
Xiaoyuzhou 播客	音频转写	免费 API key	Groq Whisper 把播客音频转全文（免费）
Web Search	搜索	自动	安装时自动配置，免费无需 key（Exa via mcporter）
GitHub	读 · 搜索	无	gh CLI；公开仓库立即可用，gh auth login 后解锁 Fork/Issue/PR
YouTube	读 · 搜索	无	字幕 + 1800+ 视频站搜索（yt-dlp）
Bilibili	读 · 搜索	无	bili-cli 搜索与视频信息（免登录），字幕走 OpenCLI；yt-dlp 因 412 拦截已弃用
RSS	读	无	任意 RSS/Atom 订阅（feedparser）
Reddit	搜索 · 读	Cookie	2024 起需认证——装完执行 rdt login（rdt-cli）

配置档位说明： 无 = 装完即用；自动 = 安装时处理；Cookie = 从浏览器导出；代理 = 约 $1/月。

装完即用的零配置命令

无需任何额外配置，只要对 Agent 提需求，它会自行选择命令：

• “读一下这个链接” → curl https://r.jina.ai/URL（任意网页转 Markdown）
• “这个 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"

README 强调“没有需要背的命令”：Agent 读取 SKILL.md 后自己知道该调什么。对应源码层面，Web 兜底渠道 agent_reach/channels/web.py 的 read() 就是把 URL 拼到 https://r.jina.ai/ 前缀并带浏览器 UA 请求，同时设了 5MB 响应上限，并用 title: just a moment...、Performing security verification 等特征识别 Cloudflare/Jina 反爬挑战页——命中时明确报错让用户改走站点专用工具，而不是把验证页当成正文返回。

需要时才配置：Cookie 与代理

README 的原则是：不用就不配，所有步骤都是可选的。

Cookie：免费、约 2 分钟

对 Agent 说“帮我配 Twitter Cookie”，它会引导你走 Cookie-Editor 手动导出流程。这里有一条严格的安全边界，docs/README_ko.md 原文写得很细：

保存的值只在 agent-reach doctor 检查显式凭据是否存在时使用，doctor 不会执行 twitter status。要直接运行的 twitter 进程则必须显式传入 TWITTER_AUTH_TOKEN 与 TWITTER_CT0。

源码印证了这一点。agent_reach/channels/twitter.py 的 twitter_cli_child_env() 只把配置中保存的凭据映射进单个子进程的环境变量，从不改写当前进程的 os.environ；而 _check_twitter_cli() 只做 shutil.which("twitter") + 凭据存在性判断（L90-L109），注释解释了原因：上游 twitter status 在凭据缺失或失效时会自动回退读取浏览器 Cookie，而 Agent Reach 只允许 Cookie-Editor 手动导出这一条凭据通道，所以 doctor 干脆不执行该命令。CLI 侧 configure 子命令支持的凭据键为 proxy / github-token / groq-key / openai-key / twitter-cookies / youtube-cookies / xhs-cookies（agent_reach/cli.py），并支持 --stdin 从标准输入读值以避免凭据出现在进程参数里。

同理，小红书渠道不代替用户登录、也不静默读取浏览器 Cookie：OpenCLI 只使用用户已拥有并明确管理的 Chrome 会话；没有会话时应手动用 Cookie-Editor 导出配置 xiaohongshu-mcp 或存量工具，agent-reach configure xhs-cookies 不会向 OpenCLI/Chrome 注入 cookie。

代理：约 $1/月，仅服务器场景

大多数用户不需要代理；只有在网络中 Reddit/Twitter 被封锁时才配置。Reddit 现在通过 rdt-cli 免代理免费工作，本地电脑访问 Bilibili 也不需要代理。

一条命令的体检：agent-reach doctor 输出与实现

README 给出的 doctor 输出示例（原文）：

$ 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는 명시적 자격 증명의 존재만 확인
  ✅ Reddit — rdt-cli (무료, 프록시 없음)
  ⬜ XiaoHongShu — OpenCLI / Cookie-Editor

상태: 6/9 채널 사용 가능

（上面按原韩文示例保留，实际运行输出随渠道数量变化。）

从 agent_reach/doctor.py 的实现看，doctor 本身极薄：它遍历 get_all_channels() 逐个调用 check(config)，收集 (status, message, active_backend)，并对每个渠道做异常兜底——“一个坏渠道绝不能拖垮整份报告”，异常会降级为 status="error"。状态词汇表是 ok / warn / off / error，报告再按 tier（0=零配置、1=需免费 key 或登录、2=复杂可选配置）分节渲染，末尾输出 N/M 渠道可用 的汇总。另一个细节：doctor 是凭据输出的最后边界，所有渠道消息在渲染前都经过 scrub_url_credentials() 清洗，防止上游探测输出回显配置里带账号密码的 URL。渠道合约本身有专门测试守护（tests/test_channel_contracts.py、tests/test_doctor.py）。

设计哲学：是脚手架，不是框架

README 的核心论断：Agent Reach 是 scaffolding，不是 framework。它只做一件事——替你做“选哪个工具、怎么配”的决定。安装之后，Agent 直接调用上游工具，没有中间 wrapper。

每个渠道都是可插拔的单文件

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() 方法）；真正的读取与搜索由 Agent 直接调用上游工具完成。

源码级解析：多后端候选与“第一个 ok 获胜”

agent_reach/channels/base.py 中的 Channel 抽象类把“插件化”落实为几个明确约定：

• backends: List[str] 是有序候选列表：backends[0] 为首选后端，其余是 fallback。“切换后端”意味着调整这个列表的顺序（或用户覆盖），而不是重写代码；
• ordered_backends(config) 支持用户覆盖：配置键 <channel>_backend（或环境变量 <CHANNEL>_BACKEND）可把指定后端移到队首；未知的覆盖值直接忽略，过期的坏配置永远遮不住可用的后端；
• check() 必须设置 self.active_backend 为当前真正服务该渠道的后端（找不到则为 None）。注释特别警告：shutil.which() 通过不等于健康——“陈旧的 venv shim 能过 which() 但无法执行”，所以渠道应当真的跑一条轻量命令来确认后端存活。

以 Bilibili 渠道为例（agent_reach/channels/bilibili.py），backends = ["bili-cli", "OpenCLI", "B站搜索 API"]：

• bili-cli 候选通过 probe_command("bili", ["--version"]) 真实探活，区分“未安装 / 断链 / 装好但跑不动”；
• OpenCLI 候选桥接已连接时仍返回 warn——因为 doctor 不执行平台命令，登录态与真实命令未实时验证，宁可保守不标记为可用；
• 零依赖兜底是 B 站搜索 API：直接 urlopen 探测 code == 0 即视为可达（仅搜索能力），并提示安装 bili-cli 获得完整功能；
• 模块 docstring 记录了决策依据：yt-dlp 已在 2026-06 实测被 B 站风控 412 拦截（最新版、直连、代理、预热 Cookie 全部无效），因此从该渠道移除，字幕改由 OpenCLI 通过浏览器会话提供。

Reddit 渠道（agent_reach/channels/reddit.py）则展示了“诚实的分层”：模块 docstring 明确“不存在零配置路径”——匿名 .json 端点被 403 反爬封死，官方 API 自 2025-11 起关闭自助注册，所以每个可用后端都依赖登录态（OpenCLI 复用浏览器会话，rdt-cli 导入 cookie）。_check_rdt() 只安全读取 ~/.config/rdt-cli/credential.json 检查 reddit_session 是否存在、是否超过 7 天 TTL，而不会执行会自动刷新 Cookie 的 rdt status；凭据缺失时给出完整的 Cookie-Editor 手工写入指引。这套“检查而不触发副作用”的原则贯穿所有需登录渠道。

当前工具选型与理由（原文表格）

场景	工具	理由
网页读取	Jina Reader	免费、无需 API key
读推文	twitter-cli	cookie 认证，支持搜索/读取/时间线/长文
Reddit	rdt-cli	cookie 认证，搜索 + 全文 + 评论
YouTube 字幕 + 搜索	yt-dlp	覆盖 YouTube 与受支持站点（不用于 Bilibili）
Bilibili	bili-cli ▸ OpenCLI ▸ 搜索 API	yt-dlp 因 412 拦截被弃用；bili-cli 免登录即可搜索/读取
Web 搜索	Exa via mcporter	AI 语义搜索，MCP 集成，无需 API key
GitHub	gh CLI	官方工具，认证后全量 API
RSS 读取	feedparser	Python 生态标准
XiaoHongShu	OpenCLI（桌面）▸ xiaohongshu-mcp（服务器）▸ xhs-cli	OpenCLI 仅用用户已有会话，其余用 Cookie-Editor 手动配置
LinkedIn	mcp-server-linkedin	MCP 服务器 + 浏览器自动化
WeChat Articles	Exa（搜索+读取）+ Camoufox（可选）	免配置搜索并读取全文
Xiaoyuzhou 播客	transcribe.sh	bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh <URL>

这是当前的选型。不满意就换文件——这正是“脚手架”的全部含义。

渠道注册表见 agent_reach/channels/init.py：ALL_CHANNELS 目前注册 15 个渠道实例（比 README 表格多出 Facebook、Instagram 两个桌面端渠道），并提供 get_channel(name) / get_all_channels() 供 doctor 与核心逻辑使用。想加自己的平台？让 Agent 在本地克隆的仓库里按“一个渠道一个单文件”的模式新增即可——这也是 README 贡献章节给出的路径。

FAQ：高频技术问题的官方答案

以下 7 条 FAQ 来自 README 的“AI 检索用”部分，完整继承：

1. 如何零 API 成本让 Agent 搜索 Twitter/X？ 使用 cookie 认证的 twitter-cli：Cookie-Editor 手动导出后经 agent-reach configure twitter-cookies 的隐藏输入保存。该值仅供 doctor 做配置存在性检查，不代表实时认证成功；直接运行 twitter search "query" -n 10 的进程需显式传入 TWITTER_AUTH_TOKEN 与 TWITTER_CT0。

2. 如何获取 YouTube 视频文稿/字幕？ yt-dlp --dump-json "https://youtube.com/watch?v=xxx" 提取元数据，yt-dlp --write-sub --skip-download "URL" 提取字幕，多语言、无需 API key。源码侧 agent_reach/channels/youtube.py 还会检查 JS runtime（deno/node）与 yt-dlp 的 --js-runtimes 配置，版本低于 2025-11-12 时给出升级指引——这是 YouTube 提取能稳定的前提。

3. 服务器/数据中心 IP 被 Reddit 403？ 2024 起 Reddit 所有 API 请求都要认证。pipx install rdt-cli 后运行 rdt login（浏览器自动提取 cookie），之后 rdt search "query" 搜索、rdt read POST_ID 读全文+评论。注意源码中 rdt-cli 安装源被固定到特定 commit（_RDT_GIT_SOURCE），原因是 PyPI 上版本落后于修复（见 agent_reach/channels/reddit.py 注释）。

4. 与 Claude Code / Cursor / Windsurf / OpenClaw 兼容吗？ 兼容一切能执行 Shell 命令的 Agent。它是安装+配置工具，与具体 Agent 实现解耦。注意从 GitHub 归档安装，PyPI 上同名包是另一个项目。

5. 免费吗？有 API 费用吗？ 100% 免费开源。所有后端（twitter-cli、rdt-cli、OpenCLI、bili-cli、yt-dlp、Jina Reader、Exa）都是免费工具、无需付费 key；仅当网络封锁相关站点时可能有可选的代理成本。

6. 有没有 Twitter API 的免费替代品？ twitter-cli 用 cookie 认证走浏览器同款会话——无 API 账单、无速率等级、无需开发者账号，支持搜索、读推文、读 Profile、时间线。

7. 如何程序化读取小红书？ Agent Reach 不代替登录、不读取浏览器 cookie；OpenCLI 只复用用户已有且明确管理的 Chrome 会话，无会话时手动用 Cookie-Editor 导出。agent-reach configure xhs-cookies 不向 OpenCLI/Chrome 注入 cookie。

适用前提与限制

• 运行环境：Python 3.10+（badge 声明）；Windows Store 的 python3 是别名，需改用 py -3 或真实解释器；Homebrew/PEP 668 环境建议 pipx 或独立 venv（docs/install.md 有对应说明）；
• 默认安装模式为只读检查，任何系统级变更都需要显式 --system，且所有文件只落在 ~/.agent-reach/、~/.agent-reach/tools/、/tmp/ 等专用目录，不污染 Agent 工作区；
• 需要 Cookie 的平台（Twitter、雪球、小红书等）官方建议使用专用/小号——cookie 会话认证存在平台封号与凭据暴露两类风险；
• 需要清理时可用 agent-reach uninstall（支持 --dry-run 与 --keep-config）。

小结

Agent Reach 把“给 Agent 一双看到整个互联网的眼睛”拆成两个可独立工作的部分：渠道注册表 + 每渠道 check() 构成的体检层（doctor 报告的来源），以及有序后端候选列表构成的可替换层（不满意就换单文件）。前者让 Agent 安装后立刻知道“什么可用、怎么修”，后者让每个平台的工具选型保持零锁定——这正是 README 反复强调的“scaffolding，不是 framework”。项目采用 MIT 许可证（LICENSE），新渠道可以直接按 agent_reach/channels/ 的单文件模式扩展。