设置

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"设置为"ask"、"always"或"never"，或将其更改为/settings。

pi config 和 package 命令使用相同的项目信任流程，但 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 的匿名安装/更新 ping。选择退出遥测不会禁用更新检查； 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/provider 重试在 Pi 看到超出使用限制的错误之前处理这些错误，这可能会阻止代理，直到在某些情况下提供程序配额重置。

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

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

npmCommand 用于所有 npm 包管理器操作，包括安装、卸载以及 git 包内的依赖项安装。用户范围的 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 }
}