Pi Coding Agent 설치 가이드 2026: npm 설치, API Key, Claude/GPT/Gemini TypeScript 실전

왜 "또 하나의 IDE Agent"로는 멀티 모델을 해결할 수 없는가

2026년 대부분 팀의 고통은 "Agent가 없다"가 아니라, 키·모델·실행 환경이 한 제품에 묶여 있다는 점이다. Claude Code는 Anthropic 구독을 먹고, Codex CLI는 ChatGPT를 먹고, Cursor는 모델 선택을 에디터 계정 안에 숨긴다. 오후에는 Claude로 아키텍처를 고치고, 저녁에는 Gemini로 테스트를 훑고, 주말에는 GPT로 커밋 메시지를 쓰고 싶은데, 매번 창·권한·컨텍스트를 바꿔야 한다.

Pi는 이 전제를 분해한다. 공식 포지션은 최소 하네스: 기본으로 모델에 read, write, edit, bash 네 도구만 준다. sub-agent, plan mode, 권한 게이트, MCP처럼 "남들이 내장한 기능"은 확장, Skills, Pi Package로 바꾸고, 워크플로에 맞춰 직접 더한다. 모델은 교체 가능한 백엔드이지, 제품의 본체가 아니다.

비대칭 결론은 이것이다: 분수령은 Claude, GPT, Gemini 중 누가 더 강한가가 아니라, 하네스가 모델을 교체 가능한 실행 백엔드로 다루고 자신의 TypeScript 프로젝트에 넣을 수 있느냐다. 업그레이드해야 할 것은 입구(CLI / SDK / RPC), 자격증명 계층, 상시 실행 노드이지, 또 하나의 더 두꺼운 IDE가 아니다. 하네스가 무엇인지는 Omnigent Agent Harness 완전 이해에서 개념을 분해한다. 이 글은 "Pi를 설치하고, 세 제공자 키를 연결하고, 저장소에 넣는 방법"만 다룬다.

Pi란 무엇인가: 최소 하네스의 네 가지 입구

먼저 분류하고, 그다음에 명령을 본다. Pi는 또 하나의 채팅 창이 아니라, 같은 Agent 루프를 여는 네 가지 방식이다. 분류 기준은 여전히 입구·실행·컨텍스트·적합한 사용자층이다.

공식 사이트는 철학을 짧게 적는다: 하네스를 바꾸고, 워크플로는 바꾸지 마라. 확장은 TypeScript 모듈이며 도구, 슬래시 명령, 단축키, TUI 위젯을 등록할 수 있다. Skills는 필요할 때 로드되어 처음부터 프롬프트 캐시를 부풀리지 않는다. 패키지는 pi install npm:@scope/pkg 또는 pi install git:host/user/repo로 넣는다. 전체 능력 목록은 pi.dev와 npm 패키지 설명을 따른다. 버전 번호는 바뀌고, "어느 달의 모델 이름"보다 명령 형태가 더 안정적이다.

Pi vs 폐쇄형 Agent: 입구·실행·컨텍스트

선택할 때 "Claude가 센가, GPT가 센가"부터 물으면 진짜 차이를 놓친다. Pi, 공식 CLI, IDE Agent를 같은 표에 올려 입구·실행·컨텍스트·적합한 사용자로 정렬하면, 결론은 거의 즉시 뒤집힌다. 순위 기사는 2026년 최고의 AI 코딩 에이전트 순위를 보라. 이 글은 순위를 다시 매기지 않는다. "키를 제품에서 분리할 것인가"만 답한다.

원격 Mac에서 Claude Code와 Codex를 고르는 문제는 Claude Code vs Codex: 원격 Mac 개발 환경을 보라. 그 글은 "공식 CLI를 어떻게 고를까"를 답한다. 이 글은 "이미 멀티 모델과 TypeScript에 루프를 넣기로 정했을 때, 하네스를 어떻게 설치할까"를 답한다.

