Pi를 나만의 로컬 모델과 함께 사용하세요

Pi는 earendil-works의 오픈소스 BYOK(“bring your own key”) 터미널 코딩 에이전트입니다. OpenAI chat-completions 프로토콜을 사용하며 JSON 구성 파일에서 제공자를 읽어오므로, Tokios를 사용자 지정 제공자로 추가하고 baseUrl를 https://api.tokios.com/v1에 연결한 후 커넥터 뒤의 모든 모델을 구동할 수 있습니다 — 해당 모델의 포트가 노출되지 않은 상태로 말이죠.

사전 요구 사항

A running Tokios connector paired with your local model — see Connector install
A registered deployment — see Register a model
A Tokios API key (sk-tok-…) — see API keys
Pi 설치됨 — npm install -g @earendil-works/pi-coding-agent

배포 이름을 찾으세요.

Pi는 콘솔에 등록한 공개 이름인 배포 이름을 보내며, 로컬 백엔드가 사용하는 업스트림 모델 ID는 보내지 않습니다. 2는 종종 서로 다른 문자열이며, 이 둘을 혼동하는 것이 404의 가장 흔한 원인입니다. API 키가 도달할 수 있는 배포를 나열하세요.

curl https://api.tokios.com/v1/models \
  -H "Authorization: Bearer sk-tok-YOUR_KEY"

curl.exe https://api.tokios.com/v1/models `
  -H "Authorization: Bearer sk-tok-YOUR_KEY"

응답의 모든 id는 models.json에서 사용할 수 있는 값입니다.

모델이 이미 Playground로 응답하더라도 이 작업을 실행하세요. Playground는 로그인된 브라우저 세션으로 인증하므로, 거기서 성공적인 테스트를 했다고 해서 sk-tok-… 키가 유효하거나 해당 배포에 범위가 지정되었음을 증명하지는 않습니다. GET /v1/models가 키 자체를 사용하는 첫 번째 호출입니다.

Pi가 설정을 저장하는 위치

Pi는 2 파일을 사용자 홈 폴더의 점으로 시작하는 .pi 디렉터리에서 읽습니다.

파일	목적
`.pi/agent/models.json`	프로바이더와 각 프로바이더가 제공하는 모델
`.pi/agent/settings.json`	기본 프로바이더 및 모델

~/.pi/agent/models.json

C:\Users\<you>\.pi\agent\models.json

디렉터리와 파일이 아직 없으면 생성하세요.

디렉터리는 .pi이며, 앞에 점이 있습니다. Pi는 pi/agent/models.json에 생성된 파일을 읽지 않습니다 — 정상적으로 시작되고, 공급자는 /model에 전혀 나타나지 않습니다.

사용자 지정 공급자 구성

이것을 models.json에 붙여넣고 2 플레이스홀더 값을 바꾸십시오. 완전한 파일이며 조각이 아닙니다. Pi의 구성 스키마는 릴리스 간에 변경될 수 있으므로 설치된 버전에서 정확한 키 이름을 확인하십시오(pi.dev/docs 참조).

~/.pi/agent/models.json

{
  "providers": {
    "tokios": {
      "baseUrl": "https://api.tokios.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-tok-YOUR_KEY",
      "models": [
        {
          "id": "gemma-tunnel",
          "input": ["text"]
        }
      ]
    }
  }
}

하나의 프로바이더 블록으로 계정의 모든 배포를 처리할 수 있습니다. 각각에 대해 models 배열에 항목을 추가하세요.

~/.pi/agent/models.json

{
  "providers": {
    "tokios": {
      "baseUrl": "https://api.tokios.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-tok-YOUR_KEY",
      "models": [
        { "id": "gemma-tunnel", "input": ["text"] },
        { "id": "qwen3-coder-tunnel", "input": ["text"] }
      ]
    }
  }
}

Replace gemma-tunnel with a deployment name from GET /v1/models — not the upstream model id your backend (Ollama, llama.cpp, vLLM, or LM Studio) serves, and not the Routes[].Model value in your connector config, which is the upstream id. Replace sk-tok-YOUR_KEY with your own key, and avoid committing models.json with a real key into version control.

baseUrl에는 /v1가 포함되어야 하며, 후행 슬래시가 없어야 합니다. Pi의 openai-completions 프로바이더는 이 URL을 기준으로 요청 경로를 구성하므로, https://api.tokios.com는 Tokios API 표면을 놓치고 https://api.tokios.com/v1/는 이중 구분 기호를 생성할 수 있습니다.

컨텍스트 창 일치 (선택 사항)

Pi는 모델의 컨텍스트 창에서 프롬프트 크기를 결정합니다. Ollama, llama.cpp, LM Studio, vLLM은 각각 모델이 로드된 컨텍스트 길이를 제공하며, 모델의 이론적 최대치가 아닙니다. 따라서 Pi에 실제 숫자를 알려주세요.

{ "id": "gemma-tunnel", "input": ["text"], "contextWindow": 32768 }

너무 높게 설정하면 Pi가 로컬 서버가 거부하는 프롬프트를 담아 보냅니다 — Tokios를 통해 도착하지만 실제로는 사용자 컴퓨터에서 발생한 오류입니다. 짧은 프롬프트는 불일치를 숨기므로 일반적으로 Pi가 전체 파일을 보내기 시작한 후에만 나타납니다. 설치된 버전과 키 이름을 대조하여 확인하세요.

기본값으로 설정(선택 사항)

