Pi 설치 및 OmniProxy 설정

Pi는 명령줄에서 직접 대화하고, 파일을 읽고, 작업을 수행하는 작은 터미널 어시스턴트입니다. 시스템 프롬프트가 짧고 기본 도구도 많지 않습니다. 다른 명령어, 워크플로 또는 인터페이스가 필요하면 확장을 통해 추가할 수 있습니다. 확장은 Pi에 기능을 추가하는 구성 요소로 볼 수 있으며, 완성한 뒤 다른 사람과 공유할 수도 있습니다.

하위 에이전트는 작업의 일부를 다른 어시스턴트에게 맡기는 기능이며, 계획 모드는 먼저 단계를 정리한 다음 실행을 시작하는 기능입니다. 두 기능 모두 기본으로 제공되지 않지만, Pi가 직접 만들게 하거나 다른 사람이 공유한 패키지를 설치할 수 있습니다.

설치 전 준비

macOS와 Linux에서는 설치 스크립트, 즉 다운로드와 설치를 자동으로 완료하는 명령어 하나를 사용합니다. Windows에서는 Pi 홈페이지에서 제공하는 PowerShell 명령어를 사용합니다. PowerShell은 Windows에 기본으로 포함된 명령줄 환경입니다. Pi를 Windows의 Linux 환경인 WSL에 설치할 수도 있습니다.

npm으로 설치하려면 먼저 Node.js 22.19 이상을 준비해야 합니다. npm은 Node.js와 함께 사용하는 패키지 관리 도구이며, 명령줄에서 Pi를 설치할 수 있습니다.

macOS Linux

install.sh

공식 curl 스크립트
종속성은 설치 프로그램에서 고정함
업데이트에는 pi update 사용

Windows

install.ps1

공식 웹사이트의 PowerShell 명령
Git for Windows에서 Bash 제공
WSL을 사용할 수도 있음

Node가 이미 있음

npm

Node 22.19+ 필요
패키지 이름은 pi-coding-agent
--ignore-scripts 추가

설치 스크립트는 의존성 버전을 고정합니다. npm 설치는 간접 의존성을 고정하지 않으며 --ignore-scripts를 추가해야 합니다.

설치 및 최초 실행

macOS 또는 Linux에서 터미널을 열고 다음을 실행합니다.

curl -fsSL https://pi.dev/install.sh | sh

Windows에서는 PowerShell을 열고 다음을 실행합니다.

powershell -c "irm https://pi.dev/install.ps1 | iex"

Node.js 22.19 이상이 이미 설치되어 있다면 Quickstart의 대체 명령어를 사용할 수도 있습니다.

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

대화형 터미널에서 설치 스크립트가 질문을 표시하며 멈출 수 있으므로 화면 안내에 따라 계속 진행해야 합니다. 요구 사항을 충족하는 Node가 이미 있다면 이 npm 명령어는 질문을 표시하지 않습니다. 다른 디렉터리에 설치하려면 --prefix /설치할/디렉터리를 추가합니다. 2026-10-09 기준으로 이 방법을 사용해 Pi 1.1.0이 설치되었습니다.

일반적인 npm 설치에는 의존성의 수명 주기 스크립트, 즉 패키지 설치 과정에서 자동으로 실행되는 스크립트가 필요하지 않습니다. 설치 스크립트는 의존성 버전을 고정하며, 이후에는 pi update로 업데이트합니다. npm 설치의 업데이트 방법은 사용 중인 패키지 관리자에 따릅니다. Nix 사용자는 Pi의 flake에서 설치합니다. flake는 Nix에서 소프트웨어와 의존성을 기술하는 설정이며, Nix로 설치한 Pi는 pi update로 업데이트할 수 없습니다.

설치가 끝나면 먼저 터미널에서 Pi를 찾을 수 있는지 확인합니다.

pi --version

