安裝 OpenClaw 並設定 OmniProxy

OpenClaw 是一款安裝在您個人電腦上的 AI 助手。您可以直接透過 Telegram、Discord、WhatsApp 或飛書與其對話，無需額外開啟聊天視窗。對話與記錄會保留在這台電腦上，它也能在本地端持續執行後續步驟。

開始之前

OpenClaw 需要 Node 24.16 或更高版本。您也可以使用 Node 26.1 或更高版本，建議使用 Node 26。Node 提供了 OpenClaw 執行所需的運行環境。

它支援 macOS、Linux 與 Windows。如果電腦中沒有合適的 Node 版本，安裝指令碼會自動準備一個：macOS 上為 Node 26，Linux 上為 Node 24 LTS。僅在從原始碼建置 OpenClaw 時才需要 pnpm。

如果您已經安裝了舊版 Node，無需先解除安裝。在 2026-10-09 的測試中，該電腦的系統 Node 版本為 24.2.0（低於要求的 24.16），非互動式安裝指令碼自動準備了 Node 24.21.0。

想要視窗介面

桌面版伴侶程式

在 Windows 上使用 Hub 安裝程式
在 macOS 上使用 GitHub DMG
本地 Gateway 可在初始設定時安裝

官方推薦

安裝指令碼

macOS Linux WSL2
在 Windows 上使用 PowerShell
您可以加入 --no-onboard

已安裝 Node

套件管理員

npm pnpm 或 bun
然後執行 onboard
請參閱安裝頁面以確認 Node 版本

如果您需要視窗介面，請下載桌面版伴侶程式。若只想在終端機中使用，請執行官方安裝指令碼。

首次安裝與啟動

您可以安裝帶有圖形視窗的桌面版伴侶程式，或直接透過終端機安裝。Gateway 是負責接收訊息、呼叫模型並回傳結果的本地服務。您可以在首次開啟桌面版伴侶程式時進行設定。

如果您需要視窗介面

Windows：下載並執行 OpenClawCompanion-Setup-x64.exe 或 OpenClawCompanion-Setup-arm64.exe。安裝程式已簽署，包含設定、系統匣狀態、聊天與節點模式。
macOS：從 OpenClaw 的 GitHub 發布頁面下載 OpenClaw .dmg。建議優先使用 dmg，您也可以使用 .zip。安裝後開啟 OpenClaw.app。如果該版本未包含 macOS 檔案，請參閱 macOS 應用程式頁面。

首次開啟時，您可以讓 OpenClaw 在本機準備 Gateway，或連線至現有的遠端 Gateway。

透過終端機安裝

針對 macOS、Linux 與 WSL2，請使用：

curl -fsSL https://openclaw.ai/install.sh | bash

針對 Windows PowerShell，請使用：

iwr -useb https://openclaw.ai/install.ps1 | iex

該指令碼會偵測當前系統、在需要時安裝 Node、安裝 OpenClaw，然後啟動初始引導流程。引導流程將帶領您完成首次設定。

如果您不想立即開始引導，請在 macOS、Linux 與 WSL2 上改用：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

在 Windows 上，請使用官方的 -NoOnboard 選項：

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

如果您已自行管理 Node，也可以使用 npm、pnpm 或 bun。若使用 npm 12 或 npm 11.16 及更高版本，請執行：

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

對於 npm 11.15 及更早版本，請移除 --allow-scripts=openclaw。使用 pnpm 時，請加入 --allow-build=openclaw。詳細差異請參閱安裝頁面。

安裝完成後，請依序執行以下三條指令：

openclaw --version
openclaw doctor
openclaw gateway status

openclaw --version 顯示版本，openclaw doctor 檢查常見環境問題，openclaw gateway status 顯示 Gateway 是否正在執行。只有當這三條指令都產生正常輸出時，基本安裝才算完成。

如果終端機回報找不到 openclaw，通常是因為 npm 全域 bin 目錄未加入 PATH。PATH 是終端機搜尋程式的路徑列表。請比較 node -v、npm prefix -g 與 echo "$PATH" 的輸出，將對應的 bin 目錄加入 PATH，然後重新開啟終端機。

如果 ~/.openclaw 已經包含目前使用的設定，預設安裝指令碼將使用該目錄。若要安裝獨立副本而不更動現有設定，請執行非互動式指令碼並指定新目錄：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/openclaw-omniproxy" --no-onboard

--no-onboard 是此指令碼的預設行為。在 2026-10-09，此指令執行安裝了 OpenClaw 2026.9.9。安裝後，請從該目錄的 bin 資料夾執行 openclaw 可執行檔。

從 OmniProxy 取得連線數值

首先確認 OmniProxy 正在執行，然後開啟其模型列表並準備以下三個數值：

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copy the full value from the current OmniProxy model list

baseUrl 是 OpenClaw 發送模型請求的位址，必須以 /v1 結尾。連線至 OmniProxy 時，請將 api 設為 openai-completions。僅當模型確實透過 /v1/responses 運作時，才將其改為 openai-responses。

模型 ID 是列表中模型的完整識別碼。請完全依照顯示內容複製，包含任何斜線。以下兩個名稱僅為 2026-10-09 時供應商文件的參考；若它們未出現在列表中，請勿使用：claude-sonnet-5-5、gpt-6-luna。

