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

设置

可以直接编辑，或使用 /settings 查看常用选项。要以交互方式保存启动时的模型默认值，请使用 /model 并按 Ctrl+S 选择所需的模型。要保存启动时的思考级别，请使用 /thinking 并按 Ctrl+S。

项目信任

在交互式启动时，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"，或通过 /settings 更改。

pi config 和软件包命令使用相同的项目信任流程，但 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 发送的匿名安装/更新数据包，以及针对 OpenRouter、NVIDIA NIM 和 Cloudflare 提供商请求的 Pi 归属标头。选择退出将同时禁用这两项功能，但不会禁用更新检查；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.maxAgentDelayMs 控制，因此在长时间故障后，长时间的重试运行仍能保持响应。

当提供商请求的重试延迟超过 retry.provider.maxRetryDelayMs 时，请求将立即失败，并给出明确的错误信息，而不是静默等待。将其设为 0 可禁用此限制。

除非明确需要提供商级重试，否则应将 retry.provider.maxRetries 保持为 0。将其设为大于 0 可能导致 SDK/提供商重试在处理超出使用限制的错误时抢先于 Pi，这可能会在提供商配额重置之前（某些情况下）阻塞代理。

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

消息投递

终端与图像

外壳

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

资源

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

~/.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",
  "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 }
}