# 设置

> pi 的 JSON 设置文件：全局与项目设置、模型、界面、压缩、重试等全部选项说明。

---

LLMS 索引： [llms.txt](/llms.txt)

---

Pi 使用 JSON 设置文件，项目设置会覆盖全局设置。

| 位置 | 作用域 |
|----------|-------|
| `~/.pi/agent/settings.json` | 全局（所有项目） |
| `.pi/settings.json` | 项目（当前目录） |

可以直接编辑，也可以使用 `/settings` 调整常用选项。要以交互方式保存启动时的默认模型，请使用 `/model` 并在所需模型上按 Ctrl+S。要保存启动时的思考级别，请使用 `/thinking` 并按 Ctrl+S。

## 项目信任 {#project-trust}

在交互式启动时，如果项目文件夹包含项目本地设置、资源或项目级 `.agents/skills`，且在 `~/.pi/agent/trust.json` 中没有针对该文件夹或其父文件夹的已保存决定，pi 会先询问是否信任该项目。信任项目后，pi 才能加载 `.pi/settings.json` 和 `.pi` 资源、安装缺失的项目包，并执行项目扩展。

非交互模式（`-p`、`--mode json` 和 `--mode rpc`）不显示信任提示。在没有适用的已保存信任决定时，它们使用全局设置中的 `defaultProjectTrust`：`ask`（默认）和 `never` 会忽略这些项目资源，而 `always` 则信任它们。传入 `--approve`/`-a` 或 `--no-approve`/`-na` 可为单次运行覆盖项目信任。

如果没有扩展或已保存决定适用，则由 `defaultProjectTrust` 控制回退行为。在 `~/.pi/agent/settings.json` 中将其设为 `"ask"`、`"always"` 或 `"never"`，或通过 `/settings` 修改。

`pi config` 和包管理命令使用相同的项目信任流程，但 `pi update` 从不弹出提示。传入 `--approve` 可为单条命令信任项目本地设置，传入 `--no-approve` 则忽略它们。

在交互模式下使用 `/trust` 可以为未来会话保存项目信任决定，包括对直接父文件夹的信任。它只写入 `~/.pi/agent/trust.json`；当前会话不会重新加载，因此需重启 pi 才能生效。

## 全部设置 {#all-settings}

### 模型与思考 {#model--thinking}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `defaultProvider` | 字符串 | - | 启动提供商（如 `"anthropic"`、`"openai"`；通过 `/model` 中按 Ctrl+S 保存，或手动编辑） |
| `defaultModel` | 字符串 | - | 启动模型 ID（通过 `/model` 中按 Ctrl+S 保存，或手动编辑） |
| `defaultThinkingLevel` | 字符串 | - | 启动思考级别（通过 `/thinking` 中按 Ctrl+S 保存，或手动编辑）：`"off"`、`"minimal"`、`"low"`、`"medium"`、`"high"`、`"xhigh"`、`"max"` |
| `modelThinkingLevels` | 对象 | - | 以 `"provider/modelId"` 为键的每模型启动思考级别；可在 `/settings` → Default thinking level per model 中配置，或手动编辑 |
| `hideThinkingBlock` | 布尔值 | `false` | 在输出中隐藏思考块 |
| `showCacheMissNotices` | 布尔值 | `false` | 为显著的提示词缓存未命中、上下文压缩或分支摘要用量，以及提供商恢复诊断（如被丢弃的 Anthropic 思考块）显示对话记录通知 |
| `thinkingBudgets` | 对象 | - | 每个思考级别的自定义 token 预算。Anthropic、Google 和 Bedrock 原生使用这些预算。兼容 OpenAI 的模型在设置了 `compat.thinkingTokenBudget`（或 `supportsThinkingTokenBudget`）时使用它们。 |

#### thinkingBudgets {#thinkingbudgets}

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