npm 설치와 API Key 설정

전역 CLI: 먼저 대화가 되게 하고, 그다음에 임베드한다

공식은 --ignore-scripts를 붙인 전역 설치를 권한다. Pi의 정상 사용은 의존 패키지의 install 라이프사이클 스크립트에 기대지 않는다. 스크립트를 건너뛰면 공급망 사고를 줄일 수 있다. Node 버전은 로컬 LTS를 따른다. 저장소가 선언한 엔진 번호는 패키지와 함께 바뀌므로, 블로그에 적힌 마이너 버전을 계약처럼 쓰지 마라.

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 또는: pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent
# 또는: bun add -g --ignore-scripts @earendil-works/pi-coding-agent
# 설치기 대안: curl -fsSL https://pi.dev/install.sh | sh
pi --version

설치 후 먼저 두 가지를 확인한다: pi가 PATH에 있는지, 쓰려는 제공자에 키 하나 또는 /login 한 번이 있는지. 자격증명이 없으면 TUI는 열리지만, 모델 카탈로그에서 실행 가능한 항목은 비어 있다.

키를 계층화하는 법: 환경 변수, auth.json, 일회성 덮어쓰기

공식 자격증명 해석 순서는 이렇다: 커맨드라인 --api-key → ~/.pi/agent/auth.json → 프로세스 환경 변수 → models.json의 커스텀 제공자 키. 인터랙티브에서 /login은 OAuth 또는 API Key를 auth.json에 쓴다(파일 권한 0600). auth.json은 환경 변수보다 우선하며, "이 머신에서 오래 쓸 키"에 맞다. 환경 변수는 CI와 일회성 실험에 맞다. SDK의 setRuntimeApiKey는 프로세스 안 덮어쓰기이며 디스크에 쓰지 않는다. 테스트와 멀티테넌트 호스트에 맞다.

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...   # auth.json 키 이름은 google

pi
# 인터랙티브: /login으로 제공자 선택; /model 또는 Ctrl+L로 전환; Ctrl+S로 시작 기본값 저장

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." }
}

key 필드는 $ENV_VAR 보간과 !op read 'op://…' 같은 명령 값(프로세스 안 캐시)도 지원한다. 원격 또는 헤드리스 머신에서 OpenRouter처럼 브라우저 콜백이 막히면, 공식은 최종 리다이렉트 URL 또는 인가 코드를 로그인 프롬프트에 붙여 넣으라고 한다——SSH 위의 클라우드 Mac에서 특히 흔하다. 제공자 대조표는 providers.md를 따른다.

Claude, GPT, Gemini 연결

Pi는 내장 제공자마다 "도구를 돌릴 수 있는" 모델 카탈로그를 유지한다. 설정된 카탈로그는 자동 갱신되며, pi update --models로 강제 한 번 당길 수 있다. 인증은 구독(Claude Pro/Max, ChatGPT Plus/Pro Codex, GitHub Copilot)이거나 API Key다. 전환은 /model, Ctrl+L이고, 자주 쓰는 모델은 Ctrl+P로 순환한다. /scoped-models가 순환 명단을 정한다.

pi --list-models claude
pi --list-models gpt
pi --list-models gemini

pi --provider anthropic --thinking high "src/ 안의 루프를 테스트 가능한 함수로 바꿔라"
pi --model openai/gpt-4o -p "이 저장소의 진입 모듈을 세 문장으로 요약하라"
pi --provider google -p "읽기 전용: 커버되지 않은 테스트 파일을 나열하라"

# 세션 안에서 전환. 재설치 불필요
# /model   또는 Ctrl+L
# Ctrl+P   scoped 명단에서 순환

