반응형
OpenAI API 사용법 — 파이썬 첫 호출부터 요금·에러까지

오픈AI API를 처음 붙이면 대부분 세 곳에서 멈춘다. 키를 어디에 넣는지, 어떤 모델 이름을 써야 하는지, 그리고 첫 호출에서 401이나 429가 터질 때 뭘 고쳐야 하는지다. 이 글은 파이썬에서 responses.create로 답을 받는 데까지만 짧게 안내하고, 요금 표와 에러 표를 같이 붙여 둔다.

공식 문서는 2026년 11월 기준 developers.openai.com으로 옮겨졌다. 예전 platform.openai.com/docs 링크를 눌러도 새 주소로 넘어가니, 검색해서 나온 옛 예제와 지금 문서가 달라 보이는 건 정상이다.

30초 요약

항목내용
준비물오픈AI 계정, 결제 수단 등록, API 키 1개
설치pip install openai
키 설정환경변수 OPENAI_API_KEY (SDK가 자동으로 읽는다)
첫 호출client.responses.create(model=..., input=...) → response.output_text
모델gpt-6.2-astra(플래그십) / gpt-6.2-sol(균형) / gpt-6-luna(저비용)
요금 감각astra 입력 1M 토큰 $8, 출력 $40 (공식 가격표)
자주 나는 에러401(키 문제), 429(한도·크레딧), 503(모델 과부하)

그림 1. 키를 넣고 모델을 고르면 호출 한 줄로 끝난다. 모델별 단가는 공식 가격표 기준.

목차

  1. OpenAI API 시작 전에 확인할 것
  2. OpenAI Python SDK 설치와 API 키 설정
  3. 첫 호출 — responses.create로 답 받기
  4. 모델 선택 — gpt-6.2-astra·sol·luna 차이
  5. 요금 — 1M 토큰당 가격과 배치 할인
  6. 대화 이어가기와 스트리밍
  7. 자주 나는 에러 401·429 해결법
  8. 내가 막혔던 곳

OpenAI API 시작 전에 확인할 것

API는 챗GPT 유료 구독과 별개로 과금된다. 구독 요금제를 쓰고 있어도 API 호출은 따로 크레딧이 빠져나가므로, 대시보드에서 결제 수단을 먼저 등록해야 한다. 이 구조를 모르고 "플러스 결제했는데 왜 429가 뜨지"로 한 시간을 날리는 경우가 많다.

키는 대시보드의 API keys 메뉴에서 만든다. 만든 직후 한 번만 전체 문자열이 보이고, 이후에는 앞부분만 보인다. 잃어버리면 새로 발급하는 게 빠르다.

키를 코드에 직접 쓰지 않는 이유는 하나다. 커밋 한 번에 키가 깃허브로 나가고, 그 키로 과금이 발생한 사례가 흔하다. 환경변수나 .env 파일에 두고 .gitignore에 넣는 습관을 처음부터 들이는 편이 낫다.

OpenAI Python SDK 설치와 API 키 설정

설치는 한 줄이다. 공식 문서 기준 파이썬 SDK는 pip로 받는다 (Quickstart).

pip install openai

가상환경을 쓰고 있다면 그 안에서 설치한다. 전역 파이썬에 깔면 프로젝트마다 버전이 엉키는 일이 생긴다. 가상환경 만드는 법은 Python 가상환경 venv 만들기에 정리해 뒀다.

키는 터미널 환경변수로 넣는다. macOS나 리눅스는 export, 윈도우 파워셸은 setx를 쓴다.

export OPENAI_API_KEY="sk-..."
setx OPENAI_API_KEY "sk-..."

SDK는 이 환경변수를 자동으로 읽는다. 그래서 코드에 OpenAI()처럼 괄호만 열어 두면 키를 따로 넘기지 않아도 된다. .env 파일로 관리하고 싶으면 python-dotenv를 같이 쓰고, 스크립트 맨 위에서 load_dotenv()를 호출하면 된다.

첫 호출 — responses.create로 답 받기

지금 문서의 기본 예제는 Responses API다. 모델 이름과 입력을 넘기고, 응답 본문은 output_text에서 꺼낸다.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.2-astra",
    input="파이썬에서 리스트와 튜플의 차이를 한 문단으로 설명해줘.",
)

print(response.output_text)

print(response)로 객체 전체를 찍어 보면 이벤트와 메타데이터가 잔뜩 나온다. 처음엔 이걸 보며 겁먹기 쉬운데, 실제로 필요한 건 output_text 한 줄인 경우가 대부분이다.

역할을 나눠 보내고 싶으면 input에 메시지 리스트를 넣는다. 시스템 지시문은 instructions로 따로 넘길 수도 있다.

response = client.responses.create(
    model="gpt-6.2-sol",
    instructions="너는 파이썬 강사다. 초보자에게 반말로 짧게 답한다.",
    input=[
        {"role": "user", "content": "딕셔너리 컴프리헨션 예시 하나만 보여줘."},
    ],
)

토큰이 무엇이고 왜 요금과 연결되는지는 토큰(token)이란에 따로 적어 두었다. 프롬프트 문장을 다듬는 쪽이 궁금하면 프롬프트 작성법을 같이 보면 된다.

모델 선택 — gpt-6.2-astra·sol·luna 차이

문서는 용도별로 세 갈래를 권한다. 복잡한 추론과 코딩은 gpt-6.2-astra, 지능과 비용의 균형은 gpt-6.2-sol, 대량·저비용 작업은 gpt-6-luna다 (Models). 세 모델 모두 텍스트와 이미지 입력, 텍스트 출력, 다국어를 지원한다.

모델문서상 위치입력 1M 토큰출력 1M 토큰캐시 입력 1M 토큰
gpt-6.2-astra플래그십, 복잡한 추론·코딩$8.00$40.00$0.40
gpt-6.2-sol지능·비용 균형$2.00$10.00$0.10
gpt-6-luna저비용·대량 처리$0.10$0.50$0.01

그림 2. 설치·첫 호출 순서와 1M 토큰 단가표. 출력 단가가 입력의 5배다.

가격은 모두 공식 가격표의 Standard, 짧은 컨텍스트 기준이다. 표를 보면 출력 단가가 입력 단가의 다섯 배라는 점이 눈에 들어온다. 같은 질문이라도 답을 길게 늘어놓게 만들면 비용이 훨씬 빨리 오른다.

처음 붙이는 단계라면 gpt-6.2-sol로 시작해서 품질이 부족할 때 astra로 올리는 편이 안전하다. 반대로 분류, 요약, 태깅처럼 정답이 뻔한 작업을 하루 수만 건 돌린다면 luna 쪽이 맞다.

요금 — 1M 토큰당 가격과 배치 할인

요금은 토큰 단위로 매겨지고, 입력과 출력이 따로 계산된다. 1M 토큰은 한글 기준으로 책 한두 권 분량이니, 짧은 챗봇 하나를 돌리는 정도로는 몇 달러 안에서 끝나는 경우가 많다.

비용을 줄이는 방법은 크게 두 가지다. 프롬프트 앞부분을 고정해 캐시 입력 단가(입력가의 5%)를 적용받는 것, 그리고 급하지 않은 작업을 Batch로 돌리는 것이다. Batch 가격은 Standard의 절반이다. astra 기준 입력 $4.00, 출력 $20.00이고, luna는 입력 $0.05, 출력 $0.25다 (가격표).

모델Standard 입력Batch 입력Standard 출력Batch 출력
gpt-6.2-astra$8.00$4.00$40.00$20.00
gpt-6.2-sol$2.00$1.00$10.00$5.00
gpt-6-luna$0.10$0.05$0.50$0.25

실제 지출은 대시보드 Usage 화면에서 확인한다. 호출마다 남는 사용량을 앱 안에서 직접 집계하지 않고, 대시보드 숫자를 기준으로 삼는 편이 계산 실수가 적다.

대화 이어가기와 스트리밍

챗봇처럼 앞 대화를 기억해야 한다면 두 방식이 있다. 대화 전체를 매번 input에 다시 넣는 방법과, 이전 응답 ID를 넘기는 방법이다. 후자는 previous_response_id를 쓰고, 저장을 원하면 store를 켠다 (Conversation state).

first = client.responses.create(
    model="gpt-6.2-sol",
    input="파이썬에서 예외 처리를 왜 쓰는지 한 줄로 알려줘.",
    store=True,
)

second = client.responses.create(
    model="gpt-6.2-sol",
    previous_response_id=first.id,
    input=[{"role": "user", "content": "방금 답을 초등학생에게 설명하듯 바꿔줘."}],
)

print(second.output_text)

답이 길어서 기다리기 답답하면 stream=True를 준다. 이벤트가 하나씩 도착하므로 화면에 타이핑되듯 출력할 수 있다 (Streaming).

stream = client.responses.create(
    model="gpt-6.2-sol",
    input="터미널에서 자주 쓰는 단축키 다섯 개만 알려줘.",
    stream=True,
)

for event in stream:
    print(event)

처음엔 이벤트 종류가 많아 보이지만, 텍스트 조각만 받고 싶으면 이벤트 안의 타입을 확인해 델타만 골라 출력하면 된다. 스트리밍은 체감 속도를 바꾸는 기능이지, 토큰 요금을 깎아 주는 기능은 아니다.

자주 나는 에러 401·429 해결법

에러 코드별 원인과 조치는 공식 Error codes 문서에 정리돼 있다. 실제로 가장 자주 만나는 네 가지를 표로 줄였다.

코드메시지원인조치
401Incorrect API key provided키 오타, 폐기된 키, 다른 조직 키키 재발급 후 환경변수 다시 설정
401You must be a member of an organization조직에 속하지 않은 계정조직 초대 수락 또는 관리자에게 요청
429Rate limit reached for requests짧은 시간에 요청 과다Retry-After 헤더만큼 대기 후 재시도
429Credit balance exhausted선불 크레딧 소진대시보드에서 크레딧 충전
503Model temporarily overloaded해당 모델 일시 과부하Retry-After 확인 후 재시도

429는 두 종류를 구분해야 한다. 크레딧이 없어서 나는 429는 몇 번을 재시도해도 그대로다. 반면 요청 속도 때문에 나는 429는 잠깐 기다리면 풀린다. 에러 본문의 code 값을 보면 credit_balance_exhausted인지 rate_limit_error인지 구분된다.

재시도를 코드로 넣을 때는 지수 백오프를 같이 쓰는 게 좋다. 1초, 2초, 4초처럼 간격을 늘리면서 최대 세 번 정도만 시도하고, 그래도 안 되면 로그를 남기고 멈추는 편이 안전하다.

내가 막혔던 곳

처음 API를 붙일 때 검색으로 나온 예제가 전부 client.chat.completions.create 기준이었다. 그대로 붙여 넣으면 모델 이름이 맞지 않는다는 에러부터 시작해서, 응답에서 텍스트를 꺼내는 위치도 지금 문서와 달라 헷갈렸다. 지금 문서의 기본 경로는 responses.create이고 본문은 output_text 하나로 끝난다.

두 번째로 막힌 곳은 환경변수였다. 터미널에서 export한 키가 IDE 안에서는 안 잡혔다. 에디터를 완전히 종료했다가 다시 열어야 환경변수를 새로 읽는 경우가 있다. 이걸 모르고 코드를 계속 고치며 401을 반복했다.

세 번째는 결제 등록이었다. 키는 멀쩡한데 429가 떠서 코드를 의심했는데, 원인은 크레딧이 0이었던 것이다. 429를 보면 코드보다 대시보드 Billing을 먼저 여는 습관이 생겼다.

이 세 가지를 겪고 나니, 새 프로젝트를 시작할 때 확인 순서가 고정됐다. 결제 등록 → 키 발급 → 환경변수 확인 → responses.create 한 번 호출. 이 순서만 지키면 초반 삽질이 거의 사라진다.

참고 자료

같이 보면 좋은 글: Claude API 사용법 (Python) · RAG가 뭐야 (검색증강생성)

반응형
반응형
어사이드 vs 에고 라이트 vs 핸들러스 — 내 브라우저를 AI에게 맡기는 3가지 방법

AI에게 내 브라우저를 맡기는 방법은 크게 셋으로 갈린다. 브라우저를 통째로 갈아타거나(어사이드), 나와 같이 쓰는 브라우저를 새로 깔거나(에고 라이트), 지금 쓰는 브라우저에 연결만 하거나(핸들러스). 셋 다 "로그인된 웹을 에이전트가 쓴다"고 말하지만, 실제로 달라지는 건 내 탭과 계정을 누가 얼마나 건드리느냐다.

30초 요약

항목어사이드(Aside)에고 라이트(ego lite)핸들러스(Handlus)
정체에이전트용으로 다시 지은 브라우저나와 에이전트가 함께 쓰는 브라우저브라우저 확장 + 컴퓨터 앱 + 원격 MCP
에이전트앱 내장 + CLI·MCP·REPL어떤 에이전트든 ego-browser 스킬로Claude Code·Codex 등 원격 MCP 클라이언트
내 탭새 브라우저라 충돌 없음Space로 분리내 브라우저를 직접 씀
컴퓨터 앱 제어파일·스프레드시트 수준브라우저만계산기·엑셀까지 가능
요금무료 월 500크레딧 / Pro $20 / Max $200무료(MIT)무료 주 1,500회 / Pro $20 / Enterprise $49
한 줄 추천브라우저를 갈아탈 각오병렬 작업·코드 제어·무료설치 최소·지금 브라우저 그대로

