Pi Agent 配置详解
Pi Agent 使用 JSON 格式的配置文件，支持全局配置和项目级配置。
配置文件位置
Pi Agent 从两个固定路径读取配置，两者的优先级不同。
| 文件路径 | 作用范围 | 说明 |
|---|---|---|
| ~/.pi/agent/settings.json | 全局（所有项目） | 适用于所有项目的通用配置 |
| .pi/settings.json | 项目级 | 仅对当前项目生效，会覆盖全局配置 |
可以直接编辑 JSON 文件，或使用交互模式中的 /settings 命令来修改常用选项。
模型与推理配置
以下配置项控制默认使用哪个提供商、哪个模型，以及推理预算如何分配。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| defaultProvider | string | - | 默认提供商，如 "anthropic"、"openai" |
| defaultModel | string | - | 默认模型 ID |
| defaultThinkingLevel | string | - | 默认推理等级，可选值为 off / minimal / low / medium / high / xhigh / max |
| hideThinkingBlock | boolean | false | 默认隐藏 AI 推理过程 |
| showCacheMissNotices | boolean | false | 显示缓存未命中提示 |
| thinkingBudgets | object | - | 自定义各等级 token 预算 |
自定义推理预算示例：
实例
"thinkingBudgets": {
"minimal": 1024,
"low": 4096,
"medium": 10240,
"high": 32768
}
}
需要说明的是，以下数值仅为演示写法，并非官方默认值。
各等级的含义与示例预算的对应关系如下：
| 等级 | 适用场景 | 示例预算 |
|---|---|---|
| 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 会立即继续执行。
网络配置
以下配置项控制 Pi Agent 访问模型 API 时使用的代理。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| httpProxy | string | - | HTTP 代理 URL（仅全局配置） |
设置代理（适用于中国大陆等需要代理访问 API 的环境）：
实例
"httpProxy": "http://127.0.0.1:7890"
}
上下文压缩配置
上下文接近上限时 Pi Agent 会自动压缩历史消息，这里控制压缩的触发与保留策略。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| 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 配置
以下配置项控制 Pi Agent 执行 bash 命令时使用的 shell 与命令前缀。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| shellPath | string | - | 自定义 shell 路径 |
| shellCommandPrefix | string | - | 每个 bash 命令的前缀 |
| npmCommand | string[] | - | 用于 npm 包操作的自定义命令 |
使用 mise 或 asdf 等工具管理 Node.js 版本的示例：
实例
"npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}
模型循环配置
以下配置项控制 Ctrl+P 循环切换模型时可以看到哪些模型。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| 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，compaction.reserveTokens 被项目配置覆盖为 8192。
也就是说，项目配置只覆盖它显式声明过的字段，其余字段继续沿用全局配置。
完整配置示例
以下是一个典型的全局配置文件：
实例
"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"]
}
warnings.anthropicExtraUsage 是布尔值，默认 true。
它会在 Anthropic 订阅鉴权可能产生付费额外用量时给出提醒。
packages 是已安装包过滤配置，用于声明要加载的包。