Pi Agent 配置详解

Pi Agent 使用 JSON 格式的配置文件，支持全局配置和项目级配置，项目配置会覆盖全局配置。

配置文件位置

文件路径	作用范围	说明
~/.pi/agent/settings.json	全局（所有项目）	适用于所有项目的通用配置
.pi/settings.json	项目级	仅对当前项目生效，会覆盖全局配置

可以直接编辑 JSON 文件，或使用交互模式中的 /settings 命令来修改常用选项。

模型与推理配置

配置项	类型	默认值	说明
defaultProvider	string	-	默认提供商，如 "anthropic"、"openai"
defaultModel	string	-	默认模型 ID
defaultThinkingLevel	string	-	默认推理等级
hideThinkingBlock	boolean	false	默认隐藏 AI 推理过程
showCacheMissNotices	boolean	false	显示缓存未命中提示
thinkingBudgets	object	-	自定义各等级 token 预算

自定义推理预算示例：

实例

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

UI 与显示配置

配置项	类型	默认值	说明
theme	string	"dark"	主题名称
externalEditor	string	根据系统自动选择	Ctrl+G 打开的外部编辑器命令
quietStartup	boolean	false	隐藏启动头部信息
collapseChangelog	boolean	false	更新后显示折叠的更新日志
editorPaddingX	number	0	编辑器水平内边距（0-3）
outputPad	number	1	消息区域水平内边距（0 或 1）
autocompleteMaxVisible	number	5	自动补全最大可见条目（3-20）

VS Code 用户推荐的外部编辑器配置：

实例

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

--wait 参数确保 Pi Agent 在 VS Code 关闭文件后才恢复运行，否则编辑器打开后 Pi Agent 会立即继续执行。

网络配置

配置项	类型	默认值	说明
httpProxy	string	-	HTTP 代理 URL（仅全局配置）

设置代理（适用于中国大陆等需要代理访问 API 的环境）：

实例

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

上下文压缩配置

配置项	类型	默认值	说明
compaction.enabled	boolean	true	启用自动压缩
compaction.reserveTokens	number	16384	预留给 LLM 响应的 token
compaction.keepRecentTokens	number	20000	保留不压缩的最近 token 数

重试配置

配置项	类型	默认值	说明
retry.enabled	boolean	true	启用自动重试
retry.maxRetries	number	3	最大重试次数
retry.baseDelayMs	number	2000	重试基础延迟（毫秒），指数退避：2s、4s、8s
retry.provider.timeoutMs	number	SDK 默认	请求超时时间（毫秒）
retry.provider.maxRetries	number	0	提供商级别的重试次数

建议将 retry.provider.maxRetries 保持为 0，除非你确实需要提供商级别的重试。设置为大于 0 可能导致在用量超限时 SDK 层面的重试阻塞 Pi Agent，而不是让 Pi Agent 层面的重试机制来处理。

消息传递配置

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

终端与图片配置

配置项	类型	默认值	说明
terminal.showImages	boolean	true	在终端中显示图片
terminal.imageWidthCells	number	60	内嵌图片宽度（终端单元格）
images.autoResize	boolean	true	将图片缩放至 2000x2000 以内
images.blockImages	boolean	false	阻止所有图片发送给 LLM

Shell 配置

配置项	类型	默认值	说明
shellPath	string	-	自定义 shell 路径
shellCommandPrefix	string	-	每个 bash 命令的前缀
npmCommand	string[]	-	用于 npm 包操作的自定义命令

使用 mise 或 asdf 等工具管理 Node.js 版本的示例：

实例

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

模型循环配置

配置项	类型	默认值	说明
enabledModels	string[]	-	Ctrl+P 循环时可用的模型列表，支持通配符

实例

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

配置合并规则

项目配置（.pi/settings.json）会覆盖全局配置（~/.pi/agent/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 保留全局配置的 true 值。

完整配置示例

以下是一个典型的全局配置文件：

实例

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

返回顶部

菜鸟教程