Agent-Reach 쓰는 법

Agent Reach(Panniantong/Agent-Reach)는 코딩 에이전트에 웹·소셜·영상·코드 저장소를 읽고 검색할 눈을 붙이는 MIT 오픈소스 CLI다. Twitter/X, Reddit, YouTube, GitHub, Bilibili, 소홍서(小红书) 등 플랫폼마다 달라지는 접속 방식을 선택·설치·진단·라우팅해 주는 능력 층(capability layer)이지, 읽기 자체를 감싸는 래퍼는 아니다. 이 글은 “Agent-Reach 쓰는 법”만 따라간다.

설치·명령·버전은 공식 README(GitHub), docs/install.md, pyproject.toml, 릴리스 v1.5.0만 근거로 적는다. README가 경고하듯 PyPI의 동명 패키지는 이 프로젝트가 아니다. GitHub 아카이브에서 설치하자.

핵심 요약 (TL;DR)

• 무엇인가: 에이전트가 인터넷·소셜·영상을 읽고 검색하도록, 플랫폼별 최선 백엔드를 골라 설치하고 doctor로 상태를 보는 CLI 능력 층.
• 요구사항: Python >=3.10 (pyproject.toml). 권장 설치는 pipx 또는 전용 venv.
• 버전(작성 시점): agent-reach 1.5.0 (최신 GitHub Release v1.5.0 / pyproject.toml). 라이선스 MIT.
• 한 줄 설치(사람에게): 에이전트에게 Install Agent Reach: https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md 를 복사해 준다.
• 수동 핵심: pipx install https://github.com/Panniantong/agent-reach/archive/main.zip → agent-reach install --env=auto(기본은 읽기 전용 점검) → 승인 후 --system → agent-reach doctor.
• 기본 안전: install은 기본적으로 시스템 패키지를 건드리지 않는다. 외부 도구 설치·설정 쓰기는 명시적 --system이 필요하다.

할 수 있는 일

먼저 용어만 짧게 풀어 둔다.

• 코딩 에이전트: Claude Code, Cursor, Windsurf, OpenClaw처럼 터미널에서 명령을 실행하며 작업을 대신하는 AI 조수.
• 능력 층(capability layer): README 표현. 읽기/검색은 상위 도구(yt-dlp, gh, OpenCLI 등)가 하고, Agent Reach는 무엇을 쓸지 고르고·설치하고·검진한다.
• 채널(channel): 웹, YouTube, GitHub, Twitter 등 플랫폼별 라우트. 각 채널은 선호+예비 백엔드 목록이다.
• MCP: Model Context Protocol. Exa 검색(mcporter), LinkedIn 등 일부 채널이 MCP로 붙는다.
• doctor: agent-reach doctor — 어떤 채널이 살아 있고 지금 어떤 백엔드를 쓰는지 보여 주는 진단 명령.

공식 README 기준으로, 설치 직후(추가 로그인 없이) 쓸 수 있는 쪽과 설정 후 열리는 쪽이 나뉜다.

• 제로 설정에 가까운 것: 임의 웹 페이지 읽기(Jina Reader), YouTube 자막·검색(yt-dlp), 공개 GitHub(gh), RSS/Atom(feedparser), Bilibili 검색·상세(bili-cli, 로그인 불필요), V2EX 공개 API.
• 설치 중/후 붙는 검색: Exa 시맨틱 웹 검색(MCP·mcporter 경로, README상 무료·키 자동 구성 흐름).
• 로그인·쿠키·데스크톱 세션이 필요한 것: Twitter/X 검색·타임라인, Reddit, Facebook, Instagram, 소홍서, LinkedIn 상세, Boss直聘 등. 에이전트에게 “XXX 설정 도와줘”라고 하면 가이드가 이어진다.

호환 대상(README): Claude Code, OpenClaw, Cursor, Windsurf 등 셸 명령을 실행할 수 있는 에이전트.

필요한 것

링크: GitHub · 설치 가이드 · 한국어 README · v1.5.0 릴리스.

단계

0) OpenClaw만 — exec 먼저

OpenClaw를 쓰는 경우, README가 설치 전에 exec 프로필을 요구한다. 기본 messaging 프로필이면 pip/mcporter 같은 명령을 에이전트가 못 돌린다.

