# OpenClaw (/zh-Hant/docs/guides/openclaw)

透過自訂模型供應商，讓 OpenClaw 個人 AI 助理使用 cheapaimodel 的模型。



OpenClaw 在 `~/.openclaw/openclaw.json` 的 `models.providers` 下把 OpenAI 相容的服務加為自訂供應商。之後代理以 `cheapaimodel/<model-id>` 指稱這些模型。

|          | OpenClaw 設定                                 | 值                                                                                            |
| -------- | ------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Base URL | `models.providers.cheapaimodel.baseUrl`     | `https://api.cheapaimodel.ai/v1`                                                             |
| API Key  | `models.providers.cheapaimodel.apiKey`      | `${CHEAPAIMODEL_API_KEY}`，其值為在控制台的 [API Key](https://console.cheapaimodel.ai/keys) 頁面建立的 Key |
| 模型 ID    | `models.providers.cheapaimodel.models[].id` | `glm-5.3`，或[目錄](/zh-Hant/models)中的任一模型 ID                                                    |

## 設定 [#設定]

<Steps>
  <Step>
    ### 存放 Key [#存放-key]

    把 Key 放進 OpenClaw 的全域環境變數檔案；即使 Gateway 以背景服務執行，也會讀取這個檔案：

    ```bash title="~/.openclaw/.env"
    CHEAPAIMODEL_API_KEY=sk-...
    ```

    若 Gateway 已在執行，請以 `openclaw gateway restart` 重新啟動，讓它讀取這個檔案。
  </Step>

  <Step>
    ### 加入供應商 [#加入供應商]

    把以下內容合併到你的設定中：

    ```json5 title="~/.openclaw/openclaw.json"
    {
      agents: {
        defaults: {
          model: { primary: "cheapaimodel/glm-5.3" },
        },
      },
      models: {
        mode: "merge",
        providers: {
          cheapaimodel: {
            baseUrl: "https://api.cheapaimodel.ai/v1",
            apiKey: "${CHEAPAIMODEL_API_KEY}",
            api: "openai-completions",
            models: [
              {
                id: "glm-5.3",
                name: "GLM-5.3",
                compat: { supportsUsageInStreaming: true },
              },
            ],
          },
        },
      },
    }
    ```

    * `api: "openai-completions"` 會把請求送往 `/v1/chat/completions`。
    * 每個模型 ID 在 `models` 中加一筆。`id` 是目錄中的模型 ID；`name` 是顯示名稱，OpenClaw 要求必填。
    * 依模型頁面在每一筆加上 `contextWindow` 與 `maxTokens`，例如 [glm-5.3 的頁面](/zh-Hant/models/glm-5.3)。沒有填時，OpenClaw 會以自己的預設值估算上下文，輸出上限則交給伺服器決定。
    * `compat.supportsUsageInStreaming` 讓 OpenClaw 在串流中要求 token 用量，cheapaimodel 會回傳（見[串流](/zh-Hant/docs/concepts/streaming)）。沒有這一項時，OpenClaw 只能估算上下文用量，並在日誌中記下 `returned no token usage`。

    Gateway 會監看這個檔案，變更不需重新啟動即可生效。
  </Step>

  <Step>
    ### 確認 [#確認]

    ```bash title="Terminal"
    openclaw models list
    ```

    清單中應該會出現 `cheapaimodel/glm-5.3`。日後要更換預設模型，請執行 `openclaw models set cheapaimodel/<model-id>`。
  </Step>
</Steps>

OpenClaw 的代理仰賴模型的工具呼叫能力。若某個模型處理工具的效果不好，請改試目錄中的其他模型。

## 常見錯誤 [#常見錯誤]

* **OpenClaw 警告找不到 `CHEAPAIMODEL_API_KEY`。** Gateway 處理程序沒有這個變數，`${CHEAPAIMODEL_API_KEY}` 因此無法解析。請把它放進 `~/.openclaw/.env` 並重新啟動 Gateway。
* **`401`。** Key 錯誤、已到期或預算已用盡。請在控制台檢查。
* **設定被拒，訊息為 `custom model providers must declare models`。** 自訂供應商必須有 `models` 陣列，每一筆都要同時有 `id` 與 `name`。
* **`404`。** 主體為 `fault filter abort` 時，是 `baseUrl` 漏了 `/v1`；主體帶有 `Invalid URL (POST /v1/chat/completions/chat/completions)` 時，是 `baseUrl` 含有端點路徑。請設定 `https://api.cheapaimodel.ai/v1`。
* **`503` 且 `model_not_found`。** `id` 必須是目錄中的模型 ID，拼寫完全一致。`cheapaimodel/` 前綴只是 OpenClaw 的模型參照，不會送出。