尧图网页设计 
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 通过三种方式使用环境变量进程标记Process Markers——配置 Pi 进程、标记自身身份的变量bash 工具会话环境Bash Tool Session Environment——Pi 设置给子进程、用于识别运行在 Pi 内部的标记会话元数据注入——由 LLM 可调用的 bash 工具执行命令时注入的当前会话与模型信息。此外各模型提供商的 API Key 变量统一记录在 providers.md 中本文不做重复展开。进程标记识别我运行在 Pi 里CLI 与 RPC 入口在启动时会为进程设置两个标记变量子进程会完整继承它们变量值用途AI_AGENTpi通用标记帮助外部工具识别当前启动方 Agent 是 PiPI_CODING_AGENTtruePi 专属标记用于检测某进程是否运行在 Pi 内部两个标记都不是会话特定的不随会话切换变化并且当 Pi 通过 SDK 被嵌入到其他程序中时这两个标记不会被自动设置——因为 SDK 场景下启动方是宿主应用而非 Pi 本身需要自行判断。实战场景如果你在编写一个会被多种 Agent 调用的工具或脚本可以通过AI_AGENT判断调用方是否为 Pi如果只需判断是否运行在 Pi 内用PI_CODING_AGENT更精确。bash 工具会话环境每次命令都能看到我是谁、我在哪个会话这是最常在实战中用到的一组变量。Pi 的 LLM 可调用 bash 工具在执行每一条命令时都会注入以下会话环境变量变量说明PI_SESSION_ID当前会话 IDPI_SESSION_FILE会话 JSONL 文件的绝对路径临时会话ephemeral session下不设置PI_PROVIDER当前选中的模型提供商PI_MODEL当前选中的模型 IDPI_REASONING_LEVEL生效的推理级别off、minimal、low、medium、high、xhigh、max值在每条命令启动时解析这些变量的值在每条命令启动时解析而不是在会话启动时固化。因此即使在会话中途通过/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 等方方面面变量说明PI_CODING_AGENT_DIR覆盖配置目录默认~/.pi/agentPI_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/noPI_CACHE_RETENTION设为long可对支持的提供商启用扩展提示缓存prompt cachingPI_SHARE_VIEWER_URL覆盖/share使用的查看器基础 URLPI_HARDWARE_CURSOR设为1显示硬件光标用于 IME 输入法定位PI_TUI_ESC_TIMEOUT单独 ESC 后等待多久才判定为 Escape 键毫秒SSH 下默认100其他场景默认10。当 Alt 组合键被误判为 Escape 时调大此值VISUAL、EDITOR在externalEditor设置未配置时的外部编辑器回退HTTP_PROXY、HTTPS_PROXY为出站 HTTP 请求配置代理命名前缀与 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-dirPI_CODING_AGENT_SESSION_DIRsettings.json中的sessionDir。PI_OFFLINE1与--offline等效会禁用所有启动网络操作而PI_SKIP_VERSION_CHECK1只禁用版本检查二者颗粒度不同。遥测方面enableInstallTelemetry设置只控制向https://pi.dev/api/report-install发送的匿名安装/更新 ping选择退出并不会禁用更新检查——后者由PI_SKIP_VERSION_CHECK或PI_OFFLINE控制。PI_TELEMETRY则可从命令行层面覆盖安装/更新遥测与提供商归属请求头取值支持布尔语义。TUI 与调试相关变量PI_HARDWARE_CURSOR1与 TUI 设置中的showHardwareCursor或扩展 APIsetShowHardwareCursor(true)等效。根据 tui.md默认情况下硬件光标保持隐藏而某些终端需要显示它才能正确弹出 IME 候选窗口中文、日文输入法场景。若遇到 Alt 键输入被误读为 Escape 的问题则调大PI_TUI_ESC_TIMEOUT。分布在其他文档中的相关变量environment-variables.md明确列出了记录在其他文档的变量它们共同构成 Pi 环境变量全景值得一并查阅变量/主题位置PI_EXPERIMENTAL实验性首次设置流程settings.mdPI_TUI_WRITE_LOG原始 ANSI 捕获日志tui.mdAWS_BEDROCK_FORCE_CACHE及各类云提供商变量providers.mdLLAMA_BASE_URL/LLAMA_API_KEY本地 llama.cpp 路由llama-cpp.md其中几个值得展开的实战点LLAMA_BASE_URL/LLAMA_API_KEY根据 llama-cpp.md这两个环境变量可以让你不通过/login llama.cpp就完成本地路由服务器配置export LLAMA_BASE_URLhttp://127.0.0.1:8080 export LLAMA_API_KEYoptional-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_CACHE1强制开启。提供商 API Key 环境变量如ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY等应在启动前设置详见 providers.md 中的完整表格。注意auth.json~/.pi/agent/auth.json权限0600的优先级高于环境变量。关键结论速查判断运行环境用AI_AGENTpi通用与PI_CODING_AGENTtruePi 专属两个标记SDK 嵌入场景下二者都不会自动设置。读取当前模型printf %s/%s\n $PI_PROVIDER $PI_MODEL值在每条命令启动时解析模型切换后即时生效PI_PROVIDER/PI_MODEL表示 Pi 选中的模型而非路由内部的上游模型。会话定位PI_SESSION_ID、PI_SESSION_FILE临时会话无文件路径、PI_REASONING_LEVEL七档推理级别。注入边界会话变量只注入 LLM 调用的 bash 工具!/!!用户命令不注入createBashTool()默认在spawnHook前注入可用exposeSessionEnvironment: false关闭并清除继承值。离线与隐私PI_OFFLINE1全量禁用启动网络操作PI_SKIP_VERSION_CHECK1仅禁用版本检查PI_TELEMETRY0关闭遥测。目录覆盖PI_CODING_AGENT_DIR、PI_CODING_AGENT_SESSION_DIR优先级低于--session-dir、PI_PACKAGE_DIRNix/Guix 场景。终端调优IME 问题用PI_HARDWARE_CURSOR1Alt 键误读用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 通过三种方式使用环境变量进程标记Process Markers——配置 Pi 进程、标记自身身份的变量bash 工具会话环境Bash Tool Session Environment——Pi 设置给子进程、用于识别运行在 Pi 内部的标记会话元数据注入——由 LLM 可调用的 bash 工具执行命令时注入的当前会话与模型信息。此外各模型提供商的 API Key 变量统一记录在 providers.md 中本文不做重复展开。进程标记识别我运行在 Pi 里CLI 与 RPC 入口在启动时会为进程设置两个标记变量子进程会完整继承它们变量值用途AI_AGENTpi通用标记帮助外部工具识别当前启动方 Agent 是 PiPI_CODING_AGENTtruePi 专属标记用于检测某进程是否运行在 Pi 内部两个标记都不是会话特定的不随会话切换变化并且当 Pi 通过 SDK 被嵌入到其他程序中时这两个标记不会被自动设置——因为 SDK 场景下启动方是宿主应用而非 Pi 本身需要自行判断。实战场景如果你在编写一个会被多种 Agent 调用的工具或脚本可以通过AI_AGENT判断调用方是否为 Pi如果只需判断是否运行在 Pi 内用PI_CODING_AGENT更精确。bash 工具会话环境每次命令都能看到我是谁、我在哪个会话这是最常在实战中用到的一组变量。Pi 的 LLM 可调用 bash 工具在执行每一条命令时都会注入以下会话环境变量变量说明PI_SESSION_ID当前会话 IDPI_SESSION_FILE会话 JSONL 文件的绝对路径临时会话ephemeral session下不设置PI_PROVIDER当前选中的模型提供商PI_MODEL当前选中的模型 IDPI_REASONING_LEVEL生效的推理级别off、minimal、low、medium、high、xhigh、max值在每条命令启动时解析这些变量的值在每条命令启动时解析而不是在会话启动时固化。因此即使在会话中途通过/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 等方方面面变量说明PI_CODING_AGENT_DIR覆盖配置目录默认~/.pi/agentPI_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/noPI_CACHE_RETENTION设为long可对支持的提供商启用扩展提示缓存prompt cachingPI_SHARE_VIEWER_URL覆盖/share使用的查看器基础 URLPI_HARDWARE_CURSOR设为1显示硬件光标用于 IME 输入法定位PI_TUI_ESC_TIMEOUT单独 ESC 后等待多久才判定为 Escape 键毫秒SSH 下默认100其他场景默认10。当 Alt 组合键被误判为 Escape 时调大此值VISUAL、EDITOR在externalEditor设置未配置时的外部编辑器回退HTTP_PROXY、HTTPS_PROXY为出站 HTTP 请求配置代理命名前缀与 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-dirPI_CODING_AGENT_SESSION_DIRsettings.json中的sessionDir。PI_OFFLINE1与--offline等效会禁用所有启动网络操作而PI_SKIP_VERSION_CHECK1只禁用版本检查二者颗粒度不同。遥测方面enableInstallTelemetry设置只控制向https://pi.dev/api/report-install发送的匿名安装/更新 ping选择退出并不会禁用更新检查——后者由PI_SKIP_VERSION_CHECK或PI_OFFLINE控制。PI_TELEMETRY则可从命令行层面覆盖安装/更新遥测与提供商归属请求头取值支持布尔语义。TUI 与调试相关变量PI_HARDWARE_CURSOR1与 TUI 设置中的showHardwareCursor或扩展 APIsetShowHardwareCursor(true)等效。根据 tui.md默认情况下硬件光标保持隐藏而某些终端需要显示它才能正确弹出 IME 候选窗口中文、日文输入法场景。若遇到 Alt 键输入被误读为 Escape 的问题则调大PI_TUI_ESC_TIMEOUT。分布在其他文档中的相关变量environment-variables.md明确列出了记录在其他文档的变量它们共同构成 Pi 环境变量全景值得一并查阅变量/主题位置PI_EXPERIMENTAL实验性首次设置流程settings.mdPI_TUI_WRITE_LOG原始 ANSI 捕获日志tui.mdAWS_BEDROCK_FORCE_CACHE及各类云提供商变量providers.mdLLAMA_BASE_URL/LLAMA_API_KEY本地 llama.cpp 路由llama-cpp.md其中几个值得展开的实战点LLAMA_BASE_URL/LLAMA_API_KEY根据 llama-cpp.md这两个环境变量可以让你不通过/login llama.cpp就完成本地路由服务器配置export LLAMA_BASE_URLhttp://127.0.0.1:8080 export LLAMA_API_KEYoptional-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_CACHE1强制开启。提供商 API Key 环境变量如ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY等应在启动前设置详见 providers.md 中的完整表格。注意auth.json~/.pi/agent/auth.json权限0600的优先级高于环境变量。关键结论速查判断运行环境用AI_AGENTpi通用与PI_CODING_AGENTtruePi 专属两个标记SDK 嵌入场景下二者都不会自动设置。读取当前模型printf %s/%s\n $PI_PROVIDER $PI_MODEL值在每条命令启动时解析模型切换后即时生效PI_PROVIDER/PI_MODEL表示 Pi 选中的模型而非路由内部的上游模型。会话定位PI_SESSION_ID、PI_SESSION_FILE临时会话无文件路径、PI_REASONING_LEVEL七档推理级别。注入边界会话变量只注入 LLM 调用的 bash 工具!/!!用户命令不注入createBashTool()默认在spawnHook前注入可用exposeSessionEnvironment: false关闭并清除继承值。离线与隐私PI_OFFLINE1全量禁用启动网络操作PI_SKIP_VERSION_CHECK1仅禁用版本检查PI_TELEMETRY0关闭遥测。目录覆盖PI_CODING_AGENT_DIR、PI_CODING_AGENT_SESSION_DIR优先级低于--session-dir、PI_PACKAGE_DIRNix/Guix 场景。终端调优IME 问题用PI_HARDWARE_CURSOR1Alt 键误读用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考