Pi Coding Agent

개요

Pi 홈페이지의 태그라인은 “There are many agent harnesses, but this one is yours”입니다. Pi는 사용자가 도구에 맞추는 것이 아니라, 사용자의 워크플로에 맞게 적응하는 의도적으로 미니멀한 에이전트 하니스를 지향합니다. Pi 코딩 에이전트(명령 및 구성 디렉터리 이름은 pi)는 Earendil Works의 오픈 소스 터미널 네이티브 코딩 에이전트(명령줄 도구)입니다. 여러 모델 공급자, 사용자 지정 공급자 및 플러그형 도구를 지원하므로 명령줄에서 코드 지원 및 작업 자동화에 적합합니다. Pi는 맞춤형 모델 제공자와 Anthropic Messages API를 지원합니다. ~/.pi/agent/models.json에서 EvoLink를 사용자 정의 공급자로 구성하면 Pi의 완전한 에이전트 도구 호출 기능을 유지하면서 Pi에서 EvoLink의 Claude 모델 제품군을 사용할 수 있습니다.

Pi의 공식 초점은 터미널 CLI(4가지 실행 모드: 대화형 / 인쇄 / JSON / RPC, 그리고 Node.js SDK를 통한 임베딩)이며, 이 가이드는 CLI를 따릅니다.

시작하기 전에

구성을 시작하기 전에 다음 준비를 완료했는지 확인하십시오.

1. Pi 코딩 에이전트 CLI 설치

Pi에는 Node.js ≥ 22.19.0이 필요합니다. 먼저 node -v로 버전을 확인하세요. 이 버전보다 낮으면 npm install -g 실행 시 EBADENGINE 경고가 출력되고 설치된 CLI가 실행되지 않을 수 있으므로, 먼저 Node를 업그레이드하세요.

컬 스크립트
npm

curl -fsSL https://pi.dev/install.sh | bash

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

설치 중에 npm warn deprecated node-domexception@1.0.0와 같은 지원 중단 경고가 표시되면 무시해도 됩니다. 이는 업스트림 종속성에서 발생하며 설치나 사용에 영향을 주지 않습니다. 끝에 added N packages가 표시되고 pi --version가 버전 번호를 인쇄하면 설치가 성공한 것입니다.공식 설치 명령에는 --ignore-scripts가 포함되어 있습니다(설치 중에 종속성의 수명 주기 스크립트를 건너뛰고 Pi의 일반 설치에는 필요하지 않음). 처음 실행할 때 Pi는 필요에 따라 ripgrep과 fd라는 두 가지 네이티브 도구를 자동으로 다운로드합니다.패키지 이름 @earendil-works/pi-coding-agent가 올바른지 확인하세요. npm에는 동일한 이름의 포크 @oh-my-pi/pi-coding-agent(다른 버전 라인)와 더 이상 사용되지 않는 @mariozechner/pi-coding-agent(관리자가 Earendil-works 버전으로 전환해야 한다고 언급한)도 있습니다. 잘못된 것을 설치하지 마십시오.

설치가 완료되면 pi 명령을 사용할 수 있는지 확인합니다.

pi --version

더 많은 설치 방법(PowerShell, pnpm, bun 등)은 Pi 홈페이지와 공식 저장소를 참고하세요.

2. EvoLink API 키 받기

EvoLink 콘솔에 로그인하세요.
콘솔에서 API 키를 찾아 “새 키 생성” 버튼을 클릭한 후 생성된 키를 복사하세요.
API 키는 일반적으로 sk-로 시작합니다. 안전하게 보관해주세요.

1단계: EvoLink 공급자 구성

Pi는 홈 디렉터리(전체 경로 ~/.pi/agent/models.json) 내의 .pi/agent/ 폴더에 있는 models.json라는 구성 파일을 통해 공급자와 모델을 정의합니다. Claude 모델은 Pi에서 tool_use / tool_result를 자주 사용하므로 이 가이드에서는 EvoLink의 Anthropic Messages 호환 API를 사용하고 이를 anthropic-messages 유형의 사용자 지정 공급자로 구성합니다.

