settings.json 配置大全

配置文件在哪

pi 用两个 JSON 文件管理配置：

文件	作用范围	怎么编辑
~/.pi/agent/settings.json	全局，影响所有项目	直接编辑文件，或交互模式里用 /settings
.pi/settings.json	项目级，只影响当前目录	同上

项目配置的优先级高于全局配置。也就是说，项目级 settings.json 里的值会覆盖全局的同名字段。

一个最小配置长什么样

至少要告诉 pi 用哪个模型：

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514"
}

这两个字段是必填的——不然 pi 不知道找谁要答案。其余所有字段都是可选的，pi 会给它们用默认值。

首次启动 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
  }
}

看效果：compaction.reserveTokens 被项目配置覆盖成了 8192，但 compaction.enabled 和 theme 继续沿用全局配置。项目配置只覆盖你明确写的字段，没写的保留全局值。

配置项一览表

下面按分类把主要配置项过一遍。不用背，当成速查目录就行：

模型与推理

配置项	类型	默认值	一句话说明
defaultProvider	string	—	默认模型提供商，如 "anthropic"、"openai"
defaultModel	string	—	默认模型 ID
defaultThinkingLevel	string	—	推理深度："off"、"low"、"medium"、"high" 等
hideThinkingBlock	boolean	false	隐藏 AI 的推理过程，只看最终回答
showCacheMissNotices	boolean	false	显示提示词缓存未命中的提示
thinkingBudgets	object	—	自定义各推理等级对应的 token 预算

UI 与显示

配置项	类型	默认值	一句话说明
theme	string	"dark"	主题："dark"、"light"，或自定义主题名
externalEditor	string	系统默认	Ctrl+G 打开的外部编辑器（VS Code 用户设 "code --wait"）
quietStartup	boolean	false	关闭启动时的头部信息
defaultProjectTrust	string	"ask"	项目信任策略："ask"、"always"、"never"（仅全局配置）
treeFilterMode	string	"default"	/tree 的默认过滤模式
doubleEscapeAction	string	"tree"	双击 Escape 触发什么："tree"、"fork"、"none"
editorPaddingX	number	0	编辑器水平内边距（0-3）
autocompleteMaxVisible	number	5	自动补全最多显示几项（3-20）

网络与代理

配置项	类型	默认值	一句话说明
httpProxy	string	—	HTTP 代理地址，如 "http://127.0.0.1:7890"（仅全局配置）

如果你在国内需要代理才能访问 OpenAI 或 Anthropic API，在这里设你的代理地址。

上下文压缩

配置项	类型	默认值	一句话说明
compaction.enabled	boolean	true	是否开启自动压缩
compaction.reserveTokens	number	16384	留给模型回复的 token 空间
compaction.keepRecentTokens	number	20000	保留不被压缩的最近 token 数

分支摘要

配置项	类型	默认值	一句话说明
branchSummary.reserveTokens	number	16384	分支摘要的 token 预算
branchSummary.skipPrompt	boolean	false	/tree 跳转时跳过”是否摘要”的提问

重试策略

配置项	类型	默认值	一句话说明
retry.enabled	boolean	true	API 出错时自动重试
retry.maxRetries	number	3	最多重试几次
retry.baseDelayMs	number	2000	重试基础间隔（毫秒），指数退避：2s → 4s → 8s
retry.provider.timeoutMs	number	SDK 默认	请求超时时间（毫秒）
retry.provider.maxRetries	number	0	提供商级别的重试次数（一般保持为 0）

消息传输

配置项	类型	默认值	一句话说明
steeringMode	string	"one-at-a-time"	steering 消息发送策略
followUpMode	string	"one-at-a-time"	follow-up 消息发送策略
transport	string	"auto"	传输协议偏好："sse"、"websocket"、"auto"

终端与图片

配置项	类型	默认值	一句话说明
terminal.showImages	boolean	true	终端里显示图片（需终端支持）
terminal.imageWidthCells	number	60	内嵌图片宽度（终端单元格）
images.autoResize	boolean	true	图片自动缩放到 2000×2000 以内
images.blockImages	boolean	false	阻止所有图片发给模型

Shell

配置项	类型	默认值	一句话说明
shellPath	string	—	自定义 shell 路径（如 Cygwin）
shellCommandPrefix	string	—	每个 bash 命令执行前的前置命令
npmCommand	string[]	—	自定义 npm 命令路径（如用 mise 管理 Node 时）

会话

配置项	类型	默认值	一句话说明
sessionDir	string	—	自定义会话文件存储目录

模型循环

配置项	类型	默认值	一句话说明
enabledModels	string[]	—	Ctrl+P 切换模型时显示哪些模型，支持通配符如 "claude-*"

资源加载

配置项	类型	默认值	一句话说明
packages	array	[]	从 npm/git 加载的扩展包
extensions	string[]	[]	本地 extension 路径
skills	string[]	[]	本地 skill 路径
prompts	string[]	[]	本地提示词模板路径
themes	string[]	[]	本地主题路径
enableSkillCommands	boolean	true	把 skill 注册为 /skill:名称 命令

一个典型的全局配置

把上面这些串起来，一个实用的全局配置大概是这样：

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "externalEditor": "code --wait",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  }
}

配置优先级总结

当多个来源定义了同一个配置项时，生效优先级从高到低：

1. CLI 参数（比如 --model、--session-dir）——启动时直接覆盖
2. 项目级 .pi/settings.json——只影响当前项目
3. 全局级 ~/.pi/agent/settings.json——所有项目的兜底
4. 环境变量（比如 PI_SKIP_VERSION_CHECK）——少数字段支持
5. 内置默认值——pi 源码里的硬编码默认值

理解这个优先级就够了。日常使用时改全局 settings.json，特定项目需要不同配置时在项目里加一个 .pi/settings.json。

下一步

这张配置地图先看到这里。每个字段的详细说明、边界值、使用场景，记得到第 28 章”配置参考手册”去查。接下来几章我们来看看怎么通过 providers、prompts 和 skills 让 pi 更顺手。