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

# 使用 OpenClaw 搭配 CometAPI

> 使用本指南透過設定 base URL、API key，以及 model 或 provider 選項，將 OpenClaw 設定為使用 CometAPI。

使用 [CometAPI](https://www.cometapi.com) 作為 [OpenClaw](https://openclaw.ai) 的模型提供者 —— 一個 API 即可使用 500+ 個模型。

## 先決條件

* Node.js ≥ 22 —— 建議透過 [nvm](https://github.com/nvm-sh/nvm) 安裝
* 擁有一個啟用中 API key 的 CometAPI 帳戶 —— [在這裡取得](https://www.cometapi.com/console/token)

## 安裝

<Steps>
  <Step title="取得你的 CometAPI API key">
    登入 [CometAPI 主控台](https://www.cometapi.com/console/token)。點擊 **Add API Key**，然後複製你的 CometAPI API key。

    <Frame>
      <img src="https://mintcdn.com/cometapi/SZhlxZhCnMLn__BW/images/overview/810968_364191.png?fit=max&auto=format&n=SZhlxZhCnMLn__BW&q=85&s=aef81a83f29f8eb16655ed4060425f50" alt="顯示 Add API Key 按鈕的 CometAPI 儀表板" width="3824" height="1892" data-path="images/overview/810968_364191.png" />
    </Frame>

    <Frame>
      <img src="https://mintcdn.com/cometapi/HhtmQffktazbxUvS/images/overview/810968_364193.png?fit=max&auto=format&n=HhtmQffktazbxUvS&q=85&s=d893f659267150d0faf45f99eb5dffc1" alt="包含 base URL 的 CometAPI API key 詳細資訊" width="2434" height="1232" data-path="images/overview/810968_364193.png" />
    </Frame>
  </Step>

  <Step title="安裝或更新 OpenClaw">
    **建議** —— 使用官方安裝程式：

    ```bash theme={null}
    curl -fsSL https://openclaw.ai/install.sh | bash
    ```

    或透過 npm 安裝：

    ```bash theme={null}
    npm install -g openclaw@latest
    ```

    接著執行一次設定精靈：

    ```bash theme={null}
    openclaw onboard --install-daemon
    ```

    在初始化設定期間，如果你想手動設定 CometAPI，請在 Model/Auth 步驟中選擇 **Skip**。完成初始化後，確認 gateway 正在執行：

    ```bash theme={null}
    openclaw gateway status
    openclaw dashboard
    ```
  </Step>
</Steps>

## 設定

<Steps>
  <Step title="儲存你的 CometAPI 金鑰">
    將你的金鑰寫入 `~/.openclaw/.env`，讓 daemon 可使用它，而不必將其硬編碼在設定檔中：

    ```bash theme={null}
    printf 'COMETAPI_KEY=%s\n' "$COMETAPI_KEY" >> ~/.openclaw/.env
    chmod 600 ~/.openclaw/.env
    ```

    <Note>
      如果你已經透過 shell、服務管理器或 secrets 工作流程注入 `COMETAPI_KEY`，請跳過此步驟——下方的設定無論變數如何設定，都會使用 `$\{COMETAPI_KEY\}`。
    </Note>
  </Step>

  <Step title="設定 CometAPI providers">
    CometAPI 支援 **四種 API 格式**。將一個或多個 provider 區塊加入 `~/.openclaw/openclaw.json`：

    | Provider                    | API 格式                 | 呼叫的端點                       | Base URL                          |
    | --------------------------- | ---------------------- | --------------------------- | --------------------------------- |
    | `cometapi-openai`           | `openai-completions`   | `POST /v1/chat/completions` | `https://api.cometapi.com/v1`     |
    | `cometapi-openai-responses` | `openai-responses`     | `POST /v1/responses`        | `https://api.cometapi.com/v1`     |
    | `cometapi-claude`           | `anthropic-messages`   | `POST /messages`            | `https://api.cometapi.com`        |
    | `cometapi-google`           | `google-generative-ai` | `POST /v1beta/...`          | `https://api.cometapi.com/v1beta` |

    ```json theme={null}
    {
      "agents": {
        "defaults": {
          "model": {
            "primary": "cometapi-claude/your-claude-model-id"
          }
        }
      },
      "models": {
        "mode": "merge",
        "providers": {
          "cometapi-openai": {
            "baseUrl": "https://api.cometapi.com/v1",
            "apiKey": "${COMETAPI_KEY}",
            "api": "openai-completions",
            "models": [{ "id": "your-chat-model-id", "name": "OpenAI-compatible text model" }]
          },
          "cometapi-openai-responses": {
            "baseUrl": "https://api.cometapi.com/v1",
            "apiKey": "${COMETAPI_KEY}",
            "api": "openai-responses",
            "models": [{ "id": "your-responses-model-id", "name": "Responses API model" }]
          },
          "cometapi-claude": {
            "baseUrl": "https://api.cometapi.com",
            "apiKey": "${COMETAPI_KEY}",
            "api": "anthropic-messages",
            "models": [{ "id": "your-claude-model-id", "name": "Claude family model" }]
          },
          "cometapi-google": {
            "baseUrl": "https://api.cometapi.com/v1beta",
            "apiKey": "${COMETAPI_KEY}",
            "api": "google-generative-ai",
            "models": [{ "id": "your-gemini-model-id", "name": "Gemini family model" }]
          }
        }
      }
    }
    ```

    你可以只保留需要的 providers，或保留全部四種，使用 `provider/model` 參照在不同格式之間路由。

    請將每個 `your-...-model-id` 佔位符替換為來自 [CometAPI Models page](https://www.cometapi.com/models/) 且與該 provider 區塊相符的目前 model ID。

    <Note>
      對於需要 OpenAI Responses API 的模型，請使用 `cometapi-openai-responses`（`api: "openai-responses"`）。對於走經典聊天補全路徑的模型，請使用 `cometapi-openai`（`api: "openai-completions"`）。兩者共用相同的 `baseUrl`（`https://api.cometapi.com/v1`）；唯一差異在於 OpenClaw 會呼叫哪個下游端點。
    </Note>

    <Note>
      此設定**不需要** `auth-profiles.json` 檔案。provider 金鑰會透過 `$\{COMETAPI_KEY\}` 環境變數，從 `models.providers.*.apiKey` 解析。只有當你想在多個金鑰之間進行每個 profile 的憑證輪替時，才需要 `auth-profiles.json`。
    </Note>
  </Step>
</Steps>

## 驗證

<Steps>
  <Step title="重新啟動並驗證">
    在加入 `.env` 或變更 provider 設定後，重新啟動 gateway：

    ```bash theme={null}
    openclaw gateway restart
    ```

    然後執行診斷：

    ```bash theme={null}
    openclaw models status
    openclaw models list --provider cometapi-claude
    openclaw doctor
    ```

    成功的設定會呈現如下：

    * `openclaw models status` 會將主要模型解析為 `cometapi-claude/your-claude-model-id`，且不會出現 CometAPI providers 的缺少驗證警告
    * `openclaw models list --provider cometapi-claude` 會列出你已設定的模型
    * `openclaw doctor` 不會回報 CometAPI providers 的 config 或 auth 錯誤

    <Frame>
      <img src="https://mintcdn.com/cometapi/3HbSFe0pH45ETcjq/images/integrations/810968_371721.png?fit=max&auto=format&n=3HbSFe0pH45ETcjq&q=85&s=928b6faed91c5c2cb2eceea6bfac630d" alt="顯示 CometAPI providers 已完成驗證的 OpenClaw models status" width="1906" height="296" data-path="images/integrations/810968_371721.png" />
    </Frame>
  </Step>
</Steps>

## 切換模型

<Steps>
  <Step title="切換模型">
    ```bash theme={null}
    # Set the default model in config
    openclaw models set cometapi-claude/your-claude-model-id

    # Switch for the current chat session
    /model cometapi-openai/your-chat-model-id
    /model cometapi-openai-responses/your-responses-model-id
    /model cometapi-claude/your-claude-model-id
    /model cometapi-google/your-gemini-model-id
    ```
  </Step>
</Steps>

## 疑難排解

<AccordionGroup>
  <Accordion title="乾淨重新安裝（可選）">
    如果你要修復損壞的舊版設定，請先停止 gateway、移除 `~/.openclaw`，然後在套用 CometAPI 設定前重新執行 onboarding：

    ```bash theme={null}
    openclaw gateway stop
    rm -rf ~/.openclaw
    openclaw onboard --install-daemon
    ```

    這會移除所有本機設定、工作階段、日誌、驗證狀態與工作區。接著再次依序執行步驟 3–5。
  </Accordion>
</AccordionGroup>

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/openclaw#howto",
        "name": "使用 OpenClaw 搭配 CometAPI",
        "description": "使用本指南，透過設定 base URL、API key，以及 model 或 provider 選項來設定 OpenClaw 與 CometAPI 搭配使用。",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/openclaw#step-1",
            "position": 1,
            "name": "取得你的 CometAPI API key",
            "text": "建立或開啟你的 CometAPI 帳戶，然後從控制台複製一組有效的 API key。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/openclaw#step-2",
            "position": 2,
            "name": "安裝或更新 OpenClaw",
            "text": "完成「使用 OpenClaw 搭配 CometAPI」指南中的「安裝或更新 OpenClaw」步驟。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/openclaw#step-3",
            "position": 3,
            "name": "儲存你的 CometAPI key",
            "text": "完成「使用 OpenClaw 搭配 CometAPI」指南中的「儲存你的 CometAPI key」步驟。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/openclaw#step-4",
            "position": 4,
            "name": "設定 CometAPI providers",
            "text": "完成「使用 OpenClaw 搭配 CometAPI」指南中的「設定 CometAPI providers」步驟。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/openclaw#step-5",
            "position": 5,
            "name": "重新啟動並驗證",
            "text": "完成「使用 OpenClaw 搭配 CometAPI」指南中的「重新啟動並驗證」步驟。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/openclaw#step-6",
            "position": 6,
            "name": "切換模型",
            "text": "完成「使用 OpenClaw 搭配 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": "使用 OpenClaw 搭配 CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/openclaw"
          }
        ]
      }
    ]
    }
    `}
</script>