9 设置

9.1 概述

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

位置	作用范围
`~/.pi/agent/settings.json`	全局（所有项目）
`.pi/settings.json`	项目（当前目录）

你可以直接编辑这些文件，或使用 /settings 命令调整常用选项。

9.2 项目信任

在交互式启动时，如果项目包含需要信任的资源（项目本地设置、资源或项目 .agents/skills），且在 ~/.pi/agent/trust.json 中没有为该文件夹或父文件夹保存的决策，Pi 会询问是否信任。

Note

信任项目后，Pi 会加载 .pi/settings.json 和 .pi 资源、安装缺失的项目包并执行项目扩展。非交互模式使用 defaultProjectTrust 设置控制行为。

9.3 所有设置项

9.3.1 模型与思考

设置	类型	默认值	描述
`defaultProvider`	string	-	默认提供商（如 `"anthropic"`、`"openai"`）
`defaultModel`	string	-	默认模型 ID
`defaultThinkingLevel`	string	-	思考级别：`"off"`、`"minimal"`、`"low"`、`"medium"`、`"high"`、`"xhigh"`、`"max"`
`hideThinkingBlock`	boolean	`false`	在输出中隐藏思考块
`showCacheMissNotices`	boolean	`false`	显示显著 Prompt 缓存未命中的通知
`thinkingBudgets`	object	-	按思考级别的自定义 Token 预算

9.3.1.1 thinkingBudgets 示例

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

Tip

thinkingBudgets 让你精确控制每个思考级别的 Token 预算。较高的预算意味着模型可以”思考”更长时间，但会消耗更多 Token。

9.3.2 UI 与显示

设置	类型	默认值	描述
`theme`	string	`"dark"`	主题名称（`"dark"`、`"light"` 或自定义）
`externalEditor`	string	$VISUAL → $EDITOR → Notepad/nano	Ctrl+G 外部编辑器命令
`quietStartup`	boolean	`false`	隐藏启动头
`defaultProjectTrust`	string	`"ask"`	项目信任回退行为：`"ask"`、`"always"`、`"never"`（仅全局设置）
`collapseChangelog`	boolean	`false`	更新后显示精简版更新日志
`doubleEscapeAction`	string	`"tree"`	双击 Escape 的动作：`"tree"`、`"fork"` 或 `"none"`
`treeFilterMode`	string	`"default"`	`/tree` 默认过滤器
`editorPaddingX`	number	`0`	输入编辑器水平内边距（0-3）
`outputPad`	number	`1`	用户消息、助手消息和思考的水平内边距（0 或 1）
`autocompleteMaxVisible`	number	`5`	自动补全下拉菜单最大可见项数（3-20）
`showHardwareCursor`	boolean	`false`	显示终端硬件光标（用于 IME 支持）

Note

对于 VS Code，在 externalEditor 中包含 --wait，这样 Pi 会在编辑器关闭后恢复："code --wait"。

9.3.3 遥测与更新检查

设置	类型	默认值	描述
`enableInstallTelemetry`	boolean	`true`	发送匿名安装/更新版本 ping
`enableAnalytics`	boolean	`false`	可选分析数据共享
`trackingId`	string	-	分析跟踪标识符

Warning

enableInstallTelemetry 仅控制匿名安装/更新 ping（发送到 https://pi.dev/api/report-install）。关闭遥测不会禁用更新检查——Pi 仍会获取 https://pi.dev/api/latest-version 来检查最新版本。

设置 PI_SKIP_VERSION_CHECK=1 可禁用 Pi 版本更新检查。使用 --offline 或 PI_OFFLINE=1 可禁用所有启动时的网络操作。

9.3.4 网络

设置	类型	默认值	描述
`httpProxy`	string	-	HTTP 代理 URL（应用为 `HTTP_PROXY` 和 `HTTPS_PROXY`，仅全局设置）

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

9.3.5 警告

设置	类型	默认值	描述
`warnings.anthropicExtraUsage`	boolean	`true`	当 Anthropic 订阅认证可能使用付费额外使用时显示警告

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

9.3.6 压缩（Compaction）

设置	类型	默认值	描述
`compaction.enabled`	boolean	`true`	启用自动压缩
`compaction.reserveTokens`	number	`16384`	为 LLM 响应预留的 Token 数
`compaction.keepRecentTokens`	number	`20000`	保留的最近 Token 数（不被摘要）

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