그림 1. 같은 문제를 푸는 세 갈래 — 갈아타기, 같이 쓰기, 붙이기.

목차

  1. 세 제품은 같은 문제를 다르게 푼다
  2. 한눈에 비교 — 연결 방식과 요금
  3. 어사이드(Aside) — 브라우저를 갈아타는 쪽
  4. 에고 라이트(ego lite) — 브라우저를 같이 쓰는 쪽
  5. 핸들러스(Handlus) — 지금 쓰는 브라우저에 붙이는 쪽
  6. 상황별 추천 — 이럴 때 이걸
  7. 같이 쓸 수 있을까
  8. 내가 막혔던 곳

세 제품은 같은 문제를 다르게 푼다

세 제품이 푸는 문제는 같다. 에이전트는 로그인이 안 된 빈 창을 들고 있고, 내 계정에는 로그인이 살아 있다. 이 간극을 메우는 방식이 다를 뿐이다.

방식대표에이전트가 쓰는 창대가
브라우저 교체어사이드새 브라우저 안브라우징 습관을 옮겨야 한다
공유 브라우저에고 라이트같은 브라우저의 Space브라우저를 하나 더 깐다
연결(확장+중계)핸들러스지금 쓰는 크롬 창내 탭을 에이전트와 나눠 쓴다

이 차이가 실무에서 드러나는 지점은 세 가지다. 작업 중에 내 탭을 뺏기는지, 병렬로 여러 작업을 돌릴 수 있는지, 로그인 정보가 어디까지 넘어가는지다.

한눈에 비교 — 연결 방식과 요금

2026-11-20에 각 공식 페이지에서 확인한 값이다. 요금은 달러 기준이고 부가세는 별도다.

항목어사이드에고 라이트핸들러스
플랫폼macOS 15+, Windows 10 22H2+macOS, WindowsmacOS·Windows 앱 + 크롬·엣지·웨일·브레이브 확장
에이전트 연결내장 에이전트, aside CLI·MCP·REPL/ego-browser 스킬 → ego-browser nodejsclaude mcp add --transport http handlus https://api.handlus.com/mcp
로그인 재사용브라우저 데이터 가져오기 + 금고 자동완성크롬 데이터 가져오기지금 브라우저 세션 그대로
병렬 작업작업·루틴 단위Space마다 동시 실행브라우저별 이름 지정
컴퓨터 제어파일·스프레드시트 작업없음(브라우저 전용)앱 열기·클릭·입력
무료 한도월 500크레딧, 루틴 3개제한 없음(모델 비용은 내 몫)주 1,500회(컴퓨터 300회)
유료Pro $20, Max $200, Enterprise 문의없음Pro $20(한국 $22), Enterprise $49($53.90)
데이터기기 내 저장·암호화기기 내 저장중계 서버는 저장 안 함, 기록 30일

그림 2. 플랫폼·연결·한도·요금을 같은 날 확인해 나란히 놓았다.

표만 보면 비슷해 보이지만, 무료 한도의 단위가 전부 다르다. 크레딧(월)과 도구 호출(주)과 무제한은 서로 환산이 안 된다. 이건 뒤에서 따로 짚는다.

어사이드(Aside) — 브라우저를 갈아타는 쪽

어사이드는 "AI를 브라우저에 얹은 것"이 아니라 브라우저를 에이전트 작업대로 다시 지은 제품이다. 공식 소개는 "사람과 에이전트를 위해 다시 지은 브라우저"라고 말한다(Aside). macOS 15 이상, 윈도우 10 22H2 이상을 요구하고 x64·ARM64 설치 파일을 준다.

가장 큰 특징은 브라우저 자체를 바꾼다는 점이다. 크롬 데이터를 가져와 로그인 상태를 옮기고, 그 브라우저 안에서 에이전트가 일한다. 내가 쓰던 크롬 탭과 섞이지 않으니 충돌이 없다.

에이전트를 부르는 방법도 여러 갈래다. 앱 안에서 말로 시키는 것 외에 aside CLI, MCP 서버, REPL이 있다. REPL은 Playwright 문법으로 페이지를 직접 다루는 방식이라, 개발자가 브라우저 자동화를 짜던 습관을 그대로 가져올 수 있다.

차별점은 세 가지다.

  • 메모리: 브라우징 기록에서 인물·회사·결정을 추려 마크다운으로 기기에 저장한다. 사이트별로 통했던 경로도 기억한다.
  • 금고: 비밀번호를 모델에 보여주지 않고 페이지에 자동완성한다. 결제·발송·게시는 내 승인을 기다린다. 자격증명 사용은 로그로 남는다.
  • 루틴: 예약 작업을 걸어 둘 수 있다. 무료는 3개, Pro부터 무제한이다.

요금은 가격 페이지 기준으로 Free $0(월 500크레딧), Pro 월 $20(무료의 3배, Ultrabrowse, 루틴 무제한), Max 월 $200(무료의 40배), Enterprise 별도 문의다. 연간 결제는 20% 할인된다. 크레딧은 모델과 속도에 따라 차감 단가가 다르고, 직접 연결한 API 키 사용료는 별도다(구독 문서).

단점도 분명하다. 브라우저를 갈아타는 결정이라 초기 이주 비용이 들고, 성능 수치는 자사 측정이다. 앞서 쓴 Aside 리뷰에서 벤치마크 조건을 자세히 따졌으니 참고하면 된다.

에고 라이트(ego lite) — 브라우저를 같이 쓰는 쪽

에고 라이트는 확장이 아니라 브라우저다. 크로미움 기반이라 쓰는 감각은 크롬과 같고, macOS·윈도우를 지원한다. 앱은 무료고 저장소는 MIT로 공개돼 있다(GitHub).

핵심은 Space다. 에이전트마다 같은 브라우저 안에 격리된 작업 공간이 생긴다. 새 창도, 두 번째 프로필도, 헤드리스도 아니다. 그래서 내가 읽던 탭은 그대로 두고, 에이전트는 자기 Space에서 페이지를 열고 읽고 클릭한다. 작업이 궁금하면 Space를 열어 보거나 직접 이어받을 수 있다.

연결은 앱이 자동으로 해준다. 온보딩이 ego-browser 스킬을 ~/.agents/skills와 ~/.claude/skills에 넣고, 에이전트에서 /ego-browser를 부르면 된다. 실행은 코드 기반이다. 에이전트가 Node.js 스크립트를 쓰면 ego-browser nodejs가 한 번에 돌린다. 명령을 주고받는 왕복이 없으니 토큰이 덜 들고 빨리 끝난다.

기존 도구와 갈리는 지점은 이렇다.

  • 병렬: Space마다 작업을 동시에 돌린다. 리드 10개를 10개 Space에서 보강하는 식이다.
  • 스냅샷: 페이지를 텍스트로 바꿔 @3 같은 참조를 준다. 중첩 iframe처럼 자주 깨지는 곳을 엔진에서 처리한다.
  • 비용: 앱은 무료다. 쓰는 모델과 네트워크 비용만 내면 된다.

주의할 점도 있다. API가 Playwright가 아니라서 locator() 같은 메서드가 없다. 설치된 버전의 안내(ego-browser skill)를 먼저 읽어야 한다. 자동 경험 축적은 아직 제한된 베타고, 리눅스는 로드맵이다. 자세한 설치·사용법은 에고 라이트 사용법에 정리해뒀다.

핸들러스(Handlus) — 지금 쓰는 브라우저에 붙이는 쪽