~는 홈 디렉터리(macOS에서는 /Users/your-username, Linux에서는 /home/your-username)를 나타냅니다. .pi는 점으로 시작하여 Finder/파일 탐색기에 기본적으로 표시되지 않는 숨겨진 폴더가 됩니다. 따라서 아래 파일을 생성하는 가장 쉬운 방법은 명령줄을 이용하는 것입니다. 복사해서 붙여넣으면 됩니다.

이 파일은 기본적으로 존재하지 않습니다(.pi 폴더는 일반적으로 Pi가 실행될 때까지 생성되지 않음). 따라서 수동으로 생성해야 합니다. 다음 세 단계를 따르세요.

터미널 열기

macOS: Command + Space를 눌러 Spotlight를 열고 Terminal를 입력한 후 Enter를 누릅니다.
Windows: 시작 메뉴에서 PowerShell를 검색하여 엽니다.

명령줄을 처음 사용하는 경우 먼저 FAQ - 명령줄 터미널을 어떻게 열 수 있나요?를 참조하세요.

구성 폴더와 새 파일을 만듭니다.

다음 명령을 터미널에 붙여넣고 Enter를 누르십시오. 필요한 폴더를 자동으로 생성하고 텍스트 편집기에서 빈 models.json를 엽니다.

맥OS/리눅스
윈도우(파워셸)

mkdir -p ~/.pi/agent && nano ~/.pi/agent/models.json

그러면 nano 편집기(터미널 내부의 간단한 텍스트 편집기)로 이동됩니다.

mkdir -Force "$HOME\.pi\agent"; notepad "$HOME\.pi\agent\models.json"

메모장은 “새 파일을 생성하시겠습니까?”라고 묻습니다. — 예를 클릭하세요.

구성을 붙여넣고 저장

아래 전체 구성을 복사하여 방금 연 편집기에 붙여넣습니다.

{
  "providers": {
    "evolink": {
      "name": "EvoLink Direct",
      "baseUrl": "https://direct.evolink.ai",
      "apiKey": "$EVOLINK_API_KEY",
      "authHeader": true,
      "api": "anthropic-messages",
      "models": [
        { "id": "claude-fable-5",            "reasoning": true,  "contextWindow": 1000000, "maxTokens": 128000,
          "cost": {"input": 9.0, "output": 45.0, "cacheRead": 0.9, "cacheWrite": 11.25} },
        { "id": "claude-sonnet-5",           "reasoning": true,  "contextWindow": 1000000, "maxTokens": 128000,
          "cost": {"input": 2.7, "output": 13.5, "cacheRead": 0.27, "cacheWrite": 3.375} },
        { "id": "claude-haiku-4-5-20251001", "reasoning": false, "contextWindow": 200000,  "maxTokens": 64000,
          "cost": {"input": 0.9, "output": 4.5, "cacheRead": 0.09, "cacheWrite": 1.125} }
      ]
    }
  }
}

그런 다음 저장합니다.

나노(macOS/Linux): Control + O를 누른 다음 Enter를 눌러 저장하고 Control + X를 눌러 종료합니다.
메모장(Windows): Control + S를 눌러 저장한 후 창을 닫습니다.

주요 필드 설명(아무 것도 건너뛰지 마세요):

