作者注：從對 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 文檔中心
