macOS 開發環境設定

​

macOS 開發者設定

從原始碼建置並執行 OpenClaw macOS 應用程式。

​

先決條件

• Xcode 26.2+（Swift 6.2 工具鏈），並使用「Software Update」中可取得的最新版 macOS。
• Node.js 24.15+ 與 pnpm，供閘道、命令列介面和封裝指令碼使用。Node 22.22.3+ 也可運作。

​

1. 安裝相依套件

pnpm install

​

2. 建置並封裝應用程式

./scripts/package-mac-app.sh

輸出至 dist/OpenClaw.app。若沒有 Apple Developer ID 憑證，指令碼會改用臨時簽署。

如需開發執行模式、簽署旗標及 Team ID 疑難排解，請參閱 apps/macos/README.md。 從存放庫根目錄快速進行開發迴圈：scripts/restart-mac.sh（加入 --no-sign 以使用 臨時簽署；使用 --no-sign 時，TCC 權限不會保留）。

臨時簽署的應用程式可能會觸發安全性提示。如果應用程式立即當機並顯示 “Abort trap 6”，請參閱疑難排解。

​

3. 安裝命令列介面與閘道

封裝後的應用程式內嵌標準的 scripts/install-cli.sh 安裝程式。在全新的 設定檔中，於初始設定期間選擇 This Mac；應用程式會先安裝相符的 使用者空間命令列介面和執行階段，再啟動閘道精靈。

若要手動進行開發復原，請自行安裝相符的命令列介面：

npm install -g openclaw@<version>

pnpm add -g openclaw@<version> 和 bun add -g openclaw@<version> 也可 運作。對閘道本身而言，Node 仍是建議使用的執行階段。

​

疑難排解

​

建置失敗：工具鏈或 SDK 不相符

macOS 應用程式建置需要最新版 macOS SDK 和 Swift 6.2 工具鏈 （Xcode 26.2+）。

xcodebuild -version
xcrun swift --version

如果版本不相符，請更新 macOS/Xcode，然後重新執行建置。

​

應用程式在授予權限時當機

如果你嘗試允許 Speech Recognition 或 Microphone 存取權時應用程式當機，原因可能是 TCC 快取損毀或簽章不相符。

1. 重設偵錯套件 ID 的 TCC 權限：

   tccutil reset All ai.openclaw.mac.debug
   

2. 如果仍然失敗，請暫時變更 scripts/package-mac-app.sh 中的 BUNDLE_ID，以強制 macOS 建立全新的權限狀態。

​

閘道無限期顯示 “Starting…”

檢查是否有殭屍程序占用連接埠：

openclaw gateway status
openclaw gateway stop

# 如果你未使用 LaunchAgent（開發模式／手動執行），請找出監聽程序：
lsof -nP -iTCP:18789 -sTCP:LISTEN

如果手動執行的程序占用連接埠，請將其停止（Ctrl+C）；或者，作為最後手段，終止上方找到的 PID。

​

相關內容

• macOS 應用程式
• 安裝概覽