Skip to main content

​
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 憑證，腳本會自動使用臨時簽名（-）。 開發執行模式、簽名旗標和 Team ID 疑難排解，請參閱 macOS 應用程式 README： https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md
注意：臨時簽名的應用程式可能會觸發安全性提示。如果應用程式立即因「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）。萬不得已時，終止你找到的 PID。