강남거북이개발자

git을 처음 배울 때 어려운 건 개념이 아니라 명령이 실패했을 때다. fatal:로 시작하는 줄이 뜨면 무슨 일이 일어난 건지 알 수 없어서, 구글에 그 문장을 그대로 붙여넣고 블로그 몇 개를 전전하게 된다.

이 글은 로컬 저장소에서 커밋하고 원격에 올리는 흐름을 한 번 훑은 뒤, 입문자가 실제로 가장 자주 만나는 에러 7개를 증상별로 정리했다. 명령은 macOS의 git 2.39.2에서 직접 실행해 확인했다.

30초 요약

목차

1. git 기초 사용법, 이 흐름 하나만 익히면 된다
2. 설치와 최초 설정 — 커밋이 거부되는 이유
3. 로컬 작업 — status·add·commit·log
4. 원격 저장소 — remote·push·clone
5. 브랜치와 충돌 — switch·merge
6. 자주 나는 에러 7가지
7. 되돌리기 — restore·reset·revert 차이
8. 내가 막혔던 곳
9. 참고 자료

git 기초 사용법, 이 흐름 하나만 익히면 된다

git은 파일을 세 군데에 나눠 담는다. 작업 폴더, 스테이징 영역(index), 커밋 기록이다. git add는 작업 폴더의 변경을 스테이징으로 올리고, git commit은 스테이징에 있는 것만 기록으로 남긴다. 이 구조를 알고 나면 "분명히 고쳤는데 커밋에 안 들어간다"는 상황이 이해된다.

처음 배울 때는 아래 다섯 줄이면 충분하다. 나머지 명령은 이 흐름이 막힐 때 꺼내 쓰는 도구다.

git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/USER/REPO.git
git push -u origin main

-u는 이후에 git push만 쳐도 같은 원격·브랜치로 올라가게 묶어두는 옵션이다. 한 번만 붙이면 된다.

설치와 최초 설정 — 커밋이 거부되는 이유

맥에서는 터미널에서 git을 처음 실행하면 Xcode Command Line Tools 설치 안내가 뜬다. 그 창에서 설치를 누르면 /usr/bin/git이 생긴다. 내 맥에서는 git version 2.39.2 (Apple Git-143)이 잡혀 있다. 더 최신 버전이 필요하면 Homebrew로 따로 깔 수 있고, 이때 PATH 순서에 따라 두 개가 공존할 수 있다. 그 이야기는 Mac 개발환경 세팅에 정리해 뒀다.

설치 다음에 반드시 하는 설정이 있다. 이름과 이메일이 없으면 git이 커밋을 만들어주지 않는다.

git config --global user.name "Henry"
git config --global user.email "me@example.com"
git config --global init.defaultBranch main
git config --list --show-origin

세 번째 줄은 새 저장소의 기본 브랜치 이름을 정한다. 공식 문서를 보면 git init의 기본값은 아직 master이고, Git 3.0에서 main으로 바뀔 예정이라고 적혀 있다. (git-init) 지금 맞춰두면 나중에 이름이 바뀌어도 헷갈리지 않는다.

--show-origin은 각 설정이 어느 파일에서 왔는지 알려준다. 회사 저장소에서만 다른 이메일을 쓰는 경우처럼 설정이 겹칠 때 이 옵션으로 원인을 찾는다.

로컬 작업 — status·add·commit·log

작업 순서는 늘 같다. 무엇이 바뀌었는지 보고, 필요한 것만 올리고, 메시지를 붙여 기록한다.

git status -sb          # 현재 브랜치와 변경 파일
git add -p              # 바뀐 부분을 하나씩 확인하며 스테이징
git commit -m "로그인 폼 유효성 검사 추가"
git log --oneline --graph -10

git add -p는 처음엔 번거롭게 느껴진다. 그런데 디버그 출력이나 임시 주석이 커밋에 섞이는 일이 확 줄어든다. 커밋 하나에 한 가지 변경만 담는 습관도 여기서 생긴다.

메시지는 "무엇을"보다 "왜"를 적는다. fix bug보다 빈 이메일로 로그인 시 500 오류 수정이 나중에 도움이 된다.

원격 저장소 — remote·push·clone

GitHub에 빈 저장소를 만들었다면 주소를 등록하고 올린다. 이미 있는 저장소를 받을 때는 clone 한 줄이면 되고, 이때 origin이 자동으로 잡힌다.

git remote add origin https://github.com/USER/REPO.git
git remote -v
git branch -M main
git push -u origin main

# 반대 방향
git clone https://github.com/USER/REPO.git

인증은 비밀번호로 하지 않는다. GitHub는 git 작업에 계정 비밀번호를 받지 않고, Personal Access Token이나 SSH 키를 쓴다. (GitHub 문서) 토큰을 URL에 넣어두면 편하지만, 그 URL이 그대로 커밋이나 로그에 남을 수 있어서 나는 SSH 키를 쓴다.

ssh-keygen -t ed25519 -C "me@example.com"
pbcopy < ~/.ssh/id_ed25519.pub   # GitHub > Settings > SSH keys에 붙여넣기
ssh -T git@github.com

마지막 줄에서 Hi USER! You've successfully authenticated가 나오면 끝이다. 처음 SSH로 접속할 때 뜨는 fingerprint 확인 문구는 yes를 입력한다.

브랜치와 충돌 — switch·merge

브랜치를 만들고 옮기는 명령은 2.23에서 switch와 restore로 분리됐다. 예전 글에 있는 checkout도 여전히 동작하지만, 새로 배울 때는 역할이 나뉜 명령을 쓰는 편이 헷갈리지 않는다.

git switch -c feature/login   # 만들면서 이동
git switch main               # 이동
git merge feature/login       # main에 합치기
git branch -d feature/login   # 합친 뒤 정리

같은 줄을 양쪽에서 고쳤다면 merge가 멈추고 CONFLICT (content)를 알려준다. 충돌 파일에는 <<<<<<<, =======, >>>>>>> 표시가 생긴다. 이 표시를 지우면서 남길 내용만 정리하고 나서 저장한 뒤 세 줄을 실행한다.

git status                 # 충돌 파일 확인
git add <해결한 파일>
git commit                 # merge 커밋 완료 (또는 git merge --continue)

중간에 마음이 바뀌면 git merge --abort로 merge 직전 상태로 돌아간다. 충돌 해결이 길어질 것 같으면 이 명령을 먼저 외워두는 게 낫다.

자주 나는 에러 7가지

입문 단계에서 실제로 자주 만나는 것들만 모았다. 대부분은 명령 한 줄로 풀린다.

refusing to merge unrelated histories는 GitHub에서 README를 만들고 로컬에서도 git init 후 첫 커밋을 따로 만든 경우에 난다. 두 저장소가 공통 조상을 갖지 않아서 git이 기본적으로 거부한다. --allow-unrelated-histories로 한 번 합치고 나면 이후부터는 정상적으로 동작한다. (git-merge)

push가 거부됐을 때 --force로 밀어버리는 사람이 많다. 남의 커밋이 사라질 수 있으니, 정말로 내 이력으로 덮어써야 하는 상황에서만 --force-with-lease를 쓴다. 원격이 내가 마지막으로 본 상태에서 바뀌었으면 이 옵션은 push를 거부한다. (git-push)

되돌리기 — restore·reset·revert 차이

되돌리기는 "무엇을 되돌리는지"에 따라 명령이 다르다. 여기서 많이 헤맨다.

reset은 기록을 지우고 revert는 기록을 남긴다. 혼자 쓰는 브랜치면 reset이 깔끔하고, 다른 사람과 공유한 브랜치면 revert를 쓴다. 공유 브랜치에서 reset 후 force push를 하면 동료의 로컬과 어긋난다.

git restore는 --staged를 붙이느냐에 따라 대상이 완전히 달라진다. 이 차이를 모르면 "add를 취소했는데 파일까지 사라졌다"는 상황이 생긴다. (git-restore)

내가 막혔던 곳

처음 git을 쓰던 시절, 나는 git init을 홈 디렉터리에서 실행했다. 그 뒤로 새 프로젝트를 만들 때마다 git status가 이상하게 많은 파일을 보여줬고, 왜 그런지 한참 몰랐다. 상위 폴더에 .git이 있으면 git은 거기를 저장소로 인식한다. 지금은 프로젝트 폴더를 만든 뒤 그 안에서만 git init을 한다. 이미 늦었다면 ls -a로 상위 경로를 훑어 .git이 있는지 확인하면 된다.

두 번째는 첫 push에서 겪은 인증 실패다. 비밀번호를 계속 넣어도 Authentication failed가 떴다. GitHub가 git 작업에 계정 비밀번호를 더 이상 받지 않는다는 걸 그때 알았다. 토큰을 만들고 나서 해결됐지만, 토큰을 원격 URL에 넣어둔 탓에 나중에 그 주소가 스크립트에 남아 있었다. 지금은 SSH 키를 쓰고, 원격 주소에는 토큰을 넣지 않는다. 파이썬 프로젝트라면 .venv를 .gitignore에 넣는 것도 같이 챙긴다. Python 가상환경 venv 만들기에서 만든 폴더를 그대로 커밋하면 저장소가 순식간에 무거워진다.

세 번째는 git pull 습관이다. 원격에 커밋이 있는 상태에서 그냥 git pull을 하면 merge 커밋이 생기고, 이력이 지저분해진다. 혼자 쓰는 저장소에서는 git config --global pull.rebase true로 rebase를 기본으로 두는 편이 읽기 쉽다. 다만 이미 push한 커밋을 rebase하면 해시가 바뀌므로, 협업 브랜치에서는 습관대로 쓰면 안 된다.

참고 자료

• git-init — 기본 브랜치 이름, Git 3.0에서 main으로 변경 예정
• git-config — user.name, init.defaultBranch, pull.rebase
• git-switch · git-restore — 2.23에서 분리된 명령
• git-merge — --allow-unrelated-histories, 충돌 처리
• git-push — --force-with-lease 동작
• git/git 태그 — v2.56.0
• GitHub — About authentication to GitHub — 토큰·SSH 키
• Mac 개발환경 세팅 · Python 가상환경 venv 만들기 · Claude Code 설치·사용법

퍼플렉시티가 2026년 11월 5일(현지시간) Teammates를 공개했다. 한 번 질문하고 답을 받는 도구가 아니라, 마케팅·영업·고객지원 같은 업무를 계속 맡아서 처리하는 상주형 에이전트다.

이 글은 Teammates가 정확히 무엇인지, 기존 Computer와 무엇이 다른지, 월 얼마인지, 그리고 쓰기 전에 확인해야 할 위험을 정리한다.

30초 요약

목차

1. Perplexity Teammates란?
2. Computer와 무엇이 다른가
3. 실제로 무엇을 하나 — 직무별 예시
4. 설정 방법 5단계
5. 가격 — 월 $167, 진짜 비용은 크레딧
6. 한계와 주의할 점
7. 다른 AI 동료 제품과 비교
8. 내가 막혔던 곳
9. 참고 자료

