Tham chiếu biến môi trường

Pi dùng environment variable ở ba nơi riêng biệt: cấu hình process của chính Pi, authentication cho provider đã chọn và environment của command do các LLM-callable tool bash và powershell khởi chạy. Scope rất quan trọng: một variable được một provider nhận diện không tự động trở thành setting dùng trên toàn Pi.

Provider credential

Với built-in provider của Pi, thứ tự credential là CLI --api-key hoặc runtime override tường minh, API key hoặc OAuth credential khớp được lưu trong auth.json, apiKey đã cấu hình trong models.json (literal hoặc tham chiếu $ENV theo contract của file này), rồi ambient environment của built-in provider. Provider do extension định nghĩa có thể triển khai contract khác. Hãy dùng /login để ghi vào credential store được bảo vệ thay vì đưa secret vào file của project.

Amazon Bedrock và Google Vertex AI còn nhận ambient cloud credential được mô tả trong phần variable riêng cho provider. Custom provider trong models.json có thể tham chiếu variable bất kỳ bằng "apiKey": "$COMPANY_AI_TOKEN"; chuỗi chỉ gồm chữ hoa là literal, không phải environment lookup. Xem Thêm một nhà cung cấp mô hình để biết surface chính xác của file này.

Runtime flag

Directory và runtime asset

PI_CODING_AGENT_DIR thay thế switch home-directory rộng trước đây; nó nhắm đến agent configuration của Pi, không phải home directory của hệ điều hành. Lời gọi SDK trực tiếp dùng path được truyền vào constructor và không tự động tái hiện mọi quy tắc ưu tiên của CLI.

export PI_CODING_AGENT_DIR=/srv/pi/agent
export PI_CODING_AGENT_SESSION_DIR=/srv/pi/sessions
export PI_PACKAGE_DIR=/nix/store/example-pi
pi

Switch offline, version và telemetry

Hãy dùng --offline hoặc giá trị truthy được hỗ trợ cho PI_OFFLINE. Muốn bật lại network work, hãy unset variable: một số path phía sau trong 0.85.0 chỉ kiểm tra PI_OFFLINE có tồn tại hay không, vì vậy PI_OFFLINE=0 không an toàn và có thể vẫn hoạt động như offline. PI_SKIP_VERSION_CHECK có scope hẹp hơn offline mode. Đừng dựa vào cách viết không được tài liệu hóa cho PI_TELEMETRY.

Hành vi terminal và editor

PI_HARDWARE_CURSOR=1 làm hardware cursor của TUI hiện ra. PI_TUI_ESC_TIMEOUT nhận số mili giây hữu hạn dương để phân biệt một phím Escape đơn với Alt-key sequence bị chia nhỏ; mặc định là 100 ms khi có SSH_CONNECTION hoặc SSH_TTY, và 10 ms trong trường hợp khác.

Pi tự động phát hiện OSC 8 hyperlink, inline image protocol và truecolor. Pi 0.85.0 cung cấp chính xác các advanced override sau:

Với PI_HYPERLINKS, 1 buộc bật OSC 8 hyperlink, 0 buộc tắt chúng, còn auto chuyển sang tự động detect. terminal.hyperlinks setting tường minh được ưu tiên hơn cả PI_HYPERLINKS lẫn kết quả detect tự động; "auto" không tạo setting override.

Với PI_IMAGE_PROTOCOL, kitty chọn protocol Kitty và iterm2 chọn protocol iTerm2; none buộc tắt inline image, còn auto chuyển sang tự động detect. Một protocol tường minh hoặc false trong terminal.images setting được ưu tiên hơn cả PI_IMAGE_PROTOCOL lẫn kết quả detect tự động; "auto" không tạo setting override.

Với PI_TRUE_COLOR, 1 buộc bật truecolor, 0 buộc tắt nó, còn auto chuyển sang tự động detect. terminal.trueColor setting tường minh được ưu tiên hơn cả PI_TRUE_COLOR lẫn kết quả detect tự động; "auto" không tạo setting override.

Chỉ force capability khi toàn bộ đường đi qua terminal, proxy và multiplexer hỗ trợ nó, vì escape sequence không được hỗ trợ có thể làm hỏng rendering.

Cơ chế tự động detect nhận diện integrated terminal của Zed là có truecolor và hyperlink nhưng không chọn inline image protocol tại đó. Với auto, Zed vì vậy dùng image text fallback; đừng force sequence của Kitty hay iTerm2 nếu terminal path thực tế không hỗ trợ.

