7 设置

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

可以直接编辑，也可以使用 /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 可为单次运行覆盖项目信任。

如果没有扩展或已保存决定适用，则由 defaultProjectTrust 控制回退行为。在 ~/.pi/agent/settings.json 中将其设为 "ask"、"always" 或 "never"，或通过 /settings 修改。

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 可禁用 Pi 版本更新检查。使用 --offline 或 PI_OFFLINE=1 可禁用本文所述的所有启动网络操作，包括更新检查、包更新检查和安装/更新遥测。

网络

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

警告

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

上下文压缩

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

每模型压缩覆盖

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000,
    "modelOverrides": {
      "some-provider/big-model": {
        "reserveTokens": 400000
      },
      "local/small-model": {
        "reserveTokens": 2048,
        "keepRecentTokens": 4096
      }
    }
  }
}

键必须精确匹配区分大小写的 provider/modelId 值，而不是名称或 glob 模式。模型 ID 可能包含斜杠（例如 openrouter/anthropic/claude-sonnet-4）。

每个 token 设置独立解析：匹配的模型覆盖 → 普通 compaction 设置 → 内置默认值。在上面的例子中，some-provider/big-model 仍保留普通的 20000 近期 token。token 值必须是非负的安全整数。匹配的模型覆盖中存在无效值时会在读取时报错；只有省略的字段才会回退到普通设置。模型覆盖条目必须是对象。普通 token 设置存在无效值时同样会在读取时报错，即使当前模型有有效的覆盖。只有省略的普通值才使用内置默认值。零是允许的，但 reserveTokens: 0 会失去回复余量，并将摘要输出预算也设为零。

全局和项目设置在模型查找之前递归合并。项目可以只覆盖某个模型的某一个字段，而不替换它的其他字段或其他模型。全局的模型专属值优先于项目范围的回退值；要更改它，需在项目中覆盖同一模型条目。

enabled 不区分模型。当前模型的 token 设置适用于手动压缩、自动阈值检查（包括助手回合之间）以及溢出恢复。切换模型会在下一次检查或压缩时生效。覆盖请在 JSON 中配置；/settings 只保留普通的自动压缩开关。

触发和摘要行为参见 compaction.md。

分支摘要

重试

智能体级重试使用以 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
    }
  }
}

消息送达

终端与图片

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

资源

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

~/.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",
  "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 (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

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