Pi Agent 외부 API 연결: Base URL, API Key, 모델 설정

Pi Agent는 터미널 코딩 에이전트 Pi입니다. models.json으로 호환되는 외부 API에 연결합니다. BetterToken을 예로 API Key, 프로토콜에 맞는 Base URL, Model ID를 설정합니다. 다른 서비스를 연결하려면 해당 서비스의 URL, 인증 정보, 모델 ID를 사용하세요.

주요 설정

항목	값
API Key	`BETTERTOKEN_API_KEY` 환경 변수로 전달하는 BetterToken API Key
Base URL	OpenAI 프로토콜: `https://bettertoken.ai/v1`; Anthropic 프로토콜: `https://bettertoken.ai`
Model	model plaza의 정확한 Model ID
설정 파일	`~/.pi/agent/models.json`

사전 요구 사항

Node.js 22.19 이상.
BetterToken API Key를 만들고 model plaza에서 도구 호출을 지원하는 모델을 선택하세요.
네이티브 Windows에서는 Pi의 Bash 도구를 위해 Git for Windows를 설치하거나 WSL에서 Pi를 실행하세요.

설치

Pi의 현재 공식 npm 명령을 실행하세요.

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

수동 설정

API Key 설정

Pi를 실행할 터미널에서 YOUR_API_KEY를 자신의 Key로 바꾸세요.

macOS / Linux
Windows PowerShell

export BETTERTOKEN_API_KEY="YOUR_API_KEY"

$env:BETTERTOKEN_API_KEY="YOUR_API_KEY"

모델을 가져와 설정 생성하기

모델 목록 가져오기를 클릭하면 API Key를 입력하지 않고 BetterToken의 최신 공개 모델 카탈로그를 가져올 수 있습니다. API와 도구 호출을 지원하는 모델을 선택한 후 Model ID를 복사하거나 생성된 models.json을 다운로드하세요. 기존 models.json이 있다면 파일 전체를 덮어쓰지 말고 생성된 bettertoken 항목을 기존 설정에 병합하세요. 설정은 위에서 지정한 $BETTERTOKEN_API_KEY 변수를 사용합니다. 추가 매개변수는 모델의 실제 기능에 맞게 설정하세요. Pi는 여러 프로토콜을 지원하므로 모델과 서버가 지원하는 프로토콜을 선택하세요. 이 연결에서는 Claude에 Anthropic Messages, 서버가 지원하는 경우 GPT에 Responses, 다른 OpenAI 호환 모델에 Chat Completions를 권장합니다. 선택기의 기본값은 Chat Completions이며 공개 카탈로그에 명시된 API로 목록을 필터링합니다. Responses에 원하는 모델이 없으면 Responses 지원이 확인된 모델에 대해 아래 수동 설정 예시를 사용하세요.

URL과 모델 추가

~/.pi/agent/models.json을 만드세요. Windows 기본 경로는 %USERPROFILE%\.pi\agent\models.json입니다. 기존 파일이 있으면 providers 객체에 bettertoken 항목을 추가하세요. 생성된 설정을 사용하지 않는 경우 아래 Responses API 예시를 직접 작성할 수도 있습니다. YOUR_MODEL_ID를 model plaza의 ID로 바꾸고, 환경 변수 참조인 $BETTERTOKEN_API_KEY는 그대로 유지하세요.

{
  "providers": {
    "bettertoken": {
      "baseUrl": "https://bettertoken.ai/v1",
      "api": "openai-responses",
      "apiKey": "$BETTERTOKEN_API_KEY",
      "models": [{ "id": "YOUR_MODEL_ID" }]
    }
  }
}

다른 API를 쓰려면 baseUrl과 api를 함께 바꾸세요.

API	`api`	`baseUrl`
Responses API	`openai-responses`	`https://bettertoken.ai/v1`
Chat Completions	`openai-completions`	`https://bettertoken.ai/v1`
Anthropic Messages	`anthropic-messages`	`https://bettertoken.ai`

