> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CometAPI와 함께 Pi 사용하기

> 이 가이드를 사용해 base URL, API key, model 또는 provider 옵션을 설정하여 Pi에서 CometAPI를 구성하세요.

[Pi](https://github.com/earendil-works/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 항목으로 추가할 수 있습니다.

공식 참고 자료:

* [Pi repository](https://github.com/earendil-works/pi)
* [Pi quickstart](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md)
* [Pi providers](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md)
* [Pi custom models](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [Pi CLI usage](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)

<Note>
  model 사용 가능 여부는 시간이 지나면서 변경됩니다. `your-model-id`를 [CometAPI Models page](/ko/overview/models)에서 사용 가능한 model ID로 바꾸세요.
</Note>

## 사전 요구 사항

* Node.js `>=22.19.0`
* npm
* [dashboard](https://www.cometapi.com/console/token)에서 발급한 활성 API key가 있는 CometAPI 계정
* 공식 npm 패키지로 설치된 Pi

## 런타임 권한 이해하기

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

## provider 구성

<Steps>
  <Step title="Pi 설치">
    npm으로 Pi를 전역 설치합니다:

    ```bash theme={null}
    npm install -g --ignore-scripts @earendil-works/pi-coding-agent
    ```

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

    ```bash theme={null}
    pi --version
    ```
  </Step>

  <Step title="CometAPI API 키 설정">
    CometAPI API 키를 `COMETAPI_KEY` 환경 변수에 저장합니다:

    ```bash theme={null}
    read -rsp "CometAPI API key: " COMETAPI_KEY
    printf '\n'
    export COMETAPI_KEY
    ```

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

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

    ```json theme={null}
    {
      "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 워크플로에 보관하세요.
  </Step>

  <Step title="두 provider 모두 확인">
    Pi가 Responses provider에서 볼 수 있는 모델 목록을 확인합니다:

    ```bash theme={null}
    pi --list-models cometapi-responses
    ```

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

    ```bash theme={null}
    pi --provider cometapi-responses --model your-model-id -p "Reply with one short sentence confirming the Responses connection."
    ```

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

    ```bash theme={null}
    pi --list-models cometapi-chat
    ```

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

    ```bash theme={null}
    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`을 다시 여세요.
  </Step>
</Steps>

## 문제 해결

<AccordionGroup>
  <Accordion title="Pi에 CometAPI 모델이 표시되지 않습니다">
    `~/.pi/agent/models.json`이 유효한 JSON인지, 그리고 각 provider 항목이 최상위 `providers` 객체 안에 있는지 확인하세요. 파일을 저장한 후 `pi --list-models cometapi-responses` 또는 `pi --list-models cometapi-chat`을 실행하세요.
  </Accordion>

  <Accordion title="Pi가 사용 가능한 API 키가 없다고 보고합니다">
    Pi를 실행하는 동일한 셸 세션에서 `COMETAPI_KEY`가 설정되어 있는지 확인하세요. 셸 프로필을 사용한다면, Pi를 실행하기 전에 새 터미널을 열거나 프로필을 source 하세요.
  </Accordion>

  <Accordion title="base URL 때문에 요청이 실패합니다">
    `models.json`에서 `baseUrl`로 `https://api.cometapi.com/v1`을 사용하세요. Pi가 대시보드 URL을 가리키도록 설정하지 말고, OpenAI 호환 라우트에 필요한 `/v1` 접미사를 생략하지 마세요.
  </Accordion>

  <Accordion title="Pi가 모델 요청을 보내기 전에 실패합니다">
    `node --version`으로 Node.js 버전을 확인하세요. Pi 패키지는 Node.js `>=22.19.0`이 필요합니다.
  </Accordion>

  <Accordion title="모델이 한 라우트에서는 작동하지만 다른 라우트에서는 작동하지 않습니다">
    모델이 지원하는 라우트와 `api` 필드가 일치하는 provider 항목을 사용하세요. `openai-responses`는 Responses API를 사용하고, `openai-completions`는 채팅 완성을 사용합니다.
  </Accordion>

  <Accordion title="Pi가 예상보다 더 많은 접근 권한을 가집니다">
    Pi는 이를 실행한 사용자와 프로세스의 권한으로 동작합니다. 파일, 프로세스, 네트워크 접근 또는 자격 증명에 대해 더 강한 경계가 필요하다면 컨테이너나 샌드박스 내부에서 Pi를 실행하세요.
  </Accordion>
</AccordionGroup>

## 관련 리소스

* [CometAPI 빠른 시작](/ko/overview/quick-start)
* [CometAPI Models 페이지](/ko/overview/models)
* [Pi 사용자 지정 모델](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [Pi CLI 사용법](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/pi#howto",
        "name": "CometAPI와 함께 Pi 사용하기",
        "description": "이 가이드를 사용해 base URL, API 키, model 또는 provider 옵션을 설정하여 Pi를 CometAPI와 함께 구성하세요.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-1",
            "position": 1,
            "name": "Pi 설치",
            "text": "CometAPI와 함께 Pi 사용하기 가이드에서 Pi 설치 단계를 완료하세요."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-2",
            "position": 2,
            "name": "CometAPI API 키 설정",
            "text": "통합에서 사용하는 환경 변수 또는 설정 필드에 CometAPI API 키를 저장하세요."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-3",
            "position": 3,
            "name": "models.json에 CometAPI provider 추가",
            "text": "CometAPI와 함께 Pi 사용하기 가이드에서 models.json에 CometAPI provider 추가 단계를 완료하세요."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-4",
            "position": 4,
            "name": "두 provider 모두 확인",
            "text": "CometAPI와 함께 Pi 사용하기 가이드에서 두 provider 모두 확인 단계를 완료하세요."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "CometAPI 문서",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "통합",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "CometAPI와 함께 Pi 사용하기",
            "item": "https://apidoc.cometapi.com/integrations/pi"
          }
        ]
      }
    ]
    }
    `}
</script>