Pi 구성

Pi는 @earendil-works/pi-coding-agent로 배포되는 터미널 코딩 에이전트입니다. 여러 API 방식을 지원하는 전송 계층을 내장하고 있어 OpenAI 호환 엔드포인트와 Anthropic 호환 엔드포인트 어느 쪽으로도 CodeByAI를 사용할 수 있습니다. 직접 작성해야 하는 것은 JSON 파일 하나뿐입니다.

1. Pi 설치

macOS 또는 Linux:

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

npm 사용 시 (Node.js 22.19 이상):

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

Windows에서는 powershell -c "irm https://pi.dev/install.ps1 | iex"를 사용하세요.

2. 모델 구성 생성

Pi는 구성을 ~/.pi/agent/에 보관하며, 사용자 지정 엔드포인트는 models.json에서 읽습니다:

macOS / Linux: ~/.pi/agent/models.json
Windows: C:\Users\YourUserName\.pi\agent\models.json

폴더가 아직 없을 수 있습니다. 폴더를 만든 다음 models.json을 생성하세요:

1 {
2   "$schema": "https://pi.dev/schemas/models.schema.json",
3   "providers": {
4     "codebyai": {
5       "name": "CodeByAI",
6       "baseUrl": "https://www.codebyai.net/api/agent",
7       "api": "openai-completions",
8       "apiKey": "$CODEBYAI_API_KEY",
9       "models": [
10         {
11           "id": "gpt-5.6-terra",
12           "name": "GPT-5.6 Terra",
13           "contextWindow": 200000,
14           "maxTokens": 32768
15         }
16       ]
17     },
18     "codebyai-claude": {
19       "name": "CodeByAI (Claude)",
20       "baseUrl": "https://www.codebyai.net/api/agent",
21       "api": "anthropic-messages",
22       "apiKey": "$CODEBYAI_API_KEY",
23       "models": [
24         {
25           "id": "claude-sonnet-5",
26           "name": "Claude Sonnet 5",
27           "contextWindow": 200000,
28           "maxTokens": 32768
29         }
30       ]
31     }
32   }
33 }

여기서 중요한 점은 다음과 같습니다:

api는 통신 프로토콜입니다. openai-completions는 /chat/completions를 호출해 GPT 계열을 담당하고, anthropic-messages는 /v1/messages를 호출해 Claude 계열을 담당합니다. 프로토콜마다 프로바이더 항목을 하나씩 두는 것이 가장 간단한 구성입니다.
baseUrl은 /api/agent에서 끝납니다. /v1을 덧붙이지 마세요: 게이트웨이가 나머지 경로를 업스트림으로 전달하므로 /api/agent/v1/chat/completions는 404 page not found로 응답합니다.
apiKey는 $VARIABLE과 ${VARIABLE} 보간을 지원하므로 파일에 비밀 값을 저장하지 않아도 됩니다.
models의 id는 해당 프로바이더의 프로토콜에 속해야 합니다. GPT 계열(예: gpt-5.6-terra)은 openai-completions, Claude 계열은 anthropic-messages에 두며, 서비스하지 않는 모델에는 chat 엔드포인트가 400을 반환합니다. contextWindow는 Pi 자체의 컨텍스트 예산을 정하고, maxTokens는 요청의 출력 한도가 되어 OpenAI 호환 경로에서는 max_completion_tokens, Anthropic 경로에서는 max_tokens로 업스트림에 전달됩니다.

3. API Key 제공

1 export CODEBYAI_API_KEY="sk-proj-xxxx"

~/.zshrc 또는 ~/.bashrc에 추가하면 세션 간에도 유지됩니다. 키 자체는 API Keys 페이지에서 생성하세요. Pi는 한 번 실행에 한해 명령줄에서 --api-key를 받을 수도 있습니다.

4. Pi 시작

1 cd your-project
2 pi --model codebyai/gpt-5.6-terra

Anthropic 호환 경로로 Claude 모델을 사용하려면:

1 pi --model codebyai-claude/claude-sonnet-5

세션을 시작하기 전에 Pi가 인식하는 모델을 확인하려면:

1 pi --list-models codebyai

5. 문제 해결

404 page not found: baseUrl이 /v1로 끝납니다. 이것을 제거하세요.
No models available가 나오거나 pi --list-models에 해당 프로바이더가 없는 경우: Pi를 실행한 셸에서 CODEBYAI_API_KEY가 비어 있어 Pi가 항목을 건너뜁니다. 존재하지 않는 모델 id도 그대로 표시되므로, 모델이 보이지 않는 것은 거의 항상 키가 없다는 뜻입니다.
openai-completions 프로바이더에서 HTTP 403, 메시지가 Invalid key! Your api-key is invalid or expired인 경우: 키가 삭제되었거나 잘못 입력되었거나 만료되었습니다. anthropic-messages 프로바이더에서는 게이트웨이가 오류 상태 대신 200으로 같은 문장을 일반 텍스트로 돌려주므로, Pi는 Anthropic stream ended without a stop reason만 표시합니다. 이 메시지도 키 문제로 보세요.
잔액 부족: 지갑 페이지에서 충전하세요.

1	`{`
2	`"$schema": "https://pi.dev/schemas/models.schema.json",`
3	`"providers": {`
4	`"codebyai": {`
5	`"name": "CodeByAI",`
6	`"baseUrl": "https://www.codebyai.net/api/agent",`
7	`"api": "openai-completions",`
8	`"apiKey": "$CODEBYAI_API_KEY",`
9	`"models": [`
10	`{`
11	`"id": "gpt-5.6-terra",`
12	`"name": "GPT-5.6 Terra",`
13	`"contextWindow": 200000,`
14	`"maxTokens": 32768`
15	`}`
16	`]`
17	`},`
18	`"codebyai-claude": {`
19	`"name": "CodeByAI (Claude)",`
20	`"baseUrl": "https://www.codebyai.net/api/agent",`
21	`"api": "anthropic-messages",`
22	`"apiKey": "$CODEBYAI_API_KEY",`
23	`"models": [`
24	`{`
25	`"id": "claude-sonnet-5",`
26	`"name": "Claude Sonnet 5",`
27	`"contextWindow": 200000,`
28	`"maxTokens": 32768`
29	`}`
30	`]`
31	`}`
32	`}`
33	`}`

1	`cd your-project`
2	`pi --model codebyai/gpt-5.6-terra`