Với Ctrl+G, setting externalEditor được ưu tiên, sau đó là VISUAL, EDITOR rồi fallback theo platform. Các variable này chứa editor command, không chứa nội dung file.

Cache và chia sẻ

PI_CACHE_RETENTION=long yêu cầu provider prompt caching kéo dài nếu API được chọn hỗ trợ; giá trị khác không chọn một tier được tài liệu hóa. PI_SHARE_VIEWER_URL thay base URL dùng để tạo viewer link cho /share. Không variable nào trong hai variable này là credential.

PI_EXPERIMENTAL

PI_EXPERIMENTAL=1 bật preferred strict JSON-schema sampling của 0.85.0 cho managed tool khi model/API hỗ trợ. Phép so sánh chính xác là 1; true không được chấp nhận. Hành vi experimental có thể thay đổi giữa các release và không thay đổi project trust hay tool set đã chọn.

Quy tắc về giá trị

Environment variable là chuỗi, nhưng Pi không coi mọi chuỗi khác rỗng là true. Chỉ dùng các giá trị nêu trên. Path có thể là absolute path hoặc được helper path của CLI expand theo tài liệu; giá trị riêng cho provider cũng có thể đến từ object env theo scope của stored credential, và được ưu tiên hơn ambient process đối với các field được hỗ trợ.

Proxy và TLS

Pi 0.85.0 cấu hình Undici EnvHttpProxyAgent cho traffic dùng fetch do Pi quản lý.

Undici cũng nhận dạng dạng chữ thường và ưu tiên dạng đó hơn dạng chữ hoa. Setting global httpProxy chỉ điền HTTP_PROXY và HTTPS_PROXY khi chúng chưa được đặt. Provider SDK như AWS hoặc Google có thể sở hữu transport riêng, vì vậy các variable này không bảo đảm cho mọi extension hoặc cloud client.

SSL_CERT_FILE không được transport trong bản Pi 0.85.0 đã publish đọc hoặc cài đặt. Hãy cấu hình custom certificate trust qua Node runtime hoặc provider SDK đã chọn rồi kiểm tra riêng route đó; đừng giả định variable từ baseline này thay đổi TLS do Pi quản lý.

Variable riêng cho provider

Azure OpenAI

Azure OpenAI Responses yêu cầu AZURE_OPENAI_API_KEY cùng AZURE_OPENAI_BASE_URL hoặc AZURE_OPENAI_RESOURCE_NAME. Control tùy chọn gồm AZURE_OPENAI_API_VERSION và AZURE_OPENAI_DEPLOYMENT_NAME_MAP phân tách bằng dấu phẩy. Variable OPENAI_ORG_ID chung trong baseline không được OpenAI provider của 0.85.0 sử dụng.

Amazon Bedrock

Bedrock nhận AWS_BEARER_TOKEN_BEDROCK, AWS_PROFILE hoặc standard AWS access-key/role chain, gồm AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN tùy chọn, ECS credential và web identity. Region selection đọc AWS_REGION hoặc AWS_DEFAULT_REGION. Proxy deployment có thể dùng AWS_ENDPOINT_URL_BEDROCK_RUNTIME; AWS_BEDROCK_SKIP_AUTH=1 và AWS_BEDROCK_FORCE_HTTP1=1 là compatibility switch chuyên biệt.

Google Vertex AI

Vertex nhận trực tiếp GOOGLE_CLOUD_API_KEY. Application Default Credentials cần default credential file hợp lệ hoặc GOOGLE_APPLICATION_CREDENTIALS, cộng với GOOGLE_CLOUD_PROJECT (hoặc GCLOUD_PROJECT) và GOOGLE_CLOUD_LOCATION. GOOGLE_API_KEY và GOOGLE_VERTEX_API_KEY không phải alias cho variable Gemini và Vertex hiện tại.

Cloudflare

Cloudflare Workers AI dùng CLOUDFLARE_API_KEY và CLOUDFLARE_ACCOUNT_ID; AI Gateway cần thêm CLOUDFLARE_GATEWAY_ID. Các tên viết hoa hoàn toàn và chính xác này thay dạng CLOUDflare_* bị viết sai trong baseline.

export HTTPS_PROXY=http://proxy.internal.example:8080
export NO_PROXY=localhost,127.0.0.1,.internal.example
export GOOGLE_CLOUD_PROJECT=example-project
export GOOGLE_CLOUD_LOCATION=us-central1

