안티그래비티 한글 설정: 설치부터 한국어 작업까지

안티그래비티란 무엇인가#

Google Antigravity는 앱과 IDE 등 여러 사용 환경을 제공합니다. 이 글은 별도 Antigravity IDE를 중심으로 살펴봅니다.

공식 자료 확인일: 설정 안내 2026-11-02, 시작 안내 2026-11-03. 설치나 한국어 입력을 직접 실행한 결과는 아닙니다.

추가 검증 필요: Antigravity IDE의 실제 설치 과정과 인증, 한국어 입력·IME 및 한글 파일명 처리, 첫 작업과 권한 승인·중단 결과에 대한 기록은 아직 없습니다.

제품별 준비 조건#

공식 시작 안내는 Antigravity App(v2.5 이상), CLI(agy v1.2 이상), 편집기 확장 다섯 종, Python SDK를 구분해 소개합니다. 이 글의 대상은 IDE이므로 아래 조건은 IDE 확장과 독립 IDE에만 적용됩니다. VS Code 확장은 VS Code 1.90 이상이 필요합니다. JetBrains 계열은 2026.2.1 이상의 IntelliJ 기반 IDE에서 JetBrains AI 설정의 Agents 메뉴로 설치합니다. Visual Studio는 Windows 10 또는 11에서 Visual Studio 2026 17.8 이상이 필요하고, Zed는 0.140.0 이상, Xcode는 Xcode 27 beta 6 이상이 필요합니다. Eclipse는 2026-06 이상이 필요하며, 공식 항목에는 Public Preview로 표시되어 있습니다.

앱은 데스크톱 애플리케이션이고 CLI는 터미널 클라이언트이며, SDK는 Python 코드에서 에이전트 런타임을 직접 호출하는 도구입니다. 편집기 확장은 각 편집기의 마켓플레이스나 확장 메뉴에서 설치합니다.

독립 IDE 설치 파일은 macOS 12 이상, Windows 10(64비트) 이상, glibc 2.28과 glibcxx 3.4.25 이상의 Linux를 요구합니다. 엔터프라이즈 로그인 지원은 VS Code와 Visual Studio에서 GA이고, JetBrains, Zed, Xcode, Eclipse에서는 Preview로 표시되어 있습니다.

설치 전 확인: 계정·권한·비용#

공식 요금 안내에서 사용할 제품과 계정의 요금제 및 한도를 확인하세요. 회사 계정이라면 관리자 정책도 살펴보세요. 연습에는 비밀키나 개인 정보가 없는 별도 폴더를 쓰고 기존 작업은 백업하거나 버전 관리로 보존하세요.

설치와 인증#

Antigravity 공식 시작 안내의 Antigravity IDE 항목에서 운영체제에 맞는 설치 방법을 확인하고 안내에 따라 로그인하세요. 앱, CLI, 다른 편집기의 확장 기능은 설치 경로가 다릅니다. 설치나 인증 성공은 직접 실행해 확인되지 않았습니다.

IDE에서는 패널이나 설정 화면이 요청할 때 개인 Google 계정 또는 Gemini Enterprise 자격 증명으로 로그인합니다. SDK 설정에는 인증 종류가 따로 있습니다. oauth-personal은 개인 계정의 Free, Pro, Ultra 요금제에, oauth-business는 Gemini Enterprise(Preview)에, gemini-api-key는 Gemini API 키에, agent-platform은 Agent Platform(Preview)에 대응합니다. 이 목록은 SDK 설정이므로 IDE 로그인 화면의 항목과 같지 않습니다.

설치 파일과 CLI 첫 실행 설정#

Antigravity 앱의 macOS 설치 파일은 Apple 실리콘과 64비트 Intel 버전을 따로 제공합니다. 내려받은 .dmg를 열어 앱을 응용 프로그램 폴더로 끌어 넣고, 기존 앱을 업그레이드할 때는 나타나는 대화상자에서 Keep Both 대신 Replace를 고르라고 공식 시작 안내의 앱 항목이 설명합니다. 독립 IDE는 공식 다운로드 페이지에서 따로 받으며, 요구 조건은 앞 절의 IDE 항목과 같습니다.

CLI는 공식 설치 스크립트로 설치하며, macOS와 Linux에서는 홈 폴더의 .local/bin에 agy가 놓입니다. Windows는 PowerShell 스크립트나 CMD용 설치 파일을 쓰고 AppData 아래 agy 폴더에 실행 파일을 둡니다. 설치 뒤에는 agy --version으로 실행 파일이 잡히는지 확인하세요. CLI 설정은 ~/.gemini/antigravity-cli/settings.json에 저장되며, 공식 JSON 스키마를 $schema 키로 연결하면 편집기에서 자동 완성을 쓸 수 있습니다.

처음 실행하면 CLI가 색 테마, 렌더링 방식, 작업 공간 신뢰 여부를 묻습니다. 렌더링은 전체 화면 버퍼를 쓰는 Alt-Screen과 터미널 기록에 순서대로 쓰는 Inline 중에서 고릅니다. 작업 공간 신뢰는 에이전트가 파일 색인을 시작하기 전에 확인하는 항목이므로, 신뢰하지 않는 저장소라면 그 단계에서 멈추세요.

첫 작업: 수정하지 말라고 요청하기#

요청과 파일 내용이 모델 제공자에게 전달될 수 있습니다. 에이전트는 작업 공간을 색인하고, 핵심 에이전트 모델로 Gemini 모델을 쓰며, 요금제에 따라 제3자 모델을 고를 수 있습니다. 제3자 모델을 주 에이전트 모델로 고르면 그 모델의 약관이 적용되고, 서비스 이용 중의 상호작용 데이터는 기록되어 Google이 제품과 머신러닝 기술 개선에 쓸 수 있습니다. 실제 코드를 사용하기 전에 Google 개인정보 처리방침과 Antigravity 이용약관, 사용 중인 계정·조직·모델 제공자에 적용되는 보존·학습 및 데이터 처리 조건을 확인하세요.

연습 폴더에서 파일의 내용을 설명만 해 달라고 요청하고, 수정이나 명령 실행은 요청하지 마세요. 이런 요청만으로 실제 읽기 전용 권한이 보장되지는 않습니다. 예상과 다른 파일 변경이나 명령이 나타나면 작업을 멈추고 확인하세요.

프로젝트 범위와 작업 모드#

앱에서 프로젝트는 에이전트가 다룰 저장소 경계와 파일 범위, 보안 권한을 정하는 단위입니다. 프로젝트에 폴더를 추가한 뒤 작업을 입력하면 설정 창에서 로컬 모드와 새 워크트리 모드 중 하나를 고르게 됩니다. 로컬 모드는 활성 폴더에서 바로 작업하고, 새 워크트리 모드는 격리된 Git 워크트리에서 작업합니다. Git이 없는 폴더에서 워크트리를 고르면 기존 로컬 폴더가 대신 쓰입니다.

프로젝트에 속하지 않은 대화는 임시 작업 디렉터리에서 실행됩니다. 새 프로젝트의 권한은 전역 설정을 따르도록 되어 있어 프로젝트별 예외가 필요할 때만 따로 바꾸면 됩니다. 전역 설정의 계정 항목에는 상호작용 기록을 모델 개선에 공유할지 정하는 텔레메트리 토글이 있으니, 민감한 내용을 입력하기 전에 이 값을 확인하세요. 프로젝트 설정에는 요청 과정에서 쌓인 권한 요청을 프로젝트 권한에 자동으로 추가하는 항목도 있으므로, 프로젝트별 권한 목록을 주기적으로 열어 보는 것이 좋습니다.

권한 승인과 중단#

IDE 설정 안내에서 터미널 자동 실행과 작업 영역 밖 파일 접근 정책을 확인하세요. 사용 환경과 설정에 따라 승인 동작이 다를 수 있습니다. 승인 요청이 나타나면 명령과 대상을 읽고, 이해하지 못하는 작업은 승인하지 마세요. 중단 후에도 변경된 파일을 확인하세요.

IDE 권한 설정 항목#

독립 IDE의 권한 설정은 앱의 프리셋과 이름과 구조가 다릅니다. 터미널 명령 자동 실행은 두 가지입니다. 요청 검토는 허용 목록에 없는 명령을 실행하기 전에 항상 확인을 요청합니다. 항상 진행은 거부 목록에 없는 명령을 묻지 않고 실행하므로 자율성은 높지만 위험도 높다고 공식 설정 문서가 표시합니다. 이 항목의 기본값은 문서에 적혀 있지 않으니 설치 뒤 설정 화면에서 현재 값을 확인하세요.

에이전트의 파일 접근은 기본적으로 프로젝트 폴더와 ~/.gemini/antigravity-ide/ 아래 로컬 앱 데이터 폴더로 제한됩니다. 이 폴더에는 산출물, 지식 항목, 설정 파일이 들어 있습니다. 프로젝트 밖 접근을 켜면 민감한 로컬 데이터가 노출될 수 있으므로 주의하라고 안내합니다.

엄격 모드를 켜면 터미널 자동 실행은 요청 검토로 고정되고 허용 목록은 무시됩니다. 브라우저의 JavaScript 실행과 산출물 계획의 실행도 요청 검토로 바뀌며, 파일 접근은 .gitignore 대상을 피하고 작업 공간 밖을 막습니다. 터미널 샌드박스는 IDE에서 기본적으로 꺼져 있고 macOS에서는 Seatbelt, Linux에서는 커널 네임스페이스로 동작합니다. 'Enable Terminal Sandbox' 설정으로 켜고, 'Sandbox Allow Network'로 파일 제한은 유지한 채 네트워크만 따로 조정할 수 있습니다. 엄격 모드에서는 샌드박스가 자동으로 켜지고 네트워크가 거부됩니다. 샌드박스가 켜진 명령은 파일을 쓸 수 있는 곳이 작업 공간과 필수 시스템 위치로 제한되어, 프로젝트 밖 파일을 실수로 고치는 일을 막도록 설계되어 있습니다. 엄격 모드에서 외부 웹사이트는 브라우저 허용 목록과 차단 목록의 적용을 받습니다. 허용되지 않은 주소의 Markdown 이미지는 렌더링되지 않고, Read URL 도구도 허용된 주소에서만 자동으로 실행됩니다.

앱과 CLI의 권한 프리셋#

앱의 권한 프리셋은 요청 검토, 기본, Auto(Preview), Turbo 네 가지입니다. Auto(Preview)는 v2.23.0 이상에서 쓸 수 있으며, 기업과 비즈니스 계정에서는 아직 제공되지 않는다고 공식 권한 안내가 밝힙니다. 요청 검토는 샌드박스를 끄고 터미널 명령을 항상 묻습니다. 기본은 샌드박스 안의 명령을 허용하고 밖의 명령만 묻습니다. Auto(Preview)는 샌드박스 밖 명령도 자동으로 평가해 안전하고 되돌릴 수 있는 명령은 묻지 않습니다. Turbo는 샌드박스를 끄고 파일 시스템 전체 접근을 허용합니다. 기업과 비즈니스 계정은 이 프리셋 대신 이전 권한 설정을 씁니다. 이전 권한 설정에서는 프로젝트 단위로 터미널 실행 정책과 프로젝트 밖 파일 접근 정책을 정하며, 밖 파일 접근은 Always Allow, Always Ask, Always Deny 중 하나로 고릅니다.

규칙은 프리셋 위에 얹히며, 충돌하면 거부, 묻기, 허용 순서로 적용됩니다. 명령은 command(git)처럼 접두사로 맞추거나 정규식 접두어로 맞춥니다. $(...), 백틱, 리다이렉션이 들어간 명령은 접두사 일치가 꺼지므로, 전체 줄이 규칙과 정확히 같을 때만 묻지 않고 실행됩니다. 예를 들어 git 허용 규칙이 있어도 git log $(whoami)는 승인을 묻습니다.

기본 프리셋의 샌드박스 명령은 작업 공간과 임시 폴더에만 접근하고 네트워크는 기본적으로 쓸 수 없습니다. 네트워크나 호스트 자원이 필요한 명령은 샌드박스 밖 실행을 요청하며, 명령 허용 규칙이 없으면 승인을 묻습니다. 읽기 허용 도메인은 샌드박스의 외부 네트워크 허용 목록에 들어가므로, 도메인 규칙을 넓게 두면 그만큼 샌드박스의 외부 통신 범위도 넓어집니다.

파일에 쓰기 권한을 주면 같은 경로의 읽기 권한도 함께 주어지고, 읽기를 거부하면 쓰기도 막힙니다. 파일, 주소, MCP 권한 카드에서는 허용하기 전에 대상 문자열을 고쳐 디렉터리 단위로 범위를 넓힐 수 있습니다. 다만 터미널 명령은 이 방식으로 범위를 넓힐 수 없습니다. 넓어진 범위가 실제로 필요한 디렉터리인지 확인한 뒤 허용하세요.

CLI에는 같은 역할을 하는 설정이 따로 있습니다. agentMode는 기본, accept-edits, auto(Preview), plan 중에서 고르고, toolPermission은 기본값인 request-review 외에 proceed-in-sandbox, strict, always-proceed를 제공합니다. 공식 설정 문서는 CLI 설정 파일을 ~/.gemini/antigravity-cli/settings.json에 두며, 권한 프롬프트에서 항상 허용이나 거부를 고르면 CLI가 이 파일에 값을 저장한다고 설명합니다.

산출물 검토 정책인 artifactReviewPolicy는 기본값이 검토를 기다리는 asks-for-review이고, always-proceed를 고르면 검토 없이 계속 진행합니다. 이 정책은 파일 편집을 다루지 않으며 파일 편집은 agentMode가 정합니다. 작업 공간 밖 파일 접근을 허용하는 allowNonWorkspaceAccess는 기본적으로 꺼져 있습니다. auto 모드는 macOS와 Linux에서 v1.3.5 이상, Windows에서 v1.4.4 이상이며 기업 계정에서는 쓸 수 없습니다. 지원되지 않는 환경에서 auto로 지정하면 CLI는 기본 모드로 시작합니다.

CLI 키와 승인 흐름#

CLI에서 생성된 산출물을 검토하라는 알림이 뜨면 Ctrl+R로 검토 화면을 엽니다. 공식 시작 안내의 예시는 ↑와 ↓로 파일을 고르고, Tab으로 인라인 diff를 본 뒤 Y로 승인하고 Esc로 패널을 닫는 순서를 보여 줍니다. 명령을 실행하는 단계도 Y로 확인합니다. 진행 중인 응답은 Ctrl+C로 중단하고, 도구 실행 항목은 Ctrl+O로 펼치거나 접습니다. 세션을 끝내려면 Ctrl+D나 /exit를 씁니다. 슬래시 명령 중 /goal은 중간 입력 없이 작업을 끝까지 실행한다고, /grill-me는 구현 전에 요구사항을 질문으로 확인한다고 공식 목록이 설명합니다. /usage는 현재 모델의 크레딧 소비와 한도를 보여 줍니다.

한국어 설정과 한글 파일명#

1. 운영체제에서 한국어 입력기를 선택하고, 연습 파일에 한글 입력 확인을 입력한 뒤 저장하고 다시 열어 글자가 유지되는지 확인합니다.
2. 직접 만든 한글-연습.txt를 열고 파일명 검색을 시도합니다. 검색 결과와 실제 경로가 일치하는지 살펴보세요.
3. 에이전트 입력란에 민감한 정보가 없는 한국어 설명을 입력해 조합 중 글자와 전송 후 문장이 같은지 확인합니다. 응답 언어가 다르면 원하는 언어를 명시해 다시 요청할 수 있지만, 결과는 보장되지 않습니다.
4. 별도로 허용한 연습 파일의 주석을 바꿨다면 diff에서 한글과 변경 범위를 확인합니다. 터미널을 쓴다면 출력도 별도로 살펴보세요.

한국어 UI 메뉴나 특정 언어 팩의 지원 여부는 확인되지 않았습니다. 위 절차는 독자가 자기 환경에서 확인할 수 있는 방법이지, 호환성 시험 결과가 아닙니다.

요금제와 한도 구조#

공식 Plans 안내는 금액보다 한도의 구조를 설명합니다. 모든 요금제는 Gemini 모델 사용, 무제한 탭 자동 완성, 예약 작업과 CLI 같은 기본 기능을 받습니다. Ultra는 가장 높은 한도를 다섯 시간마다 새로 채우고 주간 한도도 가장 높으며 제3자 모델에 접근할 수 있습니다. Pro는 다섯 시간마다 채워지는 높은 한도를 받되 주간 한도에 도달하면 멈추고, 그 밖의 요금제보다 높은 주간 한도를 받습니다. Pro와 Ultra 이외의 요금제는 주 단위로 채워지는 한도만 받습니다.

