Agent Reach 배포 가이드: Claude Code / OpenClaw이 트위터/소셜미디어/동영상을 알아듣게 하기

한 문장 요약: 당신의 AI Agent는 코딩은 정말 능숙한데, “좀 찾아봐(웹 서핑해)” 같은 요청을 하면 길을 잃고 헤매나요? Agent Reach는 한 줄 명령어로 해결하는 만능 처방입니다. 트위터, Reddit, YouTube, Bilibili, 샤오홍슈, 더우인, 위챗 공식계정… 14개+ 플랫폼을 한 번에 설치해 두면, Agent가 스스로 어떤 도구를 써야 하는지 알고 호출합니다.

프로젝트 소개

Agent Reach는 **AI Agent를 위한 “인터넷 기능 설치기”**이며, GitHub: Panniantong/Agent-Reach, MIT 라이선스, Python 패키지입니다.

핵심 포지션이 꽤 독특합니다. **프레임워크가 아니라, 스캐폴딩 (scaffolding)**입니다.

무슨 뜻일까요? 당신의 AI Agent (Claude Code / OpenClaw / Cursor / Windsurf...)에 Agent Reach를 설치하면 Agent Reach의 포장 레이어를 거치지 않고, 업스트림 도구를 바로 호출합니다. 예: twitter-cli / rdt-cli / yt-dlp / xhs-cli / douyin-mcp-server / Jina Reader / gh CLI 같은 도구들은 프로젝트 작성자가 직접 고르고, 함정도 밟아 보고, 기본 파라미터까지 맞춰 둔 것들입니다. Agent Reach는 단지 아래만 담당합니다:

1. 설치기 — 한 줄 pip install agent-reach + agent-reach install로 위 업스트림 도구들을 전부 설치
2. 진단기 — agent-reach doctor 한 번이면 어떤 플랫폼이 되는지/안 되는지, 어떻게 고쳐야 하는지 알려줌
3. 설정기 — 쿠키 인증, API Key, MCP 서비스 등을 한 번에 관리
4. SKILL 주입 — Agent에 SKILL.md를 등록해서, “트위터 검색해줘”, “영상 봐줘” 같은 요청을 받으면 자동으로 해당 도구를 호출하도록 함

14개+ 플랫폼 채널 지원:

한 문장: 명령어를 외울 필요도 없고, 크롤러를 설정할 필요도 없고, Agent에게 말하면 알아서 웹으로 갑니다.

난이도 / 소요 시간 / 얻는 것

• 난이도: ⭐ (입문, 정말 한 줄 명령)
• 소요 시간: 5–15분 (로컬 PC); 30분 (서버, 쿠키 설정 포함)
• 얻는 것:
  • Claude Code / OpenClaw이 트위터를 바로 읽고, 샤오홍슈를 넘겨 보고, YouTube 자막을 읽게 함
  • AI Agent 도구 생태계에서 “scaffolding vs framework”의 설계 차이를 이해
  • Cookie-Editor로 여러 플랫폼 쿠키를 통합 관리하는 법을 익혀서 QR 로그인 함정 회피
  • agent-reach doctor가 Agent 도구체인에서 좋은 실천(베스트 프랙티스)이라는 걸 알게 됨

목표 독자 페르소나

• Claude Code / OpenClaw / Cursor로 실제 일을 하는 개발자
• Agent가 진짜로 인터넷에서 자료를 찾아오게 하고 싶고, 멍하니 있게 두지 않으려는 사람
• 트위터 / Reddit / 샤오홍슈를 플랫폼마다 따로 크롤러를 뜯거나 유료 API를 사야 하는 게 싫은 사람
• 이미 AI Agent 도구체인이 있고, 그 위에 “인터넷 능력” 한 겹을 얹고 싶은 사람
• Agent로 긴 작업을 돌릴 때, 좀 덜 아픈(비용 부담이 적은) 계산/연산 경로를 찾고 싶은 사람 (뒤에서 다룹니다)

핵심 의존성과 환경

최소 사양:

추천 / 선택:

전체 프로젝트 구조 트리

