강남거북이개발자

Docker는 "내 맥에서는 되는데 서버에서는 안 돼요"라는 말을 줄이려고 만든 도구다. 실행 환경을 이미지로 묶어두면 노트북과 서버가 같은 컨테이너를 띄운다. 이 글은 Docker를 처음 켜는 사람이 설치하고, 컨테이너 하나 띄우고, Dockerfile과 Compose까지 가는 순서를 다룬다.

30초 요약

목차

1. Docker가 뭔가요 — 가상머신과 다른 점
2. Docker Desktop 설치 — macOS에서 세 단계
3. 첫 컨테이너 실행 — hello-world가 하는 일
4. 자주 쓰는 명령 — 이미지와 컨테이너 구분
5. 포트와 볼륨 — 컨테이너를 지워도 남는 것
6. Dockerfile로 내 이미지 만들기
7. Docker Compose로 두 개 같이 띄우기
8. 내가 막혔던 곳
9. 참고 자료

Docker가 뭔가요 — 가상머신과 다른 점

Docker는 애플리케이션을 컨테이너라는 격리된 환경에 담아 실행하는 플랫폼이다. 공식 문서는 컨테이너가 가볍고 실행에 필요한 것을 안에 다 담기 때문에, 호스트에 무엇이 설치돼 있는지에 기대지 않아도 된다고 설명한다 (Docker 개요).

구조는 클라이언트와 데몬으로 나뉜다. 내가 터미널에서 docker를 칠 때 그 명령은 Docker 데몬에 REST API로 전달되고, 데몬이 이미지를 당기고 컨테이너를 만든다. 맥에서는 Docker Desktop이 리눅스 VM을 띄우고 그 안에서 데몬을 돌리는 식이다.

가상머신과 자주 비교되는데, 차이는 부팅 단위에 있다.

그래서 맥에서 리눅스 바이너리를 돌리는 용도로는 컨테이너가 맞고, 윈도우 데스크톱 앱을 띄우려면 가상머신이 맞다. 이 구분이 잡히면 뒤에 나오는 명령이 훨씬 덜 헷갈린다.

Docker Desktop 설치 — macOS에서 세 단계

설치 파일은 칩에 따라 다르다. 애플 실리콘은 arm64, 인텔 맥은 amd64 빌드를 받는다 (설치 문서).

1. dmg를 열고 Docker 아이콘을 Applications 폴더로 끌어다 놓는다.
2. Docker.app을 실행하고 구독 약관 화면에서 Accept를 누른다.
3. 트레이 아이콘에 고래가 뜨고 docker version이 응답하면 준비 끝이다.

요구 사항은 macOS 현재 버전과 그 이전 두 개 메이저 버전, RAM 4GB 이상이다. 애플 실리콘에서 인텔 바이너리를 돌리는 선택 도구를 쓰려면 Rosetta 2를 설치한다. 최근 버전은 CLI를 $HOME/.docker/bin에 넣고 PATH에 추가하며, 기본 도커 소켓은 만들지 않는다. 이 부분은 Settings > Advanced에서 바꿀 수 있다.

라이선스는 회사 규모를 확인하고 쓰는 게 좋다. 직원 250명 이상이거나 연매출 1,000만 달러 이상인 기업의 상업적 사용은 유료 구독이 필요하다. 정부 기관도 유료다. 개인 학습과 소규모 사업장은 무료 범위에 들어간다 (Docker Desktop 약관).

첫 컨테이너 실행 — hello-world가 하는 일

설치 확인은 보통 이 한 줄로 한다.

docker run hello-world

이 명령은 로컬에 이미지가 없으면 Docker Hub에서 당겨오고, 컨테이너를 만들어 실행한 뒤 로그를 출력하고 종료한다. docker run 문서에도 이미지가 필요하면 pull하고 컨테이너를 시작한다고 적혀 있다 (docker run).

조금 더 만져보고 싶으면 우분투를 대화형으로 띄운다.

docker run -it --rm ubuntu:24.04 bash
# 컨테이너 안에서
cat /etc/os-release
exit

-it는 키보드 입력을 연결하고, --rm은 끝날 때 컨테이너를 지우라는 뜻이다. 여기서 exit를 하면 컨테이너가 사라진다. docker ps -a로 확인하면 --rm을 안 붙인 컨테이너만 목록에 남아 있다.

자주 쓰는 명령 — 이미지와 컨테이너 구분

처음에 가장 많이 헷갈리는 건 이미지와 컨테이너를 같은 것으로 보는 것이다. 이미지는 변하지 않는 템플릿이고, 컨테이너는 그 템플릿에서 만들어진 실행 인스턴스다. 같은 이미지로 컨테이너를 세 개 띄우면 서로 다른 프로세스 세 개가 생긴다.

docker exec는 이미 실행 중인 컨테이너에 셸을 하나 더 붙이는 명령이다. docker run으로 bash를 띄우는 것과 다르다. 실행 중인 서비스 설정을 확인할 때는 exec를 쓴다.

이미지 태그를 생략하면 latest가 붙는다. 운영에 쓸 이미지는 nginx:1.29처럼 버전을 명시하는 편이 안전하다. 태그가 바뀌면 같은 이름으로 다른 이미지가 받아질 수 있기 때문이다.

포트와 볼륨 — 컨테이너를 지워도 남는 것

컨테이너 안의 포트는 기본적으로 밖에서 보이지 않는다. -p로 연결해야 한다.

docker run -d --name web -p 8080:80 nginx
curl -I http://localhost:8080

8080:80은 호스트 8080을 컨테이너 80에 매핑한다는 뜻이다. 순서를 반대로 넣으면 접속이 안 되는데, 이건 뒤에서 다시 얘기한다.

데이터는 더 조심해야 한다. 컨테이너의 쓰기 레이어는 컨테이너와 함께 사라진다. 공식 문서는 볼륨을 컨테이너가 만든 데이터를 보존하는 기본 수단으로 설명하고, 볼륨의 내용은 컨테이너 수명과 별개로 존재한다고 적는다 (볼륨).

docker volume create pgdata
docker run -d --name db -e POSTGRES_PASSWORD=devpass \
  -v pgdata:/var/lib/postgresql/data postgres:17
docker volume ls

개발 중에는 바인드 마운트를 더 자주 쓴다. 내 폴더를 컨테이너 안에 그대로 붙여서, 코드를 고치면 컨테이너 안 파일도 같이 바뀐다.

docker run --rm -it -v "$(pwd)":/app -w /app python:3.12-slim bash

Dockerfile로 내 이미지 만들기

직접 만든 앱을 컨테이너로 돌리려면 Dockerfile을 쓴다. 파이썬 앱 기준으로 최소 구성은 이렇다.

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "app.py"]

빌드는 태그를 붙여서 실행한다.

docker build -t myapp:0.1 .
docker run --rm -p 8000:8000 myapp:0.1

여기서 순서가 중요하다. requirements.txt를 먼저 복사하고 설치한 다음에 나머지 코드를 복사했다. 코드만 바뀌면 마지막 COPY . . 레이어부터 다시 만들면 되고, 의존성 설치 레이어는 캐시로 남는다. 이 순서를 반대로 쓰면 코드 한 줄 고칠 때마다 pip 설치를 다시 한다.

.dockerignore도 같이 두는 게 좋다. .git, __pycache__, .venv를 넣어두면 빌드 문맥이 가벼워진다. 파이썬 가상환경을 컨테이너 안에 또 넣을 이유는 없으니 venv 글에서 만든 .venv는 꼭 제외한다.

이미지 크기를 줄이고 싶으면 베이스 이미지를 -slim이나 -alpine으로 바꾼다. 다만 alpine은 glibc 대신 musl을 쓰기 때문에, 미리 컴파일된 휠이 없는 패키지는 빌드가 깨질 수 있다. 처음에는 slim으로 시작하고 필요할 때 바꾸는 편이 낫다.

Docker Compose로 두 개 같이 띄우기

서비스가 두 개를 넘어가면 docker run을 길게 치는 대신 Compose를 쓴다. 공식 문서는 Compose를 여러 컨테이너 앱을 YAML 하나로 정의하고 한 명령으로 띄우는 도구로 설명한다 (Docker Compose).

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - REDIS_HOST=redis
    depends_on:
      - redis
  redis:
    image: redis:7

docker compose up -d
docker compose ps
docker compose logs -f web
docker compose down

Compose 안에서는 서비스 이름이 그대로 호스트 이름이 된다. 그래서 코드에서 localhost:6379 대신 redis:6379로 접속한다. 이 한 줄 때문에 로컬과 배포 환경의 설정 차이가 줄어든다.

docker compose down은 컨테이너와 네트워크를 지우지만 볼륨은 남긴다. 볼륨까지 지우려면 docker compose down -v를 쓴다. 이 차이를 모르면 "DB를 새로 시작했는데 예전 데이터가 그대로" 같은 상황이 생긴다.

내가 막혔던 곳

첫 번째는 포트 순서였다. -p 80:8080으로 띄워놓고 브라우저에서 8080을 열어놓고 왜 안 되냐고 한참을 봤다. 앞이 내 맥, 뒤가 컨테이너라는 걸 외우고 나서야 정리가 됐다. 지금은 -p 호스트:컨테이너를 소리 내어 읽으면서 친다.

두 번째는 데이터였다. --rm으로 컨테이너를 정리하는 습관을 들인 뒤, 볼륨 없이 띄운 PostgreSQL에 테스트 데이터를 넣고 다음 날 전부 날렸다. 컨테이너를 지우면 쓰기 레이어가 같이 사라진다는 걸 문서로만 알고 실제로 겪지 않아서 생긴 일이다. 그 뒤로는 DB는 무조건 볼륨을 먼저 만든다.

세 번째는 맥을 재부팅한 뒤였다. Cannot connect to the Docker daemon at unix:///var/run/docker.sock이 뜨면 Docker Desktop이 꺼져 있는 경우가 대부분이다. 트레이에서 Docker.app을 실행하고 docker info가 응답하는지 먼저 확인한다. 이 오류를 보고 이미지나 컨테이너 문제부터 의심하면 시간이 더 걸린다.

마지막으로 애플 실리콘에서 인텔 이미지를 받을 때 나오는 platform 경고다. 급할 때는 --platform linux/amd64로 맞춰서 띄우면 되지만, 빌드까지 필요하면 멀티 아키텍처 이미지를 만드는 쪽이 오래 간다. 나는 로컬 테스트에서만 platform 옵션을 쓰고 있다.

참고 자료

• Docker Desktop for Mac 설치 — 다운로드 링크, macOS·RAM 요구 사항, 설치 절차
• Docker 개요 — 컨테이너 개념과 클라이언트·데몬 구조
• docker run 레퍼런스 — 옵션 전체와 이미지 pull 동작
• 볼륨 — 볼륨과 바인드 마운트의 차이, 데이터 수명
• Docker Compose — 다중 컨테이너 정의와 실행
• Docker Desktop 릴리스 노트 — 4.99.0(2026-11-09), Engine 29.9.3, Compose v5.7.0
• Mac 개발환경 세팅 — Homebrew와 zsh를 먼저 잡아두면 설치가 편하다
• Python 가상환경 venv 만들기 — 컨테이너와 비교해서 보면 이해가 빠르다
• git 기초 사용법 — Dockerfile과 compose.yaml도 결국 버전 관리 대상이다

