Agent Reach：AI Agent 互联网接入指南

开源AgentAI

Agent Reach 是一个面向 AI Agent 的互联网能力层。它负责选择、安装、检查和路由上游工具，真正读取网页、调用 GitHub、提取视频字幕的动作交给 gh、yt-dlp、OpenCLI、bili-cli、feedparser、Jina Reader 等工具完成。这个分工让项目保持轻量，也让每个平台的登录态、代理和风控差异集中在独立渠道文件中。

Agent Reach 官方项目标识

它解决了哪一层问题

AI Agent 能否访问互联网，通常取决于三个条件：有没有合适的上游工具，工具是否已经安装，工具的认证和网络配置是否有效。Agent Reach 把这三个问题放进一套 CLI 流程里。

项目当前的 Python 包版本是 1.5.0，要求 Python 3.10 或更高版本。基础依赖包括 requests、feedparser、python-dotenv、loguru、pyyaml、rich 和 yt-dlp。浏览器自动化、浏览器 Cookie、小型 MCP 环境分别通过 browser、cookies、all 可选依赖提供，开发环境另有 pytest、ruff 和 mypy。

仓库把渠道分成不同的配置层级。网页、GitHub、YouTube、RSS、V2EX、B站基础能力等渠道可以直接使用；Twitter/X、Reddit、小红书、Facebook、Instagram、雪球等渠道需要登录态或浏览器会话；小宇宙播客转录需要 Groq Key；Exa 语义搜索需要对应的搜索配置。每个渠道在安装后都有独立的体检逻辑。

安装目录先隔离

官方安装文档要求把 Agent Reach 的配置、上游工具仓库、临时文件和技能文件放到专用目录，不污染 Agent 的项目工作区：

  • ~/.agent-reach/：配置、Token 和 Cookie
  • ~/.agent-reach/tools/：需要克隆的上游工具
  • /tmp/：转录、下载和其他临时文件
  • ~/.openclaw/skills/agent-reach/：注册后的技能文件

macOS 上可以优先使用 pipx 安装：

bash
pipx install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto

Homebrew Python 遇到 PEP 668 保护时，可以创建专用虚拟环境：

bash
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

--env=auto 会根据环境选择本地电脑或服务器配置。希望先查看动作清单，可以使用：

bash
agent-reach install --env=auto --dry-run

不希望安装器自动改变系统环境时，使用安全模式：

bash
agent-reach install --env=auto --safe

安全模式只检查依赖并给出建议。安装文档还明确规定，修复问题时不使用 sudo，不修改 ~/.agent-reach/ 之外的系统文件，不关闭防火墙或安全保护，也不把仓库克隆到 Agent 工作区。

基础渠道安装完成后，再按需求加入可选渠道。例如桌面环境需要 OpenCLI、小红书和 Reddit，可以执行：

bash
agent-reach install --env=auto --channels=opencli,xiaohongshu,reddit

可选渠道的安装和登录分开处理。安装器不会替用户输入账号密码，也不会自动读取没有明确授权的浏览器登录态。Twitter 采用 Cookie-Editor 导出的 Header String，桌面小红书优先复用用户已经控制的 Chrome 会话，Reddit 则使用 OpenCLI 浏览器会话或 rdt-cli 的显式 Cookie。

后端路由：渠道文件只描述能力

agent_reach/channels/base.py 定义了所有渠道共用的抽象。每个渠道有一个有序的 backends 列表，第一个是优先后端，后面的项目承担备用路径。例如 B站的后端顺序是：

text
bili-cli → OpenCLI → B站搜索 API

用户还可以通过 <channel>_backend 配置项调整顺序。体检过程结束后，渠道会写入 active_backend，报告中可以看到实际选中的后端。这个接口把平台差异压缩成几个稳定动作：识别 URL、探测后端、选择可用路径、返回使用建议。

路由选择依赖真实探测，不只检查命令是否出现在 PATH 中。probe.py 将结果区分为 missing、broken、timeout 和 error：

  • missing：命令不存在
  • broken：命令文件存在，但解释器或执行链已经损坏
  • timeout：命令启动后没有在限定时间内返回
  • error：命令可执行，但版本检查返回错误

这能识别常见的 Python 虚拟环境残留问题。比如 shutil.which() 还能找到一个旧的 pipx shim，但 shim 指向的 Python 已被删除，普通的文件存在检查会给出错误结论。Agent Reach 会把这类情况归为 broken，并给出 uv tool install --force 或 pipx reinstall 的修复方向。

doctor 如何判断可用

agent-reach doctor 由 doctor.py 汇总渠道状态。每个渠道的异常都在自己的检查范围内处理，单个平台出错不会让整份报告消失。输出中的状态分为 ok、warn、off 和 error，同时显示渠道名称、后端列表和修复建议。

