设置

Pi 使用 JSON settings 文件。项目 settings 的优先级高于全局 settings。

可以直接编辑，也可以使用 /settings 配置常用选项。若要交互式保存启动时的默认模型，请使用 /model，在目标模型上按 Ctrl+S。要保存启动时的默认思考级别，请使用 /thinking，然后按 Ctrl+S。

项目信任

在交互式启动时，如果某个项目文件夹包含项目级设置、资源或项目 .agents/skills，并且在 ~/.pi/agent/trust.json 中，这个文件夹或其父文件夹都没有保存过信任决策，Pi 会先询问是否信任该项目文件夹。信任项目后，Pi 可以加载 .pi/settings.json 和 .pi 资源，安装缺失的项目 Package，并执行项目扩展。

非交互模式（-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 和 Package 命令使用同一套项目信任流程，但 pi update 从不提示。可以传入 --approve，在单个命令中信任项目本地设置；也可以传入 --no-approve，忽略这些设置。

在交互模式下使用 /trust，可以保存未来会话的项目信任决策，也会一并信任紧邻的父文件夹。它只会写入 ~/.pi/agent/trust.json；当前会话不会重新加载，所以需要重启 Pi，改动才会生效。

全部设置

模型与思考

thinkingBudgets

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

UI 与显示

对于 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 可以禁用这里提到的所有启动时网络操作，包括更新检查、Package 更新检查，以及安装/更新遥测。

网络

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

警告

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

上下文压缩

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

分支摘要

重试

当 Provider 要求的重试延迟长于 retry.provider.maxRetryDelayMs 时（例如 Google 的 "quota will reset after 5h"），请求会立即失败，并返回说明性错误，而不是静默等待。设为 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

JSON 中的 Windows 路径必须使用正斜杠或转义后的反斜杠：

{
  "shellPath": "C:/Program Files/Git/bin/bash.exe"
}

{
  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
}

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

npmCommand 用于所有 npm 包管理操作，包括安装、卸载，以及在 git 包内部安装依赖。用户级 npm 包安装在 ~/.pi/agent/npm/；项目级 npm 包安装在 .pi/npm/。请使用 argv 风格的条目，并让每一项都与进程实际启动方式一致。当配置了 npmCommand 时，git 包的依赖安装会使用原始的 install，以避免包装器或其他包管理器带来的 npm 特定参数问题。

工具

defaultTools 选择启动时启用的内置工具。扩展和 SDK 自定义工具仍保持启用。可用内置工具包括 read、bash、powershell、edit、write、grep、find 和 ls：

{
  "defaultTools": ["bash", "edit", "write"]
}

在 Windows 上应使用 powershell 代替 bash，或同时包含两者：

{
  "defaultTools": ["read", "powershell", "edit", "write"]
}

空数组表示启动时不启用任何内置工具，但仍保留扩展和 SDK 自定义工具。--tools 会将此行为替换为针对所有工具的严格允许列表，--no-tools 禁用全部工具，--no-builtin-tools 禁用内置默认工具，--exclude-tools 则从最终列表中过滤工具。项目级 defaultTools 数组会替换全局数组。

会话

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

当多个来源都指定了会话目录时，优先级依次是 --session-dir、PI_CODING_AGENT_SESSION_DIR，然后是 settings.json 里的 sessionDir。

模型轮换

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

Markdown

资源

这些设置定义了从哪里加载扩展、Skill、提示词模板和主题。

在 ~/.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": []
    }
  ]
}

有关 Package 管理的详细信息，请参见 Package 文档。

示例

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