핸들러스는 브라우저를 새로 깔지 않는다. 크롬·엣지·웨일·브레이브에 확장을 붙이고, 컴퓨터에는 앱을 깐다. 에이전트는 원격 MCP 서버 하나(https://api.handlus.com/mcp)를 통해 그 브라우저와 컴퓨터를 조작한다(Handlus).

가장 큰 장점은 이주가 없다는 것이다. 지금 로그인해 둔 브라우저를 그대로 쓴다. 계정별로 브라우저 이름을 붙여 두고 "작업용 브라우저에서"처럼 골라 시킨다. 여러 개가 켜져 있으면 짐작하지 않고 물어본다.

두 번째 장점은 컴퓨터 앱까지 된다는 것이다. Handlus 앱을 깔고 손쉬운 사용 권한을 허용하면 계산기·엑셀·메모장 같은 프로그램을 열고 입력한다. 브라우저 자동화 도구 중 데스크톱까지 손을 뻗는 쪽은 드물다. 다만 비밀번호 관리자와 시스템 설정 앱은 건드리지 않고, 입력값도 기록하지 않는다고 밝힌다.

요금은 Free $0(에이전트 2·기기 2·주 1,500회, 컴퓨터 300회), Pro 월 $20(한국 $22, 기기 5대·무제한), Enterprise 월 $49($53.90)다. 무료 한도는 매주 월요일 오전 9시(한국 시간)에 다시 찬다(요금).

대신 내 브라우저를 직접 쓴다. 에이전트가 내 탭에서 움직이므로, 작업 중에 탭이나 포커스를 건드릴 수 있다. 병렬로 여러 작업을 돌리는 쪽보다는 한 번에 하나씩 맡기는 흐름에 맞다. 자세한 설정은 핸들러스 MCP 사용법에 있다.

상황별 추천 — 이럴 때 이걸

세 제품의 성격이 다르니 "무조건 이게 낫다"는 답은 없다. 내 상황을 먼저 고르는 게 빠르다.

내 상황추천이유
브라우저는 그대로 두고 설치만 최소로핸들러스확장 하나로 끝. 로그인 이주 없음
엑셀·계산기 같은 프로그램도 시켜야 함핸들러스컴퓨터 앱 제어가 기본 포함
여러 작업을 동시에 돌리고 싶다에고 라이트Space 단위 병렬 실행
자동화를 코드로 직접 짜고 싶다에고 라이트Node.js 한 덩어리 실행, 무료
브라우저를 아예 업무용으로 바꾸고 싶다어사이드메모리·금고·루틴이 브라우저에 통합
예약 작업과 승인 게이트가 필요어사이드루틴 + 결제·발송 승인 + 감사 로그
비용을 최소화하고 싶다에고 라이트 → 핸들러스둘 다 무료로 시작 가능

그림 3. 기능 목록이 아니라 막히는 지점으로 고르는 판단 순서.

처음 시작하는 사람에게는 순서를 이렇게 권한다. 읽기 전용 작업 하나를 세 도구 중 편한 걸로 돌려보고, 그 작업이 막히는 지점이 어디인지 보는 게 빠르다. 로그인에서 막히면 어사이드나 핸들러스, 병렬에서 막히면 에고 라이트, 컴퓨터 앱에서 막히면 핸들러스다.

같이 쓸 수 있을까

충돌만 없으면 조합도 된다. 실제로 겹치는 부분이 많지 않다.

  • 에고 라이트 + 핸들러스: 브라우저 작업은 에고 라이트 Space에서 병렬로, 데스크톱 작업은 핸들러스로. 둘 다 무료로 시작할 수 있어 비용 부담이 적다.
  • 어사이드 + 핸들러스: 업무용은 어사이드로 갈아타고, 기존 크롬에 남은 사내 시스템만 핸들러스로 붙이는 식이다.
  • 셋 다: 추천하지 않는다. 로그인 세션이 세 곳에 흩어지고, 어느 에이전트가 어느 브라우저를 쓰는지 헷갈린다. 도구를 늘리는 것보다 하나를 제대로 쓰는 편이 낫다.

조합할 때 지켜야 할 원칙은 하나다. 에이전트마다 쓰는 브라우저를 하나로 고정한다. 같은 사이트를 두 도구가 동시에 건드리면 로그인 세션이 꼬인다.

내가 막혔던 곳

첫 번째는 "브라우저"라는 단어가 세 제품에서 전부 다른 뜻이라는 점이다. 어사이드는 갈아타는 브라우저, 에고 라이트는 같이 쓰는 브라우저, 핸들러스는 확장을 붙이는 대상이다. 소개 문장만 읽으면 셋 다 비슷하게 들려서, 처음엔 같은 제품군인 줄 알았다.

두 번째는 무료 한도 비교다. 어사이드는 월 500크레딧, 핸들러스는 주 1,500회, 에고 라이트는 무제한이다. 숫자만 놓고 "핸들러스가 3배"라고 하면 틀린다. 크레딧은 모델과 작업 길이에 따라 차감되고, 도구 호출은 페이지 열기·읽기·클릭이 각각 1회다. 같은 작업을 돌려봐야만 비교가 된다. 그래서 이 글에서는 환산표를 만들지 않았다.

세 번째는 성능 수치다. 어사이드와 에고 라이트 모두 자사 벤치마크를 내세운다. 어사이드는 99.0% 같은 숫자를, 에고 라이트는 47~63% 빠르다는 숫자를 말한다. 둘 다 만든 쪽이 만든 측정이다. 숫자보다 "내 작업에서 끝까지 가는가"를 먼저 보는 게 낫다.

네 번째는 권한이다. 셋 다 로그인된 계정을 에이전트에 넘긴다. 결제·발송·삭제가 걸린 작업은 승인 게이트를 켜고, 업무용과 개인용 프로필을 분리하는 게 기본이다. 에이전트가 도구를 고르는 원리는 AI 에이전트란에 정리해뒀다.

솔직히 적으면, 이 글은 세 제품의 공식 문서와 가격 페이지를 같은 날 확인해 비교한 것이다. 셋 다 실제로 설치해 장기간 써본 것은 아니고, 어사이드와 에고 라이트는 설치 단계에서 계정·키체인 권한이 걸려 직접 실행하지 않았다. 대신 각 제품의 설정 문서와 요금 문서를 원문으로 확인했다.

참고 자료

반응형
반응형
에고 라이트(ego lite) 사용법 — 클로드코드가 내 로그인 브라우저를 쓴다

브라우저 자동화는 늘 같은 곳에서 막힌다. 에이전트는 로그인이 안 된 빈 창을 들고 있고, 내 크롬에는 로그인이 살아 있다. ego lite(에고 라이트)는 그 둘을 하나로 합친다. 확장을 붙이는 게 아니라, 나와 에이전트가 같은 브라우저를 나눠 쓰는 방식이다.

30초 요약

항목내용
한 줄 정의나와 AI 에이전트가 함께 쓰는 크로미움 브라우저. 에이전트는 자기만의 Space에서 작업한다
설치macOS(dmg)·윈도우(exe) 앱. 온보딩에서 크롬 데이터(로그인·쿠키·확장·북마크) 가져오기 선택
연결앱이 에이전트 스킬 폴더에 넣어주는 ego-browser를 /ego-browser로 호출
비용앱 무료, 저장소 MIT. 모델·네트워크 비용은 내 몫
속도제조사 자체 벤치 31개 작업에서 다른 도구보다 47~63% 빠르다고 주장(자체 측정)
주의로그인 세션을 그대로 쓰므로 결제·전송은 사람이 확인한다. 리눅스는 아직 로드맵

그림 1. 확장을 붙이는 게 아니라, 나와 에이전트가 같은 브라우저를 나눠 쓴다.

목차

  1. 에고 라이트(ego lite)란 — 확장이 아니라 브라우저
  2. 설치 — dmg 하나, 스킬은 자동
  3. 클로드코드에 연결 — /ego-browser와 권한
  4. 첫 작업 — 스크립트 한 덩어리로 시키기
  5. Space·Snapshot — 내 탭을 뺏지 않는 구조
  6. 요금과 데이터 — 무료, 로컬 저장
  7. 한계와 주의할 점
  8. 내가 막혔던 곳

에고 라이트(ego lite)란 — 확장이 아니라 브라우저

ego lite는 공식 소개에서 "AI 에이전트를 위한 가장 빠른 웹 자동화 브라우저"라고 부르는 앱이다. 크로미움 기반이라 쓰는 감각은 크롬과 같다. 다른 점은 에이전트가 Space라는 자기 작업 공간을 따로 받는다는 것이다.

Space는 새 창도, 두 번째 크롬 프로필도, 헤드리스 브라우저도 아니다. 같은 ego lite 안에서 탭 묶음만 갈라 놓은 공간이다. 그래서 내가 읽던 탭은 그대로 두고, 에이전트는 자기 Space에서 페이지를 열고 읽고 클릭한다. 작업이 궁금하면 Space를 열어 구경하거나, 손이 필요하면 내가 대신 조작할 수 있다.

기존 도구와의 차이는 문서가 다섯 갈래로 정리해 둔다.

유형방식ego lite와 차이
브라우저 확장내 크롬 창에 명령을 전달브라우저 자체라 붙일 확장이 없다. 내 탭을 건드리지 않는다
클라우드 브라우저남의 서버에서 브라우저가 돈다내 컴퓨터에서 돌아 로그인이 밖으로 안 나간다. 브라우저 사용료가 없다
AI 앱 내장 브라우저한 앱 안의 브라우저 환경내 에이전트가 내 코드·파일과 함께 쓴다
브라우저 CLI명령으로 세션을 조작눈에 보이는 브라우저 + Space + 자바스크립트 실행기를 준다
AI 브라우저사이드바에 그 회사 AI가 붙음내 에이전트가 직접 몬다

설치 — dmg 하나, 스킬은 자동

설치는 다운로드 페이지에서 파일을 받아 실행하면 끝이다. 실제 파일 크기를 확인해보니 이렇다(2026-11-20 기준).

플랫폼파일크기
macOS Apple Silicondmg149MB
macOS Inteldmg168MB
윈도우 x64exe19MB

dmg를 열고 안내대로 ego lite 아이콘을 두 번 눌러 설치한다. 첫 실행 온보딩에서 두 가지가 일어난다.

첫째, 설치된 에이전트를 훑어서 ego-browser 스킬을 스킬 폴더에 넣는다. 문서에 적힌 경로는 ~/.agents/skills와 ~/.claude/skills/다. 클로드코드 기준으로는 ~/.claude/skills/ego-browser/가 생겼는지 보면 된다.

둘째, 다른 브라우저에서 데이터를 가져올지 묻는다. 여기서 크롬을 고르면 로그인 세션·쿠키·비밀번호·확장·북마크가 ego lite로 넘어온다. 넘어온 데이터는 내 컴퓨터에만 남는다. macOS에서는 이 과정에서 키체인 암호를 여러 번 물을 수 있으니, 그때마다 입력하면 된다.

앱 없이 스킬만 먼저 넣고 싶으면 npx 명령도 있다.

npx skills add citrolabs/ego-lite

다만 이 경우에도 브라우저 앱은 따로 설치해야 한다. 스킬은 설명서고, 실제 브라우저는 앱이기 때문이다.

클로드코드에 연결 — /ego-browser와 권한

에이전트 채팅창에서 /ego-browser를 치면 스킬이 올라온다. 그 뒤에 한 칸 띄고 시킬 일을 쓰면 된다.

/ego-browser OpenAI와 Anthropic 블로그를 열어서 최근 글 요점만 정리해줘

주의할 점이 두 가지 있다. 첫째, Cowork가 아니라 Code 세션이어야 한다. 클로드 데스크톱 앱에서 Cowork와 Code가 같은 앱 안에 있어서, /ego-browser가 Code에는 보이고 Cowork 메뉴에는 안 보이는 상황이 생긴다. 이때 설치는 멀쩡한데 안 된 것처럼 느껴진다.

둘째, 권한이다. ego-browser는 내 컴퓨터에서 앱을 실행하는 명령이라, 샌드박스 밖 실행 권한이 필요하다. 문서와 녹화 영상은 Claude Code에서 Bypass permissions를 쓰지만, 그건 한 가지 설정일 뿐 유일한 답은 아니다. 조직 정책상 바이패스가 안 보이면 명령별 승인이나 허용 규칙으로 풀 수도 있다. 권한 문서는 Claude Code permissions에 있다.

스킬이 떴는지 확인하는 가장 확실한 방법은 작은 작업을 시켜보는 것이다.

ego-browser로 https://example.com 열어서 실제 URL과 title만 돌려줘. 다른 브라우저 도구는 쓰지 마.

이때 엉뚱한 도구가 열리면 "ego-browser를 써라"를 한 번 더 명시하면 된다. 클로드코드 설치부터 낯설면 Claude Code 설치·사용법을 먼저 보면 된다.

첫 작업 — 스크립트 한 덩어리로 시키기

ego lite의 핵심은 에이전트가 명령을 여러 번 왕복하지 않고, 자바스크립트 한 덩어리로 일을 끝낸다는 점이다. ego-browser는 표준입력으로 받은 Node.js 코드를 한 번에 실행한다.

ego-browser nodejs <<'JS'
const task = await taskSpace('예제 페이지 읽기');
const page = task.page('p1');
await page.goto('https://example.com');
console.log(await page.snapshot());
console.log({ title: await page.title(), url: await page.url() });
await task.finish({ keep: [] });
JS

그림 3. 문서 예제를 기준으로 재구성한 실행 흐름(실제 실행 화면은 아님).

이 스크립트 하나가 Space를 만들고, 페이지를 열고, 본문을 텍스트로 읽고, URL과 제목을 돌려주고, Space를 정리한다. 중간에 결과를 보고 다시 명령을 내리는 왕복이 없으니 토큰도 덜 쓰고 빨리 끝난다. 제조사는 이걸 "CLI 기반 루프 대신 코드 기반 실행"이라고 설명한다.

페이지를 조작할 때는 스냅샷이 준 참조를 쓴다. page.snapshot()을 부르면 페이지가 텍스트로 바뀌고, 요소마다 @3 같은 짧은 번호가 붙는다.

@3 [input type="email"] placeholder="Email"
@5 [button type="submit"] "Continue"

그 번호로 page.fill('@3', '...'), page.click('@5')를 호출한다. 페이지가 바뀌면 스냅샷을 다시 읽어야 한다.

await page.fill('#query', 'Alpha');
await page.click('#search', { label: '검색 버튼' });
await page.waitForSelector('text=Search: Alpha');
const result = await page.evaluate(() =>
  document.querySelector('#search-result').textContent
);
console.log({ result });

여기서 중요한 건 Playwright가 아니라는 점이다. locator()나 getByRole() 같은 메서드는 없다. 설치된 버전의 안내를 먼저 읽어야 한다. 터미널에서 ego-browser skill을 치면 그 버전에 맞는 사용법이 출력되고, 마지막 줄이 [ego-browser:skill] end of guide로 끝나야 잘린 게 아니다. 문서 기준 최신 가이드는 2.2.1, 테스트 버전은 ego(lite) 0.6.3.6이었다.

로그인이나 인증이 필요하면 에이전트가 await task.handOff()로 나를 부른다. 내가 Space에서 직접 로그인하고 알려주면 takeOverTaskSpace(spaceId)로 같은 공간을 이어받는다. 비밀번호와 인증번호를 채팅창에 붙여넣지 말라는 것도 문서가 먼저 강조한다.

Space·Snapshot — 내 탭을 뺏지 않는 구조

이 브라우저가 편한 이유는 속도보다 충돌이 없다는 쪽이다. 확장 방식은 내가 쓰는 창에서 명령이 실행되니, 작업 중에 탭이나 포커스를 뺏길 수 있다. ego lite는 에이전트마다 Space가 따로 있어서 내 마우스 위치와 읽던 탭이 그대로 남는다.

항목ego lite브라우저 확장
실행 위치내 컴퓨터내 컴퓨터
내 탭건드리지 않음(Space 분리)같은 창을 공유
병렬 작업Space마다 동시에보통 한 창에서 순차
로그인가져온 세션 그대로원래 브라우저 세션
캡차내 IP·내 세션내 IP·내 세션
비용앱 무료도구에 따라 유료

그림 2. 한 브라우저 안에서 내 탭과 에이전트 Space가 갈라져 있다.

Space는 작업마다 하나씩 두는 게 보통이다. 동시에 몇 개까지 돌릴 수 있는지는 컴퓨터 메모리와 CPU에 달렸다. 리드 10개를 10개 Space에서 동시에 보강하고, 경쟁사 5곳을 5개 Space에서 긁는 식이다.

Snapshot은 페이지를 텍스트로 바꾼 것이라, 화면을 못 보는 모델도 페이지를 읽을 수 있다. 기본은 뷰포트 범위고, 문서 전체가 필요하면 page.snapshot({ scope: "full_page" })로 넓힌다. 중첩 iframe처럼 자동화가 자주 깨지는 곳을 엔진 단에서 처리한다고 문서가 설명한다.

요금과 데이터 — 무료, 로컬 저장

ego lite 앱은 무료다. 저장소는 MIT 라이선스로 공개돼 있다(GitHub). 브라우저 사용료가 따로 없고, 비용은 내가 쓰는 모델과 네트워크에서만 나온다. 클라우드 브라우저가 세션·분 단위로 과금하는 것과 반대다.

데이터는 내 기기에 남는다. 크롬에서 가져온 로그인·쿠키·비밀번호·확장·북마크는 로컬에 있고, 회사 서버로 올라가지 않는다. 수집하는 건 "기본 브라우저로 설정했는지" 같은 단순 제품 신호뿐이라고 밝힌다.

다만 로컬 저장이 만능은 아니다. 페이지를 읽은 내용은 내가 고른 모델의 컨텍스트로 들어간다. 문서도 이 점을 분명히 적어둔다. 브라우저가 내 컴퓨터에 있다는 사실과, 페이지 내용이 모델에 안 간다는 사실은 별개다.

한계와 주의할 점

먼저 성능 숫자. "47~63% 빠르다"는 제조사가 자사 도구를 넣고 돌린 자체 벤치다. 같은 에이전트(pi), 같은 모델(gpt-5.6-sol, thinking max), 31개 과제, 같은 채점자로 맞췄다고는 하지만 만든 쪽이 만든 측정이다. 내 작업에서도 그만큼 빠른지는 직접 재봐야 안다.

둘째, 자동 경험 축적은 아직 제한된 베타다. 성공한 작업이 자동으로 재사용 스킬이 된다고 기대하면 안 된다. 지금 확실한 건 내가 스크립트를 저장해 다시 돌리는 수준이다. 저장한 스크립트도 셀렉터와 로그인 상태가 바뀌면 다시 손봐야 한다.

셋째, 크롬 탭과 실시간으로 동기화되지 않는다. 크롬 데이터를 가져오는 건 로그인 환경을 복사하는 것이지, 지금 열려 있는 크롬 탭에 에이전트가 붙는 게 아니다. 그게 필요하면 클로드코드의 크롬 확장 쪽을 봐야 한다.

넷째, 권한이 크다. Bypass permissions로 돌리면 에이전트가 로컬 명령을 승인 없이 실행한다. 결제·전송·삭제가 걸린 작업은 중간에 멈추게 만들고, 계정과 조직이 맞는지 화면에서 확인하는 습관이 필요하다. 앞서 쓴 핸들러스 MCP 사용법도 같은 이유로 "결제 화면은 손으로"를 강조했다. 에이전트가 도구를 고르는 원리는 AI 에이전트란에 정리해뒀다.

다섯째, 리눅스는 아직 로드맵이다. 지금은 macOS와 윈도우만 된다.

내가 막혔던 곳

이 글을 쓰면서 실제로 헷갈린 건 설치 순서였다. 앱을 먼저 깔아야 하는지, 스킬을 먼저 넣어야 하는지가 문서마다 다르게 보였다. 정리하면 앱이 먼저다. 앱 온보딩이 끝나야 ego-browser 실행 파일이 PATH에 생기고, 그때 ego-browser skill이 동작한다. npx로 스킬만 먼저 넣으면 설명서만 있고 브라우저가 없어서, 첫 작업에서 "명령을 찾을 수 없다"로 막힌다.

두 번째는 Cowork와 Code다. 같은 클로드 앱 안에 두 모드가 있어서, Cowork에서 /ego-browser를 찾다가 "스킬 설치가 안 됐나"로 오해하기 쉽다. Code 세션에서 다시 확인하면 대부분 해결된다.

세 번째는 스냅샷 참조다. @3 같은 번호는 페이지가 바뀌면 무효가 된다. 처음엔 한 번 읽은 스냅샷으로 계속 클릭하려다 실패했다는 사례를 문서 곳곳에서 봤다. 지금은 클릭 뒤에 스냅샷을 다시 읽는 걸 기본으로 둔다.

솔직히 적으면, 나는 앱 설치와 크롬 데이터 가져오기까지는 하지 않았다. 키체인 암호와 브라우저 세션이 걸린 단계라 계정 주인이 직접 하는 게 맞다고 판단했다. 대신 공식 문서 6개, 저장소의 스킬 원문(2.2.1), 다운로드 파일 크기를 직접 확인하고 썼다. 설치 화면과 첫 실행은 직접 보지 않았다는 뜻이다.

참고 자료

반응형
반응형
핸들러스(Handlus) MCP 사용법 — 클로드코드가 내 브라우저를 직접 조작한다

클로드코드한테 "내 브라우저에서 그 페이지 열어서 표만 뽑아줘"라고 시키고 싶은데, 터미널에 갇힌 에이전트는 남의 사이트 로그인 상태를 모른다. 핸들러스(Handlus) MCP는 그 구멍을 브라우저 확장 하나로 메운다. 내가 로그인해 둔 크롬을 원격 MCP로 넘겨주는 방식이라, 에이전트가 새 세션을 여는 대신 이미 켜져 있는 브라우저를 그대로 쓴다.

30초 요약

항목내용
한 줄 정의내 브라우저(크롬·엣지·웨일·브레이브)와 내 컴퓨터를 AI 에이전트에 원격 MCP로 붙여 주는 서비스
붙이는 명령claude mcp add --transport http handlus https://api.handlus.com/mcp
연결 순서확장 설치 → 브라우저 연결(이메일 인증·구글 로그인·연결 키) → 에이전트에 주소 등록 → /mcp에서 Authenticate
무료 한도에이전트 2개·기기 2대·도구 호출 주 1,500회(컴퓨터 조작 300회)
유료Pro 월 $20(한국 부가세 포함 $22), Enterprise 월 $49($53.90)
안 되는 것파이어폭스·사파리, 리눅스 컴퓨터 조작은 아직 목록에 없다
주의로그인된 브라우저를 통째로 넘기는 구조라, 결제·비밀번호 화면은 손으로 하는 게 안전하다

그림 1. 확장 하나와 MCP 주소 하나로 내 브라우저가 에이전트의 손이 된다.

목차

  1. 핸들러스 MCP란 — 확장 하나, 주소 하나
  2. 설치 1~2단계 — 확장 설치와 브라우저 연결
  3. 클로드코드에 붙이기 — claude mcp add 한 줄
  4. 실제로 시켜보기 — 브라우저 도구 이름과 예시
  5. 요금과 한도 — 무료로 어디까지
  6. 보안과 주의할 점
  7. 내가 막혔던 곳

핸들러스 MCP란 — 확장 하나, 주소 하나

핸들러스는 "에이전트는 머리, 브라우저와 컴퓨터는 손"이라고 설명한다(Handlus 소개). 구조는 단순하다. 브라우저에는 확장을 깔고, 컴퓨터에는 앱을 깐다. 둘 다 Handlus 계정에 연결해 이름을 붙인다. 그러면 에이전트 쪽에서는 MCP 서버 하나만 보이고, 어느 브라우저를 쓸지는 그 서버의 도구로 고른다.

중계 서버 주소는 https://api.handlus.com/mcp 하나다. 이 주소는 /mcp(MCP over HTTP)와 /ws 두 갈래로 받는다고 소개 페이지에 적혀 있다. 인증은 OAuth 방식이라, 에이전트에서 붙인 다음 브라우저로 로그인 한 번만 하면 된다.

지원 범위는 표로 보는 게 빠르다.

구분됨아직 안 됨
브라우저크롬, 엣지, 웨일, 브레이브파이어폭스, 사파리(준비 중)
컴퓨터맥, 윈도우리눅스
에이전트Claude Code, Claude, ChatGPT, Codex (공식 확인)원격 MCP(HTTP)와 OAuth만 지원하면 같은 주소로 붙는다

그림 2. 에이전트 - 중계 서버 - 내 기기로 이어지는 구조와 도구 이름.

브라우저 넷은 전부 크롬 웹스토어에서 확장을 받는다. 크로미움 기반이라 다른 브라우저에도 설치될 수 있지만, 시험은 이 넷에서만 했다고 명시돼 있다.

설치 1~2단계 — 확장 설치와 브라우저 연결

1단계. 확장 설치. 에이전트가 쓸 브라우저 프로필마다 다운로드 페이지에서 "Chrome에 추가"를 누른다. 프로필이 여러 개면 프로필마다 따로 설치해야 한다. 설치가 끝나면 연결 화면이 저절로 열린다.

2단계. 브라우저 연결. 연결 방법은 세 가지다.

방법특징
구글 로그인가장 빠르다. 인증 창에서 Handlus 계정을 고른다
가입 이메일 인증확장 0.3.1부터. 그 프로필이 다른 구글 계정이어도 된다
연결 키구글 로그인 없이 붙일 때. 반드시 내 대시보드에서 만든 키만 넣는다

연결하면서 브라우저 이름을 정한다. 에이전트는 이 이름으로 브라우저를 고른다. "작업용", "쇼핑몰 A"처럼 계정이 갈리는 단위로 지어두면 나중에 헷갈리지 않는다.

한 번 연결한 브라우저는 다시 로그인할 일이 없다. 확장 업데이트도 웹스토어판이면 브라우저가 알아서 한다.

클로드코드에 붙이기 — claude mcp add 한 줄

여기서부터는 터미널이다. 나는 Claude Code 2.1.314에서 확인했다. 명령은 한 줄이다.

claude mcp add --transport http handlus https://api.handlus.com/mcp

실행하면 이런 줄이 나온다.

Added HTTP MCP server handlus with URL: https://api.handlus.com/mcp to local config
File modified: ~/.claude.json [project: /현재폴더]

바로 상태를 본다.

claude mcp list
handlus: https://api.handlus.com/mcp (HTTP) - ! Needs authentication

Needs authentication은 실패가 아니다. 아직 로그인을 안 했다는 뜻이다. 클로드코드를 실행하고 /mcp를 치면 서버 목록이 뜨고, handlus를 고른 뒤 Authenticate를 누르면 브라우저가 열린다. 거기서 Handlus 계정으로 로그인하면 상태가 ✔ Connected로 바뀐다.

/mcp 메뉴 위치나 상태 글리프가 낯설면 Claude MCP 설정 방법에 표로 정리해뒀다. 클로드코드 자체가 처음이면 Claude Code 설치·사용법부터 보면 된다.

한 가지 미리 알아둘 점. claude mcp add의 기본 스코프는 local이라 지금 프로젝트에서만 보인다. 어느 폴더에서든 쓰려면 --scope user를 붙여서 넣는다. 스코프는 나중에 못 바꾸니, 처음 넣을 때 정하는 게 좋다.

claude mcp add --scope user --transport http handlus https://api.handlus.com/mcp

그림 3. Claude Code 2.1.314에서 실제로 실행한 등록·확인·상태 조회 결과.

실제로 시켜보기 — 브라우저 도구 이름과 예시

붙이고 나면 에이전트가 쓸 수 있는 도구가 생긴다. 소개 페이지에 공개된 이름만 추려보면 이렇다.

도구하는 일
chrome_list_browsers연결된 브라우저 목록과 상태
chrome_navigate지정한 브라우저에서 주소 열기
chrome_get_web_content페이지 글·주소·표 읽기
chrome_handle_dialog경고창·확인창 처리
chrome_upload_file / chrome_handle_download파일 올리기·내려받기
chrome_request_user_consent사람 확인이 필요한 지점에서 멈추고 묻기
desktop_list / desktop_app / desktop_act연결된 컴퓨터 목록, 프로그램 열기, 클릭·입력
flow.<이름>사이드패널에서 녹화해 둔 작업을 이름으로 호출

도구 이름을 외울 필요는 없다. 다만 처음엔 브라우저 이름을 대주는 편이 확실하다. "작업용 브라우저에서 이 페이지 열고 표만 뽑아줘"처럼 시작하면, 에이전트가 chrome_list_browsers로 이름을 확인하고 그 브라우저로 간다.

브라우저를 두 개 이상 켜 두면 짐작하지 않고 어느 쪽인지 묻는다. 한 번 이름을 대면 그 대화에서는 계속 같은 브라우저를 쓴다. 이 동작은 자동화할 때 꽤 중요하다. 계정이 섞이면 로그인 상태가 달라서 결과도 달라지기 때문이다.

컴퓨터까지 조작하려면 (선택)

브라우저 밖 프로그램까지 시키려면 Handlus 앱을 깐다. 맥은 dmg를 Applications에 넣고, 윈도우는 설치 파일을 실행한다. 앱을 열고 계정으로 로그인하면 그 컴퓨터가 연결된다.

맥에서는 처음에 손쉬운 사용 권한을 물어본다. 이걸 허용해야 에이전트가 계산기·엑셀·메모장 같은 앱을 열고 누르고 입력할 수 있다. 반대로 비밀번호 관리자와 시스템 설정 앱은 건드리지 않고, 입력한 값도 기록하지 않는다고 안내돼 있다. 메뉴 막대에서 언제든 끌 수 있다.

무료 플랜에서 컴퓨터 조작은 주 1,500회 중 300회까지다. 브라우저만 쓸 거라면 앱은 설치하지 않아도 된다.

요금과 한도 — 무료로 어디까지

가격은 달러 기준이고 부가세 별도다. 한국은 결제할 때 10%가 붙는다(요금 페이지).

플랜가격에이전트기기(브라우저+컴퓨터)도구 호출
Free$02개2대주 1,500회(컴퓨터 300회)
Pro월 $20 (한국 $22)제한 없음5대제한 없음
Enterprise월 $49 (한국 $53.90)제한 없음제한 없음제한 없음

연간 결제는 월 요금에서 20% 할인이다. Pro 연 $211.20, Enterprise 연 $514.80(부가세 포함 기준). Pro는 월간 결제만 첫 7일 무료 체험이 붙고, 결제 후 7일 안에는 전액 환불된다.

무료 한도가 감이 안 올 수 있는데, 공식 설명으로는 작업 하나에 보통 15회 안팎이 든다. 주 1,500회면 한 주에 100개쯤, 쉬지 않고 돌리면 7시간 반쯤이다. 페이지 열기·읽기·클릭이 각각 1회이고, 실패한 호출과 브라우저 목록 보기는 세지 않는다. 한도는 매주 월요일 오전 9시(한국 시간)에 다시 찬다.

결제는 Polar가 맡고 카드 정보는 Handlus 서버를 지나지 않는다. 운영 주체는 이화 STRING(대표 MISEON PYO)으로 개인정보처리방침에 적혀 있다.

보안과 주의할 점

이 서비스의 본질은 내가 로그인해 둔 브라우저를 에이전트에게 넘기는 것이다. 편한 만큼 권한도 크다. 공식 방침에서 확인한 내용은 이렇다(개인정보처리방침).

항목내용
페이지 내용·스크린샷·입력값중계 서버를 지나가기만 하고 저장하지 않는다
도구 호출의 인자와 결과기록하지 않는다
접속 기록·호출 기록30일 안에 지운다
빠르게 자동화하기 대화암호화해 마지막 메시지 뒤 7일 보관
토큰원문이 아니라 해시로 저장
연결 키AES-256으로 암호화, 여는 열쇠는 DB와 분리

다만 "저장하지 않는다"와 "내 브라우저를 조작할 수 있다"는 다른 문제다. 에이전트가 내 계정으로 결제 버튼을 누를 수도 있고, 읽은 페이지 내용이 대화 컨텍스트에 들어가 모델 쪽으로 넘어갈 수도 있다. 그래서 나는 이렇게 운용한다.

  • 결제·비밀번호·계좌 화면은 에이전트에게 맡기지 않고 손으로 한다.
  • 로그인해 둔 브라우저 중 꼭 필요한 것만 연결하고, 나머지는 대시보드에서 해제한다.
  • 에이전트가 읽은 페이지에 이상한 지시문이 섞여 있을 수 있으니, 외부 페이지를 읽힌 뒤에는 실행 계획을 한 번 읽어본다. 프롬프트 인젝션은 도구를 붙일수록 커지는 위험이다.
  • 여러 브라우저가 켜져 있으면 이름을 대고 시킨다. 계정이 섞이는 사고를 막는 가장 싼 방법이다.

Handlus 자체가 프롬프트 인젝션을 걸러준다고 기대하면 안 된다. 중계 서버는 길만 이어 주는 역할이라고 소개 페이지가 먼저 말하고 있다.

내가 막혔던 곳

첫 번째는 주소를 찾는 일이었다. 소개 페이지는 "문장 하나를 에이전트에 붙여 넣으면 나머지는 에이전트가 안내합니다"라고만 적혀 있고, claude mcp add 예시는 없다. 그래서 후보 주소를 직접 찔러봤다. https://api.handlus.com/mcp에 요청을 보내니 401과 함께 이런 문장이 돌아왔다.

{"jsonrpc":"2.0","error":{"code":-32001,"message":"Handlus 로그인이 필요합니다. 클로드코드에서 /mcp → handlus(등록한 이름) → Authenticate 를 고르면 브라우저에서 로그인합니다."},"id":null}

주소가 맞다는 것과 다음에 뭘 해야 하는지가 한 번에 나왔다. 문서에 명령 한 줄만 있었으면 삽질을 아꼈을 텐데, 아무튼 이 에러 문장이 제일 친절한 안내서였다.

두 번째는 Needs authentication을 보고 실패한 줄 알았던 것. claude mcp list에 느낌표가 붙어 있으니 서버가 죽은 것 같았는데, 그냥 로그인 전이라는 뜻이었다. /mcp에서 Authenticate를 누르면 풀린다. claude mcp get handlus로 보면 Scope·Type·URL까지 같이 나오니, 상태가 애매할 때 이 명령부터 치면 된다.

세 번째는 스코프다. /tmp에 테스트 폴더를 만들고 거기서 등록했더니 그 폴더에서만 보였다. 기본값이 local이라 그렇다. 실제로 쓸 때는 --scope user로 넣고, 테스트로 넣은 서버는 claude mcp remove handlus로 지웠다.

정리하면, 이 글에서 내가 직접 확인한 건 서버 등록과 상태 확인까지다. 브라우저 조작은 확장을 내 계정에 연결해야 해서 그 지점에서 멈췄고, 나머지 동작과 요금·보안 수치는 공식 페이지 기준으로 적었다. 에이전트가 도구를 고르는 원리는 AI 에이전트란에 정리해뒀다.

참고 자료

반응형
반응형
Claude MCP 설정 방법 — claude mcp add로 서버 붙이고 /mcp로 확인하기

MCP 서버를 붙이면 클로드가 내 파일·DB·이슈 트래커를 직접 읽는다. 그런데 막상 설정하려고 하면 claude_desktop_config.json이니 .mcp.json이니 하는 파일 이름이 먼저 튀어나와서 어디에 뭘 넣어야 할지 헷갈린다. 이 글은 Claude Code 기준으로 MCP 서버를 붙이는 명령 세 줄과, 연결이 안 될 때 어디를 보면 되는지를 정리한 것이다.

30초 요약

항목내용
한 줄 정의MCP는 AI 앱과 외부 도구를 잇는 공개 표준이다. 공식 문서는 "AI 애플리케이션용 USB-C 포트"라고 부른다
붙이는 명령claude mcp add --transport http <이름> <URL> 또는 claude mcp add <이름> -- <실행명령>
확인터미널에서 claude mcp list, 세션 안에서는 /mcp
저장 위치local·user는 ~/.claude.json, project는 프로젝트 루트의 .mcp.json
가장 흔한 실수JSON에 url만 쓰고 type을 빼먹는 것. 그러면 Claude Code가 stdio 서버로 읽고 건너뛴다
비용서버를 붙일수록 툴 이름이 매 세션 컨텍스트에 올라간다. 안 쓰는 서버는 지우는 편이 낫다

그림 1. MCP 설정은 설정 파일 편집이 아니라 명령 세 줄로 끝난다.

목차

  1. Claude MCP란 — 서버·툴·전송 방식 3가지만
  2. 설정 전에 확인할 것 — 스코프와 저장 위치
  3. Claude MCP 설정 방법 — claude mcp add 3단계
  4. .mcp.json 직접 쓰기 — 자주 틀리는 필드
  5. Claude Desktop 설정 가져오기
  6. 연결이 안 될 때 — 증상별 해결
  7. 내가 막혔던 곳

Claude MCP란 — 서버·툴·전송 방식 3가지만

MCP(Model Context Protocol)는 앱이 외부 시스템에 붙는 방식을 하나로 맞춘 규격이다. 공식 소개 문서는 이걸 "AI 애플리케이션을 위한 USB-C 포트"에 비유한다. 기기마다 다른 케이블을 들고 다니지 않듯, MCP를 쓰면 클라이언트 쪽 코드를 안 고치고 서버만 갈아 끼울 수 있다(MCP 소개).

붙이는 쪽(Claude Code, Claude Desktop, VS Code, Cursor)을 클라이언트라고 하고, 도구를 내어주는 쪽을 서버라고 부른다. 서버가 노출하는 기능은 세 갈래다. 실행되는 동작은 툴, 읽기 전용 데이터는 리소스, 재사용하는 지시문은 프롬프트다. 우리가 체감하는 건 거의 툴이다. 클로드가 mcp__서버이름__툴이름 형태로 호출하는 게 그것이다.

전송 방식은 표로 외우는 게 빠르다.

전송쓰는 경우명령
http원격 서버. 공식 문서가 권장하는 기본값claude mcp add --transport http 이름 URL
stdio내 PC에서 프로세스로 뜨는 서버claude mcp add 이름 -- npx -y 패키지
sse예전 방식. 지금은 deprecatedclaude mcp add --transport sse 이름 URL

SSE는 공식 문서에 폐기(deprecated)로 표시돼 있다. 다만 SSE 엔드포인트만 제공하는 서비스가 있어서, Claude Code v2.1.265 이상은 --transport http로 넣어도 서버가 HTTP를 거부하면 SSE로 자동 전환한다. 그 아래 버전이면 --transport sse를 직접 지정해야 한다(Claude Code MCP 레퍼런스).

설정 전에 확인할 것 — 스코프와 저장 위치

claude mcp add는 기본값이 local 스코프다. 이게 첫 번째 함정이다. local은 "내 계정 + 이 프로젝트"에만 걸리므로, 다른 폴더에서 클로드를 켜면 서버가 안 보인다. 평생 쓸 서버라면 --scope user를 붙여야 한다.

스코프파일적용 범위
local (기본)~/.claude.json 안의 해당 프로젝트 항목나만, 이 프로젝트에서만
project프로젝트 루트의 .mcp.json저장소를 클론한 모두에게
user~/.claude.json의 최상위 mcpServers나만, 모든 프로젝트

표의 파일 경로는 공식 문서의 "Find your configuration on disk" 절에서 그대로 가져왔다. 여기서 중요한 건 읽지 않는 경로다. ~/.claude/.mcp.json, ~/.claude/mcp.json, %APPDATA%\Claude\mcp.json 같은 파일을 아무리 잘 써도 Claude Code는 쳐다보지 않는다. 직접 편집할 거면 ~/.claude.json이나 <프로젝트>/.mcp.json 두 개만 기억하면 된다(MCP 퀵스타트).

스코프는 나중에 바꿀 수 없다. 바꾸려면 지우고 다시 넣는다.

claude mcp remove my-server
claude mcp add --scope user --transport http my-server https://mcp.example.com/mcp

Claude MCP 설정 방법 — claude mcp add 3단계

먼저 Claude Code가 설치돼 있고 로그인이 끝난 상태여야 한다. 설치에서 막혔다면 Claude Code 설치·사용법을 먼저 보면 된다. 아래 명령은 claude 세션 안이 아니라 터미널에서 실행한다.

1단계. 서버 등록

예시로 Claude Code 공식 문서 검색 서버를 붙여본다. 인증이 없어서 연습용으로 좋다.

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

성공하면 Added HTTP MCP server claude-code-docs with URL: ... to local config와 함께 어떤 파일을 고쳤는지 File modified: 줄이 나온다. 만약 서버 문서에 npx -y @something/mcp-server 같은 실행 명령만 있다면 stdio로 넣는다. 이때 --가 Claude Code 옵션과 서버 명령을 가르는 구분자다.

claude mcp add --env MY_API_KEY=발급받은키 --transport stdio my-server \
  -- npx -y some-mcp-server

2단계. 상태 확인

claude mcp list

여기서 봐야 할 건 상태 글리프다. 표로 정리하면 이렇다.

표시뜻다음에 할 일
✔ Connected정상그대로 쓴다
! Connected · tools fetch failed붙었는데 툴 목록을 못 가져옴claude mcp get <이름>으로 상세 확인
! Needs authentication인증이 필요/mcp에서 브라우저 로그인
✘ Failed to connect서버가 응답 안 함명령·URL·토큰 확인
⏸ Pending approval프로젝트 스코프인데 승인 전claude 실행해 승인

3단계. 세션에서 호출

claude

세션에 들어간 뒤 /mcp를 치면 서버 목록과 재연결·인증 메뉴가 뜬다. 클로드가 알아서 툴을 고르지만, 처음엔 서버 이름을 대주는 편이 확실하다. "claude-code-docs 서버로 MCP_TIMEOUT 설명 찾아줘"처럼 물으면 응답에 서버 이름이 라벨로 붙는다. 그 라벨이 보이면 진짜 MCP를 거쳐 온 답이다.

타임아웃이 필요하면 환경변수로 준다. MCP_TIMEOUT=10000 claude는 서버 기동 대기시간을 10초로 잡는다는 뜻이다. 툴 실행 시간은 서버별로 따로 준다. .mcp.json 항목에 "timeout": 600000을 넣으면 그 서버만 10분까지 기다린다.

.mcp.json 직접 쓰기 — 자주 틀리는 필드

팀원과 설정을 공유하려면 .mcp.json을 저장소에 커밋하는 게 편하다. 형식은 단순하다.

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "airtable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": { "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}" }
    }
  }
}

