讀完這篇你會得到：一個在你自己機器上常駐執行的 OpenClaw Gateway、一個打得開的網頁控制台（Control UI），以及第一則獲得 AI 回覆的訊息。約 10 到 15 分鐘。
OpenClaw 是開放原始碼的自架 Agent 框架：一個 Gateway 程序把 Telegram、WhatsApp、Discord、Slack、飛書、iMessage 等聊天軟體接到會使用工具的 AI Agent（代理） 上，能力用 skills 擴展，模型接你自己選的供應商。它跑在你的機器上、資料留在本地，相對地，安全責任也在你自己身上（文末會講）。
適用平台
- macOS、Linux、Windows 都支援。
- Windows 有三條路：原生 Windows Hub 桌面應用（簽章安裝程式，最省事的圖形介面路線，提供 x64 與 ARM64 安裝包，見 openclaw-windows-node releases）、PowerShell 安裝腳本、WSL2 內的 Gateway（見官方 Windows 平台頁）。
- macOS 另有選單列桌面應用：從 OpenClaw GitHub releases 下載
.dmg，安裝後啟動 OpenClaw.app。兩種桌面應用首次啟動都能直接幫你裝好本地 Gateway，或連到既有的遠端 Gateway。 - 本篇主線是官方推薦的命令列安裝腳本，三平台通用、最容易排查。
前置需求
- Node.js 24.16+ 或 26.1+（官方推薦 Node 26）。沒有也沒關係：安裝腳本偵測不到 Node 時會自動安裝（macOS 裝 Node 26、Linux 裝 Node 24 LTS）。已有 Node 的先跑
node --version確認。 - 一個模型入口，二選一：這台機器已登入的 Claude Code 或 Codex CLI（設定精靈會自動偵測並重用），或任一模型供應商的 API Key。金鑰只貼在精靈提示的位置：不要貼進任何聊天視窗、不要提交進 Git 倉庫，文件範例中的金鑰一律長得像
sk-xxxxxxxx這種佔位符。 - 會打開Terminal（終端機）：macOS 用「終端機」，Windows 用 PowerShell 或 WSL2。本篇指令都在CLI（命令列介面）裡執行。
- 模型調用按你所選供應商以 Token（詞元） 計費；OpenClaw 本身是開源軟體，不收費用。
- 概念預習（可跳過）：Tool Call（工具呼叫）、Harness（執行環境／框架）。
步驟
步驟一：打開終端機，確認 Node 版本
node --version
預期輸出：v24.16 以上或 v26.x 的版本號。若顯示 command not found（Windows PowerShell 是「無法將 node 項識別為 cmdlet」之類），不用處理 — 下一步的安裝腳本會自動裝 Node。
步驟二：執行官方安裝腳本
macOS / Linux / WSL2：
curl -fsSL https://openclaw.ai/install.sh | bash
Windows（PowerShell）：
iwr -useb https://openclaw.ai/install.ps1 | iex
預期輸出：腳本偵測作業系統、需要時先安裝 Node、安裝 OpenClaw，完成後自動進入首次設定精靈（onboarding）。想先裝好、之後再設定：POSIX 在結尾加 bash -s -- --no-onboard，Windows 用 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard。全部旗標見官方安裝程式內部機制。
步驟三：完成首次設定精靈
精靈給你兩條路：
- Quick start：重用偵測到的 Claude Code／Codex 登入或 API key — 它會用一次真實的模型調用驗證可用、儲存設定，然後打開網頁控制台。
- Custom setup：完整引導流程，逐項設定供應商與選項。之後想補設定用
openclaw configure；偏好舊式逐步精靈用openclaw onboard --classic。
預期輸出：瀏覽器自動打開 Control UI（網頁控制台）；同時 Gateway 程序在目前終端機前台執行 — 這個視窗關掉或按 Ctrl+C，Gateway 就停了。設定已儲存，下一步把它轉成背景服務。若偵測不到可用的模型入口，精靈會轉入手動設定供應商的流程。
步驟四：把 Gateway 裝成背景服務
在執行 Gateway 的終端機按 Ctrl+C 停止前台程序，然後：
openclaw gateway install
預期輸出：指令回報服務已安裝 — macOS 裝 LaunchAgent，Linux／WSL2 裝 systemd 使用者服務，原生 Windows 建排程工作（建立被拒時，退回為啟動資料夾的登入項）。設定在「停止前台、安裝服務」的過程中保持不變。
步驟五：驗證 Gateway 正在執行
openclaw gateway status
openclaw --version
openclaw doctor
預期輸出：gateway status 顯示 Gateway 正在監聽 18789 埠；--version 印出版本號；doctor 檢查設定問題、沒有重大錯誤。
步驟六：打開控制台，發第一則訊息
openclaw dashboard
預期輸出：瀏覽器打開 Control UI。在聊天框輸入任意訊息（例如「用一句話介紹你自己」），收到 AI 回覆 — 至此 OpenClaw 安裝完成，你的 Agent 已經在自己機器上常駐。想改從手機跟它講話，最快設定的頻道是 Telegram（只需要一個 bot token）。
怎麼確認你裝對了
四項檢查全過才算數：
openclaw --version有版本號輸出；openclaw doctor無重大錯誤；openclaw gateway status顯示正在監聽 18789 埠；- Control UI 發訊息能收到回覆。
設定與狀態預設放在家目錄的 ~/.openclaw/，可用 環境變數與 .env OPENCLAW_HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH 調整路徑（見官方環境變數文件）。
兩個日後常用的入口：直接跑 openclaw 會打開終端機介面（TUI），在Shell（殼層）裡跟 Agent 對話；openclaw dashboard 則隨時重新打開網頁控制台。Gateway 裝成服務之後，啟動就交給系統託管（官方稱為 managed startup），不必每次手動拉起 — 這也是「自架」與雲端訂閱制 Agent 產品最大的差別：程序、資料、金鑰都在你的機器上，更新與備份（官方 Backups 文件）也由你負責。
只想先試試、不想安裝：npx openclaw@latest 免全域安裝直接跑，Gateway 前台執行在該終端機，Ctrl+C 結束。
安全一句話：你的 Gateway 能執行工具、讀檔案、接聊天頻道。對任何人開放之前，先讀官方安全指南與配對機制 — 誰能傳訊息給你的 Agent，必須由你控制。相關概念：Sandbox（沙箱）、Prompt Injection（提示詞注入），以及本站的 AI 安全與紅隊測試：Prompt Injection、Jailbreak 防禦。
常見錯誤與修法
| 症狀 | 原因 | 修法 |
|---|---|---|
openclaw: command not found | 幾乎都是 PATH 問題：npm 全域 bin 目錄不在 shell 的 PATH 與路徑 裡 | 依序跑 node -v、npm prefix -g、echo "$PATH"，確認上一條輸出的 bin 目錄在 PATH 中；完整修法見官方 Node 疑難排解 |
npm 安裝時腳本被擋，提示 blocked because they are not covered by allowScripts | npm 12 起預設封鎖未經核准的套件生命週期腳本 | 用官方指令 npm install -g openclaw@latest --allow-scripts=openclaw，接著 openclaw onboard --install-daemon；npm 11.15 以前不加這個參數 |
| 網路上舊教學的指令跑不通 | 那些指令不在官方現行文件裡 | 以 docs.openclaw.ai/install 為準：設定精靈是 openclaw onboard、服務管理是 openclaw gateway，指令全表見 CLI 參考 |
| 設定卡住、不知道哪裡壞了 | 出錯點可能在模型、頻道或設定檔任何一層 | openclaw triage：跑唯讀健康檢查、產生去敏診斷報告，可交給機器上偵測到的 coding Agent 接手分析；想自己讀報告用 openclaw doctor，按症狀查表用官方疑難排解 |
下一步
- 接上第一個聊天頻道：Telegram 最快，飛書、WhatsApp、Discord、Slack 等頻道見官方 Channels 文件
- 技能生態：官方 ClawHub 與本站 OpenClaw 技能分類矩陣
- 拿它做實際工作：OpenClaw 生產力革命：22 個自動化方案重塑日常工作流（22 個生產力自動化方案）、OpenClaw 真實用例大全：30.9k Stars 社區寶庫完全解析（社群真實用例大全）
- 想比較 Nous Research 的開源 Agent：Hermes Agent 安裝教學：桌面版與命令列兩條路徑 — OpenClaw 官方甚至提供從 Hermes 遷移與兩者關係說明
- 桌面應用路線：macOS 選單列應用、Windows Hub