모델 ID는 카탈로그가 갱신되면 바뀐다. 공식 예시에 claude-opus-4-5, claude-sonnet-4-5, gpt-4o, gpt-5.1 같은 표기가 나온 적 있다. 실제 적용할 때는 pi --list-models와 SDK의 getAvailable()을 따른다. 블로그 스냅샷 ID를 프로덕션 스크립트에 넣지 마라. 커스텀 게이트웨이(Ollama, vLLM, 사내 프록시)는 ~/.pi/agent/models.json으로 가며, 상대가 OpenAI / Anthropic / Google API 중 하나를 말할 때만 된다. OAuth나 사설 프로토콜은 확장을 쓰고, CLI를 억지로 고치지 마라.

진짜로 필요한 게 "HTTP를 직접 치고 JSON을 직접 파싱하는 것"이라면, 그건 Function Calling 계층이지 하네스 계층이 아니다. Function Calling과 JSON API, GPT-5.6 API 가이드를 대조하라: 그 두 글은 제공자를 직접 친다. 이 글은 Pi가 도구 루프를 대신 관리하고, 백엔드만 바꾸게 한다.

TypeScript 프로젝트 실전

CLI는 "사람이 터미널에서 지휘하는" 문제를 푼다. SDK는 "저장소 안의 스크립트도 지휘하는" 문제를 푼다. SDK는 같은 npm 패키지에 들어 있어 따로 설치하지 않는다. 최소 루프는 이렇다: 로컬 의존성 → 키 세 개는 환경에만 → ModelRuntime으로 모델 선택 → createAgentSession으로 읽기 전용 태스크 하나 → dispose().

npm init -y
npm install @earendil-works/pi-coding-agent
# package.json에 "type": "module"을 추가

import {
  createAgentSession,
  ModelRuntime,
  SessionManager,
} from "@earendil-works/pi-coding-agent";

const runtime = await ModelRuntime.create();

if (process.env.ANTHROPIC_API_KEY) {
  await runtime.setRuntimeApiKey("anthropic", process.env.ANTHROPIC_API_KEY);
}
if (process.env.OPENAI_API_KEY) {
  await runtime.setRuntimeApiKey("openai", process.env.OPENAI_API_KEY);
}
if (process.env.GEMINI_API_KEY) {
  await runtime.setRuntimeApiKey("google", process.env.GEMINI_API_KEY);
}

const preferred =
  runtime.getModel("anthropic", "claude-opus-4-5") ??
  runtime.getModel("openai", "gpt-4o") ??
  (await runtime.getAvailable())[0];

if (!preferred) {
  throw new Error("사용 가능한 모델이 없습니다: 먼저 세 제공자 키 중 하나를 export하거나 pi --list-models를 실행하세요");
}

const { session } = await createAgentSession({
  model: preferred,
  thinkingLevel: "low",
  tools: ["read", "bash"],
  sessionManager: SessionManager.inMemory(),
  modelRuntime: runtime,
});

try {
  session.subscribe((event) => {
    if (
      event.type === "message_update" &&
      event.assistantMessageEvent.type === "text_delta"
    ) {
      process.stdout.write(event.assistantMessageEvent.delta);
    }
  });
  await session.prompt(
    "읽기 전용: 현재 디렉터리의 TypeScript 진입 파일을 나열하고, 테스트가 빠졌을 가능성이 가장 큰 한 곳을 지적하세요. 파일은 수정하지 마세요."
  );
} finally {
  session.dispose();
}

이 코드는 도구를 일부러 read + bash로 줄이고, 세션은 메모리에만 둔다. CI의 리뷰 스크립트는 기본으로 write/edit를 가지면 안 된다. 영속 세션이 필요하면 SessionManager.create(process.cwd())로 바꾼다. CLI와 같은 장기 키를 쓰려면 setRuntimeApiKey를 호출하지 말고, runtime이 ~/.pi/agent/auth.json을 읽게 하라. 커스텀 auth 경로가 필요하면 authPath / modelsPath를 앱 자체 디렉터리로 가리켜, 여러 서비스가 같은 홈 파일을 뺏지 않게 한다. SDK 이벤트, 조향(steer), 후속(followUp) 의미는 sdk.md를 본다.

