Pi

Pi는 models.json으로 HiAPI에 연결할 수 있습니다. 아래 단계는 deepseek-v4.1-flash를 예로 사용하며, 이 튜토리얼은 Mac에서 Pi 1.3.0으로 검증했습니다. Windows에서는 먼저 Git Bash를 설치하세요(3단계).

1. Node.js 설치

Node.js 설치에 설명된 대로 LTS 22.19 이상을 설치하고, 이미 있다면 건너뛰세요. 그런 다음 터미널에서 아래 두 명령을 실행하세요. 버전 번호가 보이면 충분합니다:

node --version
npm --version

Windows PowerShell에서는 이 가이드 뒤쪽의 npm / npx 명령을 npm.cmd / npx.cmd로 적으세요.

2. Pi 설치

터미널에서 각 줄을 실행하세요:

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

1.3.0이 보이면 충분합니다. Windows PowerShell에서는 npm.cmd install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0과 pi.cmd --version을 사용하세요.

3. Windows에서는 먼저 Git Bash 설치(Mac은 건너뜀)

1. Git for Windows 다운로드 페이지를 열고 아키텍처에 맞는 설치 파일을 내려받아 실행합니다. 설치 디렉터리는 C:\Program Files\Git으로 유지하고, 권장 PATH 옵션인 Git from the command line and also from 3rd-party software를 선택한 뒤 Install → Finish를 클릭하세요. 이미 Git Bash가 있다면 건너뛰세요.
2. 기존 PowerShell 창을 닫고 다시 열어 Bash 경로를 확인하세요:

& 'C:\Program Files\Git\bin\bash.exe' --version

GNU bash 버전이 보이면 충분합니다. 다른 위치에 설치했다면 파일 탐색기에서 실제 bin\bash.exe를 찾아 명령의 경로를 바꾸세요.

3. Pi는 보통 Git Bash를 자동으로 찾습니다. 시작한 뒤에도 Bash를 찾을 수 없다고 할 때만 메모장에서 %USERPROFILE%\.pi\agent\settings.json을 열고(기존 파일은 먼저 백업) shellPath 필드를 추가하거나 갱신하며 나머지 필드는 유지하세요:

{
  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
}

실제 설치 경로를 사용하고 역슬래시는 두 번 쓰세요. Save as에서 “All files”, UTF-8, 파일 이름 settings.json을 선택한 뒤 저장하고 Pi를 다시 여세요.

4. HiAPI API 키 받기

API 키 발급받기에 설명된 대로 키를 준비하고, 키 옆의 복사 아이콘을 클릭해 전체 HiAPI API 키를 복사하세요. 7단계에서 필요합니다.

5. 모델 설정 파일 열기

Mac에서는 터미널에서 각 줄을 실행하세요(기존 models.json은 먼저 자동으로 백업됩니다):

mkdir -p "$HOME/.pi/agent"
if [ -f "$HOME/.pi/agent/models.json" ]; then cp "$HOME/.pi/agent/models.json" "$HOME/.pi/agent/models.json.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.pi/agent/models.json"

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.pi\agent"
if (Test-Path "$env:USERPROFILE\.pi\agent\models.json") { Copy-Item "$env:USERPROFILE\.pi\agent\models.json" "$env:USERPROFILE\.pi\agent\models.json.bak-$(Get-Date -Format yyyyMMdd-HHmmss)" }
notepad "$env:USERPROFILE\.pi\agent\models.json"

PI_CODING_AGENT_DIR을 설정했다면 그 디렉터리의 models.json을 편집하고, 설정하지 않았다면 위의 기본 디렉터리를 사용하세요.

6. DeepSeek 구성 추가 및 저장

1. 아래 내용을 models.json에 작성하세요(터미널에서 한 줄씩 실행하지 마세요). 새 파일이라면 전부 붙여 넣고, 파일이 이미 있으면 기존 providers에 hiapi-deepseek만 병합하며 다른 공급자는 유지하고 최상위 providers는 정확히 하나만 두세요.

{
  "providers": {
    "hiapi-deepseek": {
      "baseUrl": "https://api.hiapi.ai/v1",
      "api": "openai-completions",
      "apiKey": "${HIAPI_API_KEY}",
      "models": [
        {
          "id": "deepseek-v4.1-flash",
          "name": "DeepSeek V4.1 Flash (HiAPI)",
          "api": "openai-completions",
          "reasoning": true,
          "input": [
            "text"
          ],
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "thinkingLevelMap": {
            "minimal": null,
            "low": "low",
            "medium": null,
            "high": "high",
            "xhigh": null,
            "max": "max"
          },
          "compat": {
            "thinkingFormat": "deepseek",
            "maxTokensField": "max_tokens",
            "supportsReasoningEffort": true
          }
        }
      ]
    }
  }
}

2. apiKey의 ${HIAPI_API_KEY}는 Pi가 환경 변수를 읽는 방식이므로 그대로 두고 다음 단계에서 키를 설정하세요. JSON에는 큰따옴표와 쉼표를 사용하고, 마지막 항목 뒤에 쉼표를 남기지 말고, 주석을 넣지 마세요.

① providers 아래에 hiapi-deepseek 객체 전체를 추가합니다. ② apiKey에는 환경 변수 자리 표시자를 유지합니다. 스크린샷에 이미 있는 다른 공급자는 그대로 두어도 됩니다.

3. 저장: Mac nano에서는 Ctrl+O → Enter → Ctrl+X를 누르고, Windows 메모장에서는 Save as, “All files”, UTF-8을 선택하고 파일 이름을 .json.txt가 아닌 정확히 models.json으로 지정하세요.

7. API 키 설정 및 Pi 시작

1. Mac에서는 Pi를 시작할 같은 터미널에서 실행하세요(YOUR_HIAPI_API_KEY를 자신의 HiAPI API 키로 바꾸고 따옴표는 유지):

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"

2. 프로젝트 폴더로 이동해 Pi를 시작하거나, 빈 디렉터리를 먼저 만드세요:

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
pi

Windows PowerShell:

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
pi.cmd

3. 환경 변수는 현재 터미널에만 적용됩니다. 터미널을 닫은 뒤에는 다시 설정하세요. HiAPI를 사용할 때는 Pi에서 /login을 실행할 필요가 없습니다.

8. 모델 선택 및 확인

1. Pi 입력 상자에 /model을 입력하고 Enter를 누른 뒤 hiapi를 검색하고, 화살표 키로 DeepSeek V4.1 Flash (HiAPI) (공급자 hiapi-deepseek)를 선택해 Enter를 누르세요.

① 화살표 키로 DeepSeek 행으로 이동합니다. ② Enter를 눌러 선택합니다.

2. /thinking을 입력하고 Enter를 누른 뒤 off / low / high / max 중 하나를 선택하고 Enter를 누르세요. 처음 시험할 때는 low를 권장합니다.

① off, low, high, max 중 하나를 선택합니다. ② Enter를 눌러 현재 세션에 적용합니다.

3. Enter는 현재 세션에만 적용됩니다. 이 수준을 이후 세션의 기본값으로 만들려면 메뉴 안내대로 Ctrl+S를 누르세요.

4. “안녕하세요, 한 문장으로 자기소개를 해 주세요.”를 보내세요. 정상적으로 답하면 연결이 된 것입니다. HiAPI 콘솔의 요청 로그에 이 요청이 보이면 HiAPI를 거쳐 가는 것입니다.

문제 해결

여기에는 Pi에 특화된 문제만 정리했습니다. 401, 404, 429 같은 일반적인 오류는 자주 발생하는 오류를 참고하세요.