Tokios 배포에서 매번 선택하는 대신 Pi를 바로 실행하려면 ~/.pi/agent/settings.json에서 기본값을 설정하세요.

~/.pi/agent/settings.json

{
  "defaultProvider": "tokios",
  "defaultModel": "gemma-tunnel"
}

그렇지 않으면, Pi의 TUI 내부에서 /model 명령을 사용하여 런타임에 제공자와 모델을 선택하십시오.

Anthropic 인터페이스를 선호하시나요? (선택 사항)

Pi는 또한 Anthropic 메시지 프로토콜을 지원합니다. 대신 Tokios의 Anthropic 인터페이스를 통해 라우팅하려면 api를 anthropic-messages로 설정하고 /v1를 baseUrl에서 제거하세요 — Anthropic 스타일 클라이언트는 루트 베이스를 사용합니다. 사용 중인 Pi 버전이 기대하는 정확한 api 값을 확인하세요.

"api": "anthropic-messages",
"baseUrl": "https://api.tokios.com"

도구를 사용할 수 있는 모델을 선택하세요.

Pi의 에이전트는 파일을 읽고, 명령을 실행하고, 코드를 편집하기 위해 도구 호출에 의존합니다. 모든 로컬 모델이 도구 호출을 안정적으로 처리하는 것은 아닙니다. Pi를 실제 편집에 사용하기 전에 강력한 도구 호출 지원을 갖춘 모델로 뒷받침되는 배포를 선택하세요. 에이전트형 코딩 작업에 모델을 매칭하는 방법은 작업별 모델 선택을 참조하세요.

문제 해결

Tokios가 /model에 표시되지 않음

Pi가 파일을 읽지 못하고 있습니다. 파일이 ~/.pi/agent/models.json에 있는지 확인하세요. 해당 디렉터리는 .pi이며, 앞에 점이 있고, Windows에서는 C:\Users\<you>\.pi\agent\models.json로 확인됩니다. 또한 파일이 유효한 JSON인지, providers가 공급자 이름을 키로 하는 객체이고 models가 배열인지 확인하세요.

401 오류

Pi가 보낸 API 키가 누락되었거나, 형식이 잘못되었거나, 또는 해지되었습니다. apiKey에 추가 공백 없이 전체 sk-tok-… 키가 들어 있는지 확인하고, Keys 탭에서 상태를 확인하세요. Playground 세션이 작동한다고 해서 이 가능성이 배제되지는 않습니다. Playground는 사용자의 API 키를 사용하지 않습니다.

404 오류

모델 id은(는) models 하위의 것인데 등록된 배포와 일치하지 않습니다. GET /v1/models을(를) 실행하고 응답에서 id을(를) 정확히 복사하세요. 흔히 발생하는 근접 오류는 커넥터의 Routes[].Model에 있는 업스트림 모델 ID를 배포 이름 대신 사용하는 것입니다.

403 오류

키는 존재하지만 구성한 배포에 범위가 지정되지 않았거나, 계정이 정지되었습니다. Keys 탭에서 키의 모델 패턴을 확인하세요.

503 오류

해당 배포의 커넥터가 오프라인이거나 동시 실행 한도에 도달했습니다. Connectors 탭을 확인하세요. 커넥터가 Online로 표시되어야 하며, 커넥터를 실행하는 머신이 계속 켜져 있고 연결 가능해야 합니다.

긴 세션은 실패하고 짧은 세션은 작동합니다.

Pi가 백엔드가 로드한 것보다 더 많은 컨텍스트를 보내고 있습니다. 모델 항목의 contextWindow을(를) 서버가 실제로 제공하는 컨텍스트 길이로 설정하고 Ollama, llama.cpp, LM Studio 또는 vLLM의 로드 시 설정을 확인하세요.

다음 단계

omp (oh-my-pi)

필요한 것이 모두 포함된 포크를 선호하시나요? 같은 방식으로 omp를 Tokios에 연결하세요.

작업별로 모델을 선택하세요.

로컬 모델을 Pi에 투입하기 전에 에이전트 코딩 작업에 맞추세요.

하드웨어와 호환성

런타임 서빙과 연결

클라이언트 또는 앱 연결

비교

Pi를 나만의 로컬 모델과 함께 사용하세요

사전 요구 사항

배포 이름을 찾으세요.

Pi가 설정을 저장하는 위치

사용자 지정 공급자 구성

컨텍스트 창 일치 (선택 사항)

기본값으로 설정(선택 사항)

Anthropic 인터페이스를 선호하시나요? (선택 사항)

도구를 사용할 수 있는 모델을 선택하세요.

문제 해결

다음 단계

omp (oh-my-pi)

작업별로 모델을 선택하세요.

​사전 요구 사항

​배포 이름을 찾으세요.

​Pi가 설정을 저장하는 위치

​사용자 지정 공급자 구성

​컨텍스트 창 일치 (선택 사항)

​기본값으로 설정(선택 사항)

​Anthropic 인터페이스를 선호하시나요? (선택 사항)

​도구를 사용할 수 있는 모델을 선택하세요.

​문제 해결

​다음 단계

omp (oh-my-pi)

작업별로 모델을 선택하세요.

사전 요구 사항

배포 이름을 찾으세요.

Pi가 설정을 저장하는 위치

사용자 지정 공급자 구성

컨텍스트 창 일치 (선택 사항)

기본값으로 설정(선택 사항)

Anthropic 인터페이스를 선호하시나요? (선택 사항)

도구를 사용할 수 있는 모델을 선택하세요.

문제 해결

다음 단계