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

# 使用 OpenCode 和 CometAPI

> 使用本指南在 OpenCode 中将四种 CometAPI API 格式配置为自定义提供商。

使用本指南运行 [OpenCode](https://opencode.ai/docs/) 并搭配 CometAPI 使用。
该配置通过独立的自定义提供商提供四种 API 格式。

此配置已通过 OpenCode 1.18.16 测试。

官方参考：

* [OpenCode 安装](https://opencode.ai/docs/#install)
* [OpenCode 配置](https://opencode.ai/docs/config/)
* [OpenCode 自定义提供商](https://opencode.ai/docs/providers/#custom-provider)
* [OpenCode 模型选择](https://opencode.ai/docs/models/)
* [OpenCode 权限](https://opencode.ai/docs/permissions/)

<Note>
  将每个 `your-model-id` 值替换为来自以下页面的模型 ID：
  [CometAPI 模型页面](/zh-Hans/overview/models)。请选择接受周围提供商条目所用 API
  格式的模型。
</Note>

## 前提条件

* Node.js 和 npm，或 OpenCode 指南中的其他安装方法
* 拥有来自以下位置的有效 API 密钥的 CometAPI 账户：
  [控制台](https://www.cometapi.com/console/token)
* 来自以下页面的一个或多个模型 ID： [CometAPI 模型页面](/zh-Hans/overview/models)

## 了解 API 格式

每个提供商 ID 都选择一个 SDK 适配器和一种 API 格式。

| 提供商 ID               | OpenCode 适配器                | 基础 URL                            | API 格式                 |
| -------------------- | --------------------------- | --------------------------------- | ---------------------- |
| `cometapi-chat`      | `@ai-sdk/openai-compatible` | `https://api.cometapi.com/v1`     | 聊天补全                   |
| `cometapi-responses` | `@ai-sdk/openai`            | `https://api.cometapi.com/v1`     | 响应                     |
| `cometapi-messages`  | `@ai-sdk/anthropic`         | `https://api.cometapi.com/v1`     | Anthropic 消息           |
| `cometapi-gemini`    | `@ai-sdk/google`            | `https://api.cometapi.com/v1beta` | Gemini generateContent |

本指南验证正常 OpenCode 代理轮次中使用的 Gemini 流式操作。Google 适配器会将
`:streamGenerateContent?alt=sse` 追加到模型路径。

请勿添加 `/chat/completions`、`/responses`、`/messages` 或 Gemini 模型
路径到 `baseURL`。每个适配器都会追加其所需的操作路径。

## 了解运行时权限

OpenCode 使用启动它的进程所具有的权限运行。请在目标项目目录中启动
OpenCode，并保留 git 等回滚途径。在需要更严格的文件系统、进程、
网络或 API 密钥边界时，请使用容器或沙箱。

## 配置 OpenCode

<Steps>
  <Step title="安装 OpenCode">
    使用官方 npm 包安装 OpenCode：

    ```bash theme={null}
    npm install -g opencode-ai
    ```

    确认 CLI 可用：

    ```bash theme={null}
    opencode --version
    ```

    请参阅 [OpenCode 安装指南](https://opencode.ai/docs/#install)
    ，了解 Homebrew、Windows、Docker 及其他安装方法。
  </Step>

  <Step title="设置 CometAPI API 密钥">
    将 CometAPI API 密钥存储在 `COMETAPI_KEY` 环境变量中。

    <Tabs>
      <Tab title="macOS / Linux / WSL">
        读取 API 密钥而不在终端中显示：

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

      <Tab title="Windows PowerShell">
        将 API 密钥读取到当前 PowerShell 会话中：

        ```powershell theme={null}
        $secureKey = Read-Host "CometAPI API key" -AsSecureString
        $env:COMETAPI_KEY = [System.Net.NetworkCredential]::new(
          "",
          $secureKey
        ).Password
        ```
      </Tab>
    </Tabs>

    在每个启动 OpenCode 的 shell 会话中设置该变量。请勿
    将 API 密钥提交到版本控制系统。
  </Step>

  <Step title="选择配置位置">
    使用以下任一受支持的位置：

    * 全局配置：`~/.config/opencode/opencode.json`
    * 项目配置：项目根目录中的 `opencode.json`

    OpenCode 会合并配置文件。项目配置会覆盖全局配置中
    冲突的值。

    如果希望在每个项目中使用这些提供商，请使用全局文件。如果某个
    仓库需要自己的模型条目，请使用项目文件。
  </Step>

  <Step title="添加 CometAPI 提供商">
    创建选定的配置文件。如果该文件已包含一个
    `provider` 对象，请将以下四个条目合并到该对象中：

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "cometapi-chat": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "CometAPI Chat Completions",
          "options": {
            "baseURL": "https://api.cometapi.com/v1",
            "apiKey": "{env:COMETAPI_KEY}"
          },
          "models": {
            "your-model-id": {
              "name": "CometAPI Chat model"
            }
          }
        },
        "cometapi-responses": {
          "npm": "@ai-sdk/openai",
          "name": "CometAPI Responses",
          "options": {
            "baseURL": "https://api.cometapi.com/v1",
            "apiKey": "{env:COMETAPI_KEY}"
          },
          "models": {
            "your-model-id": {
              "name": "CometAPI Responses model"
            }
          }
        },
        "cometapi-messages": {
          "npm": "@ai-sdk/anthropic",
          "name": "CometAPI Anthropic Messages",
          "options": {
            "baseURL": "https://api.cometapi.com/v1",
            "apiKey": "{env:COMETAPI_KEY}"
          },
          "models": {
            "your-model-id": {
              "name": "CometAPI Messages model"
            }
          }
        },
        "cometapi-gemini": {
          "npm": "@ai-sdk/google",
          "name": "CometAPI Gemini",
          "options": {
            "baseURL": "https://api.cometapi.com/v1beta",
            "apiKey": "{env:COMETAPI_KEY}"
          },
          "models": {
            "your-model-id": {
              "name": "CometAPI Gemini model"
            }
          }
        }
      }
    }
    ```

    分别替换每个 `your-model-id` 键。四个条目可以使用
    不同的模型 ID。

    该配置未设置顶层 `model`。这样您便可通过
    `/models` 选择所需的 API 格式和模型。

    <Warning>
      请勿在此配置中使用 `/connect`。`apiKey` 字段会读取
      `COMETAPI_KEY` 环境变量。未设置的变量会解析为空
      值，而非已存储的 `/connect` API 密钥。
    </Warning>
  </Step>

  <Step title="选择并验证各个提供商">
    在您希望 OpenCode 访问的项目中启动它：

    ```bash theme={null}
    opencode
    ```

    运行 `/models`，然后选择一个 `provider/model` 条目。在本指南的四次验证运行中，
    每个模型轮次都使用了所选条目对应的 API 格式；未观察到跨格式请求扇出或自动
    协商 API 格式。

    要从命令行验证聊天补全，请运行：

    ```bash theme={null}
    opencode run \
      --model cometapi-chat/your-model-id \
      "Reply exactly with: COMETAPI_CHAT_OK"
    ```

    要从命令行验证响应，请运行：

    ```bash theme={null}
    opencode run \
      --model cometapi-responses/your-model-id \
      "Reply exactly with: COMETAPI_RESPONSES_OK"
    ```

    要从命令行验证 Anthropic 消息，请运行：

    ```bash theme={null}
    opencode run \
      --model cometapi-messages/your-model-id \
      "Reply exactly with: COMETAPI_MESSAGES_OK"
    ```

    要从命令行验证 Gemini generateContent，请运行：

    ```bash theme={null}
    opencode run \
      --model cometapi-gemini/your-model-id \
      "Reply exactly with: COMETAPI_GEMINI_OK"
    ```
  </Step>
</Steps>

## 故障排除

<AccordionGroup>
  <Accordion title="OpenCode 未显示 CometAPI 模型">
    确认配置为有效的 JSON。每个自定义条目必须位于
    顶层 `provider` 对象内，且每个模型 ID 必须位于
    对应的 `models` 对象内。重启 OpenCode，然后再次打开 `/models`。
  </Accordion>

  <Accordion title="OpenCode 报告 API 密钥或身份验证错误">
    确认在启动 OpenCode 的 shell 中已设置 `COMETAPI_KEY`。
    未设置的 `{env:COMETAPI_KEY}` 引用会变为空值。更改 shell 配置文件后，请打开新的
    shell。
  </Accordion>

  <Accordion title="模型 ID 不可用">
    查看 [CometAPI 模型页面](/zh-Hans/overview/models)，然后替换所选提供商条目中的模型
    ID。确认该模型接受该提供商的 API 格式。
  </Accordion>

  <Accordion title="请求使用了错误的路径">
    对于聊天补全、响应和消息，请将 `baseURL` 保持为 `/v1`。对于 Gemini，请使用
    `/v1beta` 。请勿在 `baseURL` 中包含操作路径。
  </Accordion>

  <Accordion title="一个提供商可用，但另一个提供商失败">
    请使用接受所选提供商 API 格式的模型 ID。不要
    假设同一个模型 ID 接受全部四种格式。
  </Accordion>

  <Accordion title="项目配置更改了全局提供商">
    OpenCode 会合并全局配置和项目配置。当希望全局
    提供商条目保持不变时，请重命名项目提供商 ID 或移除其冲突的值。
  </Accordion>

  <Accordion title="OpenCode 的访问权限超出预期">
    OpenCode 使用启动它的进程所具有的权限。在需要更严格访问边界时，请在
    容器或沙箱中运行 OpenCode。
  </Accordion>
</AccordionGroup>

## 相关资源

* [CometAPI 快速入门](/zh-Hans/overview/quick-start)
* [CometAPI 模型页面](/zh-Hans/overview/models)
* [OpenCode 自定义提供商](https://opencode.ai/docs/providers/#custom-provider)
* [OpenCode 配置](https://opencode.ai/docs/config/)
* [OpenCode 模型选择](https://opencode.ai/docs/models/)

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/opencode#howto",
        "name": "使用 OpenCode 和 CometAPI",
        "description": "使用本指南在 OpenCode 中将四种 CometAPI API 格式配置为自定义提供商。",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-1",
            "position": 1,
            "name": "安装 OpenCode",
            "text": "安装 OpenCode 并确认 CLI 可用。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-2",
            "position": 2,
            "name": "设置 CometAPI API 密钥",
            "text": "将 CometAPI API 密钥存储在 COMETAPI_KEY 环境变量中。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-3",
            "position": 3,
            "name": "选择配置位置",
            "text": "选择全局 OpenCode 配置或项目配置。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-4",
            "position": 4,
            "name": "添加 CometAPI 提供商",
            "text": "将四个 CometAPI 自定义提供商条目添加到 opencode.json。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-5",
            "position": 5,
            "name": "选择并验证各个提供商",
            "text": "选择并验证所需的 CometAPI 提供商和模型。"
          }
        ]
      },
      {
        "@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": "使用 OpenCode 和 CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/opencode"
          }
        ]
      }
    ]
    }
    `}
</script>