여기서 사람들이 가장 많이 걸리는 게 type 누락이다. 공식 문서는 이렇게 적혀 있다. url은 있는데 type이 없는 항목은 설정 오류로 처리되고, Claude Code가 그 항목을 stdio 서버로 읽어서 건너뛴 뒤 MCP server "<이름>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws")라는 경고를 낸다. 한 줄만 넣으면 끝나는 문제인데, 경고를 안 읽으면 "서버가 안 뜬다"로 끝난다.

type에는 streamable-http도 쓸 수 있다. MCP 스펙이 쓰는 이름이 그쪽이라, 서버 문서의 JSON을 그대로 복사해도 동작한다.

프로젝트 스코프로 넣은 서버는 처음엔 ⏸ Pending approval 상태다. 저장소를 클론한 사람이 임의로 실행되지 않게 막아둔 장치다. claude를 한 번 실행해 승인하면 풀린다.

Claude Desktop 설정 가져오기

Claude Desktop 앱에는 이미 claude_desktop_config.json으로 서버를 넣어둔 사람이 많다. 그걸 Claude Code에 손으로 옮길 필요는 없다. macOS나 WSL에서는 가져오기 명령이 있다.

claude mcp add-from-claude-desktop

실행하면 어떤 서버를 가져올지 고르는 대화형 선택창이 뜨고, 끝나면 claude mcp list로 확인하면 된다. 주의할 점이 하나 있다. claude mcp 명령으로 추가하는 서버 이름은 영문·숫자·하이픈·언더스코어만 허용된다. Claude Desktop은 이 제한이 없어서 이름에 공백이 들어간 서버는 가져오기가 거부된다. 거부된 이름은 따로 알려주고 나머지는 정상적으로 가져온다.

