파이(Pi) 설치가이드 — 터미널 AI 코딩 에이전트

작성일: 2026-08-01 (패키지 버전·설치 명령·인증 방식은 이 날짜 기준 npm 레지스트리와 공식 저장소 문서에서 확인)
대상: Windows 10 / Windows 11, 터미널을 처음 열어 보는 분
선행: 공통 준비 완료 (Node.js + Git for Windows)
소요 시간: 15~20분

빠른 설치 (아는 사람용 — 5분)

1. 실습 폴더로 이동

cd "$env:USERPROFILE\Desktop\AX실습"

2. 전역 설치 (일반 PowerShell 창에서. 1~3분 소요)

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

3. PowerShell을 닫고 새로 연 뒤 버전 확인

pi --version

4. 실습 폴더에서 실행

pi

5. 파이 입력창에서 로그인 → 목록에서 제공사 선택

/login

6. 모델 선택

/model

막히면: 'pi' 용어가 ... 인식되지 않습니다 → 문제 해결 A / 401·Invalid API key → 문제 해결 D / bash 오류 → 문제 해결 E

터미널이 처음이면 아래 상세 절차로 내려가세요.

1. 이 도구는 무엇인가

파이(Pi)는 터미널(검은 화면)에서 대화하듯 지시하면 내 컴퓨터의 폴더에 있는 파일을 직접 읽고 고쳐 주는 오픈소스 AI 에이전트입니다. 채팅창에 파일을 하나씩 올리는 대신 "이 폴더를 봐"라고 말하면 됩니다.

기본 도구는 딱 네 가지 — read(읽기), write(만들기), edit(수정), bash(명령 실행).

법률 업무 예시: 실습 폴더에 가상 계약서 5건을 넣고 "이 폴더의 계약서에서 손해배상 예정액 조항만 뽑아 비교표를 만들어 비교표.md 로 저장해 줘" 라고 지시하면, 파이가 파일을 하나씩 읽고 표를 만들어 새 파일로 저장합니다.

파이를 쓰기 전 반드시 알아야 할 보안 사실

공식 보안 문서에 명시된 내용입니다. 변호사 업무 특성상 특히 중요합니다.

• 파이에는 샌드박스(격리 장치)가 없습니다. 원문: *"Pi does not include a built-in sandbox."* 내장 도구는 파이를 실행한 사용자 계정의 권한 그대로 파일을 읽고, 쓰고, 고치고, 셸 명령을 실행합니다.
• 즉 내 Windows 계정이 볼 수 있는 파일이면 원칙적으로 다 볼 수 있습니다. 실제 사건 폴더도 포함됩니다.
• 파이가 읽는 파일에 숨겨진 지시문이 있으면 그대로 따를 수 있습니다(프롬프트 인젝션). 공식 문서도 이를 "예상되는 로컬 에이전트 위험" 이라고 표현합니다.

이 교육에서 지키는 규칙

1. 파이는 항상 바탕 화면\AX실습 안에서만 실행합니다. 실행 위치가 파이의 기본 작업 범위입니다.
2. 실습 폴더에는 가상 자료만 넣습니다. 실제 의뢰인 이름·주민등록번호·사건번호가 담긴 파일은 복사해 오지 않습니다.
3. 출처를 모르는 파일·폴더에서는 파이를 실행하지 않습니다.
4. 파이가 파일을 고치겠다고 할 때 무엇을 고치는지 읽고 승인합니다. Enter를 습관적으로 연타하지 않습니다.

2. 설치 전 확인

Git for Windows가 왜 필수인가: 파이의 bash 도구는 Windows에서 bash 셸을 찾아 명령을 실행합니다. 공식 Windows 문서가 찾는 순서는 ①설정 파일의 사용자 지정 경로 ②C:\Program Files\Git\bin\bash.exe ③PATH 상의 bash.exe(Cygwin/MSYS2/WSL) 이며, 문서는 "대부분의 사용자에게는 Git for Windows로 충분하다"고 안내합니다. 없으면 파이는 설치되지만 bash 도구가 동작하지 않습니다.

3. 설치 절차

① 실습 폴더로 이동

[시작] → PowerShell 입력 → Enter. 그다음 아래를 붙여넣고 Enter.

cd "$env:USERPROFILE\Desktop\AX실습"

② 선행 조건 재확인

여기서 걸러야 나중에 헤매지 않습니다. 한 줄씩 실행합니다.

