作者注：从对 Agent 说一句话开始，手把手装好 Agent-Reach，让 Claude Code、Codex 等 Agent 读到小红书笔记、X 动态、B 站字幕，附渠道表、命令对照、排错与成本估算。
让 Agent 做一次竞品调研，它很快会撞墙。你让它“看看小红书上大家怎么评价这款耳机”，自带的网页搜索只会返回几篇搬运文章，小红书笔记本身根本搜不到。你让它“总结某个 X 账号这周发了什么”，它打不开登录墙后面的时间线。
视频内容的情况更糟。一个 40 分钟的 B 站技术分享，真正有价值的信息都在口播里。通用搜索拿不到 B 站字幕，Agent 只能看着标题和简介瞎猜。雪球、V2EX 这些中文平台在通用搜索里覆盖也很差，拿回来的网页还夹杂着大量导航和广告。
这正是开源项目 Agent-Reach 要解决的问题。它在 GitHub 上已有超过 10 万 Star，定位是“让 AI Agent 够得着它自己上不去的互联网”。这不是又一个需要你啃命令行的工具：本教程的主线是对 Agent 说一句话完成安装，之后的加渠道、换账号、升级也都用大白话完成。
核心价值：读完本文，你将让自己的 Agent 读到 X、Reddit、B 站、小红书等平台的内容，并且清楚每一步怎么验收、出错怎么排查、一次调研大概花多少钱。
Agent-Reach 教程核心要点
在动手之前，先用一张表把 Agent-Reach 的关键事实理清楚。以下信息基于 2026-10-26 对项目仓库的查证。
| 要点 | 说明 | 对你的价值 |
|---|---|---|
| 项目热度 | Star 超过 10 万，曾登 Trendshift GitHub Trending 当日第一 | 社区活跃，问题有人跟进 |
| 许可证与环境 | MIT 开源，Python 3.10+ 编写 | 可免费使用，可自行审阅代码 |
| 平台费用 | 本身免费，不需要任何平台 API 费 | 真正的成本只有 Agent 的模型 token |
| 工作方式 | 只读：只搜索和读取，不发帖、不评论、不点赞、不私信 | 不会替你在平台上“说话” |
| 输出格式 | 1.6 及以后每条命令输出一个 JSON 对象 | Agent 读 ok / result / error.hint 即可判断成败 |
Agent-Reach 解决的四类“够不着”
Claude Code、Codex、Hermes Agent、OpenClaw 这类 CLI Agent 都自带搜索和网页读取，但有四类内容它们天然够不着。第一类是要登录才能用的功能，比如在小红书搜笔记、在 X 查账号动态、读职位详情。第二类是视频里的内容，包括 B 站和 YouTube 的字幕，以及 YouTube 视频、小宇宙播客的语音转文字。
第三类是中文平台，B 站、小红书、V2EX、雪球在通用搜索里覆盖很差。第四类是干净的结构化数据，比如雪球行情、V2EX 帖子和回复、GitHub 仓库和 issue。Agent-Reach 拿回来的是整理好的内容，而不是一整页 HTML，这能直接减少 Agent 消耗的 token。
Agent-Reach 的设计思路：首选加备选
Agent-Reach 把每个平台的每个动作都设计成一个“按顺序尝试的工具列表”。例如读 B 站视频先用 bili-cli，失败后自动换成 B 站公开接口；读网页先用 Jina Reader，再用 Exa。平台改版、工具失效是常态，维护者只需调整这个列表，你和 Agent 的用法完全不变。
Agent-Reach 支持哪些渠道
当前版本把渠道分成三个等级：默认渠道装好就能用；可选渠道对 Agent 说一句“帮我加上 XX”即可开启，所需软件会自动装好；实验渠道能用，但平台反爬更严，可能随时失效。下面这张表建议收藏，它回答了“能做什么”和“需要什么”两个最常见的问题。
| 渠道 | 等级 | 能做什么 | 需要什么 |
|---|---|---|---|
| bilibili | 默认 | 搜索、视频信息、热门、字幕 | 字幕需要扫码登录 |
| v2ex | 默认 | 热门、节点、帖子和回复、用户 | 无需登录 |
| github | 默认 | 搜仓库、读仓库和 README、读 issue 和 PR（含评论） | 无需登录 |
| youtube | 默认 | 视频信息、搜索、字幕、语音转文字 | 转文字需要 Groq 或 OpenAI Key |
| web | 默认 | 网页搜索、网页阅读（保底渠道） | 无需登录 |
| xiaohongshu | 可选 | 搜笔记、读正文、看评论 | 需要登录 |
| xueqiu | 可选 | 实时行情、搜股票、热帖、热股 | 行情不用登录，热帖热股要登录 |
| boss | 可选 | 搜职位和 JD | 需要登录 |
| xiaoyuzhou | 可选 | 播客转文字 | 需要 Groq Key |
| 可选 | 搜职位、读职位详情 | 公开职位不用登录，站内搜索要登录 | |
| 可选 | 搜帖子、读正文、看评论、看版块 | 需要登录 | |
| twitter（X） | 实验 | 搜推文、用户资料、用户推文、读推文串 | 需要登录 |
| 实验 | 搜索、主页资料 | 需要登录 | |
| 实验 | 搜用户、主页资料、用户帖子 | 需要登录 |
有一点值得注意：默认渠道如果你不想要可以去掉，去掉之后以后更新也不会再自动加回来。标题里提到的 X 目前属于实验渠道，适合偶尔查询，不适合当作每天依赖的稳定数据源。
Agent-Reach 快速上手：对 Agent 说一句话
整个安装流程不需要你打开终端。下面每一步都附上“验收标准”，确认通过再进入下一步，出问题时可以直接对照后文的排错表。
第 1 步：在 Agent 设置里打开“允许执行命令”
Agent-Reach 需要 Agent 能执行终端命令。在你所用 Agent 的图形化设置界面里找到“允许执行命令”一类的开关并打开，不同 Agent 叫法略有差异。电脑上没有 uv 也不用担心，Agent 会先自动安装 uv，只需一条命令，不需要管理员密码。
- 验收标准：对 Agent 说“告诉我当前所在的目录”，它真正执行了命令并返回一个路径，而不是回复“我无法执行命令”。
第 2 步：把安装语句发给 Agent
这是官方推荐的最省事方式。直接复制下面这句话发给 Agent 即可：
帮我安装 Agent Reach：https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/install.md
Agent 读完安装说明后会自己完成两件事：先执行 uv tool install https://github.com/Panniantong/Agent-Reach/releases/latest/download/agent-reach.zip，再执行 agent-reach setup。所有文件统一放在 ~/.agent-reach/ 这一个文件夹里，以后升级、管理、删除都很方便。
- 验收标准：Agent 回报安装完成，并且执行
agent-reach channels后返回的 JSON 里ok为 true，result中列出了渠道清单。
第 3 步：让 Agent 检查渠道状态
对 Agent 说“看看 Agent Reach 状态”。它会告诉你每个渠道现在能不能用，以及哪些渠道是上次还好、现在坏了。这一步相当于体检，后续遇到奇怪问题时也建议先做它。
- 验收标准：bilibili、v2ex、github、youtube、web 五个默认渠道显示可用；B 站字幕、YouTube 转文字这类需要额外条件的功能提示“需登录”或“需 Key”属于正常现象。
第 4 步：加上可选渠道并完成登录
以小红书为例，对 Agent 说“帮我加上小红书”，它会自动装好所需软件。需要登录的平台由 Agent-Reach 自带的专用浏览器处理，后台运行、不弹窗，而且专用浏览器只对这台电脑开放。它从不替你登录，也不会向你要密码。
部分平台会复用你电脑上已有的登录状态，只复制这一个网站的登录，原浏览器不变，也不读密码库。这里请务必看完下一节的风险提示，如果复用到的是主账号，对 Agent 说“换个账号”改用小号。
- 验收标准：再次说“看看 Agent Reach 状态”，xiaohongshu 显示可用；接着让 Agent 搜一个关键词，返回结果中包含笔记标题和正文片段。
第 5 步：跑第一个跨平台调研任务
用自然语言描述目标即可，例如：“用 Agent Reach 查一下大家对某款机械键盘的评价，分别看小红书笔记、B 站评测视频字幕和 Reddit 讨论，最后按平台分别总结。”Agent 会自己拆解成多条 agent-reach <渠道> <动作> [参数] 命令去执行。
- 验收标准：Agent 的总结按平台分开列出，每条观点能对应到具体的笔记、视频或帖子；如果某个渠道失败，它能转述
error.hint中的提示，而不是悄悄跳过。
🚀 快速上手建议：Agent-Reach 只负责把内容拿回来，理解和总结靠的是 Agent 背后的大模型。如果你的 Agent 支持自定义模型接口，可以通过 API易 apiyi.com 用一个 API Key 接入 Claude、GPT、Gemini 等模型，新用户有免费测试额度，适合先低成本跑通第一个调研任务。
如何给 Agent 配置 API易 模型接口
如果你的 Agent 支持 OpenAI 兼容接口，配置思路如下，具体字段名以你所用 Agent 的设置界面为准：
- 接口地址（base_url）：
https://api.apiyi.com/v1 - API Key：在 API易 控制台创建的 Key
-
模型名：日常调研建议
claude-sonnet-5-5，批量轻量任务可选claude-haiku-5-5 -
验收标准：在 Agent 里发一句“你好，告诉我你是哪个模型”，能正常返回内容，且 API易 控制台里出现对应的调用记录。
Agent-Reach 常用命令对照表
日常使用时直接对 Agent 说左列的话就够了。右侧命令供你理解 Agent 在背后做了什么，或在自己终端里排查问题时使用。
| 你对 Agent 说的话 | Agent 背后执行的命令 | 用途 |
|---|---|---|
| “有哪些渠道，各能做什么” | agent-reach channels |
查看渠道与能力 |
| “在 B 站搜一下大模型” | agent-reach bilibili search "大模型" |
统一格式：渠道 + 动作 + 参数 |
| “读一下这个链接” | agent-reach read <链接> |
按链接自动选择渠道 |
| “升级 Agent Reach” | agent-reach update |
一次更新程序、各渠道工具和 skill |
| “安装完说命令找不到” | uv tool update-shell 后开新 shell |
修复命令路径 |
| （自己在终端里做） | agent-reach configure groq-key |
填写语音转文字所需的 Key |
| “卸载 Agent Reach” | 先列出要删的内容，确认后再删 | 安全卸载 |
除此之外，“去掉小红书”“小红书登录过期了”“退出登录”“让另一个 AI 也能用”这些说法也都可以直接对 Agent 说，不需要记任何命令。
Agent-Reach 风险提示（使用前必读）
⚠️ 请在使用 Agent-Reach 前认真阅读本节
- 这是社区开源工具，不是任何平台的官方授权 API。 我们只是推荐这个项目，不对其稳定性、安全性和合规性做任何担保。
- 账号存在被限流或封禁的可能。 X、小红书、Reddit 等平台可能把自动化访问判定为异常行为。官方 README 同样明确建议使用小号，请不要用重要账号来跑 Agent。
- 复用本机登录可能带出主账号。 部分渠道会复用电脑上已有的登录状态，而你平时登录的通常是主账号。开启渠道后请先确认当前用的是哪个账号，必要时对 Agent 说“换个账号”切到小号。
- 后果自负。 封号、限流、数据抓取与使用的合规问题等一切后果，由读者自行判断并承担，与 API易 平台及本文作者无关。
- 认准安装来源。 PyPI 上名为 agent-reach 的包不是本项目，只能从 GitHub 地址安装；项目没有任何官方代币、币、投资产品或钱包连接，借用这个名字的加密项目都与本仓库无关。
Agent-Reach 排错表
下面五个问题是上手阶段最常见的情况，每一条都可以照着做。排查前建议先让 Agent 执行一次“看看 Agent Reach 状态”，并让它把 error.hint 原文告诉你。
| 现象 | 原因 | 解决办法 |
|---|---|---|
装完后提示 agent-reach 命令找不到 |
uv 的工具目录还没加入命令路径 | 让 Agent 执行 uv tool update-shell，然后新开一个 shell（或重启 Agent）再试 |
| Agent 回复“我无法执行命令” | 未打开执行命令权限 | 回到第 1 步，在 Agent 设置中打开“允许执行命令” |
| 从 1.5 升级后各种报错 | 1.5 及更早版本是 pipx/pip 安装的 | 让 Agent 执行 uv tool install --force 加上 GitHub 安装地址，再跑 agent-reach setup，密钥和设置会保留 |
| 小红书突然搜不到内容，提示需要登录 | 登录状态过期 | 对 Agent 说“小红书登录过期了”，按提示重新登录（建议用小号） |
| X 渠道时好时坏 | twitter 属于实验渠道，平台反爬更严 | 先看状态确认是否失效，失效时等待项目更新后执行 agent-reach update，也可到 GitHub Issues 反馈 |
Agent-Reach 成本与模型选择
Agent-Reach 本身免费，也没有平台 API 费，真正花钱的是执行它的 Agent 调用大模型时消耗的 token。下面是 2026-10-26 在 API易 apiyi.com 文档中心查到的三个型号价格，单位为美元/百万 tokens，型号与价格以平台型号列表为准。
| 模型 | 输入 | 输出 | 缓存读 | 适合的 Agent-Reach 任务 | 可用平台 |
|---|---|---|---|---|---|
| claude-opus-5-5 | $4 | $20 | $0.2 | 长篇调研报告、多源信息交叉验证 | API易 apiyi.com |
| claude-sonnet-5-5 | $2 | $10 | $0.1 | 日常跨平台调研的主力选择 | API易 |
| claude-haiku-5-5 | $0.1 | $0.5 | $0.01 | 批量摘要、简单检索、状态巡检 | API易 |
我们给一个粗略估算（非实测）：一次跨 4 个平台的调研，Agent 读 5 篇长帖再加 20 条搜索结果，输入约 3 万到 6 万 token，输出约 3 千到 6 千 token。按 claude-sonnet-5-5 计算，单次大约 0.1 美元上下；换成 claude-haiku-5-5 大约不到 1 美分；换成 claude-opus-5-5 大约在 0.2 到 0.35 美元之间。
选择建议很直接：先用 sonnet 跑通流程，再根据结果质量决定是否升级到 opus，重复性的批量任务交给 haiku。Agent-Reach 返回的是整理好的结构化内容，本身就比让 Agent 读原始网页节省 token，长期使用时还可以留意缓存读价格带来的节省。
常见问题 FAQ
Q1：Agent-Reach 真的完全不花钱吗？
Agent-Reach 本身免费、MIT 开源，各平台也不收 API 费。你需要支付的只有 Agent 调用大模型的 token 费用，按上文估算，一次跨 4 个平台的调研用 sonnet 级模型大约 0.1 美元上下。想先试水，可以通过 API易 apiyi.com 领取新用户免费测试额度来跑第一个任务。
Q2：Agent 会不会用我的账号发帖、点赞或私信？
不会。Agent-Reach 是只读工具，只搜索和读取，不发帖、不评论、不点赞、不私信。但只读不等于零风险，平台仍可能把高频读取判定为异常访问，所以依然建议使用小号，详见风险提示一节。
Q3：YouTube 和小宇宙的语音转文字怎么开？Key 要发给 Agent 吗？
YouTube 转文字需要 Groq 或 OpenAI Key，小宇宙需要 Groq Key。**不要把 Key 直接发在聊天里**，官方要求在你自己的终端里执行 `agent-reach configure groq-key` 填写。验收方法：让 Agent 对一个 YouTube 视频做转文字，返回的 JSON 中 `ok` 为 true 且有文字内容。
Q4：Agent-Reach 搭配哪个模型效果最好？
日常调研建议从 claude-sonnet-5-5 开始，它在理解多源内容和控制成本之间比较平衡；需要深度分析时再切到 claude-opus-5-5。通过 API易 apiyi.com 一个 Key 就能在这几个型号间切换，只改模型名，不用改接口地址，方便用同一个调研任务直接对比效果。
Q5：已经在 Claude Code 里装好了，怎么让另一个 Agent 也能用？
直接对已装好的 Agent 说“让另一个 AI 也能用”，它会处理共享配置。由于所有文件都统一放在 `~/.agent-reach/` 文件夹中，另一个 Agent 只要同样打开了执行命令权限即可调用。验收方法：在新 Agent 里说“看看 Agent Reach 状态”，能返回与原 Agent 一致的渠道列表。
Agent-Reach 教程核心要点 Key Takeaways
- 一句话定位：Agent-Reach 让 Agent 读到登录墙后、视频里和中文平台上的内容。
- 安装方式：把官方 install.md 链接发给 Agent，它会自己装 uv 和 agent-reach。
- 三级渠道：默认 5 个开箱即用，可选 6 个一句话开启，实验 3 个可能随时失效。
- 只读设计：不发帖、不点赞、不私信，输出统一为带
ok字段的 JSON。 - 账号安全：社区工具非官方 API，可能触发限流封号，务必使用小号。
- 成本可控：平台 API 费为 0，主要成本是模型 token，可经 API易 apiyi.com 按量计费接入。
总结
Agent-Reach 教程的核心要点：
- 解决真痛点：通用搜索搜不到的小红书笔记、X 账号动态、B 站字幕，现在 Agent 可以直接读取。
- 上手零门槛：对 Agent 说一句话完成安装，后续加渠道、换账号、升级都用大白话。
- 风险要自知：这是社区开源工具，用小号、看清复用的账号，后果自行判断承担。
建议先用默认渠道跑通一次 B 站或 GitHub 的调研，确认每一步验收都通过后，再按需加上小红书、Reddit 等需要登录的渠道。
需要模型可以走 API易 apiyi.com。
📚 参考资料
- Agent-Reach GitHub 仓库：项目源码、README 与渠道说明
- 链接：
github.com/Panniantong/Agent-Reach -
说明：唯一可信的安装来源，渠道列表与安全说明以此为准
-
Agent-Reach 官方安装说明：供 Agent 读取的安装文档
- 链接：
raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/install.md -
说明：本文第 2 步发给 Agent 的就是这个地址
-
Agent-Reach GitHub Issues：问题反馈渠道
- 链接：
github.com/Panniantong/Agent-Reach/issues - 说明：实验渠道失效、安装报错时可在此搜索或反馈
作者：APIYI 技术团队
技术交流：欢迎在 API易 网站首页联系我们，更多资料可访问 docs.apiyi.com 文档中心