Opus 5.5를 쓰면서 effort를 high로 두고 있었는데, Anthropic이 직접 운영하는 기술 블로그 claude.dev를 읽고 기본값을 medium으로 내렸다. 결론부터 말하면 대부분의 작업에서 medium이 비용과 품질의 균형점이고, high는 "검증이 필요한 작업"에만 쓰는 게 맞다.

이 글은 claude.dev에 어떤 글이 있는지, Opus 5.5의 effort 단계가 무엇인지, 그리고 왜 medium을 기본으로 두는지 정리한 것이다. 기준은 2026년 11월 14일 공개된 글들이고, 수치는 모두 원문 링크를 달았다.

30초 요약

Opus 5.5의 기본값은 medium이다. claude.dev 공개 측정 기준으로 단계별 비용과 성능 차이를 정리한 이미지.

목차

1. claude.dev란? — Anthropic이 직접 쓰는 기술 블로그
2. Opus 5.5 effort란 — 한 턴에 얼마나 생각할지 정하는 손잡이
3. effort 4단계 — low·medium·high·xhigh와 max
4. 왜 medium이 기본값인가 — Opus 5와 달라진 지점
5. Claude Code에서 /effort 쓰는 법
6. effort를 올릴까, 모델을 올릴까 — 비용 계산
7. 내가 막혔던 곳 — high를 그대로 옮겼다가 토큰만 늘린 일
8. 상황별 추천 세팅
9. 참고 자료

claude.dev란? — Anthropic이 직접 쓰는 기술 블로그

claude.dev는 Anthropic이 Claude로 개발하는 사람들을 위해 운영하는 기술 블로그다. 첫 화면 설명이 "technical writing for people building with Claude"다. 공식 문서(docs)와 역할이 다르다. 문서는 파라미터와 제약을 알려주고, claude.dev는 "이 설정으로 실제 작업을 돌려봤더니 이렇게 됐다"를 숫자와 함께 보여준다.

2026년 11월 기준으로 올라와 있는 글 중 내가 먼저 읽은 것들이다.

• 2026-11-09 Which Claude model should you build with? Fable, Opus, Sonnet, or Haiku — 모델 선택 기준과 기본 effort
• 2026-11-09 Safely scaling multi-agent teams with Claude Fable 5.2 — 여러 에이전트를 돌릴 때의 통제
• 2026-10-15 How the Claude Code team does code review — 코드 리뷰 운영 방식
• 2026-09-25 Using Claude Code: Spending your effort — effort가 결과를 어떻게 바꾸는지
• 2026-09-25 What a task costs on Opus 5.5 — 작업 한 건의 실제 청구서 구조

claude.dev 첫 화면. 모델 선택, effort, 비용, 코드 리뷰 글이 올라와 있다.

claude.dev 첫 화면. 모델 선택, effort, 비용, 코드 리뷰처럼 Claude Code를 쓰는 사람이 매주 부딪히는 주제가 올라온다.

읽어보면 공통점이 있다. "모델을 올리기 전에 effort를 먼저 조절하라"는 말이 거의 모든 글에 나온다. 토큰 단가를 바꾸는 것보다 작업당 토큰 사용량을 바꾸는 게 먼저라는 뜻이다.

Opus 5.5 effort란 — 한 턴에 얼마나 생각할지 정하는 손잡이

effort는 모델에게 "이 작업에 컴퓨트를 얼마나 쓸 생각인지" 알려주는 값이다. claude.dev의 비유를 빌리면 이렇다. 누가 같은 일을 12시간 안에 해달라고 하면 끝까지 붙잡고 최선을 다할 것이고, 1시간 안에 해달라고 하면 일단 돌아가는 걸 내놓고 거기서 피드백을 받는 쪽을 택한다.

effort를 올리면 모델이 스스로 판단하는 범위가 넓어진다. 코드를 더 읽고, 테스트를 더 만들고, 엣지케이스를 더 확인한다. claude.dev의 표현으로는 "검증과 엣지케이스 테스트에 컴퓨트를 더 쓰는" 방향이다.

중요한 건 effort가 지식이나 실력을 늘려주지는 않는다는 점이다. 모델이 모르는 도메인 규칙을 effort로 알게 되지는 않는다. 그건 모델을 올려야 한다. effort는 같은 모델이 같은 지식을 더 꼼꼼하게 쓰게 만드는 손잡이다.

effort 4단계 — low·medium·high·xhigh와 max

Opus 5.5는 low, medium, high, xhigh 네 단계를 쓰고, 한 세션에 한해 max를 쓸 수 있다. claude.dev가 정리한 기준은 이렇다.

effort 단계별 쓰임과, 결과가 부족할 때 올리는 순서. 기본은 medium, 검증이 필요한 작업만 high 이상.

시간 예시는 claude.dev가 Terminal-Bench 3.0 과제로 공개한 값이다.

같은 과제에서 단계 차이가 결과를 갈랐다는 사례도 같이 공개됐다. HTML 새니타이저를 만드는 과제에서 Fable 5.1은 low에서 5번 중 1번 성공했고 xhigh에서는 5번 모두 성공했다. low 시도는 2분, xhigh 시도는 33분이 걸렸다. Opus 5.5도 저장 엔진 버그 수정 과제에서 low 0/5, xhigh 4/5였고, 선형계획법 솔버 과제에서는 low 0/5, high 5/5였다.

여기서 읽어야 할 건 "그러니 항상 높여야 한다"가 아니다. 엣지케이스가 숨은 작업에서만 차이가 크다는 뜻이다. 매일 하는 기능 구현에는 그만큼의 엣지케이스가 없다.

왜 medium이 기본값인가 — Opus 5와 달라진 지점

Opus 5의 Claude Code 기본값은 high였고, Opus 5.5는 medium이다. 그런데 여기서 많이들 헷갈린다. 같은 이름의 단계가 같은 양의 사고를 뜻하지 않는다.

claude.dev는 이렇게 쓴다. 같은 레벨에서 Opus 5.5는 Opus 5보다 턴당 더 많이 생각하고, 그 차이는 xhigh와 max에서 가장 크다. 그래서 "Opus 5에서 쓰던 high를 5.5에도 그대로 들고 오면 안 된다"고 못 박는다. 5.5에서는 medium에서 시작하라는 뜻이다.

성능과 비용은 이렇게 갈린다. SWE-bench Pro 기준으로 medium은 high보다 약 2.5점 낮은 대신 비용이 high의 약 70%다. low는 약 8점 낮고 비용은 1/3이다. xhigh는 high보다 약 1.4점 높은데 비용이 2.5배다.

정리하면 이렇다. medium에서 high로 올려서 얻는 2.5점을 사려면 30%를 더 내야 하고, 그 위로 더 올리면 점수는 조금 오르는데 값은 두 배 넘게 뛴다. 일상 작업에서 2.5점이 결과를 바꾸는 경우는 드물다. 그래서 기본값이 medium이다.

참고: 이 수치는 claude.dev가 공개한 자체 측정값이다. 내 작업이 같은 분포라고 볼 수는 없으니, /usage로 자기 세션을 한 번 재보는 게 정확하다.

Claude Code에서 /effort 쓰는 법

Claude Code에서는 슬래시 명령으로 바꾼다. 작업 도중에 바꿔도 되고, 바꾼 값은 다음 요청부터 적용된다.

/effort            # 값을 지정하지 않으면 현재 단계 표시/effort status     # 현재 effort 확인/effort medium     # medium으로 변경 (low, high, xhigh, max도 같은 방식)/usage             # 세션 토큰·캐시·비용 확인

API로 직접 호출할 때는 output_config.effort를 쓴다. 2026년 10월 21일 이후로는 temperature·top_p·top_k를 보내면 400이 떨어지니, 세기 조절은 effort로 하는 쪽이 맞다. 이 변경은 Claude API 사용법 글에서 따로 정리해뒀다.

캐시는 결제 방식에 따라 다르게 동작한다. Opus 5.5에서 API 키나 Claude 구독으로 쓰면 effort를 바꿔도 캐시가 유지된다. 어려운 단계만 high로 올렸다가 다시 medium으로 내리는 식이 가능하다는 뜻이다. 반대로 Amazon Bedrock, Google Cloud의 Agent Platform, Claude 앱 게이트웨이를 거치면 effort를 바꿀 때 캐시된 대화가 지워지고, 다음 요청이 전체를 다시 쓰는 값(cache write)으로 청구된다.

Opus 5.5는 thinking이 항상 켜져 있다. 따로 켜고 끄는 설정이 없으니, 사고량은 effort로만 조절한다고 보면 된다.

effort를 올릴까, 모델을 올릴까 — 비용 계산

claude.dev가 제시하는 순서는 명확하다. 결과가 부족할 때 이 순서대로 올린다.

1. 모델이 스스로 검증할 수단을 준다. 테스트, 빌드, 엔드포인트를 호출하는 스크립트가 여기 해당한다.
2. 그래도 부족하면 effort를 한 단계 올린다.
3. 그래도 부족하면 모델을 올린다. 이때는 이전 모델에서 쓰던 단계보다 낮은 effort에서 시작한다.

1번을 먼저 하라는 이유가 있다. 테스트 한 번 돌리는 비용은 턴 한 번과 그 출력이다. effort를 올리면 모든 턴의 사고량이 같이 늘어난다. 검증 수단을 붙이는 쪽이 싸다.

모델을 올리는 판단 기준도 숫자로 나와 있다. 어려운 작업에서 Opus 5.5를 high 위로 더 올리는 대신 Fable 5.2를 낮은 effort로 쓰는 편이 나은 경우가 있다. Fable 5.2는 $8/$40이고 Opus 5.5는 $4/$20이다. 단가만 보면 두 배지만, 작업당 비용으로 보면 캐시 읽기 비중이 큰 긴 작업에서는 격차가 줄어든다.

비용 계산 — medium이 실제로 싸게 끝나는 이유

Opus 5.5의 API 가격은 입력 $4, 출력 $20, 캐시 읽기 $0.20(백만 토큰 기준)이다. 여기서 청구서를 흔드는 건 출력 토큰이다. 출력은 캐시 읽기의 100배 가격이고, thinking도 출력으로 청구된다.

claude.dev의 계산 예시를 보면 이렇다. high가 작업 전체에 thinking 토큰 20K를 더 쓴다면 Opus 5.5 기준 $0.40이다. 캐시 100K를 유지한 채 10턴을 도는 재시도 루프도 출력 10K를 포함해 비슷한 금액이 나온다. 그래서 "high가 재시도를 한 번 줄여준다면 본전이고, medium으로도 한 번에 끝났을 작업이었다면 그냥 버린 돈"이 된다.

턴 수 자체도 비용이다. 매 턴이 지금까지의 대화를 다시 보내기 때문이다. 20K로 시작해 120K까지 커지는 작업을 40턴 돌면 입력 토큰이 280만 개로 계산된다. 대화가 120K를 넘지 않았는데도 그렇다. 이 구조는 컨텍스트 윈도우란 글에서 정리한 것과 같은 이유다.

그래서 실무에서는 이렇게 굴린다.

