스프쌤
CLI 도구

only-cli의 oc: AI 에이전트 웹 탐색 토큰 99% 줄이는 CLI

✍ 야금야금⏱ 15분 소요2026-10-24👁
← 목록으로 돌아가기

웹페이지 하나를 AI에게 넘겼을 뿐인데, 왜 3만 개의 컨텍스트 토큰이 순식간에 증발하고 마우스 커서까지 얼어붙을까요?

✦ AI Key Summary & Global Takeaways

이 아티클의 핵심 내용 요약과 글로벌 검색·AI 엔진을 위한 테이크어웨이입니다.

✦ KR 주제: AI 에이전트를 위한 경량 웹 브라우징 CLI 도구 only-cli oc

✦ KR 핵심 요약: only-cli의 oc는 Claude Code, Codex 등 터미널 기반 에이전트가 웹페이지를 수백 토큰 단위로 탐색할 수 있도록 돕는 오픈소스 CLI다. 별도 데몬이나 확장 프로그램 없이 번호 매김 뷰를 생성하며, TLS 위장과 점진적 강등 파이프라인으로 차단을 우회한다.

🌐 Global Takeaway: only-cli/oc turns complex web pages into compact, numbered CLI views consuming hundreds of tokens instead of tens of thousands. With built-in TLS impersonation fallbacks and zero daemon dependencies, it provides an efficient browsing layer for CLI agents like Claude Code and Codex.

아래 그림은 일반적인 브라우징 방식과 only-cli oc의 데이터 처리 구조 차이를 보여줍니다.

전체 마크업 전달 vs only-cli oc 텍스트 파이프라인
기존 웹 에이전트 방식
  • 수만 토큰 마크업 주입
  • 실제 창 활성화로 화면 간섭
  • 단순 fetch 차단 빈발
VS
only-cli/oc 방식
  • 수백 토큰 텍스트 축약
  • 데몬 없는 순수 CLI 실행
  • impers 다단계 우회 탑재
원본 HTML 및 헤드리스 렌더링 대비 압축된 번호 기반 인터페이스 비교

1. AI 에이전트가 웹을 읽을 때 발생하는 토큰 폭식

최근 터미널 환경에서 자율적으로 코드를 작성하고 명령을 실행하는 AI 에이전트의 활용이 급증하고 있습니다. Claude Code나 Codex 같은 에이전트는 코드베이스 검사뿐 아니라 공식 문서 확인, 이슈 트래커 검색, API 레퍼런스 조회를 위해 수시로 외부 웹에 접속합니다. 그러나 대다수 에이전트 프레임워크가 외부 웹 문서를 읽어오는 방식은 지나치게 비효율적입니다. 일반적인 웹페이지 주소를 에이전트에 넘기면, 에이전트는 헤드리스 브라우저를 띄워 전체 DOM 트리를 덤프하거나 복잡한 원본 HTML 마크업 전체를 컨텍스트 윈도우에 그대로 밀어 넣습니다.

이러한 무차별적 수집은 심각한 자원 낭비를 유발합니다. 최신 웹사이트는 화려한 UI 프레임워크, 스타일시트 인라인 데이터, 추적 스크립트, SVG 아이콘, 접근성 트리 보조 태그로 뒤덮여 있습니다. 사람이 읽을 수 있는 실제 텍스트 정보는 본문 5줄에 불과하더라도, 이를 감싸는 마크업 덩어리는 쉽게 2만 개에서 5만 개에 달하는 토큰을 소모합니다. 컨텍스트 길이가 20만 토큰 이상으로 확장되었다고 해도 단 두세 번의 웹 검색만으로 수만 토큰이 소모되면, 에이전트의 단기 기억 용량이 빠르게 잠식되고 API 호출 비용은 천정부지로 치솟습니다.

더 큰 문제는 조작의 충돌과 렌더링 비용입니다. 헤드리스 브라우저 대신 실제 화면이 표시되는 자동화 브라우저 도구를 에이전트에게 쥐여주면 백그라운드 확인 과정에서 사용자 PC의 마우스 포커스를 강제로 빼앗아 오거나 시스템 리소스를 독점해 작업 환경을 마비시키는 부작용이 동반됩니다. 개발자에게 필요한 것은 복잡한 브라우저 화면 통째가 아니라, 필요한 링크를 클릭하고 본문을 정확히 파악할 수 있는 최소한의 텍스트 인터페이스입니다.

1-1. 웹 탐색 비용 구조의 현실

일반적인 기술 뉴스 사이트나 공식 문서를 AI가 처리할 때 발생하는 데이터와 토큰 비용을 비교해 보면 불필요한 마크업 오버헤드가 얼마나 심각한지 명확해집니다.