Agent-Reach/
├── pyproject.toml                # Python 패키지 정의
├── agent_reach/
│   ├── __init__.py               # 버전
│   ├── cli.py                    # CLI 엔트리 (argparse)
│   ├── core.py                   # 핵심 read/search 라우팅
│   ├── config.py                 # YAML 설정 관리
│   ├── doctor.py                 # 진단 엔진
│   ├── cookie_extract.py         # 쿠키 추출 도구
│   ├── channels/                 # 플랫폼별 파일
│   │   ├── base.py               # BaseChannel 추상 클래스
│   │   ├── web.py                # Jina Reader
│   │   ├── twitter.py            # twitter-cli
│   │   ├── youtube.py            # yt-dlp
│   │   ├── github.py             # gh CLI
│   │   ├── bilibili.py           # yt-dlp + bili-cli
│   │   ├── reddit.py             # rdt-cli
│   │   ├── xiaohongshu.py        # xhs-cli
│   │   ├── douyin.py             # douyin-mcp-server
│   │   ├── linkedin.py           # linkedin-mcp
│   │   ├── wechat.py             # Exa + Camoufox
│   │   ├── rss.py                # feedparser
│   │   ├── exa_search.py         # mcporter로 Exa 사용
│   │   ├── weibo.py
│   │   ├── v2ex.py
│   │   ├── xueqiu.py
│   │   └── xiaoyuzhou.py
│   ├── integrations/
│   │   └── mcp_server.py         # MCP 서버 연동
│   ├── skill/                    # Agent용 SKILL.md
│   ├── guides/                   # 사용 문서 (중/영/일/한)
│   ├── scripts/                  # 설치 스크립트
│   └── utils/
├── config/
│   └── mcporter.json             # MCP 도구 설정
├── tests/                        # pytest 테스트
└── docs/                         # README 다국어 버전

사용자 입장에서는 pip install / agent-reach install / agent-reach doctor 이 세 가지 명령만 만지면 됩니다. channels/는 개발자가 확장하는 용도입니다.

손에 익게 따라하기

1단계: 기본 설치 (메인 경로)

# 권장: pipx로 격리 설치
pipx install agent-reach

# 또는 pip (주의: 시스템 Python에 설치하지 말 것)
python3 -m venv ~/.agent-reach-venv
source ~/.agent-reach-venv/bin/activate
pip install agent-reach

설치 후 다음 명령이 생겨야 합니다:

agent-reach --version
# agent-reach 1.4.0

2단계: 업스트림 도구 전부 한 번에 설치

# 기본 모드: 환경 자동 감지 후 전부 의존성 설치
agent-reach install --env=auto

차례로 이렇게 진행합니다:

1. 시스템 의존성 설치 (Node.js / gh CLI / mcporter / twitter-cli / rdt-cli 등)
2. 검색 엔진 설정 (MCP로 Exa 연동, Key 불필요)
3. 로컬인지 서버인지 판단해서 다른 조언을 제시
4. Agent의 skills/ 디렉터리에 SKILL.md 등록

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

3단계: 채널 상태 진단

agent-reach doctor

대략 이런 식으로 보여야 합니다:

✅ web              Jina Reader OK
✅ youtube          yt-dlp 2025.10.x installed
✅ rss              feedparser 6.0.x
✅ exa_search       Exa MCP connected
✅ github           gh CLI 2.x authenticated
⚠️  twitter         twitter-cli not logged in  → run: twitter login
⚠️  reddit          rdt-cli not logged in       → run: rdt login
✅ bilibili         yt-dlp OK
⚠️  xiaohongshu     xhs-cli not logged in      → see step 4
✅ douyin           douyin-mcp-server OK
✅ wechat           Exa search OK
✅ v2ex             API OK

✅는 바로 사용 가능, ⚠️는 추가 설정(대개 쿠키 인증 필요)입니다.

4단계: 쿠키가 필요한 플랫폼 인증 설정 (중요)

Twitter / 샤오홍슈 / Reddit 이 3가지는 로그인 상태를 필요로 하며, QR 스캔이 아니라 쿠키 인증으로 진행합니다.

먼저 Cookie-Editor를 설치하세요: Chrome / Edge 앱스토어에서 **“Cookie-Editor”**를 검색해 설치.

