oh-my-opencode 4.12.1 → 4.14.0

package/packages/omo-codex/plugin/skills/ultimate-browsing/references/insane-search/playwright.md

@@ -0,0 +1,142 @@
+# Playwright — MCP vs Local Chrome
+
+> JS 렌더링 / JS 챌린지 사이트를 위한 두 가지 접근. **WAF 프로파일의
+> `capabilities_needed` 태그가 선택을 결정**한다. 사용자가 직접 고를 필요 없다.
+
+## 두 Approach 요약
+
+| Approach | 실행기 | TLS 스택 | 적합 WAF | 한계 |
+|----------|--------|----------|----------|------|
+| **1. MCP** | `mcp__playwright__*` 도구 | Playwright 번들 Chromium (BoringSSL) | Cloudflare 기본, CAPTCHA 없는 SPA, JS 챌린지 약한 사이트 | Akamai Bot Manager 등 TLS-감지형 WAF에 **즉시 탐지됨** (`channel` 옵션 없음) |
+| **2. Local Node + `channel:'chrome'`** | `engine/templates/playwright_real_chrome.js` | 시스템 설치 실제 Chrome | Akamai Bot Manager, PerimeterX, DataDome 강화 설정 | Node + Chrome 시스템 설치 필요 |
+
+`engine/executor.py`가 프로파일 태그를 보고 자동 라우팅하므로, 이 선택을 스킬 외부에서 의식할 필요는 없다.
+
+## Approach 1 — Playwright MCP
+
+### 의존성
+
+```bash
+claude mcp list 2>/dev/null | grep -q playwright && echo "OK" || echo "NOT CONNECTED"
+claude mcp add playwright -- npx @playwright/mcp@latest
+```
+
+### 기본 워크플로
+
+```
+1. browser_navigate → URL
+2. browser_wait_for → 메인 콘텐츠 셀렉터 (SPA는 필수)
+3. browser_snapshot    (접근성 트리 — 토큰 효율)
+   또는
+   browser_evaluate    (특정 셀렉터 데이터 추출)
+   또는
+   browser_run_code    (스크롤/페이지네이션)
+```
+
+### 도구별 용도
+
+| 도구 | 용도 |
+|------|------|
+| `browser_snapshot` | 접근성 트리 반환 — 텍스트+인터랙티브 요소 구조화. 가장 빠르고 토큰 효율적 |
+| `browser_evaluate` | `() => document.querySelector(...).innerText` 등 JS 평가 |
+| `browser_run_code` | `async ({ page }) => {...}` 풀 자동화 — 무한 스크롤, 다단계 인터랙션 |
+| `browser_network_requests` | XHR/fetch 호출 목록 — **WAF 뒤 진짜 API 엔드포인트 발견용** (→ curl_cffi로 직접 호출) |
+| `browser_console_messages` | JS 에러/로그 |
+
+### 주의
+
+- MCP는 Chromium 번들 기반. TLS 지문이 BoringSSL이라 Akamai/DataDome은 **293 바이트 Access Denied** 또는 즉시 403 반환.
+- 이 경우 자동으로 Approach 2로 이관되도록 `engine/executor.py`가 처리. 수동 선택 불필요.
+
+## Approach 2 — Local Node + Real Chrome
+
+### 의존성 (최초 1회)
+
+```bash
+# Node (시스템 설치)
+node -v   # v18+ 권장
+
+# Playwright + stealth 플러그인
+npm i -g playwright playwright-extra puppeteer-extra-plugin-stealth
+
+# 시스템 Chrome 바이너리 (번들 Chromium 아님)
+npx playwright install chrome
+```
+
+### 호출 (engine 내부)
+
+```python
+from insane_search.engine.executor import run_playwright_fallback
+
+attempt, html = run_playwright_fallback(
+    "https://example.com/path",
+    profile_id="akamai_bot_manager",
+    success_selectors=["article"],
+    device_class="desktop",   # "desktop" | "mobile" | "auto"
+)
+```
+
+내부에서 `engine/templates/playwright_real_chrome.js` 또는 `playwright_mobile_chrome.js`를 Node로 실행하고 HTML을 받아온다. 템플릿은 **URL과 셀렉터 파라미터만** 받으며 사이트별 분기가 없다.
+
+### 데스크톱 템플릿 (`playwright_real_chrome.js`)
+
+```js
+const { chromium } = require('playwright-extra');
+const stealth = require('puppeteer-extra-plugin-stealth')();
+chromium.use(stealth);
+
+const ctx = await chromium.launchPersistentContext(profileDir, {
+  channel: 'chrome',        // ← 핵심: 번들 Chromium 아닌 실제 Chrome
+  headless: false,          // Akamai는 headless 탐지. headful 필요.
+  viewport: { width: 1366, height: 900 },
+});
+```
+
+### 모바일 템플릿 (`playwright_mobile_chrome.js`)
+
+```js
+const { chromium, devices } = require('playwright-extra');
+const iPhone = devices['iPhone 13 Pro'];
+
+const ctx = await chromium.launchPersistentContext(profileDir, {
+  channel: 'chrome',          // TLS는 실제 Chrome
+  ...iPhone,                  // UA/viewport/isMobile/hasTouch 자동 주입
+  headless: false,
+});
+```
+
+**주의**: `channel:'chrome'` + `devices[...]` 조합은 TLS 핑거프린트를 Chrome으로 유지하면서 HTTP 레이어(UA/viewport)만 모바일로 바꾼다. WAF가 실제 Chrome으로 인식해서 관대한 경우가 많다.
+
+## 선택 규칙 (자동)
+
+`engine/waf_profiles.yaml`의 `capabilities_needed` 태그가 결정한다:
+
+| 태그 조합 | 선택 실행기 | 대표 케이스 |
+|----------|-------------|-------------|
+| `needs_real_tls_stack` + `needs_js_exec` | Approach 2 (real_chrome) | Akamai Bot Manager |
+| `needs_js_exec` only | Approach 1 (MCP) | Cloudflare Turnstile |
+| `needs_real_tls_stack` only | Approach 2 (real_chrome) | 일부 DataDome 설정 |
+| 둘 다 없음 | curl 체인에서 해결. Playwright 안 씀 | F5 BIG-IP (TLS만 우회 필요) |
+
+`device_class="mobile"`이 지정되면 real_chrome → mobile 변종으로 swap.
+
+## 공통 검증
+
+두 Approach 모두 최종 HTML을 `engine/validators.py:validate()`로 재검증한다. 즉 Playwright가 HTML을 받아와도 **챌린지 페이지 또는 빈 SPA면 여전히 CHALLENGE 판정**. 자동으로 다음 조합이나 failure 보고로 이어진다.
+
+## 디버깅 팁
+
+- `profileDir`를 고정 경로로 두면 세션·쿠키가 유지되어 재시도 빠름 (`/tmp/.insane_pw_profile`)
+- Akamai 재시도가 잦으면 `profileDir`를 삭제해 fresh 상태로 리셋
+- 실패 시 `result.trace`의 `error` 필드에 Node stderr 200자가 포함됨
+
+## 사이트 예시 (독자 이해용, 코드 분기 근거 아님)
+
+> 이 섹션은 **설명 목적**이며 `engine/**` 코드에는 반영되지 않는다.
+
+- **Cloudflare 기본 챌린지**: Approach 1 (MCP) 충분
+- **Akamai Bot Manager**: Approach 2 필수. MCP로는 TLS-UA 불일치 탐지됨
+- **SSR 블로그 플랫폼**: curl_cffi safari만으로 HTML 수신. Playwright 불필요
+- **검색 결과 JS 렌더링 SPA**: Approach 1로 `browser_wait_for` 후 `browser_snapshot`
+
+실제 라우팅은 프로파일 태그가 결정한다. 위 예시는 참고일 뿐 코드 분기 근거로 쓰지 않는다.

