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。安裝程式已簽章，其中包含設定、系統匣狀態、聊天和 node 模式。
macOS：從 OpenClaw 的 GitHub releases 下載 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: 從 OmniProxy 目前的模型清單完整複製

baseUrl 是 OpenClaw 傳送模型要求的位址，必須以 /v1 結尾。連接 OmniProxy 時，api 使用 openai-completions。只有在這個模型確實透過 /v1/responses 運作時，才改成 openai-responses。

Model ID 是模型在清單中的完整識別碼。請依照清單原樣複製，如果其中有斜線，也必須保留。以下兩個名稱只是 2026-10-09 供應商文件中的對照；如果清單中沒有，請勿使用：claude-sonnet-5-5、gpt-6-luna。

即使閘道不檢查金鑰，apiKey 仍必須填入內容，可以使用一串只在這台電腦上使用的預留字元。請勿將真實金鑰提交至儲存庫。

填寫工具設定

Provider 可以理解為 OpenClaw 用來尋找模型服務的一組連線設定。這裡將 Provider 命名為 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

這個指令會將 Provider 和模型清單寫入設定。指令成功後，不必重新啟動 Gateway。

接著指定預設模型。模型參照由 omniproxy/ 和模型 ID 組成，ID 中原有的斜線全部都要保留。如果模型清單中的 ID 比下方的簡短名稱更長，請使用清單中的完整內容：

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

reasoning、input、cost、contextWindow、maxTokens 都可以省略。未填寫時，文字模型會依照預設方式處理。

同一組設定也可以直接寫入設定檔。主要設定中的 Provider 位於 models.providers。每個 agent 也可以有自己的 models.json；agent 是實際接收工作並呼叫模型的助手執行個體。檔案位置是 ~/.openclaw/agents/ 下方對應 agent 目錄中的 agent/models.json。

如果這份 models.json 設定了非空白的 baseUrl，它會覆寫主要設定中的位址。

檢查安裝

三行命令

openclaw --version
openclaw doctor
gateway status

設定

models.providers

baseUrl 以 /v1 結尾
api 使用 completions
模型至少填寫 id

選用

provider/模型

primary 使用這個引用
金鑰優先使用環境變數
清單以閘道為準

先確認系統找得到指令，再寫入位址與模型。模型參照必須包含 Provider 名稱。

驗證實際工作

進入一般專案目錄，傳送一則很短的訊息。將指令中的模型參照替換為你的完整 Model ID：

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "請用一個詞回覆。"

--local 表示在本機執行這次 agent 工作，--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 狀態可讀取

任務

它完成了一件小事

例如讀取一個本機檔案
回覆不是錯誤訊息
模型引用填寫正確

記錄

閘道看得到

來源是 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，並提到 developer 角色：如果位址的主機不是 api.openai.com，請保留預設設定，不要將 supportsDeveloperRole 設為 true。即使設為 true，仍會被覆寫。
很快就逾時：將 --timeout 提高至 300 秒以上，先不要變更位址。
選擇 gpt-6-luna，但工具呼叫失敗：它支援 Chat Completions；在 Chat Completions 中，只有 reasoning_effort 為 none 時才支援函式呼叫。如果清單中的 ID 與此不同，請以清單為準。
無法連上位址：確認 OmniProxy 正在執行、baseUrl 以 /v1 結尾，並確認寫入設定的位址可以存取。其他內部網路位址需要另外放行。
完成設定後仍連至其他位址：檢查該 agent 的 models.json 是否填寫了另一個 baseUrl。

官方參考資料

安裝步驟請參閱 OpenClaw install。自訂 Provider 的設定方式請參閱 Custom providers 和設定欄位。範例中使用的模型 ID 可對照 Claude 模型總覽和 GPT-6 Luna。

用你自己的 OmniProxy 設定取代每個佔位符。不要發布真實金鑰。

儲存成功或 HTTP 200 不單獨代表完整 Agent 相容性。請在 OmniProxy 呼叫記錄中確認來源和模型。

官方來源 · OpenClaw ↗