9.3.7 分支摘要

设置	类型	默认值	描述
`branchSummary.reserveTokens`	number	`16384`	分支摘要预留 Token
`branchSummary.skipPrompt`	boolean	`false`	跳过”是否摘要分支？“提示（默认不摘要）

9.3.8 重试

设置	类型	默认值	描述
`retry.enabled`	boolean	`true`	启用代理级自动重试
`retry.maxRetries`	number	`3`	最大代理级重试次数
`retry.baseDelayMs`	number	`2000`	代理级指数退避基础延迟（2s, 4s, 8s）
`retry.provider.timeoutMs`	number	SDK 默认	提供商/SDK 请求超时（毫秒）
`retry.provider.maxRetries`	number	`0`	提供商/SDK 重试次数
`retry.provider.maxRetryDelayMs`	number	`60000`	服务器请求的最大延迟（60s）

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

Warning

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

9.3.9 消息传递

设置	类型	默认值	描述
`steeringMode`	string	`"one-at-a-time"`	引导消息发送方式：`"all"` 或 `"one-at-a-time"`
`followUpMode`	string	`"one-at-a-time"`	后续消息发送方式：`"all"` 或 `"one-at-a-time"`
`transport`	string	`"auto"`	支持多传输的提供商的首选传输方式：`"sse"`、`"websocket"`、`"websocket-cached"` 或 `"auto"`
`httpIdleTimeoutMs`	number	`300000`	HTTP 空闲超时（毫秒），设为 0 禁用
`websocketConnectTimeoutMs`	number	`15000`	WebSocket 连接超时（毫秒），设为 0 禁用

9.3.10 终端与图片

设置	类型	默认值	描述
`terminal.showImages`	boolean	`true`	在终端中显示图片（如支持）
`terminal.imageWidthCells`	number	`60`	内联图片首选宽度（终端字符宽度）
`terminal.clearOnShrink`	boolean	`false`	内容缩小时清除空行（可能导致闪烁）
`images.autoResize`	boolean	`true`	将图片调整为最大 2000x2000
`images.blockImages`	boolean	`false`	阻止所有图片发送给 LLM

9.3.11 Shell

设置	类型	默认值	描述
`shellPath`	string	-	自定义 Shell 路径（如 Windows 上的 Cygwin）；支持前导 `~`
`shellCommandPrefix`	string	-	每个 bash 命令的前缀（如 `"shopt -s expand_aliases"`）
`npmCommand`	string[]	-	npm 包查找/安装操作的命令

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

Note

npmCommand 用于所有 npm 包管理操作，包括安装、卸载和 git 包内的依赖安装。用户级包安装在 ~/.pi/agent/npm/ 下，项目级包安装在 .pi/npm/ 下。

9.3.12 会话

设置	类型	默认值	描述
`sessionDir`	string	-	会话文件存储目录。接受绝对路径、相对路径和 `~`

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

会话目录优先级：--session-dir > PI_CODING_AGENT_SESSION_DIR > settings.json 中的 sessionDir。

9.3.13 模型循环

设置	类型	默认值	描述
`enabledModels`	string[]	-	Ctrl+P 循环的模型模式（与 `--models` CLI 标志格式相同）

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

9.3.14 Markdown

设置	类型	默认值	描述
`markdown.codeBlockIndent`	string	`" "`	代码块缩进

9.4 资源设置

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

Note

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

设置	类型	默认值	描述
`packages`	array	`[]`	要加载资源的 npm/git 包
`extensions`	string[]	`[]`	本地扩展文件路径或目录
`skills`	string[]	`[]`	本地技能文件路径或目录
`prompts`	string[]	`[]`	本地提示词模板路径或目录
`themes`	string[]	`[]`	本地主题文件路径或目录
`enableSkillCommands`	boolean	`true`	将技能注册为 `/skill:name` 命令

数组支持 glob 模式和排除规则。使用 !pattern 排除，+path 强制包含，-path 强制排除。

9.4.1 packages 配置

字符串形式加载包的所有资源：

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

对象形式筛选要加载的资源：

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

9.5 完整示例

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

9.6 项目覆盖规则

项目设置（.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 }
}

Tip

深度合并意味着你可以在项目设置中只覆盖需要改变的字段，而不必重复整个配置。对于标量值（字符串、数字、布尔值），项目设置直接覆盖；对于对象，进行递归合并。