### UI 与显示 {#ui--display}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `theme` | 字符串 | `"dark"` | 主题名称（`"dark"`、`"light"` 或自定义） |
| `externalEditor` | 字符串 | `$VISUAL`，然后 `$EDITOR`，再然后 Windows 上的记事本或其他平台上的 `nano` | Ctrl+G 外部编辑器命令；优先于环境变量 |
| `quietStartup` | 布尔值 | `false` | 隐藏启动头部 |
| `defaultProjectTrust` | 字符串 | `"ask"` | 回退的项目信任行为：`"ask"`、`"always"` 或 `"never"`。仅限全局设置 |
| `collapseChangelog` | 布尔值 | `false` | 更新后显示精简版更新日志 |
| `enableInstallTelemetry` | 布尔值 | `true` | 发送匿名安装/更新 ping 以及所选提供商的归因请求头。它不控制更新检查 |
| `enableAnalytics` | 布尔值 | `false` | 选择加入的分析数据共享。目前仅在实验性首次设置（`PI_EXPERIMENTAL=1`）期间询问 |
| `trackingId` | 字符串 | - | 分析跟踪标识符，在开启 `enableAnalytics` 时生成 |
| `doubleEscapeAction` | 字符串 | `"tree"` | 连按两次 Escape 的动作：`"tree"`、`"fork"` 或 `"none"` |
| `treeFilterMode` | 字符串 | `"default"` | `/tree` 的默认过滤器：`"default"`、`"no-tools"`、`"user-only"`、`"labeled-only"`、`"all"` |
| `editorPaddingX` | 数字 | `0` | 输入编辑器的水平内边距（0-3） |
| `outputPad` | 数字 | `1` | 用户消息、助手消息和思考内容的水平内边距（0 或 1） |
| `autocompleteMaxVisible` | 数字 | `5` | 自动补全下拉菜单的最大可见项数（3-20） |
| `showHardwareCursor` | 布尔值 | `false` | 在 TUI 为输入法支持定位光标时显示终端光标 |
| `tuiMode` | 字符串 | `"regular"` | 交互式 TUI 模式：`"regular"` 或实验性 `"fullscreen"`。在 `/settings` 中更改后立即生效；`--tui-mode` 会在启动时覆盖该设置 |
| `fullscreenExitOutput` | 字符串 | `"transcript"` | 全屏退出输出：`"transcript"` 打印最终对话记录和恢复提示，`"resume-hint"` 则恢复之前的屏幕并只打印恢复提示。在常规 TUI 模式下无效 |
| `fullscreenScrollbar` | 字符串 | `"auto"` | 全屏对话记录滚动条：`"auto"` 在滚动期间或指针悬停在最右侧轨道列时临时显示，`"always"` 保留该列并始终显示，`"hidden"` 将其隐藏。在常规 TUI 模式下无效 |
| `fullscreenCopyOnSelect` | 布尔值 | `true` | 在全屏模式下自动复制选中的文本。禁用时，选区保持高亮，由 `Ctrl+X` 复制活动选区 |

对于 VS Code，请加上 `--wait`，这样编辑器退出后 pi 会继续运行：

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

### 遥测与更新检查 {#telemetry-and-update-checks}

`enableInstallTelemetry` 控制发送到 `https://pi.dev/api/report-install` 的匿名安装/更新 ping，以及 OpenRouter、NVIDIA NIM 和 Cloudflare 提供商请求中的 Pi 归因请求头。关闭后会同时禁用两者。它不会禁用更新检查；Pi 仍可能获取 `https://pi.dev/api/latest-version` 以查询最新版本。

设置 `PI_SKIP_VERSION_CHECK=1` 可禁用 Pi 版本更新检查。使用 `--offline` 或 `PI_OFFLINE=1` 可禁用本文所述的所有启动网络操作，包括更新检查、包更新检查和安装/更新遥测。

### 网络 {#network}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `httpProxy` | 字符串 | - | HTTP 代理 URL，应用为 `HTTP_PROXY` 和 `HTTPS_PROXY`。仅限全局设置。 |

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

### 警告 {#warnings}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `warnings.anthropicExtraUsage` | 布尔值 | `true` | 当 Anthropic 订阅认证可能使用付费的额外用量时显示警告 |

```json
{
  "warnings": {
    "anthropicExtraUsage": false
  }
}
```

### 上下文压缩 {#compaction}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `compaction.enabled` | 布尔值 | `true` | 启用自动压缩 |
| `compaction.reserveTokens` | 数字 | `16384` | 为 LLM 回复保留的 token |
| `compaction.keepRecentTokens` | 数字 | `20000` | 保留的近期 token（不被摘要） |
| `compaction.modelOverrides` | 对象 | - | 以精确 `"provider/modelId"` 为键的每模型 `reserveTokens` 和 `keepRecentTokens` 覆盖 |

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

#### 每模型压缩覆盖 {#per-model-compaction-overrides}

```json
{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000,
    "modelOverrides": {
      "some-provider/big-model": {
        "reserveTokens": 400000
      },
      "local/small-model": {
        "reserveTokens": 2048,
        "keepRecentTokens": 4096
      }
    }
  }
}
```

键必须精确匹配区分大小写的 `provider/modelId` 值，而不是名称或 glob 模式。模型 ID 可能包含斜杠（例如 `openrouter/anthropic/claude-sonnet-4`）。

每个 token 设置独立解析：匹配的模型覆盖 → 普通 `compaction` 设置 → 内置默认值。在上面的例子中，`some-provider/big-model` 仍保留普通的 20000 近期 token。token 值必须是非负的安全整数。匹配的模型覆盖中存在无效值时会在读取时报错；只有省略的字段才会回退到普通设置。模型覆盖条目必须是对象。普通 token 设置存在无效值时同样会在读取时报错，即使当前模型有有效的覆盖。只有省略的普通值才使用内置默认值。零是允许的，但 `reserveTokens: 0` 会失去回复余量，并将摘要输出预算也设为零。

