导语

你有没有遇到过这种情况——让 Claude Code 帮你查个技术问题，它说"我无法访问互联网"；让它看看某个 YouTube 教程讲了什么，它说"我没有这个能力"。Agent-Reach 就是来解决这个问题的。一行命令，你的 Agent 就能读推特、搜 Reddit、看 B站、刷小红书，而且完全免费。本文带你从零装好，跑通第一个搜索。

---

一、项目背景

AI Agent 已经能帮你写代码、改文档、管项目了，但一到需要上网查东西的时候就抓瞎。Twitter API 要付费，Reddit 匿名接口被封了，B站的风控把通用下载工具全拦了，小红书不登录根本看不了。每个平台都有自己的门槛，你得一个一个去踩坑。

Agent-Reach 做的事情很简单：当下最稳的接入方式，替你选好、装好、体检好。接入方式会换代，你不用操心。

它不是一个工具，而是一个"能力层"（capability layer）——负责选型、安装、体检、路由，不负责底层读取本身。读取由 Agent 直接调用上游工具完成，没有包装层。每个平台都有"首选 + 备选"的多后端路由，某个接入方式失效了，自动切下一个。

目前支持的平台包括：网页、YouTube、RSS、全网搜索（Exa）、GitHub、Twitter/X、B站、Reddit、小红书、LinkedIn、V2EX、雪球、小宇宙播客。

官方GitHub的项目地址:
https://github.com/Panniantong/Agent-Reach

---

二、本文环境说明

• 操作系统：Windows 11（macOS / Linux 同理，安装命令略有差异）
• Python 版本：Python 3.10+
• 部署方式：pip 安装（推荐 pipx）
• 是否为简化方案：否，本文为完整安装流程
• 硬件要求：无特殊要求，普通开发机即可
• 前置条件：已安装 Python 3.10+ 和 Git

---

三、安装前准备

3.1 基础依赖检查

先确认 Python 和 pip 是否正常：

python --version
pip --version

如果 python 命令不可用，试试 py -3（Windows Python Launcher）。后面所有命令里的 python 都可以替换成 py -3。

⚠️ 如果 python3 --version 打开了 Microsoft Store，说明 python3 是 Windows 的 Store alias，不是真实的 Python 安装。改用 python 或 py -3。

3.2 检查 Git

git --version

没有的话去 git-scm.com 下载安装。

3.3 安装前注意事项

• 安装过程中 Agent-Reach 会自动安装 Node.js、gh CLI、mcporter 等系统级依赖，不需要手动装
• 如果不想自动装系统包，可以用 --safe 参数
• 所有配置文件放在 ~/.agent-reach/ 目录下，不会污染你的项目目录
• Cookie 等敏感信息只存在本地，不上传

---

四、安装与部署

4.1 安装 Agent-Reach

推荐用 pipx（最省心，自动隔离环境）：

pipx install https://github.com/Panniantong/agent-reach/archive/main.zip

如果没有 pipx，先装一下：

pip install pipx
pipx ensurepath

或者用传统虚拟环境方式：

python -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

4.2 初始化环境

装完之后运行初始化命令，它会自动检测你的环境并安装所需的基础设施：

agent-reach install --env=auto

这一步会做几件事：

1. 安装核心 CLI 工具（yt-dlp、feedparser 等）
2. 自动检测并安装 Node.js、gh CLI、mcporter
3. 通过 MCP 接入 Exa 搜索引擎（免费，不需要 API Key）
4. 检测你是本地电脑还是服务器，给出对应的配置建议
5. 在 Agent 的 skills 目录安装 SKILL.md，以后 Agent 遇到搜索需求会自动知道调哪个工具

装完之后，默认激活 7 个零配置渠道：网页、YouTube、GitHub、RSS、Exa 搜索、V2EX、B站基础版。

4.3 安装可选渠道

基础渠道装好后，Agent 会问你要不要装更多。你也可以手动指定：

# 装 OpenCLI（桌面推荐，一次安装解锁小红书/Reddit/B站字幕/Twitter备选）
agent-reach install --env=auto --channels=opencli

# 装全部可选渠道
agent-reach install --env=auto --channels=all

# 按需选择
agent-reach install --env=auto --channels=twitter,xiaohongshu,reddit

支持的可选渠道：opencli、twitter、xiaoyuzhou、xueqiu、xiaohongshu、reddit、bilibili、linkedin、all。

---

五、配置说明

5.1 核心配置文件

Agent-Reach 的配置都在 ~/.agent-reach/ 目录下：

~/.agent-reach/
├── config.json          # 主配置文件
├── tools/               # 上游工具仓库
└── ...

一般不需要手动改配置。Agent-Reach 的设计理念是"Agent 自己知道该怎么配"——你告诉 Agent “帮我配 Twitter”，它会一步一步引导你。

5.2 需要登录的平台怎么配

Twitter、小红书、Reddit 这些需要登录态的平台，配置方式很统一：

1. 在 Chrome 里登录目标平台
2. 用 Cookie-Editor 插件导出 Cookie
3. 把导出的 Cookie 发给 Agent，Agent 会自动配置

