CometAPI와 함께 Pi 사용하기

Pi는 Pi Agent Harness 프로젝트입니다. @earendil-works/pi-coding-agent 패키지는 파일, shell, edit, write, session, print, JSON, RPC, SDK 워크플로를 지원하는 대화형 코딩 에이전트 CLI를 제공합니다. Pi는 ~/.pi/agent/models.json에서 사용자 정의 provider를 로드할 수 있으므로, Pi 소스 코드를 변경하지 않고도 CometAPI를 OpenAI 호환 provider 항목으로 추가할 수 있습니다. 공식 참고 자료:

model 사용 가능 여부는 시간이 지나면서 변경됩니다. your-model-id를 CometAPI Models page에서 사용 가능한 model ID로 바꾸세요.

사전 요구 사항

Node.js >=22.19.0
npm
dashboard에서 발급한 활성 API key가 있는 CometAPI 계정
공식 npm 패키지로 설치된 Pi

런타임 권한 이해하기

Pi는 이를 실행하는 사용자와 프로세스의 권한으로 실행됩니다. Pi가 작업할 프로젝트 디렉터리에서 시작하고, git 같은 롤백 경로를 유지하며, 더 강력한 파일 시스템, 프로세스, 네트워크 또는 자격 증명 경계가 필요하다면 컨테이너나 샌드박스를 사용하세요.

provider 구성

Pi 설치

npm으로 Pi를 전역 설치합니다:

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

CLI를 사용할 수 있는지 확인합니다:

pi --version

CometAPI API 키 설정

CometAPI API 키를 COMETAPI_KEY 환경 변수에 저장합니다:

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY

터미널 세션 간에 유지되도록 하려면 export 명령을 셸 프로필에 추가하세요. API 키를 버전 관리에 커밋하지 마세요.

models.json에 CometAPI provider 추가

~/.pi/agent/models.json이 없으면 생성하세요. 파일에 이미 provider가 들어 있다면 기존 providers 객체에 cometapi-responses와 cometapi-chat 항목을 병합하세요:

{
  "providers": {
    "cometapi-responses": {
      "name": "CometAPI Responses",
      "baseUrl": "https://api.cometapi.com/v1",
      "api": "openai-responses",
      "apiKey": "$COMETAPI_KEY",
      "models": [
        {
          "id": "your-model-id",
          "name": "CometAPI Responses model"
        }
      ]
    },
    "cometapi-chat": {
      "name": "CometAPI Chat Completions",
      "baseUrl": "https://api.cometapi.com/v1",
      "api": "openai-completions",
      "apiKey": "$COMETAPI_KEY",
      "models": [
        {
          "id": "your-model-id",
          "name": "CometAPI Chat model"
        }
      ]
    }
  }
}

OpenAI Responses API가 필요한 모델이나 워크플로에는 cometapi-responses를 사용하세요. OpenAI Chat Completions와 호환되는 모델에는 cometapi-chat을 사용하세요. Pi는 요청 시점에 $COMETAPI_KEY를 확인합니다. API 키는 환경 변수 또는 자체 secrets 워크플로에 보관하세요.

두 provider 모두 확인

Pi가 Responses provider에서 볼 수 있는 모델 목록을 확인합니다:

pi --list-models cometapi-responses

Responses provider로 짧은 단발성 프롬프트(Prompt)를 실행합니다:

pi --provider cometapi-responses --model your-model-id -p "Reply with one short sentence confirming the Responses connection."

Pi가 Chat Completions provider에서 볼 수 있는 모델 목록을 확인합니다:

pi --list-models cometapi-chat

Chat Completions provider로 짧은 단발성 프롬프트(Prompt)를 실행합니다:

pi --provider cometapi-chat --model your-model-id -p "Reply with one short sentence confirming the Chat Completions connection."

대화형으로 사용하려면 프로젝트에서 Pi를 시작한 다음 /model로 CometAPI provider와 모델을 선택하세요. 대화형 세션 중에 models.json을 수정했다면 Pi가 사용자 정의 모델 항목을 다시 로드하도록 /model을 다시 여세요.

문제 해결

Pi에 CometAPI 모델이 표시되지 않습니다

~/.pi/agent/models.json이 유효한 JSON인지, 그리고 각 provider 항목이 최상위 providers 객체 안에 있는지 확인하세요. 파일을 저장한 후 pi --list-models cometapi-responses 또는 pi --list-models cometapi-chat을 실행하세요.

Pi가 사용 가능한 API 키가 없다고 보고합니다

Pi를 실행하는 동일한 셸 세션에서 COMETAPI_KEY가 설정되어 있는지 확인하세요. 셸 프로필을 사용한다면, Pi를 실행하기 전에 새 터미널을 열거나 프로필을 source 하세요.

base URL 때문에 요청이 실패합니다

models.json에서 baseUrl로 https://api.cometapi.com/v1을 사용하세요. Pi가 대시보드 URL을 가리키도록 설정하지 말고, OpenAI 호환 라우트에 필요한 /v1 접미사를 생략하지 마세요.

Pi가 모델 요청을 보내기 전에 실패합니다

node --version으로 Node.js 버전을 확인하세요. Pi 패키지는 Node.js >=22.19.0이 필요합니다.

모델이 한 라우트에서는 작동하지만 다른 라우트에서는 작동하지 않습니다

모델이 지원하는 라우트와 api 필드가 일치하는 provider 항목을 사용하세요. openai-responses는 Responses API를 사용하고, openai-completions는 채팅 완성을 사용합니다.

Pi가 예상보다 더 많은 접근 권한을 가집니다

Pi는 이를 실행한 사용자와 프로세스의 권한으로 동작합니다. 파일, 프로세스, 네트워크 접근 또는 자격 증명에 대해 더 강한 경계가 필요하다면 컨테이너나 샌드박스 내부에서 Pi를 실행하세요.

개요

AI 코딩 에이전트

AI 에이전트

AI 채팅 클라이언트

번역 및 언어

자동화 플랫폼

관측성 및 평가

AI 프레임워크

사전 요구 사항

런타임 권한 이해하기

provider 구성

문제 해결

관련 리소스

​사전 요구 사항

​런타임 권한 이해하기

​provider 구성

​문제 해결

​관련 리소스

사전 요구 사항

런타임 권한 이해하기

provider 구성

문제 해결

관련 리소스