OpenClaw macOS 開發環境建置：從原始碼編譯與安裝指南

在 macOS 上設定開發環境有時挺麻煩的，特別是當你得處理特定的 SDK 版本或簽署問題時。如果你想從原始碼編譯並執行 OpenClaw，這篇指南會帶你走過必要的步驟，幫你搞定環境設定。

這份指南涵蓋了從原始碼建置與執行 OpenClaw macOS 應用程式的所有必要步驟。

前置作業

在建置 App 之前，請確保你已經安裝了以下工具：

1. Xcode 26.2+：Swift 開發必備。
2. Node.js 24 & pnpm：建議用於 Gateway、CLI 和打包腳本。目前也支援 Node 22 LTS（22.14+）以維持相容性。

1. 安裝依賴項目

安裝專案整體的依賴項目：

pnpm install

2. 建置與打包應用程式

若要建置 macOS App 並將其打包至 dist/OpenClaw.app，請執行：

./scripts/package-mac-app.sh

如果你沒有 Apple Developer ID 憑證，腳本會自動使用 ad-hoc 簽署 (-)。

關於開發執行模式、簽署旗標以及 Team ID 的疑難排解，請參考 macOS App 的 README： https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

注意：經由 Ad-hoc 簽署的 App 可能會觸發安全性提示。如果 App 啟動後立即崩潰並顯示 “Abort trap 6”，請參考 疑難排解 章節。

3. 安裝 CLI

macOS App 需要全域安裝 openclaw CLI 來管理背景任務。

安裝方式（推薦）：

1. 打開 OpenClaw App。
2. 前往 General 設定分頁。
3. 點擊 “Install CLI”。

或者，你也可以手動安裝：

npm install -g openclaw@<version>

疑難排解

建置失敗：Toolchain 或 SDK 版本不符

建置 macOS App 需要最新的 macOS SDK 以及 Swift 6.2 toolchain。

系統依賴項目（必須）：

• 軟體更新中可用的最新 macOS 版本（Xcode 26.2 SDK 要求）
• Xcode 26.2（Swift 6.2 toolchain）

檢查方式：

xcodebuild -version
xcrun swift --version

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

授予權限時 App 崩潰

當你嘗試允許 Speech Recognition（語音辨識）或 Microphone（麥克風）存取權限時，如果 App 發生崩潰，可能是因為 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

# If you're not using a LaunchAgent (dev mode / manual runs), find the listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN

如果是手動執行的程序佔用了連接埠，請停止該程序（Ctrl+C）。最後的手段是直接刪除（kill）上面找到的 PID。

下一步

• 了解 OpenClaw 架構
• CLI 指令參考

想要更快速的協助嗎？試試我們的 AI Setup Assistant！