항목 기존 웹 렌더링/스크래핑 방식 압축 텍스트 CLI 변환 방식
입력 페이로드 전체 HTML DOM + 자바스크립트 (수십 KB~수 MB) 정제된 텍스트 및 번호 식별자
토큰 소모량 페이지당 15,000 ~ 50,000+ 토큰 페이지당 200 ~ 800 토큰
시스템 자원 크롬 프로세스 구동 (메모리 300MB~1GB) 순수 Node.js 단일 프로세스 실행
대화 지속성 몇 차례 탐색 후 이전 대화 컨텍스트 유실 수십 회 이상 탐색 후에도 컨텍스트 유지

"A typical page is tens of thousands of tokens of markup; the view above fits in a few hundred." — only-cli README

2. only-cli oc의 핵심 아키텍처와 경량화 설계

GitHub에서 공개된 only-cli/oc는 바로 이 웹 탐색 과정의 토큰 거품을 제거하기 위해 설계된 오픈소스 CLI 도구입니다. 에이전트에게 원시 HTML이나 스크린샷 래스터 이미지를 전송하는 대신, 웹페이지의 구조를 분석해 인터랙션이 가능한 번호가 매겨진 간결한 텍스트 뷰로 재구성하여 전달합니다.

AI 에이전트 브라우징 입출력 레이어
웹 리소스 계층HTML, 자바스크립트 실행 결과, CSS 렌더 트리
oc 렌더러 계층상호작용 요소 번호 부여 및 액션 목록 추출
에이전트 인풋 계층수백 토큰 규모의 넘버링 뷰와 제어 커맨드
복잡한 웹 마크업이 AI 맞춤형 액션 인터페이스로 정제되는 계층 구조

도구의 기본 철학은 단순함입니다. 각 사이트별로 전용 파서를 작성할 필요가 없는 범용 구조를 채택했으며, 상시 실행되는 무거운 백그라운드 데몬이나 별도의 브라우저 확장 프로그램 설치를 일절 요구하지 않습니다. 에이전트가 CLI 환경에서 단일 명령어로 웹페이지를 요청하면, 도구 내부의 파이프라인이 텍스트 요소를 정리하고 상호작용 가능한 앵커 태그와 폼 요소에 고유 인덱스를 매겨 터미널에 텍스트 스트림 형태로 뱉어냅니다.

2-1. 넘버링 기반 액션 인터페이스

oc open <url> 명령어를 실행하면 브라우저 렌더러가 생성하는 시각적 레이아웃 대신, 인간과 LLM 모두 즉각 해석할 수 있는 텍스트 블록이 반환됩니다. 예를 들어 Hacker News 첫 화면을 요청했을 때의 반환 구조는 다음과 같습니다.

$ oc open news.ycombinator.com
# Hacker News
[1] Show HN: I built a tiny CSV toolkit
[2] 312 comments
...
actions: do <n> | find <query> | read <n> | next | raw

$ oc do 1

반환된 뷰는 웹페이지에 존재하는 하이퍼링크와 버튼을 대괄호 번호([1], [2])로 인덱싱합니다. 이후 에이전트는 복잡한 셀렉터(XPath, CSS Selector)를 생성해 브라우저 드라이버에 전송할 필요 없이, 단순히 oc do 1이라는 초경량 커맨드를 호출해 링크를 타고 이동할 수 있습니다. 뷰 하단에는 에이전트가 취할 수 있는 기본 액션인 do, find, read, next, raw 등이 명시되어 있어, 프롬프트 엔지니어링 단계에서 장황한 지침을 주지 않아도 LLM이 자체적으로 다음 행동을 결정하게 유도합니다.

3. 웹 안티봇 차단 우회와 다단계 강등 메커니즘

단순한 curl이나 Node.js의 기본 fetch로 웹페이지를 수집하려 하면 Cloudflare, Akamai 같은 봇 감지 솔루션에 의해 403 Forbidden이나 429 Too Many Requests 에러를 마주치기 십상입니다. 웹사이트 관리자들은 일반적인 브라우저 헤더가 누락되었거나 HTTP/2 핑거프린트가 일반 브라우저와 다른 스크립트 기반 수집기를 신속하게 차단합니다.

oc open 명령의 요청 강등 처리 흐름
Chrome 위장impers 기반 TLS 핑거프린트
→
Firefox 위장Chrome 거부 시 즉각 강등
→
Native Fetch미지원 환경 최종 수렴
사이트 차단 및 라이브러리 환경에 맞춰 요청 방식을 순차적으로 전환하는 구조