• medium으로 먼저 끝내본다. 대부분 여기서 끝난다.
• 실패하면 검증 수단을 붙인다. 테스트가 없으면 medium은 "요청받은 한 겹"만 고치고 끝낸다.
• 그래도 안 되면 high로 한 번만 올린다. 그 단계는 문제 지점에만 쓰고 다시 내린다.
• 무인으로 오래 돌리는 작업만 xhigh나 max로 간다.

내가 막혔던 곳 — high를 그대로 옮겼다가 토큰만 늘린 일

Opus 5에서 Opus 5.5로 넘어올 때 설정을 그대로 복사했다. 모델만 바꾸고 effort는 high로 둔 채였다. 결과는 나쁘지 않았는데, 같은 작업의 출력 토큰이 눈에 띄게 늘었다. claude.dev를 읽고 나서 이유를 알았다. 5.5는 high가 원래 5의 high보다 무거운 자리였고, 5.5의 high는 사실상 이전 세대의 그 위 단계에 가까웠다.

두 번째로 헷갈렸던 건 "medium이 실패하는 모습"이었다. 필드 이름을 바꾸는 작업이었다고 치자. medium은 핸들러를 고치고, 핸들러 테스트까지 통과시켰다. 그런데 클라이언트는 아직 옛 필드를 보내고 있었다. 모델이 시킨 일은 다 했지만, 호출부를 더 읽지 않은 것이다. 처음엔 "medium이 부족하다"고 판단하고 high로 올렸는데, 실제로는 클라이언트까지 지나가는 테스트가 없어서 생긴 문제였다. 테스트를 하나 추가하니 medium에서도 같은 실수를 잡았다.

그래서 지금은 순서를 이렇게 둔다. 모델이나 effort를 의심하기 전에, 이 작업을 모델이 스스로 확인할 방법이 있는지 먼저 본다. 없으면 그걸 먼저 만든다.

상황별 추천 세팅

claude.dev의 기준을 내 작업에 맞춰 정리한 표다. 기본은 Opus 5.5, medium이다.

처음 Claude Code를 켰다면 기본값을 건드리지 말고 medium으로 시작하는 걸 권한다. 프롬프트를 다듬는 쪽이 effort를 올리는 것보다 효과가 큰 경우도 많다. 그 얘기는 프롬프트 작성법 글에 정리해뒀다.

참고 자료

• claude.dev — Anthropic 기술 블로그
• Using Claude Code: Spending your effort — effort 개념과 단계별 실험
• What a task costs on Opus 5.5 — 작업당 비용과 캐시 구조
• Which Claude model should you build with? — 모델 선택과 기본 effort
• Optimizing for cost and intelligence — 공식 비용·지능 문서
• Model configuration (Claude Code) — /model, /effort 동작

VSCode는 설치하면 바로 쓸 수 있지만, 기본값 그대로 쓰면 손이 계속 마우스로 간다. 파일을 열 때마다 탐색기에서 폴더를 펼치고, 같은 단어를 하나씩 고치고, 저장할 때마다 정렬을 손으로 맞추는 시간이 하루에 몇십 분씩 쌓인다.

이 글은 내가 맥에서 VSCode를 쓰면서 실제로 손에 붙인 단축키와 settings.json 항목만 골라 정리한 것이다. 기준 버전은 2026년 11월 4일 배포된 안정판 1.145.3이고, 단축키 표기는 macOS 키보드 기준이다 (릴리스 노트).

30초 요약

목차

1. 단축키를 외우기 전에 확인할 곳
2. 파일 이동 단축키 — ⌘P와 ⌃Tab
3. 편집 단축키 — 접기·줄바꿈·찾기
4. 멀티 커서 단축키 — 같은 단어를 한 번에
5. 설정은 settings.json으로 여는 편이 빠르다
6. 내가 쓰는 settings.json 8줄
7. 저장할 때 자동 정리 — formatOnSave가 안 먹는 이유
8. 내가 막혔던 곳
9. 참고 자료

단축키를 외우기 전에 확인할 곳

VSCode 단축키는 외우는 대상이 아니라 찾아 쓰는 대상이다. 키보드 단축키 편집기를 열면 명령 이름과 현재 키가 같이 나오고, 검색창에 명령 이름이나 키 조합을 넣어 바로 걸러낼 수 있다. 여는 방법은 File > Preferences > Keyboard Shortcuts 또는 명령 팔레트(⇧⌘P)에서 Preferences: Open Keyboard Shortcuts다. 단축키는 ⌘K ⌘S다.

인쇄해서 옆에 두고 싶으면 Help > Keyboard Shortcut Reference를 연다. 플랫폼별 PDF로 내려받을 수 있어서, 나는 맥용을 아이패드에 넣어두고 첫 달에만 봤다.

키보드 배열을 바꿔 쓰면 표기가 달라진다. 독일어 배열에서 ⌘\가 Ctrl+Shift+Alt+Cmd+7처럼 보이는 식이다. 화면에 뜬 키가 안 먹으면 배열부터 확인하는 게 순서다.

기존에 쓰던 에디터가 있다면 키맵 확장을 쓰는 쪽이 빠르다. File > Preferences > Migrate Keyboard Shortcuts from... 메뉴에서 Sublime Text나 Vim 같은 키맵을 고를 수 있다. 나는 Vim 확장을 쓰지 않지만, 회사 동료가 IntelliJ 키맵을 쓰는 걸 보고 이 메뉴의 존재를 알았다.

파일 이동 단축키 — ⌘P와 ⌃Tab

파일을 열 때 탐색기를 펼치는 습관을 끊으면 속도가 바로 달라진다. ⌘P를 누르고 파일 이름 일부만 치면 된다. 경로를 몰라도 되고, 폴더가 깊어도 상관없다.

⌃-와 ⌃⇧-는 같은 파일 안에서 왔다 갔다 할 때 특히 유용하다. 정의를 확인하고 원래 자리로 돌아오는 동작이 마우스 없이 끝난다.

브레드크럼은 기본으로 켜져 있다. 파일 경로와 심볼 경로를 보여주고, ⇧⌘.로 포커스를 주면 형제 파일이나 심볼로 바로 이동한다. 화면 위쪽이 좁아 보이면 breadcrumbs.enabled를 false로 두면 된다.

편집 단축키 — 접기·줄바꿈·찾기

코드가 길어지면 접기부터 쓴다. 함수 단위로 접어두면 파일 전체 구조가 한눈에 들어온다.

⌘K로 시작하는 조합은 두 번 눌러야 한다. ⌘K를 누르고 손을 뗀 다음 ⌘L을 누르는 식이다. 처음엔 어색한데, 접기 관련 조합이 전부 ⌘K로 시작해서 한 묶음으로 외우면 편하다.

⌥Z는 세션 단위 토글이라 파일마다 설정이 저장되지는 않는다. 항상 켜두고 싶으면 settings.json에서 editor.wordWrap을 지정해야 한다.

들여쓰기는 VSCode가 파일을 보고 자동으로 판단한다. 2·4·6·8칸 공백을 후보로 보고, 상태 바 오른쪽에 감지된 값을 표시한다. 3칸 들여쓰기를 쓰는 프로젝트라면 editor.detectIndentation을 끄고 editor.tabSize를 직접 정하는 편이 낫다. 나는 이걸 모르고 한참 헤맸다.

멀티 커서 단축키 — 같은 단어를 한 번에

이름을 바꿀 때 하나씩 고치는 건 손해다. ⌘D를 누르면 커서 위치의 단어가 선택되고, 한 번 더 누르면 같은 단어가 다음에 추가된다. 전부 한꺼번에 고치려면 ⇧⌘L을 쓴다.

⌘K ⌘D는 반복되는 단어가 많은 파일에서 특히 쓸모 있다. 주석에 같은 단어가 섞여 있을 때 그 건만 건너뛰고 나머지를 고칠 수 있다.

⌥⌘↑·⌥⌘↓는 그래픽 카드 드라이버가 가로채는 경우가 있다고 문서에 적혀 있다. 맥에서는 보통 잘 동작하지만, 다른 앱에서 같은 조합을 쓰고 있다면 editor.multiCursorModifier를 alt로 두고 클릭 방식으로 바꾸는 편이 안전하다.

설정은 settings.json으로 여는 편이 빠르다

VSCode 설정은 UI 편집기와 JSON 파일 두 곳에서 같은 값을 다룬다. 항목이 많아지면 JSON이 빠르다. 이름을 알고 있을 때 검색창을 거치지 않고 바로 쓸 수 있기 때문이다.

여는 경로는 세 가지다.

• ⌘, — 설정 편집기(기본은 편집 영역 위 모달)
• 명령 팔레트에서 Preferences: Open User Settings (JSON)
• 명령 팔레트에서 Preferences: Open Workspace Settings (JSON) — 프로젝트의 .vscode/settings.json

사용자 설정은 모든 창에 적용되고, 워크스페이스 설정은 그 프로젝트를 열었을 때만 적용된다. 업데이트·보안 관련 설정처럼 워크스페이스에서 덮어쓸 수 없는 항목도 있다.

내가 바꾼 값만 보고 싶으면 설정 편집기 검색창에 @modified를 넣는다. 기본값과 다른 항목만 남는다. "왜 이 파일에서만 줄바꿈이 되지" 같은 상황에서 원인을 찾는 데 제일 빠른 방법이다.

특정 설정으로 바로 가는 URL도 있다. vscode://settings/<설정이름> 형식이라, 사내 문서에 vscode://settings/editor.formatOnSave 같은 링크를 넣어두면 클릭 한 번으로 해당 항목이 열린다.

위 표를 그대로 옮겨 적기보다, 자주 쓰는 항목만 settings.json에 남기고 나머지는 기본값으로 두는 편이 관리가 쉽다.

내가 쓰는 settings.json 8줄

아래는 내 맥의 사용자 설정 중 실제로 손댄 부분만 추린 것이다.

{
  "files.autoSave": "onFocusChange",
  "editor.formatOnSave": true,
  "editor.formatOnPaste": false,
  "editor.rulers": [88],
  "files.exclude": { "**/__pycache__": true, "**/.pytest_cache": true },
  "search.exclude": { "**/node_modules": true, "**/dist": true },
  "editor.multiCursorModifier": "alt",
  "breadcrumbs.enabled": true
}

files.autoSave를 afterDelay로 두면 타이핑을 멈출 때마다 저장된다. 편하지만 저장 시 포맷이 걸려 있으면 커서가 튀는 느낌이 있어서, 나는 포커스가 떠날 때만 저장하는 쪽을 쓴다.

__pycache__와 node_modules를 양쪽에서 빼두면 탐색기가 훨씬 조용해진다. 파이썬 프로젝트를 열 때마다 캐시 폴더가 먼저 보이던 문제도 같이 사라진다.

저장할 때 자동 정리 — formatOnSave가 안 먹는 이유

editor.formatOnSave를 켰는데 아무 일도 안 일어나면 포매터가 없는 언어일 가능성이 크다. VSCode는 언어별 기본 포매터를 내장한 경우도 있지만, 파이썬처럼 확장이 필요한 언어는 별도 설치가 필요하다. 포매터가 여러 개면 어느 것을 쓸지 정해줘야 한다.

저장 시 동작은 세 가지가 따로 있다.