Perplexity Teammates는 2026년 11월 5일 공개됐다. 한 번의 질문이 아니라 지속되는 업무를 맡기는 에이전트다.

Perplexity Teammates란?

Teammates는 "프롬프트를 쓰는 방식"에서 "목표를 맡기는 방식"으로 바꾸는 제품이다. 퍼플렉시티는 공식 블로그에서 이렇게 설명한다. "Teammates는 장기 작업을 맡을 수 있는 개인 에이전트로, 프로젝트를 계획하고 조정하며, 우선순위가 바뀌면 방향을 전환하고, 결과를 검토용으로 제시한다."

쉽게 말하면 이런 구조다. 사람이 "이 캠페인을 계속 관리해"라고 역할을 주면, 에이전트가 할 일을 스스로 쪼개고, 정해진 시간이나 조건에 맞춰 실행하고, 사람이 봐야 할 지점에서 승인을 요청한다. 대화 세션이 끝나도 기억이 남는다.

중요한 차이는 지속성이다. 지금까지의 챗봇은 세션이 끝나면 맥락이 끊겼다. Teammates는 프로젝트 목표, 작업 이력, 공유 파일을 실행 사이에 기억한다. 그래서 "어제 하던 그거 이어서"가 통한다.

2026년 11월 5일 기준으로는 웹에서만 쓸 수 있고, iOS와 데스크톱 앱은 준비 중이다. Free·Pro 사용자는 Max로 업그레이드해야 한다.

Computer와 무엇이 다른가

Computer는 퍼플렉시티의 멀티모델 에이전트다. 브라우저를 열고, 파일을 다루고, 여러 단계 작업을 수행한다. Teammates는 그 위에 "역할·기억·감시·인계"를 얹은 것이다.

퍼플렉시티 표현을 빌리면, Computer는 "일을 처리하는 실행기"이고 Teammates는 "그 실행기를 계속 굴리는 담당자"다. Teammates가 Computer 세션과 다른 Teammates를 조정하는 구조라서, 상위에 하나의 조정자(coordinator)가 있는 셈이다.

Computer와 Teammates는 같은 엔진을 쓰지만 작업 단위와 기억 방식이 다르다. Teammates는 실행 사이에도 맥락을 유지한다.

실제로 무엇을 하나 — 직무별 예시

공식 블로그가 든 예시는 네 가지다. 모두 마케팅 문구이지, 성과 지표가 아니다. 숫자나 정확도는 공개되지 않았다.

공통점은 "감시 → 판단 → 초안 → 승인 요청"의 루프다. 사람이 매번 시키지 않아도 움직인다는 게 핵심이고, 동시에 가장 위험한 지점이기도 하다. 잘못된 판단을 해도 스스로 멈추지 않고 계속 실행할 수 있기 때문이다.

Slack에 Teammate를 초대하면 동료들이 직접 일을 넘기거나 진행 상황을 물을 수 있다. 에이전트끼리 일을 넘기는 것도 된다. 예를 들어 한 에이전트가 웹사이트에서 버그를 찾으면, 다른 에이전트에게 수정 준비를 넘긴다.

설정 방법 5단계

공식 안내는 다섯 단계다. 어렵지 않지만, 4단계에서 무엇을 쓰느냐가 결과를 좌우한다.

1. 퍼플렉시티 웹에 로그인하고 왼쪽 내비게이션에서 Teammates를 고른다.
2. 프로젝트를 반영하는 이름을 붙이고 설정을 진행한다.
3. 필요한 도구를 연결한다. Slack, GitHub, Gmail 같은 플러그인을 붙이고, GitHub는 접근할 저장소를 고른다.
4. 맡길 일을 설명한다. 작업이 어디서 들어오는지, 무엇을 내놓아야 하는지, 언제 움직여야 하는지를 적는다.
5. 프로젝트에 배정하고 첫 작업을 준다. 시장 조사, 가입 흐름 개선, 버그 조사 같은 것부터 시작한다.

좋은 브리프 예시 (구조만 참고)
- 입력: 매일 09:00 Slack #cs 채널의 전날 불만 스레드
- 판단: 환불 요청, 배송 지연, 기능 오류로 분류
- 출력: 유형별 요약 1장 + 대표 답변 초안 3건
- 승인: 환불·보상이 걸린 건은 보내기 전에 나에게 확인
- 금지: 고객에게 직접 메일 발송하지 말 것

브리프에 "무엇을 하지 말라"를 꼭 넣는 게 좋다. 에이전트는 권한이 있으면 시키지 않은 일도 한다. 특히 발송·결제·삭제 권한은 처음부터 주지 않는 편이 안전하다.

가격 — 월 $167, 진짜 비용은 크레딧

Teammates 자체의 별도 요금은 공개되지 않았다. Max 구독에 포함된 형태다.

출처: Perplexity 요금 페이지. Max는 "최고 사용 한도, 프론티어 모델, 신기능 우선 접근"이 붙는 최상위 플랜이다.

여기서 놓치기 쉬운 게 크레딧이다. Teammates는 계속 돌아가고, 브라우저 세션을 열고, 다른 에이전트와 대화한다. 한 번 쓰고 마는 Computer 작업보다 크레딧을 빨리 먹을 수 있다. 퍼플렉시티는 Teammates의 크레딧 소모량을 별도로 밝히지 않았다. 상시 감시를 붙이기 전에 크레딧 사용량을 먼저 재보는 게 좋다.

한계와 주의할 점

공식 문서와 보도에서 확인되는 제약은 다음과 같다.

• Max 전용이다. Free·Pro는 쓸 수 없다.
• 웹에서 먼저 시작했다. iOS·데스크톱은 추후다.
• 정확도·시간 절감·오류율 같은 성과 지표가 공개되지 않았다. 블로그 예시는 마케팅 시나리오다.
• 기존 Projects·Memory·Skills·커넥터의 권한을 그대로 물려받는다. 편하다는 뜻이자, 권한이 넓다는 뜻이다.
• 에이전트별로 환경과 브라우저 세션은 분리되지만, 계정 권한 자체가 분리되는 건 아니다.
• 저장된 자격증명은 암호화되고 안전하게 입력된다고 안내하지만, 어떤 권한을 줬는지는 사용자가 관리해야 한다.
• 여러 에이전트가 서로 일을 넘기므로, 실패가 한 곳에서 끝나지 않고 연쇄될 수 있다.

실무에서는 세 가지를 먼저 정하는 게 좋다. 첫째, 에이전트가 직접 실행해도 되는 행동과 승인받아야 하는 행동을 나눈다. 둘째, GitHub 저장소·Slack 채널·메일 범위를 최소로 준다. 셋째, 첫 2주는 결과를 매일 검토한다. 자율성이 높은 도구일수록 초기 감시 비용을 아끼면 나중에 더 크게 낸다.

다른 AI 동료 제품과 비교

"상주형 업무 에이전트"는 2026년 들어 경쟁이 붙은 카테고리다. 이름만 다르고 방향은 비슷하다.

출처: Digital Trends. 제품별 세부 기능과 가격은 계속 바뀌므로, 도입 전에 각 공식 페이지를 확인해야 한다.

퍼플렉시티 공식 제품 페이지를 직접 캡처했다. Max 구독자에게 웹으로 먼저 열린다는 안내가 함께 나온다.

퍼플렉시티의 차별점은 개인 구독자에게 먼저 열었다는 점, 그리고 Computer·Projects·Memory·Skills라는 기존 자산을 그대로 쓴다는 점이다. 반대로 조직 관리 기능(권한 정책, 감사 로그, SSO)은 아직 엔터프라이즈 제품만큼 갖춰졌다고 보기 어렵다.

내가 막혔던 곳

처음엔 Teammates가 Computer의 새 이름인 줄 알았다. 둘 다 브라우저를 열고 여러 단계 작업을 한다. 차이는 지속성과 협업에 있었다. Computer는 내가 시킬 때 움직이고, Teammates는 맡긴 일을 기준으로 스스로 움직인다. 이 차이를 모르면 "그냥 Computer 쓰면 되는 거 아닌가"에서 멈춘다.

두 번째는 가격 표기였다. 어떤 기사는 월 $200, 어떤 기사는 월 $167이라고 쓴다. 둘 다 맞다. 월 결제가 $200이고, 연간 결제가 월 $167이다. 연간로 묶으면 1년에 약 $2,004다.

세 번째는 크레딧이다. 구독료만 보고 "월 $167이면 쓰겠다"고 판단했는데, 상시 감시형 에이전트는 크레딧을 계속 쓴다. 지금은 자동화를 붙이기 전에 일주일치 사용량을 먼저 보고, 그 다음에 상시 실행으로 바꾸는 순서가 맞다고 본다.

에이전트에 권한을 주는 구조는 AI 에이전트란에, 권한을 뺏기는 공격은 AI 탈옥이란에 정리해뒀다. 맡길 일을 문장으로 잘 쓰는 법은 프롬프트 작성법을 참고하면 된다.

참고 자료

• Perplexity — Teammates are agents for complex, ongoing work (기능, 직무별 예시, 설정 5단계, 격리·권한)
• Perplexity — Teammates 제품 페이지 (역할·상시 실행, Max 웹 우선)
• Perplexity — 요금 (Max 연간 월 $167, 월 $200, 크레딧 10,000)
• Digital Trends — Perplexity's new AI coworkers can take over your workload (출시일, Slack, 경쟁 제품)
• explainx — Perplexity Teammates: What They Do, Cost, Risks (2차 분석, 크레딧·위험 정리)

"AI 탈옥"이라는 말을 처음 들으면 아이폰 탈옥처럼 프로그램을 뜯어고치는 걸 떠올리기 쉽다. 실제로는 코드를 건드리지 않는다. 그냥 문장을 잘 꾸며서 모델의 안전장치를 넘기는 것이다.

이 글은 AI 탈옥이 정확히 무엇인지, 프롬프트 인젝션과 어떻게 다른지, 왜 아직도 막기 어려운지, 서비스 운영자라면 무엇부터 해야 하는지 정리한다.

30초 요약

목차

1. AI 탈옥이란?
2. 프롬프트 인젝션과 무엇이 다른가
3. 왜 통하는가 — 안전학습의 두 구멍
4. 실제로 쓰이는 기법
5. 에이전트 시대의 탈옥
6. 막는 방법 — 시스템 프롬프트만으로는 부족하다
7. 내가 막혔던 곳
8. 참고 자료

AI 탈옥은 코드를 고치는 공격이 아니다. 같은 컨텍스트 안에서 지시와 데이터가 섞이는 구조를 이용한다.

AI 탈옥이란?

AI 탈옥은 모델이 "이건 답하면 안 된다"고 학습한 요청에 답하게 만드는 입력을 뜻한다. OWASP는 탈옥을 "공격자가 모델이 안전 프로토콜을 완전히 무시하도록 만드는 프롬프트 인젝션의 한 형태"로 정의한다. (OWASP LLM01:2025)

