设置

Pi 使用 JSON 设置文件，项目设置会覆盖全局设置。

可直接编辑文件，或使用 /settings 命令设置常用选项。

项目信任 Project Trust

交互式启动时，如果项目目录包含本地设置、资源或 .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 才能让更改生效。

所有设置 All Settings

模型与思考 Model & Thinking

thinkingBudgets

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

UI 与显示 UI & Display

对于 VS Code，包含 --wait 以便 pi 在编辑器退出后恢复：

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

遥测与更新检查 Telemetry and update checks

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 可禁用此处描述的所有启动网络操作，包括更新检查、包更新检查以及安装/更新遥测。

网络 Network

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

警告 Warnings

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

压缩 Compaction

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

分支摘要 Branch Summary

重试 Retry

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

除非明确需要提供商级别的重试，否则将 retry.provider.maxRetries 保持在 0。将其设置为高于 0 可能会使 SDK/提供商重试在处理超出使用限制的错误时，Pi 无法感知，这可能在特定情况下阻塞代理直到提供商配额重置。

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

消息投递 Message Delivery

终端与图片 Terminal & Images

终端 Shell

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

npmCommand 用于所有 npm 包管理器操作，包括安装、卸载以及 git 包中的依赖安装。用户作用域的 npm 包安装在 ~/.pi/agent/npm/ 下；项目作用域的 npm 包安装在 .pi/npm/ 下。请使用与进程启动方式完全一致的 argv 格式条目。当配置了 npmCommand 时，git 包的依赖安装使用普通的 install，以避免在包装器或其他包管理器中传入 npm 特定标志。

会话 Sessions

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

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

模型切换 Model Cycling

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

Markdown

资源 Resources

以下设置定义了从何处加载扩展、技能、提示模板和主题。

~/.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。

示例 Example

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

项目覆盖 Project Overrides

项目设置（.pi/settings.json）会覆盖全局设置。嵌套对象会合并：

// ~/.pi/agent/settings.json（全局）
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json（项目）
{
  "compaction": { "reserveTokens": 8192 }
}

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