本文为社区中文翻译（依据 MIT 协议），阅读英文原文 →。译文可能滞后于上游更新。

设置

直接编辑，或用 /settings 修改常用选项。想以交互方式保存启动模型默认值，用 /model 并在目标模型上按 Ctrl+S；保存启动思考等级用 /thinking 加 Ctrl+S。

项目信任

交互启动时，如果项目目录包含项目级设置、资源或项目 .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 为单次运行覆盖。

pi config 和软件包命令走同样的项目信任流程，但 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，以及 OpenRouter、NVIDIA NIM、Cloudflare 请求中的 Pi 署名头。关闭会同时停用两者；但不会关闭更新检查——Pi 仍可请求 https://pi.dev/api/latest-version 查询最新版本。

设置 PI_SKIP_VERSION_CHECK=1 可禁用版本更新检查。--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
    }
  }
}

消息投递

终端与图片

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/；项目级装在 .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

资源

这些设置定义从哪里加载扩展、技能、提示词和主题。

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

数组支持 glob 模式与排除：!模式 排除；+路径 强制包含；-路径 强制排除。

packages

字符串形式加载软件包的全部资源：

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

对象形式过滤要加载的资源：

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

软件包管理详情见 Pi 软件包。

示例

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "modelThinkingLevels": {
    "anthropic/claude-sonnet-4-20250514": "high"
  },
  "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（全局）
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

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

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