macOS 開發者設定

本指南涵蓋從原始碼建構與執行 OpenClaw macOS 應用程式所需的步驟。

前置需求

建構應用程式前，請確保已安裝以下工具：

1. Xcode 26.2+：Swift 開發必備。
2. Node.js 24 & pnpm：Gateway、CLI 及打包腳本建議使用。Node 22 LTS（目前為 22.16+）仍可相容使用。

1. 安裝相依套件

安裝專案級相依套件：

pnpm install

2. 建構與打包應用程式

建構 macOS 應用程式並打包為 dist/OpenClaw.app：

./scripts/package-mac-app.sh

若你沒有 Apple Developer ID 憑證，腳本會自動使用 ad-hoc 簽章（-）。

開發執行模式、簽章旗標與 Team ID 疑難排解請參閱 macOS 應用程式 README： https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

注意：Ad-hoc 簽章的應用程式可能觸發安全性提示。若應用程式啟動後立即以「Abort trap 6」當機，請參閱疑難排解章節。

3. 安裝 CLI

macOS 應用程式預期有全域安裝的 openclaw CLI 來管理背景工作。

安裝方式（建議）：

1. 開啟 OpenClaw 應用程式。
2. 前往 General 設定分頁。
3. 點選 “Install CLI”。

或者手動安裝：

npm install -g openclaw@<version>

疑難排解

建構失敗：工具鏈或 SDK 版本不符

macOS 應用程式建構需要最新的 macOS SDK 與 Swift 6.2 工具鏈。

系統相依（必要）：

• 軟體更新中最新可用的 macOS 版本（Xcode 26.2 SDK 所需）
• Xcode 26.2（Swift 6.2 工具鏈）

檢查方式：

xcodebuild -version
xcrun swift --version

若版本不符，請更新 macOS/Xcode 並重新執行建構。

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

若應用程式在你嘗試允許語音辨識或麥克風存取時當機，可能是 TCC 快取損壞或簽章不符。

修復方式：

1. 重設 TCC 權限：

   tccutil reset All ai.openclaw.mac.debug

2. 若仍無效，暫時修改 scripts/package-mac-app.sh 中的 BUNDLE_ID，強制 macOS 以「全新狀態」對待該應用程式。

Gateway 持續顯示「Starting…」

若 Gateway 狀態停在「Starting…」，檢查是否有殭屍程序佔用連接埠：

openclaw gateway status
openclaw gateway stop

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

若是手動執行的程序佔用連接埠，停止該程序（Ctrl+C）。最後手段是 kill 你找到的 PID。