Variable cũ ANTHROPIC_BASE_URL cũng không phải built-in override hiện tại. Hãy cấu hình endpoint được hỗ trợ trong models.json hoặc provider implementation thay vì dựa vào ambient alias.

Process marker và shell-tool metadata

CLI và RPC entry point đặt AI_AGENT=pi cùng PI_CODING_AGENT=true. Child process kế thừa chúng, nhưng đây không phải session identifier và bản nhúng SDK không tự động đặt chúng. Bản publish 0.85.0 không phát marker cũ PI_PARENT_SESSION.

Pi có thể expose session context hiện tại sau cho command do các LLM-callable tool bash và powershell chạy:

Operations Bash và PowerShell cục bộ mặc định khởi chạy một child process riêng cho mỗi Tool call và dùng command syntax tương ứng. Custom operations thay vào đó ủy quyền cho backend đã cấu hình; backend đó sở hữu cancellation, cleanup và quyết định execution state có persist hay không. Wrapper trước hết xóa giá trị kế thừa của cả năm session variable. exposeSessionEnvironment mặc định là true, nhưng việc inject cần Agent/Extension execution context. exposeSessionEnvironment: false chặn cả năm session field ngay cả khi context đó tồn tại. Standalone hoặc custom invocation không có context đó sẽ không tự động nhận chúng. Khi việc inject diễn ra, giá trị được resolve trước shell-tool command đó, nên thay đổi model hoặc reasoning tác động đến command kế tiếp. Tool powershell native chỉ có trên Windows. Các variable này không được inject vào command ! hoặc !! do người dùng nhập.

Khi các điều kiện trên được đáp ứng, custom shell tool tạo bằng createBashTool() hoặc createPowerShellTool() expose metadata trước spawnHook, vì vậy hãy giữ process environment nhận được khi thêm field. Nếu thiếu context hoặc exposure bị tắt, hook nhận environment đã xóa các session field này. Dạng Bash hiện có vẫn là:

import { createBashTool } from "@earendil-works/pi-coding-agent";

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

Customization PowerShell dùng cùng hook contract. Khi được đăng ký và execute qua Pi với Agent context cùng exposure mặc định, Tool nhận cùng session field:

import { createPowerShellTool } from "@earendil-works/pi-coding-agent";

export const powerShellTool = createPowerShellTool(process.cwd(), {
  spawnHook: (context) => ({
    ...context,
    env: { ...context.env, CI: "1" },
  }),
});

Hãy tắt exposure một cách tường minh trên một trong hai factory khi command vượt qua trust boundary. Pi xóa session field kế thừa trước, ngăn metadata cũ của parent rò vào command hoặc hook. Ví dụ Bash này vẫn hợp lệ; thay factory bằng createPowerShellTool() để có policy PowerShell tương đương:

import { createBashTool } from "@earendil-works/pi-coding-agent";

export const isolatedBashTool = createBashTool(process.cwd(), {
  exposeSessionEnvironment: false,
  spawnHook: (context) => context,
});

Lỗi thường gặp và bảo mật

• Không đưa API key vào shell file được commit, settings.json, mã nguồn extension, log, prompt hoặc transcript. Ưu tiên /login, secret manager hoặc process injection có scope hẹp; hãy nhớ child process kế thừa giá trị được export.
• Tên hiện tại phải chính xác. PI_HOME, PI_LOG_LEVEL, PI_PARENT_SESSION, GOOGLE_API_KEY, GOOGLE_VERTEX_API_KEY, GITHUB_TOKEN, OPENAI_ORG_ID, ANTHROPIC_BASE_URL và tên CLOUDflare_* viết sai không phải compatibility alias trong bản publish 0.85.0.
• Stored provider credential và apiKey đã cấu hình trong models.json đều được ưu tiên hơn ambient variable. Hãy logout hoặc cập nhật stored entry, đồng thời xóa hoặc đổi configured key, trước khi mong shell key vừa rotate được chọn.
• PI_EXPERIMENTAL không liên quan đến provider authentication và không phải switch permission hay “yolo”.
• Không in toàn bộ environment dump khi debug. Chỉ kiểm tra non-secret marker hoặc từng metadata field, đồng thời coi PI_SESSION_FILE là local data nhạy cảm.

Tiếp theo

• Tham chiếu cấu hình trình bày settings.json, trust, resource, tool và session.
• Tham chiếu API trình bày public SDK surface.
• Thêm một nhà cung cấp mô hình trình bày models.json, authentication và custom adapter.