api: "anthropic-messages" — EvoLink의 Anthropic Messages 호환 경로를 사용하므로 Pi는 Claude의 기본 tool_use / tool_result 프로토콜을 사용합니다.
baseUrl를 도메인 루트에만 설정 https://direct.evolink.ai — /v1 또는 /v1/messages를 수동으로 추가하지 마세요. Pi는 /v1/messages를 자동으로 추가합니다. 이를 수동으로 추가하면 경로가 복제되고 404 Invalid URL가 발생합니다.
authHeader: true는 필수입니다. 이 필드를 설정하면 Pi가 Authorization: Bearer <your-key> 요청 헤더를 추가로 붙입니다. EvoLink의 /v1/messages는 Bearer 인증만 허용하는 반면, Pi에 내장된 Anthropic SDK는 기본적으로 x-api-key만 보내므로 이 필드를 생략하면 401이 반환됩니다.
apiKey에는 두 가지 형식이 있습니다. 하나를 선택하세요.
- 옵션 1 · 키를 직접 붙여넣기(가장 간단하고 로컬 개인 사용에 적합): 구성에서 "$EVOLINK_API_KEY"를 실제 키로 바꿉니다. "apiKey": "sk-your-real-key". 한 단계로 완료되며 환경 변수가 필요하지 않습니다. 단점은 키가 구성 파일의 일반 텍스트에 있으므로 이 파일을 공유하거나 Git에 커밋하지 마세요.
- 옵션 2 · 환경 변수 보간(더 안전함, 권장): "$EVOLINK_API_KEY"를 그대로 유지하고 실제 키를 환경 변수에 넣습니다(아래 “API 키 환경 변수 설정” 참조). 이렇게 하면 구성 파일에서 일반 텍스트 키가 유지됩니다.
- (고급) Pi의 apiKey는 ${EVOLINK_API_KEY}(동일한 표기이며, 변수 이름 바로 뒤에 리터럴 텍스트가 이어질 때 중괄호로 구분합니다)와 !command(맨 앞의 !는 명령을 실행하고 그 출력을 키로 사용합니다. 예: 비밀번호 관리자에서 읽기 "!op read 'op://vault/item/credential'")도 지원합니다. 값에 리터럴 $ 또는 !가 필요하면 $$와 $!로 이스케이프하세요.

구성 파일의 키를 터치하고 싶지 않으신가요? 대화형 모드에서 /login를 사용하여 이 공급자를 선택하고 ~/.pi/agent/auth.json에 키를 저장할 수도 있습니다. 효과는 동일합니다.

API 키 환경 변수 설정

위에서 **옵션 2(환경 변수 보간)**을 선택한 경우에만 이 단계가 필요합니다. **옵션 1(키 직접 붙여넣기)**을 선택한 경우 키는 이미 구성 파일에 있습니다. 이 섹션을 건너뛰고 바로 2단계로 이동하세요.

위 구성에서 참조된 $EVOLINK_API_KEY를 실제 키로 지정하세요. 다음은 임시 버전(현재 터미널 창에서만 유효하며 창을 닫으면 사라집니다. 첫 번째 테스트 실행에 적합)과 영구 버전(터미널을 열 때마다 자동으로 로드됨)이 모두 있습니다.

맥OS/리눅스
윈도우(파워셸)

임시(현재 터미널 창, 닫으면 손실됨):

export EVOLINK_API_KEY=your_EvoLink_API_Key

지속적(셸 구성 파일에 기록되며 모든 새 터미널에 자동으로 적용됨):

# If you use zsh (the default on modern macOS)
echo 'export EVOLINK_API_KEY=your_EvoLink_API_Key' >> ~/.zshrc
source ~/.zshrc

# If you use bash
echo 'export EVOLINK_API_KEY=your_EvoLink_API_Key' >> ~/.bashrc
source ~/.bashrc

어떤 쉘을 사용하고 있는지 모르시나요? 터미널에서 echo $SHELL를 실행합니다. 출력에 zsh가 포함되어 있으면 ~/.zshrc를 사용합니다. bash가 포함된 경우 ~/.bashrc를 사용하세요.

임시(현재 PowerShell 창, 닫으면 손실됨):

$env:EVOLINK_API_KEY = "your_EvoLink_API_Key"

지속적(사용자 환경 변수에 기록되고 모든 새 창에 적용됨):

setx EVOLINK_API_KEY "your_EvoLink_API_Key"