Claude Code 데스크톱 앱은 경로가 또 다르다. 이쪽은 파일 편집이 아니라 Connectors UI에서 추가한다. 앱마다 설정 창구가 다르다는 걸 먼저 알고 있으면 헛수고를 줄일 수 있다.

연결이 안 될 때 — 증상별 해결

/mcp에 "No MCP servers configured"만 뜨는 경우가 제일 많다. 원인은 거의 셋 중 하나다.

첫째, 다른 프로젝트에서 claude mcp add를 했다. local 스코프는 git 저장소 루트(저장소가 아니면 그 디렉터리)에 묶인다. 지금 켜둔 폴더에서 다시 넣거나, --scope user로 새로 넣는다.

둘째, 파일 경로를 잘못 골랐다. 앞에서 적은 대로 Claude Code가 읽는 파일은 ~/.claude.json과 <프로젝트>/.mcp.json 둘뿐이다.

셋째, .mcp.json 문법이 깨졌다. 이때는 전체가 죽지 않고 깨진 항목만 건너뛴다. 그래서 "일부만 안 보인다" 싶으면 claude mcp list의 파싱 경고부터 확인한다. 어느 필드가 문제인지 이름을 찍어준다.

Failed to connect와 Connection error는 둘 다 서버가 안 떴거나 URL이 응답하지 않는다는 뜻이다. v2.1.219 이후 버전은 claude mcp list와 claude mcp get <이름>에 HTTP 상태나 에러 코드가 같이 나오니 그것부터 읽는다. Connection error는 버전과 무관하게 상세를 안 붙여주므로, 같은 엔드포인트를 curl로 직접 때려보는 게 빠르다. HTTP 서버가 404를 돌려주면 /mcp에서 MCP endpoint not found at <origin>가 뜬다. 경로가 빠졌다는 신호다.

