最近本地AI Agent框架真的太火了，而OpenClaw絕對是其中的“熱門選手”——很多人想安裝它，核心就是看中它能在本地運行AI代理，不用依賴云端，不管是開發者用來自動化AI工作流，還是普通用戶想實現腳本自動化、文件批量處理、快速生成代碼，它都能搞定。

但問題來了，很多人興致勃勃去裝OpenClaw，卻頻頻翻車：要么Node環境不兼容，安裝到一半報錯；要么Gateway服務啟動失敗，死活打不開；要么CLI顯示安裝成功，輸入命令卻提示“不存在”；最氣的是，全程沒報錯，最后卻打不開Web管理界面，白忙活一場。

今天這篇教程，就從零基礎開始，一步步教你在macOS上安裝OpenClaw，把大家常踩的坑全避開，不管你是新手還是剛接觸終端的小白，跟著做，一次就能安裝成功，輕松用上本地AI自動化工具！

先跟大家簡單說下OpenClaw的優勢：它能在本地運行，不用上傳數據到云端，隱私性拉滿，而且支持CLI命令行和Web界面兩種操作方式，自動化腳本、文件處理、代碼生成這些需求，都能輕松滿足，這也是為什么越來越多人想安裝它的原因。

一、安裝前準備（重中之重，避開80%的坑）

很多人安裝失敗，不是步驟錯了，而是前期準備沒做好。在裝OpenClaw之前，一定要先把運行環境準備到位，不然后續肯定報錯，大家跟著下面的步驟來，一步都別省。

1. 確認macOS系統版本

OpenClaw對macOS系統有一定要求，老系統容易出現兼容性問題，建議大家確認一下自己的系統版本：

? 推薦系統：macOS 12 Monterey 及以上版本

? 支持芯片：Apple Silicon（M1/M2/M3）和Intel芯片都可以，沒有限制

這里提醒一句：越新的系統，對Node環境和本地網絡權限的支持越好，安裝成功率也越高，如果你的系統版本太低，建議先升級系統，再進行后續操作。

2. 安裝Node.js環境（核心依賴，必須裝）

OpenClaw的CLI工具是基于Node.js運行的，沒有Node環境，根本裝不了，這是最基礎也是最容易出錯的一步。

? 推薦Node版本：Node 18 或 Node 20（親測這兩個版本最穩定，不會出現兼容性問題）

先檢查一下你的電腦有沒有裝Node，打開終端（Launchpad里搜“終端”就能找到），輸入下面這行命令，按回車：

node -v

如果終端顯示類似“v18.17.0”或“v20.9.0”的版本號，說明已經裝了Node，直接跳過安裝步驟，確認版本是18或20即可；如果顯示“command not found”，說明沒裝，繼續往下走。

最方便的安裝方式是用Homebrew（Mac自帶的包管理器，沒有的話先裝Homebrew，網上搜“Mac安裝Homebrew”，一步就能搞定），輸入命令：

brew install node

安裝完成后，再輸入下面兩個命令，確認安裝成功：

node -vnpm -v

只要兩個命令都能顯示版本號，就說明Node環境裝好了。

3. 推薦安裝Node版本管理器（避免版本沖突）

這一步不是必須的，但非常推薦！很多人電腦里可能裝了多個Node版本，容易和OpenClaw需要的版本沖突，導致安裝失敗或運行報錯。

推薦用這兩個版本管理器，二選一即可：nvm 或 nodenv，這里以nvm為例，教大家安裝（新手也能輕松操作）：

第一步：安裝nvm，終端輸入命令：

brew install nvm

第二步：安裝Node 20（最穩定版本），輸入命令：

nvm install 20

第三步：切換到Node 20版本，輸入命令：

nvm use 20

這樣一來，后續運行OpenClaw就不會出現Node版本沖突的問題，大大降低報錯概率。

二、安裝OpenClaw CLI（核心步驟，一鍵搞定）

環境準備好后，就可以正式安裝OpenClaw了，官方提供了一鍵安裝腳本，不用手動操作復雜步驟，新手也能輕松上手。