全局和项目设置在模型查找**之前**递归合并。项目可以只覆盖某个模型的某一个字段，而不替换它的其他字段或其他模型。全局的模型专属值优先于项目范围的回退值；要更改它，需在项目中覆盖同一模型条目。

`enabled` 不区分模型。当前模型的 token 设置适用于手动压缩、自动阈值检查（包括助手回合之间）以及溢出恢复。切换模型会在下一次检查或压缩时生效。覆盖请在 JSON 中配置；`/settings` 只保留普通的自动压缩开关。

触发和摘要行为参见 [compaction.md](/book/pi/compaction/)。

### 分支摘要 {#branch-summary}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `branchSummary.reserveTokens` | 数字 | `16384` | 选择分支历史时保留的 token；输出上限为 4096 token |
| `branchSummary.skipPrompt` | 布尔值 | `false` | 在 `/tree` 导航时跳过 "Summarize branch?" 提示（默认不做摘要） |

### 重试 {#retry}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `retry.enabled` | 布尔值 | `true` | 在瞬时错误上启用自动的智能体级重试 |
| `retry.maxRetries` | 数字 | `3` | 智能体级重试的最大次数 |
| `retry.baseDelayMs` | 数字 | `2000` | 智能体级指数退避的基础延迟（2 秒、4 秒、8 秒） |
| `retry.maxAgentDelayMs` | 数字 | `60000` | 智能体级重试的最大延迟（60 秒） |
| `retry.provider.timeoutMs` | 数字 | SDK 默认值 | 提供商/SDK 请求超时（毫秒） |
| `retry.provider.maxRetries` | 数字 | `0` | 提供商/SDK 重试次数 |
| `retry.provider.maxRetryDelayMs` | 数字 | `60000` | 失败前允许的服务器请求延迟上限（60 秒） |

智能体级重试使用以 `retry.maxAgentDelayMs` 为上限的指数退避，因此即使长时间故障，较长的重试过程也能保持响应。

当提供商请求的重试延迟超过 `retry.provider.maxRetryDelayMs` 时，请求会立即失败并给出有说明的错误，而不是静默等待。将其设为 `0` 可禁用该限制。

除非确实需要提供商级重试，否则请将 `retry.provider.maxRetries` 保持为 `0`。将其设为大于 `0` 可能让 SDK/提供商重试在 Pi 察觉之前处理超出用量限额的错误，某些情况下这会阻塞智能体，直到提供商配额重置。

```json
{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "maxAgentDelayMs": 60000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}
```

### 消息送达 {#message-delivery}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `steeringMode` | 字符串 | `"one-at-a-time"` | 转向消息的发送方式：`"all"` 或 `"one-at-a-time"` |
| `followUpMode` | 字符串 | `"one-at-a-time"` | 后续消息的发送方式：`"all"` 或 `"one-at-a-time"` |
| `transport` | 字符串 | `"auto"` | 支持多种传输方式的提供商的首选传输：`"sse"`、`"websocket"`、`"websocket-cached"` 或 `"auto"` |
| `httpIdleTimeoutMs` | 数字 | `300000` | HTTP 头部/正文空闲超时（毫秒），同样适用于有显式流空闲超时的提供商。设为 `0` 可禁用。 |
| `websocketConnectTimeoutMs` | 数字 | `15000` | 支持 WebSocket 传输的提供商的 WebSocket 连接/打开握手超时（毫秒）。设为 `0` 可禁用。 |

### 终端与图片 {#terminal--images}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `terminal.showImages` | 布尔值 | `true` | 在终端中显示图片（如果支持） |
| `terminal.imageWidthCells` | 数字 | `60` | 终端中行内图片的首选宽度（以单元格计） |
| `terminal.clearOnShrink` | 布尔值 | `false` | 内容收缩时清除空行（可能导致闪烁） |
| `terminal.hyperlinks` | 布尔值或 `"auto"` | `"auto"` | 覆盖 OSC 8 超链接支持（高级，仅 JSON） |
| `terminal.images` | 字符串或布尔值 | `"auto"` | 以 `"kitty"`、`"iterm2"`、`false` 或 `"auto"` 覆盖图片协议支持（高级，仅 JSON） |
| `terminal.trueColor` | 布尔值或 `"auto"` | `"auto"` | 覆盖真彩色支持（高级，仅 JSON） |
| `images.autoResize` | 布尔值 | `true` | 将图片缩放到最大 2000x2000。适用于 `@file` 附件、`read` 以及工具返回的图片 |
| `images.blockImages` | 布尔值 | `false` | 阻止所有图片发送给 LLM |

