Clawdbot macOS 应用构建

该 macOS 配套应用提供菜单栏状态、原生通知，并能访问 Mac 硬件（摄像头、屏幕录制、系统命令）。此技能用于从源代码构建它。

先决条件

• macOS (10.14+)
• Xcode 15+ 及命令行工具
• Node.js >= 22
• pnpm 包管理器
• 30+ GB 可用磁盘空间 (用于 Swift 构建产物)
• 网络连接 (用于下载大型依赖)

快速构建

# Clone repo
cd /tmp && rm -rf clawdbot-build && git clone https://github.com/clawdbot/clawdbot.git clawdbot-build

# Install + build
cd /tmp/clawdbot-build
pnpm install
pnpm ui:build

# Accept Xcode license (one-time)
sudo xcodebuild -license accept

# Build macOS app with ad-hoc signing
ALLOW_ADHOC_SIGNING=1 bash scripts/package-mac-app.sh

# Install to /Applications
cp -r dist/Clawdbot.app /Applications/Clawdbot.app

# Launch
open /Applications/Clawdbot.app

构建步骤详解

1. 克隆仓库

从 GitHub 克隆最新的 Clawdbot 源代码。这包括位于apps/macos/目录下的 macOS 应用源代码。

2. 安装依赖 (pnpm install)

为整个工作空间安装 Node.js 依赖项（约 1 分钟）。某些扩展中关于缺少二进制文件的警告是无害的。

3. 构建 UI (pnpm ui:build)

编译控制界面 UI（Vite → TypeScript/React）。输出到dist/control-ui/大约需要30秒。

4. 接受Xcode许可协议

每次更新Xcode后都需要操作一次。如果在Swift构建过程中遇到"license not agreed"（许可协议未同意）错误，请运行：

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: <名称>" 此步骤根据你的Mac性能需要10-20分钟。

This step takes 10-20 minutes depending on your Mac.

6. 安装到/应用程序

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

7. 启动

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

故障排除

"工具版本无效"

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

softwareupdate -i -a

"许可证未同意"

sudo xcodebuild -license accept

"未找到签名标识"

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

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

Swift编译卡住或非常缓慢

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

构建后应用程序无法启动

检查其是否正确签名：

codesign -v /Applications/Clawdbot.app

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

应用功能

• 菜单栏状态— 查看网关健康状况并接收通知
• 权限管理— 拥有通知、辅助功能、屏幕录制、麦克风等权限的TTC提示
• 本地/远程模式：
  • 本地模式：网关在您的Mac上运行；应用管理launchd服务
  • 远程模式：应用通过SSH/Tailscale连接到另一台机器（VPS、家庭服务器）上的网关；即使Mac处于睡眠状态，也能保持可访问性
• Mac硬件访问：摄像头、屏幕录制、Canvas、语音唤醒词
• 深度链接：通过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