Pi Agent 环境变量完全指南：进程标记、会话注入与运行时配置

Pi Agent 环境变量完全指南：进程标记、会话注入与运行时配置

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

导读：环境变量是 Pi（最小化终端编码 Agent 工作台）连接外层进程、管理会话与配置自身行为的核心机制。本文以 skills/pi-agent/references/environment-variables.md 为骨架，结合本仓库 Pi Agent Skill 中其他参考文档，系统讲解 Pi 通过环境变量的三大用途：标记运行环境、向 bash 工具注入会话元数据、配置 Pi 进程自身。读完你将掌握如何检测自己是否运行在 Pi 内、如何在命令中正确读取当前模型信息、以及如何用环境变量覆盖配置目录、禁用网络操作、调整 TUI 行为等实战技巧。

Pi 是一个极简的终端编码 Agent 工作台，其核心保持小巧，绝大多数工作流行为由 TypeScript 扩展、技能、提示模板、主题与 Pi 包承载（参见 SKILL.md）。在这样的架构下，环境变量承担着进程间协作与配置分发的"轻量协议"角色。按照 environment-variables.md 的定义，Pi 通过三种方式使用环境变量：

1. 进程标记（Process Markers）——配置 Pi 进程、标记自身身份的变量；
2. bash 工具会话环境（Bash Tool Session Environment）——Pi 设置给子进程、用于识别"运行在 Pi 内部"的标记；
3. 会话元数据注入——由 LLM 可调用的 bash 工具执行命令时，注入的当前会话与模型信息。

此外，各模型提供商的 API Key 变量统一记录在 providers.md 中，本文不做重复展开。

进程标记：识别"我运行在 Pi 里"

CLI 与 RPC 入口在启动时会为进程设置两个标记变量，子进程会完整继承它们：

两个标记都不是会话特定的（不随会话切换变化），并且当 Pi 通过 SDK 被嵌入到其他程序中时，这两个标记不会被自动设置——因为 SDK 场景下启动方是宿主应用而非 Pi 本身，需要自行判断。

实战场景：如果你在编写一个会被多种 Agent 调用的工具或脚本，可以通过AI_AGENT判断调用方是否为 Pi；如果只需判断"是否运行在 Pi 内"，用PI_CODING_AGENT更精确。

bash 工具会话环境：每次命令都能看到"我是谁、我在哪个会话"

这是最常在实战中用到的一组变量。Pi 的 LLM 可调用 bash 工具在执行每一条命令时，都会注入以下会话环境变量：

值在每条命令启动时解析

这些变量的值在每条命令启动时解析，而不是在会话启动时固化。因此，即使在会话中途通过/model切换了模型，下一条 bash 命令拿到的PI_PROVIDER/PI_MODEL就是新值，无需重启 Pi。这一设计让脚本无需关心模型切换时机，始终能读到"当前真实生效"的配置。

如何确认"当前跑的是哪个模型"

文档特别强调：PI_PROVIDER/PI_MODEL标识的是Pi 当前选中的模型，而不是路由层内部选择的上游模型。当被问到"现在运行的是哪个模型"时，应当直接查看这两个变量，不要试图从 system prompt 文本中推断：

printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"

例如输出anthropic/claude-sonnet-4-5即表示提供商为anthropic、模型为claude-sonnet-4-5。结合 settings.md 可知，模型相关的默认值同样可以在settings.json中通过defaultProvider、defaultModel、defaultThinkingLevel配置。

注入范围：仅限 LLM 调用的 bash 工具

需要特别注意作用域：这些变量只会注入到 LLM 可调用的 bash 工具中，而不会注入到用户手动输入的!或!!命令。这意味着如果你在 REPL 里用!echo $PI_MODEL测试，得到的结果是空值——这是符合预期的行为。

自定义 bash 工具与 spawnHook

使用createBashTool()构建自定义 bash 工具时，默认也会暴露同样的会话变量，且注入时机在spawnHook之前——因此 hooks 可以在ctx.env中看到这些变量。若不需要暴露，可通过exposeSessionEnvironment: false关闭；关闭后 Pi 还会主动清除继承下来的旧值，防止嵌套的 Pi 进程把父会话的过期元数据泄漏给子进程。这一点在 extensions.md 的 Remote execution 一节中有对应描述：createBashTool(cwd, { spawnHook, exposeSessionEnvironment })可以重写命令、工作目录与环境，而会话变量会在spawnHook之前注入。

Pi 进程配置：用环境变量覆盖运行时行为

下表是 Pi 进程级配置环境变量的完整清单，覆盖目录定位、网络、遥测、缓存、TUI 等方方面面：