node -v

git --version

https://git-scm.com/download/win

③ 파이 설치

아래 한 줄을 붙여넣고 Enter. (관리자 권한 아닌 일반 창에서 실행하세요.)

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

명령의 두 옵션: -g 는 어느 폴더에서든 pi 라고 칠 수 있게 하는 전역 설치, --ignore-scripts 는 설치 중 의존 패키지의 자동 실행 스크립트를 돌리지 않는 안전 옵션입니다. 공식 README가 제시하는 설치 명령 그대로이며, 파이는 이 스크립트 없이도 정상 동작합니다.
2026-08-01 기준 최신은 0.83.0(2026-07-29 배포). 위 명령은 항상 최신을 설치하므로 번호가 더 높아도 정상입니다.

④ 터미널 새로 열기

PowerShell 창을 닫고(오른쪽 위 X) [시작] → PowerShell → Enter 로 새로 엽니다. pi 명령의 위치가 방금 등록되었기 때문에 기존 창은 아직 그것을 모릅니다.

새 창에서 다시 실습 폴더로 이동합니다.

cd "$env:USERPROFILE\Desktop\AX실습"

4. 설치 확인 (30초)

pi --version

5. 초기 설정·연동

① 파이 실행

실습 폴더에 있는지 pwd 로 확인한 뒤 아래를 입력합니다.

pi

파이 화면에서 빠져나오려면 /quit 을 입력하거나 Ctrl+C를 두 번 누릅니다.

② 로그인

파이 입력창에 아래를 입력하고 Enter.

/login

API 키 입력 시 지킬 것

• 붙여넣을 때 키 앞뒤에 공백이나 줄바꿈이 딸려 오지 않았는지 확인 — 인증 실패 원인 1위입니다.
• 키를 메신저·메일·워드 문서·교육 자료 여백에 옮겨 적지 않습니다. 보관 위치(예: "1Password > AX교육")만 메모합니다.
• 화면 공유·녹화 중에는 입력하지 않습니다. 입력해야 하면 공유를 잠시 멈춥니다.
• 실습이 끝나면 발급처에서 키를 폐기(revoke) 합니다.

키는 어디에 저장되나: 로그인 정보는 아래 파일에 저장됩니다. 절대 공유·첨부하지 마세요. 키 자체를 넘겨주는 것과 같습니다.

탐색기 주소창에 붙여넣기복사

C:\Users\본인이름\.pi\agent\auth.json

③ 모델 선택

/model

6. 첫 동작 테스트 (1분)

가상 정보로만 진행합니다.

① 연습용 파일 두 개 만들기

파이 화면이면 /quit 로 나옵니다. PowerShell에서 아래를 하나씩 실행합니다.

"제1조(목적) 본 계약은 홍길동(갑)과 김철수(을) 간 사무용품 납품에 관한 사항을 정한다.
제7조(손해배상) 을이 납기를 지연한 경우 지연일수 1일당 계약금액의 0.1%를 갑에게 지급한다." | Out-File -Encoding utf8 "계약서A.txt"

"제1조(목적) 본 계약은 홍길동(갑)과 이영희(병) 간 소프트웨어 유지보수에 관한 사항을 정한다.
제9조(손해배상) 병의 귀책으로 손해가 발생한 경우 배상액은 직전 3개월 대금을 한도로 한다." | Out-File -Encoding utf8 "계약서B.txt"

② 파이 실행

pi

③ 파이에게 지시

파이 입력창에 아래를 그대로 붙여넣고 Enter.

이 폴더의 계약서A.txt 와 계약서B.txt 를 읽고, 두 계약의 손해배상 조항을 비교하는 표를 만들어 비교표.md 파일로 저장해 줘.

④ 알아두면 좋은 조작

대화 기록은 자동 저장됩니다 — 아래 폴더에 남습니다. 실습에서 무엇을 입력했는지 남는다는 뜻이니, 실제 사건 정보를 입력하지 마세요.

탐색기 주소창에 붙여넣기복사

C:\Users\본인이름\.pi\agent\sessions\

7. 문제 해결

A. 'pi' 용어가 ... 인식되지 않습니다

전체 문구: pi : 'pi' 용어가 cmdlet, 함수, 스크립트 파일 또는 실행할 수 있는 프로그램 이름으로 인식되지 않습니다.

