Pi Agent 配置参考手册
以下是 Pi Agent settings.json 配置项的速查表。
本表收录常用配置项，少量 JSON 专用高级键（如 tuiMode、fullscreen 系列、terminal.hyperlinks、markdown.mermaid 等）未逐一列出。
配置文件位置
配置分为全局与项目两个层级，项目配置需要先获得项目信任才会加载。
| 文件路径 | 作用范围 | 说明 |
|---|---|---|
| ~/.pi/agent/settings.json | 全局（所有项目） | 对所有项目生效的通用配置 |
| .pi/settings.json | 项目级 | 仅在项目获得信任后加载，覆盖全局配置中的同名键 |
模型与推理
本节配置决定默认使用的提供商、模型与推理强度。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| defaultProvider | string | 可选 | 无（首次通过 /login 或 /model 设置） | 默认提供商，如 "anthropic"、"openai" |
| defaultModel | string | 可选 | 无（首次通过 /login 或 /model 设置） | 默认模型 ID，如 "claude-sonnet-4-20250514" |
| defaultThinkingLevel | string | 可选 | 无（文档未给出） | 默认推理等级：off/minimal/low/medium/high/xhigh/max |
| modelThinkingLevels | object | 可选 | 无 | 按 "provider/modelId" 为各模型设置启动推理等级 |
| hideThinkingBlock | boolean | 可选 | false | 隐藏推理过程 |
| showCacheMissNotices | boolean | 可选 | false | 显示缓存未命中提示 |
| thinkingBudgets | object | 可选 | 无（不启用自定义预算） | 自定义各等级 token 预算 |
| warnings.anthropicExtraUsage | boolean | 可选 | true | Anthropic 订阅可能产生付费额外用量时提醒 |
UI 与显示
本节配置控制界面外观、外部编辑器与显示密度。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| theme | string | 可选 | "dark" | 主题名称 |
| externalEditor | string | 可选 | 依次取 $VISUAL、$EDITOR，否则 Windows 用 Notepad、其他系统用 nano | 外部编辑器命令（显式配置优先于环境变量） |
| quietStartup | boolean | 可选 | false | 隐藏启动头部 |
| defaultProjectTrust | string | 可选 | "ask" | 项目信任默认行为："ask"（询问）、"always"（自动信任）、"never"（自动拒绝），仅全局配置生效 |
| collapseChangelog | boolean | 可选 | false | 折叠更新日志 |
| enableInstallTelemetry | boolean | 可选 | true | 匿名安装统计 |
| enableAnalytics | boolean | 可选 | false | 用户行为分析（需主动开启） |
| doubleEscapeAction | string | 可选 | "tree" | 双击 Escape 触发的动作，默认打开会话树浏览器 |
| 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） |
网络
本节配置用于受限网络环境下的代理接入。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| httpProxy | string | 可选 | 无（不使用代理） | HTTP 代理（仅全局） |
httpProxy 仅全局配置生效，写在项目级配置中无效。
需要代理时请写入 ~/.pi/agent/settings.json。
压缩
本节配置控制上下文自动压缩的触发与保留策略。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| compaction.enabled | boolean | 可选 | true | 自动压缩 |
| compaction.reserveTokens | number | 可选 | 16384 | LLM 响应预留 token |
| compaction.keepRecentTokens | number | 可选 | 20000 | 保留的最近 token |
分支摘要
本节配置控制在会话树之间跳转时是否生成被放弃分支的摘要。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| branchSummary.reserveTokens | number | 可选 | 16384 | 摘要预留 token |
| branchSummary.skipPrompt | boolean | 可选 | false | 跳过摘要提示 |
重试
本节配置控制请求失败后的自动重试行为。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| retry.enabled | boolean | 可选 | true | 自动重试 |
| retry.maxRetries | number | 可选 | 3 | 最大重试次数 |
| retry.baseDelayMs | number | 可选 | 2000 | 基础延迟（ms） |
| retry.provider.timeoutMs | number | 可选 | SDK 默认 | 请求超时 |
| retry.provider.maxRetries | number | 可选 | 0 | 提供商级重试次数 |
| retry.provider.maxRetryDelayMs | number | 可选 | 60000 | 最大重试延迟 |
消息传递
本节配置决定导向与跟进消息的插入方式，以及使用的传输协议。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| steeringMode | string | 可选 | "one-at-a-time" | 导向消息策略："all"（所有导向消息立即插入）或 "one-at-a-time"（逐条插入） |
| followUpMode | string | 可选 | "one-at-a-time" | 跟进消息策略 |
| transport | string | 可选 | "auto" | 传输协议：sse / websocket / websocket-cached / auto |
| httpIdleTimeoutMs | number | 可选 | 300000 | HTTP 空闲超时 |
| websocketConnectTimeoutMs | number | 可选 | 15000 | WebSocket 连接超时 |
终端与图片
本节配置控制终端内图片的显示尺寸与发送行为。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| terminal.showImages | boolean | 可选 | true | 终端显示图片 |
| terminal.imageWidthCells | number | 可选 | 60 | 图片宽度（单元格） |
| terminal.clearOnShrink | boolean | 可选 | false | 内容收缩时清除空行 |
| images.autoResize | boolean | 可选 | true | 图片自动缩放 |
| images.blockImages | boolean | 可选 | false | 阻止图片发送给 LLM |
Shell
本节配置用于自定义执行命令时的 shell 与 npm 包装器。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| shellPath | string | 可选 | 无（使用系统默认 shell） | 自定义 shell 路径 |
| shellCommandPrefix | string | 可选 | 无（不加前缀） | 命令前缀 |
| npmCommand | string[] | 可选 | 无（直接调用 npm） | npm 命令包装器 |
内置工具
本节配置控制启动时默认启用的内置工具集合。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| defaultTools | string[] | 可选 | 无（使用内置默认工具集） | 初始启用的内置工具，可选值 read/bash/powershell/edit/write/grep/find/ls，其中 powershell 仅 Windows 提供 |
该配置只影响内置工具，扩展和 SDK 注册的自定义工具不受影响。
项目级 defaultTools 数组会整体替换全局数组。
模型循环与资源
本节配置管理 Ctrl+P 模型循环范围，以及扩展、Skill 等资源的加载路径。
| 配置项 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| enabledModels | string[] | 可选 | 无（所有可用模型） | Ctrl+P 可用模型 |
| packages | array（字符串或对象混合） | 可选 | [] | 包来源，字符串形式加载全部资源，对象形式用 {source, skills, extensions} 等字段过滤 |
| extensions | string[] | 可选 | [] | 扩展路径 |
| skills | string[] | 可选 | [] | Skill 路径 |
| prompts | string[] | 可选 | [] | 模板路径 |
| themes | string[] | 可选 | [] | 主题路径 |
| enableSkillCommands | boolean | 可选 | true | 注册 /skill:name 命令 |
| sessionDir | string | 可选 | 无（使用 ~/.pi/agent/sessions/） | 会话存储目录 |