AGENTS.md: 저장소 규칙을 모든 모델에 쓴다

Pi는 기동 때 ~/.pi/agent/AGENTS.md, 부모 디렉터리, 현재 디렉터리의 AGENTS.md(또는 CLAUDE.md)를 이어 붙인다. 어떤 층에 AGENTS.override.md가 있으면 그 층은 덮어쓰기 파일만 로드한다. 이것이 "모델은 바꾸고 규칙은 바꾸지 않는" 착지점이다: Claude, GPT, Gemini가 같은 진입점, 테스트 명령, 레드라인을 읽는다. 시스템 프롬프트를 바꾸려면 .pi/SYSTEM.md, 추가하려면 APPEND_SYSTEM.md.

# 이 저장소가 Pi에 주는 규칙
- 패키지 관리: npm. 마음대로 pnpm으로 바꾸지 말 것.
- 검사: npm test && npm run lint
- 레드라인: .env, auth.json, *.pem을 커밋하지 말 것
- 기본은 읽기 전용. 사용자가 "파일을 수정해도 된다"고 분명히 말할 때만 write/edit

헤드리스 CI는 프로젝트 신뢰 대화 상자를 띄우지 않는다. 저장된 trust 결정이 없으면 비대화형 모드는 전역 defaultProjectTrust를 따른다: ask(기본)와 never는 프로젝트 단위 .pi/ 자원을 무시하고, always만 신뢰한다. 한 번만 덮어쓰려면 --approve / --no-approve. 자체 러너에 Pi를 넣을 때는 신뢰 정책을 머신 이미지에 먼저 쓰고, 그다음에 모델을 이야기한다. GitHub Actions와 클라우드 Mac runner 계층은 GitHub Actions macOS 자체 러너와 클라우드 Mac을 보라.

시나리오별 선택법

진짜로 물어야 할 것은 "Pi를 설치할 것인가"가 아니라, 첫 번째 제약이다: 인터랙티브로 코드를 고칠 것인가, Agent를 스크립트로 쓸 것인가, 아니면 한 집 공식 CLI의 상자 밖 경험만 필요한가.

"클라우드 Mac이 왜 Agent 실행 계층인가"는 Cloud Mac가 2026 iOS 개발 표준이 된 이유를 보라. 이 글이 보태는 것은 그 노드 위의 한 층이다: npm, 키, 모델 전환, TypeScript 스크립트.

추천 조합

도구를 겹쳐 써도 된다. Pi가 푸는 것은 "교체 가능한 모델의 코딩 하네스"다. 뚜껑을 닫지 않는 Mac을 주지도, 세 집 청구서를 대신 내주지도 않는다.

• 개인 일상 조합: 전역 pi + 기본으로 ANTHROPIC_API_KEY + 나머지 두 키는 예비 + 저장소 AGENTS.md. 인터랙티브에서 Ctrl+L로 모델을 바꾸고, 규칙은 바꾸지 않는다.
• TypeScript 저장소 조합: 전역 CLI는 사람이 쓰고, devDependencies에 SDK를 한 번 더 넣어 스크립트가 쓴다. 리뷰는 읽기 전용 도구; 파일 수정은 사람 확인이 있는 명령을 따로 연다.
• CI 조합: pi -p 또는 SDK 스크립트 + GitHub Actions Secrets + 자체 macOS runner. 신뢰 정책은 --approve로 고정하고, 로그에 키를 찍지 마라.
• 멀티 제공자 게이트웨이 조합: OpenRouter / Cloudflare AI Gateway 키 하나로 여러 모델을 친다. 전환은 여전히 Pi의 /model을 쓴다. 머신마다 원제조 키 세 개를 흩뿌리고 싶지 않은 팀에 맞다.
• 최소 검증 조합: CLI만 설치하고, 키 하나만 export한 뒤 pi -p "현재 디렉터리의 ts 파일을 나열하라"를 돌린다. 네 박자(설치→자격증명→태스크 하나→재현 가능)를 통과시킨 뒤에 두 번째 모델과 SDK를 더한다.