• 원인: ①설치 후 PowerShell을 새로 열지 않았거나 ②npm 전역 폴더가 PATH에 없거나 ③설치가 실제로 실패했습니다.

• 해결:

  1. PowerShell 창을 모두 닫고 새로 엽니다 → pi --version 재확인.
  2. 안 되면 설치 여부를 확인합니다.

npm list -g --depth=0

npm config get prefix

출력된 경로(보통 C:\Users\본인이름\AppData\Roaming\npm)가 PATH에 없는 것입니다. PC를 재부팅하면 대부분 해결됩니다. 그래도 안 되면 교육 담당자에게 문의하세요.

B. npm ERR! code EACCES / EPERM: operation not permitted

• 원인: 전역 설치 폴더에 쓸 권한이 없거나, 회사 백신·EDR이 npm의 파일 쓰기를 실시간 차단하고 있습니다.

• 해결:

  1. PowerShell을 완전히 닫고, 시작 메뉴에서 PowerShell 을 찾아 마우스 오른쪽 → "관리자 권한으로 실행" 으로 다시 연 뒤 설치 명령을 재시도합니다. (전역 설치는 사용자 프로필 밖 폴더에 파일을 쓸 수 있고, 그 폴더가 일반 권한으로 잠겨 있을 수 있습니다.)
  2. 같은 오류면 백신 차단입니다. 백신을 임의로 끄지 마세요. IT 담당자에게 오류 문구를 그대로 전달하고 %AppData%\npm 폴더 예외 등록을 요청하세요.
  3. 다른 프로그램이 파일을 잡고 있는 경우도 있습니다. PC 재부팅 후 재시도.

C. npm ERR! code ETIMEDOUT / network request ... failed

• 원인: 사내 프록시·방화벽이 npm 저장소를 막았거나 회선이 일시적으로 끊겼습니다. 컴퓨터가 망가진 게 아닙니다.

• 해결:

  1. 같은 명령을 그대로 다시 실행합니다. ↑ → Enter. 설치 명령은 여러 번 재실행해도 안전합니다.
  2. 계속 실패하면 휴대폰 테더링으로 네트워크를 바꿔 재시도 — 교육장에서 가장 확실한 방법입니다.
  3. 그래도 안 되면 캐시를 비우고 재시도합니다.

npm cache clean --force

D. Invalid API key / 401 Unauthorized / authentication failed

• 원인: ①키 앞뒤에 공백·줄바꿈이 함께 들어갔거나 ②키가 만료·폐기되었거나 ③선택한 제공사와 키 발급처가 다릅니다.

• 해결:

  1. 파이 안에서 저장된 인증 정보를 지웁니다.

/logout

1. 다시 로그인합니다.

/login

1. 키를 붙여넣기 전에 메모장에 한 번 붙여넣어 앞뒤 빈칸·줄바꿈이 없는지 눈으로 확인한 뒤, 키 부분만 다시 복사해 입력합니다. (확인 후 메모장은 저장하지 말고 닫습니다.)
2. 제공사 선택이 맞는지 확인합니다. Anthropic 키를 OpenAI 항목에 넣으면 같은 오류가 납니다.
3. 그래도 실패하면 키가 만료·소진되었을 수 있습니다. 교육 담당자에게 새 키를 요청하세요. 오류 문구만 전달하고 키 값 자체는 메신저에 보내지 마세요.

E. 파이가 명령을 실행하려다 실패한다 / bash 관련 오류

• 증상: 파이가 bash 도구를 쓰는 순간 셸을 찾지 못했다는 오류가 나거나, 명령 실행 결과가 비어서 돌아옵니다.
• 원인: Windows에는 bash가 기본 탑재되어 있지 않습니다. 파이는 ①설정의 사용자 지정 경로 → ②C:\Program Files\Git\bin\bash.exe → ③PATH 상의 bash.exe 순으로 찾는데, Git for Windows가 없으면 셋 다 실패합니다.

• 해결:

  1. 아래에서 Git for Windows를 설치합니다 (기본값 그대로 Next 연타).

https://git-scm.com/download/win

1. PowerShell을 닫고 새로 연 뒤 확인합니다.

Test-Path "C:\Program Files\Git\bin\bash.exe"

{ "shellPath": "D:\\Git\\bin\\bash.exe" }

F. 파이가 실습 폴더 밖의 파일을 건드리려 한다

