> ## Documentation Index > Fetch the complete documentation index at: https://evolink.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Pi Coding Agent > Pi Coding Agent를 EvoLink.AI에 연결 ## 개요 Pi 코딩 에이전트(명령 및 구성 디렉터리 이름은 `pi`)는 [Earendil Works](https://github.com/earendil-works/pi)의 오픈 소스 터미널 네이티브 코딩 에이전트(명령줄 도구)입니다. 여러 모델 공급자, 사용자 지정 공급자 및 플러그형 도구를 지원하므로 명령줄에서 코드 지원 및 작업 자동화에 적합합니다. Pi는 맞춤형 모델 제공자와 **Anthropic Messages API**를 지원합니다. `~/.pi/agent/models.json`에서 EvoLink를 사용자 정의 공급자로 구성하면 Pi의 완전한 에이전트 도구 호출 기능을 유지하면서 Pi에서 EvoLink의 Claude 모델 제품군을 사용할 수 있습니다. Pi의 공식 초점은 **터미널 CLI**(4가지 실행 모드: 대화형/인쇄/RPC/SDK)이며, 이 가이드는 CLI를 따릅니다. ## 시작하기 전에 구성을 시작하기 전에 다음 준비를 완료했는지 확인하십시오. ### 1. Pi 코딩 에이전트 CLI 설치 Pi에는 **Node.js ≥ 22.19.0**이 필요합니다. 먼저 `node -v`로 버전을 확인하세요. 이 버전 이하에서는 `npm install -g`가 `EBADENGINE`를 보고하므로 먼저 Node를 업그레이드하세요. ```bash theme={null} curl -fsSL https://pi.dev/install.sh | bash ``` curl 스크립트로 Pi 설치 ```bash theme={null} npm install -g --ignore-scripts @earendil-works/pi-coding-agent ``` npm으로 Pi 설치 설치 중에 `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` 명령을 사용할 수 있는지 확인합니다. ```bash theme={null} pi --version ``` 더 많은 설치 방법(PowerShell, pnpm, bun 등)은 [Pi 홈페이지](https://pi.dev)와 [공식 저장소](https://github.com/earendil-works/pi)를 참고하세요. ### 2. EvoLink API 키 받기 * [EvoLink 콘솔](https://evolink.ai/dashboard)에 로그인하세요. * 콘솔에서 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 - 명령줄 터미널을 어떻게 열 수 있나요?](#how-do-i-open-a-command-line-terminal)를 참조하세요. 다음 명령을 터미널에 붙여넣고 Enter를 누르십시오. 필요한 폴더를 자동으로 생성하고 텍스트 편집기에서 빈 `models.json`를 엽니다. ```bash theme={null} mkdir -p ~/.pi/agent && nano ~/.pi/agent/models.json ``` 그러면 `nano` 편집기(터미널 내부의 간단한 텍스트 편집기)로 이동됩니다. ```powershell theme={null} mkdir -Force "$HOME\.pi\agent"; notepad "$HOME\.pi\agent\models.json" ``` 메모장은 "새 파일을 생성하시겠습니까?"라고 묻습니다. — **예**를 클릭하세요. 아래 **전체 구성**을 복사하여 방금 연 편집기에 붙여넣습니다. ```json theme={null} { "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": false, "contextWindow": 1000000, "maxTokens": 64000, "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의 Anthropic SDK는 기본적으로 `x-api-key`를 사용하는 반면 EvoLink의 `/v1/messages`는 `Authorization: Bearer `를 예상합니다. 이 필드는 Pi가 올바른 Bearer 인증 헤더를 보내도록 합니다. * **`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'"`)를 지원합니다. 값에 리터럴 `**(고급)** Pi의 `apiKey`는 또한 `${EVOLINK_API_KEY}`(동등함, 변수 이름 바로 뒤에 리터럴 텍스트가 올 때 중괄호를 사용하여 구분) 및 `!command`(선행 `!`가 명령을 실행하고 해당 출력을 키로 사용합니다. 예를 들어 암호 관리자에서 읽는 경우: `"!op read 'op://vault/item/credential'"`)를 지원합니다. 값에 리터럴 또는 `!`가 필요한 경우 `$`및`\$!\`로 이스케이프 처리하세요. 구성 파일의 키를 터치하고 싶지 않으신가요? 대화형 모드에서 `/login`를 사용하여 이 공급자를 선택하고 `~/.pi/agent/auth.json`에 키를 저장할 수도 있습니다. 효과는 동일합니다. ### API 키 환경 변수 설정 위에서 \*\*옵션 2(환경 변수 보간)\*\*을 선택한 경우에만 이 단계가 필요합니다. \*\*옵션 1(키 직접 붙여넣기)\*\*을 선택한 경우 키는 이미 구성 파일에 있습니다. 이 섹션을 건너뛰고 바로 2단계로 이동하세요. 위 구성에서 참조된 `$EVOLINK_API_KEY`를 실제 키로 지정하세요. 다음은 **임시** 버전(현재 터미널 창에서만 유효하며 창을 닫으면 사라집니다. 첫 번째 테스트 실행에 적합)과 **영구** 버전(터미널을 열 때마다 자동으로 로드됨)이 모두 있습니다. **임시**(현재 터미널 창, 닫으면 손실됨): ```bash theme={null} export EVOLINK_API_KEY=your_EvoLink_API_Key ``` **지속적**(셸 구성 파일에 기록되며 모든 새 터미널에 자동으로 적용됨): ```bash theme={null} # 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 창, 닫으면 손실됨): ```powershell theme={null} $env:EVOLINK_API_KEY = "your_EvoLink_API_Key" ``` **지속적**(사용자 환경 변수에 기록되고 모든 새 창에 적용됨): ```powershell theme={null} setx EVOLINK_API_KEY "your_EvoLink_API_Key" ``` `setx` **현재 창에는 영향을 주지 않습니다**; 적용하려면 **터미널을 다시 시작**하세요(PowerShell을 닫았다가 다시 엽니다). ## 2단계: 사용 시작 및 확인 ### 1. 모델을 선택하세요 Pi를 시작하려면 터미널에서 다음 명령을 실행하세요. ```bash theme={null} pi ``` Pi 세션 내에서 `/model`를 입력하여 모델 선택기를 연 다음 위에서 구성한 EvoLink 모델(예: `claude-fable-5`)을 선택합니다. ### 2. 구성 확인 모델을 선택한 후 먼저 간단한 프롬프트를 입력하여 모델 응답을 확인하세요. ``` who are you ``` “당신은 누구입니까?”에 정상적으로 응답하는 Pi 그런 다음 에이전트 기능을 확인하기 위해 도구 호출을 트리거하는 작업을 입력합니다. ``` 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 콘솔](https://evolink.ai/dashboard)에서 확인하세요. ### `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"`를 반환합니다. ```text theme={null} 400: messages: Unexpected role "tool". Allowed roles are "user" or "assistant". ``` **원인**: 구성은 여전히 ​​`/v1`로 끝나는 기본 URL과 함께 `api: "openai-completions"`를 사용하고 있습니다. Pi는 현재 Claude 호환 경로가 허용하지 않는 OpenAI의 `role: "tool"`를 사용하여 에이전트 도구 결과를 보냅니다. **해결책**: 다음 세 가지 제공업체 필드를 변경하세요. ```json theme={null} { "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 ### 명령줄 터미널을 어떻게 열 수 있나요? * 옵션 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`를 설정해야 합니까? 예. Pi의 Anthropic SDK는 기본적으로 `x-api-key`를 사용하는 반면 EvoLink의 `/v1/messages`는 Bearer 토큰을 사용합니다. `authHeader: true`는 Pi가 `Authorization: Bearer `를 보내도록 합니다. 생략하면 `401`가 발생할 수 있습니다. ### 3. 이 가이드가 터미널 CLI를 따르는 이유는 무엇입니까? Pi의 공식 기본 형식은 **터미널 CLI**(4가지 실행 모드: 대화형/인쇄/RPC/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 콘솔](https://evolink.ai/dashboard)에 로그인하여 요청량, 사용량, 토큰 사용량을 확인하세요. 자세한 사용법 및 구성은 [Pi 공식 저장소](https://github.com/earendil-works/pi)를 참고하세요.