环境变量

Pi 在三种场景下使用环境变量：

• PI_OFFLINE 等变量用于配置 Pi 进程。
• Pi 会设置 PI_CODING_AGENT，让子进程能够检测到自己运行在 Pi 内部。
• 由可调用 LLM 的 bash 工具执行的命令会收到描述当前会话的 PI_* 变量。

模型提供方的 API 密钥变量在模型提供方中单独说明。

进程标记

CLI 与 RPC 入口会设置 PI_CODING_AGENT=true。子进程继承该变量，并可用它检测自己是否运行在 Pi 内部。它与会话无关，当 Pi 通过 SDK 内嵌使用时不会自动设置。

Bash 工具会话环境

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

变量	说明
PI_SESSION_ID	当前会话 ID
PI_SESSION_FILE	当前会话 JSONL 文件的绝对路径；临时会话（ephemeral session）中不设置
PI_PROVIDER	当前选中的模型提供方
PI_MODEL	当前选中的模型 ID
PI_REASONING_LEVEL	当前生效的思考级别：off、minimal、low、medium、high、xhigh 或 max

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

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

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

当会话为持久会话时，可直接检查会话文件：

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

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

自定义 Bash 工具

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

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

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

const bashTool = createBashTool(cwd, {
  exposeSessionEnvironment: false,
  spawnHook: (ctx) => ctx,
});

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

Pi 进程配置

以下变量由 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 以显示硬件光标；参见终端设置
VISUAL、EDITOR	externalEditor 未设置时的外部编辑器回退
HTTP_PROXY、HTTPS_PROXY	代理出站 HTTP 请求

ANTHROPIC_API_KEY、OPENAI_API_KEY 等模型提供方凭据以及云服务商配置列在模型提供方中。