桌面端推荐装 OpenCLI，它直接复用浏览器的登录态，小红书、Reddit、B站字幕、Twitter 备选一次全解锁。

5.3 容易踩坑的配置点

• OpenClaw 用户：需要先开启 exec 权限。默认的 messaging 工具配置下 Agent 无法执行 shell 命令。运行 openclaw config set tools.profile "coding" 然后重启 Gateway。
• macOS Homebrew Python：如果提示 externally-managed-environment（PEP 668），优先用 pipx install，或先创建 venv。
• 服务器部署：服务器没有浏览器，需要用 xiaohongshu-mcp 扫码等方式配置登录态。还需要一个代理（约 $1/月）。

---

六、跑通第一个 Demo

6.1 先做个体检

agent-reach doctor

这条命令会列出每个渠道的状态——✅ 通了、⚠️ 部分可用、❌ 挂了。如果某个渠道显示 ❌，它会告诉你原因和修复方法。

6.2 让 Agent 帮你搜东西

装好之后，直接告诉你的 Agent 就行，不需要记命令：

• “帮我看看这个网页写了什么” → Agent 自动调 Jina Reader
• “这个 GitHub 仓库是做什么的” → Agent 自动调 gh repo view
• “这个 YouTube 视频讲了什么” → Agent 自动调 yt-dlp 提取字幕
• “B站搜一下 AI 教程” → Agent 自动调 bili-cli
• “全网搜一下 LLM 框架对比” → Agent 自动调 Exa 语义搜索

Agent 读了 SKILL.md 之后自己知道该调什么工具，你只管用自然语言提需求。

6.3 预期结果

以"B站搜一下 AI 教程"为例，Agent 会：

1. 识别到这是 B站搜索需求
2. 自动调用 bili search AI教程
3. 返回搜索结果列表（标题、播放量、链接）
4. 你可以继续让它"帮我把第一个视频的字幕总结一下"

---

七、效果验证

7.1 验证方式一：doctor 命令

agent-reach doctor

所有已安装渠道显示 ✅ 即为正常。

7.2 验证方式二：让 Agent 搜网页

对你的 Agent 说：“帮我看看 https://github.com/Panniantong/Agent-Reach 这个仓库是做什么的”

Agent 应该能返回仓库的描述、Star 数、主要功能等信息。

7.3 验证方式三：让 Agent 搜 B站

对你的 Agent 说：“B站搜一下 Python 教程，给我前三个结果”

Agent 应该返回 B站搜索结果。

---

八、常见报错与解决方案

8.1 pip 安装报 externally-managed-environment

错误现象：error: externally-managed-environment

原因分析：macOS Homebrew 安装的 Python 启用了 PEP 668 保护，不允许直接 pip install。

解决方案：

# 方案一：用 pipx（推荐）
pipx install https://github.com/Panniantong/agent-reach/archive/main.zip

# 方案二：创建虚拟环境
python3 -m venv ~/.agent-reach-venv
source ~/.agent-reach-venv/bin/activate
pip install https://github.com/Panniantong/agent-reach/archive/main.zip

8.2 python3 打开 Microsoft Store

错误现象：运行 python3 --version 打开了 Microsoft Store。

原因分析：Windows 的 python3.exe 是 Store alias，不是真实的 Python。

解决方案：改用 python 或 py -3 替代所有命令中的 python3。

8.3 B站搜索返回空或报错

错误现象：B站搜索无结果，或提示 412 错误。

原因分析：yt-dlp 已被 B站风控全面封杀（2026年6月实测）。Agent-Reach 已切换到 bili-cli 作为首选后端。

解决方案：

# 确认 bili-cli 已安装
agent-reach doctor

# 如果 bili 通道显示 ❌，重新安装
agent-reach install --env=auto --channels=bilibili

8.4 OpenClaw Agent 无法执行命令

错误现象：Agent 说"我没有执行命令的权限"。

原因分析：OpenClaw 默认使用 messaging 工具配置，不允许 Agent 执行 shell 命令。

解决方案：

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

然后开启新对话即可。

---

九、进阶说明

• 更完整配置：每个平台都有多个后端可选，查看 ~/.agent-reach/ 下的渠道配置文件了解路由逻辑
• 服务器部署：需要额外配置代理（约 $1/月），参考官方文档的服务器部署章节
• 自定义渠道：Agent-Reach 的渠道架构是插件化的，可以自己写渠道文件接入新平台
• 源码结构：channels/ 目录下每个 .py 文件对应一个平台，包含首选+备选后端的有序列表
• 安全模式：agent-reach install --env=auto --safe 不会自动装系统包，只告诉你需要什么

---

十、总结

Agent-Reach 解决了一个很实际的问题：让 AI Agent 能上网。而且它的设计思路很聪明——不做包装层，只做选型和路由，把实际的读取工作交给最合适的上游工具。这意味着每个平台永远用的是当前最好的接入方式，坏了自动换。

对于普通开发者来说，装好 Agent-Reach 之后，你的 Claude Code / Cursor / OpenClaw 就从一个"只能写代码的助手"变成了"能上网查资料的助手"。这个能力差距，用过的都知道有多大。

---