setx 현재 창에는 영향을 주지 않습니다; 적용하려면 터미널을 다시 시작하세요(PowerShell을 닫았다가 다시 엽니다).

2단계: 사용 시작 및 확인

1. 모델을 선택하세요

Pi를 시작하려면 터미널에서 다음 명령을 실행하세요.

pi

Pi 세션 내에서 명령 팔레트에 /model을 입력하고 Enter를 누르면 모델 선택기가 열립니다. 선택기에는 models.json에 구성한 모든 EvoLink 모델이 [evolink] 태그와 함께 나열됩니다. 방향키로 원하는 모델(예: claude-fable-5)을 선택한 다음 Enter를 눌러 확정하세요. 모델을 선택하면 하단 상태 표시줄에 현재 모델, 사고(thinking) 수준, 컨텍스트 사용량이 표시되어(예: claude-fable-5 · medium 및 0.0%/1.0M) 모델 카탈로그가 성공적으로 로드되었음을 확인할 수 있습니다.

노란색 안내 문구 “Only showing models from configured providers. Use /login to add providers.”는 정상입니다. Pi는 구성된 공급자의 모델만 나열하기 때문입니다. EvoLink 사용자 지정 공급자를 통해 연결하는 경우 /login은 필요하지 않습니다.

2. 구성 확인

모델을 선택한 후 먼저 간단한 프롬프트를 입력하여 모델 응답을 확인하세요.

who are you

그런 다음 에이전트 기능을 확인하기 위해 도구 호출을 트리거하는 작업을 입력합니다.

List the files in the current directory and tell me which ones are Markdown files.

성공의 모습:

AI의 일반적인 응답(몇 줄의 텍스트)이 표시됩니다.
Pi는 두 번째 작업에서 ls 도구를 호출하고 계속 응답할 수 있습니다.
401, 404, model_not_found 또는 Unexpected role "tool"와 같은 오류는 없음입니다.

문제 해결

다음은 표시되는 실제 오류별로 정리되어 있습니다. 일치하는 오류를 찾으세요.

`401`(잘못된 API 키)를 반환합니다.

{"code":"unauthorized","message":"Invalid API key (request id: ...)"}

가능한 원인:

환경 변수가 적용되지 않았습니다(가장 일반적). 현재 터미널에서 test -n "$EVOLINK_API_KEY" && echo "Key loaded" || echo "Key not loaded"를 실행합니다. Windows에서는 setx를 사용한 후 터미널을 다시 시작해야 합니다.
apiKey 필드가 잘못되었습니다. 변수 이름을 리터럴 키로 처리하지 않고 models.json에 "$EVOLINK_API_KEY"(환경 변수 참조)가 포함되어 있는지 확인하세요.
"authHeader": true가 누락되었습니다. EvoLink의 /v1/messages에는 Bearer 토큰이 필요하므로 이 필드가 apiKey와 동일한 공급자 구성 내에 있는지 확인하세요.
키 자체가 유효하지 않거나 비활성화되었습니다. EvoLink 콘솔에서 확인하세요.

`404 Invalid URL`를 반환합니다.

{"message":"Invalid URL (POST /v1/v1/messages)","type":"invalid_request_error"}

원인: baseUrl에 추가 경로를 수동으로 추가했습니다. Pi는 자동으로 /v1/messages를 추가하므로 baseUrl를 도메인 루트 https://direct.evolink.ai로 다시 변경합니다.

`404 model_not_found`를 반환합니다.

{"code":"model_not_found","message":"Model '...' is not available for this API key ... Call GET /v1/models ..."}

원인: 모델 ID의 철자가 틀리거나 모델이 활성화되지 않았습니다. models.json의 id가 EvoLink 콘솔//v1/models에서 반환된 모델 이름과 정확히 일치하는지 확인하세요.

`400 Unexpected role "tool"`를 반환합니다.

400: messages: Unexpected role "tool". Allowed roles are "user" or "assistant".

