Pi의 설정은 사용자 전역과 프로젝트 단위로 나뉩니다. 전역 설정은 에이전트 디렉터리(기본 ~/.pi/agent)에, 프로젝트 설정은 작업 폴더의 .pi에 있습니다. 프로젝트 설정은 프로젝트 신뢰(trust)가 허용된 뒤에만 로드됩니다. 예외는 sessionDir뿐이며, 세션을 찾기 위해 신뢰 판정 전에 읽힙니다.

대화형에서는 /settings로 일반적인 환경을 바꿉니다. 그 외 옵션은 Pi에게 설정 파일 수정을 시키거나 직접 편집하면 되고,수동으로 바꾼 뒤에는 /reload를 실행합니다.

에이전트 디렉터리

에이전트 디렉터리는 PI_CODING_AGENT_DIR 환경변수로 위치를 바꿀 수 있습니다. 기본 구조는 다음과 같습니다.

경로	역할
<agent-dir>/settings.json	전역 설정. 환경, 기본값, 자원 경로, Pi 패키지 선언
<agent-dir>/keybindings.json	터미널 UI·응용 단축키 커스터마이징
<agent-dir>/mcp.json	모든 프로젝트에서 쓰는 MCP 서버
<agent-dir>/models.json	호환 엔드포인트, 모델, 모델 오버라이드
<agent-dir>/auth.json	저장된 API 키와 OAuth 자격 증명
<agent-dir>/AGENTS.override.md·AGENTS.md·CLAUDE.md	모든 작업 폴더에 적용되는 사용자 지침
<agent-dir>/SYSTEM.md	기본 시스템 프롬프트 교체
<agent-dir>/APPEND_SYSTEM.md	시스템 프롬프트에 지침 추가
<agent-dir>/extensions/	사용자 확장
<agent-dir>/skills/	사용자 스킬
<agent-dir>/prompts/	/ 명령이 되는 사용자 프롬프트 템플릿
<agent-dir>/themes/	사용자 테마

프로젝트 .pi 디렉터리

경로	역할
.pi/settings.json	프로젝트 설정, 자원 경로, Pi 패키지 선언
.pi/mcp.json	프로젝트 MCP 서버
.pi/SYSTEM.md·.pi/APPEND_SYSTEM.md	프로젝트용 시스템 프롬프트 교체·추가
.pi/extensions/·skills/·prompts/·themes/	프로젝트 단위 자원

SYSTEM.md와 APPEND_SYSTEM.md는 신뢰된 프로젝트 파일이 에이전트 디렉터리의 같은 파일보다 우선합니다. 같은 이름의 파일이 합쳐지지는 않습니다.

컨텍스트 파일

컨텍스트 파일은 프로젝트 .pi 설정과 별개입니다. Pi는 에이전트 디렉터리, 작업 폴더, 그 상위 폴더에서 컨텍스트 파일을 찾으며, 해당 폴더와 그 하위에서 실행될 때마다 적용됩니다. AGENTS.override.md는 같은 폴더의 AGENTS.md/CLAUDE.md를 대체할 뿐, 다른 폴더의 컨텍스트 파일을 누르지 않습니다. 참고로 컨텍스트 파일 탐색에는 프로젝트 신뢰가 필요하지 않습니다.

모델과 제공자 연결

내장 제공자는 /login → /model 순서로 연결하면 됩니다. 그 외 상황은 다음 표로 정리됩니다.

보유한 것	권장 설정
지원되는 subscription	/login으로 로그인
제공자 API 키	/login에 저장하거나 환경변수로 제공
로컬 GGUF 모델	Pi를 llama.cpp 라우터에 연결 (/llama)
OpenAI·Anthropic·Google 호환 엔드포인트	models.json에 추가
자체 프로토콜·인증 플로우를 가진 제공자	제공자 확장 작성 또는 설치

현재 제공자·모델 ID·컨텍스트 한도·가격은 pi.dev의 모델 카탈로그에서 확인합니다. Pi는 내장 카탈로그로 시작해 pi.dev의 최신 카탈로그 데이터를 얹으며, 오프라인에서는 캐시된 데이터를 씁니다. pi update --models로 강제 갱신할 수 있습니다.

인증 자격 증명이 해석되는 우선순위는 다음 순서입니다.

1. 런타임 --api-key
2. auth.json에 저장된 자격 증명
3. models.json의 apiKey
4. 제공자의 환경변수 또는 클라우드 ambient 자격 증명

/model 선택기에서 Ctrl+S는 해당 모델을 새 세션 기본값으로 저장합니다. /thinking으로 추론 단계를 고르고, Ctrl+P는 사용 가능한 모델 순환, /scoped-models는 그 순환 대상 관리입니다. 세션은 모델과 thinking 단계 변경을 기록하므로 재개 시 복원되지만 새 세션의 기본값은 바뀌지 않습니다.

호환 엔드포인트 구성

Ollama, LM Studio, vLLM, SGLang, 프록시 배포처럼 Pi가 이미 아는 API를 말하는 엔드포인트는 models.json에 추가합니다.

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

더미 키는 모델을 Pi에 노출하는 용도이며 Ollama는 무시합니다. 인증이 필요한 엔드포인트라면 apiKey와 헤더 값에 $NAME·${NAME} 환경변수 보간, 문자열 리터럴, 또는 !command를 쓸 수 있습니다. 내장 제공자를 프록시로 우회할 때는 baseUrl만 지정하면 모델과 인증은 그대로 유지됩니다.

{
  "providers": {
    "anthropic": { "baseUrl": "https://proxy.example.com/v1" }
  }
}

/model을 열면 파일을 다시 읽습니다. models 항목은 같은 ID의 모델을 추가·교체하고, modelOverrides는 기존 모델의 메타데이터만 바꿀 때 씁니다. 이미지 리사이즈 정책(inputLimits.images.resize), 프롬프트 캐시 수명(promptCache), thinking 단계별 샘플링(samplingParamsByThinkingLevel) 등 세부 필드는 Models Configuration 레퍼런스를 참고하세요.