중요한 건 모델 가중치를 바꾸는 게 아니라는 점이다. 서버도 건드리지 않는다. 그냥 대화 입력 안에서 모델을 설득하거나 속인다. 그래서 "탈옥"보다 "정책 우회"라는 표현이 더 정확할 때가 많다.

용어도 조금씩 다르게 쓰인다. 영문권에서는 jailbreak, 국내에서는 AI 탈옥이나 프롬프트 탈옥으로 부른다. 챗GPT탈옥, Claude 탈옥처럼 제품 이름을 붙여 부르기도 한다.

프롬프트 인젝션과 무엇이 다른가

두 용어는 현장에서 거의 같이 쓰이지만, 보안 관점에서는 출발점이 다르다. 사이먼 윌리슨은 인젝션을 "개발자가 넣은 지시와 사용자 입력을 모델이 구분하지 못하는 문제"로, 탈옥을 "모델의 안전장치를 우회하는 문제"로 나눴다. (Simon Willison, 2022)

OWASP는 둘을 완전히 분리하지 않는다. 탈옥을 인젝션의 하위 유형으로 본다. 실무에서는 "인젝션은 문을 여는 기술, 탈옥은 열린 문으로 금지 구역에 들어가는 기술" 정도로 이해하면 편하다.

왜 통하는가 — 안전학습의 두 구멍

2023년 논문 「Jailbroken: How Does LLM Safety Training Fail?」은 탈옥이 성공하는 이유를 두 가지로 정리했다. 하나는 경쟁 목표(competing objectives), 다른 하나는 일반화 불일치(mismatched generalization)다. (arXiv:2307.02483)

경쟁 목표는 모델의 능력과 안전 목표가 부딪히는 경우다. 예를 들어 "유능하게 답하라"는 학습과 "위험한 요청은 거절하라"는 학습이 동시에 걸려 있으면, 입력이 앞쪽을 더 강하게 자극할 때 뒤쪽이 밀린다. 역할극이나 가상 시나리오가 잘 먹히는 이유가 여기에 있다.

일반화 불일치는 안전 학습이 특정 영역에만 적용되는 현상이다. 안전 데이터는 주로 평범한 영어 대화로 만들어진다. 공격자가 Base64로 인코딩하거나, 잘 안 쓰는 언어로 바꾸거나, 코드 블록 안에 넣으면 모델의 능력은 유지되는데 안전 학습은 따라오지 못한다.

이 논문의 결론은 지금도 유효하다. 안전장치는 모델 능력만큼 정교해야 하고, 모델 크기를 키운다고 탈옥이 사라지지 않는다.

실제로 쓰이는 기법

공격 기법은 계속 바뀌지만 큰 틀은 몇 가지로 묶인다. 여기서는 동작하는 프롬프트는 싣지 않는다. 서비스 운영자가 로그에서 어떤 패턴을 봐야 하는지 아는 정도로만 정리한다.

많은 예시 깔기는 앤트로픽이 2024년에 공개한 기법이다. 가짜 사용자·AI 대화를 256개까지 붙이면 모델이 그 패턴을 따라 위험한 요청에도 답한다는 내용이다. 컨텍스트 윈도우가 커지면서 가능해진 공격이라, 긴 입력을 받는 서비스일수록 주의해야 한다. (Anthropic — Many-shot jailbreaking)

기법 자체보다 중요한 건 조합이다. 역할극에 인코딩을 섞고, 다시 다국어로 감싸면 단일 필터로는 걸러지지 않는다. 방어 쪽도 한 겹으로는 부족하다.

프롬프트 인젝션과 탈옥은 겹치지만 같은 말이 아니다. 노리는 것과 방어 지점이 다르다.

에이전트 시대의 탈옥

챗봇 탈옥은 "이상한 답변"에서 끝난다. 에이전트는 다르다. 모델에 파일 읽기, 웹 검색, 메일 발송, 코드 실행 권한이 붙어 있으면 탈옥은 곧 도구 오용으로 이어진다.

OWASP가 꼽는 인젝션의 영향에는 민감정보 노출, 시스템 프롬프트 유출, 권한 없는 기능 접근, 연결된 시스템에서의 임의 명령 실행이 들어간다. 에이전트를 만들 때 "모델이 거절할 것이다"에 기대면 안 되는 이유다.

간접 인젝션도 같이 봐야 한다. 사용자가 악의 없이 요약을 맡긴 웹페이지 안에 숨은 지시가 들어 있을 수 있다. 모델은 그걸 사용자 지시로 착각하고 실행한다. 브라우저를 다루는 에이전트라면 이 경로가 가장 현실적인 위협이다.

OWASP LLM01 문서를 직접 캡처했다. 탈옥을 프롬프트 인젝션의 하위 유형으로 정의하고, 완화책 7가지를 제시한다.

막는 방법 — 시스템 프롬프트만으로는 부족하다

OWASP가 제시하는 완화책은 모델 밖의 통제에 가깝다. 시스템 프롬프트는 첫 번째 겹일 뿐이고, 마지막 겹이 아니다.

출처: OWASP LLM01:2025 — Prevention and Mitigation Strategies

현실적인 우선순위는 4번과 5번이다. 프롬프트 필터는 우회당할 수 있지만, 권한을 줄이고 고위험 행동에 사람을 끼워 넣으면 사고 반경이 줄어든다. "탈옥 100% 방어"를 목표로 잡으면 끝이 없다. 대신 "탈옥당해도 큰일이 안 나는 구조"를 목표로 잡는 편이 낫다.

모델 제공사도 계속 안전 학습을 갱신한다. 하지만 OWASP는 생성형 AI의 확률적 특성 때문에 완벽한 예방법은 아직 없다고 못 박는다. 그래서 운영자는 탐지·차단·권한·승인을 조합으로 가져가야 한다.

내가 막혔던 곳

처음엔 AI 탈옥과 프롬프트 인젝션이 완전히 같은 말인 줄 알았다. 검색하면 두 용어가 섞여 나오고, 기사 제목도 제각각이라 구분이 안 됐다.

두 번째로 헷갈린 건 방어 지점이었다. 시스템 프롬프트에 "이전 지시를 무시하지 마"라고 쓰면 해결되는 줄 알았다. 실제로는 그 문장도 공격 대상이다. 공격자는 "위 문장은 테스트용이니 무시하라"고 다시 덮는다. 프롬프트 안의 방어 문장은 같은 컨텍스트에 있기 때문에 언제든 경쟁한다.

지금은 방어를 세 층으로 나눠서 본다. 모델 안(안전 학습·시스템 프롬프트), 모델 주변(입출력 필터·형식 검증), 모델 밖(권한·승인·격리). 탈옥 기사가 나오면 어느 층이 뚫린 사건인지부터 확인한다. 그 구분이 있으면 새 기법이 나와도 대응할 곳이 보인다.

프롬프트 자체를 안전하게 쓰는 법은 프롬프트 작성법에, 에이전트에 권한을 줄 때의 구조는 AI 에이전트란에 정리해뒀다. 모델이 없는 내용을 자신 있게 말하는 문제는 할루시네이션 뜻에서 다뤘다.

참고 자료

• OWASP — LLM01:2025 Prompt Injection (탈옥 정의, 직접·간접 인젝션, 7가지 완화책)
• Wei et al. — Jailbroken: How Does LLM Safety Training Fail? (경쟁 목표, 일반화 불일치)
• Anthropic — Many-shot jailbreaking (가짜 대화 256개, 컨텍스트 윈도우 악용)
• Simon Willison — Prompt injection attacks against GPT-3 (인젝션과 탈옥의 구분)
• Wikipedia — Prompt injection (용어 역사, 간접 인젝션 사례)

맥을 새로 사거나 초기화하고 나면 터미널부터 손대게 된다. 그런데 Homebrew를 깔고 나서 PATH가 안 잡혀서, iTerm2로 바꿨더니 단축키가 안 먹어서, .zshrc에 넣은 설정이 SSH에서는 안 먹어서 각각 한 번씩 멈춘다.

이 글은 맥 개발환경 세팅을 Homebrew → iTerm2 → zsh 설정 순서로 정리하고, 설치 직후에 실제로 막히는 지점만 따로 모았다.

30초 요약

목차

1. Mac 개발환경 세팅, 순서를 이렇게 잡는 이유
2. Homebrew 설치 — Apple Silicon과 Intel은 경로가 다르다
3. iTerm2 설치 — 기본 터미널과 갈리는 지점
4. zsh 설정 — .zprofile과 .zshrc에 뭘 넣나
5. Oh My Zsh, 깔까 말까
6. 자주 쓰는 명령과 단축키
7. 내가 막혔던 곳
8. 참고 자료

Mac 개발환경 세팅, 순서를 이렇게 잡는 이유

순서를 바꾸면 같은 작업을 두 번 하게 된다. 예를 들어 zsh 설정을 먼저 끝내고 Homebrew를 나중에 깔면, brew shellenv가 만드는 PATH를 다시 .zprofile에 넣어야 한다. 반대로 Homebrew를 먼저 깔면 iTerm2도 brew install --cask 한 줄로 끝나서 설치 경로가 한 곳으로 모인다.

그래서 나는 항상 이 순서로 한다. 패키지 관리자를 먼저 깔고, 터미널 앱을 바꾸고, 셸 설정 파일을 마지막에 정리한다. 파이썬만 급하면 Python 설치 (Mac)을 먼저 봐도 되지만, 그 뒤에 결국 이 글의 1~2단계로 돌아온다.

Homebrew 설치 — Apple Silicon과 Intel은 경로가 다르다

설치 명령은 공식 홈페이지에 있는 한 줄이다.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

이 스크립트는 무엇을 할지 먼저 보여주고 확인을 받은 뒤 진행한다. 중간에 멈춰 있는 것처럼 보이면 대개 sudo 비밀번호 입력을 기다리는 중이다. (brew.sh)

설치 위치는 CPU에 따라 갈린다. 이 차이를 모르면 나중에 "brew는 깔려 있는데 명령이 없다"는 상황을 만난다.

출처는 Homebrew 설치 문서와 지원 등급 문서다. Tier 3는 "기본 설치는 가능해도 안정적으로 동작한다고 보장하지 않는" 등급이라고 문서에 적혀 있다.

설치가 끝나면 셸에 PATH를 넣어야 한다. 설치 스크립트가 마지막에 두 줄을 안내하는데, Apple Silicon 기준으로는 이런 형태다.

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

그다음 세 줄로 상태를 확인한다. brew doctor는 경고를 잔뜩 뱉는 게 정상이다. 경고가 하나도 없으면 오히려 뭔가 빠졌을 때가 많다.

brew --version
brew --prefix
brew doctor

iTerm2 설치 — 기본 터미널과 갈리는 지점

앱은 cask로 설치한다. 다운로드 페이지에서 직접 받아도 결과는 같다.