원인: 구성은 여전히 /v1로 끝나는 기본 URL과 함께 api: "openai-completions"를 사용하고 있습니다. Pi는 현재 Claude 호환 경로가 허용하지 않는 OpenAI의 role: "tool"를 사용하여 에이전트 도구 결과를 보냅니다. 해결책: 다음 세 가지 제공업체 필드를 변경하세요.

{
  "baseUrl": "https://direct.evolink.ai",
  "authHeader": true,
  "api": "anthropic-messages"
}

거부된 역할은 developer 역할이나 추론 매개변수가 아니라 도구 역할이기 때문에 이 문제는 supportsDeveloperRole 또는 supportsReasoningEffort로 해결할 수 없습니다. 구성을 업데이트한 후 새 세션을 시작하십시오.

비용에 대하여

위 models.json의 cost 필드는 Pi가 사용량을 추정할 때 참조로 사용할 수 있도록 EvoLink의 실제 가격(백만 토큰당 USD로 고정 10% 할인)입니다.

모델	입력	산출	캐시 읽기	캐시 쓰기
`claude-fable-5`	$9.00	$45.00	$0.90	$11.25
`claude-sonnet-5`	$2.70	$13.50	$0.27	$3.375
`claude-haiku-4-5-20251001`	$0.90	$4.50	$0.09	$1.125

캐시 읽기는 캐시에 적중되었을 때의 가격입니다(입력의 약 0.1배). 실제 절감액은 캐시 적중률에 따라 달라집니다. 맥락이 클수록 히트의 안정성이 떨어지므로 혜택이 할인됩니다. 무조건 저렴한 가격으로 취급하지 마세요.

FAQ

명령줄 터미널을 어떻게 열 수 있나요?

macOS
윈도우
리눅스

옵션 1: Command + Space를 눌러 Spotlight를 열고 Terminal를 입력한 후 Enter를 누릅니다.
옵션 2: 응용 프로그램 → 유틸리티 → 터미널로 이동합니다.

옵션 1: Win + R를 누르고 powershell를 입력한 후 Enter를 누릅니다.
옵션 2: 시작 메뉴에서 “PowerShell”을 검색합니다.

Ctrl + Alt + T를 누르거나 애플리케이션 메뉴에서 “터미널”을 검색하세요.

1. `baseUrl`를 도메인 루트에만 설정하는 이유는 무엇입니까?

Pi의 anthropic-messages 공급자는 baseUrl 뒤에 /v1/messages를 자동으로 추가하기 때문입니다. /v1 또는 /v1/messages를 추가하면 경로가 수동으로 복제되고 404 Invalid URL가 반환됩니다. https://direct.evolink.ai만 사용하세요.

2. `authHeader: true`를 설정해야 합니까?

예. authHeader: true를 설정하면 Pi가 Authorization: Bearer <your-key> 요청 헤더를 추가로 붙입니다. EvoLink의 /v1/messages는 Bearer 인증을 사용하는 반면, Pi에 내장된 Anthropic SDK는 기본적으로 x-api-key만 보내므로 이를 생략하면 401이 발생합니다.

3. 이 가이드가 터미널 CLI를 따르는 이유는 무엇입니까?

Pi의 공식 기본 형식은 터미널 CLI(4가지 실행 모드: 대화형 / 인쇄 / JSON / RPC, 그리고 Node.js SDK를 통한 임베딩)입니다. EvoLink 연동의 구성과 확인은 모두 CLI에서 이루어지며, 이 가이드의 모든 단계도 CLI를 따릅니다.

4. 구성에서 API 키를 일반 텍스트로 작성하지 않으려면 어떻게 해야 합니까?

apiKey 필드(예: "$EVOLINK_API_KEY")에서 환경 변수 보간을 사용하여 실제 키를 환경 변수에 유지합니다.

5. EvoLink는 어떤 일반 모델을 지원합니까?

