名称： clawdbot-macos-build
描述： 从源码构建 Clawdbot macOS 菜单栏应用。当你需要安装 Clawdbot.app 伴侣应用（用于菜单栏状态显示、权限管理以及访问 Mac 硬件，如摄像头/屏幕录制）时使用。自动处理依赖安装、UI 构建、Swift 编译、代码签名和应用打包。

Clawdbot macOS 应用构建

macOS 伴侣应用提供菜单栏状态显示、原生通知以及 Mac 硬件（摄像头、屏幕录制、系统命令）访问功能。本指南介绍如何从源码构建此应用。

前提条件

• macOS (10.14 或更高版本)
• Xcode 15+ 及命令行工具
• Node.js >= 22
• pnpm 包管理器
• 30 GB 以上可用磁盘空间（用于 Swift 构建产物）
• 网络连接（依赖包较大）

快速构建

# 克隆仓库
cd /tmp && rm -rf clawdbot-build && git clone https://github.com/clawdbot/clawdbot.git clawdbot-build

# 安装依赖并构建
cd /tmp/clawdbot-build
pnpm install
pnpm ui:build

# 接受 Xcode 许可协议（一次性操作）
sudo xcodebuild -license accept

# 使用临时签名构建 macOS 应用
ALLOW_ADHOC_SIGNING=1 bash scripts/package-mac-app.sh

# 安装到 /Applications 目录
cp -r dist/Clawdbot.app /Applications/Clawdbot.app

# 启动应用
open /Applications/Clawdbot.app

构建步骤详解

1. 克隆仓库

从 GitHub 克隆最新的 Clawdbot 源码，其中包含位于 apps/macos/ 目录下的 macOS 应用源码。

2. 安装依赖 (pnpm install)

为整个工作区安装 Node.js 依赖（约 1 分钟）。某些扩展中关于缺少二进制文件的警告可忽略。

3. 构建 UI (pnpm ui:build)

编译控制界面（Vite → TypeScript/React）。输出至 dist/control-ui/ 目录，耗时约 30 秒。

4. 接受 Xcode 许可协议

每次 Xcode 更新后需执行一次。若 Swift 构建过程中出现“许可协议未同意”错误，请运行：

sudo xcodebuild -license accept

5. 打包 macOS 应用 (scripts/package-mac-app.sh)

运行完整的 Swift 构建流程：
- 获取 Swift 包依赖（SwiftUI 库等）
- 为你的架构编译 macOS 应用（M1+ 为 arm64，Intel 为 x86_64）
- 打包资源（模型目录、本地化文件等）
- 对应用进行代码签名

签名选项：
- 临时签名（最快）：ALLOW_ADHOC_SIGNING=1 — 适用于本地测试，应用无法公证分发
- 开发者 ID 签名（生产环境）：若拥有签名证书，请设置 SIGN_IDENTITY="Developer ID Application: <name>"

此步骤根据你的 Mac 性能，耗时 10-20 分钟。

6. 安装到 /Applications 目录

将构建好的应用复制到系统应用程序文件夹，使其像其他 macOS 应用一样运行。

7. 启动应用

打开应用。首次运行时，你会看到权限请求提示（通知、辅助功能、屏幕录制等）— 请全部批准以获得完整功能。

故障排除

"Invalid tools version"

Swift 构建需要 6.2+ 版本。请更新 Xcode：

softwareupdate -i -a

"License not agreed"

sudo xcodebuild -license accept

"No signing identity found"

本地构建请使用临时签名：

ALLOW_ADHOC_SIGNING=1 bash scripts/package-mac-app.sh

Swift 编译卡顿或极慢

• 确保 Xcode 已完全更新：xcode-select --install 或通过 App Store 更新
• 检查磁盘空间：df -h（需约 30 GB 可用空间）
• 关闭其他应用以释放内存

构建后应用无法启动

检查签名是否正常：

codesign -v /Applications/Clawdbot.app

若签名失败，请使用 ALLOW_ADHOC_SIGNING=1 重新构建。

应用功能说明

• 菜单栏状态 — 查看网关健康状况并接收通知
• 权限管理 — 负责处理通知、辅助功能、屏幕录制、麦克风等 TCC 提示
• 本地/远程模式：
• 本地模式： 网关在你的 Mac 上运行；应用管理 launchd 服务
• 远程模式： 应用通过 SSH/Tailscale 连接到另一台机器（VPS、家庭服务器）上的网关；即使 Mac 休眠也能保持可访问性
• Mac 硬件访问： 摄像头、屏幕录制、画布、语音唤醒词
• 深度链接： 通过 clawdbot:// URL 方案触发代理请求

详见官方文档：https://docs.clawd.bot/platforms/macos

为分发而构建

如需进行生产分发，你需要：
- Apple 开发者 ID 证书（付费）
- 公证凭证
- 参考：https://docs.clawd.bot/platforms/mac/release

个人使用情况下，临时签名即可满足需求。

后续步骤

应用启动后：
1. 完成权限检查清单（TCC 提示）
2. 选择本地或远程模式
3. 若为本地模式：确保网关正在运行（clawdbot gateway status）
4. 打开 Clawdbot.app 菜单栏图标进行配置

之后，你可以在终端中管理网关：

clawdbot gateway status
clawdbot gateway restart