콘텐츠로 이동

환경 변수 (현재 런타임 참조)

이 참조는 다음 경로의 현재 코드에서 도출되었습니다:

  • packages/coding-agent/src/**
  • packages/ai/src/** (coding-agent에서 사용하는 프로바이더/인증 해결)
  • packages/utils/src/**packages/tui/src/** (해당 변수가 coding-agent 런타임에 직접 영향을 미치는 경우)

활성 동작만 문서화합니다.

대부분의 런타임 조회는 @f5-sales-demo/pi-utils (packages/utils/src/env.ts)의 $env를 사용합니다.

$env 로딩 순서:

  1. 기존 프로세스 환경 (Bun.env)
  2. 아직 설정되지 않은 키에 대해 프로젝트 .env ($PWD/.env)
  3. 아직 설정되지 않은 키에 대해 홈 .env (~/.env)

.env 파일의 추가 규칙: 파싱 중 XCSH_* 키는 PI_* 키로 미러링됩니다.


별도로 명시되지 않는 한 getEnvApiKey() (packages/ai/src/stream.ts)를 통해 사용됩니다.

변수사용 대상필요 시점참고사항 / 우선순위
ANTHROPIC_OAUTH_TOKENAnthropic API 인증OAuth 토큰 인증으로 Anthropic 사용 시프로바이더 인증 해결 시 ANTHROPIC_API_KEY보다 우선함
ANTHROPIC_API_KEYAnthropic API 인증OAuth 토큰 없이 Anthropic 사용 시ANTHROPIC_OAUTH_TOKEN 이후 폴백
ANTHROPIC_FOUNDRY_API_KEYAzure Foundry / 엔터프라이즈 게이트웨이를 통한 AnthropicCLAUDE_CODE_USE_FOUNDRY 활성화 시Foundry 모드 활성화 시 ANTHROPIC_OAUTH_TOKENANTHROPIC_API_KEY보다 우선함
OPENAI_API_KEYOpenAI 인증명시적 apiKey 인수 없이 OpenAI 계열 프로바이더 사용 시OpenAI Completions/Responses 프로바이더에서 사용됨
GEMINI_API_KEYGoogle Gemini 인증google 프로바이더 모델 사용 시Gemini 프로바이더 매핑을 위한 기본 키
GOOGLE_API_KEYGemini 이미지 도구 인증 폴백GEMINI_API_KEY 없이 gemini_image 도구 사용 시coding-agent 이미지 도구 폴백 경로에서 사용됨
GROQ_API_KEYGroq 인증Groq 모델 사용 시
CEREBRAS_API_KEYCerebras 인증Cerebras 모델 사용 시
TOGETHER_API_KEYTogether 인증together 프로바이더 사용 시
HUGGINGFACE_HUB_TOKENHugging Face 인증huggingface 프로바이더 사용 시기본 Hugging Face 토큰 환경 변수
HF_TOKENHugging Face 인증huggingface 프로바이더 사용 시HUGGINGFACE_HUB_TOKEN이 설정되지 않은 경우 폴백
SYNTHETIC_API_KEYSynthetic 인증Synthetic 모델 사용 시
NVIDIA_API_KEYNVIDIA 인증nvidia 프로바이더 사용 시
NANO_GPT_API_KEYNanoGPT 인증nanogpt 프로바이더 사용 시
VENICE_API_KEYVenice 인증venice 프로바이더 사용 시
LITELLM_API_KEYLiteLLM 인증litellm 프로바이더 사용 시OpenAI 호환 LiteLLM 프록시 키. LITELLM_BASE_URL과 함께 설정 시 models.yml 자동 구성 활성화
LM_STUDIO_API_KEYLM Studio 인증 (선택)인증된 호스트에서 lm-studio 프로바이더 사용 시로컬 LM Studio는 일반적으로 인증 없이 실행됨; 키가 필요한 경우 비어 있지 않은 토큰이면 됨
OLLAMA_API_KEYOllama 인증 (선택)인증된 호스트에서 ollama 프로바이더 사용 시로컬 Ollama는 일반적으로 인증 없이 실행됨; 키가 필요한 경우 비어 있지 않은 토큰이면 됨
LLAMA_CPP_API_KEYOllama 인증 (선택)--api-key 파라미터와 함께 llama-server 사용 시로컬 llama.cpp는 일반적으로 인증 없이 실행됨; 키가 구성된 경우 비어 있지 않은 토큰이면 됨
XIAOMI_API_KEYXiaomi MiMo 인증xiaomi 프로바이더 사용 시
MOONSHOT_API_KEYMoonshot 인증moonshot 프로바이더 사용 시
XAI_API_KEYxAI 인증xAI 모델 사용 시
OPENROUTER_API_KEYOpenRouter 인증OpenRouter 모델 사용 시선호/자동 프로바이더가 OpenRouter인 경우 이미지 도구에서도 사용됨
MISTRAL_API_KEYMistral 인증Mistral 모델 사용 시
ZAI_API_KEYz.ai 인증z.ai 모델 사용 시z.ai 웹 검색 프로바이더에서도 사용됨
MINIMAX_API_KEYMiniMax 인증minimax 프로바이더 사용 시
MINIMAX_CODE_API_KEYMiniMax Code 인증minimax-code 프로바이더 사용 시
MINIMAX_CODE_CN_API_KEYMiniMax Code CN 인증minimax-code-cn 프로바이더 사용 시
OPENCODE_API_KEYOpenCode 인증OpenCode 모델 사용 시
QIANFAN_API_KEYQianfan 인증qianfan 프로바이더 사용 시
QWEN_OAUTH_TOKENQwen 포털 인증OAuth 토큰으로 qwen-portal 사용 시QWEN_PORTAL_API_KEY보다 우선함
QWEN_PORTAL_API_KEYQwen 포털 인증API 키로 qwen-portal 사용 시QWEN_OAUTH_TOKEN 이후 폴백
ZENMUX_API_KEYZenMux 인증zenmux 프로바이더 사용 시ZenMux OpenAI 및 Anthropic 호환 라우트에서 사용됨
VLLM_API_KEYvLLM 인증/검색 옵트인vllm 프로바이더 사용 시 (로컬 OpenAI 호환 서버)인증 없는 로컬 서버의 경우 비어 있지 않은 값이면 됨
CURSOR_ACCESS_TOKENCursor 프로바이더 인증Cursor 프로바이더 사용 시
AI_GATEWAY_API_KEYVercel AI 게이트웨이 인증vercel-ai-gateway 프로바이더 사용 시
CLOUDFLARE_AI_GATEWAY_API_KEYCloudflare AI 게이트웨이 인증cloudflare-ai-gateway 프로바이더 사용 시베이스 URL은 https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/anthropic으로 구성되어야 함
변수사용 대상체인
COPILOT_GITHUB_TOKENGitHub Copilot 프로바이더 인증COPILOT_GITHUB_TOKENGH_TOKENGITHUB_TOKEN
GH_TOKENCopilot 폴백; 웹 스크레이퍼에서 GitHub API 인증웹 스크레이퍼: GITHUB_TOKENGH_TOKEN
GITHUB_TOKENCopilot 폴백; 웹 스크레이퍼에서 GitHub API 인증웹 스크레이퍼: GH_TOKEN보다 먼저 확인됨

Anthropic Foundry 게이트웨이 (Azure / 엔터프라이즈 프록시)

섹션 제목: “Anthropic Foundry 게이트웨이 (Azure / 엔터프라이즈 프록시)”

CLAUDE_CODE_USE_FOUNDRY가 활성화되면 Anthropic 요청이 Foundry 모드로 전환됩니다:

  • 베이스 URL은 FOUNDRY_BASE_URL에서 해결됩니다 (설정되지 않은 경우 모델/기본 베이스 URL이 폴백으로 유지됨).
  • anthropic 프로바이더의 API 키 해결 순서: ANTHROPIC_FOUNDRY_API_KEYANTHROPIC_OAUTH_TOKENANTHROPIC_API_KEY.
  • ANTHROPIC_CUSTOM_HEADERS는 쉼표/줄바꿈으로 구분된 key: value 쌍으로 파싱되어 요청 헤더에 병합됩니다.
  • 환경 변수 값에서 TLS 클라이언트/서버 자료를 주입할 수 있습니다: NODE_EXTRA_CA_CERTS, CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY. 각각 다음을 허용합니다:
    • PEM 콘텐츠에 대한 파일시스템 경로, 또는
    • 인라인 PEM (이스케이프된 \n 시퀀스 포함).
변수값 유형동작
CLAUDE_CODE_USE_FOUNDRY부울형 문자열 (1, true, yes, on)Anthropic 프로바이더에 대해 Foundry 모드 활성화
FOUNDRY_BASE_URLURL 문자열Foundry 모드에서의 Anthropic 엔드포인트 베이스 URL
ANTHROPIC_FOUNDRY_API_KEY토큰 문자열Authorization: Bearer <token>에 사용됨
ANTHROPIC_CUSTOM_HEADERS헤더 목록 문자열추가 헤더; header-a: value, header-b: value 형식 또는 줄바꿈 구분
NODE_EXTRA_CA_CERTSPEM 경로 또는 인라인 PEM서버 인증서 유효성 검사를 위한 추가 CA 체인
CLAUDE_CODE_CLIENT_CERTPEM 경로 또는 인라인 PEMmTLS 클라이언트 인증서
CLAUDE_CODE_CLIENT_KEYPEM 경로 또는 인라인 PEMmTLS 클라이언트 개인 키 (인증서와 쌍을 이루어야 함)
변수기본값 / 동작
AWS_REGION기본 리전 소스
AWS_DEFAULT_REGIONAWS_REGION이 설정되지 않은 경우 폴백
AWS_PROFILE명명된 프로필 인증 경로 활성화
AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEYIAM 키 인증 경로 활성화
AWS_BEARER_TOKEN_BEDROCK베어러 토큰 인증 경로 활성화
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI / AWS_CONTAINER_CREDENTIALS_FULL_URIECS 태스크 자격 증명 경로 활성화
AWS_WEB_IDENTITY_TOKEN_FILE + AWS_ROLE_ARN웹 ID 인증 경로 활성화
AWS_BEDROCK_SKIP_AUTH1이면 더미 자격 증명 주입 (프록시/비인증 시나리오)
AWS_BEDROCK_FORCE_HTTP11이면 Node HTTP/1 요청 핸들러 강제 사용

프로바이더 코드에서의 리전 폴백: options.regionAWS_REGIONAWS_DEFAULT_REGIONus-east-1.

변수기본값 / 동작
AZURE_OPENAI_API_KEY옵션으로 API 키가 전달되지 않는 한 필수
AZURE_OPENAI_API_VERSION기본값 v1
AZURE_OPENAI_BASE_URL직접 베이스 URL 재정의
AZURE_OPENAI_RESOURCE_NAME베이스 URL 구성에 사용됨: https://<resource>.openai.azure.com/openai/v1
AZURE_OPENAI_DEPLOYMENT_NAME_MAP선택적 매핑 문자열: modelId=deploymentName,model2=deployment2

베이스 URL 해결: 옵션 azureBaseUrl → 환경 변수 AZURE_OPENAI_BASE_URL → 옵션/환경 변수 리소스 이름 → model.baseUrl.

변수필수 여부참고사항
GOOGLE_CLOUD_PROJECT예 (옵션으로 전달되지 않는 한)폴백: GCLOUD_PROJECT
GCLOUD_PROJECT폴백대체 프로젝트 ID 소스로 사용됨
GOOGLE_CLOUD_LOCATION예 (옵션으로 전달되지 않는 한)프로바이더에 기본값 없음
GOOGLE_APPLICATION_CREDENTIALS조건부설정된 경우 파일이 존재해야 함; 그렇지 않으면 ADC 폴백 경로 확인 (~/.config/gcloud/application_default_credentials.json)
변수기본값 / 동작
KIMI_CODE_OAUTH_HOST기본 OAuth 호스트 재정의
KIMI_OAUTH_HOST폴백 OAuth 호스트 재정의
KIMI_CODE_BASE_URLKimi 사용 엔드포인트 베이스 URL 재정의 (usage/kimi.ts)

OAuth 호스트 체인: KIMI_CODE_OAUTH_HOSTKIMI_OAUTH_HOSThttps://auth.kimi.com.

변수기본값 / 동작
PI_AI_ANTIGRAVITY_VERSIONGemini CLI 프로바이더에서 Antigravity 사용자 에이전트 버전 태그 재정의

OpenAI Codex responses (기능/디버그 제어)

섹션 제목: “OpenAI Codex responses (기능/디버그 제어)”
변수동작
PI_CODEX_DEBUG1/true이면 Codex 프로바이더 디버그 로깅 활성화
PI_CODEX_WEBSOCKET1/true이면 웹소켓 전송 선호 활성화
PI_CODEX_WEBSOCKET_V21/true이면 웹소켓 v2 경로 활성화
PI_CODEX_WEBSOCKET_IDLE_TIMEOUT_MS양의 정수 재정의 (기본값 300000)
PI_CODEX_WEBSOCKET_RETRY_BUDGET음이 아닌 정수 재정의 (기본값 5)
PI_CODEX_WEBSOCKET_RETRY_DELAY_MS양의 정수 기본 백오프 재정의 (기본값 500)
변수동작
DEBUG_CURSOR프로바이더 디버그 로그 활성화; 2/verbose이면 상세 페이로드 스니펫 출력
DEBUG_CURSOR_LOGJSONL 디버그 로그 출력을 위한 선택적 파일 경로
변수동작
PI_CACHE_RETENTIONlong이면 지원되는 경우 긴 보존 활성화 (anthropic, openai-responses, Bedrock 보존 해결)

변수사용 주체
EXA_API_KEYExa 검색 프로바이더 및 Exa MCP 도구
BRAVE_API_KEYBrave 검색 프로바이더
PERPLEXITY_API_KEYPerplexity 검색 프로바이더 API 키 모드
TAVILY_API_KEYTavily 검색 프로바이더
ZAI_API_KEYz.ai 검색 프로바이더 (agent.db에 저장된 OAuth도 확인)
OPENAI_API_KEY / DB의 Codex OAuthCodex 검색 프로바이더 가용성/인증

packages/coding-agent/src/web/search/auth.ts는 다음 순서로 Anthropic 웹 검색 자격 증명을 해결합니다:

  1. ANTHROPIC_SEARCH_API_KEY (+ 선택적 ANTHROPIC_SEARCH_BASE_URL)
  2. api: "anthropic-messages"를 가진 models.json 프로바이더 항목
  3. agent.db의 Anthropic OAuth 자격 증명 (5분 버퍼 내에 만료되지 않아야 함)
  4. 일반 Anthropic 환경 변수 폴백: 프로바이더 키 (ANTHROPIC_FOUNDRY_API_KEY/ANTHROPIC_OAUTH_TOKEN/ANTHROPIC_API_KEY) + 선택적 ANTHROPIC_BASE_URL (Foundry 모드 활성화 시 FOUNDRY_BASE_URL)

관련 변수:

변수기본값 / 동작
ANTHROPIC_SEARCH_API_KEY최우선 명시적 검색 키
ANTHROPIC_SEARCH_BASE_URL생략 시 https://api.anthropic.com으로 기본 설정
ANTHROPIC_SEARCH_MODEL기본값 claude-haiku-4-5
ANTHROPIC_BASE_URL4단계 인증 경로를 위한 일반 폴백 베이스 URL
변수동작
PI_AUTH_NO_BORROW설정된 경우 Perplexity 로그인 흐름에서 macOS 네이티브 앱 토큰 차용 경로 비활성화

변수기본값 / 동작
PI_PYPython 도구 모드 재정의: 0/bash=bash-only, 1/py=ipy-only, mix/both=both; 유효하지 않은 값은 무시됨
PI_PYTHON_SKIP_CHECK1이면 Python 커널 가용성 검사/워밍 검사 건너뜀
PI_PYTHON_GATEWAY_URL설정된 경우 로컬 공유 게이트웨이 대신 외부 커널 게이트웨이 사용
PI_PYTHON_GATEWAY_TOKEN외부 게이트웨이를 위한 선택적 인증 토큰 (Authorization: token <value>)
PI_PYTHON_IPC_TRACE1이면 커널 모듈에서 저수준 IPC 추적 경로 활성화
VIRTUAL_ENVPython 런타임 해결을 위한 최우선 venv 경로

추가 조건부 동작:

  • BUN_ENV=test 또는 NODE_ENV=test이면 Python 가용성 검사가 OK로 처리되고 워밍이 건너뜀.
  • Python 환경 필터링은 일반적인 API 키 변수를 차단하고 안전한 기본 변수 및 LC_, XDG_, PI_ 접두사를 허용합니다.

변수기본값 / 동작
PI_SMOL_MODELsmol 역할에 대한 임시 모델 역할 재정의 (CLI --smol이 우선함)
PI_SLOW_MODELslow 역할에 대한 임시 모델 역할 재정의 (CLI --slow이 우선함)
PI_PLAN_MODELplan 역할에 대한 임시 모델 역할 재정의 (CLI --plan이 우선함)
PI_NO_TITLE설정된 경우 (비어 있지 않은 값), 첫 번째 사용자 메시지에서 자동 세션 제목 생성 비활성화
NULL_PROMPTtrue이면 시스템 프롬프트 빌더가 빈 문자열 반환
PI_BLOCKED_AGENT태스크 도구에서 특정 서브에이전트 유형 차단
PI_SUBPROCESS_CMD서브에이전트 스폰 명령 재정의 (xcsh / xcsh.cmd 해결 우회)
PI_TASK_MAX_OUTPUT_BYTES서브에이전트당 최대 캡처 출력 바이트 (기본값 500000)
PI_TASK_MAX_OUTPUT_LINES서브에이전트당 최대 캡처 출력 라인 (기본값 5000)
PI_TIMING1이면 시작/도구 타이밍 계측 로그 활성화
PI_DEBUG_STARTUP여러 시작 경로에서 stderr로 시작 단계 디버그 출력 활성화
PI_PACKAGE_DIR패키지 에셋 기본 디렉토리 해결 재정의 (문서/예제/변경로그 경로 조회)
PI_DISABLE_LSPMUX1이면 lspmux 감지/통합 비활성화 및 직접 LSP 서버 스폰 강제
LITELLM_BASE_URLLiteLLM 프록시 베이스 URL. LITELLM_API_KEY와 함께 설정 시 최초 실행 시 models.yml 자동 생성 및 매 시작 시 자가 복구 트리거
LM_STUDIO_BASE_URL기본 암묵적 LM Studio 검색 베이스 URL 재정의 (설정되지 않은 경우 http://127.0.0.1:1234/v1)
OLLAMA_BASE_URL기본 암묵적 Ollama 검색 베이스 URL 재정의 (설정되지 않은 경우 http://127.0.0.1:11434)
LLAMA_CPP_BASE_URL기본 암묵적 Llama.cpp 검색 베이스 URL 재정의 (설정되지 않은 경우 http://127.0.0.1:8080)
PI_EDIT_VARIANThashline이면 편집 도구 사용 가능 시 hashline 읽기/grep 표시 모드 강제
PI_NO_PTY1이면 bash 도구의 인터랙티브 PTY 경로 비활성화

PI_NO_PTY는 CLI --no-pty 사용 시 내부적으로도 설정됩니다.


이것들은 @f5-sales-demo/pi-utils/dirs를 통해 사용되며 coding-agent가 데이터를 저장하는 위치에 영향을 미칩니다.

변수기본값 / 동작
PI_CONFIG_DIR홈 디렉토리 아래 구성 루트 디렉토리명 (기본값 .xcsh)
PI_CODING_AGENT_DIR에이전트 디렉토리의 전체 재정의 (기본값 ~/<PI_CONFIG_DIR or .xcsh>/agent)
PWD경로 헬퍼에서 표준 현재 작업 디렉토리 일치 시 사용됨

(packages/utils/src/procmgr.ts 및 coding-agent bash 도구 통합에서.)

변수동작
PI_BASH_NO_CI스폰된 셸 환경에 자동 CI=true 주입 억제
CLAUDE_BASH_NO_CIPI_BASH_NO_CI의 레거시 별칭 폴백
PI_BASH_NO_LOGIN로그인 셸 모드 비활성화 의도
CLAUDE_BASH_NO_LOGINPI_BASH_NO_LOGIN의 레거시 별칭 폴백
PI_SHELL_PREFIX선택적 명령 접두사 래퍼
CLAUDE_CODE_SHELL_PREFIXPI_SHELL_PREFIX의 레거시 별칭 폴백
VISUAL선호하는 외부 편집기 명령
EDITOR폴백 외부 편집기 명령

현재 구현 참고: PI_BASH_NO_LOGIN/CLAUDE_BASH_NO_LOGIN은 읽히지만 현재 getShellArgs()는 두 분기 모두에서 ['-l','-c']를 반환합니다 (현재는 사실상 아무 동작도 하지 않음).


8) UI/테마/세션 감지 (자동 감지 환경 변수)

섹션 제목: “8) UI/테마/세션 감지 (자동 감지 환경 변수)”

이것들은 런타임 신호로 읽히며, 일반적으로 수동으로 구성하는 것이 아니라 터미널/OS에 의해 설정됩니다.

변수사용 대상
COLORTERM, TERM, WT_SESSION색상 기능 감지 (테마 색상 모드)
COLORFGBG터미널 배경 밝음/어두움 자동 감지
TERM_PROGRAM, TERM_PROGRAM_VERSION, TERMINAL_EMULATOR시스템 프롬프트/컨텍스트에서 터미널 식별
KDE_FULL_SESSION, XDG_CURRENT_DESKTOP, DESKTOP_SESSION, XDG_SESSION_DESKTOP, GDMSESSION, WINDOWMANAGER시스템 프롬프트/컨텍스트에서 데스크톱/윈도우 매니저 감지
KITTY_WINDOW_ID, TMUX_PANE, TERM_SESSION_ID, WT_SESSION안정적인 터미널별 세션 브레드크럼 ID
SHELL, ComSpec, TERM_PROGRAM, TERM시스템 정보 진단
APPDATA, XDG_CONFIG_HOMElspmux 구성 경로 해결
HOMEMCP 명령 UI에서 경로 단축

9) 네이티브 로더/디버그 플래그

섹션 제목: “9) 네이티브 로더/디버그 플래그”
변수동작
PI_DEVpackages/natives에서 자세한 네이티브 애드온 로드 진단 활성화

10) TUI 런타임 플래그 (공유 패키지, coding-agent UX에 영향)

섹션 제목: “10) TUI 런타임 플래그 (공유 패키지, coding-agent UX에 영향)”
변수동작
PI_NOTIFICATIONSoff / 0 / false이면 데스크톱 알림 억제
PI_TUI_WRITE_LOG설정된 경우 TUI 쓰기를 파일에 로깅
PI_HARDWARE_CURSOR1이면 하드웨어 커서 모드 활성화
PI_CLEAR_ON_SHRINK1이면 콘텐츠 축소 시 빈 행 지움
PI_DEBUG_REDRAW1이면 리드로우 디버그 로깅 활성화
PI_TUI_DEBUG1이면 심층 TUI 디버그 덤프 경로 활성화

변수동작
PI_COMMIT_TEST_FALLBACKtrue이면 (대소문자 구분 없음) 커밋 폴백 생성 경로 강제
PI_COMMIT_NO_FALLBACKtrue이면 에이전트가 제안을 반환하지 않을 때 폴백 비활성화
PI_COMMIT_MAP_REDUCEfalse이면 맵-리듀스 커밋 분석 경로 비활성화
DEBUG설정된 경우 커밋 에이전트 오류 스택 트레이스 출력

이것들을 시크릿으로 취급하십시오; 로깅하거나 커밋하지 마십시오:

  • 프로바이더/API 키 및 OAuth/베어러 자격 증명 (모든 *_API_KEY, *_TOKEN, OAuth 액세스/갱신 토큰)
  • 클라우드 자격 증명 (AWS_*, GOOGLE_APPLICATION_CREDENTIALS 경로는 서비스 계정 자료를 노출할 수 있음)
  • 검색/프로바이더 인증 변수 (EXA_API_KEY, BRAVE_API_KEY, PERPLEXITY_API_KEY, Anthropic 검색 키)
  • Foundry mTLS 자료 (CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY, 개인 CA 번들을 가리키는 경우 NODE_EXTRA_CA_CERTS)

Python 런타임은 커널 서브프로세스 스폰 전에 많은 일반적인 키 변수를 명시적으로 제거합니다 (packages/coding-agent/src/ipy/runtime.ts).