brew install --cask iterm2

2026년 11월 6일 기준 안정판은 3.7.7이고, 빌드 날짜는 2026년 11월 3일, 지원 OS는 macOS 13 이상이다. (iTerm2 다운로드)

기본 Terminal과 비교하면 이런 차이가 있다. 설정 항목이 많다는 점이 장점이자 단점이다.

셸 통합(shell integration)은 켜두는 편이 좋다. 원격 서버에 SSH로 붙었을 때 현재 경로와 명령 기록을 iTerm2가 알 수 있게 되는 기능이다. 3.5 이상에서는 Settings → Profiles → General의 Command 항목에서 "Load shell integration automatically"를 켜면 된다. 수동으로 깔 때 쓰는 명령은 curl -L https://iterm2.com/shell_integration/install_shell_integration.sh | bash다. (iTerm2 Shell Integration 문서)

zsh 설정 — .zprofile과 .zshrc에 뭘 넣나

macOS 10.15부터 새로 만든 계정의 기본 셸은 zsh다. 예전 계정을 쓰고 있다면 chsh -s /bin/zsh로 바꿀 수 있고, /etc/shells에 등록된 경로만 쓸 수 있다. (Apple 지원 — zsh를 기본 셸로 사용하기)

파일 두 개의 역할이 다르다. 여기서 많이 헷갈린다.

내가 쓰는 .zshrc의 앞부분은 이렇게 생겼다. 길게 쓰지 않는다.

# ~/.zshrc
HISTFILE=~/.zsh_history
HISTSIZE=50000
SAVEHIST=50000
setopt hist_ignore_dups share_history

alias ll='ls -alh'
alias gs='git status -sb'

# Oh My Zsh를 쓴다면 이 줄이 먼저 와야 한다
source $ZSH/oh-my-zsh.sh

히스토리 크기를 늘리는 설정은 오래 쓰는 사람일수록 체감이 크다. 기본값이 작아서 몇 주만 지나도 예전 명령이 사라진다.

Oh My Zsh, 깔까 말까

Oh My Zsh는 zsh 설정을 관리하는 프레임워크다. 300개가 넘는 플러그인과 150개 테마를 함께 제공한다. (ohmyz.sh)

설치는 README에 있는 한 줄이다.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

플러그인은 .zshrc의 plugins=(...)에 이름만 넣으면 된다. 내가 쓰는 조합은 git, z, docker, python 정도다. 테마는 ZSH_THEME="robbyrussell"이 기본값이고, agnoster처럼 Powerline 폰트가 필요한 테마는 폰트를 따로 깔아야 글자가 깨지지 않는다. (Oh My Zsh README)

단점은 시작 속도다. 플러그인을 많이 넣으면 새 탭이 눈에 띄게 느려진다. 그리고 하루에 몇 번씩 업데이트를 확인하는 프롬프트가 뜨는데, 이게 싫으면 .zshrc에 한 줄을 넣어 끈다.

zstyle ':omz:update' mode disabled

프레임워크 없이 .zshrc만 직접 관리해도 충분한 사람이 많다. 자동완성이 아쉬우면 Python 가상환경 venv 만들기처럼 손이 자주 가는 작업부터 alias로 줄여보고, 그래도 부족할 때 넘어오는 편이 낫다.

자주 쓰는 명령과 단축키

설치 직후에 제일 많이 치는 것들만 모았다.

셸 단축키는 이것만 익혀도 손이 편해진다.

내가 막혔던 곳

첫 번째는 brew가 두 개였던 일이다. 예전에 Rosetta로 띄운 터미널에서 Homebrew를 설치해서 /usr/local/bin/brew가 남아 있었고, 새로 설치한 /opt/homebrew/bin/brew와 번갈아 잡혔다. 터미널마다 brew --version이 다르게 나와서 한참 헤맸다. 지금은 새 맥을 세팅할 때 가장 먼저 which -a brew로 중복을 확인한다. 두 줄이 나오면 하나는 지우고 PATH 순서를 정리해야 한다.

두 번째는 Intel 맥에서의 지원 등급이다. 내가 쓰는 맥은 macOS 13.7.8에 Intel CPU라, 공식 문서의 요구 사항(Apple Silicon + macOS 15 이상)에 들어가지 않는다. 실제로 Homebrew 6.0.18이 /usr/local/bin/brew에서 잘 돌고 있지만, 문서상으로는 Tier 3다. 새 formula를 깔 때 미리 빌드된 bottle이 없어서 소스 컴파일로 떨어지는 경우가 있고, 이때는 Xcode Command Line Tools가 필요하다. xcode-select --install로 미리 깔아두면 이 상황에서 덜 당황한다.

세 번째는 .zshrc에 PATH를 넣은 일이다. 새 탭에서는 잘 되는데 SSH로 들어가면 command not found가 났다. 로그인 셸이 읽는 파일이 .zprofile이라서 그랬다. PATH는 .zprofile, 나머지는 .zshrc로 나눠 넣고 나서야 두 경우가 같이 해결됐다. Claude Code처럼 설치 후 PATH 안내를 주는 도구를 쓸 때도 같은 함정에 빠지기 쉬우니, Claude Code 설치·사용법의 PATH 부분과 같이 보면 좋다.

참고 자료

• Homebrew — brew.sh (설치 명령, prefix, formula·cask 개념)
• Homebrew — Installation (macOS 요구 사항, sudo를 쓰지 않는 이유)
• Homebrew — Support Tiers (Tier 1 조건, Intel macOS는 Tier 3)
• Apple 지원 — zsh를 기본 셸로 사용하기 (10.15부터 기본, .zprofile·.zshrc 역할, chsh)
• iTerm2 — Downloads (3.7.7, macOS 13+)
• iTerm2 — Shell Integration (3.5부터 자동 로드, 설치 명령)
• Oh My Zsh · README (플러그인 300+, 테마 150, 설치·업데이트 설정)
• Python 설치 (Mac) · Python 가상환경 venv 만들기 · Claude Code 설치·사용법

2026년 11월 5일, 구글이 Gemini Omni 1.2 Flash를 정식 출시했다. 영상 길이가 10초에서 15초로 늘고, 가격은 30% 내렸다. 숫자만 보면 작은 업데이트 같지만, 실제로 바뀐 건 "영상 한 편을 다시 뽑지 않고 대화로 고친다"는 작업 방식이다.

이 글은 Gemini Omni 1.2 Flash가 무엇인지, 1.1과 뭐가 달라졌는지, 초당 $0.07이라는 요금이 실제로 얼마인지 정리한다.

30초 요약

목차

1. Gemini Omni 1.2 Flash란?
2. 1.1 Flash와 무엇이 달라졌나
3. 요금 계산 — 초당 $0.07은 실제로 얼마인가
4. Gemini API로 영상 만드는 방법
5. 어디서 쓸 수 있나 (제품별 정리)
6. 한계와 주의할 점
7. 내가 막혔던 곳
8. 참고 자료

Gemini Omni 1.2 Flash는 2026년 11월 5일 정식 출시됐다. 15초 영상과 초당 0.07달러라는 두 숫자가 이번 업데이트의 핵심이다.

Gemini Omni 1.2 Flash란?

Gemini Omni는 구글 딥마인드의 영상 생성·편집 모델 계열이다. 추론 특화 모델인 Gemini 4와 이름이 비슷해 헷갈리기 쉬운데, Omni는 "영상을 만들고 고치는 모델"이라고 보면 된다. 텍스트 프롬프트만으로 영상을 만들고, 만든 영상을 자연어 대화로 계속 수정할 수 있다.

입력은 텍스트, 이미지, 영상 세 가지다. 출력은 영상과 그에 맞춰진 네이티브 오디오, 그리고 텍스트다. 별도 음성 합성 단계를 붙이지 않아도 대사와 립싱크가 같이 나온다. (Gemini API 문서)

버전은 세 개가 있다. gemini-omni-1.2-flash가 현재 안정 버전이고, gemini-omni-1.1-flash는 2026년 12월 3일부터 1.2로 자동 라우팅된다. gemini-omni-flash-preview는 종료됐다. 기존 코드에서 1.1을 쓰고 있어도 12월 3일 이후에는 코드 수정 없이 1.2로 넘어가고, 요금은 더 싼 1.2 기준으로 매겨진다. (모델 문서)

한 가지 미리 짚어둘 점이 있다. 이 모델은 무료 티어가 없다. Gemini API에서 쓰려면 유료 티어여야 한다. (요금 문서)

1.1 Flash와 무엇이 달라졌나

가장 큰 변화는 길이다. 1.1은 최대 10초였는데, 1.2는 15초까지 만들고 편집한다. 3초에서 15초 사이를 1초 단위로 지정할 수 있어서, 6초 제품 소개나 15초 광고를 한 번에 뽑을 수 있다.

두 번째는 대화형 편집이다. 마음에 안 드는 부분이 있으면 전체를 다시 생성하는 대신 "배경만 바꿔줘", "조명을 더 따뜻하게"처럼 다음 턴에서 요청한다. 이 방식이 15초 전체 길이에서 동작한다. 초안은 360p나 720p로 빠르게 뽑고, 세부를 고친 다음, 최종본만 1080p나 4K로 업스케일하는 워크플로가 공식적으로 권장된다.

세 번째는 레퍼런스 고정이다. 최대 6장의 레퍼런스 이미지와 3초 이하의 짧은 모션 클립을 넣어 인물·제품·브랜드 색을 일관되게 유지한다. 얼굴, 의상, 패키지 타이포그래피가 카메라 각도가 바뀌어도 흐트러지지 않는 게 목표다.

네 번째는 연속 촬영감이다. FPV 드론 비행이나 급격한 줌아웃 같은 복잡한 카메라 무빙에서 불필요한 점프 컷이 줄었다고 구글은 설명한다. 다만 빠른 스포츠 동작, 급격한 대본 변경, 복잡한 물리 표현은 아직 개선 중이라고 공식 블로그에 적혀 있다.

1.1과 1.2를 같은 항목으로 비교했다. 길이와 가격이 바뀌고, 해상도와 레퍼런스 이미지 수는 그대로다.

출처: Google DeepMind 모델 문서, 출시 블로그

요금 계산 — 초당 $0.07은 실제로 얼마인가

공식 요금표는 초당 달러가 아니라 토큰 단위로 적혀 있다. 영상 출력은 100만 토큰당 $12이고, 720p 영상 1초가 5,792 토큰으로 계산된다. 이걸 곱하면 초당 약 $0.07이 나온다.

출처: Gemini API 요금. 입력은 텍스트·이미지·영상 모두 100만 토큰당 $1.50, 텍스트 출력은 100만 토큰당 $9다.

여기서 많이들 착각하는 게 있다. 15초 4K 한 편이 $3를 넘는다는 건, 열 번만 다시 뽑아도 $30이라는 뜻이다. 반대로 같은 15초를 360p로 초안 뽑고 마음에 드는 것만 4K로 올리면 비용이 크게 줄어든다. 구글이 "초안은 낮게, 최종만 높게"를 강조하는 이유가 여기에 있다.