EvoLink는 전체 Claude 제품군을 지원합니다(콘솔에서 볼 수 있는 GPT, Gemini 등도 지원함). 계획/복잡한 추론을 위해서는 claude-fable-5를 권장합니다. 일상적인 실행에는 claude-sonnet-5를 사용하십시오. 가벼운 작업에는 claude-haiku-4-5-20251001를 사용하세요.

6. 사용량은 어떻게 확인하나요?

EvoLink 콘솔에 로그인하여 요청량, 사용량, 토큰 사용량을 확인하세요.

자세한 사용법 및 구성은 Pi 공식 저장소를 참고하세요.

AI 코딩 도구

AI 창작 도구

개요

시작하기 전에

1. Pi 코딩 에이전트 CLI 설치

2. EvoLink API 키 받기

1단계: EvoLink 공급자 구성

API 키 환경 변수 설정

2단계: 사용 시작 및 확인

1. 모델을 선택하세요

2. 구성 확인

문제 해결

`401`(잘못된 API 키)를 반환합니다.

`404 Invalid URL`를 반환합니다.

`404 model_not_found`를 반환합니다.

`400 Unexpected role "tool"`를 반환합니다.

비용에 대하여

FAQ

명령줄 터미널을 어떻게 열 수 있나요?

1. `baseUrl`를 도메인 루트에만 설정하는 이유는 무엇입니까?

2. `authHeader: true`를 설정해야 합니까?

3. 이 가이드가 터미널 CLI를 따르는 이유는 무엇입니까?

4. 구성에서 API 키를 일반 텍스트로 작성하지 않으려면 어떻게 해야 합니까?

5. EvoLink는 어떤 일반 모델을 지원합니까?

6. 사용량은 어떻게 확인하나요?

​개요

​시작하기 전에

​1. Pi 코딩 에이전트 CLI 설치

​2. EvoLink API 키 받기

​1단계: EvoLink 공급자 구성

​API 키 환경 변수 설정

​2단계: 사용 시작 및 확인

​1. 모델을 선택하세요

​2. 구성 확인

​문제 해결

​401(잘못된 API 키)를 반환합니다.

​404 Invalid URL를 반환합니다.

​404 model_not_found를 반환합니다.

​400 Unexpected role "tool"를 반환합니다.

​비용에 대하여

​FAQ

​명령줄 터미널을 어떻게 열 수 있나요?

​1. baseUrl를 도메인 루트에만 설정하는 이유는 무엇입니까?

​2. authHeader: true를 설정해야 합니까?

​3. 이 가이드가 터미널 CLI를 따르는 이유는 무엇입니까?

​4. 구성에서 API 키를 일반 텍스트로 작성하지 않으려면 어떻게 해야 합니까?

​5. EvoLink는 어떤 일반 모델을 지원합니까?

​6. 사용량은 어떻게 확인하나요?

개요

시작하기 전에

1. Pi 코딩 에이전트 CLI 설치

2. EvoLink API 키 받기

1단계: EvoLink 공급자 구성

API 키 환경 변수 설정

2단계: 사용 시작 및 확인

1. 모델을 선택하세요

2. 구성 확인

문제 해결

`401`(잘못된 API 키)를 반환합니다.

`404 Invalid URL`를 반환합니다.

`404 model_not_found`를 반환합니다.

`400 Unexpected role "tool"`를 반환합니다.

비용에 대하여

FAQ

명령줄 터미널을 어떻게 열 수 있나요?

1. `baseUrl`를 도메인 루트에만 설정하는 이유는 무엇입니까?

2. `authHeader: true`를 설정해야 합니까?

3. 이 가이드가 터미널 CLI를 따르는 이유는 무엇입니까?

4. 구성에서 API 키를 일반 텍스트로 작성하지 않으려면 어떻게 해야 합니까?

5. EvoLink는 어떤 일반 모델을 지원합니까?

6. 사용량은 어떻게 확인하나요?