> ## 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，以及模型或供應商選項，將 Pi 設定為搭配 CometAPI 使用。

[Pi](https://github.com/earendil-works/pi) 是 Pi Agent Harness 專案。它的 `@earendil-works/pi-coding-agent` 套件提供互動式編碼代理 CLI，支援檔案、shell、edit、write、session、print、JSON、RPC 與 SDK 工作流程。Pi 可以從 `~/.pi/agent/models.json` 載入自訂供應商，因此你可以將 CometAPI 作為與 OpenAI 相容的供應商項目加入，而無需變更 Pi 原始碼。

官方參考資料：

* [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>
  模型可用性會隨時間變動。請將 `your-model-id` 替換為來自 [CometAPI Models page](/zh-Hant/overview/models) 的可用 model ID。
</Note>

## 先決條件

* Node.js `>=22.19.0`
* npm
* 一個 CometAPI 帳戶，且已從 [dashboard](https://www.cometapi.com/console/token) 取得啟用中的 API key
* 已從官方 npm 套件安裝 Pi

## 了解執行階段權限

Pi 會以啟動它的使用者與程序權限執行。請在你希望它操作的專案目錄中啟動 Pi，保留像是 git 這樣的回復路徑，若你需要更嚴格的檔案系統、程序、網路或憑證邊界，請使用容器或沙箱。

## 設定提供者

<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 指令加入你的 shell 設定檔。不要將 API 金鑰提交到版本控制。
  </Step>

  <Step title="將 CometAPI 提供者加入 models.json">
    如果 `~/.pi/agent/models.json` 不存在，請建立它。如果該檔案已經包含 providers，請將 `cometapi-responses` 和 `cometapi-chat` 項目合併到現有的 `providers` 物件中：

    ```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 的 model 或工作流程，請使用 `cometapi-responses`。對於相容 OpenAI 聊天補全的 model，請使用 `cometapi-chat`。Pi 會在請求時解析 `$COMETAPI_KEY`。請將 API 金鑰保留在你的環境中，或保留在你自己的 secrets 工作流程中。
  </Step>

  <Step title="驗證兩個提供者">
    列出 Pi 可為 Responses 提供者看到的 model：

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

    使用 Responses 提供者執行簡短的一次性 Prompt：

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

    列出 Pi 可為聊天補全提供者看到的 model：

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

    使用聊天補全提供者執行簡短的一次性 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 提供者與 model。如果你在互動式工作階段期間編輯 `models.json`，請再次開啟 `/model`，讓 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 key">
    確認 `COMETAPI_KEY` 已在啟動 Pi 的同一個 shell 工作階段中設定。如果你使用 shell profile，請在執行 Pi 之前開啟新的終端機，或重新載入該 profile。
  </Accordion>

  <Accordion title="請求因 base URL 而失敗">
    在 `models.json` 中使用 `https://api.cometapi.com/v1` 作為 `baseUrl`。不要將 Pi 指向 dashboard 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 快速開始](/zh-Hant/overview/quick-start)
* [CometAPI Models 頁面](/zh-Hant/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 key，以及 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 key",
            "text": "將你的 CometAPI API key 儲存在此整合所使用的環境變數或設定欄位中。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-3",
            "position": 3,
            "name": "將 CometAPI provider 加入 models.json",
            "text": "完成「搭配 CometAPI 使用 Pi」指南中的「將 CometAPI provider 加入 models.json」步驟。"
          },
          {
            "@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>