15초 4K 최종본 1편 = $3.13
15초 360p 초안 5편 + 4K 업스케일 1편
= (0.35 × 5) + 3.13 = $4.88
→ 무작정 4K로 5번 뽑는 것($15.65)보다 약 3분의 1

Gemini API로 영상 만드는 방법

Python SDK에서는 client.interactions.create를 쓴다. 모델 이름만 넣고 프롬프트를 보내면 영상과 오디오가 함께 돌아온다.

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.2-flash",
    input="A marble rolling fast on a chain reaction style track, continuous smooth shot.",
)
with open("marble.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))

길이와 해상도, 화면 비율은 response_format에서 정한다. 세로 영상은 9:16, 가로는 16:9다.

interaction = client.interactions.create(
    model="gemini-omni-1.2-flash",
    input="A futuristic city with neon lights and flying cars, cyberpunk style",
    response_format={
        "type": "video",
        "aspect_ratio": "9:16",
        "resolution": "1080p",
        "duration": "15s",
    },
)

REST로 직접 호출할 때는 주의할 점이 있다. SDK의 interaction.output_video 편의 필드는 SDK 전용이고, REST 응답에서는 steps 배열 안의 model_output을 뒤져서 base64 영상 데이터를 꺼내야 한다. (REST 응답 스키마)

영상 확장은 마지막 10초를 참고해 3~10초씩 덧붙이는 방식이다. 한 번에 30초까지만 늘릴 수 있고, 앞쪽이나 중간에 끼워 넣는 건 안 된다. 대화가 들어 있는 업로드 영상에 새 대사를 추가하는 것도 현재는 지원하지 않는다.

어디서 쓸 수 있나 (제품별 정리)

제품별 제공 위치는 출시 블로그 기준이다. Google Vids는 15초 클립을 추가 비용 없이 만들 수 있다고 안내한다. 다만 Vids의 무료 생성과 API 과금은 별개다.

결과물에는 보이지 않는 SynthID 워터마크와 C2PA 콘텐츠 자격 증명이 붙는다. AI가 만든 영상인지 나중에 검증할 수 있게 하려는 장치다. (DeepMind — Gemini Omni)

구글 공식 발표 페이지를 직접 캡처했다. 15초·30% 인하·제공 제품 목록이 한 화면에 나온다.

한계와 주의할 점

문서에 적힌 제약을 모아두면 다음과 같다. (Limitations)

• 오디오 입력과 오디오 레퍼런스는 아직 지원하지 않는다. 레퍼런스 영상에 들어 있는 소리는 무시된다.
• 보이스 편집은 안 된다. 목소리만 바꾸는 용도로는 쓸 수 없다.
• 여러 영상을 동시에 참조하거나 비교 추론하는 기능은 없다.
• 시스템 지시문, temperature, top_p, 중지 시퀀스, 네거티브 프롬프트를 지원하지 않는다. 부정 조건은 본문 프롬프트에 "Do not do X" 형태로 써야 한다.
• 첫 프레임·마지막 프레임 보간은 3~10초만 된다. 10초를 넘기면 오류가 난다.
• 업로드한 영상의 편집·확장은 EEA, 스위스, 영국에서 아직 안 된다. 모델이 만든 영상을 다시 편집하는 건 된다.
• 미성년자가 나온 이미지의 업로드·편집은 EEA, 스위스, 영국에서 지원하지 않는다.
• YouTube 영상을 소스로 넣는 건 안 된다.

국내 사용자 입장에서 당장 걸리는 건 오디오 입력과 보이스 편집이다. 제품 광고에서 모델의 목소리를 그대로 쓰고 싶다면, 지금은 영상 생성 단계에서 대사를 함께 뽑는 방식으로 우회해야 한다.

내가 막혔던 곳

요금표를 처음 봤을 때 "초당 $0.07"만 보고 15초짜리를 몇 번 뽑아보면 얼마 안 나오겠다고 생각했다. 실제로는 세 가지가 더 붙는다.

첫째, 출력 길이를 안 정하면 기본값이 10초라는 점이다. 3초만 필요한데 10초로 뽑으면 같은 컷을 세 번 만드는 셈이다. duration을 항상 명시하는 습관이 비용을 줄인다.

둘째, 1080p와 4K는 업스케일 단계에서 토큰이 다시 매겨진다. 720p로 뽑고 4K로 올리면 720p 요금에 4K 요금이 더해지는 구조다. "4K로 바로 뽑으면 한 번만 내지 않나" 싶지만, 공식 계산은 해상도별 토큰 단위로 따로 잡힌다. 초안 단계와 최종 단계를 분리해서 견적을 내야 한다.

셋째, 1.1을 쓰던 코드가 12월 3일에 자동으로 1.2로 넘어간다. 요금은 싸지지만 출력 길이 기본값과 레퍼런스 제약이 달라지므로, 길이를 명시하지 않은 코드는 결과가 달라질 수 있다. 지금 duration을 넣어두면 12월 이후에도 같은 길이로 나온다.

영상 모델을 고를 때 전체 지형이 궁금하면 멀티모달 AI란과 AI 기초 용어 20개 정리를 같이 보면 도움이 된다. 프롬프트가 길어질 때의 토큰 계산은 토큰(token)이란에서 다뤘다.

참고 자료

• Google — Gemini Omni 1.2 Flash 출시 블로그 (2026-11-05, 15초·30% 인하·제품별 제공 위치)
• Gemini API — Generate and edit videos with Gemini Omni Flash (Interactions API, 길이·해상도·레퍼런스, 제약)
• Gemini API — Gemini Omni Flash 모델 사양 (토큰 한도, 3~15초, 24fps, 버전 정책)
• Gemini API — 요금 (초당 토큰, 해상도별 요금)
• Google DeepMind — Gemini Omni (SynthID·C2PA, 안전 평가)

앱 안에서만 되는 일이 아직 많다. 당근 나눔 신청, 예약 앱 체크인, 은행 앱 인증처럼 API가 없거나 막혀 있는 일은 자동화 스크립트가 손을 못 댄다. Phone Harness는 이 지점을 정면으로 건드린다. 에이전트에게 실제 폰 화면을 보여주고, 손가락 대신 탭하고 입력하게 만든다.

이 글은 Phone Harness가 무엇인지, 아이폰·안드로이드·클라우드 폰 중 무엇을 골라야 하는지, 설치와 첫 실행에서 어디서 막히는지 정리한다.

30초 요약

목차

1. Phone Harness란?
2. 설치 전에 확인할 것 — 아이폰·안드로이드·클라우드
3. 설치와 에이전트 연결 (Claude Code·Codex·OpenClaw)
4. 아이폰·안드로이드 연결 — 두 경로의 차이
5. 실제로 시키는 일 — 헬퍼 명령
6. 클라우드 폰 요금과 쓰는 법
7. 한계와 보안
8. 내가 막혔던 곳
9. 참고 자료

에이전트는 앱을 열고, 화면 글자에서 버튼 위치를 찾아 탭한 뒤 다시 화면을 읽는다. 사람이 폰을 쓰는 순서와 같다.

위 화면은 에이전트가 "설정 앱 열고 상위 10개 항목 읽기"를 수행하는 흐름을 도식으로 정리한 것이다. 사람이 하는 동작을 그대로 흉내 낸다는 점이 핵심이다.

Phone Harness란?

한 줄로 말하면 "폰을 다루는 손과 눈을 에이전트에게 붙여주는 도구"다. 탈옥도, Xcode 빌드도, 폰에 무언가를 설치하는 일도 없다. README는 이렇게 소개한다. "에이전트가 스크롤하고, 탭하고, 입력하고, 폰을 읽는다. 탈옥 없이, Xcode 없이, 폰에 설치되는 것도 없이." (GitHub README)

구조는 단순하다. Claude Code나 Codex 같은 CLI 에이전트가 내 컴퓨터에서 돌고, 그 에이전트가 phone-harness를 호출한다. Phone Harness는 폰 화면을 읽어 텍스트와 좌표를 돌려주고, 에이전트가 고른 좌표로 탭을 보낸다. 모델은 폰에 올라가지 않는다. 폰은 화면과 입력 장치 역할만 한다.

여기서 "하네스"라는 말이 낯설 수 있다. 원래 하네스는 모델을 둘러싸고 도구·권한·실행 환경을 붙여주는 껍데기다. 하네스(harness)란?에서 개념을 먼저 잡고 오면 이 글이 훨씬 빨리 읽힌다. Phone Harness는 그 껍데기에 "휴대폰"이라는 몸을 하나 더 단 셈이다.

지원 범위는 세 갈래다. 개인 아이폰은 맥의 iPhone Mirroring을 거친다. 개인 안드로이드는 adb로 붙는다. 폰이 없거나 여러 대가 필요하면 Phone Harness Cloud에서 빌려 쓴다. 세 경로의 요구사항이 완전히 다르므로, 설치보다 먼저 자기 폰이 어느 쪽인지 확인해야 한다.

설치 전에 확인할 것 — 아이폰·안드로이드·클라우드

아이폰 조건이 특히 빡빡하다. Apple 문서는 iPhone Mirroring 요구사항을 이렇게 못 박는다. "Mac이 macOS Sequoia 15 이후이고 Apple silicon 또는 Apple T2 보안 칩이 탑재된 Mac일 것, iPhone이 iOS 18 이후이고 암호가 설정되어 있을 것, 두 기기가 같은 Apple 계정으로 2단계 인증을 사용할 것." (Apple — iPhone Mirroring) T2 칩이 없는 인텔 맥은 여기서 탈락한다. 내 맥이 정확히 그 경우였고, 자세한 건 8번 절에 적었다.

아이폰·안드로이드·클라우드 폰의 조건을 한 장으로 비교했다. 아이폰 경로의 요구사항이 가장 빡빡하다.

표에 담은 세 경로를 그림으로 비교하면 위와 같다. "폰을 이미 갖고 있는가"와 "아이폰인가" 두 질문으로 갈린다고 보면 된다.

설치와 에이전트 연결 (Claude Code·Codex·OpenClaw)

기본은 PyPI 설치다. 2026-11-05 기준 최신 버전은 0.3.3이고 Python 3.10 이상을 요구한다. (PyPI — phone-harness)

pip install phone-harness
phone-harness --doctor          # 연결 상태 점검
phone-harness config set telemetry false   # 익명 사용 통계 끄기 (선택)

소스를 고치고 싶으면 Git 체크아웃으로 설치한다.

git clone https://github.com/phone-harness/phone-harness ~/.phone-harness
cd ~/.phone-harness
pip install -e .

다음은 에이전트에 스킬을 등록하는 단계다. 여기서부터가 진짜다. CLI만 깔면 사람이 명령어를 외워야 하지만, 스킬을 등록하면 에이전트가 헬퍼 목록과 요령을 스스로 읽는다.

# Claude Code
mkdir -p ~/.claude/skills/phone-harness
phone-harness skill > ~/.claude/skills/phone-harness/SKILL.md

# Codex
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness"
phone-harness skill > "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness/SKILL.md"

OpenClaw를 쓴다면 플러그인으로 붙는 쪽이 편하다. 설치는 한 줄이다. (OpenClaw 통합 문서)

openclaw plugins install clawhub:phone-harness

조건은 OpenClaw 2026.10.9 이상과 게이트웨이가 도는 머신에 uv가 있는 것이다. 플러그인은 phone_exec 도구 하나를 노출한다. 모델이 짧은 Python 스크립트를 쓰면 승인 창에 스크립트 전문이 뜨고, 내가 허용해야 폰에서 실행된다. 스크립트 앞 500자가 넘으면 승인 창에 다 못 담기 때문에 아예 승인 요청이 오지 않는다. 그래서 모델이 스크립트를 잘게 쪼개서 보낸다.

MCP 클라이언트를 쓴다면 https://mcp.phone-harness.com/mcp를 등록하면 된다. 다만 MCP는 아직 클라우드 폰(안드로이드 에뮬레이터·클라우드 아이폰)만 지원한다. 내 방에 있는 실기기를 MCP로 직접 부르는 건 안 된다.

아이폰·안드로이드 연결 — 두 경로의 차이

아이폰: iPhone Mirroring이 전부다

아이폰 경로의 원리는 이렇다. 맥에서 iPhone Mirroring을 켜면 폰 화면이 맥 창으로 흘러나온다. Phone Harness는 그 창을 캡처해서 Apple Vision 프레임워크로 글자를 읽고, 읽은 글자의 좌표에 클릭과 키 입력을 보낸다. 폰 입장에서는 맥이 보낸 터치와 키보드 입력으로 보인다.

phone-harness --doctor ios

순서는 네 단계다.

1. 맥에서 iPhone Mirroring을 열고 아이폰과 페어링한다.
2. 시스템 설정 → 개인정보 보호 및 보안에서 터미널(또는 게이트웨이 앱)에 손쉬운 사용과 화면 기록을 허용한다.
3. 화면 기록 권한을 준 뒤 터미널을 재시작한다. 이걸 빼먹으면 캡처가 계속 검게 나온다.
4. 아이폰은 잠근 상태로 둔다. 잠금을 풀면 미러링이 끊긴다.

마지막 항목이 실사용에서 제일 걸린다. 내가 폰을 들고 잠금을 풀면 에이전트의 세션이 끊긴다. 반대로 말하면, 에이전트에게 폰을 맡기는 동안에는 폰을 건드리지 않는 습관이 필요하다. 문서도 잠금 해제가 미러링을 멈춘다고 명시한다.

안드로이드: adb와 접근성 트리

안드로이드 쪽은 요구사항이 훨씬 관대하다. 맥이든 리눅스든 윈도우든 상관없다. 대신 폰에서 개발자 옵션을 열어야 한다.

# 1) 폰: 설정 → 휴대전화 정보 → 빌드번호 7번 탭 → 개발자 옵션 → USB 디버깅 켜기
# 2) USB로 연결하고 폰 화면의 디버깅 허용 팝업 승인
phone-harness --doctor android

# 무선으로 붙일 때 (Android 11 이상)
phone-harness android pair 123456    # 폰에 뜬 6자리 코드

USB를 뺄 때는 무선 디버깅을 쓰면 된다. 같은 Wi-Fi에서 페어링 코드만 넣으면 선 없이 붙는다. 노트북을 들고 다니며 폰을 조작하는 상황이면 이쪽이 편하다.

아이폰과 갈리는 지점은 "무엇을 보고 판단하느냐"다. 아이폰은 OCR로 글자를 읽고 좌표를 추정한다. 안드로이드는 접근성 트리에서 요소의 정확한 텍스트·경계·리소스 ID를 받는다. 그래서 tap_ui()처럼 이름으로 요소를 집는 명령이 안드로이드에만 있다. 글자가 안 보이는 버튼도 리소스 ID로 찾을 수 있다는 뜻이다.

단, 접근성 트리를 노출하지 않는 화면도 있다. 그럴 때는 결국 스크린샷을 보고 다음 동작을 정해야 한다. OCR과 트리를 오가는 구조라고 이해하면 된다.

실제로 시키는 일 — 헬퍼 명령

CLI는 헬퍼를 미리 불러온 상태로 Python 코드를 받는다. 터미널에서 바로 실행해 볼 수 있다.

phone-harness <<'PY'
open_app("Notes")
tap_text("New Note")
type_text("hello from the harness")
print([o["text"] for o in ocr()][:10])
PY

에이전트에게는 이렇게 시키면 된다. "노트 앱을 열고 새 메모를 만들어 '내일 9시 회의'라고 적은 다음, 화면에 제대로 들어갔는지 확인해줘." 에이전트는 앱 열기 → 버튼 찾기 → 입력 → 화면 다시 읽기 순으로 스스로 판단한다. 각 동작 뒤에 화면을 다시 읽는 것이 이 도구의 기본 리듬이다.

실무에서 쓸 만한 작업은 세 부류다. 첫째, 반복 입력이다. 매일 같은 앱에 같은 형식으로 기록하는 일. 둘째, 긴 목록 수집이다. scroll_collect()로 끝까지 내리며 텍스트를 모으면 손으로 캡처하는 것보다 빠르고 누락이 적다. 셋째, 앱 상태 확인이다. "이 화면에 오류 팝업 떴어?" 같은 질문은 스크린샷 한 장으로 끝난다.

클라우드 폰 요금과 쓰는 법

폰이 없거나, 여러 대를 동시에 돌리거나, 내 폰을 자동화에 쓰기 싫을 때 쓰는 경로다. (Phone Harness 요금)

과금 규칙에서 놓치기 쉬운 부분이 있다. 세션 시간에 프로비저닝 시간이 포함되고, 요금은 폰이 준비된 시점부터 시작된다. 세션을 끝내면 임시 폰과 앱 데이터가 삭제된다. 로그인을 유지하려면 "저장된 폰"으로 띄워야 한다는 뜻이다. (Cloud 개요)

phone-harness cloud login    # 최초 1회, 브라우저에서 승인
phone-harness cloud ls       # 계정의 폰과 진행 중인 세션 확인
phone-harness cloud start    # 기본 안드로이드, 15분
phone-harness cloud stop

클라우드 아이폰은 HTTPS로 제어하기 때문에 맥 OS 버전과 무관하다. 인텔 맥이라 iPhone Mirroring을 못 쓰는 경우에도 이 경로는 열린다. 월 $80이 비싸 보이지만, 중고 아이폰을 사서 상시 켜두는 비용과 전기·관리 공수를 생각하면 숫자가 달라진다.

한계와 보안

기능 목록보다 못 하는 일을 먼저 확인하는 편이 시간을 아낀다.

• 멀티터치 제스처(핀치 줌 등), 카메라, Face ID 조작은 지원하지 않는다.
• DRM이 걸린 영상은 캡처되지 않는다. 넷플릭스 화면을 읽히려는 시도는 처음부터 막힌다.
• 아이폰의 백그라운드 제어는 macOS 비공개 API에 의존한다. 미러링 창이 다른 창에 가려지면 캡처가 흔들린다.
• 잠긴 안드로이드는 직접 풀어야 한다. adb 텍스트 입력은 ASCII만 가능해서 한글은 그대로 타이핑되지 않는다.

마지막 항목은 한국 사용자에게 실제로 아프다. 한글 검색어를 앱에 넣어야 하는 작업이라면, 한글 입력은 클립보드 붙여넣기나 앱 자체의 최근 검색어를 쓰는 쪽으로 우회해야 한다. adb의 input text가 ASCII만 받는 것은 도구의 버그가 아니라 안드로이드 쪽 제약이다.

보안은 더 진지하게 봐야 한다. Phone Harness는 폰에 설치되는 앱이 아니라 내 컴퓨터에서 도는 프로그램이다. 에이전트가 쓴 Python이 내 계정 권한으로 실행되고, 그 코드가 실제 폰의 실제 앱을 건드린다. 결제·송금·삭제가 가능한 앱이 로그인된 폰이라면 위험도 그만큼 크다.

그래서 승인 게이트를 끄면 안 된다. OpenClaw 플러그인은 기본값이 "매 호출 승인"이고, 자동 실행(classifierAutoRun)은 꺼져 있다. 켜면 분류기가 "폰만 건드리는 코드"라고 판단한 스크립트를 묻지 않고 실행하는데, 문서 스스로 이 분류기가 휴리스틱이라 우회될 수 있다고 적는다. 그리고 샌드박스 세션에는 이 도구가 아예 주어지지 않는다. 플러그인이 게이트웨이 안에서 돌기 때문에, 샌드박스 밖인 내 맥에서 스크립트가 실행되기 때문이다.

내가 막혔던 곳

첫 번째 벽은 내 맥이었다. 아이폰 경로를 쓰려고 보니 요구사항이 macOS 15 이상에 Apple silicon 또는 T2였다. 내 장비에서 확인한 값은 이렇다.

$ sw_vers
ProductVersion:  13.7.8          # Ventura, macOS 15 미만

$ sysctl -n machdep.cpu.brand_string
Intel(R) Core(TM) i5-7360U CPU @ 2.30GHz   # T2 칩 없음

$ ls -d "/System/Applications/iPhone Mirroring.app"
No such file or directory        # 미러링 앱 자체가 없음

세 줄이 동시에 걸린다. OS가 낮고, 칩이 T2가 아니고, 미러링 앱이 설치조차 되어 있지 않다. 이 조합에서는 iPhone Mirroring을 켜는 것부터가 불가능하니, Phone Harness 이전에 Apple 쪽에서 막힌 셈이다. 결론은 두 가지였다. 안드로이드 실기기로 가거나, 클라우드 아이폰을 쓰거나.

내 맥에서 직접 확인한 결과다. OS 버전, 칩, 미러링 앱 세 가지가 동시에 걸려 아이폰 경로는 시도조차 할 수 없었다.

위 화면은 실제로 내 맥에서 돌린 점검 결과를 그대로 옮긴 것이다. 세 개의 조건이 동시에 어긋나면 아이폰 경로는 시도조차 할 수 없다.

두 번째 벽은 Python 버전이었다. 이 맥의 기본 python3는 3.9.6인데 Phone Harness는 3.10 이상을 요구한다. uv도 없었다. 이때 시스템 파이썬을 건드리는 대신 uv를 새로 깔고 3.12를 따로 받는 쪽을 택했다. 시스템 파이썬에 직접 패키지를 넣으면 나중에 다른 스크립트가 깨진다. 이 맥에서 Python을 여러 버전으로 쓰는 방법은 Python 가상환경 venv 만들기에 정리해 두었다.

세 번째는 권한이었다. 손쉬운 사용과 화면 기록을 켜고도 캡처가 계속 검게 나왔다. 원인은 터미널을 재시작하지 않은 것이었다. 화면 기록 권한은 앱이 새로 뜰 때 반영된다. 권한을 준 뒤에는 터미널을 완전히 종료했다가 다시 열어야 한다.

네 번째는 승인 창이었다. 스크립트를 길게 쓰면 승인 요청이 아예 오지 않는다. 처음엔 버그인 줄 알았는데, 500자 제한 때문에 긴 스크립트는 승인 화면에 전문을 못 보여줘서 거부되는 구조였다. 지금은 "앱 열고 → 읽고 → 다음 판단"처럼 잘게 끊어서 시킨다. 폰 상태는 호출 사이에 유지되므로 쪼개도 결과는 이어진다. 에이전트를 다루는 기본기는 AI 에이전트란과 Claude Code 설치·사용법에 있다.

참고 자료

• Phone Harness 공식 사이트 (기능, 클라우드, 요금표)
• GitHub — phone-harness (설치, 헬퍼, 지원 범위)
• Phone Harness 문서 (Cloud API, 세션 과금 규칙)
• PyPI — phone-harness 0.3.3 (버전, Python 3.10 이상)
• OpenClaw 통합 README (phone_exec, 승인, 샌드박스 제한)
• Apple — iPhone Mirroring 요구사항 (macOS 15, Apple silicon/T2, iOS 18)
• ScriptByAI — Phone Harness 정리 (헬퍼 표, 한계 정리)

챗봇에 스크린샷을 붙여넣고 "이 오류 왜 나?"라고 물으면 답이 온다. 그런데 같은 이미지를 열 장 넣는 순간 요금이 확 뛰고, 아주 작은 글씨는 못 읽는다. 이미지가 텍스트와 똑같이 취급되는 것 같으면서도 숫자가 다르게 움직이는 이유가 있다.

이 글은 멀티모달 AI가 무엇인지, 이미지·영상이 어떤 단위로 토큰이 되는지, 그리고 그 계산이 실제 요금과 답변 품질을 어떻게 바꾸는지 정리한다.

30초 요약

목차

1. 멀티모달 AI란? 한 문장 정의
2. 텍스트 전용 모델과 무엇이 다른가
3. 이미지는 어떻게 토큰이 되나 (모델별 계산식)
4. 영상·오디오는 숫자가 한 자리 다르다
5. 실제로 써보면 갈리는 지점
6. 멀티모달 AI의 한계
7. 내가 막혔던 곳
8. 참고 자료

이미지는 28×28 픽셀 패치로 잘려 토큰이 된다. 파일 크기가 아니라 픽셀 수가 요금을 정한다.

멀티모달 AI란? 한 문장 정의

Google Cloud 문서는 멀티모달 모델을 "이미지, 영상, 텍스트 등 서로 다른 모달리티의 정보를 처리할 수 있는 머신러닝 모델"로 정의한다. 텍스트를 넣으면 텍스트만 나오는 모델과 달리, 입력과 출력의 종류가 서로 달라도 된다. (Google Cloud — Multimodal AI)

여기서 많이 헷갈리는 지점이 있다. 멀티모달은 모델을 여러 개 붙여놓은 구조가 아니다. 이미지 인코더가 뽑은 특징을 텍스트 토큰과 같은 공간에 넣고, 하나의 트랜스포머가 전부 같이 본다. 그래서 "이미지도 결국 토큰"이라는 말이 나온다. 토큰 개념이 낯설면 토큰(token)이란을 먼저 보면 좋다.

출력 쪽도 넓어졌다. 텍스트와 코드는 기본이고, 이미지 생성, 음성 합성, 영상 생성까지 같은 계열 모델이 처리한다. 다만 입력을 이해하는 능력과 출력을 생성하는 능력은 별개로 봐야 한다. 이미지를 잘 읽는 모델이 이미지를 잘 그리는 것은 아니다.

텍스트 전용 모델과 무엇이 다른가

같은 질문을 텍스트로 할 때와 이미지로 할 때, 모델이 하는 일이 다르다. 텍스트는 이미 토큰으로 잘려 있는 반면, 이미지는 전처리 단계를 한 번 더 거친다.

Anthropic 문서는 이미지를 텍스트보다 앞에 두라고 권한다. 긴 문서를 질문 앞에 두는 것과 같은 이유다. 이미지 뒤에 질문을 붙이는 순서가 인식률에 유리하다. (Anthropic — Vision)

이미지는 어떻게 토큰이 되나 (모델별 계산식)

세 회사 모두 "이미지를 작은 블록으로 나누고, 블록 수만큼 토큰을 센다"는 발상을 공유한다. 블록 크기와 상한이 다를 뿐이다.

출처는 각각 Anthropic Vision, OpenAI Images and vision, Gemini 이미지 이해다.

Anthropic의 계산은 외우기 쉽다. 1000×1000 이미지는 ⌈1000/28⌉ = 36이라 36×36 = 1,296 토큰이다. 1920×1080은 표준 등급에서 1456×819로 줄어 1,560 토큰, 고해상도 등급(Claude 4.7 이후)에서는 원본 그대로 2,691 토큰이 된다. 4K 영상 프레임 한 장은 고해상도에서 4,784 토큰까지 올라간다.

OpenAI는 패치 수에 모델별 배율을 곱한다. GPT-6 Astra는 detail: high에서 최대 변 65,535 px, 패치 예산 2,500, 배율 1.2를 쓴다. 1024×1024는 1,024패치라 ⌈1024×1.2⌉ = 1,229 토큰, 2048×2048은 예산 때문에 1600×1600으로 줄어 3,000 토큰이다. 패치가 30,000개를 넘으면 리사이즈 없이 요청이 거부된다.

Google은 조금 다르게 센다. 양쪽 변이 384 px 이하면 258 토큰으로 끝나고, 그보다 크면 768×768 타일로 나눠 타일마다 258 토큰을 매긴다. 960×540 예시는 타일 6개라 1,548 토큰이 된다.

# 보내기 전에 대략적인 토큰을 미리 재는 용도 (Anthropic 기준)
import math

def claude_image_tokens(w, h, max_edge=1568):
    scale = min(1.0, max_edge / max(w, h))
    w, h = int(w * scale), int(h * scale)
    return math.ceil(w / 28) * math.ceil(h / 28)

for size in [(1000, 1000), (1920, 1080), (3840, 2160)]:
    print(size, claude_image_tokens(*size))
# (1000, 1000) 1296 · (1920, 1080) 1560 · (3840, 2160) 1560

요금으로 바꾸면 차이가 더 분명해진다. Anthropic 문서의 예시를 그대로 인용하면, Claude Haiku 4.5(백만 입력 토큰당 $1, 표준 등급)에서 1000×1000 이미지 1,000장은 약 $1.30이다. Claude Opus 5.5(백만 토큰당 $4, 고해상도 등급)에서는 같은 이미지 1,000장이 약 $5.18, 4K 이미지 1,000장은 약 $19.14다. (같은 문서)

같은 그림도 해상도 설정에 따라 토큰이 두 배 넘게 벌어진다. 보내기 전에 크롭하는 이유다.

영상·오디오는 숫자가 한 자리 다르다

영상은 프레임을 초당 몇 장 뽑느냐로 비용이 결정된다. Gemini 문서 기준으로 기본값은 초당 1프레임이고, 프레임당 258 토큰(저해상도 설정은 66 토큰), 오디오는 초당 32 토큰이 붙는다.

출처는 Gemini 영상 이해다. 10분짜리 고해상도 영상 한 편이면 20만 토큰에 가까운 창을 쓴다. 컨텍스트 윈도우가 1M이어도 영상 몇 편이면 절반이 날아간다는 뜻이다. 창 크기 자체가 궁금하면 컨텍스트 윈도우란에서 자세히 다뤘다.

Gemini 4 Argon부터는 에이전트형 모드가 있어서, 모델이 영상 전체를 훑는 대신 필요한 구간만 골라 본다. 긴 영상에서 토큰을 88%까지 아낀다고 문서는 설명한다. 대신 첫 토큰이 나오는 시간은 느려진다.

실제로 써보면 갈리는 지점

내가 멀티모달을 실제로 쓰는 곳은 세 군데다. 첫째는 오류 화면이다. 터미널 스크린샷을 넣고 "이 에러 로그에서 진짜 원인만 뽑아줘"라고 하면, 텍스트로 옮겨 적는 것보다 빠르고 오타도 없다. 특히 스택트레이스처럼 줄이 긴 출력에서 차이가 크다.

둘째는 표와 차트다. 논문 PDF의 표를 이미지로 잘라 넣으면 열 정렬을 꽤 잘 맞춘다. 다만 단위를 생략한 열이나 각주는 자주 놓친다. 숫자를 인용할 때는 원문을 다시 확인하는 편이 안전하다.

셋째는 UI 상태 판단이다. "이 화면에서 다음에 눌러야 할 버튼이 뭐야" 같은 질문은 잘 맞힌다. 브라우저 자동화처럼 좌표가 필요한 작업은 다르다. Anthropic 문서는 좌표 출력이 근사치라고 명시하고, OpenAI 문서도 좌표가 중요한 작업은 detail: original을 쓰고 원본 좌표로 되돌려 매핑하라고 안내한다.

멀티모달 AI의 한계

가장 자주 부딪히는 벽은 해상도다. Anthropic은 200 px 이하로 작거나 회전된 이미지에서 오독이 생긴다고 적는다. 리사이즈가 걸리면 텍스트가 더 작아지므로, 글자가 중요한 이미지는 미리 자르거나 확대해서 넣어야 한다.

개수 세기도 믿을 일이 아니다. 문서는 물체가 많고 작을수록 개수 추정이 부정확해진다고 못 박는다. 표의 행 개수, 재고 수량, 사람 수처럼 정확한 숫자가 필요한 작업은 모델에게 세게 하면 안 된다.

사람 식별은 아예 거부된다. Anthropic 사용 정책상 이미지 속 사람의 이름을 맞히는 용도로 쓸 수 없다. 얼굴 인식 용도로 멀티모달을 검토하고 있다면 이 지점에서 설계가 달라진다.

내가 막혔던 곳

처음엔 파일 크기가 토큰을 정한다고 생각했다. 그래서 스크린샷을 JPEG로 세게 압축해서 넣었더니 요금은 그대로였고, 글씨만 뭉개져서 답이 나빠졌다. 토큰은 바이트가 아니라 픽셀과 타일로 결정된다. 지금은 압축보다 크롭을 먼저 한다. 필요한 영역만 잘라 넣으면 토큰도 줄고 인식률도 올라간다.

두 번째는 이미지 순서였다. 여러 장을 넣고 "첫 번째 사진"이라고 지칭했는데, 모델이 세는 순서와 내가 생각한 순서가 달랐다. 지금은 각 이미지 앞에 "화면 1:", "화면 2:" 같은 텍스트 라벨을 붙인다. 라벨 하나로 오독이 크게 줄었다.

세 번째는 PDF다. 페이지 30장짜리 문서를 통째로 넣었다가 요청 크기 제한에 걸렸다. Claude API는 이미지 한 장 10MB, 요청 전체 128MB가 한도라서, 토큰보다 바이트가 먼저 막는 경우가 있다. 지금은 페이지를 나눠 넣고 각 요청의 usage를 로그로 남긴다. 모델 계열 전체 그림이 필요하면 LLM이란 무엇인가를 같이 보면 좋다.

참고 자료

• Google Cloud — Multimodal AI (정의, 생성형 AI와의 차이)
• Anthropic — Vision (28×28 패치, 1,568·4,784 토큰 상한, 이미지 요금 예시)
• OpenAI — Images and vision (32×32 패치, 배율 1.2, 30,000 패치 한도)
• Gemini — 이미지 이해 (384 px·768 타일, 258 토큰)
• Gemini — 영상 이해 (1 FPS, 초당 300 토큰, 에이전틱 88% 절감)
• AI 기초 용어 20개 정리 (토큰·임베딩·RAG 한 번에)

모델 스펙 표에서 "컨텍스트 윈도우 1M 토큰"이라는 숫자를 보고 책 한 권을 통째로 넣을 수 있다고 이해하는 경우가 많다. 실제로는 1M을 다 채우면 답의 정확도가 눈에 띄게 떨어지고, 요금도 배로 뛴다.

이 글은 컨텍스트 윈도우가 무엇이고, 무엇이 그 공간을 차지하며, 왜 큰 숫자를 그대로 믿으면 안 되는지를 정리한다.

30초 요약

목차

1. 컨텍스트 윈도우란? 한 문장 정의
2. 무엇이 토큰을 먹는가
3. 모델별 크기 비교 (2026년 11월 기준)
4. 크다고 좋은 게 아닌 이유 — context rot
5. 한도를 넘으면 실제로 무슨 일이 나나
6. 내가 쓰는 컨텍스트 관리법
7. 내가 막혔던 곳
8. 참고 자료

1,048,576토큰을 다 채우면 회수 정확도가 떨어진다. 창의 크기와 실제 성능은 다른 문제다.

컨텍스트 윈도우란? 한 문장 정의

Anthropic 문서는 컨텍스트 윈도우를 "모델이 응답을 생성할 때 참조할 수 있는 모든 텍스트, 응답 자체를 포함한 것"으로 정의한다. 학습 데이터 전체와는 다른 개념이고, 문서 표현을 빌리면 모델의 작업 기억이다. (Anthropic — Context windows)

내가 쓰는 비유는 책상이다. 책장에 책이 아무리 많아도(학습 데이터), 지금 책상 위에 펼쳐둔 것만 보면서 일한다. 책상이 넓으면 자료를 많이 올려둘 수 있지만, 넓다고 해서 눈이 좋아지는 건 아니다.

단위는 토큰이다. 영어는 대략 단어 하나가 1~1.5토큰, 한국어는 같은 내용에 더 많은 토큰이 든다. 토큰 자체가 낯설면 토큰(token)이란을 먼저 보면 좋다.

무엇이 토큰을 먹는가

처음엔 "내가 쓴 질문 + 모델 답변"만 세면 된다고 생각했다. 실제 청구서와 usage 필드를 열어보면 항목이 훨씬 많다.

Anthropic 문서는 프롬프트 캐싱을 써도 캐시된 앞부분이 창에서 사라지지는 않는다고 못 박는다. 캐싱은 무엇을 지불하는지를 바꾸는 장치이지, 공간을 비워주는 장치가 아니다. (같은 문서)

실무에서 가장 많이 새는 곳은 툴 결과다. 파일 30개를 읽으면 그 내용이 전부 대화에 남는다. 다음 턴에도, 그다음 턴에도. 에이전트를 오래 돌릴수록 비용이 계단처럼 뛰는 이유가 여기 있다.

모델별 크기 비교 (2026년 11월 기준)

숫자는 공식 문서에서 직접 확인했다. 같은 회사 모델이라도 세대에 따라 두 배 이상 차이가 나니, 표를 볼 때 모델명까지 같이 봐야 한다.

출처는 각각 Anthropic Context windows, OpenAI GPT-6 Astra, Gemini 4 Argon다.

표를 읽을 때 걸리는 지점이 두 개 있다. GPT-6 Astra는 창이 1,050,000인데 최대 입력이 922,000이다. 나머지 128,000은 출력 몫으로 비워둔 것이다. Gemini 4 Argon은 입력과 출력을 합쳐 1,048,576이라, 입력을 꽉 채우면 답변할 공간이 남지 않는다.

질문과 답변만 세면 절반이 빠진다. 툴 결과와 사고 토큰까지 같은 창에 쌓인다.

크다고 좋은 게 아닌 이유 — context rot

Anthropic 엔지니어링 글에는 이 문장이 있다. 컨텍스트 창의 토큰 수가 늘어날수록, 모델이 그 안에서 정보를 정확히 회수하는 능력은 떨어진다. 이 현상을 context rot이라고 부른다. (Anthropic — Effective context engineering for AI agents)

원인으로 설명하는 건 트랜스포머의 구조다. n개 토큰이 서로를 참조하려면 n²개의 관계를 계산해야 한다. 창이 길어질수록 각 관계에 쓸 주의(attention)가 얇게 퍼진다. 사람의 작업 기억 용량이 유한한 것과 비슷하게, 모델에도 "주의 예산"이 있다는 표현을 쓴다.

논문 쪽 근거도 있다. RULER 벤치마크는 17개 장문맥 모델을 13개 과제로 평가했다. 바늘 찾기(needle-in-a-haystack) 시험에서는 거의 만점이던 모델들이, 과제가 복잡해지고 길이가 늘어나면 성적이 크게 떨어졌다. 32K 이상을 광고한 모델 중 절반만이 32K 길이에서 만족할 성적을 유지했다. (RULER, arXiv:2404.06654)

그래서 나는 스펙 숫자를 이렇게 읽는다. 1M은 "저장 가능 한도"이고, 실제로 잘 쓰는 구간은 그보다 훨씬 앞이다. 긴 문서를 넣을 때는 앞쪽에 핵심을 몰아넣고, 중간에 묻히는 구간을 만들지 않는 편이 낫다.

한도를 넘으면 실제로 무슨 일이 나나

증상은 두 갈래다. 입력만으로 이미 창을 넘으면 API가 400 invalid_request_error("prompt is too long")를 돌려준다. 이건 모든 모델에서 동일하다.

입력은 들어갔는데 생성 도중에 한도에 닿는 경우는 다르게 동작한다. Claude 4.5 이후 모델은 요청을 받아주고, 생성이 한도에 닿으면 stop_reason: "model_context_window_exceeded"로 멈춘다. 이전 모델은 아예 검증 오류를 낸다. (Anthropic — Context window overflow behavior)

resp = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=8192,
    messages=[{"role": "user", "content": long_text}],
)
if resp.stop_reason == "model_context_window_exceeded":
    # 답이 중간에 끊긴 상태 — 이어붙이지 말고 입력을 줄여 재시도
    raise RuntimeError(f"context overflow: {resp.usage.input_tokens} tokens")