GitHub 渠道是一个很好的例子。它先运行 gh --version 检查 CLI 是否能启动，再读取 gh 的 hosts.yml 或显式的 GH_TOKEN、GITHUB_TOKEN 配置。Doctor 不执行 gh auth status，因为某些版本的 GitHub CLI 在版本检查或认证检查过程中会写入设备标识文件。即使发现认证配置，报告也会保留“尚未实时验证”的状态，避免一次体检动作改变用户目录。

B站渠道会按顺序检查 bili-cli、OpenCLI 和搜索 API。bili-cli 提供搜索、热门、排行和视频详情，字幕能力由 OpenCLI 补足。项目将 B站从 yt-dlp 路径中移出，原因是仓库文档记录了 B站对该请求路径返回 412，项目选择 bili-cli 和 OpenCLI 作为替代组合。搜索 API 作为低依赖兜底，只覆盖搜索能力。

Twitter 渠道的优先级是 twitter-cli、OpenCLI 和旧版 bird CLI。Doctor 只检查显式凭据和工具状态，不启动会自动回退浏览器 Cookie 的上游认证命令。这样，配置检查不会在用户没有明确授权时读取浏览器登录态。运行 twitter 命令时，仍需在该进程环境中设置 TWITTER_AUTH_TOKEN 和 TWITTER_CT0。

Reddit 的检查逻辑把登录态视为前置条件。桌面用户可以用 OpenCLI 复用已登录的浏览器会话，服务器或存量环境可以使用 rdt-cli 和手动导入的 Cookie。没有登录态时，Doctor 会返回配置建议，不把匿名接口当作可用后端。

配置文件的安全设计

config.py 将配置文件固定在 ~/.agent-reach/config.yaml，读取配置时不会因为一次查询自动创建目录。第一次写入时，程序创建私有目录并将配置文件权限设置为用户可读写。保存采用临时文件加原子替换，写入前后都会检查配置目录和配置文件是否为符号链接，避免凭据写入被重定向。

配置内容有大小上限，敏感字段在展示时会被遮蔽。代理地址、Token、Cookie、Secret、Session 等字段都不会在 agent-reach doctor 的报告里直接展开。Doctor 还会检查配置文件权限，如果群组或其他用户具有读取权限，就在报告中提示执行：

bash
chmod 600 ~/.agent-reach/config.yaml

这套设计适合把 Agent Reach 放在个人电脑上长期运行。工具可以读取已有配置，却不会为了显示状态而触发登录、刷新 Cookie 或写入额外的设备文件；需要执行带副作用的认证操作时，流程会把命令交给用户确认。

装好以后如何调用能力

Agent Reach 安装完成后，Agent 直接调用上游工具。常见动作可以写成下面这样：

bash
# 读取任意网页，得到干净 Markdown
curl https://r.jina.ai/https://example.com/article

# 读取公开 GitHub 仓库
 gh repo view owner/repo

# 提取视频元数据和字幕相关信息
yt-dlp --dump-json https://www.youtube.com/watch?v=VIDEO_ID

# 搜索 B站视频
bili search "AI 教程" --type video

# 读取 B站字幕（需要 OpenCLI 会话）
opencli bilibili subtitle BVxxxx

# 通过 Exa 搜索网页
mcporter call 'exa.web_search_exa(query: "LLM framework", numResults: 5)'

这些命令体现了项目的边界：Agent Reach 负责让工具出现、让工具有可检查的配置、让渠道知道应当优先调用哪一个后端；工具返回的页面、代码、视频和帖子内容仍由 Agent 直接处理。渠道文件因此可以随着平台变化独立更新，Agent 的上层工作流不需要跟着每个平台的接口变化重写。

适合什么场景

需要同时读取网页、GitHub、视频、RSS 和多个社区平台时，统一安装与体检流程能减少重复配置。尤其是部署在个人电脑上的 AI Agent，常常同时面对浏览器登录态、命令行工具、代理和 Python 环境，单个平台的“能安装”并不等于“能使用”。Agent Reach 将这些状态拆开显示，使用者可以先启用零配置渠道，再按任务解锁 Cookie、MCP 或代理能力。

项目采用 MIT License，源码、安装文档、渠道实现和安全说明都在公开仓库中。对开发者来说，最值得复用的部分是它的渠道抽象和探测模型：把一个外部能力拆成候选后端、无副作用检查、活动后端和修复提示，能用于任何依赖第三方 CLI 或远程服务的 Agent 工具链。

来源：Agent-Reach GitHub 仓库 · 安装文档 · 英文文档 · 配置实现 · 渠道抽象 · 体检实现