> ## 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.

# 使用 Pi 与 CometAPI

> 使用本指南通过设置 base URL、API key，以及 model 或 provider 选项，将 Pi 配置为使用 CometAPI。

[Pi](https://github.com/earendil-works/pi) 是 Pi Agent Harness 项目。它的 `@earendil-works/pi-coding-agent` 包提供了一个交互式编码代理 CLI，支持文件、shell、编辑、写入、会话、打印、JSON、RPC 和 SDK 工作流。Pi 可以从 `~/.pi/agent/models.json` 加载自定义 provider，因此你可以将 CometAPI 作为兼容 OpenAI 的 provider 条目添加进去，而无需修改 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-Hans/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` 不存在，请创建它。如果该文件已包含提供商，请将 `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 的模型或工作流，请使用 `cometapi-responses`。对于兼容 OpenAI 聊天补全 API 的模型，请使用 `cometapi-chat`。Pi 会在请求时解析 `$COMETAPI_KEY`。请将 API 密钥保存在你的环境中，或保存在你自己的密钥管理工作流中。
  </Step>

  <Step title="验证两个提供商">
    列出 Pi 对 Responses 提供商可见的模型：

    ```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 对聊天补全提供商可见的模型：

    ```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 提供商和模型。如果你在交互式会话期间编辑了 `models.json`，请再次打开 `/model`，以便 Pi 重新加载自定义模型条目。
  </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 配置文件，请在运行 Pi 之前打开一个新的终端，或重新加载该配置文件。
  </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-Hans/overview/quick-start)
* [CometAPI Models 页面](/zh-Hans/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": "将 Pi 与 CometAPI 配合使用",
        "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": "完成“将 Pi 与 CometAPI 配合使用”指南中的“安装 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": "将 CometAPI providers 添加到 models.json",
            "text": "完成“将 Pi 与 CometAPI 配合使用”指南中的“将 CometAPI providers 添加到 models.json”步骤。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-4",
            "position": 4,
            "name": "验证两个 provider",
            "text": "完成“将 Pi 与 CometAPI 配合使用”指南中的“验证两个 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": "将 Pi 与 CometAPI 配合使用",
            "item": "https://apidoc.cometapi.com/integrations/pi"
          }
        ]
      }
    ]
    }
    `}
</script>