• 증상: 파이가 C:\Users\본인이름\Documents\... 등 실습 폴더 밖 경로를 읽거나 고치겠다고 제안합니다.
• 원인: 파이에는 샌드박스가 없습니다. 내 계정 권한으로 접근 가능한 파일이면 범위 밖이라도 손댈 수 있습니다. 실습 폴더 밖에서 실행했거나 지시문에 그런 경로가 섞였을 수 있습니다.

• 해결:

  1. 승인하지 말고 거절합니다. 확신이 없으면 Ctrl+C 두 번으로 즉시 종료하세요.
  2. pwd 로 위치를 확인하고 실습 폴더로 이동한 뒤 다시 실행합니다.

cd "$env:USERPROFILE\Desktop\AX실습"

1. 실제 사건 폴더가 열려 있었다면 어떤 파일이 읽혔는지 확인하고 교육 담당자·정보보호 담당자에게 알립니다.

8. 제거·연동 해제

1) 로그인 정보 먼저 지우기 — 파이를 실행한 상태에서:

/logout

2) 발급처에서 키·권한 회수 (가장 중요)

• API 키를 썼다면: 발급처(교육 주관사 또는 제공사 콘솔)에서 그 키를 폐기(revoke) 합니다. 내 PC에서 지우는 것만으로는 키가 살아 있습니다.
• 구독 계정으로 로그인했다면: 해당 서비스의 "연결된 앱"에서 파이의 액세스 권한을 삭제합니다. 구글 계정이면 아래 주소.

https://myaccount.google.com/permissions

3) 파이 제거

npm uninstall -g @earendil-works/pi-coding-agent

4) 제거 확인

pi --version

5) 설정·인증·대화 기록 삭제

Remove-Item -Recurse -Force "$env:USERPROFILE\.pi" -ErrorAction SilentlyContinue

이 폴더에는 auth.json(인증 정보)과 sessions\(대화 기록 전체)가 들어 있습니다. PC를 반납하거나 교육이 끝나면 반드시 지우세요.

6) 실습 자료 정리 — 바탕 화면 AX실습 폴더를 휴지통으로 옮기고 휴지통도 비웁니다.

다른 설치 방법 · 선택 설정

본문의 표준 경로(npm 전역 설치 + /login)로 진행하는 것을 권장합니다. 아래는 해당되는 경우에만 보세요.

① 환경 변수로 키 지정 — /login 대신 ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY 환경 변수로 키를 넘길 수도 있습니다. 다만 키가 시스템 설정에 남아 관리가 어려우므로, 초보자는 /login 만 쓰는 편이 안전합니다.

② Windows Terminal에서 Alt+Enter 되살리기 — Windows Terminal에서는 Alt+Enter가 전체화면 전환에 먼저 걸려 파이의 "후속 질문 대기열" 기능이 동작하지 않습니다. 이 기능을 쓸 때만 설정하세요. 일반 PowerShell 창을 쓰면 건너뛰어도 실습에 지장 없습니다.

1. Windows Terminal에서 Ctrl+Shift+, → settings.json 이 열립니다.
2. 맨 바깥 { } 안에 아래를 추가하고 저장합니다.

"actions": [
  { "command": { "action": "sendInput", "input": "\u001b[13;2u" }, "keys": "shift+enter" },
  { "command": { "action": "sendInput", "input": "\u001b[13;3u" }, "keys": "alt+enter" }
]

1. Windows Terminal을 완전히 닫았다 다시 엽니다. (안 그러면 전체화면 동작이 그대로 남습니다.)

③ bash 셸 경로 직접 지정 — Git을 기본 위치가 아닌 곳에 설치한 경우에만 필요합니다. 문제 해결 E 3번 참고.

관련 문서

• 공통 준비 — Windows 실습 환경 만들기

확인한 공식 출처 (2026-08-01)

• npm 레지스트리 @earendil-works/pi-coding-agent — 최신 0.83.0(2026-07-29), engines.node >=22.19.0, 실행 명령 pi
• GitHub earendil-works/pi — packages/coding-agent/README.md(설치 명령), docs/quickstart.md(첫 실행·기본 도구 4종), docs/providers.md(/login·auth.json·환경 변수), docs/windows.md(bash 셸 탐색 순서·shellPath), docs/terminal-setup.md(Windows Terminal Alt+Enter), docs/security.md(샌드박스 없음), docs/usage.md(CLI 플래그·슬래시 명령)