package/packages/omo-codex/plugin/skills/ultimate-browsing/references/insane-search/public-api.md

@@ -0,0 +1,119 @@
+# 공개 API 직접 호출
+
+> 인증 없이 구조화된 데이터를 반환하는 공개 API.
+> 웹 크롤링이 아니라 공식 API — 안정적이고 정확.
+
+## Bluesky (AT Protocol)
+
+프로필과 피드는 완전 공개. 검색은 403 차단.
+
+```bash
+# 프로필
+curl -sL "https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile?actor={handle}" | \
+python3 -c "import sys,json; d=json.load(sys.stdin); print(f'{d[\"displayName\"]} — Followers: {d[\"followersCount\"]}, Posts: {d[\"postsCount\"]}')"
+
+# 피드 (최근 게시물)
+curl -sL "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor={handle}&limit=10"
+```
+
+Rate limit: ~3,000 req/hour
+
+## Mastodon
+
+인스턴스별 상이. mastodon.social은 공개 타임라인 차단, hachyderm.io/fosstodon.org 등은 허용.
+
+```bash
+# 계정 조회
+curl -sL "https://{instance}/api/v1/accounts/lookup?acct={username}"
+
+# 계정 타임라인 (ID 획득 후)
+curl -sL "https://{instance}/api/v1/accounts/{id}/statuses?limit=10"
+
+# 해시태그 타임라인 (인스턴스에 따라 인증 필요)
+curl -sL "https://hachyderm.io/api/v1/timelines/tag/{tag}?limit=10"
+```
+
+## Stack Exchange (v2.3)
+
+```bash
+# 질문 검색
+curl -sL "https://api.stackexchange.com/2.3/search?order=desc&sort=votes&intitle={query}&site=stackoverflow"
+
+# 태그 기반
+curl -sL "https://api.stackexchange.com/2.3/questions?tagged={tag1};{tag2}&site=stackoverflow&pagesize=5"
+
+# 답변 포함 (본문 필요 시)
+curl -sL "https://api.stackexchange.com/2.3/questions/{id}/answers?order=desc&sort=votes&site=stackoverflow&filter=withbody"
+```
+
+Rate limit: 비인증 300 req/day (IP당)
+
+## arXiv (학술 논문)
+
+```bash
+# 논문 검색 (ti=제목, au=저자, abs=초록, cat=카테고리)
+curl -sL "http://export.arxiv.org/api/query?search_query=ti:{query}&max_results=5&sortBy=submittedDate&sortOrder=descending"
+```
+
+**주의**: 3 req/second 제한. 요청 간 1초 sleep 필수.
+카테고리: cs.AI, cs.CL, cs.LG, cs.CV 등
+
+## CrossRef (DOI / 피어리뷰 논문)
+
+```bash
+# 논문 검색
+curl -sL "https://api.crossref.org/works?query={query}&filter=from-pub-date:2025-01&rows=5&sort=relevance"
+
+# DOI로 조회
+curl -sL "https://api.crossref.org/works/{DOI}"
+```
+
+Rate limit: 50 req/second. User-Agent에 이메일 추가 시 Polite Pool 진입.
+
+## OpenLibrary (도서)
+
+```bash
+# ISBN 조회
+curl -sL "https://openlibrary.org/api/books?bibkeys=ISBN:{isbn}&jscmd=data&format=json"
+
+# 도서 검색
+curl -sL "https://openlibrary.org/search.json?q={query}&limit=5"
+```
+
+## Wayback Machine (아카이브)
+
+```bash
+# 스냅샷 확인
+curl -sL "https://archive.org/wayback/available?url={URL}"
+
+# CDX API (스냅샷 목록)
+curl -sL "https://web.archive.org/cdx/search/cdx?url={URL}&output=json&fl=timestamp,statuscode&limit=5"
+```
+
+## GitHub REST API (gh CLI 없을 때)
+
+비인증 60 req/hour. gh CLI 우선 사용 권장.
+
+```bash
+# 저장소 검색
+curl -sL "https://api.github.com/search/repositories?q={query}&sort=stars&per_page=5"
+
+# 릴리즈
+curl -sL "https://api.github.com/repos/{owner}/{repo}/releases?per_page=5"
+
+# 코드 검색
+curl -sL "https://api.github.com/search/code?q={query}+language:python&per_page=5"
+```
+
+## Rate Limit 요약
+
+| API | 비인증 | 비고 |
+|-----|-------|------|
+| Bluesky | ~3K/hr | 검색 403 |
+| Mastodon | 인스턴스별 | |
+| Stack Exchange | 300/day | 인증 시 10K |
+| arXiv | 3/sec | sleep 필수 |
+| CrossRef | 50/sec | |
+| OpenLibrary | 무제한 | |
+| Wayback | 무제한 | |
+| GitHub REST | 60/hr | gh CLI 우선 |

