Pi Coding Agent 모델 설정: /login, models.json 및 사용자 지정 Provider

Pi 코딩 에이전트의 모델 설정은 세 계층으로 나뉩니다. 내장 provider는 /login로 로그인(구독 또는 API 키)하거나 환경 변수를 설정합니다. Pi에 내장되어 있지는 않지만 OpenAI／Anthropic／Google API와 호환되는 엔드포인트는 ~/.pi/agent/models.json에 작성합니다. 특수한 인증 또는 프로토콜이 필요한 서비스에만 확장 기능을 작성해야 합니다. 선택한 뒤에는 /model로 전환합니다.이 글은 Pi의 2026년 9월 22일 개정 후 문서와 2026년 9월 30일 공개된 v0.99.2 소스 코드를 바탕으로 각 계층의 설정 방법, 변경된 키 읽기 순서, 사용자 지정 모델에서 조용히 문제를 일으키는 세 가지 기본값, OpenAI 호환 엔드포인트 연결의 전체 예시를 설명합니다.

먼저 어떤 Pi인지 확인하세요. 이 페이지는 Earendil이 pi.dev에서 공개한 터미널 코딩 에이전트, 즉 earendil-works/pi(이전 badlogic/pi-mono)를 다룹니다. MIT 라이선스입니다. Inflection의 챗봇 Pi(pi.ai), Pi Network 코인, Raspberry Pi 또는 다른 저자가 만든 Oh My Pi가 아닙니다.

먼저 연결 방식을 선택하세요

Pi의 모델 문서 첫머리에는 바로 이 비교표가 있습니다:

Pi에는 자체 모델 카탈로그가 내장되어 있으며 pi.dev에서 더 최신 카탈로그 데이터를 추가할 수 있습니다. 오프라인에서는 캐시를 사용하고, 강제로 업데이트하려면 pi update --models을 실행하면 됩니다. Pi에 원하는 provider나 엔드포인트가 없을 때만 사용자 지정 모델 설정이 필요합니다.

Pi에서 모델 선택

• /model: 모델을 검색하고 선택합니다. provider에 사용 가능한 인증 정보가 있는 모델만 표시됩니다.
• 모델에서 Ctrl+S 누르기: 새 세션의 기본 모델로 저장합니다.
• /thinking: 현재 모델의 사고 수준을 선택합니다. Pi에는 해당 모델이 지원하는 수준만 표시되며, Ctrl+S를 다시 눌러 시작 기본값으로 저장합니다.
• Ctrl+P: 사용 가능한 모델 사이를 순환합니다. /scoped-models으로 순환 목록을 제어하고 저장합니다.

세션에는 모델과 사고 수준을 변경한 기록이 남습니다. 세션을 복원하면 그대로 복원되지만 새 세션의 기본값은 변경하지 않습니다.

키 읽기 순서(개정 후 변경됨)

여러 키 소스를 동시에 설정한 경우 Pi 문서에 적힌 순서는 다음과 같습니다: 런타임의 --api-key → auth.json에 저장된 자격 증명 → models.json의 apiKey → provider의 환경 변수(또는 클라우드 플랫폼의 환경 자격 증명). 따라서 /login에 저장한 이전 키가 방금 파일에 입력한 키보다 우선하는 것이 ‘설정을 바꿨는데도 계속 이전 계정을 사용함’의 가장 흔한 원인입니다. /logout으로 저장된 자격 증명을 제거할 수 있습니다. 9월 22일 개정 전에는 문서에서 환경 변수가 models.json보다 앞선다고 했으므로, 온라인의 오래된 튜토리얼에는 이전 순서가 남아 있을 수 있습니다.

또 다른 흔한 오해가 있습니다. 모델이 /model에 나타나지 않는 것은 대부분 JSON을 잘못 작성해서가 아니라 인증 문제입니다. 문서에는 사용자 지정 모델을 models.json에서 불러올 수 있다고 되어 있지만, Pi가 자격 증명을 해석하기 전까지는 계속 ‘사용 불가’ 상태입니다.