### Shell {#shell}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `shellPath` | 字符串 | - | 自定义 shell 路径（例如 Windows 上的 Cygwin）；支持开头的 `~` 表示主目录 |
| `shellCommandPrefix` | 字符串 | - | 每条 bash 命令的前缀（例如 `"shopt -s expand_aliases"`） |
| `npmCommand` | 字符串数组 | - | npm 包查找/安装操作使用的命令 argv（例如 `["mise", "exec", "node@20", "--", "npm"]`） |

JSON 中的 Windows 路径必须使用正斜杠或转义的反斜杠：

```json
{
  "shellPath": "C:/Program Files/Git/bin/bash.exe"
}
```

```json
{
  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
}
```

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

`npmCommand` 用于所有 npm 包管理器操作，包括安装、卸载以及 git 包内部的依赖安装。用户范围的 npm 包安装在 `~/.pi/agent/npm/` 下；项目范围的 npm 包安装在 `.pi/npm/` 下。请按进程的实际启动方式使用 argv 形式的条目。配置了 `npmCommand` 后，git 包的依赖安装会使用纯 `install`，以避免包装器或替代包管理器中的 npm 专属标志。

### 工具 {#tools}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `defaultTools` | 字符串数组 | - | 启动时启用的内置工具。省略时，Pi 使用其标准默认值 |

`defaultTools` 选择启动时启用的内置工具。扩展和 SDK 自定义工具仍然保持启用。可用的内置工具有 `read`、`bash`、`powershell`、`edit`、`write`、`grep`、`find` 和 `ls`：

```json
{
  "defaultTools": ["bash", "edit", "write"]
}
```

在 Windows 上，请选择 `powershell` 而不是 `bash`，或者两者都包含：

```json
{
  "defaultTools": ["read", "powershell", "edit", "write"]
}
```

空数组表示启动时不启用任何内置工具，同时保留扩展和 SDK 自定义工具。`--tools` 会以针对所有工具的严格白名单取代这一行为，`--no-tools` 禁用所有工具，`--no-builtin-tools` 禁用内置默认工具。`--exclude-tools` 会在结果列表上再做过滤。项目的 `defaultTools` 数组会替换全局数组。

### 会话 {#sessions}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `sessionDir` | 字符串 | - | 会话文件的存储目录。接受绝对或相对路径，也支持 `~`。 |

```json
{ "sessionDir": ".pi/sessions" }
```

当多个来源指定会话目录时，优先级依次为 `--session-dir`、`PI_CODING_AGENT_SESSION_DIR`、settings.json 中的 `sessionDir`。

### 模型循环 {#model-cycling}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `enabledModels` | 字符串数组 | - | 用于 Ctrl+P 循环切换的模型模式（格式与 `--models` CLI 标志相同） |

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

### Markdown {#markdown}

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `markdown.codeBlockIndent` | 字符串 | `"  "` | 代码块的缩进 |
| `markdown.mermaid` | 字符串 | `"streaming"` | Mermaid 渲染模式：`"off"`、`"final"` 或 `"streaming"` |

### 资源 {#resources}

这些设置定义从哪里加载扩展、技能、提示词和主题。

`~/.pi/agent/settings.json` 中的路径相对于 `~/.pi/agent` 解析。`.pi/settings.json` 中的路径相对于 `.pi` 解析。支持绝对路径和 `~`。

| 设置 | 类型 | 默认值 | 说明 |
|---------|------|---------|-------------|
| `packages` | 数组 | `[]` | 从中加载资源的 npm/git 包 |
| `extensions` | 字符串数组 | `[]` | 本地扩展文件路径或目录 |
| `skills` | 字符串数组 | `[]` | 本地技能文件路径或目录 |
| `prompts` | 字符串数组 | `[]` | 本地提示词模板路径或目录 |
| `themes` | 字符串数组 | `[]` | 本地主题文件路径或目录 |
| `enableSkillCommands` | 布尔值 | `true` | 将技能注册为 `/skill:name` 命令 |

数组支持 glob 模式和排除项。使用 `!pattern` 排除。使用 `+path` 强制包含某个精确路径，使用 `-path` 强制排除某个精确路径。

#### packages {#packages}

字符串形式会加载包中的所有资源：

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

对象形式可以过滤要加载的资源：

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

包管理详情参见 [packages.md](/book/pi/packages/)。

## 示例 {#example}

```json
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "modelThinkingLevels": {
    "anthropic/claude-sonnet-4-20250514": "high"
  },
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}
```

## 项目覆盖 {#project-overrides}

项目设置（`.pi/settings.json`）会覆盖全局设置。嵌套对象会被合并：

```json
// ~/.pi/agent/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}
```

---

反链：

- [上下文压缩与分支摘要](/book/pi/compaction/)
- [快速开始](/book/pi/quickstart/)
- [会话](/book/pi/sessions/)
- [使用 Pi](/book/pi/usage/)