토큰을 붙여넣다가 앞뒤 공백이 섞이는 사고도 흔하다. Claude Code는 설정값에 숨은 공백이 있으면 경고를 따로 띄운다.

내가 막혔던 곳

처음에 나는 .mcp.json을 ~/.claude/ 밑에 만들어두고 왜 안 잡히는지 한참 헤맸다. 문서를 다시 읽어보니 읽지 않는 경로 목록에 내가 만든 위치가 그대로 적혀 있었다. 파일을 예쁘게 쓰는 것보다 어느 파일을 읽는지가 먼저라는 걸 그때 배웠다.

두 번째는 type 누락이다. 서버 문서에서 url 한 줄만 복사해 넣었더니 Claude Code가 그 항목을 조용히 건너뛰었다. 지금은 새 서버를 넣을 때 claude mcp list를 먼저 치고, 경고 문장이 한 줄이라도 나오면 그 자리에서 고친다.

세 번째는 서버를 너무 많이 붙인 것이다. 서버마다 툴 이름과 설명이 매 세션 컨텍스트에 올라가서, 안 쓰는 서버를 정리하니 같은 질문에 대한 답이 눈에 띄게 안정됐다. MCP는 많이 붙이는 것보다 지금 하는 작업에 필요한 것만 붙이는 쪽이 낫다. 에이전트가 어떤 식으로 도구를 고르는지는 AI 에이전트란에, 서버를 코드로 직접 호출하는 쪽은 Claude API 사용법에 정리해뒀다.

그림 2. 등록·확인·호출 세 단계와 스코프별 저장 위치.

참고 자료

반응형
반응형
npm 설치 오류 해결 — command not found·EACCES 증상별 원인

Node.js를 설치했는데 터미널이 npm: command not found라고 하거나, npm install -g에서 EACCES 권한 오류가 터지는 경우가 많습니다. 설치 자체가 실패한 게 아니라 PATH나 권한, 버전 중 하나가 어긋난 경우가 대부분입니다. 이 글은 증상별로 원인을 좁히고 바로 칠 수 있는 명령을 정리했습니다.

30초 요약

증상원인해결
npm: command not foundNode를 설치했지만 PATH에 없음which -a node로 위치 확인 후 셸 설정에 PATH 추가
EACCES: permission denied전역 설치 경로가 root 소유npm config set prefix ~/.local 후 PATH 추가
npm ERR! code ENOENTpackage.json이 없는 디렉터리에서 실행프로젝트 루트로 이동하거나 npm init -y
EBADENGINE / engine 오류프로젝트가 요구하는 Node 버전과 불일치nvm으로 버전 전환
bad CPU type in executableApple Silicon에 Intel 바이너리 설치arm64 빌드 재설치 또는 Rosetta 확인

그림 1. npm 오류 다섯 가지 증상과 원인 네 갈래.

기준 버전은 Node.js v26.13.1(Lithium, LTS), v24.22.3(Krypton, LTS), v22.23.5(Jod, LTS)입니다. v27은 아직 Alpha 단계라 실무에서는 쓰지 않습니다(Node.js 릴리스 목록).

목차

  • 먼저 확인할 것 — node·npm 버전과 PATH
  • npm: command not found — PATH가 안 잡힌 경우
  • EACCES 권한 오류 — sudo 대신 prefix를 바꾼다
  • npm ERR! code ENOENT — package.json 위치 문제
  • EBADENGINE — Node 버전이 맞지 않을 때
  • bad CPU type — Apple Silicon과 Intel 바이너리
  • 내가 막혔던 곳 — Homebrew node와 nvm이 싸운 이유

먼저 확인할 것 — node·npm 버전과 PATH

오류 문구를 보고 바로 명령을 치기 전에, 지금 어떤 바이너리가 잡혀 있는지부터 봅니다. 이 세 줄이면 원인의 절반이 갈립니다.

node -v
npm -v
which -a node npm

which -a는 PATH에 있는 모든 후보를 보여줍니다. 여기서 /usr/local/bin/node와 /opt/homebrew/bin/node가 동시에 나오면 두 개가 설치된 상태이고, 어느 쪽이 먼저 잡히는지에 따라 버전이 달라집니다. npm은 Node.js 설치 패키지에 함께 들어오므로, node -v는 되는데 npm -v가 안 되면 npm만 빠진 게 아니라 PATH 우선순위가 꼬인 경우가 많습니다.

제 맥에서는 node -v가 v24.18.0, npm -v가 11.16.0으로 나옵니다. 두 명령의 실행 경로가 같은 디렉터리인지도 같이 확인하세요.

npm: command not found — PATH가 안 잡힌 경우

설치는 됐는데 셸이 못 찾는 상태입니다. Node를 공식 인스톨러로 설치하면 /usr/local/bin에 들어가고, Homebrew로 설치하면 Apple Silicon 기준 /opt/homebrew/bin에 들어갑니다. 새 터미널을 열었을 때 이 경로가 PATH에 없으면 command not found가 뜹니다.

echo $PATH | tr ':' '\n' | grep -E 'homebrew|local/bin'
ls -l /opt/homebrew/bin/node /usr/local/bin/node 2>/dev/null

경로가 PATH에 없다면 셸 설정 파일에 한 줄을 추가합니다. zsh 기준입니다.

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Intel 맥이거나 공식 인스톨러를 쓴 경우에는 /usr/local/bin을 넣습니다. 설치는 했는데 파일 자체가 없으면 설치가 중간에 실패한 것이므로 재설치가 맞습니다. 맥 개발환경을 처음 세팅하는 중이라면 Homebrew·iTerm·zsh 순서를 먼저 잡아두는 편이 이후가 편합니다. 정리해 둔 글이 Mac 개발환경 세팅입니다.

EACCES 권한 오류 — sudo 대신 prefix를 바꾼다

npm install -g에서 가장 자주 보는 오류입니다. 전역 설치 디렉터리가 root 소유라 일반 계정으로 쓸 수 없을 때 발생합니다.

npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules
npm error errno -13

npm 공식 문서는 두 가지 해결책을 제시합니다. Node 버전 관리자로 npm을 다시 설치하는 방법(권장)과, 기본 디렉터리를 사용자 홈으로 옮기는 방법입니다(npm docs). 급하면 후자로 바로 해결됩니다.

npm config get prefix
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g npm-check-updates

여기서 sudo npm install -g를 쓰는 사람이 많은데, 권장하지 않습니다. root 소유 파일이 쌓이면 다음 업데이트에서 같은 오류가 더 크게 돌아옵니다. 이미 sudo로 설치해 꼬였다면 해당 디렉터리 소유권을 사용자로 되돌린 뒤 prefix를 옮기세요.

파이썬에서 같은 종류의 권한 문제를 겪었다면 pip install 오류 해결의 흐름이 그대로 통합니다. 패키지 관리자마다 증상은 같고 경로만 다릅니다.

npm ERR! code ENOENT — package.json 위치 문제

npm error code ENOENT
npm error path /Users/me/package.json
npm error enoent Could not read package.json

이 오류는 npm이 package.json을 못 찾았다는 뜻입니다. 대부분 프로젝트 폴더가 아니라 상위 디렉터리에서 명령을 친 경우입니다.

pwd
ls package.json
npm init -y

npm init -y는 기본값으로 package.json을 만들어 줍니다. 이미 프로젝트가 있는데 파일이 없다면 저장소를 잘못 받은 것이므로 git status로 현재 위치를 확인하는 게 빠릅니다. node_modules만 있고 package.json이 없는 상태는 복구가 어렵기 때문에, 그럴 때는 npm install을 다시 돌리기 전에 어떤 패키지가 필요했는지부터 정리합니다.

EBADENGINE — Node 버전이 맞지 않을 때

패키지의 engines 필드가 요구하는 Node 버전과 현재 버전이 다를 때 나옵니다. 기본 동작은 경고이고, engine-strict=true가 켜져 있으면 설치가 중단됩니다.

npm config get engine-strict
node -v
npm view <패키지명> engines

버전을 맞추는 가장 깔끔한 방법은 nvm입니다. 공식 저장소의 설치 스크립트를 쓰면 셸 설정에 로드 구문이 함께 들어갑니다(nvm 저장소).

nvm install --lts
nvm use --lts
nvm alias default 'lts/*'
node -v

프로젝트마다 버전이 다르면 루트에 .nvmrc를 두고 nvm use만 치는 방식이 편합니다. LTS 기준을 확인하려면 Node.js 다운로드 페이지의 표를 보면 됩니다.

bad CPU type — Apple Silicon과 Intel 바이너리

M 시리즈 맥에서 zsh: bad CPU type in executable: node가 뜨는 경우입니다. Intel(x64) 바이너리를 arm64 셸에서 실행했거나, Rosetta 없이 x64 전용 바이너리를 부른 상황입니다.

uname -m
node -p "process.arch"
file $(which node)

uname -m이 arm64인데 process.arch가 x64로 나오면 arch가 어긋난 것입니다. arm64용 Node를 다시 설치하거나, x64 바이너리를 계속 써야 한다면 Rosetta를 설치합니다.

softwareupdate --install-rosetta --agree-to-license

Homebrew를 Rosetta로 설치한 경우 /usr/local에, 네이티브로 설치한 경우 /opt/homebrew에 바이너리가 들어갑니다. 두 개가 섞여 있으면 앞의 PATH 문제와 겹쳐서 버전이 계속 바뀌는 것처럼 보입니다.

내가 막혔던 곳 — Homebrew node와 nvm이 싸운 이유

처음엔 brew install node로 설치하고 나중에 nvm을 추가했더니, 터미널을 열 때마다 node -v가 달라졌습니다. 원인은 .zshrc에서 nvm 로드 구문보다 Homebrew PATH 추가가 뒤에 있었던 것입니다. 나중에 추가된 경로가 앞에 붙으면서 Homebrew 쪽 node가 이겼습니다.

해결은 순서를 정하는 것이었습니다. nvm을 쓸 거면 Homebrew node를 지우고, .zshrc에서 nvm 로드 구문을 PATH 설정보다 아래에 두었습니다. 확인은 항상 같은 방식으로 합니다.

which -a node
echo $PATH | tr ':' '\n' | head -5

또 하나 걸렸던 지점은 Claude Code를 npm으로 전역 설치할 때였습니다. Node 버전이 낮으면 설치가 중간에 멈추는데 오류 메시지가 권한처럼 보여서 한참 헤맸습니다. 지금은 Node LTS를 먼저 맞추고 설치하는 순서로 바꿨습니다. 설치 절차는 Claude Code 설치·사용법에 정리해 두었습니다.

정리하면, npm 오류는 설치 실패로 보이지만 실제로는 PATH·권한·버전·arch 네 가지 중 하나입니다. 순서대로 확인하면 대부분 10분 안에 끝납니다.

그림 2. 위에서부터 확인하는 다섯 단계와 피해야 할 습관.

참고 자료

반응형
반응형
gws CLI 구조 — 구글 워크스페이스 명령어를 런타임에 만드는 방식

gws는 드라이브·지메일·캘린더·시트 같은 구글 워크스페이스를 터미널에서 다루는 CLI다. 다른 CLI와 다른 점은 명령어 목록이 바이너리 안에 들어 있지 않다는 것이다. 실행하는 순간 구글의 Discovery 문서를 읽어서 명령 트리를 새로 만든다. 이 글은 그 구조를 실제로 설치해서 확인한 순서대로 정리한다.

30초 요약

궁금한 것답
무엇인가구글 워크스페이스 18개 서비스를 한 바이너리로 다루는 CLI (README)
핵심 구조명령어를 하드코딩하지 않고 실행할 때 Discovery 문서를 받아 명령 트리를 만든다(2단계 파싱)
실측값Drive v3 Discovery 기준 리소스 14개·메서드 64개, 캐시 파일 263KB(~/.config/gws/cache/drive_v3.json)
명령 두 종류Discovery가 만든 명령 + 손으로 만든 + 헬퍼(+send, +agenda, +standup-report)
인증 순서토큰 env → 자격증명 파일 env → gws auth login(AES-256-GCM + OS 키체인) → 평문 파일
출력전부 JSON. --format table/yaml/csv, --page-all은 페이지마다 한 줄(NDJSON)
종료 코드0 성공 · 1 API 오류 · 2 인증 오류 · 3 검증 오류 · 4 Discovery 오류 · 5 내부 오류
내가 받은 버전v0.22.5 (2026-03-31 공개) — gws 0.22.5
주의저장소에 "not an officially supported Google product"라고 적혀 있다. 구글 공식 지원 제품이 아니다