여기서 많이 하는 실수가 잘린 답변을 정상 답변으로 취급하는 것이다. 문장이 자연스럽게 끝나도 stop_reason이 end_turn이 아니면 완결된 답이 아니다. 비용을 아끼려고 max_tokens를 크게 잡아두면, 정작 창 한도에 먼저 부딪혀 잘리는 일이 생긴다.

내가 쓰는 컨텍스트 관리법

큰 창을 믿고 밀어 넣는 방식은 오래 못 간다. 지금 쓰는 방식은 네 가지다.

첫째, 툴 결과는 요약해서 넣는다. 파일을 읽고 그대로 대화에 남기지 않는다. 필요한 줄만 인용하고 나머지는 버린다. 같은 파일을 두 번 읽지 않도록 읽은 목록을 따로 적어둔다.

둘째, 대화가 길어지면 앞부분을 접는다. Anthropic은 서버 측 압축(compaction)을 제공하고, 직접 하려면 앞 턴을 요약해 시스템 프롬프트에 넣는 방식이 된다. 요약에는 결정 사항과 아직 안 끝난 일만 남긴다.

셋째, 출력 공간을 먼저 계산한다. 창이 200k면 200k를 입력에 쓰면 안 된다. 최대 출력 128k를 감안해 입력 예산을 잡는다.