only-cli/oc는 이러한 문제를 우회하기 위해 내부적으로 브라우저 사칭 라이브러리인 impers(libcurl-impersonate 기반) 계층을 결합했습니다. 에이전트가 웹사이트에 접근할 때 단순 헤더 위조에 그치지 않고, TLS 핸드셰이크 파라미터, 암호화 스위트 순서, HTTP/2 세팅 프레임까지 완벽하게 실제 브라우저처럼 조작합니다.

3-1. 3단계 폴백(Fallback) 파이프라인

네트워크 요청은 단일 모듈의 성공 여부에 의존하지 않고 체계적인 다운그레이드 구조를 따릅니다.

  1. Chrome 프로필 위장: 기본 상태에서 impers 모듈을 사용해 최신 데스크톱 구글 크롬 브라우저의 TLS 핑거프린트와 네트워크 서명을 그대로 흉내 내어 요청을 보냅니다.
  2. Firefox 프로필 강등: 사이트의 보안 정책이 크롬 핑거프린트를 비정상 세션으로 판단해 거부하거나 로컬의 libcurl-impersonate 바이너리가 특정 크롬 정체성을 해석하지 못할 경우, 즉각 모질라 파이어폭스(Firefox) 프로필로 전환하여 재시도합니다.
  3. Native Fetch 최종 수렴: 실행 환경에 바이너리 의존성이 없거나 두 가지 브라우저 위장이 모두 거부될 경우, 런타임의 기본 fetch 인터페이스로 강등되어 원시 HTTP 요청을 완수합니다.

이러한 계층형 다운그레이드 덕분에 에이전트는 웹 탐색 도중 원인을 알 수 없는 네트워크 단절로 작업을 중단하지 않고 안정적으로 필요한 텍스트 데이터를 확보할 수 있습니다.

4. 환경 구성과 설치 시 충돌 주의사항

only-cli/oc는 Node.js 런타임 환경에서 전역 CLI 패키지로 손쉽게 배포할 수 있습니다. 시스템에 사전 요구되는 최소 환경은 Node.js 20 버전 이상입니다.

npm install -g @only-cli/oc

설치는 매우 직관적이지만, 기업 환경이나 엔터프라이즈 데브옵스 인프라를 다루는 엔지니어는 명령어 네이밍 충돌을 반드시 인지해야 합니다. 레드햇의 대표적인 쿠버네티스 엔터프라이즈 플랫폼인 Red Hat OpenShift 역시 커맨드라인 도구의 바이너리 명칭으로 동일한 oc를 사용합니다.

4-1. OpenShift oc 바이너리와의 네이밍 충돌

Red Hat OpenShift CLI와 only-cli/oc는 공통적으로 login, logout 등의 서브커맨드를 정의하고 있습니다. 두 패키지가 한 시스템의 동일한 $PATH 환경에 설치될 경우 쉘 설정의 우선순위에 따라 원하지 않는 바이너리가 호출되는 문제가 발생합니다. 예를 들어 클러스터 접근 인증을 시도하다가 웹 탐색 CLI의 인증 루틴이 실행되거나, 그 반대의 상황이 벌어질 수 있습니다.

따라서 이미 OpenShift CLI가 설치된 개발 머신이나 CI/CD 환경에서 본 도구를 활용할 때는 전역 설치 경로를 격리하거나, 쉘 알리아스를 분리하고, 컨테이너화된 독립 샌드박스 내부에서 AI 에이전트를 구동하는 방식을 권장합니다.

5. 터미널 기반 AI 에이전트 연동 실무와 llms.txt의 활용

에이전트에게 도구를 노출할 때 컨텍스트 낭비를 줄이는 것은 커맨드 자체의 출력 길이뿐만 아니라 도구 사용법(Tool Description)을 어떻게 주입하느냐에 달려 있습니다. only-cli/oc 프로젝트는 루트 디렉토리에 AI가 직접 읽고 최적화된 방식으로 기능을 이해할 수 있도록 llms.txt 규격을 기본 제공합니다.

5-1. Claude Code 및 에이전트 스킬 등록 구조

Claude Code나 Antigravity 같은 최신 에이전트 프레임워크는 터미널 명령어를 직접 실행하거나 커스텀 툴 플러그인 형태로 등록할 수 있습니다. 프로젝트 저장소 내부의 .claude-plugin 및 skills/web-browsing-cli 설정을 활용하면 에이전트가 웹 정보를 조회해야 할 때 브라우저 렌더러 대신 oc 명령을 우선 사용하도록 라우팅할 수 있습니다.

에이전트는 다음과 같은 흐름으로 자율적인 정보 조사를 수행합니다:

  1. oc open <문서 URL>로 진입해 주요 목차 및 헤더를 번호 인덱스로 훑어봅니다.
  2. 전체를 다 읽지 않고 actions: find <검색어>를 실행해 원하는 키워드가 포함된 단락만 터미널로 끌어옵니다.
  3. 특정 링크의 상세 설명이 필요할 경우 oc read <번호> 또는 oc do <번호>를 호출해 다음 단계로 심층 탐색을 전개합니다.