models.json: OpenAI 호환 엔드포인트 연결 전체 예시

Pi 자체 예시는 로컬 Ollama입니다. dummy 키는 모델을 사용 가능 상태로 만들기 위한 것일 뿐 Ollama 자체는 이를 확인하지 않습니다:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [{ "id": "qwen2.5-coder:7b" }]
    }
  }
}

Kunavo처럼 인증이 필요한 엔드포인트에 연결하는 경우는 다음과 같습니다:

{
  "providers": {
    "kunavo": {
      "baseUrl": "https://api.kunavo.com/v1",
      "api": "openai-completions",
      "apiKey": "$KUNAVO_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "Claude Sonnet 5",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 128000
        },
        {
          "id": "claude-haiku-4-5",
          "name": "Claude Haiku 4.5",
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

• baseUrl과 api는 필수입니다. provider 수준이나 모델 수준에 작성할 수 있습니다. v0.99.2 소스 코드에 따르면 둘 중 하나라도 없으면 Pi는 해당 모델을 불러오지 않습니다.
• api은 네 가지 중 하나를 고르는 항목이 아닙니다. 9월 22일 개정 전 Pi 문서에는 사용자 지정 provider에 대해 네 가지 값인 openai-completions, openai-responses, anthropic-messages, google-generative-ai가 나열되어 있었습니다. 개정 후 문서에서는 목록을 더 이상 제시하지 않고, 위 비교표에 ‘OpenAI, Anthropic 또는 Google 호환 엔드포인트’라고만 적으며, 예시에서도 openai-completions만 사용합니다. v0.99.2 소스 코드는 api을 임의의 문자열로 정의하고, 10가지 내장 구현 중 해당 구현에 처리를 맡깁니다. 즉 위 네 가지에 openai-codex-responses, azure-openai-responses, google-vertex, mistral-conversations, bedrock-converse-stream, pi-messages가 더해집니다. 앞의 네 가지만 문서에서 사용자 지정 provider 사용법으로 설명된 적이 있으며, 나머지 여섯 가지는 여기서 테스트하지 않았으므로 이 페이지도 서드파티 엔드포인트에 연결된다고 주장하지 않습니다.
• openai-completions의 baseUrl에는 /v1가 포함되어야 합니다. 문서가 한 문장으로 규정하지는 않지만 호환 엔드포인트 예시에는 모두 버전 경로가 포함되어 있습니다. /v1가 없으면 인증 오류가 아니라 404가 반환됩니다.
• 키를 하드코딩하지 마세요. apiKey과 헤더 값에는 $NAME 또는 ${NAME}을 사용해 환경 변수를 참조하거나 값을 직접 입력할 수 있고, !指令로 가져올 수도 있습니다. 문서에 따르면 models.json 안의 명령은 요청마다 실행되며 캐시되지 않습니다. auth.json과 키를 가져오는 모든 명령은 비밀로 유지하세요.
• 변경 후 다시 시작할 필요가 없습니다. /model을 열 때 파일을 다시 읽습니다. models 안에서 같은 ID를 가진 항목은 해당 provider의 모델을 추가하거나 대체합니다. 내장 모델의 메타데이터만 바꾸고 전체 목록을 대체하지 않으려면 modelOverrides을 사용하세요.

조용히 오류를 일으키는 기본값 세 가지

9월 22일 문서 개정으로 필드 표는 삭제되었지만 기본값은 소스 코드(v0.99.2의 provider-composer.ts)에 남아 있습니다. 사용자 지정 모델에 값을 입력하지 않으면 다음이 적용됩니다:

또한 reasoning의 기본값은 false이고 input의 기본값은 텍스트만입니다. 위 Kunavo 예시는 가격표에 따라 컨텍스트와 출력 한도를 입력했으며 cost는 넣지 않았습니다. 가격을 파일에 하드코딩하면 금방 최신 가격과 맞지 않게 되기 때문입니다. 하단에 비용을 표시하려면 가격표에 따라 직접 100만 토큰당 가격을 입력하세요. Pi는 promptCache도 지원합니다(캐시 워밍업에 사용하는 provider 캐시의 유지 시간을 초 단위로 선언). 문서에서는 공개된 범위 중 보수적인 쪽을 사용할 것을 권장합니다.

anthropic-messages: 연결할 수 있지만 baseUrl은 확정되지 않음

anthropic-messages은 개정 전 문서에서 사용자 지정 provider에 대해 나열한 네 가지 값 중 하나이며, Kunavo도 Anthropic Messages 인터페이스를 제공하므로 api: "anthropic-messages" 경로는 존재합니다. 그러나 Pi 문서는 이런 유형의 baseUrl에 /v1을 포함해야 하는지 명확히 설명한 적이 없습니다. 개정 전에는 한 예시가 https://proxy.example.com/v1를 사용했고 다른 예시는 경로 없는 https://proxy.example.com를 사용했으며, 개정 후에는 두 예시 모두 삭제되어 여전히 확정되지 않았습니다. 이 경로를 사용한다면 먼저 한 가지를 시도하고, 첫 요청에서 401이 아니라 404가 반환되면 이 한 줄을 바꾸세요. compat에는 원래 제공업체가 아닌 제3자의 엔드포인트를 위해 설계된 스위치도 몇 가지 있습니다(예: supportsEagerToolInputStreaming, supportsStrictTools). 그러나 문서는 호환성 설정이 ‘검증된 동작 차이’를 설명해야 하며, 엔드포인트가 OpenAI 또는 Anthropic 호환이라고 주장한다는 이유만으로 켜서는 안 된다고 주의를 줍니다. 위의 openai-completions 예시는 이러한 문제를 피합니다. 이것이 해당 예시부터 시작하도록 권장하는 진짜 이유이며, 더 빠르기 때문이 아닙니다.

솔직한 설명과 결제

위 내용은 Pi 문서와 소스 코드를 읽고 정리한 설정 참고 자료이며, Kunavo는 자체 엔드포인트를 Pi에서 실제로 실행해 보지 않았습니다. 세션, 스트리밍, 도구 왕복을 실행하지 않았고 요청이 최종적으로 어떤 모델에 도달하는지도 확인하지 않았습니다. 현재 사용할 수 있는 경로를 유지한 채 Pi에 실제 파일을 읽고 쓰는 작업을 맡겨 보세요. Pi는 거의 모든 단계에서 도구 호출에 의존하므로, 첫 실행에서 스트리밍이나 도구 형식 불일치가 가장 잘 드러납니다. 영어 전체 설정 페이지는 Pi integration guide에서, Earendil 자체의 Radius 게이트웨이를 포함한 여러 유료 경로 비교는 Pi coding agent pricing에서 확인할 수 있습니다.

Kunavo는 선불 충전 방식으로 토큰별로 차감되며 월 이용료가 없습니다. 최소 충전액은 $10이고, 결제는 Stripe를 통해 이루어집니다. 대만에서는 신용카드(Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay 및 Link를 사용할 수 있습니다. JKOPay와 LINE Pay는 사용 가능한 목록에 없습니다. 자세한 내용은 청구 안내를 참조하고, 준비가 되면 계정을 생성하여 키를 발급받으세요.

자주 묻는 질문

2026년 10월 1일 확인: pi.dev/docs/latest/models(Choose a Model) 및 providers 페이지, earendil-works/pi 태그 v0.99.2의 src/core/model-config.ts 및 provider-composer.ts, 그리고 GitHub API의 버전 정보. 같은 날 api 필드도 별도로 확인했습니다. models 페이지에 현재 어떤 값이 나열되는지(Ollama 예시의 openai-completions만 있음), v0.99.2 model-config.ts에서 api의 타입(임의의 문자열, 191행 및 233행), 사용자 지정 모델에 대한 provider-composer.ts의 분배(579행), packages/ai/src/compat.ts의 BUILTIN_APIS(180행, 총 10종)입니다. Kunavo는 자체 엔드포인트를 Pi에서 실제로 실행해 보지 않았습니다.