pi 설치는 복잡하지 않습니다. 명령어 한 줄이면 됩니다. 먼저 결정해야 할 것은 인증 방식입니다. 기존 구독을 사용할지, API Key를 사용할지 선택하면 됩니다. 아래에서 설치, 인증, 첫 대화까지 한 번에 진행해 보겠습니다.
핵심 개념: 두 가지 인증 방식
pi를 설치한 후에는 LLM 서비스 제공업체의 자격 증명이 있어야 작동합니다. 인증 방법은 두 가지이며, 이 차이만 이해하면 됩니다:
구독 로그인（/login）｜API Key
사용 방법｜Claude Pro/Max, ChatGPT Plus/Pro 등의 구독｜서비스 제공업체가 발급한 API Key
요금 부과｜복잡함（구독 한도 + 추가 사용량이 발생할 수 있음）｜토큰 단위, 사용한 만큼 지불
자격 증명 저장 위치｜~/.pi/agent/auth.json（OAuth 토큰, 자동 갱신）｜환경 변수 또는 auth.json
적합한 사용자｜기존 구독이 있고 Key를 별도로 관리하고 싶지 않은 경우｜비용을 정확하게 관리하고 싶은 경우
한 가지 알려 두자면, Anthropic 구독 로그인（Claude Pro/Max）은 서드파티 harness 채널을 사용하며 토큰 단위로 과금됩니다. 구독 요금제의 사용량을 차감하지 않으며, pi에서 경고가 표시되는 것은 정상입니다. 비용을 완전히 통제하고 언제든 사용 금액을 확인하고 싶다면 API Key가 더 편리합니다.
직접 사용해 보기
1. pi 설치
pi는 Node.js에서 실행되며, 22.19.0 이상이 필요합니다. 먼저 node --version 으로 확인하세요. 두 가지 설치 방법 중 하나를 선택하면 됩니다:
# npm 전역 설치（--ignore-scripts는 종속성 스크립트를 건너뛰므로 더 안전함）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 또는 curl 설치 프로그램 사용（Node가 설치되어 있지 않으면 자동으로 설치함）
curl -fsSL https://pi.dev/install.sh | sh설치가 끝나면 pi --version 으로 확인하세요. 제거할 때는 npm uninstall -g @earendil-works/pi-coding-agent를 사용합니다.
2. 인증 설정
방법 1: API Key（권장）, Key를 환경 변수로 설정합니다:
export ANTHROPIC_API_KEY=sk-ant-...
pi또는 pi에서 /login 을 입력하고 API Key provider를 선택한 다음, Key를 ~/.pi/agent/auth.json에 저장할 수 있습니다（권한 0600, 본인만 읽고 쓸 수 있음）. 주요 서비스 제공업체의 환경 변수는 다음과 같습니다:
서비스 제공업체｜환경 변수
Anthropic｜ANTHROPIC_API_KEY
OpenAI｜OPENAI_API_KEY
DeepSeek｜DEEPSEEK_API_KEY
Google Gemini｜GEMINI_API_KEY
Groq｜GROQ_API_KEY
xAI｜XAI_API_KEY
OpenRouter｜OPENROUTER_API_KEY
전체 목록은 수십 곳에 이르며, 공식 Providers 문서[1]에서 확인할 수 있습니다.
방법 2: 구독 로그인, Claude Pro, ChatGPT Plus 등의 구독이 있다면 pi에서 /login 을 입력하고 해당 provider를 선택한 뒤 OAuth 절차를 진행하세요. 토큰이 만료되면 pi가 자동으로 갱신합니다. 선택 가능한 항목: Claude Pro/Max, ChatGPT Plus/Pro(Codex), GitHub Copilot, xAI, OpenRouter. 로그아웃할 때는 /logout을 사용합니다.
Pi 커뮤니티는 매우 활발하며, 최신 Pi Agent는 이미 천문의 token plan도 지원합니다.
모델 설정을 마치면 /model 을 사용해 원하는 모델을 선택할 수 있습니다.
Pi Agent에는 scoped models라는 개념도 있습니다.
이 scoped models는 사용자가 여러 모델 사이를 ctrl + p 로 빠르게 전환할 수 있도록 해 줍니다. 또는 ctrl + l 을 사용해 선택할 수도 있습니다. 관련 설정은 ~/.pi/agent/settings.json 파일의 enabledModels 필드에 있습니다.
3. 첫 실행
프로젝트 디렉터리로 이동해 실행합니다:
cd /path/to/your/project
pi처음으로 .pi/ 구성이 포함된 프로젝트에 들어가면 pi가 신뢰 여부를 묻습니다. 프로젝트 수준 리소스에는 임의의 코드를 실행할 수 있는 확장 기능이 포함될 수 있으므로, pi는 사용자가 모르는 상태에서 이를 로드하지 않습니다. 신뢰 결정은 ~/.pi/agent/trust.json에 저장되며, 다음부터는 다시 묻지 않습니다.
화면은 위에서부터 네 부분으로 나뉩니다: Header（단축키/로드된 리소스）, Messages, Editor（입력하는 곳, 테두리 색상=사고 단계）, Footer（디렉터리/세션/token 사용량/비용/현재 모델）. 바로 입력하고 Enter를 누르면 됩니다. 예:
이 저장소의 구조를 살펴보고 검사를 실행하는 방법을 알려 줘.pi는 기본적으로 모델에 네 가지 도구를 제공합니다: read, write, edit, bash. 그 밖의 읽기 전용 도구 세 가지 grep/find/ls 는 기본적으로 비활성화되어 있으며, 필요할 때 --tools 로 활성화할 수 있습니다. 예를 들어 pi가 읽기만 하며 코드 리뷰를 수행하게 하려면:
pi --tools read,grep,find,ls -p "이 저장소의 코드 품질을 검토해 줘"모델 전환은 Ctrl+L 또는 /model을 사용하고, 종료는 Ctrl+C를 두 번 누르거나 /quit을 입력합니다. 이전 대화를 이어서 하려면 pi -c를 사용하세요.
원리 이해하기
인증 확인 순서: 환경 변수, auth.json, 명령줄 인자를 동시에 설정한 경우 pi는 명령줄 --api-key > auth.json > 환경 변수 > models.json 순서로 사용합니다. 임시로 다른 Key를 테스트하려면 pi --api-key xxx를 직접 실행하면 되며, 구성 파일은 변경되지 않습니다.
프로젝트 신뢰는 입력 보호 장치이지 샌드박스가 아닙니다: 대화형 실행 시에만 팝업이 표시됩니다. 비대화형 모드（pi -p）에서는 기본적으로 ask가 적용되며, -a/-na 로 덮어쓸 수 있습니다. pi에는 기본 샌드박스가 없으므로 모델이 bash를 사용할 수 있으면 어떤 명령이든 실행할 수 있습니다. 신뢰할 수 없는 저장소를 다룰 때는 컨테이너 격리를 사용해야 하며, 이는 이후 보안 편에서 다룹니다.
자주 묻는 질문
Q:pi --version 을 실행했더니 command not found가 표시되지만 npm에서는 설치되었다고 합니다.
대부분 npm 전역 bin 디렉터리가 PATH에 포함되어 있지 않은 경우입니다. npm prefix -g 로 경로를 확인해 PATH에 추가하세요. nvm 사용자는 nvm use도 잊지 마세요.
Q: 시작할 때 Node 버전이 너무 낮다고 표시됩니다.
pi에는 Node 22.19.0 이상이 필요합니다. 버전 관리 도구（fnm/mise/nvm）로 업그레이드하거나 curl 설치 프로그램을 사용하세요.
Q: Claude Pro에 로그인한 후 매번 추가 사용량 경고가 표시됩니다.
Anthropic 구독은 서드파티 채널을 통해 토큰 단위로 과금됩니다. 경고를 끄려면 ~/.pi/agent/settings.json에 다음을 추가하세요:
{ "warnings": { "anthropicExtraUsage":false } }Q: Shift+Enter로 줄을 바꿀 수 없습니다.
pi는 Kitty 키보드 프로토콜을 사용해 수정 키를 인식합니다. iTerm2, Kitty, Ghostty는 별도 설정 없이 사용할 수 있으며, VS Code 1.109.5+도 기본적으로 지원합니다. Windows Terminal, WezTerm, Alacritty는 키 입력 전달 설정을 수동으로 한 줄 추가해야 합니다. 터미널 설정 문서[2]를 참고하세요.
Q: 완전히 오프라인으로 사용하고 싶어 pi.dev의 업데이트 확인도 차단하고 싶습니다.PI_OFFLINE=1은 시작 시 수행되는 모든 네트워크 작업을 끕니다. 버전 확인만 끄려면 PI_SKIP_VERSION_CHECK=1을 사용하세요.
참고 자료
• Pi 빠른 시작 문서[3]
• Pi Providers 문서[1] - 모든 Provider, 환경 변수, 클라우드 제공업체 구성
• Pi Custom Models 문서[4] - models.json으로 Provider 사용자 지정
• Pi Settings 문서[5]
• Pi Terminal Setup[2] - 터미널별 키 설정
• Pi GitHub 저장소[6]
인용 링크
[1] 공식 Providers 문서: https://pi.dev/docs/latest/providers[2] 터미널 설정 문서: https://pi.dev/docs/latest/terminal-setup[3] Pi 빠른 시작 문서: https://pi.dev/docs/latest/quickstart[4] Pi Custom Models 문서: https://pi.dev/docs/latest/models[5] Pi Settings 문서: https://pi.dev/docs/latest/settings[6] Pi GitHub 저장소: https://github.com/earendil-works/pi