# 环境变量

> pi 读取的配置变量、进程标记，以及注入 shell 工具的会话环境变量。

---

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

---

Pi 通过三种方式使用环境变量：

- `PI_OFFLINE` 等变量用于配置 Pi 进程。
- Pi 会设置进程标记，让子进程能够识别出启动它们的智能体是 Pi。
- 由 LLM 可调用的 shell 工具执行的命令会收到描述当前会话的 `PI_*` 变量。

提供商 API 密钥变量在[提供商](/book/pi/providers/#environment-variables-or-auth-file)中单独说明。

## 进程标记 {#process-marker}

CLI 和 RPC 入口会设置两个进程标记：

- `AI_AGENT=pi` 是一个通用标记，让各类工具能够识别 Pi 是启动该进程的智能体。
- `PI_CODING_AGENT=true` 是 Pi 专用的标记，让子进程检测到自己运行在 Pi 内部。

子进程会继承这两个标记。它们与会话无关，并且在通过 SDK 嵌入 Pi 时不会自动设置。

## Shell 工具会话环境 {#shell-tool-session-environment}

由 `bash` 和 `powershell` 工具执行的命令会收到当前 Pi 会话的状态：

| 变量 | 说明 |
|----------|-------------|
| `PI_SESSION_ID` | 当前会话 ID |
| `PI_SESSION_FILE` | 当前会话 JSONL 文件的绝对路径；临时会话未设置 |
| `PI_PROVIDER` | 当前选定的模型提供商 |
| `PI_MODEL` | 当前选定的模型 ID |
| `PI_REASONING_LEVEL` | 当前生效的推理级别：`off`、`minimal`、`low`、`medium`、`high`、`xhigh` 或 `max` |

这些值在每条命令启动时解析。因此，切换模型或更改推理级别无需重启 Pi 即可影响下一条 shell 命令。`PI_PROVIDER` 和 `PI_MODEL` 标识的是所选的 Pi 模型，而不是路由器内部可能选择的其他上游模型。

当被问到当前运行的是哪个模型或提供商时，应检查这些变量，而不是从系统提示词中推断答案：

```bash
printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"
printf 'reasoning=%s session=%s\n' "$PI_REASONING_LEVEL" "$PI_SESSION_ID"
```

当会话是持久化会话时，可以直接查看会话文件：

```bash
if [ -n "$PI_SESSION_FILE" ]; then
  tail -n 1 "$PI_SESSION_FILE"
fi
```

这些变量会注入到 LLM 可调用的 `bash` 和 `powershell` 工具中，但不会注入到用户手动输入的 `!` 或 `!!` 命令中。

### 自定义 Shell 工具 {#custom-shell-tools}

使用 `createBashTool()` 或 `createPowerShellTool()` 创建的工具在注册到 Pi 后，默认会暴露会话环境。注入发生在 `spawnHook` 之前，因此钩子会在 `ctx.env` 中收到这些变量：

```typescript
const bashTool = createBashTool(cwd, {
  spawnHook: (ctx) => ({
    ...ctx,
    env: { ...ctx.env, CI: "1" },
  }),
});
```

可以独立于 spawn 钩子禁用会话元数据：

```typescript
const powershellTool = createPowerShellTool(cwd, {
  exposeSessionEnvironment: false,
  spawnHook: (ctx) => ctx,
});
```

禁用后，Pi 会移除这些变量的继承值，避免嵌套的 Pi 进程暴露过时的父会话元数据。

## Pi 进程配置 {#pi-process-configuration}

以下变量由 Pi 自身读取：

| 变量 | 说明 |
|----------|-------------|
| `PI_CODING_AGENT_DIR` | 覆盖配置目录；默认为 `~/.pi/agent` |
| `PI_CODING_AGENT_SESSION_DIR` | 覆盖会话存储；会被 `--session-dir` 覆盖 |
| `PI_PACKAGE_DIR` | 覆盖包目录，适用于 Nix/Guix store 路径 |
| `PI_OFFLINE` | 禁用启动时的网络操作，包括更新检查、包更新和安装/更新遥测 |
| `PI_SKIP_VERSION_CHECK` | 禁用 `pi.dev` 的最新版本请求 |
| `PI_TELEMETRY` | 覆盖安装/更新遥测和提供商归因标头：`1`/`true`/`yes` 或 `0`/`false`/`no` |
| `PI_CACHE_RETENTION` | 在支持的提供商上设为 `long` 可启用扩展提示词缓存 |
| `PI_SHARE_VIEWER_URL` | 覆盖 `/share` 使用的基础 URL |
| `PI_HARDWARE_CURSOR` | 设为 `1` 显示硬件光标；参见[终端设置](/book/pi/terminal-setup/) |
| `PI_HYPERLINKS` | 以 `1`、`0` 或 `auto` 覆盖 OSC 8 超链接检测 |
| `PI_IMAGE_PROTOCOL` | 以 `kitty`、`iterm2`、`none` 或 `auto` 覆盖内联图片检测 |
| `PI_TRUE_COLOR` | 以 `1`、`0` 或 `auto` 覆盖真彩色检测 |
| `PI_TUI_ESC_TIMEOUT` | 在单独按下 ESC 后等待多久才将其视为 Escape 键，单位为毫秒；SSH 下默认为 `100`，其他情况为 `10`。如果 Alt 键输入被误判为 Escape，请增大该值 |
| `VISUAL`、`EDITOR` | 未设置 `externalEditor` 时使用的外部编辑器回退 |
| `HTTP_PROXY`、`HTTPS_PROXY` | 为出站 HTTP 请求设置代理 |

`ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 等提供商凭据以及云提供商配置详见[提供商](/book/pi/providers/#environment-variables-or-auth-file)。

`PI_SERVER_DIR` 和 `PI_SERVER_ID` 仅适用于只随源码提供的[实验性远程测试框架](/book/pi/development/#experimental-remote-harness)，不适用于分发的构建。

---

反链：

- [扩展](/book/pi/extensions/)