即使 Gateway 不驗證金鑰，apiKey 仍必須包含一個數值。您可以使用僅在此電腦上使用的佔位字串。請勿將真實金鑰提交至儲存庫。

輸入工具設定

供應商（Provider）可以理解為 OpenClaw 用來定位模型服務的一組連線設定。在此，供應商名稱為 omniproxy。

在終端機中執行以下指令，將位址、金鑰與兩個模型 ID 替換為您自己的數值：

openclaw config set models.providers.omniproxy '{"baseUrl":"https://your-omniproxy-origin.example/v1","apiKey":"<YOUR_OMNIPROXY_API_KEY>","api":"openai-completions","models":[{"id":"claude-sonnet-5-5","name":"Claude Sonnet 5.5"},{"id":"gpt-6-luna","name":"GPT-6 Luna"}]}' --strict-json --merge

此指令會將供應商與模型列表寫入設定檔。指令成功後，無需重新啟動 Gateway。

接下來，指定預設模型。模型參考由 omniproxy/ 加上模型 ID 組成。請保留 ID 中已有的所有斜線。如果模型列表中的 ID 比下方的簡稱長，請使用列表中的完整數值：

openclaw config set agents.defaults.model.primary '"omniproxy/claude-sonnet-5-5"' --strict-json

reasoning、input、cost、contextWindow 與 maxTokens 均可省略。若未提供，文字模型將使用預設值處理。

您也可以將相同的設定直接寫入設定檔。在主設定中，供應商位於 models.providers 下。每個代理（Agent）也可以擁有自己的 models.json；代理是實際接收任務並呼叫模型的助手實例。該檔案位於 ~/.openclaw/agents/ 下對應代理目錄內的 agent/models.json。

如果此 models.json 包含非空的 baseUrl，它將覆蓋主設定中的位址。

檢查安裝

三條指令

openclaw --version
openclaw doctor
gateway status

配置

models.providers

baseUrl 以 /v1 結尾
將 api 設為 completions
至少指定模型 ID

選擇

provider/model

將此參考用於主要模型
優先使用環境變數存放金鑰
以 Gateway 列表作為事實來源

先確認指令可被找到，再輸入位址與模型。模型參考必須包含供應商名稱。

驗證實際任務

進入一個一般的專案目錄並發送一則極短的訊息。將指令中的模型參考替換為您的完整模型 ID：

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "Reply with one word."

--local 在本地執行此代理任務，--model 指定本次執行使用的模型，--timeout 300 將最大等待時間設為 300 秒。

終端機中必須出現實際的模型回應。在 2026-10-09，OpenClaw 2026.9.9 使用此指令成功收到回應。首次呼叫可能需要一到兩分鐘。

如果出現原始錯誤 Request timed out before a response was generated，請增加 --timeout 後再次發送請求。這通常代表等待時間不足，並不一定代表位址錯誤。

短回應成功後，請要求它讀取您指定的本地檔案。接著開啟 OmniProxy 的請求記錄，確認記錄中顯示的來源與模型 ID。僅有版本指令或 doctor 指令的輸出，並不代表模型連線已完全配置完成。

安裝

指令有回應

顯示版本號碼
doctor 回報無阻礙
Gateway 狀態可讀取

任務

已完成小型任務

例如讀取本地檔案
回應非錯誤訊息
模型參考正確

記錄

在 Gateway 中可見

來源為 OpenClaw
模型 ID 相符
金鑰未被加入儲存庫

版本指令產生輸出後，您還必須收到一次實際回應。

常見錯誤

無法找到 openclaw：將 npm 全域 bin 目錄加入 PATH，然後重新開啟終端機。若安裝至指定目錄，請從該目錄的 bin 資料夾執行可執行檔。
node -v 低於 24.16：無需先解除安裝舊版本。檢查安裝指令碼準備的 Node 版本，或依照安裝頁面說明使用 24.16+ 或 26.1+。建議使用 Node 26。
模型未出現：模型必須包含在 models.providers 下的 models 陣列中，且至少需具備相同的 id。僅設定 agents.defaults.models 本身並不會註冊新模型。
400 回應提到開發者角色：當位址主機非 api.openai.com 時，請保持預設值，不要將 supportsDeveloperRole 設為 true。即使設為 true，它仍會被覆蓋。
超時過快：在更改位址前，請將 --timeout 增加至 300 秒以上。
選擇 gpt-6-luna 後工具呼叫失敗：它支援 Chat Completions；僅當 reasoning_effort 為 none 時才支援 Chat Completions 中的函式呼叫。若列表中的 ID 與此不同，請使用列表中顯示的 ID。
無法連線至位址：確認 OmniProxy 正在執行，baseUrl 以 /v1 結尾，且寫入設定的位址可存取。其他私人網路位址必須另外允許。
設定後請求仍發送至其他位址：檢查該代理的 models.json 是否包含不同的 baseUrl。

官方參考

安裝步驟請參閱 OpenClaw 安裝。自訂供應商設定請參閱自訂供應商與設定欄位。範例中使用的模型 ID，請對照 Claude 模型概覽與 GPT-6 Luna。

將所有佔位符替換為您自己的 OmniProxy 配置值。切勿發布真實金鑰。

保存的結果或 HTTP 200 單獨存在並不證明完整的 Agent 相容性。請在 OmniProxy 的呼叫記錄中檢查來源與模型。

官方來源 · OpenClaw ↗