打開終端，直接復制粘貼下面這行命令，按回車即可（建議直接復制，避免手動輸入出錯）：

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

執行命令后，系統會自動開始安裝，不用管它，等待幾分鐘就好。這個腳本會自動完成以下操作，不用你手動干預：

• 安裝OpenClaw CLI核心工具

• 自動創建用戶配置目錄

• 初始化Gateway后臺服務

• 寫入shell自動補全（后續輸入命令更方便）

當終端顯示“OpenClaw installed successfully”（OpenClaw安裝成功），就說明CLI已經裝好了，下一步就是驗證安裝是否成功。

三、驗證安裝是否成功（必做，避免白忙活）

安裝完成后，別著急啟動服務，先驗證一下CLI是否能正常使用，避免后續啟動失敗又要回頭排查。

終端輸入下面這行命令，檢查版本號：

openclaw --version

如果終端返回類似“OpenClaw CLI v1.x.x”的版本號，說明安裝成功了；如果提示“command not found”，別慌，后面會講解決方法。

另外，也可以查看OpenClaw的幫助文檔，熟悉一下基本命令，輸入：

openclaw help

終端會顯示所有可用的命令，不用記，后續用到再查就好。

四、啟動OpenClaw Gateway服務（后臺核心，必須啟動）

OpenClaw在Mac上是通過Gateway服務運行后臺AI Agent的，CLI裝好了只是第一步，必須啟動Gateway服務，才能正常使用所有功能。

終端輸入啟動命令：

openclaw gateway start

這個命令會自動完成3件事，不用手動操作：

• 啟動本地API服務（OpenClaw運行的核心）

• 初始化agent runtime（AI代理運行環境）

• 創建macOS后臺服務（保證服務能穩定運行）

如果啟動成功，終端通常會顯示“Gateway started at http://localhost:3333”，說明Gateway服務已經正常啟動了，下一步就是訪問Web管理界面。

五、訪問Web管理界面（可視化操作，新手友好）

OpenClaw默認會啟動一個本地Web控制臺，不用記復雜的命令，通過瀏覽器就能操作，非常適合新手。

打開你電腦上的任意瀏覽器（Safari、Chrome都可以），在地址欄輸入下面的地址，按回車：

http://localhost:3333

進入Web控制臺后，你就可以輕松操作這些功能了：

• 創建屬于自己的AI Agent（根據需求設置自動化任務）

• 執行自動化任務（比如批量處理文件、生成代碼）

• 管理workspace（存放任務數據、日志）

• 查看運行日志（遇到問題可以在這里排查）

如果打開頁面顯示“無法訪問”，別慌，先檢查Gateway服務是否在運行，輸入命令：

openclaw gateway status

如果顯示“running”，說明服務在運行，刷新瀏覽器即可；如果顯示“stopped”，重新輸入啟動命令即可。

六、OpenClaw默認目錄結構（了解即可，方便后續維護）

安裝完成后，OpenClaw會在你的用戶目錄下自動創建一個配置目錄，了解這些目錄的作用，后續遇到問題（比如日志排查、配置修改）會更方便。

主要目錄：~/.openclaw（這個目錄藏在用戶目錄下，按“command+shift+.”可以顯示隱藏文件）

這個目錄里面包含4個核心文件夾，作用給大家整理清楚了，一看就懂：

不用特意去修改這些目錄，了解它們的作用，后續維護時能快速找到對應文件就好。

七、將Gateway設置為開機啟動（可選，懶人福音）

如果經常用OpenClaw，每次開機都要手動啟動Gateway服務，會比較麻煩，建議把它設置為開機自動啟動，這樣每次登錄Mac，Gateway就會自動運行，不用再手動操作。

終端輸入下面這行命令，啟用開機自啟動：

openclaw gateway install

啟用成功后，系統會自動創建一個plist文件（自啟動配置文件），路徑是：~/Library/LaunchAgents/ai.openclaw.gateway.plist

