设置

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

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

可直接编辑文件，或使用 /settings 处理常用选项。

项目信任

在交互式启动时，如果项目文件夹包含项目本地设置、资源或项目的 .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 使更改生效。

全部设置

模型与思考

设置	类型	默认值	说明
`defaultProvider`	string	-	默认模型提供方（例如 `"anthropic"`、`"openai"`）
`defaultModel`	string	-	默认模型 ID
`defaultThinkingLevel`	string	-	`"off"`、`"minimal"`、`"low"`、`"medium"`、`"high"`、`"xhigh"`、`"max"`
`hideThinkingBlock`	boolean	`false`	在输出中隐藏思考块
`showCacheMissNotices`	boolean	`false`	对显著的提示缓存未命中（prompt-cache miss）显示转录通知
`thinkingBudgets`	object	-	每个思考级别的自定义 token 预算

thinkingBudgets

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

UI 与显示

设置	类型	默认值	说明
`theme`	string	`"dark"`	主题名称（`"dark"`、`"light"` 或自定义）
`externalEditor`	string	`$VISUAL`，然后是 `$EDITOR`，再是 Windows 上的 Notepad 或其他平台上的 `nano`	Ctrl+G 外部编辑器命令；优先于环境变量
`quietStartup`	boolean	`false`	隐藏启动横幅
`defaultProjectTrust`	string	`"ask"`	回退的项目信任行为：`"ask"`、`"always"` 或 `"never"`。仅全局设置
`collapseChangelog`	boolean	`false`	更新后显示精简的更新日志
`enableInstallTelemetry`	boolean	`true`	在首次安装或检测到更新日志更新后发送匿名的安装/更新版本 ping。这不控制更新检查
`enableAnalytics`	boolean	`false`	选择加入的分析数据共享。目前仅在实验性首次安装设置（`PI_EXPERIMENTAL=1`）期间询问
`trackingId`	string	-	分析跟踪标识符，在 `enableAnalytics` 开启时生成
`doubleEscapeAction`	string	`"tree"`	双击 Esc 的操作：`"tree"`、`"fork"` 或 `"none"`
`treeFilterMode`	string	`"default"`	`/tree` 的默认过滤器：`"default"`、`"no-tools"`、`"user-only"`、`"labeled-only"`、`"all"`
`editorPaddingX`	number	`0`	输入编辑器的水平内边距（0-3）
`outputPad`	number	`1`	用户消息、助手消息和思考块的水平内边距（0 或 1）
`autocompleteMaxVisible`	number	`5`	自动补全下拉列表的最大可见项数（3-20）
`showHardwareCursor`	boolean	`false`	在 TUI 定位光标以支持 IME 时显示终端光标
`tuiMode`	string	`"regular"`	交互式 TUI 模式：`"regular"` 或实验性的 `"fullscreen"`。通过 `/settings` 的更改会立即生效；`--tui-mode` 在启动时覆盖此设置
`fullscreenExitOutput`	string	`"transcript"`	全屏退出输出：`"transcript"` 打印最终转录和恢复提示，而 `"resume-hint"` 恢复之前的屏幕并只打印恢复提示。在常规 TUI 模式下无效
`fullscreenScrollbar`	string	`"auto"`	全屏转录滚动条：`"auto"` 在滚动时临时显示，`"always"` 保留最右侧一列并保持可见，`"hidden"` 隐藏。在常规 TUI 模式下无效

对于 VS Code，加入 --wait，这样 pi 会在编辑器退出后恢复：

{
  "externalEditor": "code --wait"
}

遥测与更新检查

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

网络

设置	类型	默认值	说明
`httpProxy`	string	-	作为 `HTTP_PROXY` 和 `HTTPS_PROXY` 应用的 HTTP 代理 URL。仅全局设置。

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

警告

设置	类型	默认值	说明
`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` 导航时跳过“为分支生成摘要？“提示（默认为不生成摘要）

重试

设置	类型	默认值	说明
`retry.enabled`	boolean	`true`	在瞬时错误时启用智能体级别的自动重试
`retry.maxRetries`	number	`3`	智能体级别的最大重试次数
`retry.baseDelayMs`	number	`2000`	智能体级别指数退避的基础延迟（2 秒、4 秒、8 秒）
`retry.provider.timeoutMs`	number	SDK 默认值	模型提供方/SDK 请求超时时间（毫秒）
`retry.provider.maxRetries`	number	`0`	模型提供方/SDK 重试次数
`retry.provider.maxRetryDelayMs`	number	`60000`	失败前允许服务器请求的最大延迟（60 秒）

当模型提供方请求的重试延迟超过 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
    }
  }
}

消息投递

设置	类型	默认值	说明
`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。适用于 `@file` 附件、`read` 以及工具返回的图片
`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	`" "`	代码块的缩进
`markdown.mermaid`	string	`"streaming"`	Mermaid 渲染模式：`"off"`、`"final"` 或 `"streaming"`

资源

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

~/.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": []
    }
  ]
}

包管理详情请参阅包管理。

示例

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