모델의 도구 호출을 지원하는 API를 선택하세요. 예를 들어 GPT-6.1 Sol은 Responses를 사용합니다. Base URL은 표의 값으로 유지하면 Pi가 요청 경로를 붙입니다.

Pi 시작

프로젝트 폴더에서 설정한 Model ID로 실행하세요.

pi --provider bettertoken --model YOUR_MODEL_ID

새 터미널에서는 환경 변수를 다시 설정하거나 셸 설정에 저장하세요.

연결 확인

pi --list-models를 실행해 bettertoken과 모델이 표시되는지 확인하세요. 그다음 Pi를 시작하고 다음 메시지를 보내세요.

Reply with PI_OK only. Do not use tools.

PI_OK를 받으면 작은 읽기 전용 작업으로 도구 호출도 확인하세요.

모델 전환

models 배열에 모델을 추가한 뒤 Pi에서 /model을 실행하면 models.json을 다시 읽습니다. 모델을 선택하고 Ctrl+S를 누르면 새 세션의 기본 모델로 저장됩니다. 프로토콜이 다른 연결은 로컬 이름을 구분하고 각각 api와 baseUrl을 지정하세요.

자주 발생하는 오류

증상	해결 방법
모델이 목록에 없음	JSON 형식, Model ID, 환경 변수를 확인하고 `/model`을 다시 여세요.
`401` 또는 `Unauthorized`	변수의 BetterToken API Key가 유효한지, 같은 터미널에서 Pi를 실행했는지 확인하세요.
`404` 또는 잘못된 URL	표에 맞게 `api`와 `baseUrl`을 확인하세요. 직접 추가한 `/responses`, `/chat/completions`, `/v1/messages`를 제거하세요.
텍스트는 되지만 도구 호출이 실패함	모델과 API의 도구 지원을 확인하고, Responses가 필요한 모델에는 `openai-responses`를 사용하세요.
Windows에서 Bash를 찾지 못함	Git for Windows를 설치하고 터미널을 다시 열거나 Pi Windows 가이드에 따라 `shellPath`를 설정하세요.

고급 설정

이미지, 추론 수준, 긴 컨텍스트가 필요하면 실제 모델 기능에 맞게 input, reasoning, contextWindow, maxTokens를 설정하세요. 모델 선택 가이드를 참고하세요.

기술 세부 정보

providers와 --provider는 Pi 클라이언트의 설정 필드이며 bettertoken은 이 예시의 로컬 이름입니다. Pi는 --api-key, auth.json의 저장된 인증 정보, models.json의 apiKey 순서로 사용합니다. 같은 이름에 이전 인증 정보가 저장되어 있다면 Pi의 /logout으로 해당 항목을 제거한 뒤 다시 연결하세요.

시작하기

Coding Agent 설정

AI 애플리케이션 플랫폼 설정

고급 설정

Pi Agent 외부 API 연결: Base URL, API Key, 모델 설정

주요 설정

사전 요구 사항

설치

수동 설정

API Key 설정

모델을 가져와 설정 생성하기

URL과 모델 추가

Pi 시작

연결 확인

모델 전환

자주 발생하는 오류

고급 설정

기술 세부 정보

Pi 공식 자료

​주요 설정

​사전 요구 사항

​설치

​수동 설정

​API Key 설정

​모델을 가져와 설정 생성하기

​URL과 모델 추가

​Pi 시작

​연결 확인

​모델 전환

​자주 발생하는 오류

​고급 설정

​기술 세부 정보

​Pi 공식 자료

주요 설정

사전 요구 사항

설치

수동 설정

API Key 설정

모델을 가져와 설정 생성하기

URL과 모델 추가

Pi 시작

연결 확인

모델 전환

자주 발생하는 오류

고급 설정

기술 세부 정보

Pi 공식 자료