설정

Pi는 전역 설정을 재정의하는 프로젝트 설정과 함께 JSON 설정 파일을 사용합니다.

직접 편집하거나 일반 옵션에 /settings를 사용하세요.

대화형 시작 시 pi는 프로젝트 로컬 설정, 리소스 또는 프로젝트 .agents/skills를 포함하고 ~/.pi/agent/trust.json의 폴더 또는 상위 폴더에 대해 저장된 결정이 없는 프로젝트 폴더를 신뢰하기 전에 묻습니다. 프로젝트를 신뢰하면 pi가 .pi/settings.json 및 .pi 리소스를 로드하고, 누락된 프로젝트 패키지를 설치하고, 프로젝트 확장을 실행할 수 있습니다.

비대화형 모드(-p, --mode json 및 --mode rpc)에는 신뢰 프롬프트가 표시되지 않습니다. 적용 가능한 저장된 신뢰 결정이 없으면 전역 설정에서 defaultProjectTrust를 사용합니다. ask(기본값) 및 never는 해당 프로젝트 리소스를 무시하고 always는 이를 신뢰합니다. 한 번의 실행에 대해 프로젝트 신뢰를 재정의하려면 --approve/-a 또는 --no-approve/-na를 전달합니다.

확장이나 저장된 결정이 적용되지 않는 경우 defaultProjectTrust는 대체 동작을 제어합니다. ~/.pi/agent/settings.json에서는 "ask", "always", "never"로 설정하거나 /settings로 변경하세요.

pi config 및 패키지 명령은 동일한 프로젝트 신뢰 흐름을 사용합니다. 단, pi update는 메시지를 표시하지 않습니다. 하나의 명령에 대해 프로젝트 로컬 설정을 신뢰하려면 --approve를 전달하고 이를 무시하려면 --no-approve를 전달합니다.

직계 상위 폴더에 대한 신뢰를 포함하여 향후 세션에 대한 프로젝트 신뢰 결정을 저장하려면 대화형 모드에서 /trust를 사용하세요. ~/.pi/agent/trust.json만 씁니다. 현재 세션은 다시 로드되지 않으므로 변경 사항을 적용하려면 pi를 다시 시작하세요.

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

VS Code의 경우 --wait를 포함하면 편집기가 종료된 후 pi가 다시 시작됩니다.

{
  "externalEditor": "code --wait"
}

enableInstallTelemetry는 https://pi.dev/api/report-install에 대한 익명 설치/업데이트 핑만 제어합니다. 원격 분석을 옵트아웃해도 업데이트 확인이 비활성화되지는 않습니다. Pi는 여전히 https://pi.dev/api/latest-version를 가져와서 최신 버전을 찾을 수 있습니다.

PI_SKIP_VERSION_CHECK=1를 설정하면 Pi 버전 업데이트 확인이 비활성화됩니다. 업데이트 확인, 패키지 업데이트 확인, 설치/업데이트 원격 측정을 포함하여 여기에 설명된 모든 시작 네트워크 작업을 비활성화하려면 --offline 또는 PI_OFFLINE=1를 사용하세요.

{
  "httpProxy": "http://127.0.0.1:7890"
}

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

공급자가 retry.provider.maxRetryDelayMs보다 긴 재시도 지연을 요청하면 조용히 기다리는 대신 정보 오류와 함께 요청이 즉시 실패합니다. 제한을 비활성화하려면 0로 설정하세요.

공급자 수준 재시도가 명시적으로 필요한 경우가 아니면 retry.provider.maxRetries를 0로 유지하세요. 0 이상으로 설정하면 SDK/공급자 재시도가 사용 제한 초과 오류를 Pi에서 확인하기 전에 처리할 수 있으며, 이로 인해 일부 상황에서 공급자 할당량이 재설정될 때까지 에이전트가 차단될 수 있습니다.

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

npmCommand는 git 패키지 내부의 설치, 제거 및 종속성 설치를 포함한 모든 npm 패키지 관리자 작업에 사용됩니다. 사용자 범위 npm 패키지는 ~/.pi/agent/npm/ 아래에 설치됩니다. 프로젝트 범위 npm 패키지는 .pi/npm/ 아래에 설치됩니다. 프로세스가 시작되어야 하는 것과 똑같이 argv 스타일 항목을 사용하십시오. npmCommand가 구성되면 git 패키지 종속성 설치는 일반 install를 사용하여 래퍼 또는 대체 패키지 관리자의 npm 관련 플래그를 방지합니다.

{ "sessionDir": ".pi/sessions" }

여러 소스가 세션 디렉터리를 지정하는 경우 settings.json에서 우선 순위는 --session-dir, PI_CODING_AGENT_SESSION_DIR, sessionDir입니다.

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

이러한 설정은 확장 프로그램, 스킬, 프롬프트 및 테마를 로드할 위치를 정의합니다.

~/.pi/agent/settings.json의 경로는 ~/.pi/agent를 기준으로 결정됩니다. .pi/settings.json의 경로는 .pi를 기준으로 결정됩니다. 절대 경로와 ~가 지원됩니다.

배열은 glob 패턴과 제외를 지원합니다. 제외하려면 !pattern를 사용하세요. 정확한 경로를 강제로 포함하려면 +path를 사용하고, 정확한 경로를 강제로 제외하려면 -path를 사용하세요.

문자열 형식은 패키지에서 모든 리소스를 로드합니다.

{
  "packages": ["pi-skills", "@org/my-extension"]
}

개체 양식은 로드할 리소스를 필터링합니다.

{
  "packages": [
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

패키지 관리에 대한 자세한 내용은 packages.md를 참조하세요.

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

프로젝트 설정(.pi/settings.json)은 전역 설정보다 우선 적용됩니다. 중첩된 개체가 병합됩니다.

// ~/.pi/agent/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}