그림 1. gws의 구조. 실행 시 Discovery 문서를 받아 명령 트리를 만들고, 인증을 거쳐 HTTP 요청으로 나간다.

목차

  1. gws CLI란 — 설치부터 첫 실행까지
  2. 핵심 구조 — Discovery 문서로 명령 트리를 만든다
  3. 실제 명령 계층 — drive 하나에 리소스 14개, 메서드 64개
  4. 두 종류의 명령 — Discovery 메서드와 + 헬퍼
  5. 인증 구조 — 우선순위 4단계와 키체인 암호화
  6. 출력과 종료 코드 — 스크립트가 분기할 수 있게
  7. 에이전트 스킬 레이어 — SKILL.md 100개
  8. 내가 막혔던 곳
  9. 참고 자료

gws CLI란 — 설치부터 첫 실행까지

한 줄로 말하면 "구글 워크스페이스 REST API를 사람이 쓰기 좋은 명령어로 감싼 래퍼"다. 서비스마다 따로 만들어진 CLI가 아니라, 바이너리 하나가 18개 서비스를 전부 담당한다. Rust로 작성돼 있어서 cargo install과 Nix로도 설치할 수 있고, 정적 바이너리라 런타임 의존성이 없다 (README).

설치 경로는 세 가지다.

# 1) 릴리스 바이너리 (권장)
curl -LO https://github.com/googleworkspace/cli/releases/download/v0.22.5/google-workspace-cli-x86_64-apple-darwin.tar.gz
tar xzf google-workspace-cli-x86_64-apple-darwin.tar.gz   # gws 바이너리 하나가 나온다

# 2) Homebrew (macOS·Linux)
brew install googleworkspace-cli

# 3) npm — 릴리스 바이너리를 내려받아 주는 래퍼
npm install -g @googleworkspace/cli

설치 후 첫 화면은 이렇게 나온다. 확인 겸 면책 문구까지 같이 찍힌다.

$ ./gws --version
gws 0.22.5
This is not an officially supported Google product.

인증은 두 단계다. gws auth setup은 gcloud로 클라우드 프로젝트 생성·API 활성화·로그인까지 한 번에 처리하고, 그다음부터는 gws auth login만 쓰면 된다. gcloud가 없으면 클라우드 콘솔에서 OAuth 클라이언트(Desktop app)를 만들어 ~/.config/gws/client_secret.json에 두는 수동 경로가 있다.

gws auth setup     # 최초 1회: 프로젝트 + API + 로그인
gws auth login     # 이후: 스코프 선택과 로그인
gws drive files list --params '{"pageSize": 5}'

첫 실행 뒤 설정 디렉터리가 이렇게 생긴다. 구조를 이해할 때 제일 먼저 봐야 하는 곳이다.

~/.config/gws/
├── cache/drive_v3.json      # Discovery 문서 캐시 (24시간 유효)
├── client_secret.json       # OAuth 클라이언트 (수동 설정 시)
├── credentials.json         # 암호화된 자격증명
└── .encryption_key          # KEYRING_BACKEND=file일 때만

핵심 구조 — Discovery 문서로 명령 트리를 만든다

gws의 가장 큰 특징은 명령어 정의가 코드에 없다는 점이다. 저장소 설명에도 "Dynamically built from Google Discovery Service"라고 적혀 있다. 구글이 새 API 메서드를 추가하면 CLI를 업데이트하지 않아도 다음 실행에서 자동으로 그 명령이 생긴다 (Discovery Service).

실행 흐름은 2단계 파싱이다.

  1. argv[1]만 먼저 읽어 서비스 이름을 알아낸다 (drive, gmail 같은 값).
  2. 그 서비스의 Discovery 문서를 받아온다. 캐시가 있으면 24시간 동안 재사용한다.
  3. 문서의 리소스·메서드 정의로 clap 명령 트리를 만든다.
  4. 남은 인자를 그 트리로 다시 파싱한다.
  5. 인증 → HTTP 요청 조립 → 실행 → JSON 출력.

내 환경에서 실제로 확인한 값은 이렇다. 캐시 파일은 263KB였고, 문서 리비전은 20261109였다.

$ ls -lh ~/.config/gws/cache/
-rw-------  263K  drive_v3.json

