设置

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

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

直接编辑或使用 /settings 进行常见选项。

所有设置

模型与思考

设置	类型	默认	说明
defaultProvider	string	-	默认提供商（如 "anthropic"、"openai"）
defaultModel	string	-	默认模型 ID
defaultThinkingLevel	string	-	"off"、"minimal"、"low"、"medium"、"high"、"xhigh"
hideThinkingBlock	boolean	false	隐藏输出中的思考块
thinkingBudgets	object	-	每个思考级别的自定义 token 配额

thinkingBudgets

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

UI 与显示

设置	类型	默认	说明
theme	string	"dark"	主题名称（"dark"、"light" 或自定义）
quietStartup	boolean	false	隐藏启动头
collapseChangelog	boolean	false	更新后显示浓缩变更日志
enableInstallTelemetry	boolean	true	首次安装或检测到变更日志后发送匿名安装/更新版本 ping。这不会控制更新检查
doubleEscapeAction	string	"tree"	双转义操作："tree"、"fork" 或 "none"
treeFilterMode	string	"default"	/tree 的默认过滤器："default"、"no-tools"、"user-only"、"labeled-only"、"all"
editorPaddingX	number	0	输入编辑器的水平边距（0-3）
autocompleteMaxVisible	number	5	自动补全下拉菜单中最多可见项目数（3-20）
showHardwareCursor	boolean	false	显示终端光标

遥测与更新检查

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

警告

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

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

压缩

设置	类型	默认	说明
compaction.enabled	boolean	true	启用自动压缩
compaction.reserveTokens	number	16384	为 LLM 响应保留的 token
compaction.keepRecentTokens	number	20000	保留的最近 token（不汇总）

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

分支摘要

设置	类型	默认	说明
branchSummary.reserveTokens	number	16384	为分支汇总保留的 token
branchSummary.skipPrompt	boolean	false	在 /tree 导航时跳过 "Summarize branch?" 提示（默认为不汇总）

重试

设置	类型	默认	说明
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.provider.maxRetryDelayMs（例如 Google 的 "quota 将在 5 小时后重置"）时，请求会立即以信息性错误失败，而不是静默等待。设置为 0 可禁用上限。

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

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

消息交付

设置	类型	默认	说明
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 传输的提供商的 WebSocket 连接/打开握手超时（毫秒）。设置为 0 可禁用。

终端与图像

设置	类型	默认	说明
terminal.showImages	boolean	true	在终端中显示图像（如支持）
terminal.imageWidthCells	number	60	终端中的首选内联图像宽度
terminal.clearOnShrink	boolean	false	内容缩小时清空空行（可能导致闪烁）
images.autoResize	boolean	true	将图像缩放到最大 2000x2000
images.blockImages	boolean	false	阻止所有图像发送给 LLM

Shell

设置	类型	默认	说明
shellPath	string	-	自定义 shell 路径（如 Windows 上的 Cygwin）
shellCommandPrefix	string	-	每个 bash 命令的前缀（如 "shopt -s expand_aliases"）
npmCommand	string[]	-	用于 npm 包查找/安装操作的命令 argv（如 ["mise", "exec", "node@20", "--", "npm"]）

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

npmCommand 用于所有 npm 包管理器操作，包括安装、卸载和 git 包内的依赖安装。用户范围的 npm 包安装在 ~/.pi/agent/npm/ 下；项目范围的 npm 包安装在 .pi/npm/ 下。使用 argv 风格的条目，完全按照应启动进程的方式。当配置 npmCommand 时，git 包依赖安装使用纯 install，以避免在包装器或替代包管理器中出现 npm 特定标志。

会话

设置	类型	默认	说明
sessionDir	string	-	会话文件存储的目录。接受绝对或相对路径，以及 ~。

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

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

模型循环

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

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

Markdown

设置	类型	默认	说明
markdown.codeBlockIndent	string	" "	代码块的缩进

资源

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

~/.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 强制排除确切路径。

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",
  "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 }
}