한도는 작업량에 따라 소모가 달라집니다. 단순한 작업은 더 많은 프롬프트를 쓸 수 있고 복잡한 작업은 한도를 더 씁니다. 공식 안내는 기본 한도가 용량과 남용 방지를 위해 정해지며 바뀔 수 있다고 밝힙니다. Pro와 Ultra 사용자는 기본 한도를 넘으면 구매한 AI 크레딧을 쓸 수 있고, 'AI Credit Overages' 설정에서 Never(기본 한도가 채워질 때까지 기다림)나 Always(한도가 소진되면 크레딧 사용) 중 하나를 고릅니다. 이때 AI 크레딧은 Gemini Enterprise의 표준 소비 요금으로 차감된다고 설명합니다. BYOK나 자체 엔드포인트, 조직별 맞춤 계약 등급은 지원되지 않는다고 나옵니다. CLI에서는 /usage로 모델별 크레딧 소비와 한도를 확인할 수 있습니다. 이 안내에는 요금제의 금액이 나오지 않으므로 현재 가격은 결제 화면에서 확인하세요.

자주 막히는 지점#

글자가 조합 중 깨지거나 중복되면 다른 입력란과 다른 앱에서도 같은지 비교하고 운영체제·제품·버전·입력기 버전을 기록하세요. 파일명이 검색되지 않으면 실제 파일이 열린 폴더 안에 있는지 먼저 확인하세요. 터미널 출력이 깨진다면 에디터 본문과 터미널을 나눠 확인하세요. 비밀번호, 토큰, 사설 저장소 내용은 진단 요청에 포함하지 마세요.

먼저 같은 제품 표면을 보고 있는지 확인하기#

Antigravity 안내에는 앱, CLI와 IDE가 함께 나올 수 있습니다. 다운로드한 제품과 문서의 대상이 다르면 메뉴와 권한 이름도 다를 수 있습니다. 이 글의 연습 대상은 IDE입니다. 공식 문서에서 현재 선택한 제품 표면을 확인하고 그 환경의 안내를 따라야 합니다. 다른 표면의 명령이나 샌드박스 설명을 IDE의 동일한 기능으로 옮겨 적지 마세요.

현재 버전에서 제공되는 설정을 확인한 뒤 입력과 파일 처리 검사를 진행하세요.

조합 입력과 전송 동작을 따로 점검하기#

연습 문장을 입력하는 동안 조합 중인 글자와 입력을 마친 글자를 구분해 보세요. Enter를 누르는 시점에 따라 전송과 입력 확정이 어떻게 처리되는지 관찰할 수 있습니다. 같은 문장을 에디터 본문과 에이전트 입력란에 넣어 차이가 있는지도 확인합니다. 직접 타이핑과 붙여넣기의 결과를 구분하면 문제 위치를 좁히는 데 도움이 됩니다.

글자가 저장된 뒤에만 깨진다면 입력기와 다른 문제일 수 있습니다. 원본을 보관하고 파일 인코딩과 실제 내용을 별도로 확인하세요. 한글 파일명을 찾지 못할 때도 열린 프로젝트 경로와 검색 범위를 먼저 봅니다. 원인이 확인되지 않은 상태에서 파일 전체를 변환하거나 이름을 일괄 변경할 필요는 없습니다. 실패한 한 지점과 정상인 지점을 나눠 기록하는 편이 다음 질문을 구체적으로 만듭니다.

한국어 점검 결과 나누기 (제안, 미실행)#

아래 구분은 실제 실행 결과가 아니라 점검 결과를 나누기 위한 제안입니다. 조합 중에 보이던 글자와 입력을 마친 뒤의 글자가 다르면 입력기 쪽 문제로 적으세요. 에디터 본문에서는 정상이고 에이전트 입력란에서만 다르면 입력란의 처리 문제로 분류합니다. 기록에는 운영체제 버전, 입력기 이름, 제품 종류와 버전, 실패한 단계를 함께 남기면 다음 점검에서 같은 조건을 재현할 수 있습니다.

편집 메모#

편집 메모 (2026-11-02): 제품 구분과 한국어 UI·실행 권한·가격 조건 FAQ를 보충했습니다. 실제 설치·한글 UI·터미널 화면과 권한 승인 기록은 여전히 필요합니다.