piagent配置速查：settings.json全字段详解与三种实用模板

本教程共 30 篇 · 第 28 篇 · 更新于 2026-08-10 · 约 16 分钟阅读

本节目标：拿到 settings.json 所有字段的完整速查表——每个字段的类型、默认值、说明、改了会怎样，外加三个一键复制就能用的配置模板。

第 9 章讲了配置文件在哪、全局和项目配置怎么配合。这一章不再重复那些基础概念，专注一件事：把所有字段列清楚，让你翻一次就知道查哪个字段调什么效果。

本章基于 pi v0.84.1。配置文件位置：全局 ~/.pi/agent/settings.json，项目级 .pi/settings.json。

模型与推理

字段	类型	默认值	说明	变更影响
`defaultProvider`	string	—	默认 AI 提供商，如 `"anthropic"`、`"openai"`、`"google"`	改完重进交互模式生效；所有没显式指定 provider 的会话走这个
`defaultModel`	string	—	默认模型 ID，如 `"claude-sonnet-4-20250514"`	同上
`defaultThinkingLevel`	string	—	默认推理等级：`"off"` / `"minimal"` / `"low"` / `"medium"` / `"high"` / `"xhigh"` / `"max"`	设置后新会话默认用这个推理深度；交互模式里可以 Shift+Tab 临时切
`hideThinkingBlock`	boolean	`false`	设为 `true` 隐藏模型的推理过程块	只影响显示，不影响实际推理行为
`showCacheMissNotices`	boolean	`false`	设为 `true` 显示 prompt cache 未命中的提示	排错时开一下有用，平时建议关着
`thinkingBudgets`	object	—	自定义各推理等级的 token 预算	改了之后对应等级的最大推理 token 数变化，影响模型思考深度

thinkingBudgets 的结构：

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

只写你想改的等级就行，没写的用内置默认值。

UI 与显示

字段	类型	默认值	说明	变更影响
`theme`	string	`"dark"`	主题名称：`"dark"`、`"light"`，或自定义主题名	交互模式颜色方案立即改变
`externalEditor`	string	自动检测	外部编辑器命令，Ctrl+G 触发	下一轮按 Ctrl+G 时用新的编辑器
`quietStartup`	boolean	`false`	`true` 隐藏启动头部信息	下次启动生效，界面更干净
`defaultProjectTrust`	string	`"ask"`	项目信任默认行为：`"ask"` / `"always"` / `"never"`（仅全局）	非交互模式下影响是否加载项目配置
`collapseChangelog`	boolean	`false`	`true` 折叠更新日志	更新后显示更精简
`enableInstallTelemetry`	boolean	`true`	`true` 发送匿名安装/更新版本 ping	关掉不影响功能，只是不发统计
`enableAnalytics`	boolean	`false`	用户行为分析（需主动开启）	打开后生成 trackingId
`doubleEscapeAction`	string	`"tree"`	双击 Escape 的行为：`"tree"` / `"fork"` / `"none"`	立即生效
`treeFilterMode`	string	`"default"`	`/tree` 默认过滤模式：`"default"` / `"no-tools"` / `"user-only"` / `"labeled-only"` / `"all"`	下次打开 `/tree` 生效
`editorPaddingX`	number	`0`	编辑器水平内边距（0-3）	立即生效
`outputPad`	number	`1`	消息内边距（0 或 1）	立即生效
`autocompleteMaxVisible`	number	`5`	自动补全最大可见条目（3-20）	立即生效
`showHardwareCursor`	boolean	`false`	显示终端硬件光标，用于 IME 输入法支持	立即生效
`tuiMode`	string	`"regular"`	TUI 模式：`"regular"` 或 `"fullscreen"`（实验性）	`/settings` 里改立即生效，`--tui-mode` CLI 参数覆盖
`fullscreenExitOutput`	string	`"transcript"`	全屏退出时输出：`"transcript"` 打印全部 / `"resume-hint"` 只打恢复提示	全屏模式退出时生效
`fullscreenScrollbar`	string	`"auto"`	全屏滚动条：`"auto"` / `"always"` / `"hidden"`	立即生效

externalEditor 的典型设置：

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

--wait 是关键的，保证 VS Code 关闭后 pi 才继续。

网络

字段	类型	默认值	说明	变更影响
`httpProxy`	string	—	HTTP 代理 URL，同时影响 `HTTP_PROXY` 和 `HTTPS_PROXY`（仅全局）	设置后 pi 的所有 HTTP 请求走代理

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

Tip

如果你有多个代理（比如公司 VPN + 个人代理），httpProxy 写全局配置，个别项目在环境变量里覆盖。优先级：环境变量 > settings.json。

警告

字段	类型	默认值	说明
`warnings.anthropicExtraUsage`	boolean	`true`	Anthropic 订阅用户可能产生额外使用费时是否弹警告

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

上下文压缩（compaction）

字段	类型	默认值	说明	变更影响
`compaction.enabled`	boolean	`true`	开启自动压缩	下一次发送消息前生效
`compaction.reserveTokens`	number	`16384`	为 LLM 响应预留的 token 数	触发压缩的阈值变化——值越小越早压缩
`compaction.keepRecentTokens`	number	`20000`	压缩时保留最近的 token 数，不被总结	值越大保留的近期对话越多，越晚溢出但每次压缩释放的 token 越少

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

分支摘要（branchSummary）

字段	类型	默认值	说明	变更影响
`branchSummary.reserveTokens`	number	`16384`	分支摘要预留 token 数	摘要生成时可用 token 变化
`branchSummary.skipPrompt`	boolean	`false`	`true` 跳过生成摘要的确认提示	在 `/tree` 中切换分支时不再问

重试策略