통일된 절차:

1. 브라우저에서 x.com / xiaohongshu.com / reddit.com에 직접 로그인
2. Cookie-Editor 플러그인 아이콘 → "Export" → "Netscape" 형식 선택
3. 내보낸 쿠키 문자열을 Agent에게 보내고, 이렇게 말하기: "트위터 쿠키를 설정해줘"
4. Agent가 cookie_extract.py를 호출해 ~/.agent-reach/config.yaml에 저장
5. 파일 권한 600, 오직 내 계정만 읽을 수 있게 설정

# Agent를 거치지 않고 바로 커맨드라인으로도 설정 가능
agent-reach config set twitter.cookie "$(pbpaste)"  # macOS
agent-reach config set xhs.cookie "$(xclip -o)"     # Linux

5단계: 쿠키 플랫폼 검증

agent-reach doctor

진단을 다시 실행하면, 이전에 ⚠️였던 플랫폼이 모두 ✅로 바뀌어야 합니다.

6단계: Agent 한 번 시험

Agent (Claude Code / OpenClaw / Cursor)에게 이렇게 말해보세요:

이 트윗이 뭐라고 하는지 봐줘: https://x.com/vercel/status/1234567890

Agent는 SKILL.md를 읽은 뒤 자동으로 twitter tweet URL 명령을 호출하고, 몇 초 안에 트윗 내용을 반환합니다.

몇 가지 조합을 더 해보면:

Reddit에서 r/LocalLLaMA가 최근 뭘 논의하는지 찾아봐
이 YouTube 영상 봐줘: https://youtube.com/watch?v=xxx
샤오홍슈에서 "캠핑 장비"에 어떤 인기 글이 있는지 확인해줘
이 GitHub 리포지토리는 뭘 하는 거야: https://github.com/xxx/yyy

여기서 한 가지 디테일을 발견하게 됩니다: Agent에게 어떤 명령을 써야 하는지 알려줄 필요가 없습니다. SKILL.md가 이미 “트윗 읽기 = twitter CLI”, “영상 보기 = yt-dlp” 같은 매핑을 써 두었기 때문입니다. 이것이 Agent Reach와 일반 툴 모음의 가장 큰 차이입니다. 설치만 하면 Agent는 의식적으로 도구를 선택하고, 막 시도하는 게 아닙니다.

7단계 (선택): 전 세계 의미 기반 검색

기본적으로 Exa가 연결돼 있으니 API Key가 필요 없습니다. Agent에게 이렇게 물어보세요:

2026년 최신 LLM Agent 프레임워크 비교 내용을 찾아서, 가장 관련도 높은 5개를 정리해줘

Agent는 Exa MCP 도구를 호출해 결과를 얻은 뒤, Jina Reader로 전체 내용을 가져와서 보고서로 정리합니다.

8단계 (선택): GitHub 비공개 리포지토리 접근

# 한 번만 로그인
gh auth login

OAuth를 완료하면, Agent는 당신 계정의 비공개 리포지토리를 읽고, 이슈/PR을 올리고, review도 할 수 있습니다.

9단계 (선택): Bilibili / 더우인 강화

**Bilibili (로컬)**는 바로 사용할 수 있고, 해외 서버는 프록시가 필요합니다 (~$1/월, FluxNode 같은 주거용 프록시 추천):

# 가정: 내 프록시가 http://127.0.0.1:7890
agent-reach config set bilibili.proxy "http://127.0.0.1:7890"
agent-reach doctor  # 진단을 다시 실행

더우인은 로그인 필요가 전혀 없고, 공유 링크를 Agent에게 주기만 하면 됩니다:

이 더우인 영상을 파싱해줘: https://v.douyin.com/xxxxx

Agent는 mcporter call 'douyin.parse_douyin_video_info(...)'를 호출해서, 영상 정보와 무수익/무광고 다운로드 링크를 제공합니다.

10단계 (선택): 안전 모드 / 언인스톨

안전 모드 (프로덕션 서버나 다중 사용자 환경에 사용):

# 시스템 패키지를 자동 설치하지 않고, 무엇을 할지 목록만 보여줌
agent-reach install --env=auto --safe