openclaw config set tools.profile "coding"

또는 ~/.openclaw/openclaw.json에 "tools": { "profile": "coding" } 후 Gateway 재시작(openclaw gateway restart)과 새 대화. Claude Code·Cursor·Windsurf는 이 제한이 없다.

1) 가장 쉬운 길 — 에이전트에게 install.md 넘기기

사람에게 권장하는 한 줄(영문 README Quick Start):

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

한글 README/install.md 문구:

帮我安装 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md

에이전트가 CLI 설치 → 환경 점검 → (승인 시) 시스템 의존성·스킬 등록까지 이어 간다. 업데이트도 같은 패턴으로 docs/update.md를 넘기면 된다.

2) 수동 설치 — pipx (권장)

pipx install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto
# 시스템 변경을 명시적으로 허용한 뒤에만:
agent-reach install --env=auto --system

3) Homebrew/PEP 668 — venv

macOS Homebrew Python 등이 externally-managed-environment를 내면 install.md가 권하는 경로다.

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
agent-reach install --env=auto --system

4) 스킬로 붙이기 (Claude Code / Skills 지원 에이전트)

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

스킬 설치 후 에이전트가 agent-reach CLI 유무를 보고 없으면 설치를 이어 간다(영문 README).

5) 설치 모드 정리

--system 기본으로 켜지는 제로 설정 쪽 예(install.md): Web(Jina), YouTube, GitHub, RSS, Exa Search, V2EX, Bilibili(기본).

6) 옵션 채널 — 필요한 것만

기초가 끝나면 에이전트/문서가 메뉴를 제시한다. 예:

agent-reach install --env=auto --system --channels=opencli,twitter
agent-reach install --env=auto --system --channels=all

지원 채널 이름(install.md): opencli, twitter, xiaoyuzhou, xueqiu, xiaohongshu, reddit, facebook, instagram, bilibili, linkedin, boss, all.

쿠키가 필요한 플랫폼은 Cookie-Editor로 사용자가 직접 Export한 문자열을 넘기는 흐름이 기본이다. Twitter는 저장 후에도 실제 twitter CLI 호출 전에 프로세스 환경에 TWITTER_AUTH_TOKEN / TWITTER_CT0를 명시해야 한다(README).

7) 진단 — doctor

agent-reach doctor
agent-reach doctor --json

다백엔드 채널은 active_backend가 “지금 쓰는 길”이다. 고장난 백엔드는 처방(재설치 명령 등)을 준다. 정기 점검용으로 agent-reach watch / check-update도 있다.

8) 일상에서 쓰는 법

명령을 외울 필요는 없다. 스킬/README를 읽은 에이전트에게 자연어로 시키면 된다. 참고용 업스트림 예(install.md Quick Reference):

• 웹: curl -s "https://r.jina.ai/URL"
• GitHub: gh search repos "query" / gh repo view owner/repo
• YouTube: yt-dlp --dump-json URL
• Bilibili: bili search "query" --type video
• Exa: mcporter call exa.web_search_exa query="..." numResults=5

막히는 지점

보안 메모(README): 쿠키·브라우저 세션이 필요한 플랫폼은 전용 부계정을 권한다. 스크립트/API 호출은 계정 제재 위험이 있고, 쿠키는 사실상 전체 로그인 권한이다. 자격 증명은 ~/.agent-reach/에만 두고 업로드하지 않는다.

디렉터리 규칙(install.md): 설정·도구 클론은 ~/.agent-reach/·~/.agent-reach/tools/에만. 에이전트 작업 디렉터리(프로젝트 워크스페이스) 안에 클론·임시 파일을 만들지 말 것.

제거:

agent-reach uninstall
# 또는 미리보기
agent-reach uninstall --dry-run
pip uninstall agent-reach

마치며

Agent Reach는 “또 하나의 스크래퍼”가 아니라, 에이전트가 인터넷을 볼 때 쓰는 길을 골라 주고 고쳐 주는 층이다. 버전 1.5.0 기준으로 다백엔드 라우팅과 실측 doctor가 핵심이다. 오늘은 공식 채널만으로 CLI를 올리고, 제로 설정 채널부터 확인한 뒤, 꼭 필요한 로그인 채널만 여는 순서가 가장 덜 아프다.

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.