macOS 签名（调试构建）

此应用程序通常通过 scripts/package-mac-app.sh 脚本构建，该脚本现在执行以下操作：

  • 设置稳定的调试包标识符：com.clawdbot.mac.debug
  • 将 Info.plist 文件写入该包标识符（可通过 BUNDLE_ID=... 覆盖）
  • 调用 scripts/codesign-mac-app.sh 来签名主二进制文件和应用包，这样 macOS 会将每次重建视为同一个已签名的包，并保留 TCC 权限（通知、辅助功能、屏幕录制、麦克风、语音）。为了保持稳定的权限，建议使用真实的签名身份；无身份签名（ad-hoc）需要显式启用，且较为脆弱（参见 macOS 权限）。
  • 默认使用 CODESIGN_TIMESTAMP=auto；它为 Developer ID 签名启用受信任的时间戳。设置 CODESIGN_TIMESTAMP=off 可跳过时间戳（离线调试构建）。
  • 将构建元数据注入到 Info.plist 中：ClawdbotBuildTimestamp（UTC 时间）和 ClawdbotGitCommit（短哈希值），以便“关于”面板可以显示构建信息、Git 提交信息和调试/发布渠道。
  • 打包需要 Node 22+：该脚本会运行 TS 构建和 Control UI 构建。
  • 从环境变量中读取 SIGN_IDENTITY。将 export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"（或你的 Developer ID Application 证书）添加到你的 shell rc 文件中，以便始终使用你的证书进行签名。无身份签名需要通过 ALLOW_ADHOC_SIGNING=1 或 SIGN_IDENTITY="-" 显式启用（不推荐用于权限测试）。
  • 在签名后运行 Team ID 审计，如果应用包中的任何 Mach-O 文件由不同的 Team ID 签名，则会失败。设置 SKIP_TEAM_ID_CHECK=1 可跳过此检查。 bash

    从仓库根目录运行

    scripts/package-mac-app.sh # 自动选择签名身份；如果没有找到会报错 SIGN_IDENTITY=”Developer ID Application: Your Name” scripts/package-mac-app.sh # 使用真实证书 ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh # 无身份签名（权限不会保留） SIGN_IDENTITY=”-“ scripts/package-mac-app.sh # 显式无身份签名（同样存在权限问题） DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh # 仅用于开发的 Sparkle Team ID 不匹配解决方案 ``````

    临时签名说明

    当使用 SIGN_IDENTITY="-"（临时签名）进行签名时，脚本会自动禁用 强化运行时（--options runtime）。这是为了防止应用尝试加载嵌入式框架（如 Sparkle）时出现崩溃，这些框架可能不共享相同的团队 ID。临时签名还会破坏 TCC 权限的持久性；有关恢复步骤，请参阅 macOS 权限。

关于的构建元数据

package-mac-app.sh 会将以下信息写入 bundle：

  • ClawdbotBuildTimestamp：打包时的 ISO8601 UTC 时间
  • ClawdbotGitCommit：简短的 git 提交哈希（如果不可用则为 unknown）

“关于” 选项卡会读取这些键，以显示版本号、构建日期、git 提交信息以及是否为调试构建（通过 #if DEBUG 判断）。在代码更改后，运行打包程序以更新这些值。

原因

TCC 权限与 bundle 标识符 和 代码签名相关联。未签名的调试构建由于每次构建时 UUID 都会变化，导致 macOS 在每次重新构建后忘记之前授予的权限。通过默认的临时签名方式对二进制文件进行签名，并保持固定的 bundle ID/路径（dist/Clawdbot.app），可以在不同构建之间保留权限，这与 VibeTunnel 的方法一致。