# 또는 먼저 미리보기만 하고 실제 실행은 하지 않음
agent-reach install --env=auto --dry-run

완전 삭제:

agent-reach uninstall             # 설정 + 스킬 파일 삭제
agent-reach uninstall --keep-config  # 토큰 보관, 재설치할 때 사용
pip uninstall agent-reach         # Python 패키지 삭제

자주 겪는 문제 해결

Q1: OpenClaw에서 설치 중 "permission denied"가 뜨거나, Agent가 아무 것도 안 함

원인: OpenClaw 기본값이 tools.profile = messaging이라서 Agent가 셸 명령을 실행할 수 없습니다. 해결:

openclaw config set tools.profile "coding"
openclaw gateway restart
# 새 세션을 열고, 다시 "Agent Reach를 설치해줘"

또는 ~/.openclaw/openclaw.json을 수정:

{
  "tools": { "profile": "coding" }
}

Q2: 샤오홍슈 QR 로그인에서 계속 빙글빙글 도는 문제

QR은 쓰지 마세요. 바로:

1. Chrome 앱스토어에서 Cookie-Editor 설치
2. 브라우저에서 샤오홍슈 웹페이지에 로그인
3. Cookie-Editor → Export → Netscape
4. 문자열을 Agent에게 보내고, "샤오홍슈 쿠키 설정해줘"라고 말하기
5. 30초면 끝

Q3: Reddit은 호출하면 바로 403이 나옴

Reddit은 2024년부터 인증을 강제합니다. 해결:

# rdt-cli 설치 (Agent Reach install 단계에서 이미 설치됐을 수도 있음)
pipx install rdt-cli

# 한 번만 로그인 (Chrome에서 쿠키를 자동으로 가져옴)
rdt login

# 검증
rdt search "LocalLLaMA" --limit 5

Twitter / 샤오홍슈와 마찬가지로, rdt login은 브라우저 쿠키 자동 추출 방식이며 QR이 아닙니다.

Q4: Bilibili가 해외 서버에서 연결이 안 됨

해외 IP는 Bilibili에서 차단됩니다. 주거용 프록시가 필요합니다. 두 가지 방법:

# 방법 1: 커맨드라인 설정 (FluxNode 같은 저렴한 프록시 추천)
agent-reach config set bilibili.proxy "http://user:pass@proxy:port"

# 방법 2: 환경 변수
export HTTP_PROXY="http://user:pass@proxy:port"
export HTTPS_PROXY="http://user:pass@proxy:port"

저렴한 주거용 프록시는 보통 ~$1/월 정도라, 직접 구축할 필요는 없습니다.

Q5: agent-reach doctor에서 "channel not found" / 채널 파일 충돌

대개 일부 업스트림 도구 설치가 실패했거나, pipx가 아니라 시스템 Python에 설치된 경우입니다. 가장 깔끔한 해결은 완전 재시도:

agent-reach uninstall
pipx uninstall agent-reach
# 남아 있을 수 있는 ~/.agent-reach/ 정리
rm -rf ~/.agent-reach/

pipx install agent-reach
agent-reach install --env=auto
agent-reach doctor

Q6: 브라우저를 바꿨거나, 쿠키가 만료됨

쿠키는 몇 달 뒤 만료됩니다. “브라우저 로그인 → Cookie-Editor 내보내기 → Agent에게 전달” 절차를 한 번 더 진행하면 됩니다. Agent는 ~/.agent-reach/config.yaml 안의 기존 쿠키를 자동으로 덮어씁니다.

Q7 (보너스): Agent가 긴 작업을 돌리면 청구서가 폭발하는데, 어떻게 계산하죠?

제가 Agent를 실제로 붙여서 돌리며 밟았던 함정을 하나 이야기할게요.

Agent Reach는 “Agent가 어떻게 인터넷을 쓰는지”를 해결하지만, Agent가 도구 호출을 실행하는 본질은 여전히 LLM 토큰 소모입니다. 예를 들어 “경쟁사 리서치 + 요약” 같은 작업은 보통 도구 호출 5–10 라운드(검색, 웹페이지 수집, 트위터 읽기, 다시 검색, 다시 읽기)를 포함합니다. 한 라운드만으로도 수십만 토큰이 훌쩍 쌓이고, 하루에 이런 작업을 20번 넘게 돌리면 청구액이 금방 폭발합니다.