멀티 에이전트 수업이나 IM 분신은 Pi의 주 무대가 아니다. 그런 일은 편성과 게이트웨이가 필요하고, OpenMAIC와 멀티 에이전트 협업 시대를 보라. Pi는 "같은 읽기·수정·실행 루프를, 백엔드만 바꿔 계속 돌리는" 쪽에 맞다.

자주 하는 오해

• Pi를 Claude Code의 무료 클론으로 이해한다. sub-agent와 plan mode는 일부러 없다. 필요한 기능은 확장 또는 Package로 더하고, "코어가 너무 말랐다"고 불평한 뒤 다음 IDE를 기다리지 마라.
• 키 세 개를 git에 올라갈 dotenv 하나에 밀어 넣는다. 개발 머신은 셸 프로필 또는 1Password; CI는 Secrets; 공유 머신은 0600의 auth.json. SDK runtime key는 디스크에 쓰지 않으며, 머신 자격증명을 대체하지 않는다.
• 블로그의 모델 ID를 프로덕션에 박아 넣는다. 카탈로그는 갱신된다. 스크립트는 getAvailable() 또는 --list-models를 쓰고, 안정적인 provider 접두사로 폴백한다.
• CI에서 Agent에게 기본으로 write/edit를 준다. 리뷰와 점검은 읽기 전용 화이트리스트; 파일 수정은 사람 문턱을 따로 연다.
• 헤드리스 모드인데 trust 대화 상자가 뜨기를 바란다. 먼저 defaultProjectTrust를 쓰거나 --approve를 넘겨라. 그렇지 않으면 프로젝트 Skills가 로드되지 않는다.
• 슬립하는 노트북에서 장시간 SDK 태스크를 돌린다. 세션 트리는 복구할 수 있지만, 슬립이 중간에 끊은 bash의 부작용은 자동으로 롤백되지 않는다. 장시간 태스크는 상시 노드에 둔다.

도입 단계

1. 타협 불가 항목을 적는다: 인터랙티브만, 스크립트만, 아니면 둘 다; 첫 주에 세 모델을 동시에 붙여야 하는가; CI가 디스크에 써도 되는가.
2. CLI를 설치하고 한 번 공회전한다: npm install -g --ignore-scripts @earendil-works/pi-coding-agent, pi --version, PATH 확인.
3. 키 하나만 붙인다: export 또는 /login, pi -p "현재 디렉터리를 나열하라". 검수 기준은 "재현 가능"이지 "답변이 더 길다"가 아니다.
4. 두 번째, 세 번째를 붙인다: OPENAI_API_KEY / GEMINI_API_KEY를 보태고, /model 또는 --provider로 같은 프롬프트를 각 한 번씩 돌린다. 규칙이 모델 성격이 아니라 AGENTS.md에서 오는지 확인한다.
5. SDK를 저장소에 쓴다: 프로젝트 의존성 + 읽기 전용 scripts/pi-review.ts 하나. 도구 화이트리스트는 코드에 고정한다.
6. 실행 환경을 고른다: 로컬 시험은 괜찮다. CI와 장시간 태스크는 상시 클라우드 Mac 또는 자체 러너에 두고, 로그는 마스킹하고, 키는 아티팩트에 넣지 않는다.
7. 그다음에 확장과 관측을 더한다: plan mode / MCP / 권한 게이트가 필요할 때 Package를 설치한다. 사용량, 실패 폴백, 사람 인수부터 잰 뒤에 능력을 넓힌다.

FAQ

Pi Coding Agent와 Claude Code는 어떤 관계인가요?