package/packages/omo-codex/plugin/skills/ultimate-browsing/references/insane-search/rss.md

@@ -0,0 +1,123 @@
+# RSS/Atom 피드
+
+> 인증 불필요. URL만 알면 바로 구독. 뉴스/블로그/커뮤니티에서 가장 깔끔한 데이터.
+
+## 의존성
+
+```bash
+python3 -c "import feedparser" 2>/dev/null || pip install feedparser -q
+```
+
+## RSS 자동 발견
+
+Jina Reader JSON 모드로 사이트의 RSS URL을 자동 탐지:
+
+```bash
+curl -sH "Accept: application/json" "https://r.jina.ai/{URL}" | \
+  python3 -c "import sys,json; print(json.load(sys.stdin)['data'].get('external',{}).get('alternate',[]))"
+```
+
+## URL 변형으로 피드 탐색
+
+사이트에 RSS가 명시되지 않아도 시도해볼 패턴:
+
+```bash
+curl -sL "{origin}/rss"
+curl -sL "{origin}/feed"
+curl -sL "{origin}/atom.xml"
+curl -sL "{origin}/rss.xml"
+curl -sL "{origin}/index.xml"
+```
+
+## Google News RSS (무인증)
+
+```bash
+# 키워드 검색
+curl -sL "https://news.google.com/rss/search?q={검색어}&hl=ko&gl=KR&ceid=KR:ko"
+
+# 토픽별 (TECHNOLOGY, BUSINESS, SCIENCE, SPORTS, HEALTH, WORLD)
+curl -sL "https://news.google.com/rss/headlines/section/topic/TECHNOLOGY?hl=ko&gl=KR&ceid=KR:ko"
+
+# 시간 필터: when:1h, when:7d, when:12m, after:YYYY-MM-DD
+curl -sL "https://news.google.com/rss/search?q={검색어}+when:7d&hl=ko&gl=KR&ceid=KR:ko"
+```
+
+## 한국 언론사 RSS
+
+전부 무인증. 바로 curl로 접근 가능.
+
+```bash
+# SBS 뉴스
+curl -sL "https://news.sbs.co.kr/news/rss.do"
+
+# 조선일보
+curl -sL "http://www.chosun.com/site/data/rss/rss.xml"
+
+# 중앙일보
+curl -sL "http://rss.joinsmsn.com/joins_news_list.xml"
+
+# 동아일보
+curl -sL "http://rss.donga.com/total.xml"
+
+# 경향신문
+curl -sL "http://www.khan.co.kr/rss/rssdata/total_news.xml"
+
+# 매일경제
+curl -sL "http://file.mk.co.kr/news/rss/rss_30000001.xml"
+
+# MBC 뉴스
+curl -sL "http://imnews.imbc.com/rss/news/news_00.xml"
+
+# 한국경제
+curl -sL "https://www.hankyung.com/feed/all-news"
+
+# 연합뉴스
+curl -sL "https://www.yonhapnewsagency.com/RSS/headline.xml"
+```
+
+## 블로그/플랫폼 RSS
+
+```bash
+# 네이버 블로그
+curl -sL "https://rss.blog.naver.com/{BLOG_ID}.xml"
+
+# 티스토리
+curl -sL "https://{blogname}.tistory.com/rss"
+
+# 벨로그
+curl -sL "https://v2.velog.io/rss/@{username}"
+
+# Substack
+curl -sL "https://{publication}.substack.com/feed"
+
+# GitHub 릴리즈 (Atom)
+curl -sL "https://github.com/{owner}/{repo}/releases.atom"
+
+# YouTube 채널
+curl -sL "https://www.youtube.com/feeds/videos.xml?channel_id={id}"
+
+# HN (hnrss.org — 비공식이지만 안정적)
+curl -sL "https://hnrss.org/frontpage"
+```
+
+## feedparser 파싱
+
+```python
+import feedparser
+
+feed = feedparser.parse("FEED_URL")
+for e in feed.entries[:10]:
+    print(f"{e.title} — {e.link}")
+    if hasattr(e, 'summary'):
+        print(f"  {e.summary[:200]}")
+```
+
+## SearXNG (무인증 메타검색)
+
+공개 인스턴스에서 JSON 검색 가능. 인스턴스별로 JSON 지원 여부 다름.
+
+```bash
+# 공개 인스턴스 목록: https://searx.space
+curl -sL "https://search.mdosch.de/search?q={검색어}&format=json" \
+  -H "User-Agent: insane-search/1.0"
+```