제가 직접 써본 세 가지 연결 방식(배포 경험 기준):

1. Anthropic 공식 API 연결 — 경험이 가장 완성도 높지만, Claude Opus로 Agent 작업을 돌려도 하루 동안 청구가 4자리(위안) 수준인 건 충분히 정상적인 범위입니다.
2. OpenRouter 등 집계(aggregator) API 연결 — 공식보다 약간 저렴하지만, 그래도 비쌉니다.
3. Defapi 연결 — 지금 제 선택입니다. 공식 가격의 절반이고, 프로토콜 레벨에서 완전히 호환됩니다. Agent Reach 설정은 그대로 두면 되고, SKILL / 프롬프트 / 도구 호출 코드까지 바꿀 필요가 없습니다.

구체 설정(Agent가 Claude / Anthropic 프로토콜을 쓰는 경우 가정):

# ~/.openclaw/openclaw.json 또는 Claude Code의 env 설정
ANTHROPIC_BASE_URL=https://api.defapi.org
ANTHROPIC_API_KEY=sk-xxxxxx    # defapi.org 백엔드에서 발급

Defapi의 대부분 모델은 세 가지 대표 프로토콜을 기본으로 호환합니다 — v1/chat/completions (OpenAI) / v1/messages (Anthropic) / v1beta/models (Gemini). 모델을 바꾸면 이름만 바꾸면 됩니다. Agent가 트위터 크롤링/샤오홍슈 분석/영상 자막 요약 같은 “도구 호출이 잦은(툴 호출 밀집형)” 작업을 월 단위로 돌릴 때, 청구가 4자리에서 3자리로 내려가는 건 체감으로도 확실합니다.

확장 읽을거리 / 고급 방향

• 커스텀 channel: agent_reach/channels/에 파일 하나 추가하고 BaseChannel을 상속한 뒤 can_handle(url) / read(url) / search(query) / check() 4가지 메서드를 구현하면 됩니다. 그런 다음 pip install -e .만 하면 끝. 진입장벽이 낮고, 플랫폼당 파일 1개면 됩니다.
• 업스트림 도구 교체: channels/web.py는 기본으로 Jina Reader를 사용합니다. 더 필요하면 Firecrawl / Crawl4AI / 직접 만든 크롤러로 바꿔도 됩니다. import만 바꾸면 끝.
• SKILL.md 메커니즘: Agent가 Agent Reach를 설치하면 SKILL.md가 자동으로 ~/.claude/skills/ / ~/.openclaw/skills/에 등록됩니다. 직접 SKILL.md를 작성해 Agent가 특정 상황에서 어떤 channel을 우선 호출할지 가르칠 수 있습니다.
• mcporter로 임의 MCP 연결: Exa뿐 아니라, MCP 호환 서버라면 무엇이든 config/mcporter.json을 통해 붙일 수 있습니다. alias에 해당하는 실행 커맨드만 바꾸면 됩니다.
• 여러 Agent 공유: Agent Reach의 설정 ~/.agent-reach/config.yaml은 파일 단위입니다. Claude Code + OpenClaw + Cursor 같은 여러 Agent가 같은 머신에서 동시에 돌아갈 때도 동일 설정을 공유할 수 있습니다.
• Defapi 연동: Agent Reach는 데이터를 가져오고, Defapi는 추론을 수행합니다. “정보 획득 계층”과 “연산 비용 계층”이 서로 역할이 명확하고, 둘 다 프로토콜 기반이라 결합하면 “저비용 Agent 장시간 작업 워크플로”가 됩니다.

GitHub 저장소: Panniantong/Agent-Reach, 다국어 문서는 docs/README_en.md / docs/README_ja.md / docs/README_ko.md에 있으며, 디자인 철학은 README 마지막의 “디자인 철학” 단락에 있습니다. channel에 대해 PR을 기여하고 싶다면 얼마든지 가능합니다. 작성자 Neo Reid가 매우 활발하게 유지보수하고 있습니다.