Windows에서 모델이 Bash 명령어를 실행하게 하려면 대부분의 로컬 사용자에게 Git for Windows 설치를 권장합니다. Bash는 Pi가 일부 명령어를 실행할 때 사용하는 명령 환경입니다. Pi는 ~/.pi/agent/settings.json의 shellPath, Program Files의 Git Bash, PATH에 있는 bash.exe 순서로 찾습니다. shellPath는 Bash의 위치를 지정하고, PATH는 시스템이 명령어를 찾을 때 확인하는 디렉터리 목록입니다.

실행한 뒤 !printf 'Bash is working\n'을 입력해 확인할 수 있습니다. 파일과 도구가 이미 WSL에 있다면 해당 Linux 환경에서 Quickstart에 따라 설치합니다.

다음으로 Pi가 확인하거나 처리할 폴더로 이동한 뒤 실행합니다.

cd /path/to/folder
pi

이 폴더는 Pi의 현재 작업 범위가 되어 파일과 설정을 찾는 데 사용되며, 세션을 그룹화하는 기준으로도 사용됩니다.

OmniProxy에서 연결 정보 가져오기

먼저 OmniProxy에서 다음 세 가지 항목을 준비합니다.

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: 현재 OmniProxy 모델 목록에서 전체 ID 복사

baseUrl은 Pi가 요청을 보내는 API 주소이며 /v1까지 입력해야 합니다. apiKey는 API에 접근할 때 사용하는 키입니다. Model ID는 호출할 모델의 이름이며, 현재 OmniProxy 모델 목록에서 전체 값을 복사해야 합니다.

api에는 호환 API 예시에 나온 openai-completions를 입력합니다. 이 필드는 Pi에 어떤 API 형식으로 요청을 보낼지 알려 줍니다.

모델 ID는 전체를 복사하고 이름에 포함된 슬래시도 그대로 유지해야 합니다. 2026-10-09 기준 공급자 문서에서 대조한 두 ID는 gemini-3.8-flash와 grok-4.7입니다. 목록에 없는 이름을 그대로 사용하지 마세요.

도구 설정 입력

Pi의 사용자 수준 사용자 지정 모델 설정은 models.json에 작성합니다. 이 파일은 agent 디렉터리에 있으며 기본 디렉터리는 ~/.pi/agent이므로 전체 경로는 ~/.pi/agent/models.json입니다. 환경 변수 PI_CODING_AGENT_DIR을 설정하면 Pi는 해당 변수가 지정한 디렉터리를 대신 사용합니다. 환경 변수는 시스템이 프로그램에 제공하여 읽게 하는 설정값으로 이해할 수 있습니다.

호환 API 예시에 따라 입력합니다.

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers에는 연결할 서비스를 나열하고, models에는 선택할 수 있는 모델을 나열합니다. 각 모델의 id는 현재 OmniProxy 모델 목록에 있는 전체 Model ID와 일치해야 하며, input은 여기에서 설정하는 입력 형식이 텍스트임을 나타냅니다.

apiKey에는 값을 직접 입력할 수도 있고 $NAME 또는 ${NAME} 형식으로 작성해 Pi가 환경 변수에서 읽게 할 수도 있습니다. !로 시작하는 값은 명령어로 처리되어 요청할 때마다 실행됩니다. 실제 키를 저장소에 커밋하지 마세요. 게이트웨이가 키를 검증하지 않는다면 로컬에서만 사용하는 임의의 자리표시자 문자열을 입력할 수 있습니다. 2026-10-09 기준으로 이 방법을 통해 파일을 읽었습니다.

/model을 열면 이 파일을 다시 불러옵니다. /model은 Pi에서 모델을 확인하고 선택하는 진입점입니다. Pi가 자격 증명을 해석할 수 있기 전에는 사용자 지정 모델이 /model에 표시되지 않습니다. 모델을 선택한 뒤 Ctrl+S를 누르면 새 세션의 기본 모델로 저장할 수 있습니다.

파일

models.json

기본 디렉터리는 ~/.pi/agent
providers에 항목 하나 추가
api에는 completions 사용

