BazaarLinkBazaarLink
登入
← 所有文章
發布時間 2026-09-21 · · 作者：BazaarLink · OpenClaw · AI assistant · Gateway · OpenAI 相容端點

OpenClaw 入門：安裝、設定與自訂 OpenAI 相容端點

從 Node.js 安裝 OpenClaw，啟動 Gateway，並以官方 custom provider 設定接上自訂 OpenAI 相容端點。

OpenClaw 入門：從安裝到接上自訂 OpenAI 相容端點

OpenClaw 是一個開源 AI assistant。它把對話、Gateway、頻道整合、工具與可安裝的 skill 放在同一個可自架的工作流裡；你可以在自己的環境啟動 Gateway，再讓不同聊天入口共用同一組 agent 設定。

截至 2026-09-21，官方 npm 套件版本是 2026.9.5。本篇依官方文件整理安裝、最小啟動、模型設定與 ClawHub 的基本操作；若你的版本不同，請以該版本的官方文件為準。

1. OpenClaw 是什麼，解決什麼問題？

如果你只是想在終端機問模型問題，單一 SDK 就夠了。但當你想把同一個 assistant 放進多個聊天入口、讓它持續由 Gateway 管理，並用 skills 擴充工作流程時，分散設定通常會很快變得難以維護。

OpenClaw 的核心可以先這樣理解：

  • Gateway 是常駐的控制面，負責接收請求與管理 agent 工作流。
  • agent 決定使用哪個模型，以及要套用哪些預設。
  • provider 設定模型的連線方式、API 形態與模型能力。
  • skill 是可被 OpenClaw 使用的功能包；ClawHub 是公開的 skill registry。

這篇只處理一條最小路徑：先在本機讓 Gateway 跑起來，再把 agent 指向一個 OpenAI 相容端點。頻道、daemon 與 skill 的進一步配置，等基礎路徑確認後再加。

2. 安裝與最小可跑範例

先準備 Node.js

官方 Getting Started 文件目前要求 Node.js 24.16+ 或 26.1+，並建議使用 Node 26。先確認版本：

node --version
npm --version

安裝 OpenClaw

官方文件提供互動式安裝器；也可以用 npm 全域安裝：

npm install -g openclaw@latest --allow-scripts=openclaw

安裝後先完成 onboarding：

openclaw onboard --install-daemon

如果你不想一開始安裝 daemon，可以先執行：

openclaw onboard

接著啟動或檢查 Gateway：

openclaw gateway status
openclaw gateway

官方預設 Gateway port 是 18789。要開啟控制介面，可執行：

openclaw dashboard

如果你只想確認 CLI 能被找到，這個最小檢查也足夠：

openclaw --version

先用內建命令查看 skills

OpenClaw 官方文件提供 ClawHub 的命令列操作範例：

openclaw skills search "calendar"
openclaw skills install @openclaw/demo
openclaw skills update --all

這裡的重點是先確認 CLI、Gateway 與 skill 路徑都能工作；本文不假設你已經安裝任何特定 skill。

3. 主要設定：指到自訂 OpenAI 相容端點

OpenClaw 的官方 custom provider 設定放在設定檔的 models.providers。最小 JSON5 範例如下：

{
  models: {
    providers: {
      bazaarlink: {
        baseUrl: "https://api.bazaarlink.ai/v1",
        apiKey: "${BAZAARLINK_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gemini-3.8-flash",
            name: "gemini-3.8-flash",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1000000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "bazaarlink/gemini-3.8-flash",
      },
    },
  },
}

上面使用的 gemini-3.8-flash 是在 2026-09-21 讀取公開模型清單時查到的實際 model ID。這次以 OpenAI 相容的 image_url data URI 形狀實測回 200，模型確實讀到圖片並回答顏色；因此範例宣告已查核的 text 與 image 輸入，查核日期為 2026-09-21。

API key 不要直接寫進版本庫。可先在目前 shell 設定佔位符對應的環境變數：

export BAZAARLINK_API_KEY="<BAZAARLINK_API_KEY>"

Windows PowerShell：

$env:BAZAARLINK_API_KEY = "<BAZAARLINK_API_KEY>"

官方 custom provider 文件的關鍵欄位是：

  • baseUrl：相容端點的 base URL。
  • apiKey：可放環境變數替換值。
  • api：API 形態；官方範例對 OpenAI 相容 completion 介面使用 openai-completions。
  • models[].id：上游實際接受的模型 ID。
  • reasoning、input、contextWindow、maxTokens：模型能力與限制的描述欄位。
  • agents.defaults.model.primary：使用 provider/model 格式指定預設模型。

若你要保留同名 provider 的其他設定，官方文件也說明 mode: "merge" 的用法；新增 provider 時先用一份最小設定排錯會比較容易：