$ gws schema drive.files.list | head -3
{
  "description": " Lists the user's files. ...",
  "httpMethod": "GET",

여기서 gws schema <service.resource.method>가 중요하다. Discovery 문서를 그대로 보여주는 명령이라, 어떤 파라미터가 필수인지, 응답이 어떤 모양인지 CLI 안에서 바로 확인할 수 있다. 문서 사이트를 따로 열 필요가 없다. --resolve-refs를 붙이면 $ref 참조까지 펼쳐서 보여준다.

2단계 파싱의 대가도 있다. 서비스 이름을 틀리면 3번(검증 오류)으로 끝나고, Discovery 문서를 못 받으면 4번(Discovery 오류)으로 끝난다. 둘 다 "명령이 틀렸다"가 아니라 "명령 트리를 못 만들었다"는 뜻이라 원인을 구분해서 봐야 한다.

실제 명령 계층 — drive 하나에 리소스 14개, 메서드 64개

gws drive --help를 치면 Discovery 문서의 리소스가 그대로 하위 명령으로 나열된다.

$ gws drive --help
The Google Drive API allows clients to access resources from Google Drive.

Commands:
  +upload          [Helper] Upload a file with automatic metadata
  about            Operations on the 'about' resource
  accessproposals  Operations on the 'accessproposals' resource
  apps             Operations on the 'apps' resource
  changes          Operations on the 'changes' resource
  channels         Operations on the 'channels' resource
  comments         Operations on the 'comments' resource
  drives           Operations on the 'drives' resource
  files            Operations on the 'files' resource
  permissions      Operations on the 'permissions' resource
  ...

그림 3. 실제 실행 출력. 리소스 목록이 곧 Discovery 문서의 리소스 목록이다.

명령은 gws <service> <resource> [sub-resource] <method> 순서로 내려간다. REST 경로를 거의 그대로 옮긴 형태라, API 문서를 읽을 줄 알면 CLI 사용법은 절반쯤 안 것이다.

REST 요청gws 명령
GET /drive/v3/filesgws drive files list --params '{"pageSize":10}'
GET /drive/v3/files/{fileId}gws drive files get --params '{"fileId":"abc123"}'
POST /gmail/v1/users/me/messages/sendgws gmail users messages send --json '{"raw":"..."}'
GET /sheets/v4/spreadsheets/{id}/values/{range}gws sheets spreadsheets values get --params '{...}'
POST /upload/drive/v3/filesgws drive files create --json '{...}' --upload ./report.pdf

리소스가 3단으로 내려가는 서비스도 있다. 지메일은 users → messages → attachments처럼 하위 리소스가 붙는다. 그래서 명령이 gws gmail users messages attachments get까지 길어진다. 계층을 외우는 게 아니라 --help를 따라 내려가면 된다.

전역 플래그는 서비스 공통이라 표로 정리해 두면 편하다.

플래그하는 일
--params <JSON>URL·쿼리 파라미터
--json <JSON>요청 본문(POST·PATCH·PUT)
--upload <PATH>파일을 multipart로 업로드
--dry-run요청만 조립하고 전송하지 않음
`--format json\table\yaml\csv`출력 형식
--page-all자동 페이지네이션, 페이지마다 JSON 한 줄
`--api-version v2\v3`API 버전 강제

두 종류의 명령 — Discovery 메서드와 + 헬퍼

자동 생성 명령만으로는 "안 읽은 메일 요약" 같은 일상 작업이 너무 번거롭다. 그래서 저장소가 손으로 만든 헬퍼를 따로 넣어 두는데, 자동 생성 이름과 절대 겹치지 않도록 앞에 +를 붙인다. --help에서도 [Helper]로 구분해 보여준다.

$ gws workflow --help
Commands:
  +standup-report  [Helper] Today's meetings + open tasks as a standup summary
  +meeting-prep    [Helper] Prepare for your next meeting: agenda, attendees, and linked docs
  +email-to-task   [Helper] Convert a Gmail message into a Google Tasks entry
  +weekly-digest   [Helper] Weekly summary: this week's meetings + unread email count
  +file-announce   [Helper] Announce a Drive file in a Chat space
서비스헬퍼하는 일
gmail+send +reply +reply-all +forward스레딩까지 알아서 처리하는 메일 명령
gmail+triage +watch안 읽은 메일 요약, 새 메일 NDJSON 스트리밍
calendar+agenda +insert다가오는 일정, 일정 생성
sheets+read +append범위 읽기, 행 추가
drive+upload메타데이터 자동으로 채워 업로드
workflow+standup-report +meeting-prep +weekly-digest여러 서비스를 묶은 요약
modelarmor+sanitize-prompt +sanitize-response프롬프트 인젝션 검사

+agenda 같은 시간 인식 헬퍼는 캘린더 설정 API에서 계정 시간대를 읽어 24시간 캐시한다. 시간대를 바꾸려면 --timezone Asia/Seoul처럼 플래그로 덮으면 된다.

인증 구조 — 우선순위 4단계와 키체인 암호화

자격증명은 정해진 순서로 찾는다. 위에서부터 먼저 발견되는 것을 쓴다.

순위방식설정
1액세스 토큰GOOGLE_WORKSPACE_CLI_TOKEN
2자격증명 파일GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE
3암호화된 자격증명gws auth login 결과
4평문 자격증명~/.config/gws/credentials.json

3번은 저장 방식이 눈에 띈다. 자격증명을 AES-256-GCM으로 암호화하고, 키는 OS 키체인(맥은 Keychain Access, 윈도는 Credential Manager)에 넣는다. 0.22.3에서 키체인 연동이 엄격해져서, 예전처럼 키 파일을 평문으로 떨어뜨리지 않는다. 키 파일을 꼭 써야 하는 환경에서만 GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file로 바꾼다 (CHANGELOG).

서버나 CI에서는 두 가지 방법을 쓴다. 브라우저가 있는 기기에서 자격증명을 내보내 옮기거나, 서비스 계정 키를 그대로 가리킨다.

# 브라우저 있는 기기에서 내보내기 → 헤드리스 서버에서 사용
gws auth export --unmasked > credentials.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json

# 이미 토큰을 발급하는 도구가 있을 때
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

주의할 점은 OAuth 앱이 테스트 모드일 때 스코프가 25개로 제한된다는 것이다. 권장 프리셋은 85개가 넘는 스코프를 요청하기 때문에, @gmail.com 계정에서는 그대로 실패한다. 필요한 서비스만 골라서 로그인해야 한다.

gws auth login -s drive,gmail,sheets

출력과 종료 코드 — 스크립트가 분기할 수 있게

성공이든 실패든 출력은 JSON이다. 인증이 없을 때 내가 받은 응답은 이랬다.

{
  "error": {
    "code": 401,
    "message": "Access denied. No credentials provided. Run `gws auth login` or set GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE to an OAuth credentials JSON file.",
    "reason": "authError"
  }
}

종료 코드도 실패 종류별로 나뉜다. 에러 메시지를 정규식으로 긁지 않아도 스크립트가 분기할 수 있다는 뜻이다.

코드의미내가 직접 확인한 경우
0성공gws --version, --dry-run
1API 오류잘못된 fileId
2인증 오류자격증명 없이 drive files list → 2
3검증 오류gws unknown-service files list → 3
4Discovery 오류Discovery 문서를 못 받음
5내부 오류예기치 않은 실패

--dry-run은 인증을 건너뛰고 요청 조립 결과만 보여준다. API를 호출하기 전에 URL과 multipart 여부를 확인하기 좋다.

$ gws gmail +send --to a@b.com --subject t --body hi --dry-run
{
  "body": null,
  "dry_run": true,
  "is_multipart_upload": true,
  "method": "POST",
  "query_params": [],
  "url": "https://gmail.googleapis.com/upload/gmail/v1/users/me/messages/send"
}

목록 API는 --page-all로 자동 페이지네이션을 켠다. 결과가 페이지마다 JSON 한 줄(NDJSON)로 떨어지므로 jq로 바로 이어 붙이면 된다.

gws drive files list --params '{"pageSize":100}' --page-all --page-limit 5 \
  | jq -r '.files[].name'

그림 2. 자동 생성 명령과 + 헬퍼, 그리고 인증·출력 계층이 겹쳐 있는 구조.

에이전트 스킬 레이어 — SKILL.md 100개

저장소가 CLI만 배포하지 않는다는 점도 구조의 일부다. 서비스마다 SKILL.md를 두고, 헬퍼와 자주 쓰는 레시피까지 문서로 묶어서 같이 배포한다. README 기준 100개가 넘고, 목록은 gws generate-skills로 자동 생성된다 (Skills Index).

# 전체 스킬 설치
npx skills add https://github.com/googleworkspace/cli

# 필요한 것만
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive

# OpenClaw에서 저장소와 동기화된 상태로 쓰기
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

이 구조가 에이전트에 잘 맞는 이유는 두 가지다. 모든 응답이 JSON이라 파싱 규칙이 하나면 되고, --sanitize로 Model Armor를 걸면 API 응답을 에이전트에 넣기 전에 프롬프트 인젝션을 검사할 수 있다.

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

Gemini CLI 확장으로도 붙는다. 이 경우 gws가 자기 인증을 직접 관리하므로 터미널에서 한 번만 로그인하면 확장이 그 자격증명을 이어받는다.

내가 막혔던 곳

처음 npm install @googleworkspace/cli로 설치했더니 바이너리가 없었다. 이 npm 설정이 postinstall 스크립트를 자동 실행하지 않아서(allow-scripts 경고만 뜨고 스킵) 바이너리 다운로드 단계가 건너뛰어진 탓이다. 결국 릴리스 tar.gz를 직접 받아 풀었다. 0.22.5 체인지로그에 "바이너리가 없으면 실행 시 자동 설치" 수정이 들어간 걸 보면 같은 일을 겪은 사람이 나뿐은 아닌 것 같다.

두 번째는 따옴표다. --params는 JSON 문자열이라 반드시 작은따옴표로 감싸야 한다. 큰따옴표로 감싸면 셸이 먼저 해석해서 JSON이 깨지고, 시트 범위의 !는 zsh 히스토리 확장으로 먹혀 버린다. '{"range": "Sheet1!A1:C10"}'처럼 통째로 감싸는 게 안전하다.

세 번째는 종료 코드다. gws ... | head로 출력을 자르고 echo $?를 찍었더니 0이 나왔다. 파이프의 마지막 명령(head) 상태가 찍힌 것이라 gws의 실패가 가려진 것이다. 지금은 출력을 파일로 돌리고 ; echo $?를 따로 찍어서 확인한다.

참고 자료

반응형
반응형
코딩테스트 Python 준비 — 3개월 로드맵과 필수 문법·자료구조

코딩테스트 준비를 시작할 때 많이 하는 실수는 푼 문제 수를 세는 것이다. 파이썬은 문법이 짧아서 3개월이면 손에 붙지만, 무엇을 어떤 순서로 익히느냐에 따라 같은 시간이 두 배로 갈린다. 이 글은 내가 실제로 돌린 12주 루틴과, 그 기간에 몸에 붙여야 하는 문법·자료구조만 추린 정리다.

30초 요약

궁금한 것답
기간하루 1~2시간 기준 12주. 직장인은 16주로 늘려도 된다
1개월 차입력 처리와 기본 문법. input() 대신 sys.stdin으로 읽는 습관부터
2개월 차자료구조 5개(deque, dict, Counter, heapq, bisect)를 손으로 써본다
3개월 차유형별 패턴을 문제 60~80개로 굳힌다. 새 유형은 이때 늘리지 않는다
하루 루틴복습 30분 + 새 문제 60분 + 오답 노트 20분
언어 선택파이썬 정수는 크기 제한이 없다. 긴 자릿수 연산을 직접 구현할 필요가 없다 (표준 타입 문서)
판단 기준"맞았다"가 아니라 "왜 이 풀이인지 남에게 설명된다"

그림 1. 12주 동안 무엇을 어떤 순서로 쌓는지.

목차

  1. 코딩테스트 Python 준비 전체 로드맵 — 12주
  2. 1개월 차: 입력 처리부터 — input() 대신 sys.stdin
  3. 2개월 차: 손에 붙여야 하는 자료구조 5개
  4. 3개월 차: 유형별 풀이 패턴
  5. 시간복잡도 — n을 보고 풀이를 고르는 법
  6. 자주 틀리는 Python 문법 함정
  7. 내가 막혔던 곳
  8. 참고 자료

코딩테스트 Python 준비 전체 로드맵 — 12주

12주를 세 덩어리로 나눈다. 한 덩어리가 끝날 때 남는 결과물이 없으면 다음으로 넘어가지 않는다. 강의 진도보다 이 결과물이 기준이다.

주차목표그 달에 남겨야 하는 것
1~4주입력·출력, 리스트·문자열·딕셔너리 조작, 함수 분리템플릿 파일 1개(입력 파싱 + 출력)
5~8주자료구조 5개를 문제에 직접 적용자료구조별 코드 스니펫 5개
9~12주유형별 패턴 6개, 시간 관리오답 노트 30문제, 유형별 체크리스트

처음 4주에 욕심을 내서 DP부터 건드리면 대부분 중간에 멈춘다. 입력을 못 읽어서 틀리는 구간을 먼저 없애야 그 뒤가 재밌어진다. 로컬 환경부터 정리해야 한다면 가상환경 만드는 법을 먼저 보고 오면 된다 (Python 가상환경 venv 만들기).

1개월 차: 입력 처리부터 — input() 대신 sys.stdin

첫 달의 절반은 입력이다. 문제를 풀 줄 알아도 입력 형식에서 틀리면 0점이고, 채점 서버는 내 화면을 봐주지 않는다. 두 가지 템플릿만 외우면 대부분 커버된다.

import sys

input = sys.stdin.readline          # 한 줄씩 읽을 때

n = int(input())
arr = list(map(int, input().split()))
graph = [list(map(int, input().split())) for _ in range(n)]
import sys

data = sys.stdin.buffer.read().split()   # 전체를 한 번에 토큰으로
n = int(data[0])
arr = list(map(int, data[1:1 + n]))

두 번째 형태는 줄바꿈과 공백을 구분하지 않고 토큰 단위로 잘라 준다. 줄 수가 많은 문제에서 편하고, sys.stdin.buffer는 바이트 스트림이라 디코딩 단계가 하나 줄어든다 (sys.stdin 문서).

이 달에 같이 정리해야 하는 것들.

  • 출력은 print를 반복하지 말고 리스트에 모아 '\n'.join(map(str, ans))로 한 번에 낸다.
  • 문자열은 불변이라 s[i] = 'a'가 안 된다. 리스트로 바꿔 고치고 ''.join()으로 되돌린다.
  • //는 음수에서 아래로 내려간다. -7 // 2는 -4다. 나머지 연산과 같이 쓸 때 부호를 확인한다.
  • 함수는 solve() 하나에 몰아넣고 마지막에 if __name__ == "__main__": solve()를 붙인다. 재귀를 쓸 때 지역 변수 스코프가 단순해진다.

2개월 차: 손에 붙여야 하는 자료구조 5개

라이브러리로 해결되는 문제가 생각보다 많다. 직접 구현하는 시간을 줄이는 게 목적이 아니라, 어떤 상황에서 꺼내 쓸지 몸이 기억하게 하는 게 목적이다.

자료구조언제핵심 API
collections.deque양 끝에서 넣고 빼는 BFS, 슬라이딩 윈도append, appendleft, popleft, maxlen
dict개수 세기, 방문 표시, 인덱스 매핑get(k, 0), setdefault, in
collections.Counter빈도 문제, 애너그램most_common(n), subtract, + 연산
heapq우선순위 큐, 다익스트라, 상위 k개heappush, heappop, heapify
bisect정렬된 배열에서 위치 찾기, LISbisect_left, bisect_right, insort

deque는 양쪽 끝에서의 추가·삭제가 빠르도록 만든 컨테이너라는 점이 문서에 명시돼 있다 (collections 문서). 리스트에서 pop(0)을 반복하면 뒤 원소를 매번 당겨야 해서 느려진다. BFS 큐는 무조건 deque라고 외워두면 된다.

from collections import deque, Counter
import heapq, bisect

q = deque([1, 2, 3])
q.appendleft(0)
q.popleft()

cnt = Counter("banana")
print(cnt.most_common(2))        # [('a', 3), ('n', 2)]

h = []
heapq.heappush(h, (3, "c"))
heapq.heappush(h, (1, "a"))
print(h[0])                     # 최소 힙의 루트가 가장 작은 원소

arr = [1, 3, 5, 7]
print(bisect.bisect_left(arr, 5))   # 2
print(bisect.bisect_right(arr, 5))  # 3

heapq는 최소 힙이고 h[0]이 가장 작은 값이다 (heapq 문서). 최대 힙이 필요하면 (-값, 값) 튜플로 넣는 방식을 쓴다. bisect는 값을 찾는 함수가 아니라 삽입 위치를 돌려주는 함수라서, 같은 값이 여러 개일 때 왼쪽·오른쪽 중 어디에 넣을지를 left/right로 고른다 (bisect 문서).

그림 2. 다섯 개를 언제 꺼내는지 한 장으로 정리.

3개월 차: 유형별 풀이 패턴

마지막 달은 새 문법을 배우지 않는다. 패턴을 반복해서 손에 붙인다. 유형마다 "이 신호가 보이면 이걸 쓴다"는 조건을 하나씩 붙여두면 문제 읽는 속도가 달라진다.

유형문제에서 보이는 신호첫 시도
완전탐색·백트래킹입력이 작다(n ≤ 8~10), 모든 조합을 묻는다itertools 또는 재귀 + 되돌리기
BFS최단 거리, 격자 이동, 단계 수deque + 방문 배열
DFS연결 요소, 사이클, 경로 존재재귀 또는 스택
이분 탐색"정렬된 배열", "최소값 중 최대"bisect 또는 매개변수 탐색
DP앞의 결과를 재사용, 경우의 수·최적값표 채우기, 메모이제이션
그리디정렬 후 앞에서부터 결정정렬 + 교환 논리 증명

유형별로 10문제씩만 풀어도 60문제다. 이 정도면 처음 보는 문제에서도 "아 이건 매개변수 탐색 냄새가 난다"가 온다. 문제 수를 늘리는 것보다 같은 유형을 붙여서 푸는 게 효율이 좋다.

시간복잡도 — n을 보고 풀이를 고르는 법

문제를 읽으면 가장 먼저 n을 확인한다. n이 10만이면 O(n²)은 통과하지 못하고, n이 20이면 O(2ⁿ)까지도 된다. 아래 표는 내가 문제를 고를 때 쓰는 어림값이다. 공식 기준이 아니라 경험으로 잡은 값이라는 점을 먼저 밝혀둔다.

n의 크기노려볼 복잡도흔한 풀이
10 이하O(n!), O(2ⁿ)순열, 부분집합
20~25O(2ⁿ)비트마스크 DP
100~500O(n³)삼중 반복, 플로이드-워셜
1,000~5,000O(n²)이중 반복, DP 표
10만~100만O(n log n)정렬, 이분 탐색, 힙
1,000만 이상O(n)한 번 훑기, 투 포인터

복잡도를 계산할 때는 반복문 중첩만 세면 부족하다. 리스트 슬라이스는 새 리스트를 만들기 때문에 반복문 안에서 arr[i:]를 쓰면 그 자체가 O(n)이다 (리스트 튜토리얼). 정렬은 sorted가 안정 정렬이라 같은 키의 순서가 유지되고, 이 성질을 이용해 두 번 정렬하는 트릭도 쓸 수 있다 (정렬 HOWTO).

자주 틀리는 Python 문법 함정

맞은 줄 알았는데 틀리는 경우는 대부분 문법이 아니라 값의 복사·공유다.

함정증상대응
[[0] m] n한 행을 고치면 모든 행이 바뀐다[[0] * m for _ in range(n)]
슬라이스 대입원본이 안 바뀐 줄 안다슬라이스는 새 리스트를 만든다
재귀 깊이깊은 DFS에서 RecursionError반복문으로 바꾸거나 한도 조정
dict 순회 중 수정RuntimeError: dictionary changed sizelist(d.items())로 복사 후 순회
정수 나눗셈음수에서 예상과 다른 값//와 %를 함께 확인
input() 반복줄 수가 많으면 느려진다sys.stdin으로 교체

재귀 한도는 sys.setrecursionlimit()으로 올릴 수 있지만, 문서는 최대 한도가 플랫폼에 따라 다르고 너무 높이면 크래시할 수 있다고 경고한다 (sys 문서). 재귀를 스택으로 바꾸는 연습이 오래 간다.

내가 막혔던 곳

처음에 BFS를 리스트 큐로 짰다. 작은 테스트는 통과했고 제출에서 시간 초과가 났다. 원인은 pop(0)이었고, deque로 바꾸자 같은 로직이 통과했다. 그 뒤로는 큐가 나오면 코드를 쓰기 전에 import 줄부터 적는다.

두 번째는 재귀 DFS였다. 깊이 1,000 근처에서 RecursionError가 났고, 한도를 올렸더니 이번엔 채점 환경에서 세그폴트가 났다. 로컬과 채점 서버의 스택 크기가 다르다는 걸 그때 알았다. 지금은 깊이가 클 것 같으면 처음부터 반복문으로 쓴다.

세 번째는 얕은 복사였다. visited = [[False] m] n으로 초기화하고 한 달 동안 이상한 답을 냈다. 디버깅에 쓴 시간이 문제 푸는 시간보다 길었다. 이후로는 2차원 배열을 만들 때 무조건 컴프리헨션으로 쓴다.

환경 쪽에서 막히면 그것도 시간을 잡아먹는다. pip install이 안 되거나 모듈을 못 찾는 오류는 따로 정리해 두었다 (ModuleNotFoundError 해결). 공부 순서를 더 크게 잡고 싶다면 개발자 AI 공부 로드맵도 참고할 만하다 (개발자 AI 공부 순서).

참고 자료

관련 글

반응형

+ Recent posts