> ## Documentation Index
> Fetch the complete documentation index at: https://claw-tw.jackle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# macOS Dev Setup（macOS 開發環境設定）

# macOS 開發者設定

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

## 前置需求

建置應用程式之前，請確保已安裝下列項目：

1. **Xcode 26.2+**：Swift 開發必備。
2. **Node.js 24 & pnpm**：建議用於 gateway、CLI 和打包腳本。Node 22 LTS，目前為 `22.16+`，仍可相容使用。

## 1. 安裝相依套件

安裝專案範圍的相依套件：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm install
```

## 2. 建置並打包應用程式

若要建置 macOS 應用程式並將其打包至 `dist/OpenClaw.app`，請執行：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
./scripts/package-mac-app.sh
```

如果你沒有 Apple Developer ID 憑證，腳本會自動使用**臨時簽名**（`-`）。

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

> **注意**：臨時簽名的應用程式可能會觸發安全性提示。如果應用程式立即因「Abort trap 6」崩潰，請參閱[疑難排解](#troubleshooting)章節。

## 3. 安裝 CLI

macOS 應用程式需要全域 `openclaw` CLI 安裝來管理背景任務。

**安裝方式（建議）：**

1. 開啟 OpenClaw 應用程式。
2. 前往 **General** 設定標籤。
3. 點選 **「Install CLI」**。

或者，手動安裝：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npm install -g openclaw@<version>
```

## 疑難排解

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

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

**系統相依套件（必要）：**

* **軟體更新中可用的最新 macOS 版本**（Xcode 26.2 SDK 必要）
* **Xcode 26.2**（Swift 6.2 工具鏈）

**檢查：**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
xcodebuild -version
xcrun swift --version
```

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

### 授予權限時應用程式崩潰

如果在嘗試允許**語音辨識**或**麥克風**存取時應用程式崩潰，可能是因為 TCC 快取損毀或簽名不符。

**修復方式：**

1. 重設 TCC 權限：

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   tccutil reset All ai.openclaw.mac.debug
   ```

2. 如果無效，暫時修改 [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 中的 `BUNDLE_ID`，以強制讓 macOS 重新初始化權限。

### Gateway 一直停在「Starting...」

如果 gateway 狀態一直停留在「Starting...」，請檢查是否有殭屍行程佔用連接埠：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway status
openclaw gateway stop

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

如果是手動執行的程式佔用連接埠，請停止該行程（Ctrl+C）。萬不得已時，終止你找到的 PID。