결과적으로 단 한 번의 프롬프트-응답 루프에서 소모되는 웹 스크래핑 비용이 100분의 1 수준으로 줄어들어, 대규모 디버깅 세션에서도 컨텍스트 윈도우가 가득 차는 현상을 근본적으로 방지합니다.

6. 도구의 한계점과 브라우저 자동화가 불가피한 영역

only-cli/oc가 강력한 경량성을 제공하지만, 모든 웹 시나리오를 대체할 수 있는 것은 아닙니다. 텍스트 정보의 빠른 취득과 단순 링크 내비게이션에는 최적화되어 있으나, 그래픽 인터페이스에 강하게 결합된 서비스에서는 분명한 기술적 한계가 존재합니다.

  • 복잡한 싱글 페이지 애플리케이션(SPA) 렌더링: 극단적으로 복잡한 클라이언트 사이드 자바스크립트 상태 머신이나 WebGL, Canvas 기반의 대시보드는 텍스트 인터페이스로 변환 시 의미 있는 정보를 온전히 추출하지 못할 수 있습니다.
  • CAPTCHA 및 대화형 시각 챌린지: TLS 사칭으로 기본 차단은 피하더라도, 회전 이미지 맞추기나 퍼즐 형태의 인간 인증 챌린지가 주입되면 텍스트 중심 인터페이스로는 에이전트가 이를 해결할 수 없습니다.
  • 시각적 UI 검증 작업: 웹 프론트엔드 스타일링, 반응형 레이아웃 깨짐, CSS 애니메이션 동작 확인처럼 렌더링된 픽셀 자체를 평가해야 하는 시각적 QA 작업에서는 여전히 실제 헤드리스 브라우저나 스크린샷 캡처 도구가 필수적입니다.

따라서 실무에서는 프론트엔드 시각 렌더링 테스트에는 실제 브라우저 자동화 도구를 배치하고, API 문서 참조·이슈 검색·기술 블로그 조사 등 순수 정보 획득 단계에는 oc를 전담 배치하는 이원화 전략이 가장 효율적입니다.

7. 결론: 효율적인 에이전트 웹 브라우징의 기준

AI 에이전트의 발전 속도에 비해 이들이 사용하는 인터페이스는 여전히 인간 중심의 레거시 웹 규격에 묶여 있었습니다. 인간을 위해 덧붙여진 수만 줄의 CSS와 추적 스크립트를 LLM에게 그대로 읽히는 것은 계산 자원의 명백한 낭비입니다.

only-cli/oc는 웹을 인간의 브라우징 창이 아닌 '에이전트 전용 CLI'라는 원초적 뷰로 재정의함으로써 컨텍스트 효율을 극대화했습니다. 수백 토큰 단위로 웹을 탐색할 수 있는 경량 도구를 파이프라인에 도입하는 것은 에이전트의 응답 지연 시간을 줄이고, 실행 비용을 절감하며, 터미널 세션의 안정성을 확보하는 실질적인 해결책이 될 것입니다.

자주 묻는 질문

Q. 기존 curl이나 wget 명령어와 only-cli oc의 차이점은 무엇인가요?
A. curl은 가공되지 않은 수만 줄의 원본 HTML을 그대로 가져와 토큰 낭비가 심하고 봇 차단에 쉽게 막힙니다. 반면 oc는 하이퍼링크와 버튼에 번호를 매긴 수백 토큰 분량의 정제된 텍스트 뷰를 생성하며, TLS 위장 기술을 통해 차단을 자동으로 우회합니다.

Q. 설치할 때 시스템 요구 사양이나 주의할 점은 무엇인가요?
A. Node.js 20 이상의 런타임이 필수적입니다. 또한 Red Hat OpenShift의 명령줄 도구 역시 바이너리 이름이 동일한 oc이므로, 같은 환경에 두 도구가 설치될 경우 명령어 충돌이 발생할 수 있어 경로 분리나 별칭 설정이 필요합니다.

Q. JavaScript가 많이 포함된 동적 사이트도 읽을 수 있나요?
A. 일반적인 콘텐츠 중심 사이트는 원활히 처리되지만, Canvas나 복잡한 인터랙티브 그래픽, 다단계 캡차(CAPTCHA) 풀이가 강제되는 페이지는 텍스트 CLI 특성상 정상 탐색이 제한될 수 있습니다.

원본

https://github.com/only-cli/oc

https://www.threads.com/@nangman_muk/post/DfE9ZsEiYMT

함께 보면 좋은 글

댓글 0개