這樣一來，每次你登錄Mac，Gateway服務就會自動啟動，打開瀏覽器輸入http://localhost:3333，就能直接使用OpenClaw了，非常方便。

八、創建第一個Agent（實操演示，快速上手）

安裝、啟動都完成后，我們來實操一下，創建第一個AI Agent，感受一下OpenClaw的自動化功能，新手也能輕松操作。

方法一：直接運行一個簡單任務，終端輸入：

openclaw run "summarize this folder"

這個命令會讓AI Agent自動總結當前文件夾的內容，執行完成后，終端會顯示總結結果。

方法二：進入交互模式，和AI Agent對話，輸入：

openclaw chat

進入交互模式后，你可以輸入任意任務，比如“Analyze files in workspace”（分析工作空間里的文件），OpenClaw會自動執行對應的流程，完成后給你反饋。

大家可以多嘗試幾個命令，熟悉一下操作，很快就能上手。

九、常見安裝問題（踩坑必看，快速解決）

就算跟著步驟來，也可能會遇到一些小問題，這里整理了4個最常見的報錯，給出具體的解決方法，不用再到處查教程，省時又省心。

1. 報錯：openclaw 命令不存在

最常見的問題，原因通常是安裝完成后，PATH環境變量沒有刷新，終端識別不到openclaw命令。

解決方法：終端輸入下面這行命令，刷新PATH：

source ~/.zshrc

如果你的終端用的是bash，就輸入：source ~/.bashrc，刷新后，再輸入openclaw --version，就能識別到了；如果還是不行，重新打開終端即可。

2. 報錯：Gateway 無法啟動

大概率是默認端口3333被其他程序占用了，導致Gateway啟動失敗。

解決方法：第一步，檢查3333端口是否被占用，輸入命令：

lsof -i :3333

如果顯示有程序占用，要么關閉占用端口的程序，要么修改OpenClaw的端口，修改方法：打開~/.openclaw/config文件，修改端口號即可。

3. 報錯：Node 版本不兼容

如果你的Node版本不是18或20，就可能出現CLI運行報錯、Gateway啟動失敗的問題。

解決方法：如果安裝了nvm，輸入命令切換到Node 20版本：

nvm use 20

切換完成后，重新啟動Gateway服務，就能正常運行了。

4. 報錯：macOS 安全權限問題

如果Gateway無法訪問電腦里的文件，比如無法分析文件夾、生成文件失敗，大概率是終端沒有磁盤訪問權限。

解決方法：打開Mac的“系統設置” → 找到“隱私與安全” → 點擊“完全磁盤訪問” → 點擊左下角的“+”，添加“終端”，勾選終端的訪問權限，重新啟動Gateway服務即可。

十、升級 OpenClaw（后續更新，簡單操作）

OpenClaw會不斷更新新功能、修復bug，后續如果想升級到最新版本，有兩種簡單方法，二選一即可。

方法一：通過npm升級，終端輸入：

npm update -g openclaw

方法二：重新運行官方安裝腳本，自動更新到最新版本，輸入：

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

兩種方法都很簡單，升級完成后，輸入openclaw --version，就能看到最新的版本號了。

? 總結（重點劃重點，記不住就看這里）

其實在macOS上安裝OpenClaw，一點都不復雜，核心就是5個步驟，抓好這5步，就能一次安裝成功，避開所有坑：

1. 準備環境：安裝Node 18/20，推薦裝nvm避免版本沖突；

2. 安裝CLI：運行官方一鍵安裝腳本，等待安裝成功；

3. 啟動服務：輸入命令啟動Gateway后臺服務；

4. 訪問Web：瀏覽器打開http://localhost:3333，進入控制臺；

5. 實操上手：創建第一個AI Agent，體驗自動化功能。

只要跟著上面的步驟來，不管你是新手還是小白，都能輕松在Mac上安裝并使用OpenClaw，再也不用為安裝報錯、啟動失敗而煩惱。

如果操作過程中遇到其他問題，評論區留言，我會及時回復大家，幫大家順利搞定安裝！