Claude Code는 Anthropic의 공식 코딩 워크플로이며, 모델과 입구가 함께 묶여 있다. Pi는 서드파티 최소 하네스로, Anthropic 키 또는 Claude 구독을 쓸 수 있고 OpenAI와 Gemini도 동시에 붙일 수 있다. "공식 딥 통합"을 대체하지 않는다. 대체하는 것은 "모델을 바꾸면 도구 세트 전체를 바꿔야 하는" 상황이다.

Claude, GPT, Gemini를 꼭 동시에 설정해야 하나요?

아니다. 키 하나만으로 설치 검수는 통과한다. 두 번째 키의 의미는 같다: 같은 AGENTS.md와 도구 화이트리스트를 두고, 태스크에 따라 백엔드를 바꾼다. 두 번째 청구서가 없으면 "멀티 모델"을 위해 운영면을 넓히지 마라.

전역 npm 설치와 프로젝트 SDK가 충돌하나요?

같은 명령을 뺏지는 않지만, 버전은 어긋날 수 있다. 약속은 이렇다: 사람은 전역 CLI, 스크립트는 프로젝트 package.json 버전을 잠근다. 둘 다 같은 ~/.pi/agent를 읽을 때, 스크립트의 runtime key가 머신의 장기 키를 덮어쓰지 않게 주의한다.

Gemini 환경 변수가 왜 GOOGLE_API_KEY가 아닌가요?

공식 표는 Gemini API Key를 GEMINI_API_KEY로 적고, auth.json 키 이름은 google이다. Vertex는 ADC와 프로젝트/리전 변수를 쓰며, AI Studio Gemini 키와 같은 길이 아니다. providers.md를 따르고, 상식으로 키 이름을 추측하지 마라.

Windows / 헤드리스 클라우드 Mac에도 설치할 수 있나요?

된다. npm 전역 패키지는 크로스 플랫폼이고, 공식 사이트에 install.sh와 PowerShell 설치기도 있다. 헤드리스 머신은 pi -p, RPC, SDK를 쓰고 TUI에 기대지 마라. OpenRouter 같은 OAuth는 SSH에서 콜백을 붙여 넣어야 한다. 클라우드 Mac에서는 Node 버전, PATH, auth.json 권한을 먼저 고정하는 편이 맞다.

왜 클라우드 Mac이 또 필요한가요? 로컬에 npm만 설치하면 안 되나요?

로컬은 명령을 배우기에 충분하다. 야간 리뷰, 뚜껑을 닫은 뒤의 장시간 수정, Xcode / 서명과 같은 환경의 CI를 돌리기에는 부족하다. Pi는 모델을 분리했지만, bash와 파일 도구는 여전히 그 프로세스가 돌아가는 머신에 묶여 있다.

정리

Pi Coding Agent 설치 가이드는 겉으로 npm, 환경 변수, 세 모델 ID다. 실제로 착지해야 하는 것은 한 줄의 계층이다: 하네스와 모델을 분리하고, 키와 저장소를 분리하고, 인터랙티브 입구와 스크립트 입구를 분리한다. 2026년 9월에 설 수 있는 쓰임새는 이렇다. 전역 CLI는 사람에게, SDK는 저장소에, AGENTS.md는 모든 백엔드에, 상시 노드는 장시간 태스크에.

비대칭 결론은 그대로다: 분수령은 Claude, GPT, Gemini 중 누가 더 강한가가 아니라, 모델을 교체 가능한 백엔드로 다룰 수 있느냐다. 먼저 키 하나의 pi -p 한 번을 통과시키고, 그다음에 두 번째 모델과 TypeScript 스크립트를 더한다. 실행면이 필요하면 프로세스를 슬립하는 노트북에서 클라우드 Mac으로 옮긴다. 업그레이드해야 할 것은 입구·자격증명·노드이지, 또 하나의 IDE Agent가 아니다.