命名前缀与 fork 重命名

文档特别注明：这些变量名来源于可重命名的应用名（package.json中的piConfig.name）。也就是说，如果你 fork 了 Pi 并改了名字，环境变量前缀会随之改变——这点在 development.md 中有更详细的说明：修改piConfig的name、configDir与bin会同时影响 CLI 横幅、配置路径与环境变量名。

与 settings.json 的优先级关系

这组环境变量并非孤立存在，它们与settings.json形成互补：

• PI_CODING_AGENT_SESSION_DIR与sessionDir设置、--session-dir参数存在优先级链。根据 settings.md 的说明，优先级为：--session-dir>PI_CODING_AGENT_SESSION_DIR>settings.json中的sessionDir。
• PI_OFFLINE=1与--offline等效，会禁用所有启动网络操作；而PI_SKIP_VERSION_CHECK=1只禁用版本检查，二者颗粒度不同。遥测方面，enableInstallTelemetry设置只控制向https://pi.dev/api/report-install发送的匿名安装/更新 ping，选择退出并不会禁用更新检查——后者由PI_SKIP_VERSION_CHECK或PI_OFFLINE控制。
• PI_TELEMETRY则可从命令行层面覆盖安装/更新遥测与提供商归属请求头，取值支持布尔语义。

TUI 与调试相关变量

PI_HARDWARE_CURSOR=1与 TUI 设置中的showHardwareCursor（或扩展 APIsetShowHardwareCursor(true)）等效。根据 tui.md，默认情况下硬件光标保持隐藏，而某些终端需要显示它才能正确弹出 IME 候选窗口（中文、日文输入法场景）。若遇到 Alt 键输入被误读为 Escape 的问题，则调大PI_TUI_ESC_TIMEOUT。

分布在其他文档中的相关变量

environment-variables.md明确列出了"记录在其他文档"的变量，它们共同构成 Pi 环境变量全景，值得一并查阅：

其中几个值得展开的实战点：

• LLAMA_BASE_URL/LLAMA_API_KEY：根据 llama-cpp.md，这两个环境变量可以让你不通过/login llama.cpp就完成本地路由服务器配置：

  export LLAMA_BASE_URL=http://127.0.0.1:8080 export LLAMA_API_KEY=optional-secret pi

  如果服务器启用了 API Key，需要以匹配的--api-key启动llama-server。

• PI_TUI_WRITE_LOG：按 tui.md 所述，PI_TUI_WRITE_LOG=/tmp/tui-ansi.log可捕获写入 stdout 的原始 ANSI 流，是排查终端渲染问题的利器。

• AWS_BEDROCK_FORCE_CACHE：在 providers.md 中，Amazon Bedrock 对模型 ID 中带可识别模型名的 Claude 模型自动启用提示缓存；对应用推理配置文件（application inference profiles）则需要AWS_BEDROCK_FORCE_CACHE=1强制开启。

• 提供商 API Key 环境变量：如ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY等应在启动前设置，详见 providers.md 中的完整表格。注意auth.json（~/.pi/agent/auth.json，权限0600）的优先级高于环境变量。

关键结论速查

1. 判断运行环境：用AI_AGENT=pi（通用）与PI_CODING_AGENT=true（Pi 专属）两个标记；SDK 嵌入场景下二者都不会自动设置。
2. 读取当前模型：printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"，值在每条命令启动时解析，模型切换后即时生效；PI_PROVIDER/PI_MODEL表示 Pi 选中的模型，而非路由内部的上游模型。
3. 会话定位：PI_SESSION_ID、PI_SESSION_FILE（临时会话无文件路径）、PI_REASONING_LEVEL（七档推理级别）。
4. 注入边界：会话变量只注入 LLM 调用的 bash 工具，!/!!用户命令不注入；createBashTool()默认在spawnHook前注入，可用exposeSessionEnvironment: false关闭并清除继承值。
5. 离线与隐私：PI_OFFLINE=1全量禁用启动网络操作；PI_SKIP_VERSION_CHECK=1仅禁用版本检查；PI_TELEMETRY=0关闭遥测。
6. 目录覆盖：PI_CODING_AGENT_DIR、PI_CODING_AGENT_SESSION_DIR（优先级低于--session-dir）、PI_PACKAGE_DIR（Nix/Guix 场景）。
7. 终端调优：IME 问题用PI_HARDWARE_CURSOR=1；Alt 键误读用PI_TUI_ESC_TIMEOUT；渲染调试用PI_TUI_WRITE_LOG。

如需完整上下文，可继续阅读 pi-agent SKILL.md 及其 references 目录 下与上述主题对应的文档。

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills