#Settings（设置）

本页面是 Pi 官方文档 的中文翻译。仅供学习参考。

Pi 使用 JSON 设置文件，项目级配置优先于全局配置。

可以直接编辑文件，或使用 /settings 进行常用选项配置。

#项目信任

在交互式启动时，如果项目目录包含项目本地设置、资源或项目 .agents/skills，且在 ~/.pi/agent/trust.json 中该目录或父目录没有已保存的决策，Pi 会询问是否信任该目录。信任项目后，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 才能使更改生效。

#所有设置项

#模型和思维（Model & Thinking）

#thinkingBudgets

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

#UI 和显示

#遥测和更新检查

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（警告）

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

#Compaction（压缩）

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

#Branch Summary（分支摘要）

#Retry（重试）

当 Provider 请求的重试延迟超过 retry.provider.maxRetryDelayMs 时（例如 Google 的"配额将在 5 小时后重置"），请求会立即失败并显示信息性错误，而不是静默等待。设为 0 可禁用此上限。

除非明确需要 Provider 级别重试，否则请保持 retry.provider.maxRetries 为 0。将其设为大于 0 可能导致 SDK/Provider 重试在 Pi 处理之前就处理了用量超限错误，在某些情况下可能会阻塞 Agent 直到 Provider 配额重置。

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

#消息传递

#终端和图像

#Shell

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

npmCommand 用于所有 npm 包管理器操作，包括安装、卸载和 git 包内的依赖安装。用户范围的 npm 包安装在 ~/.pi/agent/npm/ 下；项目范围的 npm 包安装在 .pi/npm/ 下。使用与进程实际启动一致的 argv 格式条目。配置 npmCommand 后，git 包依赖安装使用普通的 install，以避免包装器或替代包管理器中的 npm 特定标志。

#会话

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

当多个来源指定会话目录时，优先级为：--session-dir、PI_CODING_AGENT_SESSION_DIR、settings.json 中的 sessionDir。

#模型循环

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

#Markdown

#资源

这些设置定义了扩展、Skills、Prompt 和主题的加载位置。

~/.pi/agent/settings.json 中的路径相对于 ~/.pi/agent 解析。.pi/settings.json 中的路径相对于 .pi 解析。支持绝对路径和 ~。

数组支持 glob 模式和排除。使用 !pattern 排除。使用 +path 强制包含精确路径，使用 -path 强制排除精确路径。

#packages

字符串形式加载包的所有资源：

{
  "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 }
}

法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。