Agentic Research
中文
English Edition/Tools

This article is not yet available in English. You are reading the Traditional Chinese original. The English edition will appear here once it is translated.

Browse articles that do have an English edition

OpenClaw 安裝教學：一條指令裝好屬於你的 AI Agent Gateway

2026/09/3016 min readBryan Chan閱讀中文原文
TopicsOpenClaw安裝教學AI AgentCLI

讀完這篇你會得到：一個在你自己機器上常駐執行的 OpenClaw Gateway、一個打得開的網頁控制台（Control UI），以及第一則獲得 AI 回覆的訊息。約 10 到 15 分鐘。

OpenClaw 是開放原始碼的自架 Agent 框架：一個 Gateway 程序把 Telegram、WhatsApp、Discord、Slack、飛書、iMessage 等聊天軟體接到會使用工具的 AI Agent（代理） 上，能力用 skills 擴展，模型接你自己選的供應商。它跑在你的機器上、資料留在本地，相對地，安全責任也在你自己身上（文末會講）。

Harness 的運行流程流程圖：使用者請求進入 harness 後，先組裝上下文（系統提示、工具清單、記憶），呼叫 LLM 做一次 forward pass，解析輸出。若輸出是純文字就直接收斂成最終答案；若是工具呼叫，則先過權限閘門（放行、詢問或拒絕），在沙箱執行，再把觀察結果回灌到上下文，重新呼叫模型。這個迴圈會一直轉到模型不再要求工具為止。HARNESS（執行環境）工具呼叫純文字回灌使用者請求一句話或一段任務組裝上下文系統提示 + 工具清單 + 記憶呼叫 LLM一次 forward pass解析輸出純文字？還是工具呼叫？權限閘門放行 / 詢問 / 拒絕沙箱執行在受限環境跑工具觀察回灌結果併回上下文最終答案不再要求工具，收斂
1/8使用者請求
任務用自然語言進來。harness 要把它變成模型能處理的東西。
第 1 步，共 8 步 使用者請求
圖：你即將裝好的東西，本質上就是這個循環 — LLM 思考、透過 harness 調用工具、結果回灌，直到任務完成。

適用平台

  • 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（執行環境／框架）。

步驟

安裝 OpenClaw 的六個步驟打開終端機確認 Node 版本（需要 24.16+ 或 26.1+，官方推薦 26）、執行官方安裝腳本、完成首次設定精靈（Quick start 會沿用既有的 Claude Code 或 Codex 登入）、把 Gateway 裝成背景服務、用 gateway status 驗證它在 port 18789 監聽、最後打開控制台發第一則訊息。Terminal — openclaw終端機$ node --version # 需要 24.16+ 或 26.1+$ curl -fsSL https://openclaw.ai/install.sh | bash首次設定精靈Quick start：沿用既有的Claude Code / Codex 登入事後補設定：openclaw configureGateway 與控制台$ openclaw gateway install$ openclaw gateway status # port 18789$ openclaw dashboard版本不夠會在後面才出錯，先確認最省事示意圖，非截圖。只畫與當前步驟相關的區域，實際介面有更多選項。
1/6確認 Node 版本
第 1 步，共 6 步 確認 Node 版本
安裝 OpenClaw 的終端機流程示意（六步）

步驟一：打開終端機，確認 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）。

怎麼確認你裝對了

四項檢查全過才算數：

  1. openclaw --version 有版本號輸出；
  2. openclaw doctor 無重大錯誤；
  3. openclaw gateway status 顯示正在監聽 18789 埠；
  4. 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 allowScriptsnpm 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，按症狀查表用官方疑難排解

下一步

More in Tools