package/packages/omo-codex/plugin/skills/ultimate-browsing/references/insane-search/tls-impersonate.md

@@ -0,0 +1,186 @@
+# TLS 임퍼소네이션 — curl_cffi
+
+> TLS 핑거프린트(JA3/JA4) 기반 WAF를 우회하는 핵심 방법.
+> 일반 curl/requests는 OpenSSL 핑거프린트라 즉시 차단되지만,
+> curl_cffi는 실제 브라우저(Chrome/Safari/Firefox)의 TLS 핑거프린트를 복제한다.
+
+## 의존성
+
+```bash
+python3 -c "import curl_cffi" 2>/dev/null || pip install curl_cffi -q
+```
+
+설치 후 사용 가능. **미설치를 이유로 이 스텝을 건너뛰지 않는다.**
+
+## 다중 타겟 순차 시도
+
+하나의 impersonate 타겟이 실패하면 다른 타겟으로 재시도한다.
+**시도 순서: safari → chrome → firefox**
+
+```python
+from curl_cffi import requests
+
+TARGETS = ["safari", "chrome", "firefox"]
+HEADERS = {
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7",
+    "Accept-Encoding": "gzip, deflate, br",
+    "Referer": "https://www.google.com/",
+}
+
+def cffi_fetch(url, locale="ko-KR"):
+    """다중 타겟 순차 시도 + 신원위장. 성공하면 (response, target) 반환."""
+    from urllib.parse import urlparse
+    origin = f"{urlparse(url).scheme}://{urlparse(url).netloc}"
+    for target in TARGETS:
+        try:
+            session = requests.Session(impersonate=target)
+            session.headers.update(HEADERS)
+            session.headers["Accept-Language"] = f"{locale},{locale.split('-')[0]};q=0.9"
+            session.headers["Referer"] = "https://www.google.com/"
+            # 신원위장: 홈페이지 쿠키 워밍 → Referer 체인
+            try:
+                session.get(origin, timeout=10)
+            except Exception:
+                pass  # 홈 실패해도 본 요청은 시도
+            session.headers["Referer"] = origin
+            resp = session.get(url, timeout=20)
+            # JS 필수 사이트 감지 → 나머지 타겟 시도 무의미
+            if "behavioral-content" in resp.text or "sec-if-cpt" in resp.text:
+                return None, None  # → Phase 3 Playwright
+            if resp.status_code == 200 and len(resp.text) > 500:
+                return resp, target
+        except Exception:
+            continue
+    return None, None
+```
+
+## 임퍼소네이션 타겟 목록 (v0.15.0)
+
+generic alias는 항상 최신 버전으로 해석된다. **2026년에 chrome99 같은 옛 버전은 WAF가 의심하므로 generic alias 사용 권장.**
+
+| Alias | 해석 (2026.04) | 용도 |
+|-------|---------------|------|
+| `safari` | safari260 | **한국 사이트 최적** (쿠팡, 에펨코리아) |
+| `chrome` | chrome146 | 범용 (Cloudflare, Akamai) |
+| `firefox` | firefox135 | chrome/safari 실패 시 대안 |
+| `chrome_android` | chrome131_android | 모바일 API 엔드포인트 |
+| `safari_ios` | safari260_ios | iOS 모바일 |
+
+<details>
+<summary>핀 버전 전체 (클릭)</summary>
+
+```
+chrome99, chrome100, chrome101, chrome104, chrome107, chrome110,
+chrome116, chrome119, chrome120, chrome123, chrome124, chrome131,
+chrome133a, chrome136, chrome142, chrome145, chrome146,
+chrome131_android, edge99, edge101,
+safari15_3, safari15_5, safari17_0, safari17_2_ios,
+safari18_0, safari18_0_ios, safari260, safari260_ios,
+firefox133, firefox135
+```
+
+</details>
+
+## WAF별 최적 전략
+
+| WAF | 최적 타겟 | 추가 조건 | 성공률 |
+|-----|-----------|-----------|--------|
+| F5 BIG-IP (쿠팡) | `safari` | `Referer: https://www.coupang.com/` | ~70% |
+| Cloudflare (TLS만) | `chrome` | Sec-Fetch-* 헤더 추가 | ~80% |
+| Akamai | `chrome` | 레지덴셜 프록시 병행 | 80-90% |
+| AWS WAF | `chrome` | — | ~80% |
+| CloudFront (요즘IT) | 불필요 | 일반 curl + Chrome UA로 충분 | 100% |
+
+## 세션과 쿠키
+
+```python
+from curl_cffi import requests
+
+# 세션 유지 (쿠키 자동 관리)
+session = requests.Session(impersonate="safari")
+
+# 첫 요청으로 세션 쿠키 획득
+session.get("https://www.coupang.com/")
+
+# 이후 요청에 쿠키 자동 전달
+resp = session.get("https://www.coupang.com/np/search?q=키보드")
+```
+
+## 콤보: nodriver/FlareSolverr → curl_cffi
+
+JS 챌린지 사이트는 브라우저로 쿠키를 획득한 뒤 curl_cffi로 고속 처리:
+
+```python
+# 1. nodriver로 cf_clearance 쿠키 획득
+import nodriver as uc
+browser = await uc.start(headless=True)
+page = await browser.get("https://cf-protected-site.com")
+await page.cf_verify()
+cookies = await browser.cookies.get_all()
+
+# 2. curl_cffi Session에 쿠키 전달
+from curl_cffi import requests
+session = requests.Session(impersonate="chrome")
+for c in cookies:
+    session.cookies.set(c["name"], c["value"])
+resp = session.get("https://cf-protected-site.com/api/data")
+```
+
+## 비동기 (async)
+
+```python
+import asyncio
+from curl_cffi.requests import AsyncSession
+
+async def fetch_many(urls):
+    async with AsyncSession(impersonate="chrome") as session:
+        tasks = [session.get(url) for url in urls]
+        return await asyncio.gather(*tasks)
+```
+
+## HTTP/3 (v0.15.0+)
+
+```python
+from curl_cffi import requests
+from curl_cffi.const import CurlHttpVersion
+
+resp = requests.get(
+    "https://www.cloudflare.com/",
+    impersonate="chrome",
+    http_version=CurlHttpVersion.V3,
+)
+```
+
+WAF 벤더들이 아직 HTTP/3 핑거프린트를 적극 활용하지 않아 우회 효과가 높다.
+
+## 대안 라이브러리
+
+curl_cffi 실패 시 대안:
+
+| 라이브러리 | 설치 | 특징 |
+|-----------|------|------|
+| primp | `pip install primp` | Rust 기반, Firefox 148까지, 고성능 |
+| wreq/rnet | `pip install wreq` | Rust 기반, 100+ 디바이스 프로필 |
+| tls-client2 | `pip install tls-client2` | Go 기반 포크, 동기만 |
+
+```python
+# primp 예시
+import primp
+client = primp.Client(impersonate="chrome_146")
+resp = client.get("https://example.com")
+```
+
+## curl_cffi가 못 뚫는 것
+
+| 방어 수단 | curl_cffi | 대응 |
+|-----------|-----------|------|
+| TLS/JA3 핑거프린트 | 우회 가능 | 핵심 기능 |
+| HTTP/2 SETTINGS 핑거프린트 | 우회 가능 | impersonate에 포함 |
+| HTTP/3 QUIC 핑거프린트 | 우회 가능 (v0.15+) | 신규 |
+| JS 챌린지 (Turnstile 등) | **불가** | → nodriver 또는 Playwright |
+| CAPTCHA | **불가** | → 2captcha/CapSolver |
+| IP 평판 (데이터센터) | **불가** | → 프록시/VPN |
+| 행동 분석 (마우스/타이밍) | **불가** | → 실제 브라우저 |
+
+JS 챌린지가 걸린 사이트는 → [playwright.md](playwright.md) 로 넘긴다.