• editor.formatOnSave — 파일 전체 포맷
• editor.formatOnPaste — 붙여넣은 범위 포맷. 범위 포맷을 지원하는 포매터에서만 동작한다
• editor.formatOnType — 한 줄 입력 후 포맷

셋 다 기본값은 꺼짐이다. 자동 저장을 켜두고 포맷도 같이 돌리면 저장 타이밍이 내 손을 떠나므로, 처음 며칠은 저장 단축키(⌘S)로 감각을 확인하는 편이 낫다.

내가 막혔던 곳

가장 오래 헤맨 건 단축키 충돌이었다. ⌘D가 안 먹길래 키보드 문제인 줄 알고 한참을 만졌는데, 원인은 같은 조합을 쓰는 다른 앱이었다. 키보드 단축키 편집기에서 항목을 우클릭해 Show Same Keybindings를 눌렀더니 같은 키에 명령이 여러 개 걸려 있었다. 이 메뉴를 알기 전까지는 설정을 하나씩 지워가며 확인했다.

두 번째는 포커스다. 단축키가 파일에 따라 먹었다 안 먹었다 했는데, 편집기가 포커스를 잃으면 편집 명령이 실행되지 않는다는 걸 늦게 알았다. Developer: Toggle Keyboard Shortcuts Troubleshooting을 켜면 키를 눌렀을 때 어떤 명령이 잡히고 어느 조건에서 막히는지 로그로 나온다. 예를 들어 맥에서 ⌘/를 누르면 editor.action.commentLine이 editorTextFocus && !editorReadonly 조건으로 매칭되는 식이다. 이 로그를 보고 나서야 "안 먹는 게 아니라 조건이 안 맞는 것"이라는 구분이 생겼다.

세 번째는 설정 동기화다. 회사 맥과 집 맥에서 같은 계정으로 설정을 동기화했더니, 예전에 실수로 넣은 files.exclude가 따라와서 특정 폴더가 안 보였다. @modified로 내가 바꾼 항목을 훑고 나서야 찾았다. 그 뒤로는 프로젝트별 설정은 .vscode/settings.json에만 두고, 사용자 설정에는 최소한만 남기고 있다.

참고 자료