주소

baseUrl

/v1까지 입력
apiKey에는 변수를 사용할 수 있음
모델 id가 정확해야 함

선택

/model

열면 파일을 다시 불러옴
방금 추가한 모델 선택
Ctrl+S로 기본값 저장 가능

파일을 수정한 뒤 Pi에서 /model을 열어 모델이 표시되는지 확인합니다.

실제 작업으로 검증

설정을 마친 뒤 파일이 있는 디렉터리에서 비대화형 검사를 한 번 수행할 수 있습니다. 비대화형은 지속적인 대화에 들어가지 않고 Pi가 해당 작업 하나를 완료한 뒤 종료되는 방식입니다. --model 뒤의 값을 현재 OmniProxy 목록에 있는 전체 ID로 바꿉니다.

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "지정한 파일의 첫 번째 줄을 읽고 파일은 수정하지 마세요."

여기서 --tools read는 읽기 도구만 허용하며, 작업 내용에서도 파일을 수정하지 말라고 명확하게 요구합니다. 2026-10-09에 Pi 1.1.0으로 파일 내용을 읽는 데 성공했습니다. 첫 응답에는 약 2분이 걸렸습니다.

대화형 방식도 사용할 수 있습니다. 디렉터리에서 pi를 실행한 다음 /model로 모델을 선택합니다. Quickstart의 예시 작업 중 하나는 Pi에 이 저장소가 어떻게 구성되어 있고 검사를 어떻게 실행하는지 설명하게 하는 것입니다. Pi가 파일을 읽고 설명을 제공하는지 확인한 다음 OmniProxy의 호출 기록에서 요청 출처와 모델 ID를 확인합니다.

시작

pi가 실행됨

먼저 cd로 폴더로 이동
pi --version이 출력됨
인터페이스 하단에 모델 이름이 있음

작업

디렉터리를 읽음

저장소 구조에 관해 질문하기
나열된 파일 확인하기
설정 저장 여부만 확인하지 않기

기록

게이트웨이에서 확인 가능

소스가 Pi임
모델 ID가 일치함
키는 로컬에 유지

인터페이스 하단에 모델 이름이 표시된 뒤에도 실제 작업을 한 번 완료해야 합니다.

자주 발생하는 오류

pi를 찾을 수 없음: 터미널을 다시 연 뒤 pi --version을 실행합니다. npm으로 설치했다면 전역 bin이 PATH에 포함되어 있는지 확인합니다.
/model에 사용자 지정 모델이 없음: models.json이 ~/.pi/agent/에 있는지, apiKey를 해석할 수 있는지 확인한 다음 /model을 다시 엽니다.
Windows에서 Bash를 찾을 수 없다는 메시지가 표시됨: Git for Windows를 설치하거나 ~/.pi/agent/settings.json에 shellPath를 설정합니다. JSON에서 백슬래시는 두 개로 작성해야 합니다.
요청이 거부됨: api가 openai-completions인지, baseUrl이 /v1으로 끝나는지 확인합니다. 상대 서비스가 호환된다고 명시했다는 이유만으로 추가 호환 옵션을 활성화하지 마세요.
모델 ID가 유효하지 않음: 현재 OmniProxy 목록에서 다시 복사합니다.

공식 참고 자료

설치 명령어는 Pi 홈페이지와 Quickstart를 참고하세요. 모델 파일은 Choose a Model과 Configuration을 참고하세요. Windows 명령 환경은 Run Pi on Windows를 참고하세요. 예시에 사용된 모델 ID는 Gemini 모델 목록과 xAI 모델 페이지를 참고하세요.

모든 플레이스홀더를 고유한 OmniProxy 구성의 값으로 바꾸세요. 실제 키를 게시하지 마세요.

저장된 결과나 HTTP 200 만으로는 전체 에이전트 호환성이 입증되지 않습니다. OmniProxy 호출 기록에서 소스와 모델을 확인하세요.

공식 소스 · Pi ↗