넷째, 캐싱은 비용 절감용으로만 본다. 앞부분이 안 바뀌는 구조로 프롬프트를 짜면 캐시 적중률이 올라간다. 다만 창을 비워주지는 않으니, 캐시를 믿고 대화를 방치하면 안 된다.

관련 글: 프롬프트 작성법 — 좋은 예·나쁜 예 10쌍에서 무엇을 넣고 무엇을 뺄지 판단하는 기준을 다뤘다. RAG가 뭐야 (검색증강생성)는 창을 늘리는 대신 필요한 것만 검색해 넣는 접근이다.

내가 막혔던 곳

처음엔 컨텍스트 윈도우와 max_tokens를 같은 것으로 착각했다. max_tokens를 100k로 올려두면 긴 답이 나올 거라고 기대했는데, 실제로는 창 한도에서 먼저 잘렸다. 두 값은 별개이고, 출력은 언제나 창의 일부다.

두 번째는 한국어 토큰 수를 과소평가한 것이다. 같은 내용을 영어로 쓸 때와 한국어로 쓸 때 토큰 수가 꽤 벌어진다. 문서를 넣기 전에 토큰 카운팅 API로 재보는 습관을 들인 뒤로 "넣을 수 있겠지"로 시작하는 일이 없어졌다.

세 번째는 이미지다. PDF 200장을 한 요청에 넣었다가 요청 크기 제한에 걸렸다. 토큰보다 바이트 한도가 먼저 막는 경우가 있다. 지금은 문서를 나눠 넣고, 각 요청의 usage를 로그로 남긴다.

이 글의 숫자도 전부 공식 문서를 직접 열어 확인했다. 모델 이름이 바뀌면 창 크기도 같이 바뀌기 때문에, 블로그 글의 표보다 각 회사 문서를 우선하는 게 안전하다. 모델 계열 전체 그림이 필요하면 LLM이란 무엇인가를 같이 보면 좋다.

참고 자료

• Anthropic — Context windows (정의, 모델별 크기, 초과 동작)
• Anthropic — Effective context engineering for AI agents (context rot, 주의 예산)
• OpenAI — GPT-6 Astra 모델 문서 (1,050,000 창, 922,000 최대 입력)
• Gemini 4 Argon 모델 문서 (1,048,576 통합 한도)
• RULER — What's the Real Context Size of Your Long-Context Language Models? (17개 모델, 13개 과제)
• AI 기초 용어 20개 정리 (토큰·임베딩·RAG 한 번에)