字段	类型	默认值	说明	变更影响
`retry.enabled`	boolean	`true`	开启 agent 级自动重试	临时错误时自动重试，不丢会话
`retry.maxRetries`	number	`3`	最大重试次数	值越大，临时错误时越能撑过去，但等候时间更长
`retry.baseDelayMs`	number	`2000`	基础延迟（ms），指数退避：2s→4s→8s	影响重试节奏
`retry.provider.timeoutMs`	number	SDK 默认	提供商请求超时（ms）	对响应慢的模型，调大可以避免误判超时
`retry.provider.maxRetries`	number	`0`	提供商级重试次数	建议保持 0，大于 0 可能让额度耗尽类错误被 SDK 层吞掉
`retry.provider.maxRetryDelayMs`	number	`60000`	服务器要求重试的最长等待时间	超过这个延迟直接报错而非傻等

{
  "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 空闲超时（ms），设为 0 禁用	连接空闲超过此值断开
`websocketConnectTimeoutMs`	number	`15000`	WebSocket 连接超时（ms），设为 0 禁用	网络差时可以调大

终端与图片

字段	类型	默认值	说明	变更影响
`terminal.showImages`	boolean	`true`	终端显示图片（需终端支持）	立即生效，关掉后图片以占位符显示
`terminal.imageWidthCells`	number	`60`	图片宽度（终端单元格）	已显示的图片不变，新图生效
`terminal.clearOnShrink`	boolean	`false`	内容收缩时清除空行（可能闪烁）	打开后界面更紧凑但可能有闪烁
`images.autoResize`	boolean	`true`	图片自动缩放到 2000x2000 以内	影响 `@file` 附件和工具返回的图片
`images.blockImages`	boolean	`false`	阻止所有图片发送给 LLM	打开后 LLM 收不到图片内容

Shell

字段	类型	默认值	说明	变更影响
`shellPath`	string	—	自定义 shell 路径（例如 Cygwin），支持 `~`	下次执行 bash 工具时用新 shell
`shellCommandPrefix`	string	—	每个 bash 命令前加的前缀	可以用来加载别名或环境
`npmCommand`	string[]	—	npm 命令包装器，如 `["mise","exec","node@20","--","npm"]`	影响所有 npm 包管理操作

会话存储

字段	类型	默认值	说明	变更影响
`sessionDir`	string	—	会话文件存储目录，支持绝对路径、相对路径和 `~`	新会话存到新路径；旧会话还在原位置

优先级：--session-dir > PI_CODING_AGENT_SESSION_DIR > sessionDir。

模型循环

字段	类型	默认值	说明	变更影响
`enabledModels`	string[]	—	Ctrl+P 循环可用的模型模式列表	立即生效

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

格式和 --models CLI 参数一样，支持通配符。

Markdown 渲染

字段	类型	默认值	说明	变更影响
`markdown.codeBlockIndent`	string	`" "`	代码块缩进	之后渲染的代码块缩进量变化
`markdown.mermaid`	string	`"streaming"`	Mermaid 图表渲染：`"off"` / `"final"` / `"streaming"`	`"streaming"` 实时渲染，`"final"` 等回答完再渲染

资源路径

这些字段定义扩展、技能、模板和主题从哪里加载。全局配置里写的路径相对于 ~/.pi/agent，项目配置里写的相对于 .pi。绝对路径和 ~ 也支持。

字段	类型	默认值	说明
`packages`	array	`[]`	npm/git 包，从中加载资源
`extensions`	string[]	`[]`	本地扩展文件路径或目录
`skills`	string[]	`[]`	本地 skill 文件路径或目录
`prompts`	string[]	`[]`	本地提示词模板路径或目录
`themes`	string[]	`[]`	本地主题文件路径或目录
`enableSkillCommands`	boolean	`true`	是否注册 `/skill:name` 命令

packages 支持两种写法。字符串形式加载包的全部资源：

{
  "packages": ["pi-skills", "@org/my-extension"]
}

对象形式精确控制加载哪些资源：

{
  "packages": [
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

数组支持 glob 模式和排除语法——!pattern 排除匹配的，+path 强制包含，-path 强制排除。

三种实用配置模板

模板一：最小配置（新手起步）

只写必填字段，其余全走默认值：

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

适用场景：刚装好 pi，只想知道这东西能不能跑。两条字段就够了。

模板二：全功能配置（日常主力）

覆盖常用偏好的完整配置：

{
  "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"],
  "externalEditor": "code --wait",
  "httpProxy": "http://127.0.0.1:7890"
}

适用场景：日常开发主力工具。包含了常用 provider、中等推理深度、自动压缩、重试保护、skills 包和代理设置。

模板三：本地模型配置（离线/省钱）

用 llama.cpp 跑本地模型，完全不联网：

{
  "defaultProvider": "llamacpp",
  "defaultModel": "llama3.1-8b",
  "defaultThinkingLevel": "off",
  "terminal": {
    "showImages": false
  },
  "compaction": {
    "enabled": true,
    "reserveTokens": 4096,
    "keepRecentTokens": 8192
  },
  "retry": {
    "enabled": false
  }
}

适用场景：离线环境、处理敏感代码不想出网、或者想省 API 费用的日常简单任务。推理关了（本地模型大多不支持）、图片关了、压缩 token 数调低适配小型上下文窗口。

下一章进入排错模式——安装失败、认证报错、模型连不上，这些常见问题怎么快速定位和解决。

配置参考手册

模型与推理

UI 与显示

网络

警告

上下文压缩（compaction）

分支摘要（branchSummary）

重试策略

消息传递

终端与图片

Shell

会话存储

模型循环

Markdown 渲染

资源路径

三种实用配置模板

模板一：最小配置（新手起步）

模板二：全功能配置（日常主力）

模板三：本地模型配置（离线/省钱）