{
  models: {
    mode: "merge",
    providers: {
      bazaarlink: {
        baseUrl: "https://api.bazaarlink.ai/v1",
        apiKey: "${BAZAARLINK_API_KEY}",
        api: "openai-completions",
        models: [{ id: "gemini-3.8-flash", name: "gemini-3.8-flash" }],
      },
    },
  },
}

OpenClaw 官方文件確認了 custom provider 的欄位與模型選擇方式。以下是 2026-09-21 用真實帳號做的最小 request-shape replay：

  • GET https://api.bazaarlink.ai/v1/models 使用 Authorization: Bearer 回 200，回應含 object、data，且清單含 gemini-3.8-flash。
  • 這份設定已在 models[] 明確列出 model ID，因此固定模型的生成路徑不需要先用 /v1/models 才能組出請求；openclaw models list --refresh 等目錄刷新是另一個流程，可能另外讀取模型清單。
  • OpenClaw openai-completions 的 POST https://api.bazaarlink.ai/v1/chat/completions 使用 stream: true 回 200、text/event-stream，共 5 個 SSE chunk，有文字 delta 並以 [DONE] 收尾。純文字對話也回 200，finish_reason=stop，有正常文字。
  • 帶 tools 與 tool_choice: auto 的請求回 200，finish_reason=tool_calls，回應含 get_weather 與 {"city":"Taipei"}；這次已確認符合 OpenAI tool call 的標準結束原因。
  • 帶標準 top-level reasoning_effort: "low" 的請求回 200，但回應只有 role 與 content，沒有結構化 reasoning 欄位；這是「請求被接受」，不是完整 reasoning 互通證明。
  • 用 agent 常見的 image_url data URI 請求回 200，模型確實讀到圖片並回答顏色；這個圖片輸入形狀已於 2026-09-21 查核。
  • 若明確把 custom provider 改成 Anthropic Messages 形狀，x-api-key 的 POST /v1/messages 短文字請求回 200，回應 type=message；這不是目前 openai-completions 設定的預設路徑，Anthropic 格式的工具與串流互通仍未驗證。

這些是端點級 request-shape 結果，不是已安裝 OpenClaw Gateway 的全流程驗收；Gateway session、頻道與 skill 工作流仍須另行驗證。

4. 常見問題

啟動後找不到模型

先檢查 agents.defaults.model.primary 是否是 provider/model 格式，例如 bazaarlink/gemini-3.8-flash。再確認 models.providers.bazaarlink.models[].id 與公開模型清單的 ID 完全一致。

為什麼不能把 provider 名稱當成模型 ID？

OpenClaw 用 provider/model 解析預設模型。provider 是你在設定檔中取的名字；model 是端點真正接受的 ID。兩者混用時，Gateway 可能啟動成功，但模型解析會失敗。

設定檔可以使用 JSON 嗎？

官方範例使用 JSON5，因此註解與尾逗號可能可用；實際仍以你目前版本接受的設定檔格式為準。若遇到解析錯誤，先拿掉註解與尾逗號，用最小純 JSON 結構重試。

為什麼設定改了但行為沒變？

先確認 Gateway 讀的是你正在修改的設定檔，再重新啟動 Gateway。也要檢查目前 agent 是否仍被 session 或其他 profile 覆寫。不要只看 dashboard 是否能開啟，要實際確認目前選用的 model。

Node 版本符合，仍然安裝失敗

先確認 node --version 與 npm --version，再重新開一個 shell，確保執行到的是同一份全域安裝。若使用官方安裝器，保留安裝輸出的錯誤訊息，並對照該版本的 Getting Started 文件。

回應幾乎是空的，而且 finish_reason 是 length，怎麼辦？

這個模型預設開啟思考；如果 max_tokens 太小，推理 token 可能先把額度用完，導致 finish_reason=length 且幾乎沒有輸出。把 max_tokens 調高即可；實測從 16 調到 400 後才正常輸出。

把 provider 的 baseUrl 設成 https://api.bazaarlink.ai/v1，apiKey 使用 <BAZAARLINK_API_KEY>，再以公開模型清單中的實際 ID（本文為 gemini-3.8-flash）填入 models[].id。純文字、tool call（finish_reason=tool_calls）、5 個 SSE chunk 串流與圖片輸入（模型讀到圖片並回答顏色）的最小形狀已在 2026-09-21 驗證；OpenClaw 完整 session／channel／skill 流程，以及 Anthropic 格式的工具與串流互通仍不可宣稱。需要更多端點設定時，可參考模型清單與SDK 文件。

立即體驗 BazaarLink

台幣計費・統一發票・主流 AI 模型・OpenAI 相容 API

免費註冊 / 登入企業採購洽詢
客服
客服
您好！有什麼可以協助？
請留下訊息，我們會盡快回覆。