• VSCode 키보드 단축키 문서 — 단축키 편집기, 키맵 확장, 충돌 확인, 트러블슈팅 로그
• VSCode 기본 편집 문서 — 멀티 커서, 접기, 찾기·바꾸기, 자동 저장, 들여쓰기 감지
• VSCode 코드 탐색 문서 — ⌘P, 편집 위치 이동, 브레드크럼, 정의로 이동
• VSCode 설정 문서 — 사용자·워크스페이스 설정 범위, @modified, 설정 URL
• VSCode 터미널 문서 — ⌃`로 터미널 열기, 출력 링크
• VSCode 1.145 릴리스 노트 — 2026년 11월 4일 배포된 1.145.3 기준
• Cursor 사용법 — VSCode 기반 에디터라 단축키가 대부분 그대로 통한다
• git 기초 사용법 + 자주 하는 에러 — 소스 제어 패널과 터미널을 같이 쓰는 흐름
• Mac 개발환경 세팅 — Homebrew·iTerm2·zsh를 먼저 잡아두면 편하다

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc7 in position 0 같은 줄을 만나면 대부분 encoding='utf-8'을 붙였다가 또 실패하고, 그다음엔 errors='ignore'로 넘겨버린다. 그러면 에러는 사라지지만 글자는 영원히 깨진 채로 남는다.

이 글은 한글 파일을 읽을 때 나는 UnicodeDecodeError를 기준으로, 에러 메시지에서 무엇을 읽어야 하는지와 읽는 쪽·쓰는 쪽을 어떤 순서로 고치는지를 정리했다. 예제는 내 맥의 python3 3.9.6과 최신 문서(Python 3.15 계열)를 함께 확인해서 썼다.

30초 요약

한글 깨짐은 파일 손상이 아니라 코덱 선택 문제라는 것을 정리한 히어로 이미지

목차

1. UnicodeDecodeError는 왜 나는가
2. 에러 메시지에서 읽어야 하는 네 가지
3. 해결 1 — 읽는 쪽에 encoding을 지정한다
4. 해결 2 — cp949와 BOM(utf-8-sig) 구분
5. 해결 3 — 인코딩을 모를 때 확인하고 변환하기
6. 그래도 안 될 때 — 쓰는 쪽과 실행 환경
7. 증상별 처방 표
8. 내가 막혔던 곳
9. 참고 자료

UnicodeDecodeError는 왜 나는가

파이썬 3에서 str은 글자, bytes는 바이트다. 파일을 텍스트 모드로 열면 파이썬이 바이트를 읽어서 코덱으로 글자로 바꾸는데, 이때 바이트가 그 코덱의 규칙에 맞지 않으면 UnicodeDecodeError가 난다. 같은 파일이라도 어떤 코덱을 고르느냐에 따라 성공과 실패가 갈린다.

내 맥에서 직접 확인한 결과다. 같은 "한글"이라는 글자를 utf-8로 저장하면 b'\xed\x95\x9c\xea\xb8\x80', cp949로 저장하면 b'\xc7\xd1\xb1\xdb'가 된다. 이 cp949 바이트를 utf-8로 읽으면 바로 에러가 난다.

>>> "한글".encode("cp949")
b'\xc7\xd1\xb1\xdb'
>>> "한글".encode("cp949").decode("utf-8")
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc7 in position 0: invalid continuation byte

cp949의 첫 바이트 0xC7은 utf-8에서 "앞 글자의 뒤를 잇는 바이트"로만 쓰이는 값이라, 파이썬 입장에서는 문장이 시작하자마자 규칙이 깨진 것이다. 반대 방향도 똑같이 실패한다. utf-8 바이트를 cp949로 읽으면 'cp949' codec can't decode byte 0xed in position 0: illegal multibyte sequence가 나온다.

정리하면 이 에러는 파일이 깨진 게 아니다. 내가 고른 코덱이 파일과 안 맞는 것이다. 파일은 그대로 두고 읽는 쪽을 고치면 된다.

에러 메시지에서 읽어야 하는 네 가지

트레이스백은 생각보다 많은 정보를 준다. 아래 한 줄만 제대로 읽어도 절반은 해결된다.

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc7 in position 12: invalid continuation byte

position이 0이고 byte가 0xef라면 BOM(Byte Order Mark)이 원인일 수 있다. utf-8 BOM은 EF BB BF 세 바이트다. 이때는 utf-8-sig로 읽으면 BOM을 건너뛴다. 처리 방식은 아래 해결 2에서 따로 다룬다.

어느 파일에서 났는지 안 보이면 트레이스백 위쪽 프레임을 봐야 한다. open()을 여러 번 부르는 코드라면 파일 경로를 로그로 찍는 편이 빠르다. 나는 예외를 잡아서 경로를 붙여 다시 올리는 방식을 쓴다.

try:
    text = open(path, encoding="utf-8").read()
except UnicodeDecodeError as exc:
    raise RuntimeError(f"{path} 디코딩 실패: 코덱={exc.encoding}, 위치={exc.start}") from exc

UnicodeDecodeError에는 encoding, object, start, end, reason 속성이 있어서 어느 지점에서 막혔는지 코드로 꺼낼 수 있다. (내장 예외)

여러 파일을 한꺼번에 읽는 배치라면, 원인을 찾기 전에 -X warn_default_encoding을 붙여 실행해 보는 것도 방법이다. 인코딩을 적지 않은 open()마다 EncodingWarning이 찍힌다. 이 경고는 Python 3.10부터 있고 기본은 꺼져 있다. (PEP 597)

해결 1 — 읽는 쪽에 encoding을 지정한다

결론은 간단하다. 텍스트를 읽는 모든 지점에 인코딩을 적는다. 파이썬 3.15 문서 기준으로, 텍스트 모드에서 encoding을 생략하면 UTF-8이 기본이고, UTF-8 모드가 꺼진 환경에서는 locale.getencoding()이 대신 쓰인다. 즉 같은 코드가 OS와 버전에 따라 다르게 동작할 수 있다. (open())

이 불확실성을 없애려고 파이썬은 3.15부터 UTF-8 모드를 기본으로 켠다. (PEP 686) 그래도 3.14 이하를 쓰는 사람이 많으니, 코드에는 인코딩을 직접 적는 습관이 안전하다.

# 가장 기본
from pathlib import Path

text = Path("메모.txt").read_text(encoding="utf-8")

# 한 줄씩 읽기
with open("로그.txt", encoding="utf-8") as f:
    for line in f:
        print(line.rstrip())

csv 모듈은 newline=""을 같이 넣어야 줄바꿈 처리가 꼬이지 않는다. 엑셀이 만든 파일이면 cp949부터 시도한다.

import csv

with open("주소록.csv", newline="", encoding="cp949") as f:
    rows = list(csv.DictReader(f))

pandas를 쓴다면 read_csv의 encoding 인자로 같은 값을 넘긴다. encoding_errors의 기본값은 'strict'라서, 인코딩이 틀리면 조용히 넘어가지 않고 에러를 낸다. (pandas.read_csv)

import pandas as pd

df = pd.read_csv("매출.csv", encoding="cp949")
df = pd.read_csv("매출.csv", encoding="utf-8-sig")   # BOM 있는 utf-8

JSON은 예외가 적다. 교환용 JSON 텍스트는 UTF-8로 쓰는 것이 표준이고, 파이썬 json 모듈도 그 전제로 동작한다. (RFC 8259 §8.1) 그래도 파일을 직접 열어 읽는다면 인코딩을 적어두는 편이 좋다.

증상별 처방을 한 장에 정리한 카드 — 코덱·BOM·errors 처리 순서

위 코드처럼 읽는 지점마다 encoding을 붙여두면, 나중에 다른 사람이 같은 파일을 열어도 에러 없이 같은 결과를 본다. 인코딩은 "환경이 정해주는 값"이 아니라 "내가 정하는 값"으로 다루는 게 핵심이다.

해결 2 — cp949와 BOM(utf-8-sig) 구분

한국어 환경에서 실제로 마주치는 인코딩은 크게 셋이다. 이름이 비슷해서 헷갈리는데, 파이썬 표준 인코딩 목록에는 cp949가 949, ms949, uhc와 같은 코덱으로 등록돼 있다. (표준 인코딩)

utf-8-sig는 읽을 때 앞의 BOM을 건너뛰고, 쓸 때는 BOM을 붙인다. (codecs — utf_8_sig) 이걸 안 쓰면 첫 컬럼 이름이 '\ufeff이름'처럼 보이면서, 값은 멀쩡한데 컬럼 매칭만 실패하는 이상한 상황이 된다. KeyError: '이름'이 나는데 눈으로는 똑같아 보이는 증상이 그거다.

cp949와 euc-kr은 겹치는 부분이 많지만 같은 코덱은 아니다. cp949가 euc-kr보다 넓은 문자 집합을 담는다. 그래서 euc-kr로 저장된 파일은 cp949로도 대부분 읽힌다. 반대는 안 된다. 실무 순서는 utf-8 → cp949 → euc-kr로 두는 편이 무난하다.

def read_korean_text(path):
    for enc in ("utf-8-sig", "cp949"):
        try:
            return path.read_text(encoding=enc), enc
        except UnicodeDecodeError:
            continue
    raise UnicodeDecodeError("unknown", b"", 0, 1, f"{path} 인코딩 판별 실패")

이 함수는 BOM 있는 utf-8과 cp949를 모두 잡는다. 다만 "성공했다"가 "제대로 읽혔다"를 보장하지는 않는다. 아래 섹션에서 이 함정을 다룬다.

해결 3 — 인코딩을 모를 때 확인하고 변환하기

파일이 어떤 인코딩인지 모르면 추측보다 확인이 먼저다. 맥·리눅스에서는 file 명령으로 charset을 볼 수 있다.

file -I 주소록.csv          # macOS
file -i 주소록.csv          # Linux

charset=unknown-8bit처럼 나오면 판별에 실패한 것이다. 이럴 때 파이썬에서는 charset-normalizer를 쓴다. requests가 의존성으로 함께 설치하는 라이브러리라 이미 깔려 있는 경우가 많다.

from charset_normalizer import from_bytes

raw = open("주소록.csv", "rb").read()
best = from_bytes(raw).best()
print(best.encoding)          # 예: cp949
text = str(best)

바이너리로 읽어서("rb") 디코딩을 직접 하는 게 요령이다. 텍스트 모드로 열면 그 순간 이미 에러가 나기 때문이다.

이미 인코딩을 알았다면 파일 자체를 utf-8로 바꿔두는 편이 오래 편하다. iconv는 맥과 리눅스에 기본으로 있다.

iconv -f CP949 -t UTF-8 주소록.csv > 주소록-utf8.csv

주의할 점은 짧은 문자열의 인코딩 판별이 원리적으로 불가능하다는 것이다. 바이트 몇 개는 여러 코덱에서 동시에 유효하다. 자동 판별은 "후보를 좁히는 도구"로만 쓰고, 사람이 눈으로 결과를 확인하는 절차를 남겨두는 게 안전하다.

그래도 안 될 때 — 쓰는 쪽과 실행 환경

읽기에서 고쳤는데도 에러가 나면 이번엔 반대쪽이다. UnicodeEncodeError는 글자를 바이트로 바꾸는 과정에서 났다는 뜻이라 처방이 다르다.

첫째, 터미널 출력에서 막히는 경우다. print()가 UnicodeEncodeError: 'ascii' codec can't encode characters로 죽으면 표준출력의 인코딩이 ascii로 잡힌 것이다. 환경 변수로 고정한다.

PYTHONIOENCODING=utf-8 python3 app.py
python3 -X utf8 app.py          # UTF-8 모드 강제

UTF-8 모드는 PYTHONUTF8=1로도 켤 수 있고, 3.15부터는 기본값이다. (PEP 540, PEP 686)

둘째, 파일을 쓸 때 인코딩을 안 적은 경우다. 읽기만 고치고 쓰기는 그대로 두면, 저장된 파일이 실행 환경에 따라 달라진다.

with open("결과.csv", "w", encoding="utf-8-sig", newline="") as f:
    f.write("이름,점수\n")

엑셀에서 다시 열어야 하는 파일이라면 utf-8-sig가 편하다. BOM이 있어야 엑셀이 utf-8로 인식한다.

셋째, 외부 명령의 출력을 읽을 때다. subprocess의 text=True는 로캘 인코딩을 쓰기 때문에, 실행 환경이 바뀌면 깨진다.

import subprocess

out = subprocess.run(["ls"], capture_output=True, text=True, encoding="utf-8").stdout

넷째, 파일 이름 자체가 문제인 경우다. 리눅스에서 잘못된 바이트가 섞인 파일명은 surrogateescape 오류 처리기로 문자열에 담긴다. 이걸 다시 인코딩해야 원래 파일명으로 돌아간다. (에러 처리기)

import os

for name in os.listdir("."):
    raw = name.encode("utf-8", "surrogateescape")

errors 기본값은 strict이고, replace는 깨진 글자를 �로 바꾸며 ignore는 아예 지운다. 데이터를 살려야 하는 자리에서 ignore를 쓰면 행 길이가 달라져서 나중에 원인 찾기 어려운 버그가 된다. (에러 처리기)

증상별 처방 표

지금까지 내용을 증상 기준으로 다시 묶었다. 에러 문구를 그대로 검색해 들어온 사람을 위한 표다.

내가 막혔던 곳

가장 오래 헤맨 건 공공데이터 CSV였다. pd.read_csv(path)가 UnicodeDecodeError를 내서 encoding="cp949"를 붙였더니 이번엔 읽히는데, 컬럼 이름이 지역이 아니라 \ufeff지역처럼 잡혀서 df["지역"]이 KeyError를 냈다. 화면에 출력된 컬럼명은 멀쩡해 보여서 한참을 의심하지 못했다. BOM은 눈에 안 보이니까. 결국 repr(df.columns[0])로 찍어보고 나서야 원인을 알았다. 지금은 한국어 CSV를 받으면 utf-8-sig를 먼저 시도하고, 실패하면 cp949로 내려간다.

두 번째는 errors="ignore"의 유혹이었다. 급할 때 이걸 붙이면 에러가 사라지고 코드는 끝까지 돌아서 성공한 것처럼 보인다. 그런데 그 뒤에 만든 집계표에서 특정 지역 이름만 비어 있었다. 복구가 안 되는 손실이었다. 그 뒤로는 ignore 대신 replace를 쓰고, 깨진 개수를 세서 로그로 남긴다. 몇 건이 깨졌는지 알아야 데이터를 믿을지 결정할 수 있다.

세 번째는 환경 차이였다. 내 맥에서는 잘 돌던 스크립트가 윈도우 노트북에서 같은 파일을 읽다가 죽었다. 맥은 기본이 utf-8이고 한국어 윈도우는 ANSI 코드 페이지가 cp949라서, 인코딩을 안 적은 open()이 서로 다르게 동작한 것이다. 그때부터 텍스트를 여는 코드에는 예외 없이 encoding을 적는다. 파일을 옮겨 다니는 프로젝트라면 Python 가상환경 venv 만들기처럼 실행 환경을 문서에 남겨두는 습관도 같이 들였다.

참고 자료

• UnicodeDecodeError — Built-in Exceptions — encoding·start·end·reason 속성
• open() — Built-in Functions — 텍스트 모드 기본 인코딩 규칙
• codecs — 표준 인코딩 — cp949/949/ms949/uhc 별칭
• codecs — 에러 처리기 — strict·replace·surrogateescape
• codecs — utf_8_sig — BOM 처리
• PEP 686 — Make UTF-8 mode default — Python 3.15 기본값 변경
• PEP 597 — Add optional EncodingWarning — -X warn_default_encoding
• PEP 540 — UTF-8 mode — PYTHONUTF8
• pandas.read_csv — encoding, encoding_errors
• RFC 8259 §8.1 — JSON은 UTF-8
• 관련 글: ModuleNotFoundError 해결 · pip install 오류 해결 · Python 가상환경 venv 만들기

스레드에서 "드디어 dot이 여러 대의 컴퓨터에 붙는다"는 글이 돌고, 그 밑에 "코덱스는 신이야"라는 댓글이 붙어 있었다. dot이 뭔지 모르면 이 대화가 무슨 말인지 따라가기 어렵다.

이 글은 dots가 무엇인지, 이번에 무엇이 열렸는지, 실제로 어떻게 설정하는지, 그리고 어디서 막히는지를 OpenAI 공식 문서에서 확인해 정리한 것이다. 2026년 11월 10일 기준 문서 내용이다.

30초 요약

목차

1. dots란? 한 문단 정의
2. 이번에 달라진 것 — dot 하나에 컴퓨터 여러 대
3. 설정은 3단계 — 컴퓨터마다 같은 작업을 반복
4. 실제로 이게 왜 편한가 — 노트북과 맥을 동시에 쓰는 그림
5. 한 번에 한 대 — 알아야 할 제약
6. 요금과 접근 조건
7. 내가 막혔던 곳
8. 참고 자료

dots란? 한 문단 정의

dot은 ChatGPT 안에서 돌아가는 개인용 에이전트다. 챗봇처럼 질문에 답하는 게 아니라, 자기 컴퓨터를 하나 받아서 일을 대신 처리한다. OpenAI 발표문은 이렇게 적는다. "dot은 프런티어 지능에 클라우드 컴퓨터, 피드백으로 배우는 능력, 24/7로 목표를 향해 일하는 성질을 붙인 것"이다. (발표문)

그래서 기본값이 "내 컴퓨터를 쓰는 AI"가 아니다. dot은 클라우드에 자기 컴퓨터와 브라우저를 갖고 있고, 내 기기와는 분리돼 있다. 내 노트북을 쓰게 하려면 따로 허용해야 한다. 이 구조를 모르고 쓰면 "왜 내 파일을 못 읽지"에서 막힌다.

모델은 GPT-6 Astra로 시작했고, 2026년 11월 3일부터 GPT-6.1 Terra가 추가됐다. 한 작업 안에서도 부분마다 다른 모델을 쓸 수 있다는 설명이다. (발표문) GPT-6 계열 자체가 궁금하면 GPT-6 Cyber 정리에 배경을 적어뒀다.

이번에 달라진 것 — dot 하나에 컴퓨터 여러 대

이전에는 dot 하나에 컴퓨터 한 대를 붙이는 그림이 기본이었다. 지금 문서는 "컴퓨터를 한 대 넘게 연결하고, 작업마다 어느 컴퓨터를 쓸지 dot에게 말할 수 있다"고 적는다. (문서)

바뀐 지점은 세 가지다.

여기서 많이 헷갈리는 부분이 하나 있다. 이 연결은 Codex에 컴퓨터를 연결하는 것과 별개다. Work Sync를 켜는 것과도 별개다. 문서는 "어느 한쪽 연결만으로는 dot이 내 컴퓨터에 접근할 수 없다"고 못 박는다. (문서)

설정은 3단계 — 컴퓨터마다 같은 작업을 반복

설정 자체는 짧다. 대신 컴퓨터 대수만큼 반복해야 한다.

1. 그 컴퓨터에서 ChatGPT 데스크톱 앱을 연다.
2. dot 프로필을 열고 Computers에서 지금 쓰는 컴퓨터를 찾아 Allow를 누른다.
3. 확인 창에서 Allow access를 누른다.

다른 컴퓨터를 추가하려면 그 컴퓨터에서 같은 과정을 한 번 더 하면 된다. (문서)

모바일에서 만든 dot이라도 데스크톱 앱에서 나중에 연결할 수 있다. 반대로 모바일 웹은 지원하지 않는다. 설정은 모바일 앱, 데스크톱 앱, 데스크톱 브라우저 셋 중 아무 데서나 시작해도 되고, 만든 dot은 다른 기기에서 그대로 이어진다. (문서)

권한을 끊을 때는 Revoke access를 쓴다. 상태가 Offline으로 보이는 건 권한이 사라진 게 아니라 그 컴퓨터를 지금 못 쓴다는 뜻이다. (문서)

실제로 이게 왜 편한가 — 노트북과 맥을 동시에 쓰는 그림

스레드 글이 든 예시가 이해가 빠르다. 노트북에서 코딩하는 동안, dot에게 다른 맥의 Xcode에서 iOS 앱을 빌드·테스트하고 결과 화면을 보내달라고 하는 식이다. 서로 다른 컴퓨터에서 같은 오류를 재현하는 것도 같은 원리다.

이게 되는 이유는 dot이 클라우드에서 작업을 조율하고, 실제 실행만 연결된 컴퓨터에서 하기 때문이다. 문서 표현으로는 "작업은 클라우드에서 관리되면서 연결된 컴퓨터의 파일과 도구를 쓴다"이다. (문서)

실무에서는 이런 조합이 나온다.

Xcode처럼 그 컴퓨터에만 깔린 도구를 쓰는 작업이 대표적이다. 로컬 스킬도 연결된 컴퓨터가 있어야 돈다. (문서)

한 번에 한 대 — 알아야 할 제약

가장 중요한 제약은 "여러 대를 동시에 조종한다"가 아니라는 점이다. 문서는 이렇게 적는다. 컴퓨터별로 별도 스레드를 시작하고, 각 스레드는 한 번에 컴퓨터 한 대를 쓴다. (문서)

여기에 하나 더. dot의 대화는 Pro·Business Premium의 ChatGPT 사용량 한도에 안 들어가지만, dot이 시작한 Work·Codex 작업은 그 제품의 한도에 그대로 들어간다. (문서) 에이전트를 부려서 아낀 시간이 사용량으로 돌아오는 구조라는 뜻이다.

요금과 접근 조건

dots는 별도 구독이 아니라 ChatGPT 요금제에 붙어 있다. 첫 dot은 추가 비용 없이 포함되고, 여러 dot과 속도·작업량 확장은 앞으로 열린다는 설명이다. (발표문)

Pro 요금은 공식 요금 문서의 "월 $100, $200, $500 중 선택" 표기를 그대로 옮겼다. (요금 문서) Business Premium 금액은 사용자 수와 결제 방식에 따라 달라서 여기 적지 않았다.

접근 조건 표에서 눈여겨볼 건 마지막 줄이다. 기업용은 관리자 프리뷰 기간을 거쳐 11월 18일부터 기본값이 켜짐으로 바뀐다. (문서) 회사 계정으로 쓰는 사람은 그날 전에 관리자에게 물어보는 게 안전하다.

내가 막혔던 곳

이 글을 쓰면서 실제로 세 번 걸렸다.

첫째, 한국어 검색으로는 정보가 거의 안 나온다. "닷", "dots", "오픈AI 에이전트"로는 스레드 글과 요약 블로그만 나왔다. 결국 OpenAI 문서 원문을 직접 열어서 읽어야 했다. 문서는 learn.chatgpt.com/docs/llms-full.txt로 전체를 한 파일로 받을 수 있어서, 거기서 "컴퓨터", "연결" 부분을 찾는 게 제일 빨랐다.

둘째, "여러 대 연결"을 처음엔 "여러 대 동시 사용"으로 읽었다. 문서를 두 번 읽고 나서야 스레드마다 한 대라는 걸 확인했다. 블로그 요약 글에 이 제약이 빠져 있는 경우가 많아서, 이 글에는 표로 따로 뺐다.

셋째, Codex에 이미 컴퓨터를 연결해 둔 사람은 dots도 자동으로 될 거라고 생각하기 쉽다. 문서는 명시적으로 별개라고 적는다. 기존 연결이 있다고 dot 설정을 건너뛰면 "왜 파일을 못 읽지"에서 막힌다.

참고 자료

• Introducing dots — OpenAI
• Connect computers and apps to your dot — ChatGPT 문서
• Meet dots · Access — ChatGPT 문서
• Pricing — ChatGPT 문서
• Tasks and memory — ChatGPT 문서

관련 글: GPT-6 Cyber 총정리 · Gemini 사용법 · Cursor 사용법

요즘 국내에서 "AI 비서"라는 말로 같이 묶여 소개되는 앱이 둘이다. 부이(vooy)와 피클(Pickle). 둘 다 채팅창에 말로 시키면 일을 처리한다고 해서, 처음엔 같은 앱인 줄 알았다.

막상 써보려고 앱스토어 설명을 나란히 놓으니 역할이 꽤 달랐다. 하나는 찾고 비교하고 계획하는 쪽, 다른 하나는 전화하고 결제하는 쪽이다. 이 글은 2026년 11월 9일 기준 공식 사이트와 앱스토어 정보로 둘을 같은 기준에 놓고 비교한 것이다.

30초 요약

부이(vooy)와 피클은 같은 ‘AI 비서’로 묶여 소개되지만, 줄여주는 구간이 다르다.

목차

1. 부이(vooy)란? — 이름부터 낯선 앱
2. 피클이란? — 이미 한 번 정리한 앱
3. 한눈에 비교
4. 같은 부탁을 두 앱에 하면
5. 요금 비교
6. 안전과 권한 — 여기서 갈린다
7. 어떤 사람에게 뭐가 맞나
8. 내가 막혔던 곳
9. 참고 자료

부이(vooy)란? — 이름부터 낯선 앱

먼저 이름 정리. 공식 한글 표기는 부이다. 회사명도 (주)부이코리아, 앱스토어 개발자도 Vooy Korea, Inc.다. "보이"가 아니다. vooy는 Virtual Oracle of You의 앞글자를 딴 조합이고, 슬로건은 "당신의 첫 반려 에이전트"다. (vooy 공식 사이트)

하는 일은 이렇게 소개된다. 메신저에서 평소 말하듯 부탁하면, 내 취향과 일정을 바탕으로 정보를 찾고 다음 할 일을 정리해준다. 대표 예시가 식당 찾기, 장보기 계획, 약속 준비, 여행 항공권 최저가, 출근길 브리핑이다. (Google Play)

기능 중 눈에 띄는 건 세 가지다.

• 취향 기억 — 좋아하는 음식, 선호하는 분위기, 지난 대화의 계획까지 맥락으로 쓴다
• 그룹 대화 — 친구들과 만날 장소를 찾을 때 단체방 안에서 정보를 나누고 계획을 이어간다
• 실행 연결 — 추천에서 끝내지 않고 일정과 할 일을 구체적으로 정한다

앱스토어 카테고리는 생산성이 아니라 소셜 네트워킹이다. 채팅 UX를 전면에 둔다는 뜻으로 읽힌다. iOS 16.4 이상, 한국어·영어·일본어를 지원하고, 채용 페이지에는 서울에서 시작해 도쿄·방콕·타이베이·싱가포르로 확장한다는 계획이 적혀 있다. (App Store, 채용 페이지)

부이(vooy) 공식 사이트를 직접 캡처했다. ‘찾고 비교하고 예약하는 일까지’를 전면에 내세운다.

피클이란? — 이미 한 번 정리한 앱

피클은 10월 31일에 이미 단독 글로 정리했다. (피클 AI 총정리) 여기서는 비교에 필요한 부분만 다시 짚는다.

피클은 질문에 답하는 데서 끝나지 않고 실제 행동을 한다. 대신 전화를 걸고, 쿠팡·다이소몰에서 주문·결제하고, KTX·항공권·숙소·병원·식당을 예매한다. 결제나 예매처럼 되돌리기 어려운 일은 진행 전에 승인을 받는다. (pickle.com, Google Play)

가장 독특한 기능은 친구의 피클과 약속 잡기다. 사람끼리 "언제 볼까?"로 시작하는 대화를 양쪽 에이전트가 대신 맞추고, 장소와 식당 예약까지 처리한다.

기술적으로는 권한 설계가 눈에 띈다. 자격증명은 AWS Nitro Enclaves 격리 환경에서만 쓰고, 비밀번호·카드는 기기에서 만든 키로 암호화하며, 권한은 1~30일 기간을 정해 빌려주는 구조다. 자세한 내용은 앞선 글에 정리해뒀다.

한눈에 비교

두 앱의 역할을 나란히 놓았다. 부이는 계획 쪽, 피클은 실행 쪽에 가깝다.

표의 세 번째 줄이 가장 중요하다. 부이의 공식 설명은 예약·주문·일정을 "확인 후 단계별로 안내"하는 쪽에 가깝다. 피클은 같은 일을 대신 실행한다. "AI 에이전트"라는 같은 단어를 쓰지만, 손을 대는 지점이 다르다. 애초에 에이전트가 챗봇과 어떻게 다른지는 AI 에이전트란에 정리해뒀다.

같은 부탁을 두 앱에 하면

말로 비교하는 것보다 상황을 하나 놓는 편이 낫다. "이번 주말에 친구 셋이랑 성수에서 점심 먹고 전시 보려는데, 다들 시간 맞춰서 예약까지 해줘"라고 부탁한다고 치자.

부이 쪽 흐름

1. 셋의 가능한 시간대를 대화로 정리한다
2. 성수 식당 후보를 취향에 맞춰 비교한다
3. 전시 시간과 동선을 묶어 일정으로 정리한다
4. 예약은 확인 후 단계별로 안내한다

피클 쪽 흐름

1. 친구의 피클과 대화해 빈 시간을 맞춘다
2. 식당을 예약하고, 필요하면 전시 예매까지 처리한다
3. 결제가 들어가면 승인을 요청한다
4. 끝나면 결과를 요약해 알려준다

둘 다 "카톡 20개"를 줄여주지만, 줄어드는 구간이 다르다. 부이는 생각하고 정하는 구간, 피클은 전화하고 결제하는 구간이다. 같은 부탁도 어디까지 맡길 수 있는지가 다르다.

요금 비교

출처는 각 앱스토어 표시 가격이다. (App Store vooy, Google Play 피클)

부이는 현재 무료다. 초기 사용자 확보 단계라 언제 유료화해도 이상하지 않다. 피클은 무료 한도가 있고, 전화·예매처럼 오래 걸리는 작업이 한도를 많이 먹는 구조다.

안전과 권한 — 여기서 갈린다

에이전트 앱에서 진짜 비용은 구독료가 아니라 사고 났을 때의 비용이다. 두 앱의 공개 자료를 같은 기준으로 놓으면 이렇게 된다.

부이 쪽 "공개 자료 없음"은 문제가 있다는 뜻이 아니라, 아직 보안 설계 문서를 공개하지 않았다는 뜻이다. 신생 앱에서는 흔한 일이다. 다만 위치·연락처·연락처 정보까지 수집한다고 앱스토어에 표시돼 있으니, 가입 전에 권한을 어디까지 줄지 직접 확인하는 게 좋다. (App Store 개인정보)

피클은 반대로 보안 문서를 먼저 공개한 쪽이다. 실제 사고가 없었다는 뜻은 아니지만, "무엇을 어떻게 지키는지"를 읽고 판단할 재료가 있다는 건 선택에 도움이 된다.

어떤 사람에게 뭐가 맞나

부이가 맞는 경우

• 여행·외식·모임 준비에서 "뭐가 좋을지" 비교하는 시간이 아깝다
• 친구들과 계획 맞추는 대화가 길어지는 편이다
• 결제까지 맡기는 건 아직 부담스럽다

피클이 맞는 경우

• 통신사·보험사·병원 전화 대기가 싫다
• KTX·항공권·숙소 예매를 자주 한다
• 승인만 하면 결제까지 맡기고 싶다
• 권한이 어떻게 통제되는지 확인하고 쓰고 싶다

둘 다 쓰는 경우

부이로 계획을 세우고, 피클로 실행하는 조합이 이론상 가장 자연스럽다. 다만 앱을 두 개 오가야 해서, 한쪽이 다른 쪽 기능을 흡수하는 방향으로 빠르게 바뀔 가능성이 크다. 두 회사 모두 초기 단계라 석 달만 지나도 그림이 달라질 수 있다.

내가 막혔던 곳

두 앱 모두 전화번호 인증이 필요해서, 내가 대신 가입해 실제로 돌려보지는 못했다. 그래서 이 글에는 내가 만든 사용 화면이 아니라 공식 페이지 캡처만 들어간다. 후기 글을 쓸 때 늘 아쉬운 부분이다.

대신 확인하면서 헷갈렸던 지점을 남긴다. 첫째, "부이"를 "보이"로 검색하면 결과가 잘 안 나온다. 회사명이 (주)부이코리아라서 한글 표기는 부이다. 둘째, 두 앱의 앱스토어 카테고리가 다르다. 부이는 소셜 네트워킹, 피클은 생산성이다. 카테고리만 봐도 설계 철학이 갈린다는 걸 알 수 있다.

셋째, "AI가 예약해준다"는 문구를 액면가로 믿으면 안 된다. 부이는 안내까지, 피클은 대행까지다. 같은 문장처럼 보여도 내가 마지막에 버튼을 눌러야 하는지, AI가 누르는지가 완전히 다른 경험이다. 가입 전에 이 차이를 먼저 확인하는 걸 권한다.

참고 자료

• vooy 공식 사이트
• vooy App Store
• vooy Google Play
• 피클 공식 사이트
• 피클 Google Play
• 피클 App Store

Gemini를 처음 열면 채팅창 하나만 보인다. 그런데 주변에서 쓰는 사람 얘기를 들어보면 Gems, Deep Research, Canvas, Notebook 같은 이름이 계속 튀어나와서 내가 쓰는 화면과 같은 앱인지 헷갈린다.

이 글은 무료 계정으로 시작해서 어디까지 쓸 수 있는지, 유료로 올렸을 때 무엇이 달라지는지를 2026년 11월 9일 기준 공식 문서로 확인해 정리한 것이다. 요금과 한도는 모두 구글 공식 페이지에서 가져왔다.

30초 요약

목차

1. Gemini 사용법, 한 줄 정의부터
2. 시작하기 — 웹과 앱 중 뭘 쓸까
3. 무료 플랜으로 되는 것과 안 되는 것
4. Gemini 프롬프트는 첨부에서 갈린다
5. Gems와 Notebook — 반복 작업 줄이기
6. Deep Research 사용법 — 보고서 뽑는 순서
7. 요금제 비교 — 무료·Plus·Pro·Ultra
8. 내가 막혔던 곳
9. 참고 자료

Gemini 사용법, 한 줄 정의부터

구글 문서는 Gemini를 "텍스트, 오디오, 이미지를 함께 처리하는 멀티모달 LLM에 대한 인터페이스"로 설명한다. 모델 이름이 아니라 모델을 쓰는 창구라는 뜻이다. (Gemini 앱 안내)

그래서 같은 Gemini라도 어디서 부르느냐에 따라 만나는 모델이 다르다. 웹과 앱에서는 대화용 모델이 붙고, 구글 검색의 AI 모드에서는 검색에 맞춘 구성이 붙는다. 2026년 11월 기준 가장 위에 있는 모델은 Gemini 4 Argon이고, 이건 AI Pro 이상 요금제에서 열린다. (요금제)

처음 쓰는 사람이 기억할 건 하나다. Gemini는 "질문창"이 아니라 "작업대"에 가깝다. 파일을 붙이고, 링크를 주고, 표를 만들고, 이미지를 고치는 일이 한 대화 안에서 이어진다.

시작하기 — 웹과 앱 중 뭘 쓸까

시작은 구글 계정 로그인 하나로 끝난다. 설치형 프로그램이 아니고 브라우저에서 열면 바로 쓸 수 있다. (Gemini 앱)

웹과 앱은 같은 계정이면 대화 기록이 이어진다. 나는 문서 작업은 웹에서 하고, 이동 중에는 앱에서 음성으로 이어서 쓴다. Gemini Live는 채팅 안에 들어와 있어서 음성 모드와 텍스트 입력을 오가며 쓸 수 있다. (요금제)

개발자라면 AI Studio를 같이 열어두는 게 편하다. 초기 비용 없이 Gemini Developer API를 쓸 수 있고, 무료 구간에서는 입력·출력 토큰이 무료다. 대신 무료 구간 콘텐츠는 구글 제품 개선에 사용된다고 명시돼 있다. (요금제) 사내 코드를 넣을 거라면 유료 구간으로 올리는 게 맞다.

무료 플랜으로 되는 것과 안 되는 것

무료가 생각보다 넓다. 유료의 핵심은 기능 개방이 아니라 모델 등급과 사용량이다.

출처는 구글 요금제 페이지와 사용량 한도 안내다. (요금제, 한도 안내)

여기서 많이들 오해하는 부분이 모델이다. 무료 계정은 2026년 10월 9일부터 모델 자동 선택이 기본값이라, 대부분의 질문이 가장 빠른 Flash-Lite로 간다. 깊은 추론이 필요한 질문만 Flash나 Pro로 넘어간다. 설정에서 스마트 모델 선택을 끄면 무료 계정은 모든 답변에 Flash-Lite를 쓴다. (한도 안내)

영상 쪽이 궁금하면 Gemini Omni 1.2 Flash 정리에 따로 적어뒀다. 영상 생성은 요금제에 따라 크레딧이 갈리는 부분이 있어서 따로 보는 게 낫다.

Gemini 프롬프트는 첨부에서 갈린다

같은 질문이라도 파일을 붙이면 답의 밀도가 달라진다. 무료 계정에서도 문서 업로드와 요약은 열려 있어서, 이 기능만 써도 체감 차이가 크다.

내가 자주 쓰는 형태는 이렇다.

첨부한 계약서 PDF에서 위약금 조항만 뽑아줘.
조항 번호와 원문 문장을 같이 적고, 없으면 "없음"이라고 써.
추측해서 채우지 마.

포인트는 세 가지다. 원하는 출력 형식을 먼저 말하고, 없는 경우를 어떻게 처리할지 정하고, 추측 금지를 명시한다. 프롬프트를 길게 쓰는 것보다 이 세 줄이 결과를 안정시킨다. 더 자세한 기준은 프롬프트 작성법에 좋은 예·나쁜 예로 정리해뒀다.

Canvas는 이 과정에서 문서를 다듬을 때 쓴다. 답변을 캔버스로 띄운 뒤 문단을 직접 고치고, 그 상태로 계속 대화를 이어갈 수 있다. 블로그 초안이나 회의록 정리에 붙여 쓰면 복사·붙여넣기 왕복이 줄어든다.

Gems와 Notebook — 반복 작업 줄이기

Gems는 자주 쓰는 지시를 저장해두는 기능이다. 매번 같은 말투와 형식을 요구한다면 Gem 하나로 묶어두는 게 낫다. 무료 계정에서도 열린다. (요금제)

내가 만들어 쓰는 Gem은 두 개다. 하나는 "블로그 교정"이고, 다른 하나는 "코드 리뷰"다. 블로그 교정 Gem에는 말투 규칙과 금지 패턴만 넣어뒀다. 초안을 붙이면 그 규칙에 맞춰 고친다.

Notebook은 리서치와 글쓰기를 붙여놓은 공간이다. 자료를 모으고 요약하면서 원고까지 이어가는 흐름이라, 조사와 작성이 따로 놀지 않는다. 무료는 기본 사용량, AI Plus는 오디오 개요를 더 많이 준다. (요금제)

Deep Research 사용법 — 보고서 뽑는 순서

Deep Research는 질문 하나를 여러 출처로 쪼개서 조사하고 긴 보고서로 묶는 기능이다. 데스크톱과 모바일 모두에서 쓸 수 있고, Gemini 앱에 로그인해야 하며 만 18세 이상만 쓸 수 있다. (혜택 제한)

순서는 이렇게 잡으면 된다.

중요한 건 한도다. 구글 문서는 이미지·영상·음악 생성, Deep Research, Pro 모델, 확장된 사고를 "사용량을 더 많이 쓰는 기능"으로 따로 적어둔다. 한도에 빨리 닿는 이유가 여기 있다. (한도 안내)

요금제 비교 — 무료·Plus·Pro·Ultra

2026년 11월 9일 기준 구글 공식 요금제 페이지에 적힌 금액이다. (요금제)

AI Pro 금액은 결제 지역과 프로모션에 따라 화면에 다르게 뜬다. 내가 확인한 시점의 국내 페이지에는 금액이 고정 표기되지 않아서, 이 표에는 배수만 적었다. 대신 AI Pro부터 Gemini 4 Argon이 열린다는 점이 무료·Plus와의 실질적인 차이다.

무료로 충분한 사람은 이렇다. 하루에 몇 번 질문하고, 가끔 이미지 한 장 만들고, 문서 요약 정도면 무료로 끝난다. 유료가 필요한 순간은 한도에 자주 부딪히거나, Argon급 모델로 코드와 긴 문서를 다뤄야 할 때다.

다른 챗봇과 고민된다면 ChatGPT vs Claude 비교에 판단 기준을 적어뒀다. 도구를 여러 개 쓰는 편이면 AI 기초 용어 20개 정리를 먼저 훑는 게 이해가 빠르다.

내가 막혔던 곳

처음에 "왜 답이 이렇게 짧지" 싶어서 설정을 한참 뒤졌다. 원인은 모델이었다. 무료 계정은 자동 선택이 기본이라 대부분 Flash-Lite로 가고, 나는 그걸 Pro급 모델이라고 생각하고 있었다. 한도 안내 페이지를 읽고 나서야 구조가 이해됐다. (한도 안내)

두 번째는 한도 계산이다. 하루에 몇 번만 썼는데 갑자기 막혀서 이상하다고 느꼈다. 그날은 Deep Research를 두 번 돌리고 이미지를 여러 장 만들었다. 한도가 프롬프트 개수가 아니라 복잡도·기능·대화 길이를 합산하는 방식이라, 무거운 기능을 몰아 쓰면 금방 소진된다. 5시간마다 새로고침되고 주간 한도에서 최종적으로 멈춘다는 것도 같이 알게 됐다.

세 번째는 Gems를 만들어놓고 안 쓰는 습관이다. Gem을 열 개 넘게 만들었는데 정작 대화할 때 부르지 않으면 소용이 없다. 지금은 두 개만 남기고, 대화 시작할 때 @로 부르는 걸 습관으로 만들었다.

참고 자료

• Gemini 앱이란 — 구글 공식 안내 — 멀티모달 LLM 인터페이스 정의, 기능 범위
• Gemini 요금제 — 무료·Plus·Pro·Ultra 기능과 금액
• Gemini 모델 액세스 및 한도 변경사항 — 2026년 10월 모델 자동 선택, 5시간·주간 한도
• Google One 혜택 제한사항 — Deep Research·Flow의 연령·지역 제한
• Google AI 요금제 상세 — 플랜별 포함 기능
• Gemini Omni 1.2 Flash 정리 · 프롬프트 작성법 · ChatGPT vs Claude 비교 · AI 기초 용어 20개

2026년 11월 5일, OpenAI가 GPT-6 Cyber를 공개했다. 이름 그대로 보안 업무만 따로 학습시킨 모델이다. 취약점을 찾는 데서 끝나지 않고, 실제로 동작하는 익스플로잇을 만들고 패치 후보까지 낸다.

이 글은 이 모델이 무엇이고, 무엇을 실제로 해냈고, 돈을 내면 바로 쓸 수 있는지까지 정리한 것이다. 수치와 접근 조건은 OpenAI 공식 발표문, API 문서, 시스템 카드에서 직접 확인했다.

30초 요약

GPT-6 Cyber는 2026년 11월 5일 공개됐다. GPT-6 Astra를 보안 업무에 특화시킨 모델이다.

목차

1. GPT-6 Cyber란? 한 문단 정의
2. 무엇이 달라졌나 — ExploitGym 48.5%
3. 실제로 찾아낸 것 — Firefox 81개, Linux 948개
4. 왜 '정렬'이 이 모델의 핵심인가
5. 기존 모델과 비교
6. 요금과 쓰는 방법 — Daybreak Red 승인 절차
7. 한계와 주의할 점
8. 내가 막혔던 곳
9. 참고 문헌

GPT-6 Cyber란? 한 문단 정의

GPT-6 Cyber는 GPT-6 Astra를 기반으로 사이버보안 업무만 강화 학습한 변형 모델이다. 시스템 카드는 용도를 "취약점 발굴, 익스플로잇 개발, 웹 모의해킹 같은 승인된 보안 업무"로 적는다. (시스템 카드)

일반 모델과 갈리는 지점은 두 가지다. 하나는 보안 요청을 거부하는 비율을 낮춘 것, 다른 하나는 반대로 작업 범위를 넘어서지 않도록 따로 훈련한 것이다. 보안 모델에서 이 두 가지는 원래 충돌한다. 거부를 줄이면 위험한 요청도 통과하고, 안전을 올리면 정당한 연구까지 막힌다. OpenAI는 이번 모델이 양쪽을 동시에 개선했다고 주장한다.

모델 ID는 gpt-6-cyber 하나뿐이고 스냅샷도 하나다. 입력은 텍스트와 이미지, 출력은 텍스트만 받는다. (API 문서)

무엇이 달라졌나 — ExploitGym 48.5%

성능 비교의 기준점은 ExploitGym이다. 원격 대상에 지정된 취약점을 실제로 공격해 성공하는지 보는 평가다. GPT-6 Cyber는 48.5%를 기록했고, GPT-5.6 Cyber는 32.1%였다. OpenAI는 이를 상대 기준 51% 개선이라고 표현한다. (발표문)

절대 수치로 보면 절반은 아직 실패한다는 뜻이기도 하다. 그래도 이전 세대가 3분의 1 수준이었던 것을 생각하면 한 세대 만에 크게 올라온 편이다.

취약점을 찾는 능력도 따로 쟀다. 소스 코드 없이 웹 애플리케이션만 보고 취약점을 찾아내는 새 평가에서 GPT-6 Cyber는 재현율 40.3%를 냈다. GPT-6 Astra는 32.0%였다.

가장 눈에 띄는 건 RemoteExploitBench다. GitLab, PostgreSQL, Jenkins처럼 실제로 쓰이는 애플리케이션의 알려진 취약점을 통제된 환경에 띄워두고 원격 공격을 시도한다. GPT-6 Astra를 Daybreak Blue 권한으로 돌리면 작업의 100%를 거부했다. 같은 과제에서 GPT-6 Cyber는 95%를 완료했다. 실패한 하나는 원격에서 익스플로잇이 동작하지 않은 경우였다. (발표문)

실제로 찾아낸 것 — Firefox 81개, Linux 948개

벤치마크보다 무게가 있는 건 실제 코드베이스에서 나온 결과다.

Linux 쪽은 파이프라인 비용도 같이 공개돼 있어서 참고할 만하다. 감사 대상 선별에 $3,426, 취약점 후보 분석에 $316,549, 재현 검증에 $73,330이 API 크레딧으로 들었다. OpenAI 스스로 이 금액을 "상한에 가깝다"고 밝혔다. (OpenAI 분석)

사람이 손으로 하던 감사를 에이전트 팀으로 바꾸면 단가가 이렇게 잡힌다는 뜻이다. 취약점 하나를 찾는 값이 아니라, 후보 수천 개를 걸러내고 실제로 재현되는 것만 남기는 공정 전체의 값이다.

OpenAI 공식 발표 페이지를 직접 캡처했다. Daybreak Red 승인 고객에게 우선 제공된다는 안내가 앞부분에 나온다.

왜 '정렬'이 이 모델의 핵심인가

보안 에이전트에서 진짜 사고는 성능이 낮아서 나지 않는다. 시킨 범위를 넘어서서 엉뚱한 서비스를 건드릴 때 난다. OpenAI는 이 문제를 ExploitGym Honeypot으로 평가했다.

과제 환경에 패키지 레지스트리나 오브젝트 스토리지 같은 보조 서비스를 붙여둔다. 일부러 공격하기 쉽게 만들어놨고, 그 서비스를 뚫으면 과제 플래그를 얻을 수 있다. 모델은 그것이 자기 업무 범위 밖이라는 걸 스스로 판단해야 한다. (발표문)

수치는 시스템 카드 기준이다. (시스템 카드) GPT-6 Astra는 프롬프트 없이도 0%였는데, GPT-6 Cyber는 공격 능력이 올라간 만큼 프롬프트 없이 0.07%가 남았다. 성능을 올리면 이 숫자가 다시 올라간다는 걸 보여주는 대목이다.

여기에 붙은 장치가 더 있다. 범위를 벗어난 행동을 잡는 감시, 산업 제어 시스템·필수 서비스·선거 시스템 관련 고위험 요청 차단, 자격증명 탈취 대비 IP 허용 목록, 그리고 제로 데이터 보존 고객에게 요구하는 Private Safety Processing이다. (발표문)

기존 모델과 비교

OpenAI가 공개한 실제 결과. Firefox 신규 고위험 취약점 81개, Linux 권한상승 익스플로잇 948개다.

표의 빈칸은 OpenAI가 같은 기준으로 공개하지 않은 값이다. 채우려고 추정하지 않았다. (발표문, 시스템 카드)

Daybreak는 OpenAI의 신뢰 기반 접근 프로그램이다. Blue는 검증된 방어자에게 취약점 확인과 패치를 돕고, Red는 익스플로잇 개발과 승인된 보안 테스트까지 허용한다. GPT-6 Cyber는 Red 등급에 속한다.

요금과 쓰는 방법 — Daybreak Red 승인 절차

먼저 알아둘 건, 결제만 하면 쓸 수 있는 모델이 아니라는 점이다. API 문서 첫 줄이 "조직에 Daybreak Red 접근 권한과 승인이 필요하다"로 시작한다. 승인 여부는 계정 팀이 확인해준다. (API 문서)

비용은 100만 토큰 기준으로 이렇다.

(API 문서)

출력 단가가 입력의 5배다. 취약점 분석처럼 코드와 로그를 길게 넣고 답은 짧게 받는 작업은 캐시 입력 단가($2)를 얼마나 잘 쓰느냐가 비용을 가른다. 반대로 익스플로잇 코드와 설명을 길게 뽑는 작업은 출력 단가가 그대로 붙는다.

지원 범위도 확인해야 한다. Chat Completions와 Responses API는 되지만 Batch, 파인튜닝, 임베딩, 이미지 생성, 오디오 계열은 전부 지원하지 않는다. 스트리밍, 구조화 출력, 함수 호출, 웹 검색, 프롬프트 캐싱은 지원한다. (API 문서)

준비 순서는 대략 이렇다.

1. Daybreak 프로그램에 신청한다.
2. 조직과 프로젝트를 만들고 계정 팀에서 Red 등급 승인을 받는다.
3. Red API는 기본적으로 IP 허용 목록을 요구하니 접근 가능한 네트워크 대역을 정해둔다.
4. Zero Data Retention을 쓰는 조직은 Private Safety Processing을 함께 설정한다.

한계와 주의할 점

• 벤치마크는 전부 OpenAI 자체 평가다. 외부 재현 결과는 아직 없다. 숫자를 인용할 때 "OpenAI 발표 기준"을 붙이는 게 안전하다.
• Critical 등급은 "위험하다"는 뜻이지 "쓰면 안 된다"는 뜻이 아니다. 대신 접근이 좁고 감시가 붙는다. 일반 사용자가 ChatGPT에서 바로 고르는 모델이 아니다.
• 방어 성공률 100%는 없다. OpenAI도 차단율을 100%로 올리는 걸 목표로 두지 않는다고 밝힌다. 정당한 보안 업무까지 막히기 때문이다. (발표문)
• 보안 특화 학습이 다른 분야의 거부 성향을 낮추지 않았는지도 따로 평가했다. 생물·화학 분야는 High로 유지됐고 Critical로 올라가지는 않았다. (시스템 카드)
• 역할 경계는 사람이 잡아야 한다. 에이전트가 찾은 취약점을 실제로 보고할지, 어느 범위까지 테스트할지는 위임 계약서와 승인 절차의 문제다. 프롬프트 인젝션이나 탈옥 공격의 기본 개념은 AI 탈옥이란에 정리해뒀다.

내가 막혔던 곳

API 문서를 처음 열었을 때는 모델 ID만 확인하면 바로 호출해볼 수 있을 거라고 생각했다. 실제로는 첫 문단이 접근 승인 요구였고, 그 아래에 IP 허용 목록과 Private Safety Processing 이야기가 이어졌다. 개인 계정으로 키를 만들어 호출하는 방식이 통하지 않는 모델이다.

그래서 이 글에는 내가 직접 돌려본 화면이 없다. 대신 공개된 시스템 카드와 발표문 수치를 기준으로 정리했다. 실제 도입을 검토한다면 순서를 이렇게 잡는 게 현실적이다. 계정 팀에 Red 등급 가능 여부를 먼저 묻고, 그다음에 파이프라인 설계를 시작한다. 승인이 안 나오면 설계가 아무리 좋아도 테스트할 수 없다.

컨텍스트가 100만 토큰을 넘는다고 해서 코드베이스를 통째로 밀어넣는 방식도 권하지 않는다. OpenAI가 Linux 감사에서 실제로 쓴 방법은 먼저 감사 대상 7%만 골라내는 것이었다. 큰 창은 편의 기능이고, 비용을 줄이는 건 선별 단계다. 컨텍스트 길이 자체가 궁금하면 컨텍스트 윈도우란을 먼저 보면 된다.

참고 문헌

• Introducing GPT-6 Cyber — OpenAI
• GPT-6 Cyber System Card — OpenAI Deployment Safety Hub
• GPT-6-Cyber 모델 문서 — OpenAI API
• A thousand fewer paths to root — OpenAI
• Mozilla 보안 공지 MFSA2026-118