package/packages/omo-codex/plugin/skills/ultimate-browsing/references/insane-search/twitter.md

@@ -0,0 +1,104 @@
+# X/Twitter 접근 전략
+
+> WebFetch는 402로 차단됨. 아래 방법으로 우회한다. 모두 API 키/인증 불필요.
+
+## 검색 (트윗 발견)
+
+```python
+WebSearch(query="site:x.com {검색어}")
+```
+
+WebSearch는 X 포스트를 검색 결과로 반환한다. 제목, snippet, URL을 획득할 수 있지만 트윗 전문이나 engagement 수치는 없다.
+
+## 타임라인 조회 — Syndication API
+
+특정 핸들의 최근 ~100개 트윗 + engagement 수치(likes, RTs) 제공.
+
+### 엔드포인트
+
+```
+https://syndication.twitter.com/srv/timeline-profile/screen-name/{handle}
+```
+
+### 원샷 스크립트
+
+```bash
+curl -sL "https://syndication.twitter.com/srv/timeline-profile/screen-name/{handle}" | \
+python3 -c "
+import sys, json, re, html
+content = sys.stdin.read()
+match = re.search(r'__NEXT_DATA__.*?>(.*?)</script>', content)
+if match:
+    data = json.loads(match.group(1))
+    for e in data['props']['pageProps']['timeline']['entries']:
+        if e['type'] == 'tweet':
+            t = e['content']['tweet']
+            print(f\"@{t['user']['screen_name']} ({t.get('created_at','?')})\")
+            print(f\"  {html.unescape(t.get('full_text',''))[:300]}\")
+            print(f\"  Likes: {t.get('favorite_count',0)} | RTs: {t.get('retweet_count',0)}\")
+            print('---')
+"
+```
+
+### 가져올 수 있는 데이터
+
+| 필드 | 경로 | 예시 |
+|------|------|------|
+| 트윗 전문 | `tweet.full_text` | "Give your agent the..." |
+| 작성자 핸들 | `tweet.user.screen_name` | "openclaw" |
+| 작성자 이름 | `tweet.user.name` | "OpenClaw" |
+| 좋아요 수 | `tweet.favorite_count` | 1929 |
+| RT 수 | `tweet.retweet_count` | 169 |
+| 작성 시각 | `tweet.created_at` | "Mon Apr 06 04:04:08 +0000 2026" |
+| 트윗 ID | `tweet.id_str` | "2041003999856406714" |
+| 미디어 URL | `tweet.entities.media[].media_url_https` | 이미지/동영상 URL |
+
+### 제한
+
+- 최근 ~100개 반환 (페이지네이션 불가)
+- 비공개 계정 접근 불가
+- 검색 기능 없음 (타임라인만)
+- **저팔로워/신규 계정**: `hasResults: false` 반환 가능. 이 경우 oEmbed 개별 트윗 접근은 정상 동작하므로 "조합 패턴"으로 폴백.
+- 비공식 엔드포인트 — X가 변경/차단 가능
+
+## 개별 트윗 조회 — oEmbed API
+
+특정 트윗 URL을 알 때 전문 가져오기.
+
+### 엔드포인트
+
+```
+https://publish.twitter.com/oembed?url=https://x.com/{user}/status/{tweet_id}
+```
+
+### 사용법
+
+```bash
+curl -sL "https://publish.twitter.com/oembed?url=https://x.com/{user}/status/{tweet_id}"
+```
+
+### 응답 (JSON)
+
+| 필드 | 설명 |
+|------|------|
+| `author_name` | 작성자 표시 이름 |
+| `author_url` | 작성자 프로필 URL |
+| `html` | 트윗 전문이 포함된 HTML blockquote |
+| `url` | 트윗 원본 URL |
+
+## 조합 패턴 (검색 → 상세)
+
+```
+1단계: WebSearch(query="site:x.com {키워드}") → 트윗 URL 획득
+2단계: curl oEmbed API → 트윗 전문 획득
+```
+
+## 실패하는 방법 (사용하지 말 것)
+
+| 방법 | 결과 | 원인 |
+|------|------|------|
+| WebFetch | 402 Payment Required | Claude Code의 WebFetch 제한 |
+| Nitter | 빈 응답 | Nitter 인스턴스 대부분 종료됨 |
+| Wayback Machine | OG 메타태그만 | SPA 렌더링 안 됨 |
+| Mobile UA curl | OG 메타태그만 | SPA 렌더링 안 됨 |
+| RSS | 엔드포인트 없음 | X는 RSS 지원 중단 |